@jielga/tmdatagrid 2.1.4 → 2.3.0

package/skills/options/SKILL.md

@@ -2,19 +2,23 @@
 name: options
 description: >
   useTMDataGrid options, return value and state persistence. Covers passthrough
-  of TanStack TableOptions, the default initialState (pagination, columnPinning,
-  globalFilterFn), the meta object (loading, noResultsLabel, rowHeight,
-  totalRowCount), the grid's own persist, enableColumnOrdering,
-  enablePagination, selectionMode and showSelectedBackground options, the
-  persist option with dataKey/settingsKey slice selection and storageMode, the
-  returned api (table, ui, edit, features, labels, resetSettings, scrollToRow),
-  ui panel and column drag actions, and reading grid state with useSelector.
-  Load when configuring the hook, persisting column layout or filters, or
-  reacting to grid state from a parent.
+  of TanStack TableOptions, every default the grid changes (globalFilterFn,
+  groupedColumnMode, autoResetExpanded, autoResetPageIndex,
+  defaultColumn.minSize), the default initialState, the meta object (loading,
+  noResultsLabel, rowHeight, totalRowCount), the grid's own options (persist,
+  labels, editing, filters, exportOptions, enableColumnOrdering,
+  enablePagination, resetPageOnQueryChange, enableRowNumbers, selectionMode,
+  showSelectedBackground, cellSelection, renderDetails, overscan,
+  quickSearchMode), persist with dataKey/settingsKey slices, storageMode and
+  urlKey deep links, the returned api (table, ui, edit, features, labels,
+  resetSettings, scrollToRow), ui actions, and reading grid state with
+  useSelector over table.store, since table.getState() does not exist in v9.
+  Load when configuring the hook, looking up an option's default, persisting
+  layout or filters, or reacting to grid state from a parent.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/use-tm-data-grid.md'
   - 'Jielga/react:packages/tmdatagrid/docs/persistence.md'
@@ -28,7 +32,8 @@ Creates the table instance and the state used by the grid interface.
 
 ```tsx
 const grid = useTMDataGrid<TData>(options);
-// { table, ui, edit, features, labels, resetSettings, scrollToRow }
+// { table, ui, edit, features, labels, filters, exportOptions, renderDetails,
+//   renderDetailsEstHeight, overscan, resetSettings, scrollToRow }
 ```
 
 The signature is
@@ -42,43 +47,77 @@ All TanStack `TableOptions` are supported and passed through unchanged, includin
 flags and `rowCount`. The `features` option is supplied internally and cannot be
 overridden.
 
-`persist`, `enableColumnOrdering`, `enablePagination`, `selectionMode` and
-`showSelectedBackground` are the grid's own options and are consumed by the hook
-rather than forwarded to TanStack.
+The grid defines these options itself: `persist`, `labels`, `editing`,
+`filters`, `exportOptions`, `enableColumnOrdering`, `enablePagination`,
+`resetPageOnQueryChange`, `enableRowNumbers`, `selectionMode`,
+`showSelectedBackground`, `defaultHighlightedRowId`, `onHighlightedRowChange`,
+`cellSelection`, `onFocusedCellChange`, `renderDetails`,
+`renderDetailsEstHeight`, `detailsColumnPosition`, `overscan`,
+`quickSearchMode` and `enableMatchHighlighting`. The table below marks them
+"Defined by the grid"; every other row is a TanStack option, listed where the
+grid changes its default or where it decides something visible. A TanStack
+default the grid changes reads, for example, `"remove"` (grid default;
+TanStack: `"reorder"`). A TanStack option that is not listed passes through
+with TanStack's own default.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `data` | `TData[]` | – | Row data. Keep the reference stable with `useMemo`. |
-| `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. |
-| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. Required once `editing` is set. |
+| `data` | `TData[]` | – | Row data. When the reference changes the table reprocesses the row models, so keep it stable with `useMemo`; a fresh `[]` for the empty case belongs in a module-scope constant. |
+| `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. Define them outside the component. |
+| `getRowId` | `(row, index, parent?) => string` | Row index | The id that row selection, expansion, row pinning and editing are keyed by. The index points at another record after a sort or a refetch, so return the entity id. Required once `editing` is set. |
+| `defaultColumn` | `Partial<ColumnDef>` | `{ minSize: 80 }` (grid default; TanStack: `{}`) | Defaults merged under every column. The grid sets `filterFn: "tmDataGrid"` and clears `aggregationFn` and `aggregatedCell` on every column, so those three keys have no effect here; a value on the column wins. |
 | `enableRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes row selection and its checkbox column. |
-| `selectionMode` | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a row click does. Defined by the grid - see the `rows` skill. |
-| `showSelectedBackground` | `boolean` | Follows the mode | Background tint on selected rows: off for `"checkbox"`, on for `"row"`. Colour is `--dg-row-selected-bg`. Defined by the grid. |
-| `enableSorting` | `boolean` | `true` | Enables sorting for the table. |
-| `enableColumnFilters` | `boolean` | `true` | Enables filtering for the table. |
-| `enableHiding` | `boolean` | `true` | Enables column visibility for the table. |
+| `enableMultiRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes the select-all checkbox and limits the selection to one row. |
+| `selectionMode` | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a bare row click does. Defined by the grid, see the `rows` skill. |
+| `showSelectedBackground` | `boolean` | On for `"row"`, off for `"checkbox"` | Determines whether selected rows take a background tint, coloured by `--dg-row-selected-bg`. Defined by the grid, see the `rows` skill. |
+| `defaultHighlightedRowId` | `string \| null` | – | Row highlighted on mount, under a mode with a highlight. Read once, like `initialState`. Defined by the grid. |
+| `onHighlightedRowChange` | `(rowId: string \| null) => void` | – | Follows the highlighted row, from clicks and from `ui.actions.setHighlightedRow`. Defined by the grid. |
+| `enableSorting` | `boolean` | `true` | `false` removes the sort indicator, the sort menu items and click-to-sort. Also a column option. See the `columns` skill. |
+| `enableMultiSort` | `boolean` | `true` for accessor columns | Shift+click on a header adds a sort instead of replacing it. Also a column option. See the `columns` skill. |
+| `maxMultiSortColCount` | `number` | `Number.MAX_SAFE_INTEGER` | How many sorts are kept; past it the oldest is dropped. |
+| `enableColumnFilters` | `boolean` | `true` | `false` removes the filter menu item, the `FilterButton`, the header filter row and the panel's column list, and disables the panel's "Add filter" button. Filters already in state still apply. See the `filtering` skill. |
+| `enableGlobalFilter` | `boolean` | `true` | `false` removes `Search`. Also a column option, removing one column from the search. See the `filtering` skill. |
+| `globalFilterFn` | filter fn \| name | `"tmDataGridFuzzy"`; `"includesString"` under `quickSearchMode: "contains"` (grid default; TanStack: `"auto"`) | How the quick search matches. An explicit value also switches the fuzzy rank ordering off. |
+| `enableHiding` | `boolean` | `true` | `false` removes the Hide column item, the Manage columns submenu and the column chooser. Also a column option. |
 | `enableColumnPinning` | `boolean` | `true` | Enables pinning for the table. `false` removes the pin menu items; the generated lanes stay pinned. |
-| `enableColumnResizing` | `boolean` | `true` | Enables resizing for the table. |
-| `enableColumnOrdering` | `boolean` | `true` | Enables header dragging and the move menu items. Defined by the grid. |
-| `enablePagination` | `boolean` | `false` | Enables client-side paging and the `Footer` pager. Implied by `manualPagination`. Defined by the grid. |
-| `cellSelection` | `"none" \| "single" \| "range"` | `"none"` | Cell cursor; `"range"` adds a drag-selectable rectangle, Ctrl+C and CSV export. Defined by the grid. |
-| `onFocusedCellChange` | `(cell \| null) => void` | – | Fires whenever the focused cell moves. |
-| `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Defined by the grid. |
-| `columnResizeMode` | `"onChange" \| "onEnd"` | `"onChange"` | Resize update strategy. |
-| `initialState` | `Partial<TableState>` | See below | The state the grid starts from, read once on mount. Merged over the grid defaults. |
-| `state` | `Partial<TableState>` | – | Controlled state. Each slice requires its `onXChange` - see below. |
-| `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
-| `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
-| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. Two axes: `mode` (`"cell" \| "cellConfirm" \| "row"`) picks what counts as a commit, `draft` picks whether it parks in the draft store; the object also holds `onCommit`, `onSaveDrafts`, `rowValidators`, `isRowEditable`, `newRowDefaults`, `newRowsSticky` (keeps committed new rows in the sticky entry block instead of sorting them in with the body), `onRowAdd` and `onRowDelete` - see the `editing` skill. |
-| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. |
+| `enableColumnResizing` | `boolean` | `true` | With `false` the divider is displayed but cannot be dragged, and double-click autosize and the Autosize menu item are removed. Also a column option, as `enableResizing`. |
+| `enableColumnOrdering` | `boolean` | `true` | Enables header dragging and the move menu items. Defined by the grid, see the `columns` skill. |
+| `enableGrouping` | `boolean` | `true`; `false` under `manualPagination` (grid default; TanStack: `true`) | `false` removes the Group by and Ungroup menu items and the tree lane. Also a column option. See the `grouping` skill. |
+| `groupedColumnMode` | `"remove" \| "reorder" \| false` | `"remove"` (grid default; TanStack: `"reorder"`) | What happens to a column the rows are grouped by: `"remove"` takes it out of the grid, `"reorder"` moves it to the front, `false` leaves it in place. See the `grouping` skill. |
+| `enablePagination` | `boolean` | `false` | Enables client-side paging and the `Footer` pager. Implied by `manualPagination`. Defined by the grid, see the `data` skill. |
+| `resetPageOnQueryChange` | `boolean` | `true` | Returns to the first page when a column filter, the quick search, the sorting or the grouping changes through the table. A `data` change does not count. Defined by the grid, see the `data` skill. |
+| `autoResetPageIndex` | `boolean` | `false` (grid default; TanStack: `!manualPagination`) | TanStack's return to the first page on every `data` change. Off, since `resetPageOnQueryChange` covers the query. |
+| `autoResetExpanded` | `boolean` | `false` (grid default; TanStack: `!manualExpanding`) | TanStack's collapse of every expanded row on a `data` change. Off, so open details panels survive a refetch. |
+| `manualFiltering`, `manualSorting`, `manualGrouping`, `manualPagination` | `boolean` | `false` | The server does that step and the grid shows `data` as given. `manualPagination` also implies `enablePagination`. See the `server-side` skill. |
+| `rowCount` | `number` | – | The total row count under `manualPagination`, read by the pager. |
+| `enableRowNumbers` | `boolean` | `false` | The row-number gutter, outermost left. Defined by the grid, see the `rows` skill. |
+| `enableRowPinning` | `boolean \| (row) => boolean` | `false` (grid default; TanStack: `true`) | Rows can be pinned to sticky edge blocks with `row.pin()`. See the `rows` skill. |
+| `quickSearchMode` | `"fuzzy" \| "contains"` | `"fuzzy"` | How `Search` matches. Fuzzy forgives typos and orders unsorted results by match quality; `"contains"` is plain substring matching. Defined by the grid, see the `filtering` skill. |
+| `enableMatchHighlighting` | `boolean` | `false` | Cells mark the matched text while a contains-family filter or the quick search is active. Defined by the grid, see the `filtering` skill. |
+| `renderDetails` | `({ row, table }) => ReactNode` | – | Panel rendered under an expanded row, spanning every column. Setting it turns row details on and adds the pinned chevron lane. Defined by the grid, see the `rows` skill. |
+| `renderDetailsEstHeight` | `number` | `160` | What the virtualizer assumes for a panel it has not measured yet. Panels are measured once mounted, so an approximation is enough. Defined by the grid. |
+| `detailsColumnPosition` | `"left" \| "right"` | `"left"` | Which edge the details lane is pinned to. `"right"` places it after every column, inside the edit lane. Defined by the grid, see the `rows` skill. |
+| `cellSelection` | `"none" \| "single" \| "range"` | `"none"` | Cell cursor and, under `"range"`, a selectable rectangle with Ctrl+C and CSV export. Defined by the grid, see the `cell-selection` skill. |
+| `onFocusedCellChange` | `(cell: TMDataGridCellPosition \| null) => void` | – | Called whenever the focused cell moves, by key, click or `setFocusedCell`. Defined by the grid. |
+| `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Raise it if fast scrolling flashes blank rows, lower it when rows are expensive to render. Defined by the grid. |
+| `columnResizeMode` | `"onChange" \| "onEnd"` | `"onEnd"` | When a resize drag writes `columnSizing`. The grid paints a running drag itself either way; `"onChange"` also publishes a width on every pointer move, which re-renders the grid with each of them. |
+| `initialState` | `Partial<TableState>` | – | Starting state, read once on mount. Merged over the grid defaults below. |
+| `state` | `Partial<TableState>` | – | Controlled state. Each slice requires its `onXChange`. See below. |
+| `atoms` | `Partial<Record<slice, Atom>>` | – | External atoms owning state slices. No callback required. Takes precedence over `state`. |
+| `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration. See below. |
+| `filters` | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Where the filter controls go - a popup, a sidebar, the column headers, or nowhere. Defined by the grid, see the `filtering` skill. |
+| `exportOptions` | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | The export's `format`, `fileName`, `includeHeaders` and `columns`. Defined by the grid, see the `data` skill. |
+| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. `mode` picks what counts as a commit and `draft` whether edits collect in the draft store. Requires `getRowId`. Defined by the grid, see the `editing` skill. |
+| `persist` | `TMDataGridPersistence` | – | State persistence. Defined by the grid, see below. |
+| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. Defined by the grid, see the `appearance` skill. |
 
 ### Default initial state
 
 | Slice | Default |
 | --- | --- |
-| `pagination` | `{ pageIndex: 0, pageSize: 25 }` - inert until pagination is enabled |
-| `columnPinning.start` | The checkbox column, followed by any columns you provide |
-| `globalFilterFn` | `"includesString"` |
+| `pagination` | `{ pageIndex: 0, pageSize: 25 }`. Inert until pagination is enabled |
+| `columnPinning.start` | The row number, checkbox, tree and details columns, followed by any columns you provide. The details column moves to `end` under `detailsColumnPosition: "right"` |
+| `columnPinning.end` | Any columns you provide, then the details column under `detailsColumnPosition: "right"`, then the edit column |
 
 ### Controlled state
 
@@ -113,22 +152,25 @@ const grid = useTMDataGrid({
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `loading` | `boolean` | – | Displays a loader instead of the empty state. |
-| `noResultsLabel` | `string` | `"No rows match your filters"` | Empty state text. |
+| `loading` | `boolean` | `false` | While `true` and the view is empty, a loader replaces the empty state; `renderEmptyState` is not called. Rows on screen stay. See the `data` skill. |
+| `noResultsLabel` | `string` | `labels.noResults` | The text shown when a filter or the search leaves no rows. |
 | `rowHeight` | `number` | From `size` | Row height in px. Overrides the size scale. |
-| `totalRowCount` | `number` | – | Unfiltered total used by `SummaryCount`. Required for server-side data. |
+| `totalRowCount` | `number` | – | Unfiltered total used by `SummaryCount`. Without it a `manualFiltering` or `manualPagination` grid shows the shown count alone. |
 
 ## persist
 
 Restores table state on mount and writes it back on every change. State is split
-across two keys because the groups have different lifetimes: column configuration
-stays valid indefinitely, while filters and pagination go stale as the data
-changes. Separate keys let one group be cleared without touching the other.
+across three keys because the groups have different lifetimes: column configuration
+stays valid indefinitely, filters and pagination go stale as the data
+changes, and a deep link has to travel with the page URL. Separate keys let one
+group be cleared without touching the others.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | `TMDataGridPersistKey<TMDataGridSettingsSlice>`: `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `urlKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](#deep-links). |
+| `urlStorage` | `TMDataGridUrlStorage`: `{ get(name): string \| null; set(name, value: string \| null): void }` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `storageMode` | `TMDataGridStorageMode`: `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
@@ -164,6 +206,7 @@ const persist = {
 | Group | Available slices |
 | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey`. |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
 
 `grouping` is a settings slice because it names columns rather than values, so it
@@ -188,38 +231,131 @@ dropped.
 
 Source: `packages/tmdatagrid/docs/persistence.md` (Behaviour).
 
+### Deep links
+
+`urlKey` keeps data slices in one URL search param, so a link to the page opens
+the grid on the same filters. The string is the param name; a bare key takes
+every data slice, a tuple a subset, as with `dataKey`.
+
+```tsx
+const persist = {
+  settingsKey: "employees.settings",
+  // Sorting is remembered per browser; the filters travel in the link.
+  dataKey: ["employees.data", ["sorting"]],
+  urlKey: ["employees", ["columnFilters", "globalFilter"]],
+} satisfies TMDataGridPersistence;
+```
+
+- A slice lives in one group. A slice listed under `urlKey` is taken out of
+  `dataKey`: a bare `dataKey` hands it over silently, while a `dataKey` tuple
+  that names the slice explicitly is reported with `console.error` on mount.
+- The param carries only the slices whose value differs from the initial state
+  (`initialState` merged over the grid defaults), and only the column filters
+  that are active. When nothing differs, the param is removed. A link without the param, or without a slice, opens on the
+  initial state; a URL slice never falls back to storage.
+- Writes use `history.replaceState`, never `pushState`. Only the grid's own
+  param changes; the path, the hash, other params and `history.state` are kept.
+  Two grids on one page use two keys.
+- The URL payload has no version stamp, so a bookmarked link survives a
+  release. The shape guards and the realignment against existing columns apply
+  as for storage, and `serialize` / `deserialize` apply to the URL payload too.
+- `meta.filter.url: false` on a column keeps its filter out of the param, on
+  read and on write. The column's filter is then not persisted anywhere, and a
+  filter on it in `initialState` still applies when a link is opened. The
+  flag has no effect unless `urlKey` carries `columnFilters`.
+- `urlStorage` replaces the default read and write of the param, for a router
+  that owns the URL. `get` returns the param's string or `null`; `set` receives
+  the string, or `null` to remove the param. `set` is only called when the
+  value changed. Keep `persist` referentially stable here too: react-router
+  rebuilds `setSearchParams` on every URL change, so read it through a ref.
+
+```tsx
+// react-router: let the router do the replace.
+const [, setSearchParams] = useSearchParams();
+const setSearchParamsRef = useRef(setSearchParams);
+setSearchParamsRef.current = setSearchParams;
+
+const persist = useMemo(
+  () =>
+    ({
+      urlKey: ["employees", ["columnFilters"]],
+      urlStorage: {
+        get: (name) => new URLSearchParams(window.location.search).get(name),
+        set: (name, value) =>
+          setSearchParamsRef.current(
+            (prev) => {
+              if (value === null) prev.delete(name);
+              else prev.set(name, value);
+              return prev;
+            },
+            { replace: true },
+          ),
+      },
+    }) satisfies TMDataGridPersistence,
+  [],
+);
+```
+
+Source: `packages/tmdatagrid/docs/persistence.md` (Deep links).
+
 ## Return value
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
 | `ui` | `TMDataGridUiStore`: `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
+| `filters` | `TMDataGridFiltersSettings` | The `filters` option with its defaults filled in. |
+| `exportOptions` | `TMDataGridExportSettings` | The `exportOptions` option with its defaults filled in. |
 | `edit` | `TMDataGridEditApi` | The edit engine, inert until `editing` is set. See the `editing` skill. |
 | `features` | `TMDataGridFeatureFlags` | Table-level feature switches, re-read on each render. |
 | `labels` | `TMDataGridLabels` | The resolved label set, overrides merged over English. |
+| `renderDetails` | `TMDataGridDetailsRenderer<TData> \| undefined` | The detail renderer, passed through for `TMDataGrid.Table` to call. |
+| `renderDetailsEstHeight` | `number` | The estimate, resolved to its default when the option was not set. |
+| `overscan` | `number` | The overscan, resolved to its default when the option was not set. |
 | `resetSettings` | `() => void` | Puts the settings state back to a clean first visit. |
 | `scrollToRow` | `({ rowId, align? }) => boolean` | Scrolls a row into view through the virtualizer. `false` when the row is not in the current view. |
 
-Both stores are subscribable, which is how a parent reacts to grid state without
-owning it:
+`table` is `TMDataGridTable<TData>`, TanStack's core `Table` type. It has no
+`getState()` (that method does not exist in TanStack Table v9) and `table.state`
+is not part of the type; state lives in `table.store`.
+
+### Reading state
+
+`table.store` and `ui` are TanStack stores. Read a slice with `useSelector`
+from `@tanstack/react-store`, which subscribes the component to what the
+selector returns:
 
 ```tsx
 import { useSelector } from "@tanstack/react-store";
 
 const selectedCount = useSelector(
   grid.table.store,
-  (state) => Object.keys(state.rowSelection).length,
+  () => grid.table.getSelectedRowModel().rows.length,
 );
-
+const isGrouped = useSelector(grid.table.store, (state) =>
+  state.grouping.includes("department"),
+);
+const pageIndex = useSelector(grid.table.store, (state) => state.pagination.pageIndex);
 const filterPanelOpen = useSelector(grid.ui, (state) => state.filterPanelOpen);
 ```
 
+`grid.table.store.state` is a plain read and does not subscribe the component.
+A bare read is stale in any component that does not call `useTMDataGrid`
+itself, and under the React Compiler also in the one that does; `useSelector`
+subscribes either way. A table or column getter such as
+`table.getSelectedRowModel()` or `column.getIsGrouped()` is a plain read as
+well; call it inside a selector, as above. `getTMDataGridPaginationApi(table)`
+is a snapshot too; wrap it in `useSelector` or use the `state` the Footer's
+`renderPagination` slot receives.
+
 ### ui actions
 
 | Action | Signature |
 | --- | --- |
 | `openFilterPanel` | `(columnId?: string \| null) => void` |
 | `closeFilterPanel` | `() => void` |
+| `openExportPicker` | `(request: TMDataGridExportPickerRequest) => void` |
+| `closeExportPicker` | `() => void` |
 | `focusPanelFilter` | `(columnId: string \| null) => void` |
 | `focusHeaderFilter` | `(columnId: string \| null) => void` |
 | `startColumnDrag` | `(columnId: string) => void` |
@@ -232,29 +368,41 @@ const filterPanelOpen = useSelector(grid.ui, (state) => state.filterPanelOpen);
 The last two move the cell cursor and the selected rectangle under
 `cellSelection`; DOM focus follows `focusedCell` and scrolls its row into view.
 
-`startColumnDrag` / `endColumnDrag` are called by the header cells while a column is being dragged, and
-`ui.draggedColumnId` holds the column being moved - browsers keep `dataTransfer`
-unreadable until the drop.
+`startColumnDrag` / `endColumnDrag` are called by the header cells while a
+column is being dragged, and `ui.state.draggedColumnId` holds the column being
+moved - browsers keep `dataTransfer` unreadable until the drop.
 
 `openColumnFilter(grid, columnId)` combines the two steps the column menu uses:
-add an empty filter row for the column if none exists, then open the panel.
+add an empty filter row for the column if none exists, then open the panel on
+it, or focus the column's header control under `filters.inHeader`.
 
 ## Common mistakes
 
 ### Reading store state during render
 
-`grid.table.store.state` is a plain read - it does not subscribe the component,
-so the value is correct on first render and then never updates.
+`grid.table.store.state` is a plain read - it does not subscribe the component.
+A bare read is stale in any component that does not call `useTMDataGrid`
+itself, and under the React Compiler also in the one that does; `useSelector`
+subscribes either way. The same holds for every table and column getter called
+outside a selector.
 
 ```tsx
 // Wrong - never re-renders when the selection changes.
 const count = Object.keys(grid.table.store.state.rowSelection).length;
+// Wrong - a getter outside a selector is a snapshot.
+const grouped = grid.table.getColumn("department")!.getIsGrouped();
+// Wrong - `getState()` does not exist in TanStack Table v9.
+const sorting = grid.table.getState().sorting;
 
 // Right.
 const count = useSelector(
   grid.table.store,
   (state) => Object.keys(state.rowSelection).length,
 );
+const grouped = useSelector(grid.table.store, (state) =>
+  state.grouping.includes("department"),
+);
+const sorting = useSelector(grid.table.store, (state) => state.sorting);
 ```
 
 ### persist object built during render
@@ -273,4 +421,7 @@ Include a tenant or user identifier in the key.
 
 A new array identity on each render re-runs the row model. `data={rows ?? []}`
 allocates a fresh `[]` every render when `rows` is undefined - hoist the empty
-array to a module-scope constant or `useMemo` the expression.
+array to a module-scope constant or `useMemo` the expression. Under `editing`
+the cost is higher: every new `data` identity drops the open drafts of the rows
+it no longer contains, so a transient `[]` while refetching discards every
+draft.

package/skills/rows/SKILL.md

@@ -8,16 +8,16 @@ description: >
   reading a selection through the table store, onRowClick / onCellClick /
   onCellDoubleClick / onCellContextMenu, the renderRowContextMenu slot with its
   internalItems handback, renderColumnMenuItems and rowContextMenuProps, per-row
-  styling with rowStyle, rowClassName, striped and the --row-bg rule, the row
-  details panel through renderDetails, detailsColumnPosition and
-  DETAILS_COLUMN_ID, row pinning with enableRowPinning and row.pin, and the
-  row-number gutter through enableRowNumbers. Load when selecting rows, reacting
-  to a click, opening a detail panel, colouring rows by their data, pinning rows
-  to an edge, or numbering them.
+  styling with rowStyle, rowClassName, striped, highlightOnHover and the
+  --row-bg rule, the row details panel through renderDetails,
+  detailsColumnPosition and DETAILS_COLUMN_ID, row pinning with enableRowPinning
+  and row.pin, and the row-number gutter through enableRowNumbers. Load when
+  selecting rows, reacting to a click, opening a detail panel, colouring rows by
+  their data, pinning rows to an edge, or numbering them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/react:packages/tmdatagrid/docs/row-interaction.md'
@@ -37,8 +37,8 @@ cell cursors and ranges are `cell-selection`.
 ## Selection
 
 `selectionMode` sets what selecting looks like **and** what a bare row click
-does. It is one option rather than two because a click can toggle a
-multi-selection or move a highlight, but not both.
+does. A bare click either toggles the selection or moves the highlight, never
+both.
 
 | Mode | Checkbox column | Row click |
 | --- | --- | --- |
@@ -51,8 +51,8 @@ multi-selection or move a highlight, but not both.
 const grid = useTMDataGrid({ data, columns, selectionMode: "row" });
 ```
 
-The first two write to TanStack's `rowSelection`, so the toolbar count,
-`getSelectedRowModel()` and persistence all behave the same either way. Under
+The first two write to TanStack's `rowSelection`, so `getSelectedRowModel()`
+and `onRowSelectionChange` behave the same either way. Under
 `"row"` the click follows desktop-list conventions: a plain click
 makes the selection this row, Ctrl/Cmd toggles it and leaves the rest, Shift
 selects the range from the anchor, Ctrl+Shift adds that range. Rows are
@@ -61,7 +61,7 @@ focusable in this mode, and Space or Enter toggles the focused row.
 `enableRowSelection: false` removes the checkbox column and row-click selection
 in any mode.
 
-### The highlight is not a selection
+### The highlighted row
 
 The highlight is state of its own, not a slice of `rowSelection`. That is what
 lets `"checkboxAndHighlight"` run both at once: tick rows for a bulk action,
@@ -81,8 +81,9 @@ const grid = useTMDataGrid({
 ### Reading a selection
 
 Read it through the table store rather than by calling the method directly.
-`table` keeps one identity across renders, so the React Compiler caches a bare
-`getSelectedRowModel()` and the component stops updating.
+A bare read is stale in any component that does not call `useTMDataGrid`
+itself, and under the React Compiler also in the one that does; `useSelector`
+subscribes either way.
 
 ```tsx
 import { useSelector } from "@tanstack/react-store";
@@ -160,9 +161,10 @@ the row with `data-context-menu` while its menu is open, so an action meant for
 a multi-selection reads `table` and falls back to the clicked row.
 
 Under `cellSelection: "range"` the grid has its own items for this menu: copy,
-export and include headers. `internalItems` is those items, and **using it takes
-over the composition**: place it and the menu is exactly what you returned; omit
-it and the grid keeps its own items above a divider and yours below.
+export and include headers. `internalItems` holds those items, and **using it
+takes over the composition**. Place it, and the menu is exactly what you
+returned. Omit it, and the grid renders its items above a divider and yours
+below.
 
 ```tsx
 renderRowContextMenu={({ row, internalItems }) => (
@@ -211,8 +213,15 @@ them and they stop showing. `striped` follows position in the view, so it
 survives sorting and filtering rather than sticking to records, and pinned rows
 are not striped.
 
+The hover tint follows the gestures a row answers: a row takes it under
+`selectionMode: "row"` or a highlight mode, `onRowClick` or
+`renderRowContextMenu`, and a group row never does. A grid with none of those
+shows no hover tint. `highlightOnHover` on the Table overrides that: `true`
+tints every row, `false` none.
+
 Rows carry `data-selected`, `data-selected-bg`, `data-highlighted`,
-`data-grouped`, `data-depth`, `data-context-menu` and `data-row-id`, so a
+`data-grouped`, `data-depth`, `data-context-menu`, `data-highlight-on-hover`
+and `data-row-id`, so a
 stylesheet can target any of it without a callback. The boolean attributes are
 present, with the value `"true"`, only while they apply - `data-grouped` only
 on group rows - so `[data-grouped]` and `[data-grouped="true"]` are
@@ -232,20 +241,31 @@ const grid = useTMDataGrid({
 });
 ```
 
-Each panel is measured, so heights need not be uniform.
-`renderDetailsEstHeight` (default `160`) is what the virtualizer assumes for one
-it has not measured yet. A generated chevron column, `DETAILS_COLUMN_ID`, is
-pinned left after the checkbox and tree lanes, or right, inside the edit lane,
-under `detailsColumnPosition: "right"`; it cannot be hidden, moved, resized or
-unpinned, and its header opens and closes every panel.
+The panel opens below the row's cells, which stay where they are; there is no
+mode in which a panel replaces the row. Each panel is measured, so heights need
+not be uniform. `renderDetailsEstHeight` (default `160`) is what the virtualizer
+assumes for one it has not measured yet; set it to the typical panel height.
+`DETAILS_COLUMN_ID` is a generated chevron lane. It is pinned left, after the
+checkbox and tree lanes; under `detailsColumnPosition: "right"` it is pinned
+right, inside the edit lane. It cannot be hidden, moved, resized or unpinned.
+Its header opens and closes every panel.
 
 Which rows are open is TanStack's own `expanded` state, so anything can open
 one - `row.toggleExpanded()` from a menu item, `initialState.expanded`,
 `table.toggleAllRowsExpanded()` - and it persists as a `data` slice. The panel
 is a cell spanning the row, not a row: `aria-rowcount` still counts records, and
-a click inside it does not select the row underneath. Group rows have no panel;
+a click inside it does not select the row underneath. It has no padding: content
+fills the row edge to edge, and content that should line up with the cell text
+pads itself with `padding: var(--dg-padding)`. Group rows have no panel;
 expanding one opens its children.
 
+Rows are virtualized. A row that leaves the viewport and the `overscan`
+unmounts, and its panel unmounts with it, so state held inside the panel is
+lost; keep such state outside the grid, keyed by `row.id`. `renderDetails` runs
+on every render of the body, so give a heavy panel a `memo` component and pass
+it `row.original`, not the row. Key a stateful child by `row.id`; that is stable
+only when `getRowId` returns the entity id.
+
 ## Pinning and numbering
 
 Two independent lanes at the edges.
@@ -264,7 +284,7 @@ There is no built-in pin gesture and no pin icon. Build one from TanStack's own
 either as a display column whose cell is a pin button or in the row context
 menu. Read the pinned state through a subscription
 (`useSelector(row.table.store, () => row.getIsPinned())`) rather than calling it
-in a component body: the `row` identity survives a pin, so the React Compiler
+in a component body. The `row` identity survives a pin, so the React Compiler
 would cache the call and the icon would never change. Whichever control you
 build, include unpin in it. Pinned rows leave the scrolling order and render in
 sticky blocks: top under the header, bottom above the summary row.
@@ -300,13 +320,13 @@ Correct:
 rowStyle={() => ({ "--row-bg": "pink" })}
 ```
 
-Source: `packages/tmdatagrid/docs/row-styling.md` (Set `--row-bg`, not `background`).
+Source: `packages/tmdatagrid/docs/row-styling.md` (Set the row background).
 
 ### CRITICAL Reading the selection without subscribing
 
-`table` keeps one identity for the life of the grid, so the React Compiler
-memoizes a bare `getSelectedRowModel()` against it. The count renders once and
-then never changes.
+A bare read is stale in any component that does not call `useTMDataGrid`
+itself, and under the React Compiler also in the one that does; `useSelector`
+subscribes either way. A stale count renders once and then never changes.
 
 Wrong:
 
@@ -327,8 +347,8 @@ Source: `packages/tmdatagrid/docs/row-selection.md` (Acting on a selection).
 ### HIGH Looking for the highlight in `rowSelection`
 
 The highlight is separate state, which is what lets `"checkboxAndHighlight"`
-run both at once. It never appears in `rowSelection`, `getSelectedRowModel()` or
-the persisted selection slice.
+run both at once. It never appears in `rowSelection` or
+`getSelectedRowModel()`.
 
 Wrong:
 
@@ -343,7 +363,7 @@ Correct:
 const current = useSelector(grid.ui, (state) => state.highlightedRowId);
 ```
 
-Source: `packages/tmdatagrid/docs/row-selection.md` (The highlight is not a selection).
+Source: `packages/tmdatagrid/docs/row-selection.md` (The highlighted row).
 
 ### HIGH Expecting a click handler to replace the built-in behaviour
 
@@ -382,18 +402,29 @@ written as though every row reaches it silently skips them.
 
 Source: `packages/tmdatagrid/docs/row-interaction.md`, `packages/tmdatagrid/docs/row-pinning.md`.
 
-### MEDIUM Open panels closing when `data` is replaced
+### MEDIUM Keeping state inside a details panel
 
-TanStack resets `expanded` when the row structure changes, so a refetch collapses
-every open panel.
+A panel unmounts with its row when the row leaves the virtual window, so a form
+or an accordion inside `renderDetails` loses its state on a long scroll and
+comes back reset.
 
-Correct:
+Correct: hold the state outside the grid, keyed by `row.id`, and pass it in.
 
 ```tsx
-useTMDataGrid({ data, columns, renderDetails, autoResetExpanded: false });
+const [drafts, setDrafts] = useState<Record<string, Draft>>({});
+useTMDataGrid({
+  data,
+  columns,
+  renderDetails: ({ row }) => (
+    <DetailsForm draft={drafts[row.id]} onChange={(d) => setDrafts((all) => ({ ...all, [row.id]: d }))} />
+  ),
+});
 ```
 
-Source: `packages/tmdatagrid/docs/row-details.md`.
+`autoResetExpanded` is already `false` by default, so a refetch does not close
+the panels; pass `autoResetExpanded: true` to get TanStack's collapse back.
+
+Source: `packages/tmdatagrid/docs/row-details.md` (Panel behaviour).
 
 ### MEDIUM Expecting pinned rows to persist
 

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/server-side.md'
   - 'Jielga/react:packages/tmdatagrid/docs/server-query.md'