@happyvertical/smrt-ui 0.42.4 → 0.42.5

package/README.md

@@ -135,9 +135,9 @@ transition path.
 <DataTable {controller} data={rows} {columns} rowKey="id" sortable selectable />
 ```
 
-`controller.snapshot()` returns the canonical JSON-safe version-2 `{ version,
-modes, state }` envelope. `hydrateDataTableSnapshot()` accepts version 1 and
-migrates it to version 2. The envelope contains no rows, callbacks, snippets,
+`controller.snapshot()` returns the canonical JSON-safe version-3 `{ version,
+modes, state }` envelope. `hydrateDataTableSnapshot()` accepts versions 1, 2,
+and 3 and normalizes them to version 3. The envelope contains no rows, callbacks, snippets,
 storage handles, tenant/principal data, query objects, or authority. URL and
 saved-view adapters remain application-owned: persist the snapshot (normally
 excluding selection and expansion IDs), validate it with
@@ -167,6 +167,26 @@ Without one, the component creates an internal controller and maps the legacy
 props. Multi-column sorting and persisted layouts use the controller state;
 the legacy `SortState` remains intentionally single-column.
 
+### Public surface and supported combinations
+
+`DataTable` supports the following contracts. These are intentionally composed
+through the controller rather than through a separate report or remote-table
+component.
+
+| Need | Public API | Important constraint |
+| --- | --- | --- |
+| Stable row interaction | `rowKey`, `selectable`, `expanded`, `onRowClick`, `agentAddressable` | `rowKey` is mandatory whenever a row has durable or remote identity. |
+| Declarative view state | `controller`, `state`, `initialState`, `onStateChange` | A supplied `controller` wins over controlled state and legacy bindables. |
+| Local or remote transformations | `modes`, `manualSorting`, `manualPagination`, `filterFn`, `totalRows` | A manual stage never runs locally; never mix a local transform with an already transformed remote result. |
+| Query lifecycle | `loading`, `refreshing`, `stale`, `partialResults`, `error`, `onRetry` | The caller owns request cancellation and revision checks; the table only presents the supplied result state. |
+| Report layout | column `headerPath`, `resizable`, `role`, `responsive`; `structuralRows`; controller widths/pinning | Group structure follows final visible leaf columns. Structural rows are never selectable or virtualized. |
+| Narrow screens | `visibleColumnIds` and responsive column metadata | The table preserves its semantic columns behind a named, keyboard-scrollable horizontal overflow region; it does not silently collapse content. |
+| Continuous browsing | `virtualization` | Requires `rowKey` and a fixed-height body. Expanded rows deliberately use the normal semantic body. |
+
+The interactive workbench's **Data Table** entry contains a release conformance
+fixture for each row in this table: local interaction, manual query lifecycle,
+responsive overflow, report layout, and virtualization.
+
 ### Row identity and selection
 
 `rowKey` is required for selectable, expandable, manual/server, and
@@ -223,6 +243,139 @@ the value changes. Data or total changes clamp an out-of-range page but do not
 otherwise reset it; empty known totals normalize to page 1. Column layout,
 selection, and expansion never change the page.
 
+### Manual query, retry, and race contract
+
+When any stage is `manual`, the host owns the request and result lifecycle. On
+each query-shape change, derive a stable `queryFingerprint` from every
+server-owned input (search, filters, sort rules, page, and page size) and a
+monotonically increasing `queryRevision`; start the request, retain the
+currently displayed rows with `refreshing`/`stale` as appropriate, and only
+commit a response when both values still match. A late response is discarded by
+the host, not merged by `DataTable`.
+
+```ts
+const queryFingerprint = JSON.stringify({ search, filters, sorting, page, pageSize });
+const query = { queryFingerprint, queryRevision: String(revision) };
+const result = await loadRows(query);
+
+if (query.queryRevision === String(revision) && query.queryFingerprint === currentQueryFingerprint()) {
+  rows = result.rows;
+  totalRows = result.totalRows;
+}
+```
+
+Set `error` without clearing a usable page, and make `onRetry` create a new
+revision. For query-wide actions, dispatch `selectAllMatching` with the same
+fingerprint/revision and call `assertDataTableSelectionCurrent` directly before
+the destructive request. This gives ContentList, reporting, admin, and agent
+surfaces the same stale-result and selection guardrail.
+
+### Saved layout and report guidance
+
+Use `headerPath` on every leaf that belongs to a grouped heading; matching IDs
+at a given depth form a column group after visibility and restored column order
+are applied. Keep report totals in `structuralRows` or `footer`, not in the
+data array. Persist `controller.snapshot()` only after removing tenant-specific
+selection and expansion IDs, then hydrate it before creating the next
+controller. The version-3 snapshot includes `columnOrder`,
+`columnVisibility`, `columnWidths`, and `columnPinning`, so a report can safely
+restore layout without persisting row data or query authority.
+
+### Scale boundaries and virtualization
+
+`DATA_TABLE_SCALE_THRESHOLDS` publishes the measured operating boundaries used
+by the reproducible DataTable benchmark:
+
+| Work | Boundary | Use after the boundary |
+| --- | --- | --- |
+| Ordinary local rendering | 250 rows / 5,000 cells | Page or virtualize the body. |
+| Local filtering and sorting | 1,000 rows / 20,000 cells | Move the transform to the caller or server. |
+| Manual/server paging | 100 supplied rows per page | Keep `totalRows` server-owned and bounded. |
+
+Run `pnpm --filter @happyvertical/smrt-ui bench:data-table` to measure the
+250-row local render, 1,000-row client-transform, and 100-row manual-paging
+fixtures. The fixture data has deterministic `rowKey` values so a browser or
+renderer comparison does not depend on array-arrival identity.
+
+`virtualization` is opt-in and requires `rowKey`. It virtualizes only a
+fixed-height data body; table headers (including grouped headers) and the
+`footer` summary remain normal semantic table sections and do not count toward
+the window. The virtual scroll region keeps captions and headers sticky, is
+keyboard-scrollable, and reports the full row count plus each rendered row's
+logical row index. Supplying `expandedContent` makes data-row height variable,
+so the component deliberately falls back to the full semantic body and does
+not emit virtual scroll callbacks. Use controlled `scrollTop`/
+`onScrollTopChange` for scroll restoration, and pair `focusedRowId` with
+`onFocusedRowIdChange` to restore DOM focus to a stable row after a data
+refresh. A measured footer extends the virtual scroll range, so keyboard End
+and a controlled scroll position can still reveal the summary. Selection and
+expansion continue to be controller state keyed by `rowKey`, never by a
+rendered window index. With manual pagination, `totalRows` and the current page
+set that full row count and each rendered row's global index.
+## Mounted data-surface registry
+
+`createDataSurfaceRegistry()` is the transport-neutral sibling of the form
+interaction registry. A mounted table, list, or report supplies serializable
+discovery metadata, a revisioned view snapshot, and a small handler for its
+declared visible controls. The registry rejects duplicate identities, validates
+JSON-safe data, requires an `expectedRevision`, records monotonic event
+sequences, serializes commands per mounted identity, and returns a cached
+acknowledgement when the same `commandId` is replayed. The replay cache retains
+only the 100 most recently used command IDs per mounted surface.
+
+Visible-command and preview/apply-action envelopes are capped at 100,000 UTF-8
+bytes (`DATA_SURFACE_MAX_REQUEST_BYTES`). JSON values reject prototype keys and
+have fixed nesting and container-size bounds, so every browser-facing request
+remains safe to normalize before host policy evaluates it.
+
+```ts
+import { createDataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
+
+const registry = createDataSurfaceRegistry();
+let revision = 0;
+let search = '';
+
+registry.register({
+  descriptor: {
+    version: 1,
+    identity: { surfaceId: 'content-library', kind: 'table' },
+    schemaVersion: 1,
+    label: 'Content library',
+    rowKey: 'id',
+    columns: [
+      { id: 'id', label: 'ID', capabilities: ['read', 'project'] },
+      { id: 'title', label: 'Title', capabilities: ['read', 'search'] },
+    ],
+    query: { modes: ['rows', 'count'], projectableColumnIds: ['id', 'title'] },
+    controls: [{ id: 'set-search', label: 'Search' }],
+    actions: [],
+    limits: { maxQueryRows: 100, maxQueryBytes: 100_000, maxSelectionSize: 100 },
+  },
+  getSnapshot: () => ({ revision, state: { search } }),
+  execute: (command) => {
+    if (command.controlId === 'set-search') {
+      search = String((command.payload as { search?: string }).search ?? '');
+      revision += 1;
+    }
+  },
+});
+```
+
+`inspect()` and command results are deterministic `{ version, descriptor,
+revision, state, selection }` envelopes; neither includes a timestamp, rows,
+functions, authority fields, tenant/principal data, SQL, or a transport handle.
+The registry rejects those boundary keys from both default and redacted snapshot
+state. An optional registration `redact()` hook can remove sensitive view state
+before it leaves the mounted host, but cannot alter the identity or revision.
+
+The registry validates bounded projection/count/facet query envelopes (including
+the UTF-8 byte length of their normalized JSON form) and preview/apply action
+envelopes, but it does not execute either. Canonical query semantics belong to
+the query protocol, browser command acknowledgement belongs to a transport
+adapter, and authentication, tenancy, confirmation-token verification, and
+durable actions remain server-side. URL state and saved views also remain
+application-owned persistence adapters.
+
 ## Themes
 
 `@happyvertical/smrt-ui/themes` is the canonical theme API and includes the
@@ -237,6 +390,7 @@ hand-authored, and every text pairing clears WCAG AA.
 ```svelte
 <script>
   import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
+  import '@happyvertical/smrt-ui/themes/styles/all.css';
   import '@happyvertical/smrt-ui/themes/styles/fonts.css';
 </script>