@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/docs/loading-and-empty.md

@@ -0,0 +1,92 @@
+# Loading and empty states
+
+A grid can have nothing to show for four different reasons, and the body says
+which one it is: still fetching, emptied by a filter, or holding no data.
+
+```demo
+file: data/LoadingAndEmpty.tsx
+hint: Switch to loaded, then search for something that cannot match, to see the other branch.
+extraSources: data/employeeColumns.tsx
+```
+
+## Precedence
+
+An empty body shows exactly one thing, decided in this order:
+
+1. **Loading** - `meta.loading` is true: a centred loader. A grid that is
+   fetching never reports itself as empty.
+2. **Entry rows** - an open entry row from `edit.addRow()`: the entry block
+   only, with no message beside the form.
+3. **`renderEmptyState`** - your node, centred where the message would be.
+4. **Filtered-empty** - a filter or search is active: a search icon and
+   `labels.noResults` ("No rows match your filters").
+5. **Truly-empty** - no data at all: `labels.noRows` ("No rows to show").
+
+## Replacing the message
+
+`renderEmptyState` replaces states 4 and 5 with one render prop.
+`hasActiveFilters` says which of the two it is replacing, so one prop can render
+two different messages:
+
+```tsx
+<TMDataGrid.Table<Employee>
+  renderEmptyState={({ hasActiveFilters, table }) =>
+    hasActiveFilters ? (
+      <Stack align="center" gap="xs">
+        <Text c="dimmed">Nothing matches your filters</Text>
+        <Button variant="light" onClick={() => table.resetColumnFilters()}>
+          Clear filters
+        </Button>
+      </Stack>
+    ) : (
+      <Stack align="center" gap="xs">
+        <Text c="dimmed">No employees yet</Text>
+        <Button onClick={openCreateModal}>Add the first one</Button>
+      </Stack>
+    )
+  }
+/>
+```
+
+## Loading with rows on screen
+
+The body's loading state only appears while the grid is **empty**. A
+server-driven grid refetching with rows still on screen keeps showing them
+rather than blanking the body on every page change.
+
+`TMDataGrid.LoadingIndicator` covers that case: a small spinner while
+`meta.loading` is true, and nothing otherwise. Place it where you want it,
+typically after `Spacer`.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.LoadingIndicator />
+</TMDataGrid.Toolbar>
+```
+
+## Counting what is there
+
+`TMDataGrid.SummaryCount` shows visible rows out of the total. The total is
+`meta.totalRowCount` when you provide it, and the pre-filtered row count
+otherwise. A [server-side](/docs/server-side) grid must provide it, because the
+client only holds one page.
+
+```tsx
+<TMDataGrid.SummaryCount>
+  {visible} of {total} employees
+</TMDataGrid.SummaryCount>
+```
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |
+| `meta.noResultsLabel` | Option | `string` | `labels.noResults` | The filtered-empty message, without a render prop. |
+| `meta.totalRowCount` | Option | `number` | Pre-filtered count | The total `SummaryCount` reports. |
+| `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. |
+| `TMDataGrid.LoadingIndicator` | Component | – | – | Spinner while `meta.loading`, for when the body has rows. |
+| `TMDataGrid.SummaryCount` | Component | `children` replaces the text | – | Visible rows out of total. |
+| `labels.noRows` · `labels.noResults` | Labels | `string` | English defaults | The two built-in messages. See [Localization](/docs/localization). |

package/docs/localization.md

@@ -0,0 +1,79 @@
+# Localization
+
+Every string the grid renders - menu items, panels, tooltips, the pager and
+every `aria-label` - comes from one labels object. English by default.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  labels: { noResults: "Inga rader matchar dina filter" },
+});
+```
+
+`labels` takes **any subset** and merges it over the defaults.
+
+```demo
+file: customization/Localization.tsx
+extraSources: data/employeeColumns.tsx
+```
+
+## A complete translation
+
+A full Swedish dictionary ships as `TMDATAGRID_LABELS_SV`:
+
+```tsx
+import { TMDATAGRID_LABELS_SV } from "@jielga/tmdatagrid";
+
+const grid = useTMDataGrid({ data, columns, labels: TMDATAGRID_LABELS_SV });
+```
+
+`TMDATAGRID_LABELS_EN` is the English base, and `TMDataGridLabels` is the full
+dictionary type, so a missing key in a new translation is a compile error.
+
+## Labels that carry a value
+
+These labels are functions, so each language can place the value where its
+grammar requires:
+
+```tsx
+labels: {
+  groupBy: (column) => `Gruppera på ${column}`,
+  pageRange: ({ from, to, total }) => `${from}–${to} av ${total}`,
+}
+```
+
+## Keep the object stable
+
+Define it at module scope, or memoize it. The grid re-renders when the labels
+object changes identity.
+
+```tsx
+const labels = { noResults: "Inga träffar" } satisfies TMDataGridLabelsOverride;
+```
+
+## Reading them yourself
+
+The resolved dictionary comes back from the hook as `grid.labels`, and from
+context as `useTMDataGridContext().labels`, so a
+[toolbar component of your own](/docs/toolbar) uses the same strings as the
+built-in parts, in whatever language is configured.
+
+`mergeLabels(base, override)` is the merge itself, exported for composing
+dictionaries before passing one in.
+
+`meta.noResultsLabel` remains as a per-instance override of
+`labels.noResults`.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `labels` | Option | `TMDataGridLabelsOverride` | English | Any subset, merged over the defaults. Keep it stable. |
+| `grid.labels` | Hook return | `TMDataGridLabels` | – | The resolved dictionary. |
+| `TMDATAGRID_LABELS_EN` | Export | `TMDataGridLabels` | – | The English base. |
+| `TMDATAGRID_LABELS_SV` | Export | `TMDataGridLabels` | – | A complete Swedish dictionary. |
+| `TMDataGridLabels` | Export | type | – | The full dictionary. What a new translation must cover. |
+| `TMDataGridLabelsOverride` | Export | type | – | A partial dictionary. |
+| `mergeLabels` | Export | `(base, override) => TMDataGridLabels` | – | The merge, for composing dictionaries. |
+| `meta.noResultsLabel` | Option | `string` | `labels.noResults` | Per-instance override of the filtered-empty message. |

package/docs/menu.md

@@ -0,0 +1,143 @@
+# Grid menu
+
+`TMDataGrid.Menu` is the burger button at the end of the toolbar and the Mantine `Menu` it opens.
+Its children are the dropdown: Mantine `Menu.Item`s of your own, and the built-in items under `TMDataGrid.Menu.*`.
+
+```tsx
+import { Menu } from "@mantine/core";
+
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.FilterButton />
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Export />
+    <Menu.Item onClick={saveView}>Save view</Menu.Item>
+    <Menu.Divider />
+    <Menu.Label>Columns</Menu.Label>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+</TMDataGrid.Toolbar>
+```
+
+```demo
+file: customization/GridMenu.tsx
+hint: The burger holds the app's own items above the column chooser.
+```
+
+A custom item reads the grid from context, the same way a [toolbar button](/docs/toolbar#buttons-of-your-own) does.
+`TMDataGrid.Menu.Export` and `TMDataGrid.Menu.ExportSelected` are the built-in export items; their props and formats are on [Export](/docs/export).
+Mantine's `Menu.Divider`, `Menu.Label` and `Menu.Sub` work as they do in any Mantine menu; the grid wraps nothing of Mantine's.
+
+`TMDataGrid.Menu` always renders: it cannot see whether its children render anything.
+A menu holding only `TMDataGrid.Menu.Columns` on a grid with `enableHiding: false` opens empty, so hide it with the same check the built-in buttons use:
+
+```tsx
+const { table, features } = useTMDataGridContext();
+const { canHideAny } = getGridCapabilities(table, features);
+
+{canHideAny && (
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+)}
+```
+
+## The column chooser as menu items
+
+`TMDataGrid.Menu.Columns` is the whole chooser: one checkbox item per column that can be hidden, a search box once there are six of them, **Show/Hide All** and **Reset layout**.
+It renders nothing when no column can be hidden.
+The pieces it is made of are exported for menus that want only some of them.
+
+| Component | Renders |
+| --- | --- |
+| `TMDataGrid.Menu.Columns` | `Menu.Search`, the toggles, a divider, show/hide all and reset layout. By default the search box shows from six columns; `searchable` shows it always and `searchable={false}` never. |
+| `TMDataGrid.Menu.ColumnToggles` | One item per hideable column, with a checkbox that shows both states. `search` narrows the list to the labels containing it. |
+| `TMDataGrid.Menu.ShowHideAll` | One checkbox item over the same list. An indeterminate box marks a partial state, and a click then shows all. |
+| `TMDataGrid.Menu.ResetLayout` | One item calling `resetSettings()`: visibility, order, pinning and widths. |
+
+Each of them needs a Mantine `Menu` around it and reads the grid from context, so they work in any Mantine menu rendered inside `TMDataGrid`, not only in the burger:
+
+```tsx
+<Menu width={260} withinPortal>
+  <Menu.Target>
+    <Button size="compact-xs" variant="subtle">
+      View
+    </Button>
+  </Menu.Target>
+  <Menu.Dropdown>
+    <Menu.Item onClick={() => setDensity("compact")}>Compact rows</Menu.Item>
+    <Menu.Divider />
+    <TMDataGrid.Menu.ColumnToggles />
+    <Menu.Divider />
+    <TMDataGrid.Menu.ShowHideAll />
+    <TMDataGrid.Menu.ResetLayout />
+  </Menu.Dropdown>
+</Menu>
+```
+
+### As a submenu
+
+Every column header's menu has **Manage columns**, a `Menu.Sub` holding `TMDataGrid.Menu.Columns`.
+The same composition works in a menu of your own:
+
+```tsx
+<Menu.Sub>
+  <Menu.Sub.Target>
+    <Menu.Sub.Item>Manage columns</Menu.Sub.Item>
+  </Menu.Sub.Target>
+  <Menu.Sub.Dropdown>
+    <TMDataGrid.Menu.Columns searchable={false} />
+  </Menu.Sub.Dropdown>
+</Menu.Sub>
+```
+
+`searchable` is for a block at the top level of a dropdown.
+`Menu.Search` registers on the root menu, which switches off type-ahead and the arrow keys of every dropdown of that menu, so a search box inside a submenu breaks the keyboard behaviour of the menu around it.
+ArrowDown from the search box moves to the first listed column, whatever sits above the block.
+
+### The panel instead
+
+`TMDataGrid.ColumnsPanel` is the same chooser as plain controls, for a host that is not a menu: a Popover, a Drawer, or a settings page.
+
+```tsx
+const [opened, setOpened] = useState(false);
+
+<Popover opened={opened} onChange={setOpened} withinPortal trapFocus>
+  <Popover.Target>
+    <ActionIcon aria-label="Columns" onClick={() => setOpened((open) => !open)}>
+      <IconColumns3 size={18} />
+    </ActionIcon>
+  </Popover.Target>
+  <Popover.Dropdown p={0}>
+    <TMDataGrid.ColumnsPanel />
+  </Popover.Dropdown>
+</Popover>
+```
+
+## Labels
+
+`labels.menuButton` is the burger's tooltip and `aria-label`.
+The chooser uses the panel's strings: `columnsSearchPlaceholder`, `columnsNoMatch`, `columnsShowHideAll` and `columnsReset`.
+See [Localization](/docs/localization).
+
+## Testing
+
+The burger is `data-dg-part="menu-button"`.
+The items publish the same parts as the panel: `columns-search`, `columns-toggle` with `data-column-id`, `columns-toggle-all` and `columns-reset`, so a test written against the panel reads the same on the menu.
+The export items are `menu-export` and `menu-export-selected`.
+See [Testing](/docs/testing).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `TMDataGrid.Menu` | Component | Mantine `MenuProps` without `children`, plus `children`, `icon`, `label` | `position="bottom-end"`, `shadow="md"`, `width={260}`, `withinPortal` | The burger and its dropdown. `icon` replaces the burger; `label` is the tooltip and `aria-label`, default `labels.menuButton`. |
+| `TMDataGrid.Menu.Columns` | Component | `searchable?: boolean \| "auto"` | `"auto"` | The whole column chooser as menu items. `"auto"` shows the search box from six columns. Renders nothing when no column can be hidden. |
+| `TMDataGrid.Menu.ColumnToggles` | Component | `search?: string` | – | One checkbox item per hideable column. |
+| `TMDataGrid.Menu.ShowHideAll` | Component | – | – | One checkbox item over every hideable column. |
+| `TMDataGrid.Menu.ResetLayout` | Component | – | – | Calls `resetSettings()`. |
+| `TMDataGrid.Menu.Export` · `.ExportSelected` | Components | `TMDataGridExportOptions` | – | The export items. Props on [Export](/docs/export). |
+| `TMDataGrid.ColumnsPanel` | Component | – | – | The chooser as plain controls, for a host that is not a menu. |
+| `labels.menuButton` | Option | `string` | `"Menu"` | The burger's tooltip and `aria-label`. |
+| `TMDataGridMenuProps` · `TMDataGridMenuColumnsProps` · `TMDataGridMenuExportProps` | Export | types | – | The prop types. |

package/docs/pagination.md

@@ -0,0 +1,144 @@
+# Pagination
+
+**Off by default.** The grid renders every filtered and sorted row and relies
+on [virtualization](/docs/scrolling), which handles any row count. Turn paging
+on when users should move through the data a page at a time, not to keep a
+large grid responsive.
+
+There are three modes.
+
+**No pagination** - the default. `TMDataGrid.Footer` renders nothing.
+
+```tsx
+const grid = useTMDataGrid({ data, columns });
+```
+
+**Client pagination** - the table pages the data itself, and the Footer renders
+its pager. Initial page size is 25, configurable through
+`initialState.pagination`.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enablePagination: true });
+```
+
+**Manual pagination** - the server pages, and the grid stops.
+`manualPagination: true` implies `enablePagination`, so no extra flag is
+needed. See [Server-side data](/docs/server-side).
+
+```tsx
+const grid = useTMDataGrid({
+  data: page.rows,
+  columns,
+  manualPagination: true,
+  rowCount: page.total,
+  state: { pagination },
+  onPaginationChange: setPagination,
+});
+```
+
+```demo
+file: data/Pagination.tsx
+extraSources: data/employeeColumns.tsx
+```
+
+`enablePagination` is defined by the grid rather than by TanStack, which ships
+the pagination state and APIs but no `enable` option.
+
+## Replacing the pager
+
+`TMDataGrid.Footer` takes a `renderPagination` slot, handed three things: the
+`state` the pager is showing, the `actions` it can take, and `Controls` - the
+built-in pieces, already wired.
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ state, actions, Controls }) => (
+    <Group>
+      <Controls.PageSize />
+      <Button onClick={actions.previousPage} disabled={!state.canPreviousPage}>
+        Back
+      </Button>
+      <Text>
+        {state.pageIndex + 1} / {state.pageCount}
+      </Text>
+      <Button onClick={actions.nextPage} disabled={!state.canNextPage}>
+        Next
+      </Button>
+    </Group>
+  )}
+/>
+```
+
+The default footer renders `PageSize`, `Range` and `Pager`, in that order. A
+control kept from `Controls` behaves as it does in the default footer, including
+greying out while a grouping suspends paging.
+
+| Member | Renders |
+| --- | --- |
+| `Controls.PageSize` | "Rows per page" and its select |
+| `Controls.Range` | The "1–25 of 300" label |
+| `Controls.PageNumber` | The "Page 3 of 200" label |
+| `Controls.Pager` | The previous and next buttons |
+
+`PageNumber` is not in the default footer.
+It is the label a server-paged grid usually shows in place of a row range, so it is put in through the slot:
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ Controls }) => (
+    <>
+      <Controls.PageSize />
+      <Controls.PageNumber />
+      <Controls.Pager />
+    </>
+  )}
+/>
+```
+
+It reads `pageCount`, so a grid declaring `pageCount: -1` shows "Page 3" alone.
+
+`state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
+`canPreviousPage`, `canNextPage`, the `from` / `to` bounds of the current page,
+and `isPagingActive`. `actions` carries `setPageIndex`, `setPageSize`,
+`previousPage`, `nextPage`, `firstPage` and `lastPage`.
+
+`getTMDataGridPaginationApi(table)` returns the same `{ state, actions }`
+outside the Footer, for a pager that lives elsewhere on the page. `Controls` is
+not included: those components are bound to the grid's context and work only
+inside the slot.
+
+## Grouping
+
+While a column is grouped the pager greys itself out and the range is replaced
+with `Grouped · all N rows`. See
+[Grouping](/docs/grouping#grouping-and-pagination).
+
+A custom pager can grey itself out the same way:
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ state, actions }) => (
+    <MyPager {...state} {...actions} disabled={!state.isPagingActive} />
+  )}
+/>
+```
+
+`isPagingActive` is live state: whether the pager is currently slicing
+anything. `getGridCapabilities(...).canPaginate` is configuration: whether
+paging is switched on at all. The two differ while a grouping is active.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enablePagination` | Option | `boolean` | `false` | Client-side paging and the Footer's pager. Grid-defined. |
+| `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
+| `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
+| `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A data slice, so it persists. |
+| `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
+| `resetPageOnQueryChange` | Option | `boolean` | `true` | Back to page 1 when a filter, the quick search, the sort or the grouping changes. `false` keeps the page. See [Server-side data](/docs/server-side#the-page-index). |
+| `TMDataGrid.Footer` | Component | – | – | The footer bar. Renders nothing when paging is off. |
+| `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
+| `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
+| `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot's argument. |
+| `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |

package/docs/persistence.md

@@ -0,0 +1,111 @@
+# Persistence
+
+Restores table state on mount and writes it back on every change, so users
+return to the grid as they left it.
+
+State is split across **two keys**: `settingsKey` for the column layout, which
+stays valid indefinitely, and `dataKey` for filters, sorting and pagination,
+which go stale as the data underneath them changes. Either can be cleared
+without touching the other.
+
+```tsx
+// Module scope: the object is a dependency of the write subscription.
+const persist = {
+  dataKey: "employees.data",
+  settingsKey: "employees.settings",
+} satisfies TMDataGridPersistence;
+
+const grid = useTMDataGrid({ data, columns, persist });
+```
+
+Both keys are optional - pass only `settingsKey` to remember the layout but
+never the filters.
+
+```demo
+file: data/Persistence.tsx
+hint: Sort, filter and hide a column, then reload the page. It all comes back; the page index does not.
+extraSources: data/employeeColumns.tsx
+```
+
+## The two groups
+
+| Group | Slices | Lifetime |
+| --- | --- | --- |
+| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` | As long as the data means the same thing |
+| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` | Indefinite. This is the user's layout |
+
+`DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` are exported with the same
+values. Slice names are typed per group, so only valid names compile.
+
+Settings saved by 1.x with the old `columnPinning` keys `left` and `right` are
+read and migrated to `start` and `end`.
+
+## Persisting only some of it
+
+A key on its own persists every slice in its group. Pass a tuple to narrow it:
+
+```tsx
+const persist = {
+  // Restore filters and sorting, but always start on the first page.
+  dataKey: ["employees.data", ["columnFilters", "sorting"]],
+  // Restore column layout but not widths.
+  settingsKey: ["employees.settings", ["columnVisibility", "columnOrder"]],
+  storageMode: "sessionStorage",
+} satisfies TMDataGridPersistence;
+```
+
+Only the selected slices are read back, so a payload written before you narrowed
+the selection cannot reintroduce slices you have since opted out of.
+
+## Behaviour
+
+**Restoring happens once**, on mount, through `initialState`. Writing is a
+subscription to the table store, so state changed directly through the table
+API is persisted too.
+
+**A payload from another version is dropped whole**, not migrated. Payloads
+carry the exported `PERSIST_PAYLOAD_VERSION`, and anything else, including
+everything written by a 0.x build, which had no stamp, is discarded.
+
+**Restored state is realigned against the columns that exist.** Entries naming a
+column removed between deploys are dropped: a stale id in the order, a width for
+a column that no longer exists, or a sort or filter that would be active with no
+column to show it. New columns need no handling, since TanStack appends columns
+missing from `columnOrder` in definition order.
+
+**Storage access is guarded.** If storage is unavailable, disabled or full,
+persistence is skipped rather than throwing.
+
+**Keys are not namespaced.** Include a tenant or user identifier if several
+people can share a browser profile.
+
+## Resetting
+
+`resetSettings()` puts the settings state back to what a first visit with clean
+storage would have shown (your `initialState` plus the structural lanes), and,
+with persistence configured, writes through to storage like any other change.
+The columns panel's **Reset layout** button calls it.
+
+TanStack's own `resetColumnX()` family cannot do it on a persisted grid: those
+reset to `initialState`, which the mount built *from* the restored payload.
+
+## Relation to Mantine
+
+Persistence does not use Mantine's `useLocalStorage`; the table owns the state
+and storage only mirrors it. The option names follow Mantine's
+`UseStorageOptions` where they apply, and `storageMode` takes the same values as
+its `StorageType`.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `persist` | Option | `TMDataGridPersistence` | – | The whole configuration. Keep it referentially stable. |
+| `dataKey` | persist field | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
+| `settingsKey` | persist field | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `storageMode` | persist field | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
+| `serialize` | persist field | `(value) => string` | `JSON.stringify` | Serializes a payload before storing. |
+| `deserialize` | persist field | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
+| `resetSettings` | Hook return | `() => void` | – | Back to a clean first visit, written through to storage. |
+| `DATA_STATE_SLICES` · `SETTINGS_STATE_SLICES` | Exports | `string[]` | – | The slice names of each group. |
+| `PERSIST_PAYLOAD_VERSION` | Export | `number` | – | The stamp. A payload from another version is dropped. |

package/docs/portfolio-rebalancer.md

@@ -0,0 +1,94 @@
+# A portfolio rebalancer
+
+A holdings book where one column is a decision and the rest are consequences.
+The user edits **Target**; the grid recomputes drift and the trade to place, totals each sector, and refuses an edit that would allocate more than the whole book.
+
+```demo
+file: recipes/PortfolioRebalancer.tsx
+hint: Type 40 into a Target cell - the commit is refused with the total it would have produced.
+height: 620
+```
+
+## Deriving the rows
+
+`accessorFn` is handed one row, so a column whose value depends on the other rows - a weight as a share of the portfolio - cannot be written as one.
+Derive the whole collection once and hand the grid the finished shape:
+
+```tsx
+const positions = useMemo(() => {
+  const valued = holdings.map((h) => ({ ...h, marketValue: h.price * h.shares }));
+  const total = valued.reduce((sum, h) => sum + h.marketValue, 0);
+
+  return valued.map((h) => ({
+    ...h,
+    currentPct: (h.marketValue / total) * 100,
+    drift: h.targetPct - (h.marketValue / total) * 100,
+  }));
+}, [holdings]);
+```
+
+`editing.onCommit` writes back to `holdings`, the source array, and the derived rows arrive through `data` on the next render.
+Under `editing.mode: "cell"` with no draft store, every dependent column follows the keystroke that committed.
+
+## Gating the one editable column
+
+`editing.columns` lists what takes edits. Everything else is market data and stays read-only whatever its own meta says.
+
+```tsx
+editing: {
+  mode: "cell",
+  columns: ["targetPct"],
+  onCommit: ({ rowId, value }) => save(rowId, value.targetPct),
+}
+```
+
+## The rule that needs the other rows
+
+A target weight is only valid against the rest of the book, so the rule is `editing.tableValidators`, not `meta.edit.validate`.
+`rows` is the collection as it would stand if the commit landed, so the committing row's drafted value is already in it.
+
+```tsx
+tableValidators: {
+  onSubmit: ({ rows }) => {
+    const total = rows.reduce((sum, r) => sum + Number(r.value.targetPct ?? 0), 0);
+
+    return total > 100.005
+      ? { fields: { targetPct: `Targets would total ${pct(total)}` } }
+      : undefined;
+  },
+}
+```
+
+The bound on a single cell - between 0 and 100 - stays on the column as [`meta.edit.validate`](/docs/editors), because it needs nothing but the value.
+
+## Totals in two places
+
+Sector totals come from `aggregationFn` on each column; the portfolio total comes from a `footer` and [`aggregateColumn`](/docs/summary-row), which follows the filters.
+
+```tsx
+columnHelper.accessor("marketValue", {
+  aggregationFn: "sum",
+  footer: ({ table }) =>
+    money.format(Number(aggregateColumn({ table, columnId: "marketValue" }))),
+});
+```
+
+Summing `targetPct` is meaningful only because the values are shares of one whole: a footer reading `100.0%` says the book is fully allocated.
+
+## Reading drift
+
+Drift is signed, so the cell renders a tint whose strength follows the size of the miss and whose colour follows its direction.
+Rows more than three points out take `--row-bg` as well, which composes under hover and selection instead of replacing them.
+
+```tsx
+<TMDataGrid.Table<Position>
+  rowStyle={(row) =>
+    !row.getIsGrouped() && Math.abs(row.original.drift) >= 3
+      ? { "--row-bg": "color-mix(in srgb, var(--mantine-color-yellow-6) 10%, transparent)" }
+      : undefined
+  }
+/>
+```
+
+A group row is handed to `rowStyle` too, and its `original` is an arbitrary child's record, so the callback guards with `row.getIsGrouped()`.
+[Row styling](/docs/row-styling) covers the rest of the vocabulary.