@happyvertical/smrt-ui 0.42.2 → 0.42.4

package/README.md

@@ -102,6 +102,127 @@ 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-2 `{ version,
+modes, state }` envelope. `hydrateDataTableSnapshot()` accepts version 1 and
+migrates it to version 2. 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.
+
+### 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.
+
 ## Themes
 
 `@happyvertical/smrt-ui/themes` is the canonical theme API and includes the