@jielga/tmdatagrid 2.1.4 → 2.3.0

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). |

package/docs/localization.md

@@ -59,12 +59,139 @@ context as `useTMDataGridContext().labels`, so a
 [toolbar component of your own](/docs/toolbar) uses the same strings as the
 built-in parts, in whatever language is configured.
 
-`mergeLabels(base, override)` is the merge itself, exported for composing
-dictionaries before passing one in.
+`mergeLabels(override)` is the merge itself: it folds a partial override over
+the English defaults, `operators` included, and returns the full dictionary.
+Called without an argument, it returns `TMDATAGRID_LABELS_EN` itself.
 
 `meta.noResultsLabel` remains as a per-instance override of
 `labels.noResults`.
 
+## Label keys
+
+Every key of `TMDataGridLabels`, with its English default and where the grid
+shows it; a function label shows its template:
+
+| Key | Default | Where it shows |
+| --- | --- | --- |
+| `operators.contains` | `contains` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.equals` | `equals` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.notEquals` | `does not equal` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.startsWith` | `starts with` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.endsWith` | `ends with` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.greaterThan` | `is greater than` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.greaterThanOrEqual` | `is greater than or equal to` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.lessThan` | `is less than` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.lessThanOrEqual` | `is less than or equal to` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.between` | `is between` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.before` | `is before` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.after` | `is after` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.onOrBefore` | `is on or before` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.onOrAfter` | `is on or after` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.isAnyOf` | `is any of` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.isNoneOf` | `is none of` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.isEmpty` | `is empty` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `operators.isNotEmpty` | `is not empty` | The operator select of `TMDataGrid.FilterPanel`, the text of a filter pill, and the operator button of a header filter. |
+| `filters` | `Filters` | Tooltip and `aria-label` of `TMDataGrid.FilterButton`, the title and `aria-label` of the filter popup and sidebar, and the `aria-label` of `TMDataGrid.FilterPanel`. |
+| `searchPlaceholder` | `Search` | Placeholder of `TMDataGrid.Search`. Its `placeholder` prop wins. |
+| `searchLabel` | `Search rows` | `aria-label` of the `TMDataGrid.Search` input. |
+| `clearSearch` | `Clear search` | `aria-label` of the clear button in `TMDataGrid.Search`. |
+| `menuButton` | `Menu` | Tooltip and `aria-label` of the `TMDataGrid.Menu` trigger. Its `label` prop wins. |
+| `manageColumns` | `Manage columns` | Column menu: the submenu that lists the columns. |
+| `columnsSearchPlaceholder` | `Search` | Search box of `TMDataGrid.ColumnsPanel`, `TMDataGrid.Menu.Columns` and the export column picker. |
+| `columnsNoMatch` | `` `No columns match “${search}”` `` | The same three lists, when the search matches no column. |
+| `columnsShowHideAll` | `Show/Hide All` | `TMDataGrid.ColumnsPanel` and `TMDataGrid.Menu.ShowHideAll`. |
+| `columnsReset` | `Reset layout` | `TMDataGrid.ColumnsPanel` and `TMDataGrid.Menu.ResetLayout`. |
+| `columnsResetHint` | `Resets column visibility, order, widths, pinning and grouping` | Tooltip of the reset button in `TMDataGrid.ColumnsPanel`. |
+| `rowNumberColumnLabel` | `Row number` | `meta.label` of the generated row-number lane. |
+| `noRows` | `No rows to show` | Body, when the view is empty, no column filter is active (`isFilterActive`) and the quick search is blank. |
+| `filterColumn` | `Column` | Label of the column field in `TMDataGrid.FilterPanel`. |
+| `filterOperator` | `Operator` | Label of the operator field in `TMDataGrid.FilterPanel`. |
+| `filterValue` | `Value` | Label of the value field in `TMDataGrid.FilterPanel`. |
+| `filterValuePlaceholder` | `Filter value` | Placeholder of the filter value input. |
+| `filterFrom` | `From` | The lower bound of a `between` filter: its input, or its slider thumb. |
+| `filterTo` | `To` | The upper bound of a `between` filter: its input, or its slider thumb. |
+| `filterAll` | `All` | The no-filter segment of the tri-state filter. |
+| `booleanTrue` | `Yes` | The `true` choice of a boolean filter value control and of the tri-state filter. |
+| `booleanFalse` | `No` | The `false` choice of a boolean filter value control and of the tri-state filter. |
+| `addFilter` | `Add filter` | Button in `TMDataGrid.FilterPanel`. |
+| `clearAllFilters` | `Clear all` | Button in `TMDataGrid.FilterPanel` and in `TMDataGrid.FilterPills`. |
+| `closeFilters` | `Close filters` | `aria-label` of the close button of the filter popup and sidebar. |
+| `removeFilter` | `Remove filter` | `aria-label` of the remove button on a filter row in `TMDataGrid.FilterPanel`. |
+| `filterOperatorFor` | `` `${column} filter operator` `` | `aria-label` of the operator button of a header filter. |
+| `activeFilters` | `Active filters` | `aria-label` of the `TMDataGrid.FilterPills` group. |
+| `clearFilter` | `` `Clear ${column} filter` `` | `aria-label` of the remove button on a filter pill. |
+| `sortAsc` | `Sort ascending` | Column menu item. |
+| `sortDesc` | `Sort descending` | Column menu item. |
+| `filterMenuItem` | `Filter` | Column menu item. |
+| `groupBy` | `` `Group by ${column}` `` | Column menu item. |
+| `ungroup` | `` `Ungroup ${column}` `` | Column menu item. |
+| `expandAllGroups` | `Expand all groups` | Column menu item. |
+| `collapseAllGroups` | `Collapse all groups` | Column menu item. |
+| `pinLeft` | `Pin to left` | Column menu item. |
+| `pinRight` | `Pin to right` | Column menu item. |
+| `unpin` | `Unpin` | Column menu item. |
+| `moveLeft` | `Move left` | Column menu item. |
+| `moveRight` | `Move right` | Column menu item. |
+| `autosizeColumn` | `Autosize column` | Column menu item. |
+| `hideColumn` | `Hide column` | Column menu item. |
+| `filterOn` | `` `Filter on ${column}` `` | `aria-label` of the header filter button, of a header filter cell, and of the value control in it. |
+| `sortColumn` | `` `Sort ${column}` `` | `aria-label` of the header sort button. |
+| `columnMenu` | `` `${column} column menu` `` | `aria-label` of the column menu trigger. |
+| `rowsPerPage` | `Rows per page:` | `TMDataGrid.Footer`: the text before the page size select. |
+| `pageRange` | `` `${from}–${to} of ${total}` `` | `TMDataGrid.Footer`: the range of rows on the page. |
+| `pageNumber` | `` `Page ${page} of ${pageCount}` ``, or `` `Page ${page}` `` when `pageCount` is `-1` | `TMDataGrid.Footer`: the page number. |
+| `groupedAllRows` | `` `Grouped · all ${total} rows` `` | `TMDataGrid.Footer`: in place of the range and the page number while the rows are grouped. |
+| `pagingSuspendedHint` | `Paging is off while the rows are grouped, and every row is shown. Ungroup to page again.` | `TMDataGrid.Footer`: tooltip of the pager while the rows are grouped. |
+| `previousPage` | `Previous page` | `TMDataGrid.Footer`: `aria-label` of the previous page button. |
+| `nextPage` | `Next page` | `TMDataGrid.Footer`: `aria-label` of the next page button. |
+| `noResults` | `No rows match your filters` | Body, when the view is empty and a column filter is active (`isFilterActive`) or the quick search is not blank. `meta.noResultsLabel` overrides it. |
+| `loading` | `Loading` | `aria-label` of the body loader, of `TMDataGrid.LoadingIndicator`, and of the edit lane spinner while a row saves. |
+| `editCell` | `` `Edit ${column}` `` | `aria-label` of an open cell editor. |
+| `confirmEdit` | `Save` | `aria-label` of the ✓ button beside a cell editor. |
+| `cancelEdit` | `Cancel` | `aria-label` of the ✕ button beside a cell editor. |
+| `editColumnLabel` | `Edit` | `meta.label` of the generated edit lane. |
+| `editRow` | `Edit row` | Edit lane: tooltip and `aria-label` of the pencil button. |
+| `saveRow` | `Save row` | Edit lane: tooltip and `aria-label` of the ✓ button while a row edit is open. |
+| `cancelRowEdit` | `Cancel edit` | Edit lane: tooltip and `aria-label` of the ✕ button while a row edit is open. |
+| `editRowErrors` | `Fix the marked cells` | Edit lane: tooltip of the save button when field errors block the row and the row has no message of its own. |
+| `saveAllEdits` | `"Save 1 row"` when `rows` is 1, else `` `Save ${rows} rows` `` | `TMDataGrid.DraftActions`: the save button. |
+| `discardAllEdits` | `Discard` | `TMDataGrid.DraftActions`: the discard button. |
+| `editRowsStillOpen` | `"1 row still being edited"` when `rows` is 1, else `` `${rows} rows still being edited` `` | `TMDataGrid.DraftActions`: the note shown while rows are still open in an edit. |
+| `confirmNewRow` | `Add row` | Edit lane: tooltip and `aria-label` of the ✓ button on the entry row. |
+| `discardNewRow` | `Discard new row` | Edit lane: tooltip and `aria-label` of the ✕ button on the entry row. |
+| `deleteRow` | `Delete row` | Edit lane: tooltip and `aria-label` of the trash button. |
+| `restoreRow` | `Restore row` | Edit lane: tooltip and `aria-label` of the undo button on a row marked for deletion. |
+| `revertRow` | `Revert changes` | Edit lane: tooltip and `aria-label` of the undo button on a row with a draft. |
+| `rowStateNew` | `New row` | Edit lane: the row-state marker of a confirmed entry row. |
+| `rowStateEdited` | `Edited row` | Edit lane: the row-state marker of a row with a draft. |
+| `rowStateDeleted` | `Marked for deletion` | Edit lane: the row-state marker of a row marked for deletion. |
+| `cellCount` | `"1 cell"` when `count` is 1, else `` `${count} cells` `` | Cell-selection context menu: its heading. |
+| `copy` | `Copy` | Cell-selection context menu item. |
+| `exportCells` | `Export cells` | Cell-selection context menu item. |
+| `includeHeaders` | `Include headers` | Cell-selection context menu: the checkbox. |
+| `exportAll` | `Export all rows` | `TMDataGrid.Menu.Export`. Its `label` prop wins. |
+| `exportSelected` | `"Export 1 selected row"` when `count` is 1, else `` `Export ${count} selected rows` `` | `TMDataGrid.Menu.ExportSelected`. Its `label` prop wins. |
+| `exportPickerTitle` | `` `Export as ${format}` `` | Export column picker: the title. `format` is the file extension in upper case. |
+| `exportPickerHint` | `"Select the columns to export"` when `selected` is `null`, `"Select the columns to export for the selected row"` when it is 1, else `` `Select the columns to export for the ${selected} selected rows` `` | Export column picker: the line under the title. |
+| `exportPickerConfirm` | `Export` | Export column picker: the confirm button. |
+| `exportPickerCancel` | `Cancel` | Export column picker: the cancel button. |
+| `exportPickerSelectAll` | `Select all` | Export column picker: the select-all checkbox over the list. |
+| `exportPickerCount` | `` `${checked} of ${total}` `` | Export column picker: the count beside the select-all checkbox. |
+| `exportPickerHidden` | `Hidden` | Export column picker: the mark on a column the grid hides. |
+| `selectColumnLabel` | `Checkbox selection` | `meta.label` of the generated checkbox lane. |
+| `selectAllRows` | `Select all rows` | `aria-label` of the header checkbox. |
+| `selectRow` | `Select row` | `aria-label` of a row checkbox. |
+| `selectGroup` | `Select group` | `aria-label` of a group row checkbox. |
+| `detailsColumnLabel` | `Details` | `meta.label` of the generated details lane. |
+| `showDetails` | `Show details` | `aria-label` of a collapsed row's details toggle. |
+| `hideDetails` | `Hide details` | `aria-label` of an expanded row's details toggle. |
+| `expandAllDetails` | `Expand all details` | `aria-label` of the details lane's header toggle while some row is collapsed. |
+| `collapseAllDetails` | `Collapse all details` | `aria-label` of the details lane's header toggle while every row is expanded. |
+| `groupColumnLabel` | `Group` | `meta.label` of the generated tree lane, and its header text while nothing is grouped. |
+| `blankGroupValue` | `(Blank)` | Group row text for an empty group key. |
+| `expandGroup` | `` `Expand ${label}` `` | `aria-label` of a collapsed group row's toggle. |
+| `collapseGroup` | `` `Collapse ${label}` `` | `aria-label` of an expanded group row's toggle. |
+
 ## Reference
 
 | Name | Kind | Type | Default | What it does |
@@ -75,5 +202,5 @@ dictionaries before passing one in.
 | `TMDATAGRID_LABELS_SV` | Export | `TMDataGridLabels` | – | A complete Swedish dictionary. |
 | `TMDataGridLabels` | Export | type | – | The full dictionary. What a new translation must cover. |
 | `TMDataGridLabelsOverride` | Export | type | – | A partial dictionary. |
-| `mergeLabels` | Export | `(base, override) => TMDataGridLabels` | – | The merge, for composing dictionaries. |
+| `mergeLabels` | Export | `(override?: TMDataGridLabelsOverride) => TMDataGridLabels` | – | Folds a partial override over the English defaults. Returns `TMDATAGRID_LABELS_EN` itself without an argument. |
 | `meta.noResultsLabel` | Option | `string` | `labels.noResults` | Per-instance override of the filtered-empty message. |

package/docs/menu.md

@@ -54,7 +54,7 @@ The pieces it is made of are exported for menus that want only some of them.
 | `TMDataGrid.Menu.Columns` | `Menu.Search`, the toggles, a divider, show/hide all and reset layout. By default the search box shows from six columns; `searchable` shows it always and `searchable={false}` never. |
 | `TMDataGrid.Menu.ColumnToggles` | One item per hideable column, with a checkbox that shows both states. `search` narrows the list to the labels containing it. |
 | `TMDataGrid.Menu.ShowHideAll` | One checkbox item over the same list. An indeterminate box marks a partial state, and a click then shows all. |
-| `TMDataGrid.Menu.ResetLayout` | One item calling `resetSettings()`: visibility, order, pinning and widths. |
+| `TMDataGrid.Menu.ResetLayout` | One item calling `resetSettings()`: visibility, order, pinning, widths and grouping. |
 
 Each of them needs a Mantine `Menu` around it and reads the grid from context, so they work in any Mantine menu rendered inside `TMDataGrid`, not only in the burger:
 

package/docs/pagination.md

@@ -21,6 +21,18 @@ its pager. Initial page size is 25, configurable through
 const grid = useTMDataGrid({ data, columns, enablePagination: true });
 ```
 
+The Footer renders a rows-per-page select, the range (`1–25 of 300`, from
+`table.getRowCount()`) and previous and next 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.
+
+```tsx
+const PAGE_SIZES = [10, 20, 50];
+
+<TMDataGrid.Footer pageSizeOptions={PAGE_SIZES} />
+```
+
 **Manual pagination** - the server pages, and the grid stops.
 `manualPagination: true` implies `enablePagination`, so no extra flag is
 needed. See [Server-side data](/docs/server-side).
@@ -102,15 +114,20 @@ It reads `pageCount`, so a grid declaring `pageCount: -1` shows "Page 3" alone.
 and `isPagingActive`. `actions` carries `setPageIndex`, `setPageSize`,
 `previousPage`, `nextPage`, `firstPage` and `lastPage`.
 
-`getTMDataGridPaginationApi(table)` returns the same `{ state, actions }`
-outside the Footer, for a pager that lives elsewhere on the page. `Controls` is
-not included: those components are bound to the grid's context and work only
-inside the slot.
+Outside the Footer,
+`getTMDataGridPaginationApi(table, isPagingActive(table, grid.features))`
+returns the same `{ state, actions }`, for a pager that lives elsewhere on the
+page. Without the second argument `state.isPagingActive` is `true`, also while
+the rows are grouped. `Controls` is not included: those components are bound to
+the grid's context and work only inside the slot.
 
 ## Grouping
 
 While a column is grouped the pager greys itself out and the range is replaced
-with `Grouped · all N rows`. See
+with `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. The body shows every filtered
+row. There is no option to keep the built-in pager active while grouped. See
 [Grouping](/docs/grouping#grouping-and-pagination).
 
 A custom pager can grey itself out the same way:
@@ -134,11 +151,13 @@ paging is switched on at all. The two differ while a grouping is active.
 | `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. |
 | `resetPageOnQueryChange` | Option | `boolean` | `true` | Back to page 1 when a filter, the quick search, the sort or the grouping changes. `false` keeps the page. See [Server-side data](/docs/server-side#the-page-index). |
 | `TMDataGrid.Footer` | Component | – | – | The footer bar. Renders nothing when paging is off. |
+| `Footer` `pageSizeOptions` | Prop | `ReadonlyArray<number>` | `[10, 25, 50, 100]` | The rows-per-page choices. Keep the array referentially stable. |
 | `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
-| `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
+| `data-paging-suspended` | Data attribute | – | – | On the default footer bar while grouping suspends paging. |
+| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => { state, actions }` | `isPaging`: `true` | The pager API, outside the Footer. Pass `isPagingActive(table, features)` as `isPaging`. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot's argument. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |

package/docs/persistence.md

@@ -6,7 +6,8 @@ return to the grid as they left it.
 State is split across **two keys**: `settingsKey` for the column layout, which
 stays valid indefinitely, and `dataKey` for filters, sorting and pagination,
 which go stale as the data underneath them changes. Either can be cleared
-without touching the other.
+without touching the other. A third key, `urlKey`, keeps data slices in the
+page URL instead, as a [deep link](#deep-links).
 
 ```tsx
 // Module scope: the object is a dependency of the write subscription.
@@ -32,6 +33,7 @@ extraSources: data/employeeColumns.tsx
 | Group | Slices | Lifetime |
 | --- | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` | As long as the data means the same thing |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey` | As long as the link is opened. See [Deep links](#deep-links) |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` | Indefinite. This is the user's layout |
 
 `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` are exported with the same
@@ -57,6 +59,99 @@ const persist = {
 Only the selected slices are read back, so a payload written before you narrowed
 the selection cannot reintroduce slices you have since opted out of.
 
+## Deep links
+
+`urlKey` keeps data slices in one URL search param, so a link to the page opens
+the grid on the same filters. The string is the param name, and the slices
+follow the same rules as `dataKey`: a bare key takes every data slice, a tuple a
+subset. A slice lives in one group, so a slice listed under `urlKey` is taken
+out of `dataKey`:
+
+```tsx
+const persist = {
+  settingsKey: "employees.settings",
+  // Sorting is remembered per browser; the filters travel in the link.
+  dataKey: ["employees.data", ["sorting"]],
+  urlKey: ["employees", ["columnFilters", "globalFilter"]],
+} satisfies TMDataGridPersistence;
+```
+
+```demo
+file: data/DeepLinks.tsx
+hint: Filter a column, then copy the address bar into a new tab. The Location filter stays out of the link.
+extraSources: data/employeeColumns.tsx
+```
+
+The param carries only the slices whose value differs from the initial state,
+`initialState` merged over the grid defaults, and only the column filters that
+are active. When nothing differs, the param is removed. A link without the
+param, or without a slice, opens on the initial state; a URL slice never falls
+back to storage.
+
+Writes use `history.replaceState`, so a filter change never adds a history
+entry. Only the grid's own param changes; the path, the hash, other params and
+`history.state` are kept. Two grids on one page use two keys.
+
+The URL payload carries no version stamp, because a bookmarked link has to
+survive a release. The shape guards and the realignment against existing
+columns apply as they do to storage, and so do `serialize` and `deserialize`.
+
+Note that a bare `dataKey` hands the URL slices over silently, while a
+`dataKey` tuple that names a slice `urlKey` also lists is reported with
+`console.error` on mount; `urlKey` handles the slice either way.
+
+### Keeping a column out of the link
+
+Set `meta.filter.url` to `false` on a column whose filter should not travel
+with the link:
+
+```tsx
+columnHelper.accessor("owner", {
+  header: "Owner",
+  meta: { filter: { url: false } },
+});
+```
+
+The column's filter is then not persisted anywhere. A filter on it in
+`initialState` still applies when a link is opened. The flag has no effect
+unless `urlKey` carries `columnFilters`.
+
+### Routers that own the URL
+
+`urlStorage` replaces the default read and write of the param, for a router
+that validates its search params and would not see a `replaceState` call.
+`get` returns the param's string or `null`; `set` receives the string, or
+`null` to remove the param. Keep `persist` referentially stable here too:
+react-router rebuilds `setSearchParams` on every URL change, so read it
+through a ref rather than listing it as a dependency:
+
+```tsx
+// react-router: let the router do the replace.
+const [, setSearchParams] = useSearchParams();
+const setSearchParamsRef = useRef(setSearchParams);
+setSearchParamsRef.current = setSearchParams;
+
+const persist = useMemo(
+  () =>
+    ({
+      urlKey: ["employees", ["columnFilters"]],
+      urlStorage: {
+        get: (name) => new URLSearchParams(window.location.search).get(name),
+        set: (name, value) =>
+          setSearchParamsRef.current(
+            (prev) => {
+              if (value === null) prev.delete(name);
+              else prev.set(name, value);
+              return prev;
+            },
+            { replace: true },
+          ),
+      },
+    }) satisfies TMDataGridPersistence,
+  [],
+);
+```
+
 ## Behaviour
 
 **Restoring happens once**, on mount, through `initialState`. Writing is a
@@ -103,7 +198,11 @@ its `StorageType`.
 | `persist` | Option | `TMDataGridPersistence` | – | The whole configuration. Keep it referentially stable. |
 | `dataKey` | persist field | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | persist field | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
-| `TMDataGridPersistKey` | Type | `string \| [string, slices]` | – | The type of `dataKey` and `settingsKey`. |
+| `urlKey` | persist field | `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](#deep-links). |
+| `urlStorage` | persist field | `TMDataGridUrlStorage` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
+| `TMDataGridUrlStorage` | Type | `{ get(name): string \| null; set(name, value: string \| null): void }` | – | The type of `urlStorage`. |
+| `meta.filter.url` | Column meta | `boolean` | `true` | Determines whether the column's filter is written to the URL under `urlKey`. |
+| `TMDataGridPersistKey` | Type | `string \| [string, slices]` | – | The type of `dataKey`, `settingsKey` and `urlKey`. |
 | `storageMode` | persist field | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
 | `TMDataGridStorageMode` | Type | `"localStorage" \| "sessionStorage"` | – | The type of `storageMode`. |
 | `serialize` | persist field | `(value) => string` | `JSON.stringify` | Serializes a payload before storing. |

package/docs/row-details.md

@@ -19,10 +19,13 @@ hint: Expand a few rows - the panels differ in height, and each one is measured.
 height: 460
 ```
 
-The panel is as tall as whatever it renders. The grid measures each one, so
-they need not be uniform. `renderDetailsEstHeight` (default `160`) is what the
-virtualizer assumes for a panel it has not measured yet, which keeps the
-scrollbar accurate for rows that open off screen.
+The panel opens below the row's cells, which stay where they are; there is no
+mode in which a panel replaces the row. The panel is as tall as whatever it
+renders. The grid measures each one, so they need not be uniform.
+`renderDetailsEstHeight` (default `160`) is what the virtualizer assumes for a
+panel it has not measured yet, which keeps the scrollbar accurate for rows that
+open off screen. Set it to the typical panel height; the estimate only decides
+how far the scrollbar is off until the panel has mounted.
 
 ## The details lane
 
@@ -87,6 +90,12 @@ Because it is the standard state, `table.toggleAllRowsExpanded()`,
 > `autoResetExpanded: false`; pass `autoResetExpanded: true` to have a new
 > `data` array close the panels.
 
+## A wider cell on an open row
+
+To have an open row show something wider in the row itself - a title across
+the columns, say - give that column a `meta.colSpan` that depends on
+`row.getIsExpanded()`. See [Spanning columns](/docs/columns#spanning-columns).
+
 ## The two kinds of expanding
 
 TanStack keeps one `expanded` state, and the grid uses it for two unrelated
@@ -119,8 +128,36 @@ not select or highlight the row underneath. It carries
 `data-dg-part="details"` with the row's `data-row-id`. See
 [Testing](/docs/testing).
 
+The panel has no padding. Its content starts at the row's left edge and ends at
+its right edge, so a nested grid, a tab strip or an image fills the row. Give
+content that should line up with the cell text `padding: var(--dg-padding)`,
+the [cell padding](/docs/styling#css-variables) of the grid's `size`.
+
 Group rows have no panel. Expanding one opens its children.
 
+Rows are virtualized. A row that leaves the viewport and the `overscan`
+unmounts, and its panel unmounts with it, so state held inside the panel is
+lost. Keep such state outside the grid, keyed by `row.id`. Rows pinned to an
+edge never unmount.
+
+`renderDetails` runs on every render of the body. Give a heavy panel a memoized
+component and pass it the record, not the row:
+
+```tsx
+const EmployeeDetails = memo(function EmployeeDetails({ employee }: { employee: Employee }) {
+  return <EmployeeCard employee={employee} />;
+});
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  renderDetails: ({ row }) => <EmployeeDetails employee={row.original} />,
+});
+```
+
+Key a stateful child by `row.id`; that is stable only when `getRowId` returns
+the entity id.
+
 ## Reference
 
 | Name | Kind | Type | Default | What it does |

package/docs/row-interaction.md

@@ -22,7 +22,7 @@ hint: Click, double-click and right-click anywhere in the body.
 
 | Prop | Argument | Notes |
 | --- | --- | --- |
-| `onRowClick` | `row` | Rows show a pointer cursor when set. |
+| `onRowClick` | `row` | Rows show a pointer cursor and the [hover tint](/docs/row-styling#hover) when set. |
 | `onCellClick` | `{ cell, row, column, event }` | The cell cursor still moves. |
 | `onCellDoubleClick` | same | A double-click that opens an editor still does. |
 | `onCellContextMenu` | same | `renderRowContextMenu` and the cell-selection menu still open. |
@@ -100,7 +100,7 @@ copy and export items too. By default they appear above a divider and yours
 below, which is what happens when the render prop does not use `internalItems`.
 See [Cell selection](/docs/cell-selection#copy-and-export).
 
-`internalItems` is those built-in items. **Using it takes over the
+`internalItems` holds those built-in items. **Using it takes over the
 composition**: the menu becomes exactly what you return, in the order you
 return it.
 

package/docs/row-selection.md

@@ -18,8 +18,7 @@ file: rows/SelectionModes.tsx
 ## The four modes
 
 `selectionMode` sets what selecting looks like and what a bare row click does.
-A click can toggle a multi-selection or move a highlight, not both, so the two
-are one option rather than two.
+A bare click either toggles the selection or moves the highlight, never both.
 
 | Mode | Checkbox column | Row click |
 | ---- | --------------- | --------- |
@@ -28,8 +27,8 @@ are one option rather than two.
 | `"checkboxAndHighlight"` | yes, multi-select | highlights one row |
 | `"highlight"` | no | highlights one row - no selection at all |
 
-The first two write to TanStack's `rowSelection`, so the toolbar count,
-`getSelectedRowModel()` and persistence all behave the same either way.
+The first two write to TanStack's `rowSelection`, so `getSelectedRowModel()`
+and `onRowSelectionChange` behave the same either way.
 
 Under `"row"` the click follows the usual desktop-list conventions: a plain
 click replaces the selection with this row, Ctrl/Cmd toggles it and leaves the
@@ -71,9 +70,9 @@ For a panel that opens under the row instead of beside the grid, see
 
 Read the selection through the table store with TanStack Store's
 [`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference), rather
-than by calling a method directly. The table identity is stable across renders,
-so the React Compiler caches a bare `getSelectedRowModel()` call and the
-toolbar stops updating.
+than by calling a method directly. A bare read is stale in any component that
+does not call `useTMDataGrid` itself, and under the React Compiler also in the
+one that does; `useSelector` subscribes either way.
 
 ```tsx
 const selected = useSelector(

package/docs/row-styling.md

@@ -95,6 +95,21 @@ virtualization rather than sticking to particular records.
 
 Pinned rows are not striped: they have left the scrolling order.
 
+## Hover
+
+A row takes the hover tint under the pointer when the row itself answers a
+gesture: `selectionMode: "row"` or a highlight mode, `onRowClick`, or
+`renderRowContextMenu`. A grid with none of those shows no hover tint, and a
+group row never does, since it sits out those gestures.
+
+`highlightOnHover` overrides that: `true` tints every row, `false` none.
+
+```tsx
+<TMDataGrid.Table highlightOnHover={false} />
+```
+
+A row carries `data-highlight-on-hover="true"` while the tint applies.
+
 ## Styling by state
 
 Rows carry data attributes for their state, so a stylesheet can target any of
@@ -108,6 +123,7 @@ it without a callback:
 | `data-grouped` | Group rows |
 | `data-depth` | Every row. The nesting level |
 | `data-context-menu` | The row whose context menu is open |
+| `data-highlight-on-hover` | Rows that take the hover tint. See [Hover](#hover) |
 | `data-row-id` | Every row. Its id, which [tests](/docs/testing) key off |
 
 The state attributes are present, with the value `"true"`, only on the rows
@@ -127,6 +143,7 @@ they apply to, so the bare attribute and the value match the same rows:
 | `rowStyle` | Table prop | `TMDataGridRowStyle \| (row) => TMDataGridRowStyle` | – | Inline style for a body row. |
 | `rowClassName` | Table prop | `string \| (row) => string \| undefined` | – | Class for a body row, added after the grid's own. |
 | `striped` | Table prop | `boolean` | `false` | Every second row takes `--dg-row-striped-bg`. |
+| `highlightOnHover` | Table prop | `boolean` | On for rows that answer a click or a right-click | Whether a body row takes the hover tint. |
 | `TMDataGridRowStyle` | Export | type | – | `CSSProperties` or an object of `--*` custom properties. |
 | `--row-bg` | CSS variable | colour | – | The row's own background, composed over the body colour and under hover, selection and range. |
 | `--dg-row-striped-bg` | CSS variable | colour | Themed | The stripe colour. |

package/docs/scrolling.md

@@ -103,7 +103,7 @@ boundary and the pinned band is always on.
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
 | `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](/docs/styling#the-size-scale) | 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. Answers whether it could be reached. |
 | `TMDataGridScrollToRowArgs` | Type | `{ rowId, align? }` | – | What `scrollToRow` takes. |
 | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |

package/docs/server-side.md

@@ -64,7 +64,7 @@ column manager behave identically in both modes.
 
 ## The page index
 
-A column filter, the quick search or a sort changes what page 3 means.
+A column filter, the quick search, a sort or a grouping changes what page 3 means.
 The result set is a different one, and it may not have a page 3 at all - so the grid resets `pageIndex` to 0 whenever the query changes, on every grid.
 The reset is applied in the same event as the change, so one request goes out, for the first page of the new query.
 
@@ -139,6 +139,8 @@ even though they are no longer mounted. Read the state rather than the row
 models:
 
 ```ts
+// In an event handler. In render, subscribe instead:
+// useSelector(grid.table.store, (state) => Object.keys(state.rowSelection))
 const selectedIds = Object.keys(grid.table.store.state.rowSelection);
 ```
 

package/docs/testing.md

@@ -66,6 +66,24 @@ const cell = orders.locator(
 Body cells carry no `data-dg-part`; the coordinate pair identifies them.
 The `editor` part of an open cell carries the same pair, so `:not([data-dg-part])` keeps the locator on the cell while the cell is being edited.
 
+The generated lanes are columns like any other, with exported ids:
+
+| Constant | `data-column-id` | Lane |
+| --- | --- | --- |
+| `ROW_NUMBER_COLUMN_ID` | `__rowNumber__` | Row numbers |
+| `SELECT_COLUMN_ID` | `__select__` | Selection checkboxes |
+| `GROUP_COLUMN_ID` | `__group__` | The grouping tree |
+| `DETAILS_COLUMN_ID` | `__details__` | Details toggles |
+| `EDIT_COLUMN_ID` | `__edit__` | Row editing |
+
+A lane's header is `[data-dg-part="header"][data-column-id="__select__"]` and
+a lane cell `[data-row-id="42"][data-column-id="__select__"]:not([data-dg-part])`.
+The control inside a lane cell has a part of its own, keyed by the row:
+`select-row`, `details-toggle`, `group-toggle` and the edit lane's buttons (see
+[Keyed by `data-row-id`](#keyed-by-data-row-id)); `select-all` and
+`details-toggle-all` sit in the lane headers. The checkbox parts are on the
+`<input>` itself, so `check()` works on them directly.
+
 **The body scrolls inside the scroll container.** The element carrying
 `data-dg-scroll-container` is the one to scroll in a test, whether to load the
 next page of an infinite-scroll grid or to move the virtualizer without the api: