@jielga/tmdatagrid 2.1.4 → 2.3.0

package/skills/columns/SKILL.md

@@ -2,9 +2,9 @@
 name: columns
 description: >
   Define and arrange TMDataGrid columns. Covers createTMDataGridColumnHelper,
-  every column meta field (label, type, options, flex, align, autoSize,
+  every column meta field (label, type, options, flex, align, colSpan, autoSize,
   enableOrdering, and the meta.filter and meta.edit namespaces holding
-  operators, defaultOperator, control, enabled, field, editor, validate and
+  operators, defaultOperator, control, url, enabled, field, editor, validate and
   mapValue), the six column types, fluid minmax sizing versus fixed width with
   minSize / maxSize / size, autosizing and autosizeColumn, hiding through
   enableHiding and the columns panel, pinning and why a pinned column becomes
@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/columns.md'
   - 'Jielga/react:packages/tmdatagrid/docs/column-layout.md'
@@ -84,6 +84,7 @@ columnHelper.group({
 | `options` | `TMDataGridOptionsSource` | – | Choices for a `select` / `multiSelect` column: an array, `"faceted"`, or a function. One declaration feeds the filter panel and the editor. |
 | `flex` | `number` | `1` | Share of the remaining width. |
 | `align` | `"left" \| "right" \| "center"` | `"left"` | Applied to both header and cells. |
+| `colSpan` | `number \| ({ row, table }) => number` | `1` | Columns the cell covers on a row, counting itself; the covered cells do not render there. See below. |
 | `autoSize` | `boolean` | `false` | Size to the widest mounted content once, after the first rows render. |
 | `enableOrdering` | `boolean` | `true` | `false` keeps the column where it is. |
 | `filter` | `TMDataGridColumnFilterOptions` | – | How this column filters. See below. |
@@ -93,7 +94,7 @@ What the column **is** stays flat; what the filter panel and the edit engine do
 with it sits in their namespaces. `type` and `options` are read by both stages,
 which is why they are in neither.
 
-`meta.filter` holds `operators`, `defaultOperator` and `control`; `meta.edit`
+`meta.filter` holds `operators`, `defaultOperator`, `control` and `url`; `meta.edit`
 holds `enabled`, `field`, `editor`, `validate` and `mapValue`. Their fields are
 in [references/columns-api.md](references/columns-api.md).
 
@@ -117,6 +118,11 @@ annotation. A column written without the helper keeps the untyped row,
 TanStack defines no column option for. `meta.edit` only acts once `editing` is
 set: see the `editing` skill. `meta.filter` belongs to the `filtering` skill.
 
+`colSpan` (args `TMDataGridColSpanArgs`, `{ row, table }`) is display only, never
+covers a generated lane or leaves its pinned block, and is ignored on group rows,
+on rows in row edit mode, and on a row whose open cell editor a span would cover.
+Source: `packages/tmdatagrid/docs/columns.md` (Spanning columns).
+
 ### Column types
 
 `meta.type` is one of `"string"`, `"number"`, `"boolean"`, `"date"`,
@@ -163,10 +169,11 @@ Columns are fluid. Each track is `minmax(minSize, flex fr)`.
 
 | 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`. |
 
 ```tsx
 // Fixed 64px action column that never flexes.
@@ -191,21 +198,23 @@ consumer code.
 
 All three write state that persists together, so a grid comes back arranged the
 way it was left. `resetSettings()` from the hook clears visibility, order,
-pinning and widths in one go, and the column chooser offers it as **Reset
-layout**.
+pinning, widths and grouping in one go, and the column chooser offers it as
+**Reset layout**.
 
 **Hiding** is `columnVisibility`, driven by "Hide column" in a column menu and by
-the column chooser: `TMDataGrid.Menu.Columns` in the grid menu, **Manage
-columns** as a submenu of every column menu, and `TMDataGrid.ColumnsPanel` as
-plain controls for a host that is not a menu. See the `appearance` skill.
+the column chooser, which comes in three forms (see the `appearance` skill):
+
+- `TMDataGrid.Menu.Columns` in the grid menu.
+- **Manage columns**, a submenu of every column menu.
+- `TMDataGrid.ColumnsPanel`, plain controls for a host that is not a menu.
 
 **Pinning** is "Pin to left" / "Pin to right" in the column menu. A pinned
 column also becomes fixed-width: sticky offsets are computed from `getSize()`,
 which cannot resolve an `fr` value, so the grid stores the rendered width in
 `columnSizing` at the moment it is pinned and nothing jumps. A column pinned
 from `initialState.columnPinning` 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.
+its `size` - TanStack's default of `150` where none is set - clamped by
+`minSize` and `maxSize`.
 
 **Ordering** is header dragging plus "Move left" / "Move right". A column can
 only move **within its own pinned region** - pinning splits the grid into left,
@@ -253,24 +262,18 @@ const grid = useTMDataGrid({
 ```
 
 `sortFn` on a column takes any registered name or a
-`(rowA, rowB, columnId) => number` function - v9's name for what v8 called
-`sortingFn`, and a rename an agent will reproduce wrongly from memory. Sorting writes
+`(rowA, rowB, columnId) => number` function. `sortFn` is v9's name for v8's
+`sortingFn`. Sorting writes
 TanStack's `sorting` state, an array of `{ id, desc }` in priority order. It is
 a **data** slice, persisted under `dataKey`, while the column layout below is a
 settings slice under `settingsKey`.
 
 ## Column-level feature options
 
-Standard TanStack column options. Each also removes the corresponding interface.
-
-| Option | Effect when `false` |
-| --- | --- |
-| `enableSorting` | No sort indicator, no sort menu items, no click-to-sort. |
-| `enableColumnFilter` | No filter menu item. Excluded from the filter panel's column list, and its header filter cell is empty. |
-| `enableHiding` | No hide menu item. Checkbox disabled in the column manager. |
-| `enablePinning` | No pin menu items. |
-| `enableResizing` | The divider is displayed but cannot be dragged. |
-| `enableGrouping` | No "Group by" menu item. |
+Standard TanStack column options, each removing its interface when `false`:
+`enableSorting`, `enableMultiSort`, `enableColumnFilter`, `enableHiding`,
+`enablePinning`, `enableResizing` and `enableGrouping`. What each one removes is
+in [references/columns-api.md](references/columns-api.md#column-level-feature-options).
 
 `meta.enableOrdering: false` belongs to the same set. A column whose menu has no
 remaining items renders no menu button and takes no right-click, so the
@@ -294,16 +297,17 @@ columns and edit.
 They are structural: fixed width, no column menu, and they cannot be sorted,
 filtered, resized, re-pinned or moved. The checkbox lane anchors the left pinned
 region, so no column can be placed in front of it. `isControlColumn(columnId)`
-identifies them.
+identifies them. To locate a lane in a test, use the constant with
+`data-column-id`; see the `testing` skill.
 
 ## Common mistakes
 
 ### CRITICAL Setting `size` to control width
 
-`size` is only applied once the column becomes fixed by resizing or pinning. On
-a fluid column it is ignored - the track is `minmax(minSize, flex fr)` - so a
-column given `size: 200` renders at whatever the flex share works out to, and
-the number looks like it did nothing.
+`size` applies only to a column pinned at mount. On a fluid column it is
+ignored - the track is `minmax(minSize, flex fr)` - so a column given
+`size: 200` renders at whatever the flex share works out to. A resize or an
+interactive pin stores the rendered width, not `size`.
 
 Wrong:
 
@@ -322,29 +326,28 @@ columnHelper.accessor("email", {
 });
 ```
 
-The corollary is that a pinned column is fixed-width and does use `size`, so a
-column that is pinned needs one.
+A column pinned at mount is fixed-width and does use `size`, so give it one.
 
 Source: `packages/tmdatagrid/docs/column-layout.md` (Sizing).
 
-### HIGH Pinning a column at mount without size
+### HIGH Pinning a column at mount without a width
 
 A column pinned interactively keeps the width it was rendering, which the grid
 writes into `columnSizing`. A column pinned from `initialState.columnPinning`
-has no rendered width, so it takes `size` - TanStack's default of `150` where
-none is set - and `minSize` does not apply.
+has no rendered width, so it takes `size` clamped by `minSize` / `maxSize`:
+TanStack's `150` when none is set, whatever the content needs.
 
 Wrong:
 
 ```tsx
-columnHelper.accessor("name", { header: "Name", minSize: 220 });
+columnHelper.accessor("name", { header: "Name" });
 initialState: { columnPinning: { start: ["name"], end: [] } },
 ```
 
 Correct:
 
 ```tsx
-columnHelper.accessor("name", { header: "Name", minSize: 220, size: 220 });
+columnHelper.accessor("name", { header: "Name", size: 220 });
 initialState: { columnPinning: { start: ["name"], end: [] } },
 ```
 
@@ -399,8 +402,7 @@ Source: `packages/tmdatagrid/src/core/columnUtils.ts`.
 
 `getColumnType(column)` defaults to `"string"`, so a numeric column that omits
 `meta: { type: "number" }` offers only the string operators, and comparisons run
-as text - `"9"` above `"10"`. The column still sorts and filters, which is why
-it is easy to miss.
+as text - `"9"` above `"10"`. The column still sorts and filters.
 
 Source: `packages/tmdatagrid/src/core/filterOperators.ts`.
 
@@ -421,10 +423,9 @@ Source: `packages/tmdatagrid/docs/column-layout.md` (Regions).
 
 ### HIGH Reaching for the v8 name of a v9 option
 
-TanStack v9 renamed the column comparator to `sortFn`. `sortingFn` is not an
-error the compiler catches in every position - it is simply an unknown key on
-the column definition, so the column keeps its automatic comparator and the
-custom ordering never appears.
+TanStack v9 renamed the column comparator to `sortFn`. `sortingFn` is an
+unknown key in v9; TypeScript does not always report it, and the column keeps
+its automatic comparator, so the custom ordering never appears.
 
 Wrong:
 

package/skills/columns/references/columns-api.md

@@ -11,6 +11,7 @@ Reference for the `columns` skill.
 | `operators` | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. For a backend that answers only some. |
 | `defaultOperator` | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter on this column starts with. |
 | `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
+| `url` | `boolean` | `true` | Whether the column's filter is written to the URL under `persist.urlKey`. `false` keeps it out of the link, and out of storage. |
 
 `meta.edit` belongs to the `editing` skill, and only acts once `editing` is set:
 
@@ -22,6 +23,20 @@ Reference for the `columns` skill.
 | `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
 | `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
 
+## Column-level feature options
+
+Standard TanStack column options. Each also removes the corresponding interface.
+
+| Option | Effect when `false` |
+| --- | --- |
+| `enableSorting` | No sort indicator, no sort menu items, no click-to-sort. |
+| `enableMultiSort` | Shift+click on this header replaces the sort instead of adding to it. |
+| `enableColumnFilter` | No filter menu item. Excluded from the filter panel's column list, and its header filter cell is empty. |
+| `enableHiding` | No hide menu item. Checkbox disabled in the column manager. |
+| `enablePinning` | No pin menu items. |
+| `enableResizing` | The divider is displayed but cannot be dragged. |
+| `enableGrouping` | No "Group by" menu item. |
+
 ## Exports and options
 
 | Name | Kind | Type | Default | What it does |
@@ -34,7 +49,7 @@ Reference for the `columns` skill.
 | `TMDataGridOptionsArgs` | Type | `{ table, column, row? }` | – | What a `meta.options` function receives. `row` is absent when the filter panel asks. |
 | `resolveColumnOptions` | Export | `({ table, column, row?, fallback? }) => Array<TMDataGridOption>` | – | Normalises all three `meta.options` forms. Empty when the column declares none. |
 | `optionsToComboboxData` | Export | `(options) => ComboboxData` | – | Options as Mantine `Select` / `MultiSelect` data, groups folded in. |
-| `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / – | Width bounds, and the fixed width once one applies. |
+| `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / `150` | Floor of the fluid track, a resize and a pinned width; ceiling of a resize and a pinned width; width of a column pinned at mount. |
 | `enableSorting` · `enableColumnFilter` · `enableHiding` · `enablePinning` · `enableResizing` · `enableGrouping` | Column options | `boolean` | `true` | Per-column switches, each removing its interface. |
 | `enableColumnOrdering` | Option | `boolean` | `true` | Header dragging and the move menu items. Grid-defined. |
 | `enableMultiSort` · `maxMultiSortColCount` · `isMultiSortEvent` | Table options | – | Shift held | Multi-column sorting. |

package/skills/data/SKILL.md

@@ -8,7 +8,7 @@ description: >
   canPaginate, always-on virtualization with overscan and meta.rowHeight,
   scrollToRow, the edge callbacks onScrollToBottom / onScrollToRight and why
   onReachEnd is better for loading more, the header and pinned-lane depth
-  shadows, and the four empty states in precedence order with meta.loading,
+  shadows, and the five empty states in precedence order with meta.loading,
   renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator and
   TMDataGrid.SummaryCount, and export: TMDataGrid.Menu.Export and
   Menu.ExportSelected, useTMDataGridExport, exportGrid, exportOptions, the
@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/react:packages/tmdatagrid/docs/scrolling.md'
@@ -56,8 +56,14 @@ const grid = useTMDataGrid({
 ```
 
 Initial page size is 25, through `initialState.pagination`. `enablePagination`
-is defined by the grid rather than by TanStack, and is the only grid option that
-defaults to off.
+is defined by the grid rather than by TanStack.
+
+The Footer renders a rows-per-page select, the range (`1–25 of 300`, from
+`table.getRowCount()`) and previous and next buttons; there are no numbered page
+buttons. The select offers `pageSizeOptions`, by default `[10, 25, 50, 100]`,
+with the current size folded in when it is not in the list. Pass a module-scope
+array: the select is memoized on it, and an inline literal remounts it on every
+render.
 
 `TMDataGrid.Footer` takes a `renderPagination` slot handed three things: the
 `state` the pager shows, the `actions` it can take, and `Controls`, the built-in
@@ -82,22 +88,26 @@ pieces, already wired.
 
 `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are what the default
 footer renders, in that order, so a custom layout can keep the parts it wants
-instead of rebuilding them. They behave exactly as before, including greying out
-under a suspended pager. `Controls.PageNumber` - the "Page 3 of 200" label a
-server-paged grid usually shows in place of a row range - is a fourth control,
-not in the default footer; put it in through the slot rather than writing it by
-hand.
+instead of rebuilding them. They behave as in the default footer, including
+greying out while paging is suspended. `Controls.PageNumber` renders
+"Page 3 of 200", the label a server-paged grid usually shows in place of the
+row range. It is not in the default footer; add it through the slot.
 
 `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
 `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
 carries `setPageIndex`, `setPageSize`, `previousPage`, `nextPage`, `firstPage`
-and `lastPage`. `getTMDataGridPaginationApi(table)` returns the same
-`{ state, actions }` outside the Footer. `Controls` is bound to the grid
-context, so those components work only inside the slot.
-
-Grouping suspends the pager: it greys out and the range becomes
-`Grouped · all N rows`. `isPagingActive(table, features)` is the live state,
-whether the pager is slicing anything right now, while
+and `lastPage`. Outside the Footer,
+`getTMDataGridPaginationApi(table, isPagingActive(table, grid.features))`
+returns the same `{ state, actions }`. Without the second argument
+`state.isPagingActive` is `true`, also while the rows are grouped. `Controls`
+is bound to the grid context, so those components work only inside the slot.
+
+Grouping suspends the pager: the built-in controls grey out and the range
+becomes `Grouped · all N rows`. The default footer also carries
+`data-paging-suspended` on its bar and shows `labels.pagingSuspendedHint` as a
+tooltip; a footer with `renderPagination` has neither. There is no option to
+keep the built-in pager active while grouped. `isPagingActive(table, features)`
+is the live state, whether the pager is slicing anything right now, while
 `getGridCapabilities(...).canPaginate` is the configuration. The two differ
 while a grouping is active.
 
@@ -141,14 +151,13 @@ arrival rather than on every scroll event. For loading more rows use
 `onReachEnd` (the `server-side` skill) instead: it fires a number of rows before
 the bottom, and latches per row count so a pending fetch is not requested twice.
 
-Two depth cues are scroll-driven animations run on the compositor, with no
-scroll listener and no React render: a shadow under the sticky header once rows
-scroll beneath it, and a band beside a pinned lane while it is covering
-content.
+Two depth cues run as scroll-driven CSS animations, with no scroll listener and
+no React render. A shadow appears under the sticky header once rows scroll
+beneath it. A band appears beside a pinned lane while it covers content.
 
 ## Empty states
 
-There are four ways to have nothing to show, and an empty body shows exactly one
+There are five ways to have nothing to show, and an empty body shows exactly one
 of them, in this order:
 
 1. **Loading** - `meta.loading` is true: a centred loader. A grid that is
@@ -156,9 +165,23 @@ of them, 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: `labels.noResults`, since
-   clearing the filter will bring rows back.
-5. **Truly-empty** - no data at all: `labels.noRows`.
+4. **Filtered-empty** - a column filter is active (`isFilterActive`) or the
+   quick search is not blank: `labels.noResults`, since clearing the filter
+   will bring rows back.
+5. **Truly-empty** - no column filter is active and the quick search is blank:
+   `labels.noRows`.
+
+"Empty" means no displayed row and no pinned 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.
+
+The loader is the only "no data yet" signal, so set `meta.loading` during the
+first fetch too; 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 unmounts again on the next
+refetch.
 
 `renderEmptyState` replaces the last two with one render prop, and
 `hasActiveFilters` says which it is standing in for:
@@ -177,15 +200,14 @@ of them, in this order:
 />
 ```
 
-An empty grid is a good place to offer the action that fills it, such as
-clearing the filters or creating the first record.
-
 The body's loading state only appears while the grid is **empty**. A
 server-driven grid refetching with rows still on screen keeps showing them.
 `TMDataGrid.LoadingIndicator` covers that case: a small spinner while
 `meta.loading` is true. `TMDataGrid.SummaryCount` shows visible rows out of
-total, where the total is `meta.totalRowCount` when provided and the pre-filtered
-count otherwise.
+total. The total is `meta.totalRowCount` when provided, otherwise the
+pre-filtered count on a client-side grid; a server-driven grid
+(`manualFiltering` or `manualPagination`) without `meta.totalRowCount` shows the
+visible count alone, with no total.
 
 ## Export
 
@@ -214,15 +236,19 @@ function ExportButton() {
 }
 ```
 
-What is written: the data columns in render order (never the generated lanes,
-never a column with `meta.enableExport: false`), every row after filtering and
-sorting (a grouped grid writes the records under every group, never the group
-rows), and each cell's **value** rather than what it renders -
-`meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+What is written:
+
+- **Columns** - the data columns in render order. Never the generated lanes,
+  never a column with `meta.enableExport: false`.
+- **Rows** - every row after filtering and sorting. A grouped grid writes the
+  records under every group, never the group rows.
+- **Values** - each cell's **value** rather than what it renders.
+  `meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+
 `columns` on `exportOptions`, the items and the functions is `"visible"` (the
-default), `"all"` (hidden columns too) or a list of ids; `columns="custom"` on
-a menu item opens a picker instead - every exportable column, the visible ones
-ticked, Export and Cancel - driven by `ui.state.exportPicker` and
+default), `"all"` (hidden columns too) or a list of ids. `columns="custom"` on a
+menu item opens a picker instead: every exportable column, the visible ones
+ticked, Export and Cancel. The picker is driven by `ui.state.exportPicker` and
 `ui.actions.openExportPicker`. `TMDataGrid.Menu.ExportSelected` counts and
 writes the ticked rows of the current view, in grid order; it renders nothing
 when row selection is off.
@@ -303,10 +329,11 @@ a pending fetch is not requested twice.
 
 Source: `packages/tmdatagrid/docs/scrolling.md` (Edge callbacks).
 
-### HIGH `SummaryCount` reporting the page under manual pagination
+### HIGH `SummaryCount` without a total under manual pagination
 
-The client only holds one page, so without `meta.totalRowCount` the total is
-whatever arrived. It shows "25 of 25" over a table of thousands.
+The client holds one page, so a server-driven grid has no total of its own.
+Without `meta.totalRowCount`, `SummaryCount` shows the visible count alone, with
+no total, over a table of thousands.
 
 Correct:
 
@@ -334,7 +361,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { loading: isFetching } });
 ```
 
-Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (Precedence).
 
 ### MEDIUM Trusting the pager while grouped
 
@@ -342,7 +369,7 @@ Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
 grid is rendering the whole tree. A custom pager must read
 `isPagingActive(table, features)` rather than the page count.
 
-Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
+Source: `packages/tmdatagrid/docs/pagination.md` (Grouping).
 
 ## Reference
 
@@ -351,31 +378,31 @@ Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 | `enablePagination` | Option | `boolean` | `false` | Client-side paging and the Footer's pager. Grid-defined. |
 | `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
 | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
-| `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
+| `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ pageIndex: 0, pageSize: 25 }` | Where paging starts. A `data` slice, so it persists. |
 | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
-| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
+| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `pageSizeOptions`: `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
 | `TMDataGridFooterProps` | Type | – | – | The props of `TMDataGrid.Footer`. |
 | `Footer` `renderPagination` | Slot | `(args: TMDataGridPaginationSlotArgs) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
 | `TMDataGridPaginationSlotArgs` | Type | `TMDataGridPaginationApi & { Controls }` | – | What `renderPagination` receives: `{ state, actions, Controls }`. |
-| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | The pager API, outside the Footer. |
+| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | The pager API, outside the Footer. Pass `isPagingActive(table, features)` as `isPaging`. |
 | `TMDataGridPaginationApi` | Type | `{ state, actions }` | – | What `getTMDataGridPaginationApi` returns. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot argument. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |
 | `overscan` | Option | `number` | `6` | Rows kept mounted beyond each edge of the viewport. |
-| `meta.rowHeight` | Option | `number` | From `size` | Row height in pixels. The virtualizer needs a number. |
+| `meta.rowHeight` | Option | `number` | `52` at the default `md` size; see the `size` scale in the `appearance` skill | Row height in pixels. The virtualizer needs a number. |
 | `scrollToRow` | Hook return | `({ rowId, align? }) => boolean` | `align: "auto"` | Scrolls a row into view, mounted or not. |
 | `TMDataGridScrollToRowArgs` | Export | `{ rowId, align? }` | – | What `scrollToRow` takes. |
 | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
 | `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
-| `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. |
 | `--dg-header-shadow-color` | CSS variable | colour | Themed | The shadow under the sticky header. |
 | `--dg-sticky-edge-range` | CSS variable | length | `20px` | How far the pinned-lane band takes to fade in. |
-| `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 | `TMDataGridExportValueGetter`: `({ value, row, column }) => unknown` | – | The value written in place of `row.getValue`. |
 | `TMDataGrid.Menu.Export` · `TMDataGrid.Menu.ExportSelected` | Components | `TMDataGridMenuExportProps` | – | Menu items: every filtered row, and the selected rows. `columns="custom"` opens the picker. |

package/skills/editing/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/draft-store.md'