@jielga/tmdatagrid 1.0.0 → 1.0.2

package/skills/getting-started/SKILL.md

@@ -3,27 +3,28 @@ name: getting-started
 description: >
   Set up TMDataGrid, a compound React data grid built on TanStack Table v9 and
   Mantine. Covers useTMDataGrid, the TMDataGrid root, context, the component
-  catalog (Table, Footer, Toolbar, Spacer, SummaryCount, FilterButton,
-  ColumnsButton, FilterPanel, FilterPills, ColumnsPanel), the size scale and the
-  bounded-height layout requirement. Load when adding a grid, choosing which
-  parts to render, or when rows do not appear.
+  catalog (Table, Footer, Toolbar, Spacer, SummaryCount, Search,
+  LoadingIndicator, EditActions, FilterButton, ColumnsButton, FilterPanel,
+  FilterPills, ColumnsPanel), the size scale and the bounded-height layout
+  requirement. Load when adding a grid, choosing which parts to render, or when
+  rows do not appear.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.0'
+  library_version: '1.0.2'
 sources:
   - 'Jielga/TMDataGrid:src/docs/getting-started.md'
-  - 'Jielga/TMDataGrid:src/docs/components.md'
+  - 'Jielga/TMDataGrid:src/docs/anatomy.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'
   - 'Jielga/TMDataGrid:src/tmdatagrid/core/sizes.ts'
 ---
 
-# TMDataGrid — Getting started
+# TMDataGrid - Getting started
 
 `useTMDataGrid` creates the table, `TMDataGrid` provides it through context, and
 the parts rendered inside read what they need from that context. Only the parts
 you render exist, and only the features you enable have state: pagination is
-opt-in via `enablePagination` — by default every row renders, virtualized.
+opt-in via `enablePagination` - by default every row renders, virtualized.
 
 ## Install
 
@@ -103,14 +104,31 @@ Spread the hook result (`{...grid}`) rather than assigning `table`, `ui` and
 | Column menu | On hover: sort, filter, pin, move, hide, manage columns. |
 | Filter panel | Column, operator and value rows. |
 | Column manager | Search, toggle, show/hide all, reset. |
-| Row selection | Checkbox column pinned to the left, or click-to-select rows with `rowSelectionMode: "row"`. |
+| Row selection | Checkbox column pinned to the left, or click-to-select rows with `selectionMode: "row"`. See the `rows` skill. |
 | Pagination | Off by default: all rows render, virtualized. Opt in with `enablePagination: true`. |
 | Sizing | `size="xs"` to `size="xl"` scales rows, type and controls. |
 
-Each is bound to a capability check — disabling the standard table or column
-option also removes its interface. Column ordering (`enableColumnOrdering`) and
-pagination (`enablePagination`) are the two switches the grid defines itself.
-See the `features` skill.
+Each is bound to a capability check - disabling the standard table or column
+option also removes its interface, and empty menus and inactive buttons are
+never rendered. Column ordering (`enableColumnOrdering`) and pagination
+(`enablePagination`) are the two switches the grid defines itself, because
+TanStack ships state and APIs for both but no `enable` option.
+
+## Which skill covers what
+
+| Need to | Load |
+| --- | --- |
+| Define columns, size, hide, pin, reorder, sort them | `columns` |
+| Filter, or add a search box | `filtering` |
+| Select rows, react to clicks, colour rows, details, pin rows | `rows` |
+| Move a cell cursor, select ranges, copy, export CSV | `cell-selection` |
+| Make cells editable | `editing` |
+| Group rows, aggregate, add a summary row | `grouping` |
+| Page, tune scrolling, handle empty and loading states | `data` |
+| Back the grid with a server | `server-side` |
+| Configure the hook, or persist state | `options` |
+| Theme, size, compose the toolbar, translate | `appearance` |
+| Write tests against a grid | `testing` |
 
 ## Layout
 
@@ -125,21 +143,24 @@ takes a fixed pixel width once resized or pinned.
 
 All read the grid from context and must be rendered inside `TMDataGrid`, except
 `TMDataGrid.FilterPills`, which takes the grid as an `api` prop and can live
-anywhere on the page. Order and presence are up to you — the root is a plain
+anywhere on the page. Order and presence are up to you - the root is a plain
 flex column.
 
 | Component | Props | Notes |
 | --- | --- | --- |
 | `TMDataGrid` | `table`, `ui`, `features`, `size`, `className`, `style` | Root. Provides context. `style` also takes CSS variables: `--dg-row-selected-bg`, `--dg-row-height`, `--dg-header-height`, `--dg-font-size`, `--dg-padding`. |
-| `TMDataGrid.Table` | `onRowClick(row)`, `rowContextMenu` render prop, `rowContextMenuProps` | Header, virtualized body, filter panel. `onRowClick` runs in addition to selection under `rowSelectionMode: "row"`. |
+| `TMDataGrid.Table` | `onRowClick(row)`, `rowContextMenu` render prop, `rowContextMenuProps` | Header, virtualized body, filter panel. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
 | `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`), `pagination` render prop | Pagination controls. Renders nothing unless pagination is enabled. |
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
-| `TMDataGrid.Spacer` | — | Pushes later toolbar items right. |
+| `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
-| `TMDataGrid.FilterButton` | — | Toggles filter panel. Renders nothing if no column is filterable. |
-| `TMDataGrid.ColumnsButton` | — | Opens column manager. Renders nothing if no column is hideable. |
-| `TMDataGrid.FilterPanel` | — | Rendered by `.Table`; exported for custom layouts. Header close button, Escape, click-away, "Add filter" and "Clear all". |
-| `TMDataGrid.ColumnsPanel` | — | Rendered by `.ColumnsButton`; exported for custom layouts. |
+| `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. |
+| `TMDataGrid.LoadingIndicator` | - | Small spinner while `meta.loading` is `true` and rows stay on screen. |
+| `TMDataGrid.EditActions` | - | Save with the pending count, and Discard. Renders nothing while editing is off - see the `editing` skill. |
+| `TMDataGrid.FilterButton` | - | Toggles filter panel. Renders nothing if no column is filterable. |
+| `TMDataGrid.ColumnsButton` | - | Opens column manager. Renders nothing if no column is hideable. |
+| `TMDataGrid.FilterPanel` | - | Rendered by `.Table`; exported for custom layouts. Header close button, Escape, click-away, "Add filter" and "Clear all". |
+| `TMDataGrid.ColumnsPanel` | - | Rendered by `.ColumnsButton`; exported for custom layouts. |
 | `TMDataGrid.FilterPills` | `api`, `size` (default `"sm"`), `showClearAll` (default `true`), `onPillClick(columnId)`, `className` | One pill per active filter, ✕ to clear it. Takes the api as a prop, so it can be rendered outside the grid. Also exported as `TMDataGridFilterPills`. |
 
 Pass the row type so `onRowClick` stays typed:
@@ -149,8 +170,8 @@ Pass the row type so `onRowClick` stays typed:
 ```
 
 `rowContextMenu` fills the dropdown of a Mantine `Menu` the grid opens at the
-pointer on a right-click (or a long press). The grid owns the `Menu` — opening,
-positioning, and closing on Escape, outside click, body scroll or an item pick —
+pointer on a right-click (or a long press). The grid owns the `Menu` - opening,
+positioning, and closing on Escape, outside click, body scroll or an item pick -
 so the render prop only says what goes in it:
 
 ```tsx
@@ -174,7 +195,7 @@ so the render prop only says what goes in it:
 `cell` is the one that was right-clicked, `table` is there for actions that read
 the selection, and `close` is for dropdown content that is not a `Menu.Item`
 (those close themselves). Return `null` to leave a row without a menu. It is
-called during render, and only for the open row, so it must stay pure — put the
+called during render, and only for the open row, so it must stay pure - put the
 work in the item handlers. Right-clicking does not change the selection or the
 highlight; the row carries `data-context-menu` while its menu is open. Pass
 `rowContextMenuProps` for `width`, `shadow`, `position` and the rest.
@@ -229,7 +250,7 @@ mirrors them. Set `meta.rowHeight` for a height outside the scale.
 | `getColumnLabel(column)` | `meta.label`, a string header, or the column id. |
 | `getColumnType(column)` | `meta.type`, defaulting to `"string"`. |
 | `formatFilterLabel({ label, type, filter })` | The one-line filter description used on the pills. |
-| `moveColumn({ table, columnId, targetId, side })` | Moves a column next to another. See the `features` skill. |
+| `moveColumn({ table, columnId, targetId, side })` | Moves a column next to another. See the `columns` skill. |
 | `moveColumnByStep({ table, columnId, direction })` | Moves a column one position within its region. |
 | `SELECT_COLUMN_ID` | Id of the generated checkbox column. |
 
@@ -241,7 +262,7 @@ A new array on every render rebuilds the table's column model. Define `columns`
 at module scope; keep `data` stable with `useMemo`.
 
 ```tsx
-// Wrong — rebuilds the column model every render.
+// Wrong - rebuilds the column model every render.
 export function Employees({ data }: { data: Employee[] }) {
   const columns = columnHelper.columns([...]);
   const grid = useTMDataGrid({ data, columns });
@@ -251,7 +272,7 @@ export function Employees({ data }: { data: Employee[] }) {
 ### Root with no bounded height
 
 The root is `overflow: hidden`. Without `flex: 1; minHeight: 0` in a flex parent
-or an explicit height, the table area collapses and no rows are visible — there
+or an explicit height, the table area collapses and no rows are visible - there
 is no error.
 
 ### Assigning the hook result field by field
@@ -261,7 +282,7 @@ and feature toggles stop being reactive. Spread instead: `<TMDataGrid {...grid}>
 
 ### Expecting Footer to enable pagination
 
-Rendering `TMDataGrid.Footer` does not switch pagination on — the option does.
+Rendering `TMDataGrid.Footer` does not switch pagination on - the option does.
 With pagination off (the default) the Footer renders nothing and every row is
 rendered, virtualized. Set `enablePagination: true` (or `manualPagination:
 true` for server paging) to page the data and show the pager.

package/skills/grouping/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: grouping
+description: >
+  Group TMDataGrid rows into a tree, and total them. Covers enableGrouping,
+  initialState.grouping, the generated GROUP_COLUMN_ID tree lane, why a grouped
+  column leaves the grid and how groupedColumnMode keeps it, aggregationFn and
+  aggregatedCell with the registered names (sum, mean, count, uniqueCount,
+  extent, …), why the grid clears TanStack's "auto" default, group-row
+  selection, why group rows are not data rows, why grouping suspends the pager
+  and isPagingActive, manualGrouping for server-side trees, and the summary row
+  through a column footer with aggregateColumn. Load when grouping rows,
+  aggregating a column, adding totals along the bottom edge, or when the pager
+  greys out.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '1.0.2'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/grouping.md'
+  - 'Jielga/TMDataGrid:src/docs/summary-row.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/grouping.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/summary.ts'
+---
+
+# TMDataGrid - Grouping and totals
+
+Two independent things: grouping folds the rows into a tree and totals each
+category, and the summary row totals everything along the bottom edge.
+
+## Grouping
+
+On by default, and nothing changes until a column is grouped - the reader does
+that from **Group by …** in any column menu. To open already grouped, seed the
+state:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  initialState: { grouping: ["department"] },
+});
+```
+
+Grouping a column **removes it** - its values have moved into the tree lane -
+and a generated Group column (`GROUP_COLUMN_ID`) appears at the front, pinned
+beside the checkbox lane. Each group row shows its value, its record count and a
+chevron. Grouping a second column nests.
+
+Because a grouped column is no longer in the grid, **Ungroup** lives on the tree
+column's menu, one item per grouped column. `groupedColumnMode: "reorder"`
+(TanStack's own default) keeps grouped columns in the grid, moved to the front,
+instead of removing them.
+
+## Aggregation
+
+Off unless asked for. A grouped grid is a tree, not a summary: a group row
+leaves every cell blank except the tree lane. Give a column an `aggregationFn`
+and it fills in.
+
+```tsx
+columnHelper.accessor("salary", {
+  header: "Salary",
+  aggregationFn: "sum",
+  aggregatedCell: (info) => <strong>{sek(Number(info.getValue()))}</strong>,
+  meta: { type: "number", align: "right" },
+});
+```
+
+`"sum"`, `"min"`, `"max"`, `"extent"`, `"mean"`, `"median"`, `"unique"`,
+`"uniqueCount"`, `"count"` and `"auto"` are registered, and a function is
+accepted too.
+
+TanStack's grouping feature defaults every column to `aggregationFn: "auto"`.
+**The grid clears that default**, so grouping does not silently start summing
+numeric columns. Setting `"auto"` yourself restores it.
+
+Grouping runs before sorting, so sorting sorts the rows *inside* each group and
+orders the groups by their aggregated value. A column with no aggregation has no
+value on a group row, so sorting on it reorders rows within each group and
+leaves the groups where they are.
+
+## Group rows are not data rows
+
+A group row is built on its first child's record, so handing it to a callback
+would hand over a real-looking row that is the wrong one. Group rows therefore:
+
+- do not fire `onRowClick` or the cell handlers
+- cannot be highlighted, pinned, or given a details panel
+- never edit
+- carry `data-grouped` and `data-depth`, with `--dg-row-group-bg` behind them
+
+A group row's checkbox selects every record under it at any depth, including
+records inside collapsed sub-groups, showing a tick once all are selected and a
+dash while only some are. Only the records reach `rowSelection` - a group row is
+never in it - so `getSelectedRowModel()` and the toolbar count are unaffected by
+how the tree is arranged. Under `enableMultiRowSelection: false` group rows carry
+no checkbox.
+
+`getGroupDataRows(row)` returns every record under a group row, at any depth.
+
+## Grouping suspends pagination
+
+**Grouping and the built-in pager do not work together, and grouping wins.** As
+soon as a column is grouped the grid renders the whole tree and relies on
+virtualization; `TMDataGrid.Footer` greys its pager out and replaces the range
+with `Grouped · all N rows`. Ungroup and paging resumes where it left off.
+
+This is deliberate. A page can only count one kind of thing, and once the rows
+are a tree neither answer is usable: counting every row splits a group across a
+page boundary, and counting top-level rows quietly redefines "rows per page" as
+groups per page. Rendering the whole tree is the grid's default mode anyway -
+pagination is the opt-in - so nothing is lost but the pager.
+
+`isPagingActive(table, features)` is exported so a custom pager can grey itself
+out the same way. To have both, page on the server: group there and feed the
+grid one page of a tree at a time with `manualPagination` and `manualGrouping`.
+
+## The summary row
+
+There is no flag. Give a column a `footer` and the row appears; it exists
+exactly when at least one visible column defines one.
+
+```tsx
+import { aggregateColumn } from "@jielga/tmdatagrid";
+
+columnHelper.accessor("salary", {
+  header: "Salary",
+  footer: ({ table }) =>
+    sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+});
+```
+
+`footer` is TanStack's own column option, rendered the way the header is.
+`aggregateColumn({ table, columnId, fn })` computes over every **filtered** row -
+all pages, following the filters live - through the registered aggregation
+functions, with `fn` defaulting to `"sum"`.
+
+```tsx
+aggregateColumn({ table, columnId: "age", fn: "mean" });
+aggregateColumn({ table, columnId: "location", fn: "uniqueCount" });
+```
+
+Following the filters is the point: a footer that keeps saying the same number
+while the reader narrows the grid looks like it is answering the question in
+front of them when it is not.
+
+Pinned columns keep their lanes in the summary row, the generated lanes define
+no `footer` so their cells stay blank, and the row is sticky at
+`--dg-summary-height`.
+
+## Common mistakes
+
+### CRITICAL Expecting group rows to total automatically
+
+Grouping alone leaves every cell blank on a group row, because the grid clears
+TanStack's `aggregationFn: "auto"` default. Nothing errors - the tree simply
+looks empty, which reads as a broken feature.
+
+Wrong:
+
+```tsx
+columnHelper.accessor("salary", { header: "Salary" });
+```
+
+Correct:
+
+```tsx
+columnHelper.accessor("salary", { header: "Salary", aggregationFn: "sum" });
+```
+
+Source: `src/docs/grouping.md` (Aggregation).
+
+### HIGH Looking for the grouped column in the grid
+
+`groupedColumnMode` defaults to `"remove"`, so grouping by Department takes the
+Department column out - its values are in the tree lane. Code that reads that
+column's cells, or a test that queries its header, stops finding it the moment a
+reader groups.
+
+Correct, when the column must stay:
+
+```tsx
+useTMDataGrid({ data, columns, groupedColumnMode: "reorder" });
+```
+
+Source: `src/docs/grouping.md` (What grouping does to the grid).
+
+### HIGH Combining the pager with grouping
+
+`enablePagination: true` and a grouped column cannot both be honoured. The pager
+greys out rather than paging the tree, so a footer count wired to
+`getPageCount()` reports a number nobody can navigate to. Read
+`isPagingActive(table, features)` before trusting the pager state.
+
+Source: `src/docs/grouping.md` (Grouping suspends pagination).
+
+### HIGH Handing a group row to a row callback
+
+Group rows sit out `onRowClick`, the cell handlers, pinning, details and
+editing, and their `row.original` is an arbitrary child's record. A bulk action
+built from `row.original` on the tree lane acts on one record instead of the
+group.
+
+Correct:
+
+```tsx
+import { getGroupDataRows } from "@jielga/tmdatagrid";
+
+const records = getGroupDataRows(groupRow).map((row) => row.original);
+```
+
+Source: `src/docs/grouping.md` (Group rows are not data rows).
+
+### MEDIUM Totalling the page instead of the data
+
+`aggregateColumn` deliberately runs over every filtered row, all pages. Summing
+`table.getRowModel().rows` instead totals only what is currently paged in, which
+matches the screen but answers a different question - and under virtualization
+it is not even the whole page.
+
+Source: `src/docs/summary-row.md` (Totalling a column).
+
+### MEDIUM Grouping a server-paged grid
+
+`manualPagination: true` turns grouping off: the client holds one page and would
+build groups out of an arbitrary slice. Group on the server and declare it.
+
+Correct:
+
+```tsx
+useTMDataGrid({
+  data: page.rows,
+  columns,
+  manualPagination: true,
+  manualGrouping: true,
+  enableGrouping: true,
+});
+```
+
+Source: `src/docs/grouping.md` (Server-side grids).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enableGrouping` | Table option | `boolean` | `true` | Group by and Ungroup menu items. Also a column option. |
+| `groupedColumnMode` | Table option | `"reorder" \| "remove" \| false` | `"remove"` | Whether a grouped column leaves the grid or moves to the front. |
+| `manualGrouping` | Table option | `boolean` | `false` | The rows arrive grouped. Required to group a server-paged grid. |
+| `initialState.grouping` | Table option | `string[]` | `[]` | Column ids grouped at mount. A settings slice, so it persists. |
+| `aggregationFn` | Column option | `TMDataGridAggregationName \| fn` | – | How a column fills in its group rows. Unset means blank. |
+| `aggregatedCell` | Column option | `(ctx) => ReactNode` | The `cell` renderer | Renders a group row's value differently. |
+| `footer` | Column option | `(ctx) => ReactNode` | – | Renders this column's summary cell, and summons the row. |
+| `aggregateColumn` | Export | `({ table, columnId, fn }) => unknown` | `fn: "sum"` | Aggregates over every filtered row, all pages. |
+| `TMDataGridAggregationName` | Export | type | – | The registered function names. |
+| `GROUP_COLUMN_ID` | Export | `"__group__"` | – | Id of the generated tree column. |
+| `formatGroupValue` | Export | `(value) => string` | – | How the tree lane renders a group's value. |
+| `getGroupDataRows` | Export | `(row) => Row[]` | – | Every record under a group row, at any depth. |
+| `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
+| `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |
+| `--dg-summary-height` | CSS variable | length | From `size` | Height of the summary row. |
+| `data-grouped` · `data-depth` | Data attributes | – | – | On group rows, and the nesting level on every row. |
+
+See also: the `rows` skill for selection and the details lane, and the `data`
+skill for the pager grouping suspends.

package/skills/options/SKILL.md

@@ -5,28 +5,29 @@ description: >
   of TanStack TableOptions, the default initialState (pagination, columnPinning,
   globalFilterFn), the meta object (loading, noResultsLabel, rowHeight,
   totalRowCount), the grid's own persist, enableColumnOrdering,
-  enablePagination, rowSelectionMode and highlightSelectedRows options, the
+  enablePagination, selectionMode and showSelectedBackground options, the
   persist option with dataKey/settingsKey slice selection and storageMode, the
-  returned table/ui/features triple, 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.
+  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.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.0'
+  library_version: '1.0.2'
 sources:
   - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
   - 'Jielga/TMDataGrid:src/tmdatagrid/core/persistence.ts'
 ---
 
-# TMDataGrid — useTMDataGrid
+# TMDataGrid - useTMDataGrid
 
 Creates the table instance and the state used by the grid interface.
 
 ```tsx
 const grid = useTMDataGrid<TData>(options);
-// { table, ui, features }
+// { table, ui, edit, features, labels, resetSettings, scrollToRow }
 ```
 
 Spread the result onto `TMDataGrid`.
@@ -38,18 +39,18 @@ 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`, `rowSelectionMode` and
-`highlightSelectedRows` are the grid's own options and are consumed by the hook
+`persist`, `enableColumnOrdering`, `enablePagination`, `selectionMode` and
+`showSelectedBackground` are the grid's own options and are consumed by the hook
 rather than forwarded to TanStack.
 
 | 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. |
+| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. Required once `editMode` is set. |
 | `enableRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes row selection and its checkbox column. |
-| `rowSelectionMode` | `"checkbox" \| "row"` | `"checkbox"` | `"row"` drops the checkbox column and selects on row click. Defined by the grid. |
-| `highlightSelectedRows` | `boolean` | Follows the mode | Highlight background on selected rows: off for `"checkbox"`, on for `"row"`. Colour is the `--dg-row-selected-bg` CSS variable. Defined by the grid. |
+| `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. |
@@ -64,12 +65,14 @@ rather than forwarded to TanStack.
 | `initialState` | `Partial<TableState>` | See below | Merged over the grid defaults. |
 | `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
 | `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
+| `editMode` | `"cell" \| "cellConfirm" \| "row" \| "batch"` | off | Turns editing on. Brings `rowValidators`, `isRowEditable`, `onEditCommit`, `onEditCommitBatch`, `newRowDefaults`, `onRowAdd` and `onRowDelete` with it - see the `editing` skill. |
+| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. |
 
 ### Default initial state
 
 | Slice | Default |
 | --- | --- |
-| `pagination` | `{ pageIndex: 0, pageSize: 25 }` — inert until pagination is enabled |
+| `pagination` | `{ pageIndex: 0, pageSize: 25 }` - inert until pagination is enabled |
 | `columnPinning.left` | The checkbox column, followed by any columns you provide |
 | `globalFilterFn` | `"includesString"` |
 
@@ -127,8 +130,12 @@ const persist = {
 
 | Group | Available slices |
 | --- | --- |
-| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination` |
-| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning` |
+| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
+
+`grouping` is a settings slice because it names columns rather than values, so it
+survives the data changing under it the way the column layout does. `expanded` is
+a data slice for the opposite reason.
 
 `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` export the same values. Slice
 names are typed per group, so only valid names are accepted.
@@ -136,7 +143,7 @@ names are typed per group, so only valid names are accepted.
 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. Only selected slices are read back, and unrecognised keys are ignored. All
-storage access is guarded — if storage is unavailable, disabled or full,
+storage access is guarded - if storage is unavailable, disabled or full,
 persistence is skipped rather than throwing.
 
 ## Return value
@@ -145,7 +152,11 @@ persistence is skipped rather than throwing.
 | --- | --- | --- |
 | `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
 | `ui` | `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
+| `edit` | `TMDataGridEditApi` | The edit engine, inert until `editMode` 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. |
+| `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:
@@ -180,7 +191,7 @@ 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`
+`ui.draggedColumnId` holds the column being moved - browsers keep `dataTransfer`
 unreadable until the drop.
 
 `openColumnFilter(grid, columnId)` combines the two steps the column menu uses:
@@ -190,11 +201,11 @@ add an empty filter row for the column if none exists, then open the panel.
 
 ### Reading store state during render
 
-`grid.table.store.state` is a plain read — it does not subscribe the component,
+`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.
 
 ```tsx
-// Wrong — never re-renders when the selection changes.
+// Wrong - never re-renders when the selection changes.
 const count = Object.keys(grid.table.store.state.rowSelection).length;
 
 // Right.
@@ -219,5 +230,5 @@ Include a tenant or user identifier in the key.
 ### Unstable data reference
 
 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
+allocates a fresh `[]` every render when `rows` is undefined - hoist the empty
 array to a module-scope constant or `useMemo` the expression.