@happyvertical/smrt-ui 0.42.3 → 0.42.5

package/README.md

@@ -102,6 +102,280 @@ apply, clear, or undo. Agent mutations are denied for secret/read-only controls
 and require explicit confirmation before apply, clear, or undo. Staging is
 separate so the UI can show a proposal before it changes user state.
 
+## DataTable controller
+
+`DataTable` can share one headless `DataTableController` between rendered
+controls and a programmatic adapter. Search, declarative filters, ordered
+multi-column sorting, pagination, columns, selection, and expansion all become
+plain-data commands; a header click and `controller.dispatch()` take the same
+transition path.
+
+```svelte
+<script lang="ts">
+  import {
+    createDataTableController,
+    DataTable,
+    type DataTableColumn,
+  } from '@happyvertical/smrt-ui/data';
+
+  const controller = createDataTableController({
+    columnIds: ['name', 'status'],
+    initialState: {
+      pageSize: 25,
+      sorting: [{ columnId: 'name', direction: 'asc' }],
+    },
+  });
+
+  controller.dispatch({
+    type: 'setFilters',
+    filters: [{ columnId: 'status', operator: 'equals', value: 'active' }],
+  });
+</script>
+
+<DataTable {controller} data={rows} {columns} rowKey="id" sortable selectable />
+```
+
+`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
+`hydrateDataTableSnapshot`, and feed the state into a new controller or
+`replaceState`. `smrt-ui` does not read or write the URL, browser storage, or a
+database.
+
+### Controlled and migration use
+
+Pass `state` plus `onStateChange` for controlled state. A controlled controller
+emits a candidate and waits for the host to call `replaceState`; an
+uncontrolled controller owns the state initialized by `initialState`.
+
+The existing Svelte bindables remain supported during migration:
+
+| Existing prop | Controller state |
+| --- | --- |
+| `bind:sort` | first entry of ordered `sorting` (single-sort compatibility) |
+| `bind:page`, `pageSize` | `page`, `pageSize` |
+| `bind:selected`, `bind:expanded` | legacy explicit `selectedRowIds`, canonical `selection` and `expandedRowIds` |
+| `visibleColumnIds` | `columnVisibility` intersected with static `column.hidden` |
+| `manualSorting`, `manualPagination` | sorting/pagination entries in `modes` |
+| `filterFn` | local-only legacy predicate; never serialized |
+
+An explicit `controller` takes precedence over `state` and legacy bindables.
+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
+`agentAddressable` tables. Its values must be unique non-empty strings or finite
+numbers. This fails closed before a renderer can reuse the wrong row after a
+sort, refresh, or server-page change. The historical source-index fallback
+exists only for local presentational tables with no durable row state.
+
+The controller stores a `selection` union alongside the deprecated
+`selectedRowIds` shorthand:
+
+| Scope | Stored value | Lifecycle |
+| --- | --- | --- |
+| `page` | IDs from the current rendered page | Cleared when page, page size, search, filters, or sorting changes. |
+| `explicit` | Explicit stable IDs across pages | Persists across page and query navigation until changed by the caller. |
+| `allMatching` | `queryFingerprint`, `queryRevision`, and `expectedCount` only | Never stores loaded IDs; query-shape changes clear it. |
+
+The built-in header checkbox explicitly means **Select all rows on this page**.
+For query-wide selection, dispatch `selectAllMatching` with the caller-owned
+query fingerprint, revision, and expected count. A destructive domain action
+must call `assertDataTableSelectionCurrent(selection, currentQuery)` immediately
+before applying it; a mismatched fingerprint or revision throws rather than
+acting on stale results.
+
+`index` passed to row callbacks, cells, expansion snippets, and `rowClass` is
+the zero-based display index on the currently rendered page. The source index
+is the zero-based position in the supplied `data` array and is used only by the
+non-durable fallback. It must never be saved, sent to an agent, or used as a
+remote identity.
+
+### Transformation ownership and page rules
+
+`modes` makes each stage explicit. A `manual` stage renders caller-supplied
+results and bypasses that local stage, so rows are never double-filtered,
+double-sorted, or double-paged.
+
+| Filtering | Sorting | Pagination | Renderer behavior |
+| --- | --- | --- | --- |
+| `local` | `local` | `local` | filter → ordered multi-sort → slice |
+| `manual` | `local` | `local` | sort and slice supplied rows |
+| `local` | `manual` | `local` | filter and slice supplied rows |
+| `local` | `local` | `manual` | filter and sort supplied page; never slice it |
+| `manual` | `manual` | `manual` | render supplied rows unchanged |
+
+Every combination follows the same rule per column in the table: each local
+stage runs once and each manual stage runs zero times. For manual pagination,
+`totalRows` supplies the total; when it is unknown the component does not guess
+the last page or render misleading pagination controls. A supplied `totalRows`
+must be a non-negative integer and is rejected unless pagination mode is
+`manual`.
+
+Changing search, filters, sorting, or page size resets the page to 1 only when
+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
@@ -116,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>