@jielga/tmdatagrid 2.1.4 → 2.3.0

package/skills/filtering/SKILL.md

@@ -4,21 +4,21 @@ description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
   meta.type offers each, meta.filter.operators to offer a column only a subset
-  of them, meta.filter.defaultOperator, isFilterActive and the half-typed
-  filter, the filters option and its surfaces (popup, sidebar, none, plus
-  inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
-  TMDataGrid.FilterButton, TMDataGrid.FilterPills with its api prop,
-  openColumnFilter, replacing a value control with DgRangeSliderFilter /
-  DgDateRangeFilter / DgAutocompleteFilter / DgTriStateFilter or a
-  meta.filter.control component, per-column filterFn, and the quick search:
-  TMDataGrid.Search, quickSearchMode fuzzy or contains, fuzzyGlobalFilterFn,
-  enableMatchHighlighting and enableGlobalFilter. Load when adding filters,
-  choosing operators, building a filter control, showing active filters outside
-  the grid, or wiring a search box.
+  of them, meta.filter.defaultOperator, meta.filter.url for deep links,
+  isFilterActive and the half-typed filter, the filters option and its surfaces
+  (popup, sidebar, none, plus inHeader for header filters),
+  TMDataGrid.FilterPanel and its layout prop, TMDataGrid.FilterButton,
+  TMDataGrid.FilterPills with its api prop, openColumnFilter, replacing a value
+  control with DgRangeSliderFilter / DgDateRangeFilter / DgAutocompleteFilter /
+  DgTriStateFilter or a meta.filter.control component, per-column filterFn, and
+  the quick search: TMDataGrid.Search, quickSearchMode fuzzy or contains,
+  fuzzyGlobalFilterFn, enableMatchHighlighting and enableGlobalFilter. Load when
+  adding filters, choosing operators, building a filter control, showing active
+  filters outside the grid, or wiring a search box.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/react:packages/tmdatagrid/docs/quick-search.md'
@@ -50,11 +50,12 @@ cell is tested against) and `between` (a `[min, max]` pair, an empty string
 leaving that end open).
 
 A filter with an empty value **stays in state** so the panel keeps its row while
-the user types. It matches every row, does not set the header indicator and
-produces no pill. `isFilterActive(value)` tests for that state, and
-`activeColumnFilters(columnFilters | table)` applies it across the slice and
-types what it hands back (entries in any other value shape are dropped); presence in
-`columnFilters` does not.
+the user types. The built-in matcher lets every row through, and the filter
+does not set the header indicator and produces no pill.
+`isFilterActive(value)` tells whether a value narrows anything.
+`activeColumnFilters(columnFilters | table)` returns the active entries, typed,
+and drops entries in any other value shape. An entry in `columnFilters` is not
+necessarily active.
 
 ## Operators
 
@@ -104,10 +105,22 @@ columnHelper.accessor("customer", {
 `getColumnDefaultOperator(column)` the operator a fresh filter opens on. The
 `server-side` skill shows the list typed together with the API mapping table.
 
+`meta.filter.url` determines whether the column's filter goes into the URL
+search param when `persist.urlKey` carries `columnFilters`. By default it does.
+Set it to `false` for a filter that should not travel in a shared link; the
+filter is then not persisted anywhere. The `options` skill covers `urlKey`.
+
+```tsx
+columnHelper.accessor("owner", {
+  header: "Owner",
+  meta: { filter: { url: false } },
+});
+```
+
 ## The filters option
 
-`filters` on `useTMDataGrid` picks the surface. It is read field by field, so a
-literal is fine.
+`filters` on `useTMDataGrid` picks the surface. It is read field by field, so an
+inline object literal needs no `useMemo`.
 
 | Option | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -132,13 +145,14 @@ close it; `FilterButton` is exempt from the click-away so it stays a toggle.
 the toolbar. The rows give up the width rather than being covered, a click in
 the table does not dismiss it, and clearing the filters leaves it standing.
 Escape closes it. It starts open, being a layout choice; its rows are
-`layout="stacked"`, since 280px has no room for the triple.
+`layout="stacked"`, since the default 280px cannot fit the column, operator and
+value fields side by side.
 
 **Header filters** - `inHeader: true` adds a header row of value controls, one
 per filterable column, on the same column tracks as everything else. The
 column and operator dropdowns are not there: the column is the one the cell
-sits over, and the operator is a funnel button beside the input, tinted off its
-default. The column menu's Filter item and the funnel indicator both come off,
+sits over, and the operator is a funnel button beside the input, tinted when
+the operator is not the type's default. The column menu's Filter item and the funnel indicator both come off,
 having nothing left to reveal; the filtered column's tinted title stays. A
 narrow column clips its control - give it a `minSize`.
 
@@ -158,7 +172,7 @@ hand-placed `TMDataGrid.FilterPanel` is the only one. Read
 
 The panel of filter rows - one column / operator / value triple per filter, over "Add filter" and "Clear all".
 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>` (it reads the grid from context) and it only reads and writes `columnFilters`, so a `manualFiltering` grid gets it for free.
+It must be inside `<TMDataGrid>` (it reads the grid from context) and it only reads and writes `columnFilters`, so it works unchanged under `manualFiltering`.
 Closing a surface only hides it; the filters stay.
 **Clear all** drops every filter, half-typed ones included.
 
@@ -201,7 +215,8 @@ import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
 
 ## openColumnFilter
 
-`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row - or, under `inHeader`, scrolls the column's header control into view and focuses it, leaving the surface closed.
+`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row.
+Under `inHeader` it instead scrolls the column's header control into view and focuses it, leaving the surface closed.
 It is what a pill's label and the column menu's Filter item both call.
 
 ## Replacing the value control
@@ -232,41 +247,47 @@ the same way.
 inside. It handles the value only: it reads `operator` to shape itself and
 writes the bare value through `onChange`, and the grid stores the
 `{ operator, value }` pair around it. The column and operator dropdowns remain
-the panel's.
-
-```tsx
-import type { TMDataGridFilterControlComponent } from "@jielga/tmdatagrid";
-
-// Module scope: a new identity per render remounts the control mid-typing.
-const StatusFilter: TMDataGridFilterControlComponent = ({
-  operator,
-  value,
-  options,
-  onChange,
-}) => (
-  <Chip.Group
-    multiple
-    value={Array.isArray(value) ? [...value] : []}
-    onChange={onChange}
-  >
-    {options.map((option) => (
-      <Chip key={option.value} value={option.value}>
-        {option.label}
-      </Chip>
-    ))}
-  </Chip.Group>
-);
-
-meta: { type: "select", filter: { control: StatusFilter } }
-```
+the panel's. Worked example: `references/custom-filters.md` (A value control of
+your own).
 
 `args.options` arrives pre-resolved for a column that declares `meta.options` or
 is select-shaped. `args.table` is available to a control that needs more than
 that.
 
+## Writing filters from your own interface
+
+The grid's controls write plain TanStack state, so a control of your own does
+the same: `column.setFilterValue({ operator, value })` or
+`table.setColumnFilters([...])` with an envelope, and the matcher, the pills,
+the header indicator and `activeColumnFilters` all read it.
+`setFilterValue(undefined)` removes the entry; an empty envelope stays in state
+and matches every row. `getColumnOperators(column)`,
+`getColumnDefaultOperator(column)` and `emptyValueForOperator(operator)` build
+a valid envelope. To keep the grid's panel and place it yourself, set
+`filters: { surface: "none" }` and render `TMDataGrid.FilterPanel`. To drop
+only the column menu's Filter item, pass `renderColumnMenuItems` to
+`TMDataGrid.Table` and leave out the item keyed `"filter"`. To replace every
+filter control, set `enableColumnFilters: false` and write the envelope
+yourself; filters in state still apply. Worked examples:
+`references/custom-filters.md`.
+
+## Custom matching
+
 To give a column its own *matching* instead of its own control, set `filterFn`
-on the column definition. The grid provides only `"tmDataGrid"`, which is the
-default.
+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(row, columnId, filter)` for the operators it
+does not handle; `matchesFilter(cellValue, filter)` applies the built-in
+matching to a derived value, and `filterValueShape(operator)` tells whether
+`value` is a string, a `ReadonlyArray<string>` (`isAnyOf` / `isNoneOf`) or a
+`[min, max]` pair (`between`). 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. The column's controls do
+not change and 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. Worked example: `references/custom-filters.md`.
 
 ## Quick search
 
@@ -298,10 +319,20 @@ excluded.
 
 ## Turning it off
 
-`enableColumnFilters: false` removes the panel, the button and the menu item;
-`enableColumnFilter: false` on a column takes that column out.
-`enableGlobalFilter: false` removes the search input, or on a column removes its
-participation in the search. The generated lanes are already excluded.
+`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.
+`TMDataGrid.Menu` has no filter items, so the switch changes nothing there.
+
+`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. `enableGlobalFilter: false` removes the search input, or on a
+column removes its participation in the search. The generated lanes are already
+excluded.
 
 ## Common mistakes
 
@@ -417,17 +448,20 @@ Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button 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. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
 | `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. Module scope. |
-| `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
+| `filterFn` | Column option | `TMDataGridFilterFn<TData>` or 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. |
 | `quickSearchMode` | Option | `TMDataGridQuickSearchMode`: `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |
 | `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. Removes the input, or one column's participation. |
-| `globalFilterFn` | Table option | filter fn | fuzzy | Overrides the matching, and the ranking with it. |
+| `globalFilterFn` | Table option | filter fn or name | `"tmDataGridFuzzy"`; `"includesString"` under `quickSearchMode: "contains"` | Overrides the matching, and the ranking with it. |
 | `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"`, Mantine `BoxProps` | `"row"` | The panel of filter rows, as a plain block. Style props set on it. |
 | `TMDataGridFilterPanelProps` · `TMDataGridFilterPanelLayout` | Types | – · `"row" \| "stacked"` | – | The props of `TMDataGrid.FilterPanel`, and the type of its `layout`. For wrapping the panel in a component of your own. |
 | `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |

package/skills/filtering/references/custom-filters.md

@@ -0,0 +1,118 @@
+# Custom filters
+
+Worked examples for the three ways to take over part of TMDataGrid's filtering: a value control of your own, writing the filter state from an interface of your own, and matching a column with a function of your own.
+All three keep the `{ operator, value }` envelope, so the panel, the pills, the header indicator and `activeColumnFilters` keep working.
+
+## A value control of your own
+
+`meta.filter.control` is a component that handles the value only: it reads `operator` to shape itself and writes the bare value through `onChange`.
+
+```tsx
+import type { TMDataGridFilterControlComponent } from "@jielga/tmdatagrid";
+
+// Module scope: a new identity per render remounts the control mid-typing.
+const StatusFilter: TMDataGridFilterControlComponent = ({
+  operator,
+  value,
+  options,
+  onChange,
+}) => (
+  <Chip.Group
+    multiple
+    value={Array.isArray(value) ? [...value] : []}
+    onChange={onChange}
+  >
+    {options.map((option) => (
+      <Chip key={option.value} value={option.value}>
+        {option.label}
+      </Chip>
+    ))}
+  </Chip.Group>
+);
+
+meta: { type: "select", filter: { control: StatusFilter } }
+```
+
+## Writing filters from your own interface
+
+The grid's controls write plain TanStack state, so a control of your own does the same:
+
+```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);
+
+// Several columns at once.
+grid.table.setColumnFilters([
+  { id: "status", value: { operator: "equals", value: "active" } },
+  { id: "salary", value: { operator: "between", value: ["40000", ""] } },
+]);
+```
+
+`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` 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"`.
+To replace every filter control, set `enableColumnFilters: false` and write the envelope yourself; filters in state still apply.
+
+## Custom matching
+
+A column `filterFn` replaces the shared matcher for that column, so its third argument is the stored 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:
+
+```ts
+import { isFilterActive, matchesFilter, type TMDataGridFilterFn } from "@jielga/tmdatagrid";
+
+// Matches the filter against the owner's full name instead of the stored id.
+const matchesOwner: TMDataGridFilterFn<Task> = (row, _columnId, filter) => {
+  if (!isFilterActive(filter)) return true;
+  return matchesFilter(ownerName(row.original.ownerId), filter);
+};
+```
+
+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.

package/skills/getting-started/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/react:packages/tmdatagrid/docs/anatomy.md'
@@ -157,7 +157,7 @@ flex column.
 | --- | --- | --- |
 | `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)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, and whichever filter surface the `filters` option asks for. `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.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`, keep the array stable), `renderPagination` slot | Rows-per-page select, range and previous/next buttons. Renders nothing unless pagination is enabled. |
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
 | `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
@@ -360,6 +360,41 @@ Source: `packages/tmdatagrid/docs/card-view.md`,
 | `moveColumnByStep({ table, columnId, direction })` | Moves a column one position within its region. |
 | `SELECT_COLUMN_ID` | Id of the generated checkbox column. |
 
+## 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 the `columns` skill.
+- **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 in the
+  `options` skill.
+- **Filters are envelopes** - `columnFilters` holds `{ operator, value }`, and
+  a column's own `filterFn` receives that envelope. See the `filtering` skill.
+- **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.
+- **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`.
+- **State reads** - there is no `table.getState()`; read slices with
+  `useSelector(table.store, ...)`. See the `options` skill.
+- **Tests** - the grid publishes `data-dg-part`, `data-row-id` and
+  `data-column-id`, and no `data-testid`. See the `testing` skill.
+
 ## Common mistakes
 
 ### Columns or data defined during render

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/grouping.md'
   - 'Jielga/react:packages/tmdatagrid/docs/summary-row.md'
@@ -96,8 +96,8 @@ would pass a row that looks real but is the wrong one. Group rows therefore:
 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 do not depend on
-how the tree is arranged. Under `enableMultiRowSelection: false` group rows carry
+never in it, so `getSelectedRowModel()` and `onRowSelectionChange` do not depend
+on 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.
@@ -116,8 +116,11 @@ page. Rendering the whole tree is the grid's default mode in any case, so only
 the pager is lost.
 
 `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`.
+out the same way. 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 have both, page on the server with
+`manualPagination` and `manualGrouping`, and render the pager through the
+Footer's `renderPagination` slot, ignoring `isPagingActive`.
 
 ## The summary row
 
@@ -197,7 +200,7 @@ out instead of 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: `packages/tmdatagrid/docs/grouping.md` (Grouping suspends pagination).
+Source: `packages/tmdatagrid/docs/grouping.md` (Grouping and pagination).
 
 ### HIGH Handing a group row to a row callback
 
@@ -224,7 +227,7 @@ const records = getGroupDataRows(groupRow).map((row) => row.original);
 />;
 ```
 
-Source: `packages/tmdatagrid/docs/grouping.md` (Group rows are not data rows).
+Source: `packages/tmdatagrid/docs/grouping.md` (Group rows).
 
 ### MEDIUM Totalling the page instead of the data
 
@@ -252,18 +255,22 @@ useTMDataGrid({
 });
 ```
 
+The built-in pager still greys out while `grouping` is set, so such a grid
+renders its pager through `TMDataGrid.Footer`'s `renderPagination` slot and
+ignores `state.isPagingActive`.
+
 Source: `packages/tmdatagrid/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. |
+| `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 grouped 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. |
+| `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. |
 | `footer` | Column option | `(ctx) => ReactNode` | – | Renders this column's summary cell. Defining one adds the row. |
 | `aggregateColumn` | Export | `({ table, columnId, fn }) => unknown` | `fn: "sum"` | Aggregates over every filtered row, all pages. |
 | `TMDataGridAggregationName` | Export | type | – | The registered function names. |

package/skills/migrating-to-2/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: lifecycle
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/migrating-to-2.md'
   - 'Jielga/react:packages/tmdatagrid/src/index.ts'