# dashgui

Reusable custom **GUI class components** (React + MUI), shared across the
`dash*` apps. This is the "outsourced" home for custom GUI primitives that
previously lived inside `dashfront/src/components`.

This package is source-only: consumers import directly from `src/` via the
`exports` map, so there is no build step for the library itself.

## Contents

| Export | Source | Description |
| --- | --- | --- |
| `dashgui/panels` | `src/panels/` | `PanelTile`, `PanelTileGrid`, `EditablePanelTile`, `injectMuiTheme`, layout helpers |
| `dashgui/lists` | `src/lists/` | `RecordList` — generic presentational data list (loading/error/empty states + table with edit/delete) |
| `dashgui/tiles` | `src/tiles/` | `Tile`, `TILE_SIZE`, `tileBaseSx` |
| `dashgui/ElevatedPill` | `src/ElevatedPill.jsx` | `ElevatedPill`, `ToggleElevatedPill`, `ActionElevatedPill` |
| `dashgui/SingleLineTextEdit` | `src/SingleLineTextEdit.jsx` | Centralized single-line text field |
| `dashgui/FillSpace` | `src/FillSpace.jsx` | `FillSpace` — viewport-height spacer between header/footer refs; optional repeating `measureElement` |

## Design rules

- **No app coupling.** No Redux, router, notistack, storage manager, or backend
  error imports. Error surfaces are injected via props (e.g. `EditablePanelTile`'s
  `onError`, `RecordList`'s `error`). Data and actions are always passed in.
- **Class components** for the base primitives (matches the existing codebase).
- Only `react`, MUI, and MUI icons as (peer) dependencies.

## Consuming from dashfront

`dashfront` declares `"dashgui": "file:../dashgui"` (npm workspace / symlink).
Source imports keep changes instantly visible in the app.

## Development harness

Run `npm run dev` to render the components on **mock pages** (`dev/`) without a
backend. This is where test cases with mock pages will live.

```sh
npm install
npm run dev      # http://localhost:5199
npm run build    # bundle the dev harness (dist/)
npm run lint
```

## Screenshot testing

Variations of the GUI elements are covered by **reference screenshot tests**
(Playwright). Each variation is rendered by the static harness at
[`/screenshots.html`](screenshots.html) (`src/dev/screenshots/ScreenshotHarness.jsx`)
inside a `data-shot` section, and every section is compared against a committed
reference image in `tests/screenshots/reference/`.

```sh
npm run test:screenshots           # compare against references
npm run test:screenshots:update    # regenerate references (after intentional changes)
```

Notes:

- The tests reuse the running dev server (`npm run dev` on port 5199) or start
  it automatically.
- Reference images are committed so visual regressions fail the run; the
  actual + diff images land in `test-results/` (gitignored).
- Animations are frozen during capture so spinners/transitions render
  deterministically.
- Interactive states (e.g. the `EditablePanelTile` edit/dirty rings) are driven
  from the test itself, on top of the static sections.

### Adding a new variation

1. Add a `<Section id="…">` block to `ScreenshotHarness.jsx`.
2. Add the id to the test in `tests/screenshot.spec.js` (or write a dedicated
   interaction test).
3. Run `npm run test:screenshots:update` to generate the new reference, review
   it, and commit it.

## Future

- Unit + component tests with mock pages will be added under `dev/` /
  `src/__tests__/` as they are written.