jobtrackingapp/docs/pre-phase10-ux/C_IMPLEMENTATION.md

# C: interactive dashboard implementation contract

28 October 2026. Entry: accepted cumulative B history through `aea7c29` (source3f4db8c), verified pushed. Branch `feature/dashboard-interactive-grid`. Existing local runtime continues to serve B until C is separately qualified.

Keep the existing widget registry, reports, preference JSON/revision columns, authentication boundaries, draft/save/cancel hook and navigation guard. Analytics/reporting retains its current layout. No dashboard database migration or parallel preference store is needed.

Use pinned `react-grid-layout@2.3.0`, modern typed API. Official package metadata declares MIT and React/ReactDOM>=16.3; installed exports and declarations were inspected. Its grouped grid/drag/resize configuration and existing compactor avoid a new collision engine. Actual React19 pointer/resize compatibility, accessibility alternatives and bundle impact must be measured, not inferred from peer ranges. Sources: [upstream package](https://github.com/react-grid-layout/react-grid-layout/blob/master/package.json), [modern API](https://github.com/react-grid-layout/react-grid-layout#whats-new-in-v2).

## Geometry and compatibility

- Canonical schema2 stores bounded integer `x,y,w,h` per known widget on12 columns. Retain legacy `size` as a consistent full/standard alias. Bounds: x>=0,y>=0,w4–12,h4–24,x+w<=12,y+h<=256; summary cards remain12 columns. Hidden geometry remains stored.
- Deterministically migrate schema1 order/visibility/full-or-standard widths in memory. New missing widgets remain hidden for existing accounts. Loading or changing viewport never persists a reset or migration.
- Preserve valid schema2 geometry/revision. Unsupported future schemas remain blocked. Schema1 clients cannot overwrite stored schema2, even with a current revision. Retain request-byte bounds and atomic owner/revision compare-and-swap.
- Visible rectangles cannot overlap on write; adjacent edges and overlapping hidden rectangles are allowed. The grid retains gaps using the library's `noCompactor` when there are no collisions, and delegates actual overlap resolution to `verticalCompactor` using `getAllCollisions`. A RED resize test exposed that `noCompactor` alone permits overlapping rectangles during resizing; the server rejected the write. Completed pointer operations order visible records by row/column, retaining hidden slots and all geometry.
- Desktop uses measured container width and real drag/resize handles. Mobile/tablet narrow containers use a linear content layout, retaining desktop geometry without writes. Content remains scrollable/readable at bounded sizes.

## Interaction

Edit the actual report widgets. The existing toolbar retains explicit Save, Discard, Reset and conflict/reload behaviour; a compact catalogue replaces the large per-widget configuration form. Drag handles and widget options supply keyboard movement, width/height and visibility alternatives. Keep focus after moves, announce changes, respect reduced motion and preserve ordinary widget links/inputs and touch scrolling.

Only actual drag/resize completion or explicit controls change the draft. Ignore mount/compaction/breakpoint callbacks as persistence events. No timers or automatic saves. A save success follows confirmed durable acknowledgement; conflicts retain the draft and require deliberate recovery.

## Qualification

1. RED/GREEN pure migration/geometry and backend HTTP schema/stale-write tests, retaining existing owner/revision/corruption/request-bound checks. Future-schema fixtures advance to3 because2 is now supported.
2. Real widget pointer drag/resize, keyboard/menu/catalogue, save/reload, discard/reset, failed save and two-tab conflict; existing report actions/data and hidden preferences survive.
3. EN/Bokmål, light/dark, desktop/tablet/mobile, reduced motion and accessibility automation. Physical device/assistive-technology acceptance remains separate.
4. Real MariaDB revision/ownership/preservation coverage, focused/full appropriate regressions, measured aggregate compiled bundle impact and browser screenshots. Commit/push/remote verification before D entry.

No production deployment, main merge, Phase10 cleanup or unrelated integrations.

## Implementation and evidence, 28 October

Implemented in `DashboardGrid.tsx`, the existing editor/catalogue, `dashboardLayout.ts`, preference hook and existing AuthController/JSON model. No preference table, queue, schema migration or new data owner. Actual report components and their links/tables remain intact. Narrow containers use content height and desktop geometry survives without writes. Scrollable desktop content has keyboard focus; controls include native width/height inputs, movement, visibility, announcements and focus recovery. The reduced-motion rule disables item transitions.

Evidence under `.artifacts/pre-phase10-ux/`:

- Initial migration RED: `c-layout-red.log`, 2 failed/6 passed. Initial HTTP geometry RED: `c-layout-red/c-layout-red.trx`, 1 failed/31 passed. GREEN foundation: 8 pure tests and32 API tests. Added visible-overlap/adjacency/hidden cases subsequently pass in the full backend suite.
- Full backend `c-backend-02/c-backend.trx`: **1,405 passed, zero failed/skipped**, including35 dashboard HTTP cases, existing revision/authentication/preservation tests.
- Real MariaDB12.2.2 `c-mariadb-01/`: **86 passed, zero failed/skipped**, including new durable geometry/owner/legacy/stale protection and concurrent one-winner tests. Generated schema/container cleanup exited0. No production database access.
- Final focused frontend `c-focused-final-03.json`: **33 passed/5 suites**; includes4 grid collision/callback/narrow viewport/conflict cases. Test-double callbacks qualify surrounding logic only; actual pointer qualification uses Playwright. Collision RED `c-collision-red.json`:1 failed/3 passed; GREEN `c-collision-green.json`:4 passed.
- Browser qualification and full frontend totals are recorded in C_ACCEPTANCE.md when complete. Failed runs are retained. A screen-reader announcement used MUI numeric width1 (100%), causing outer overflow; corrected to explicit1px and the existing reflow assertion passes. Resize simulation now starts at the actual handle centre, avoiding a clipped rounded corner. Tests now open the compact catalogue and compare pointer-induced order to actual geometry; no original ownership, persistence, failure or accessibility assertions were removed.
- Final static build `c-build-05.log` exits0; exact React19 runtime tested by actual browser cases. Full lint/typecheck native exits are recorded alongside final acceptance.
- `c-bundle-final.json`: all exported JS artifacts, B57 files3,499,170 raw/1,032,319 gzip bytes; C57 files3,572,883 raw/1,055,955 gzip. Delta **73,713 raw/23,636 gzip bytes**. This measures aggregate artifacts, not route download or runtime performance. CSS is separate. Dependency is pinned2.3.0/MIT; official peer range permits React>=16.3, actual React19 functionality requires the browser evidence.
- `c-npm-production-audit.json`: exit0, zero production advisories. `c-npm-audit.json`: exit1, five low dev-tool dependency entries around existing Jest/deepmerge; no package-lock changes to those existing packages. No new grid dependency is flagged. A suggested downgrade to Jest25 is not applied. Carry these tooling advisories to integrated security qualification; this is not a clean full audit.

No human screen-reader, physical-touch or subjective design acceptance is inferred from automation. Existing B rendering/model qualification debt remains open. C has not been deployed to the local B runtime or production.