@jielga/tmdatagrid 2.1.3 → 2.2.0

package/docs/cell-selection.md

@@ -180,7 +180,7 @@ Unlike the Export cells item, `resolveRangeBounds` does not fall back to the foc
 | `cellSelection` | Option | `"none" \| "single" \| "range"` | `"none"` | Turns the cell cursor, and the rectangle, on. |
 | `TMDataGridCellSelectionMode` | Type | – | – | The type of `cellSelection`. |
 | `onFocusedCellChange` | Callback | `(cell \| null) => void` | – | Follows the cursor. |
-| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row of the Export cells item. See [Export](/docs/export). |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | Format, file name and header row of the Export cells item. See [Export](/docs/export). |
 | `ui.state.focusedCell` | UI state | `{ rowId, columnId } \| null` | `null` | The cursor. |
 | `ui.state.cellRange` | UI state | `{ anchor, focus } \| null` | `null` | The rectangle's two corners. |
 | `ui.actions.setFocusedCell` · `setCellRange` | UI actions | – | – | Move either from your own code. |

package/docs/column-layout.md

@@ -14,7 +14,11 @@ hint: Drag a header to reorder · pin or hide from a column menu · drag a divid
 ## Hiding
 
 **Hide column** in any column menu, and the column chooser for the whole list at once: a search field, one checkbox per column, show/hide all, and **Reset layout**.
-The chooser is `TMDataGrid.Menu.Columns` in the [grid menu](/docs/menu), **Manage columns** in every column menu (a submenu of the same items), and `TMDataGrid.ColumnsPanel` as plain controls for a host that is not a menu.
+The chooser comes in three forms:
+
+- `TMDataGrid.Menu.Columns` in the [grid menu](/docs/menu).
+- **Manage columns**, a submenu of every column menu with the same items.
+- `TMDataGrid.ColumnsPanel`, plain controls for a host that is not a menu.
 
 `enableHiding: false` removes all of it; on a column it removes that column's
 menu item and leaves it out of the panel, which lists what can be hidden and
@@ -42,8 +46,8 @@ computed from an `fr` value. The grid writes the column's rendered width into
 To start pinned, set `initialState.columnPinning`. The slice is TanStack's
 full `ColumnPinningState`, so a partial does not compile - name both sides.
 A column pinned at mount has no rendered width to store, so it takes its
-`size` - TanStack's default of `150` where none is set - and `minSize` does
-not apply. Give such a column an explicit `size`:
+`size`, clamped between `minSize` and `maxSize`; with none of them set that is
+TanStack's default of `150`. Give such a column an explicit `size`:
 
 ```tsx
 columnHelper.accessor("registration", { header: "Registration", size: 220 });
@@ -114,10 +118,11 @@ Columns are fluid by default. Each track is `minmax(minSize, flex fr)`.
 
 | Column option | Effect |
 | --- | --- |
-| `minSize` | Minimum width, and the column's contribution to the grid minimum width. Defaults to `80`. |
+| `minSize` | Minimum width, and the column's contribution to the grid minimum width. Also the floor of a resize and of a pinned width. Defaults to `80`, through `defaultColumn.minSize`. |
+| `maxSize` | Ceiling of a resize, an autosize and a pinned width. Does not cap a fluid track. No default. |
 | `meta.flex` | Share of the remaining width. Defaults to `1`. |
 | `minSize === maxSize` | Fixed width. The column is never fluid. |
-| `size` | Applied once the column becomes fixed by resizing or pinning. |
+| `size` | Width of a column pinned at mount, clamped by `minSize` and `maxSize`. Ignored on a fluid column; a resize or an interactive pin stores the rendered width instead. Defaults to `150`. |
 
 Drag a divider to resize. A column switches to a fixed pixel width the moment
 it is resized or pinned, and the width is stored in `columnSizing`. The drag
@@ -148,8 +153,8 @@ the column's cells.
 
 ## Reset the layout
 
-`resetSettings()` from the hook clears visibility, order, pinning and widths in
-one call. The columns panel offers it as **Reset layout**.
+`resetSettings()` from the hook clears visibility, order, pinning, widths and
+grouping in one call. The columns panel offers it as **Reset layout**.
 
 ```tsx
 const { resetSettings } = useTMDataGrid({ data, columns });
@@ -169,7 +174,7 @@ const { resetSettings } = useTMDataGrid({ data, columns });
 | `meta.flex` | Column meta | `number` | `1` | Share of the remaining width. |
 | `meta.autoSize` | Column meta | `boolean` | `false` | Autosize once, on the render the column's first cells appear in. |
 | `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / – | Width bounds, and the fixed width once one applies. |
-| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning and widths. |
+| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning, widths and grouping. |
 | `moveColumn` | Export | `({ table, columnId, targetId, side }) => void` | – | Moves a column beside another. |
 | `moveColumnByStep` | Export | `({ table, columnId, direction }) => void` | – | Moves it one place. |
 | `MoveColumnArgs` · `ColumnStepArgs` | Types | – | – | What `moveColumn` takes, and what `moveColumnByStep` and `getStepTargetColumn` take. |

package/docs/columns.md

@@ -88,6 +88,7 @@ Its type is `TMDataGridColumnMeta`.
 | `options` | `TMDataGridOptionsSource` | - | The choices of a `select` / `multiSelect` column. See [Options](#options). |
 | `flex` | `number` | `1` | Share of the remaining width. |
 | `align` | `"left" \| "right" \| "center"` | `"left"` | Alignment, applied to both header and cells. |
+| `colSpan` | `number \| ({ row, table }) => number` | `1` | Columns the cell covers on a row, counting itself. See [Spanning columns](#spanning-columns). |
 | `autoSize` | `boolean` | `false` | Fit the column to its content once, on the render its first cells appear in. |
 | `enableOrdering` | `boolean` | `true` | `false` keeps the column where it is. |
 | `filter` | `TMDataGridColumnFilterOptions` | - | How this column filters. See [meta.filter](#metafilter). |
@@ -185,6 +186,57 @@ A select column that declares no options still filters: the panel falls back to
 the faceted values. Mantine's dropdowns are not virtualized, so use the function
 form for very large sets.
 
+## Spanning columns
+
+`meta.colSpan` makes a column's cell cover the columns to its right.
+A cell spanning `n` is one cell `n` columns wide, with one background and one
+border, and the `n - 1` cells it covers do not render on that row.
+A function decides per row:
+
+```tsx
+columnHelper.accessor("name", {
+  header: "Name",
+  meta: {
+    colSpan: ({ row }) => (row.getIsExpanded() ? Infinity : 1),
+  },
+});
+```
+
+```demo
+file: columns/SpanningCells.tsx
+hint: Open a row with its chevron - its name takes the rest of the row, and the panel opens below.
+```
+
+- The span is counted over the displayed columns. Hiding or moving a column
+  changes what a span covers, so `Infinity` - "to the last of my columns" - is
+  usually safer than a count.
+- A span stops at the last of your columns. It never covers the checkbox,
+  tree, details or edit lane.
+- A span stops at the edge of its pinned block.
+- A column covered by a span ignores its own `colSpan` on that row.
+- Group rows ignore `colSpan`, and so does a row open in
+  [row edit mode](/docs/editing), where every column holds an editor.
+- Sorting, filtering, copy and export still see every column. Autosize leaves
+  a spanning cell out of its column's measurement, and a column whose every
+  mounted cell spans fits its header.
+- Under [cell selection](/docs/cell-selection) the spanning cell is one cell:
+  the arrow keys step over it, and a move onto a column it covers lands on it.
+  It is addressed by its first column: a range holds it when it holds that
+  column, and a range over only the columns it covers leaves it out. Copy and
+  export take every column of the range either way. When the column the focus
+  is on becomes covered, the focus moves to the spanning cell.
+- Under [cell editing](/docs/editing) a covered column has no cell to open,
+  and Tab from the spanning cell's editor moves past the columns it covers.
+  A row keeps its cells while an editor is open in a column a span would
+  cover, and the span lands when the edit ends.
+
+A cell renderer that reads `row.getIsExpanded()`, as the demo's does, has to
+subscribe to the store - see
+[Opening a row from elsewhere](/docs/row-details#opening-a-row-from-elsewhere).
+
+The cell carries `aria-colspan` and `data-col-span` with the number of columns
+it covers.
+
 ## Header groups
 
 `columnHelper.group` nests columns under a shared header. The group is a header
@@ -231,8 +283,9 @@ Sizing, pinning, ordering and visibility are covered on
 ## The generated columns
 
 Five lanes the grid adds when a feature needs them. All are **system lanes**:
-fixed width, no column menu, no resize handle, never exported, never hidden and
-never listed in the columns panel.
+pinned, with no column menu, never exported and never listed in the columns
+panel. Four of them are fixed width with no resize handle; the tree lane can be
+resized, and it is shown only while a grouping is active.
 
 | Id | Appears when | Where |
 | --- | --- | --- |
@@ -259,6 +312,8 @@ column can be placed in front of it.
 | `meta.options` | Column meta | array \| `"faceted"` \| `(args) => …` | – | The choices of an option column. |
 | `TMDataGridOptionsArgs` | Type | – | – | What a `meta.options` function receives: `{ table, column, row? }`. `row` is absent when the filter panel asks. |
 | `meta.align` | Column meta | `"left" \| "right" \| "center"` | `"left"` | Header and cell alignment. |
+| `meta.colSpan` | Column meta | `number \| (args) => number` | `1` | Columns the cell covers on a row. See [Spanning columns](#spanning-columns). |
+| `TMDataGridColSpanArgs` | Type | `{ row, table }` | – | What a `meta.colSpan` function receives. |
 | `meta.filter` | Column meta | `TMDataGridColumnFilterOptions` | – | How the column filters: `defaultOperator`, `control`. |
 | `meta.edit` | Column meta | `TMDataGridColumnEditOptions` | – | How the column edits: `enabled`, `field`, `editor`, `validate`, `mapValue`. |
 | `resolveColumnOptions` | Export | `({ table, column, row? }) => options` | – | Normalises all three `meta.options` forms. |

package/docs/export.md

@@ -80,7 +80,7 @@ const grid = useTMDataGrid({
 | `includeHeaders` | `boolean` | `true` | Determines whether the column labels are written as the first row. |
 | `columns` | `"visible" \| "all" \| Array<string>` | `"visible"` | Which columns are written. See [What is written](#what-is-written). |
 
-The option is read field by field, so a literal is fine.
+The option is read field by field, so an inline object literal needs no `useMemo`.
 Every export of the grid reads it: the menu items, the hook, and the export item of the cell-range menu.
 
 ## Formats
@@ -290,7 +290,7 @@ See [Testing](/docs/testing).
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row for every export of the grid. |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | Format, file name and header row for every export of the grid. |
 | `meta.enableExport` | Column meta | `boolean` | `true` | `false` leaves the column out of every export and of Ctrl+C. |
 | `meta.exportValue` | Column meta | `({ value, row, column }) => unknown` | – | The value written in place of `row.getValue`. |
 | `TMDataGridExportValueGetter` | Type | – | – | The type of `meta.exportValue`. |

package/docs/filtering.md

@@ -32,8 +32,8 @@ array only under `isAnyOf` / `isNoneOf` (the set the cell is tested against) and
 
 A filter with an empty value stays in state, so a panel row survives while the
 user types. (A header filter control has no row to keep alive and drops its
-entry instead - see [inHeader](#inheader).) It matches every row, does not set the header's filter
-indicator, and produces no pill. `isFilterActive(value)` tests for that
+entry instead - see [inHeader](#inheader).) The built-in matcher lets every row through, and
+the filter does not set the header's filter indicator and produces no pill. `isFilterActive(value)` tests for that
 state, and `activeColumnFilters` applies it across the whole slice, handing
 back the entries that narrow the grid with their values typed as
 `TMDataGridFilterValue` rather than as `unknown`. Entries in any other value
@@ -117,7 +117,7 @@ useTMDataGrid({ data, columns, filters: { surface: "sidebar", inHeader: true } }
 `surface` and `inHeader` are two separate choices, not one list: `inHeader` composes with all three surfaces.
 `{ surface: "none", inHeader: true }` is header filters and nothing else; `{ inHeader: true }` keeps the popup as well, for the multi-column work a header row has no room for.
 
-The option is read field by field, so a literal is fine - unlike `labels` and `persist`, it does not have to be referentially stable.
+The option is read field by field, so an inline object literal needs no `useMemo` - unlike `labels` and `persist`, it does not have to be referentially stable.
 
 ### surface: "popup"
 
@@ -132,7 +132,7 @@ Closing only hides the popup; the filters stay.
 The same panel beside the rows, inside the grid frame and under the toolbar.
 It is a column of the frame rather than a layer over it: the rows give up the width instead of being covered, a click in the table does not dismiss it, and clearing the filters leaves it standing with its **Add filter** button.
 Escape closes it.
-It starts open (`defaultOpen` defaults to `true` here) and renders the panel with `layout="stacked"`, because 280px has no room for the side-by-side triple.
+It starts open (`defaultOpen` defaults to `true` here) and renders the panel with `layout="stacked"`, because the default 280px cannot fit the column, operator and value fields side by side.
 
 ```demo
 file: columns/FilterSidebar.tsx
@@ -182,7 +182,7 @@ No props.
 
 The panel of filter rows - one column / operator / value triple per filter, over an "Add filter" / "Clear all" footer.
 It is a plain block with no title, no close button and no open state: it renders wherever it is mounted, and the popup and sidebar surfaces are wrappers around it.
-It must be inside `<TMDataGrid>`, since it reads the grid from context, and it only reads and writes the table's `columnFilters` state, so a `manualFiltering` grid gets the same panel for free.
+It must be inside `<TMDataGrid>`, since it reads the grid from context, and it only reads and writes the table's `columnFilters` state, so the same panel works unchanged under `manualFiltering`.
 
 Pair it with `surface: "none"` so it is the only panel on the page, and drive it off `ui.state.filterPanelOpen` if it belongs behind a control of your own - `defaultOpen` sets where that state starts.
 
@@ -302,8 +302,8 @@ const SalaryFilter: TMDataGridFilterControlComponent = ({ layout, ...rest }) =>
   layout === "header" ? <NumberInput {...} /> : <RangeSlider {...} />;
 ```
 
-A control that ignores `layout` still works - it will simply look the same
-everywhere, which is fine until it has to fit a header cell. Every built-in
+A control that ignores `layout` still works and looks the same in every
+surface, including a header cell, where the room is smallest. Every built-in
 control honours it.
 
 ```demo
@@ -311,24 +311,111 @@ file: columns/CustomFilterControl.tsx
 hint: Open the filter panel - Status offers chips, every other column the built-in control.
 ```
 
+## Writing filters from your own interface
+
+The grid's controls write plain TanStack state, so a control of your own does
+the same. Write an envelope with `column.setFilterValue` or
+`table.setColumnFilters`; the matcher, the pills, the header indicator and
+`activeColumnFilters` all read it:
+
+```tsx
+import { emptyValueForOperator, type TMDataGridFilterValue } from "@jielga/tmdatagrid";
+
+const status = grid.table.getColumn("status")!;
+
+// A set filter, as the panel would write it.
+status.setFilterValue({
+  operator: "isAnyOf",
+  value: ["active", "paused"],
+} satisfies TMDataGridFilterValue);
+
+// An empty envelope stays in state and matches every row.
+status.setFilterValue({ operator: "isAnyOf", value: emptyValueForOperator("isAnyOf") });
+
+// `undefined` removes the entry.
+status.setFilterValue(undefined);
+```
+
+`getColumnOperators(column)` returns the operators a column offers and
+`getColumnDefaultOperator(column)` the one a fresh filter opens on;
+`emptyValueForOperator(operator)` returns the empty value of the right shape.
+
+To keep the grid's panel and place it yourself, set `filters: { surface: "none" }`
+and render [TMDataGrid.FilterPanel](#tmdatagridfilterpanel) where it belongs.
+To keep filtering on and drop only the column menu's Filter item, pass
+`renderColumnMenuItems` to `TMDataGrid.Table` and leave out the item keyed
+`"filter"` (see [Column menu](/docs/column-menu)). To replace every filter
+control, set `enableColumnFilters: false` and write the envelope yourself;
+filters in state still apply.
+
 ## Custom matching
 
 To give a column its own matching logic instead of its own control, set
-`filterFn` on the column definition. The grid provides only `"tmDataGrid"`,
-which is the default.
+`filterFn` on the column definition. A column `filterFn` replaces the shared
+matcher for that column, so its third argument is the stored
+`{ operator, value }` envelope, not the unwrapped value. Type it as
+`TMDataGridFilterFn<TData>` and delegate to `tmDataGridFilterFn` for the
+operators it does not handle itself. A column `filterFn` is also called with
+half-typed envelopes, which the built-in matcher treats as matching every row,
+so return `true` for `!isFilterActive(filter)` first:
+
+```ts
+import {
+  isFilterActive,
+  tmDataGridFilterFn,
+  type TMDataGridFilterFn,
+} from "@jielga/tmdatagrid";
+
+// Reads "contains" as "has this tag", so "ops" matches the tag "ops" and not
+// "devops"; every other operator keeps the built-in matching.
+const matchesTags: TMDataGridFilterFn<Employee> = (row, columnId, filter) => {
+  if (!isFilterActive(filter)) return true;
+  if (filter.operator === "contains") {
+    const wanted = String(filter.value).toLowerCase();
+    return row.original.tags.some((tag) => tag.toLowerCase() === wanted);
+  }
+  return tmDataGridFilterFn(row, columnId, filter);
+};
+
+columnHelper.accessor((row) => row.tags.join(", "), {
+  id: "tags",
+  header: "Tags",
+  filterFn: matchesTags,
+  meta: { type: "string" },
+});
+```
+
+`filter.value` is a string under the scalar operators, a `ReadonlyArray<string>`
+under `isAnyOf` / `isNoneOf` and a `[min, max]` pair under `between`;
+`filterValueShape(operator)` tells which. `matchesFilter(cellValue, filter)`
+applies the built-in matching to a value derived by the function itself.
+
+The column's filter controls do not change: the operators still come from
+`meta.type` and `meta.filter.operators`, and the panel, the pills and the header
+indicator keep reading the envelope. A filter function named by string also
+receives the envelope and does not unwrap it, so TanStack's built-ins such as
+`"includesString"` do not work as a column `filterFn`. Write custom matching as
+a function.
 
 ## Turning it off
 
-`enableColumnFilters: false` removes the filter menu item, the `FilterButton`,
-the panel and the header filter row. `enableColumnFilter: false` on a column
-removes that column's menu item, its entry in the panel's column list and its
-header control - the header cell stays, empty.
+`enableColumnFilters: false` removes the Filter item from the column menu, the
+`FilterButton`, the header filter row and the panel's column list, and disables
+the panel's "Add filter" button. It does not clear `columnFilters`: an entry already in
+state, or one written with `setFilterValue`, still narrows the rows, still shows
+as a pill and still sets the header indicator. Call `table.resetColumnFilters()`
+when switching the interface off. Under `filters.surface: "sidebar"`, set
+`surface: "none"` as well, as the sidebar does not follow the switch.
+
+`enableColumnFilter: false` on a column removes that column's menu item, its
+entry in the panel's column list and its header control - the header cell
+stays, empty.
 
 ## Reference
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button, the header row and the menu item. |
+| `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the menu item, the button, the header row and the panel's column list, and disables the panel's "Add filter" button. Filters already in state still apply. |
 | `filters.surface` | Table option | `"popup" \| "sidebar" \| "none"` | `"popup"` | Which surface the table renders. |
 | `filters.sidebarSide` | Table option | `"left" \| "right"` | `"right"` | Which side the sidebar sits on. |
 | `filters.sidebarWidth` | Table option | `string` | `"280px"` | Width of the sidebar. |
@@ -339,7 +426,10 @@ header control - the header cell stays, empty.
 | `meta.filter.operators` | Column meta | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. |
 | `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. |
-| `filterFn` | Column option | name \| fn | `"tmDataGrid"` | Custom matching for one column. |
+| `filterFn` | Column option | `TMDataGridFilterFn<TData>` \| name | `"tmDataGrid"` | Custom matching for one column. Receives the `{ operator, value }` envelope. |
+| `TMDataGridFilterFn<TData>` | Type | `(row, columnId, filter: TMDataGridFilterValue, addMeta?) => boolean` | – | The signature of a column's own `filterFn`. |
+| `tmDataGridFilterFn` | Export | `(row, columnId, filterValue: unknown) => boolean`, assignable to `TMDataGridFilterFn<TData>` | – | The shared matcher, for a custom `filterFn` to delegate to. |
+| `matchesFilter` | Export | `(cellValue, filter: TMDataGridFilterValue) => boolean` | – | The built-in matching applied to one value. |
 | `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"` | `"row"` | The panel of filter rows, as a plain block. |
 | `TMDataGrid.FilterButton` | Component | – | – | Toolbar button toggling the surface, with an active count. Seeds a filter row only when the panel is empty. |
 | `TMDataGrid.FilterPills` | Component | takes `api` | – | Active filters as removable pills, renderable anywhere. |

package/docs/getting-started.md

@@ -112,6 +112,46 @@ file: getting-started/ToolbarAndFooter.tsx
 [Grid anatomy](/docs/anatomy) for what each part is, and
 [Toolbar](/docs/toolbar) for adding your own buttons among them.
 
+## Coming from TanStack Table
+
+`useTMDataGrid` takes TanStack's `TableOptions`, so a page built on
+`useReactTable` keeps its `data`, `columns`, `state` and `onXChange` callbacks.
+Go through these differences:
+
+- **`getRowId`** - return the entity id. The index default points at another
+  record after a sort or a refetch, which breaks selection, expansion and
+  editing. Required once `editing` is set.
+- **Stable `data` and `columns`** - define `columns` outside the component and
+  keep `data` referentially stable; a fresh `[]` for the empty case belongs in
+  a module-scope constant. Under `editing`, a transient `[]` drops every open
+  draft.
+- **Sizing** - columns are fluid, `minmax(minSize, flex fr)`. `size` applies
+  only to a column pinned at mount, `maxSize` only to resizing and autosizing,
+  and `minSize` defaults to `80`. See
+  [Visibility, pinning, ordering and size](/docs/column-layout#sizing).
+- **Defaults the grid changes** - `aggregationFn` is cleared, so grouping does
+  not sum anything on its own; `groupedColumnMode` is `"remove"`;
+  `autoResetExpanded` and `autoResetPageIndex` are off; `globalFilterFn` is the
+  fuzzy matcher. The full list is on
+  [useTMDataGrid](/docs/use-tm-data-grid#options).
+- **Filters are envelopes** - `columnFilters` holds `{ operator, value }`, and
+  a column's own `filterFn` receives that envelope. See
+  [Filtering](/docs/filtering#custom-matching).
+- **Interface the page already owns** - `enableGlobalFilter: false`, or no
+  `TMDataGrid.Search`, for the search; `enableColumnFilters: false`, or
+  `filters: { surface: "none" }` to keep filtering without the grid's panel.
+  See [Filtering](/docs/filtering#turning-it-off).
+- **Page reset** - `resetPageOnQueryChange` (default `true`) returns to the
+  first page when a filter, the search, the sorting or the grouping changes
+  through the table. A data source re-filtered outside table state does not
+  trigger it; call `table.setPageIndex(0)` yourself, or use `manualFiltering`.
+  See [Server-side data](/docs/server-side).
+- **State reads** - there is no `table.getState()`; read slices with
+  `useSelector(table.store, ...)`. See
+  [useTMDataGrid](/docs/use-tm-data-grid#reading-state).
+- **Tests** - the grid publishes `data-dg-part`, `data-row-id` and
+  `data-column-id`, and no `data-testid`. See [Testing](/docs/testing).
+
 ## Where to go next
 
 - **[Defining columns](/docs/columns)** - accessors, `meta.type`, and what each

package/docs/grouping.md

@@ -100,8 +100,8 @@ records inside collapsed sub-groups. It shows a tick once all of them are
 selected and a dash while only some are.
 
 Only the records are written to `rowSelection`. A group row is never in it, so
-`getSelectedRowModel()` and the toolbar count do not depend on how the tree is
-arranged.
+`getSelectedRowModel()` and `onRowSelectionChange` do not depend on how the tree
+is arranged.
 
 Under `enableMultiRowSelection: false` group rows carry no checkbox.
 
@@ -125,8 +125,11 @@ While 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.
 
-To page a grouped grid, group and page on the server: feed the grid one page of
-a tree at a time with `manualPagination` and `manualGrouping`.
+There is no option to keep the built-in pager active while grouped, and
+`manualGrouping` does not change that: the pager greys out whenever `grouping`
+is non-empty. To page a grouped grid, group and page on the server with
+`manualPagination` and `manualGrouping`, and render the pager through
+`renderPagination`, ignoring `isPagingActive`.
 
 `isPagingActive(table, features)` is exported, so a custom pager can grey itself
 out the same way:
@@ -150,12 +153,12 @@ server-side can set `enableGrouping: true` alongside `manualGrouping: true`. See
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `enableGrouping` | Table option | `boolean` | `true` | Group by and Ungroup menu items. Also a column option. |
+| `enableGrouping` | Table option | `boolean` | `true`; `false` under `manualPagination` | Group by and Ungroup menu items, and the tree lane. 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 to group on at mount. A settings slice, so it persists. |
 | `aggregationFn` | Column option | `TMDataGridAggregationName \| fn` | – | How a column fills in its group cells. Unset leaves them blank. |
-| `aggregatedCell` | Column option | `(ctx) => ReactNode` | The `cell` renderer | Renders a group row's value differently from a data row's. |
+| `aggregatedCell` | Column option | `(ctx) => ReactNode` | `cell` over the aggregate when `aggregationFn` is set, else blank | Renders a group row's value differently from a data row's. |
 | `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. |

package/docs/loading-and-empty.md

@@ -1,6 +1,6 @@
 # Loading and empty states
 
-A grid can have nothing to show for four different reasons, and the body says
+A grid can have nothing to show for five different reasons, and the body says
 which one it is: still fetching, emptied by a filter, or holding no data.
 
 ```demo
@@ -18,9 +18,29 @@ An empty body shows exactly one thing, decided in this order:
 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").
+4. **Filtered-empty** - a column filter is active (`isFilterActive`) or the
+   quick search is not blank: a search icon and `labels.noResults` ("No rows
+   match your filters").
+5. **Truly-empty** - no column filter is active and the quick search is blank:
+   `labels.noRows` ("No rows to show").
+
+"Empty" means no displayed row and no pinned row: the current page under
+pagination, otherwise every filtered row. States 4 and 5 are decided by the
+filter state alone, so an empty `data` array shows `noResults` while a filter is
+active. A half-typed filter, such as `{ operator: "contains", value: "" }`, is
+not active, so it does not count.
+
+## While data loads
+
+The loader shows only while `meta.loading` is `true` and the view is empty. It
+is the only "no data yet" signal the grid has, so set `meta.loading` during the
+first fetch as well; without it the empty message shows until the rows arrive.
+
+`renderEmptyState` is called only once `meta.loading` is not `true`. During a
+refetch that returns no rows, the loader mounts when `loading` turns `true`,
+`renderEmptyState` mounts when it turns `false`, and it unmounts again on the
+next refetch; the two branches never render together. Rows on screen stay on
+screen until `data` changes, whatever `loading` says.
 
 ## Replacing the message
 
@@ -70,8 +90,8 @@ typically after `Spacer`.
 
 `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.
+otherwise. A [server-side](/docs/server-side) grid holds one page, so without
+`meta.totalRowCount` it shows the shown count alone, with no total.
 
 ```tsx
 <TMDataGrid.SummaryCount>
@@ -83,10 +103,10 @@ client only holds one page.
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |
+| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. While `true` and the view is empty, the loader replaces every empty message and `renderEmptyState` is not called. |
 | `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. |
+| `meta.totalRowCount` | Option | `number` | Pre-filtered count; none on a server-driven grid | The total `SummaryCount` reports. |
+| `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. `hasActiveFilters` is `true` when a column filter is active (`isFilterActive`) or the quick search is not blank. |
 | `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). |