82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 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` — paginates `items` via `renderItem`, filling the viewport space between `aboveRef`/`belowRef`; wheel flips pages |
|
|
|
|
## 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.
|