@jielga/tmdatagrid 2.1.4 → 2.3.0

package/docs/use-tm-data-grid.md

@@ -4,7 +4,7 @@ Creates the table instance and the state used by the grid interface.
 
 ```tsx
 const grid = useTMDataGrid<TData>(options);
-// { table, ui, features }
+// TMDataGridApi<TData>, see Return value
 ```
 
 Spread the result onto `TMDataGrid`.
@@ -16,48 +16,69 @@ including `data`, `columns`, `getRowId`, `state` and the `onXChange` callbacks
 (see [Controlled state](#controlled-state)), the `manual*` flags and `rowCount`.
 The `features` option is supplied internally and cannot be overridden.
 
-`persist`, `enableColumnOrdering`, `enablePagination`, `selectionMode`,
+The grid defines these options itself: `persist`, `labels`, `editing`,
+`filters`, `exportOptions`, `enableColumnOrdering`, `enablePagination`,
+`resetPageOnQueryChange`, `enableRowNumbers`, `selectionMode`,
 `showSelectedBackground`, `defaultHighlightedRowId`, `onHighlightedRowChange`,
-`renderDetails`, `renderDetailsEstHeight`, `overscan`, `cellSelection`,
-`onFocusedCellChange`, `quickSearchMode`, `labels` and `editing`
-(see [Editing](/docs/editing)) are the grid's own options and are consumed here
-rather than forwarded to TanStack.
+`cellSelection`, `onFocusedCellChange`, `renderDetails`,
+`renderDetailsEstHeight`, `detailsColumnPosition`, `overscan`,
+`quickSearchMode` and `enableMatchHighlighting`. The table below marks them
+"Defined by the grid"; every other row is a TanStack option, listed where the
+grid changes its default or where it decides something visible. A TanStack
+default the grid changes reads, for example, `"remove"` (grid default;
+TanStack: `"reorder"`). A TanStack option that is not listed passes through
+with TanStack's own default.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `data` | `TData[]` | – | Row data. When the reference changes the table reprocesses the row models, so keep it stable with `useMemo`. |
-| `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. |
-| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. |
+| `data` | `TData[]` | – | Row data. When the reference changes the table reprocesses the row models, so keep it stable with `useMemo`; a fresh `[]` for the empty case belongs in a module-scope constant. |
+| `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. Define them outside the component. |
+| `getRowId` | `(row, index, parent?) => string` | Row index | The id that row selection, expansion, row pinning and editing are keyed by. The index points at another record after a sort or a refetch, so return the entity id. Required once `editing` is set. |
+| `defaultColumn` | `Partial<ColumnDef>` | `{ minSize: 80 }` (grid default; TanStack: `{}`) | Defaults merged under every column. The grid sets `filterFn: "tmDataGrid"` and clears `aggregationFn` and `aggregatedCell` on every column, so those three keys have no effect here; a value on the column wins. |
 | `enableRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes row selection and its checkbox column. |
+| `enableMultiRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes the select-all checkbox and limits the selection to one row. |
 | `selectionMode` | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a bare row click does. Defined by the grid, see [Row selection](/docs/row-selection). |
 | `showSelectedBackground` | `boolean` | On for `"row"`, off for `"checkbox"` | Determines whether selected rows take a background tint, coloured by `--dg-row-selected-bg`. Defined by the grid, see [Row selection](/docs/row-selection). |
-| `defaultHighlightedRowId` | `string \| null` | – | Row highlighted on mount, under a mode with a highlight. Read once, like `initialState`. |
-| `onHighlightedRowChange` | `(rowId: string \| null) => void` | – | Follows the highlighted row, from clicks and from `ui.actions.setHighlightedRow`. |
-| `enableSorting` | `boolean` | `true` | Enables sorting for the table. |
-| `enableColumnFilters` | `boolean` | `true` | Enables filtering for the table. |
-| `enableHiding` | `boolean` | `true` | Enables column visibility for the table. |
+| `defaultHighlightedRowId` | `string \| null` | – | Row highlighted on mount, under a mode with a highlight. Read once, like `initialState`. Defined by the grid. |
+| `onHighlightedRowChange` | `(rowId: string \| null) => void` | – | Follows the highlighted row, from clicks and from `ui.actions.setHighlightedRow`. Defined by the grid. |
+| `enableSorting` | `boolean` | `true` | `false` removes the sort indicator, the sort menu items and click-to-sort. Also a column option. See [Sorting](/docs/sorting). |
+| `enableMultiSort` | `boolean` | `true` for accessor columns | Shift+click on a header adds a sort instead of replacing it. Also a column option. See [Sorting](/docs/sorting). |
+| `maxMultiSortColCount` | `number` | `Number.MAX_SAFE_INTEGER` | How many sorts are kept; past it the oldest is dropped. |
+| `enableColumnFilters` | `boolean` | `true` | `false` removes the filter menu item, the `FilterButton`, the header filter row and the panel's column list, and disables the panel's "Add filter" button. Filters already in state still apply. See [Filtering](/docs/filtering#turning-it-off). |
+| `enableGlobalFilter` | `boolean` | `true` | `false` removes `Search`. Also a column option, removing one column from the search. See [Quick search](/docs/quick-search). |
+| `globalFilterFn` | filter fn \| name | `"tmDataGridFuzzy"`; `"includesString"` under `quickSearchMode: "contains"` (grid default; TanStack: `"auto"`) | How the quick search matches. An explicit value also switches the fuzzy rank ordering off. |
+| `enableHiding` | `boolean` | `true` | `false` removes the Hide column item, the Manage columns submenu and the column chooser. Also a column option. |
 | `enableColumnPinning` | `boolean` | `true` | Enables pinning for the table. `false` removes the pin menu items; the generated lanes stay pinned. |
-| `enableColumnResizing` | `boolean` | `true` | Enables resizing for the table. |
+| `enableColumnResizing` | `boolean` | `true` | With `false` the divider is displayed but cannot be dragged, and double-click autosize and the Autosize menu item are removed. Also a column option, as `enableResizing`. |
 | `enableColumnOrdering` | `boolean` | `true` | Enables header dragging and the move menu items. Defined by the grid, see [Column layout](/docs/column-layout#ordering). |
+| `enableGrouping` | `boolean` | `true`; `false` under `manualPagination` (grid default; TanStack: `true`) | `false` removes the Group by and Ungroup menu items and the tree lane. Also a column option. See [Grouping](/docs/grouping). |
+| `groupedColumnMode` | `"remove" \| "reorder" \| false` | `"remove"` (grid default; TanStack: `"reorder"`) | What happens to a column the rows are grouped by: `"remove"` takes it out of the grid, `"reorder"` moves it to the front, `false` leaves it in place. See [Grouping](/docs/grouping). |
 | `enablePagination` | `boolean` | `false` | Enables client-side paging and the `Footer` pager. Implied by `manualPagination`. Defined by the grid, see [Pagination](/docs/pagination). |
+| `resetPageOnQueryChange` | `boolean` | `true` | Returns to the first page when a column filter, the quick search, the sorting or the grouping changes through the table. A `data` change does not count. Defined by the grid, see [Pagination](/docs/pagination). |
+| `autoResetPageIndex` | `boolean` | `false` (grid default; TanStack: `!manualPagination`) | TanStack's return to the first page on every `data` change. Off, since `resetPageOnQueryChange` covers the query. |
+| `autoResetExpanded` | `boolean` | `false` (grid default; TanStack: `!manualExpanding`) | TanStack's collapse of every expanded row on a `data` change. Off, so open details panels survive a refetch. |
+| `manualFiltering`, `manualSorting`, `manualGrouping`, `manualPagination` | `boolean` | `false` | The server does that step and the grid shows `data` as given. `manualPagination` also implies `enablePagination`. See [Server-side data](/docs/server-side). |
+| `rowCount` | `number` | – | The total row count under `manualPagination`, read by the pager. |
 | `enableRowNumbers` | `boolean` | `false` | The row-number gutter, outermost left. Defined by the grid, see [Row pinning and numbering](/docs/row-pinning). |
-| `enableRowPinning` | `boolean \| (row) => boolean` | `false` | Rows can be pinned to sticky edge blocks with `row.pin()`. See [Row pinning and numbering](/docs/row-pinning). |
+| `enableRowPinning` | `boolean \| (row) => boolean` | `false` (grid default; TanStack: `true`) | Rows can be pinned to sticky edge blocks with `row.pin()`. See [Row pinning and numbering](/docs/row-pinning). |
 | `quickSearchMode` | `"fuzzy" \| "contains"` | `"fuzzy"` | How `Search` matches. Fuzzy forgives typos and orders unsorted results by match quality; `"contains"` is plain substring matching. Defined by the grid, see [Quick search](/docs/quick-search). |
 | `enableMatchHighlighting` | `boolean` | `false` | Cells mark the matched text while a contains-family filter or the quick search is active. Defined by the grid, see [Quick search](/docs/quick-search#match-highlighting). |
 | `renderDetails` | `({ row, table }) => ReactNode` | – | Panel rendered under an expanded row, spanning every column. Setting it turns row details on and adds the pinned chevron lane. Defined by the grid, see [Row details](/docs/row-details). |
-| `renderDetailsEstHeight` | `number` | `160` | What the virtualizer assumes for a panel it has not measured yet. Panels are measured once mounted, so an approximation is enough. |
+| `renderDetailsEstHeight` | `number` | `160` | What the virtualizer assumes for a panel it has not measured yet. Panels are measured once mounted, so an approximation is enough. Defined by the grid. |
 | `detailsColumnPosition` | `"left" \| "right"` | `"left"` | Which edge the details lane is pinned to. `"right"` places it after every column, inside the edit lane. Defined by the grid, see [Row details](/docs/row-details). |
 | `cellSelection` | `"none" \| "single" \| "range"` | `"none"` | Cell cursor and, under `"range"`, a selectable rectangle with Ctrl+C and CSV export. Defined by the grid, see [Cell selection](/docs/cell-selection). |
-| `onFocusedCellChange` | `(cell: TMDataGridCellPosition \| null) => void` | – | Called whenever the focused cell moves, by key, click or `setFocusedCell`. |
-| `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Raise it if fast scrolling flashes blank rows, lower it when rows are expensive to render. |
+| `onFocusedCellChange` | `(cell: TMDataGridCellPosition \| null) => void` | – | Called whenever the focused cell moves, by key, click or `setFocusedCell`. Defined by the grid. |
+| `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Raise it if fast scrolling flashes blank rows, lower it when rows are expensive to render. Defined by the grid. |
 | `columnResizeMode` | `"onChange" \| "onEnd"` | `"onEnd"` | When a resize drag writes `columnSizing`. The grid paints a running drag itself either way; `"onChange"` also publishes a width on every pointer move, which re-renders the grid with each of them. |
 | `initialState` | `Partial<TableState>` | – | Starting state, read once on mount. Merged over the [grid defaults](#default-initial-state). |
 | `state` | `Partial<TableState>` | – | Controlled state. Each slice requires its `onXChange`. See [Controlled state](#controlled-state). |
 | `atoms` | `Partial<Record<slice, Atom>>` | – | External atoms owning state slices. No callback required. Takes precedence over `state`. |
 | `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration. See [meta](#meta). |
-| `filters` | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Where the filter controls go - a popup, a sidebar, the column headers, or nowhere. See [Filtering](/docs/filtering#the-filters-option). |
-| `persist` | `TMDataGridPersistence` | – | State persistence. See [persist](#persist). |
-| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings, see [Localization](#localization). |
+| `filters` | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Where the filter controls go - a popup, a sidebar, the column headers, or nowhere. Defined by the grid, see [Filtering](/docs/filtering#the-filters-option). |
+| `exportOptions` | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | The export's `format`, `fileName`, `includeHeaders` and `columns`. Defined by the grid, see [Export](/docs/export). |
+| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. `mode` picks what counts as a commit and `draft` whether edits collect in the draft store. Requires `getRowId`. Defined by the grid, see [Editing](/docs/editing). |
+| `persist` | `TMDataGridPersistence` | – | State persistence. Defined by the grid, see [persist](#persist). |
+| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. Defined by the grid, see [Localization](#localization). |
 
 ### Default initial state
 
@@ -66,7 +87,6 @@ rather than forwarded to TanStack.
 | `pagination` | `{ pageIndex: 0, pageSize: 25 }`. Inert until pagination is enabled |
 | `columnPinning.start` | The row number, checkbox, tree and details columns, followed by any columns you provide. The details column moves to `end` under `detailsColumnPosition: "right"` |
 | `columnPinning.end` | Any columns you provide, then the details column under `detailsColumnPosition: "right"`, then the edit column |
-| `globalFilterFn` | `"tmDataGridFuzzy"`, the fuzzy matcher behind `quickSearchMode`. `"includesString"` under `quickSearchMode: "contains"` |
 
 ### Controlled state
 
@@ -110,10 +130,10 @@ Grid configuration, passed through the `meta` option.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `loading` | `boolean` | – | Displays a loader while the grid is empty. Takes precedence over every empty state. |
+| `loading` | `boolean` | `false` | Displays a loader while the grid is empty. Takes precedence over every empty state. |
 | `noResultsLabel` | `string` | `"No rows match your filters"` | The filtered-empty message. A grid with no data and no filters says `labels.noRows` instead; `renderEmptyState` on the Table replaces both. |
 | `rowHeight` | `number` | From `size` | Row height in px. Overrides the size scale. |
-| `totalRowCount` | `number` | – | Unfiltered total used by `SummaryCount`. Required for server-side data. |
+| `totalRowCount` | `number` | – | Unfiltered total used by `SummaryCount`. Without it a `manualFiltering` or `manualPagination` grid shows the shown count alone. |
 
 ## Localization
 
@@ -161,13 +181,16 @@ toolbar components can read the same strings as the built-in parts.
 ## persist
 
 Restores table state on mount and writes it back on every change. State is
-split across two keys: `settingsKey` for the column layout, `dataKey` for
-filters, sorting and pagination. Either can be cleared without the other.
+split across three keys: `settingsKey` for the column layout, `dataKey` for
+filters, sorting and pagination, and `urlKey` for data slices kept in the URL
+as a deep link. Each can be cleared without the others.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataKey` | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `urlKey` | `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](/docs/persistence#deep-links). |
+| `urlStorage` | `TMDataGridUrlStorage` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `storageMode` | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. Use `"sessionStorage"` for per-tab state. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes a payload before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
@@ -202,6 +225,7 @@ const persist = {
 | Group | Available slices |
 | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey`. |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
 
 The exported `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` arrays contain the
@@ -247,6 +271,7 @@ identifier if several users can share a browser profile.
 | `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
 | `ui` | `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
 | `filters` | `TMDataGridFiltersSettings` | The `filters` option with its defaults filled in. See [Filtering](/docs/filtering#the-filters-option). |
+| `exportOptions` | `TMDataGridExportSettings` | The `exportOptions` option with its defaults filled in. See [Export](/docs/export). |
 | `edit` | `TMDataGridEditApi` | The edit engine, inert until `editing` is set. See [Editing](/docs/editing). |
 | `features` | `TMDataGridFeatureFlags` | Table-level feature switches, re-read from options on each render. See [Toolbar](/docs/toolbar#reading-options-reactively). |
 | `labels` | `TMDataGridLabels` | The resolved label set, overrides merged over English. See [Localization](/docs/localization). |
@@ -278,22 +303,34 @@ The identity is stable, so it is safe in a dependency array. Before
 `TMDataGrid.Table` has mounted there is nothing to scroll and it returns
 `false`.
 
-Both stores are subscribable, so a parent component can react to grid state
-without holding it:
+### Reading state
+
+`table.store` and `ui` are TanStack stores. Read a slice with `useSelector`
+from `@tanstack/react-store`, which subscribes the component to what the
+selector returns:
 
 ```tsx
 import { useSelector } from "@tanstack/react-store";
 
 const selectedCount = useSelector(
   grid.table.store,
-  (state) => Object.keys(state.rowSelection).length,
+  () => grid.table.getSelectedRowModel().rows.length,
 );
-
+const isGrouped = useSelector(grid.table.store, (state) =>
+  state.grouping.includes("department"),
+);
+const pageIndex = useSelector(grid.table.store, (state) => state.pagination.pageIndex);
 const filterPanelOpen = useSelector(grid.ui, (state) => state.filterPanelOpen);
 ```
 
-Read state with `useSelector` rather than `grid.table.store.state`. A direct
-read does not subscribe the component to the store.
+`grid.table.store.state` is a plain read and does not subscribe the component.
+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. A table or column getter such as
+`table.getSelectedRowModel()` or `column.getIsGrouped()` is a plain read as
+well; call it inside a selector, as above. Note that `table.getState()` does
+not exist in TanStack Table v9, and `table.state` is not part of
+`TMDataGridTable`.
 
 ### ui actions
 
@@ -301,6 +338,8 @@ read does not subscribe the component to the store.
 | --- | --- |
 | `openFilterPanel` | `(columnId?: string \| null) => void` |
 | `closeFilterPanel` | `() => void` |
+| `openExportPicker` | `(request: TMDataGridExportPickerRequest) => void` |
+| `closeExportPicker` | `() => void` |
 | `focusPanelFilter` | `(columnId: string \| null) => void` |
 | `focusHeaderFilter` | `(columnId: string \| null) => void` |
 | `startColumnDrag` | `(columnId: string) => void` |
@@ -316,7 +355,7 @@ focus follows `focusedCell` while the grid holds it, scrolling the row into view
 when it is off screen.
 
 `startColumnDrag` and `endColumnDrag` are called by the header cells while a
-column is being dragged. `ui.draggedColumnId` holds the column being moved,
+column is being dragged. `ui.state.draggedColumnId` holds the column being moved,
 since `dataTransfer` is unreadable until the drop.
 
 `openColumnFilter(grid, columnId)` combines two steps used by the column menu:
@@ -342,7 +381,7 @@ to off; ordering, like the options around it, defaults to on.
 | Option | Level | Interface removed |
 | --- | --- | --- |
 | `enableSorting: false` | Table, column | Sort indicator, sort menu items, click-to-sort. See [Sorting](/docs/sorting) |
-| `enableColumnFilters: false` | Table | Filter menu item, `FilterButton`, filter panel, header filter row. See [Filtering](/docs/filtering) |
+| `enableColumnFilters: false` | Table | Filter menu item, `FilterButton`, header filter row, the panel's column list; the panel's "Add filter" button is disabled. Filters already in state still apply, with their pills and header indicators. See [Filtering](/docs/filtering#turning-it-off) |
 | `enableColumnFilter: false` | Column | That column's filter menu item, panel entry and header control |
 | `enableGlobalFilter: false` | Table, column | `Search`: the whole input at table level, one column's participation at column level |
 | `enableHiding: false` | Table, column | Hide column, Manage columns, `TMDataGrid.Menu.Columns`. See [Column layout](/docs/column-layout) |
@@ -359,6 +398,6 @@ to off; ordering, like the options around it, defaults to on.
 | `enableRowNumbers: true` | Table | Opt-in: the row-number gutter, outermost left. Numbers the current view: sorted, filtered, continuing across pages. Group rows take no number |
 | `enableRowPinning: true` | Table | Opt-in: rows can be pinned to sticky edge blocks with `row.pin()`. Also takes a per-row predicate. See [Row pinning](/docs/row-pinning) |
 | `enableMatchHighlighting: true` | Table | Opt-in: cells mark the matched text while a contains-family filter or the quick search is active. See [Quick search](/docs/quick-search#match-highlighting) |
-| `enableGrouping: false` | Table, column | Group by and Ungroup menu items. See [Grouping](/docs/grouping) |
+| `enableGrouping: false` | Table, column | Group by and Ungroup menu items, and the tree lane at table level. The default is `false` under `manualPagination`. See [Grouping](/docs/grouping) |
 | `renderDetails` | Table | Opt-in: adds the details lane, and an expanded row opens a panel underneath it. See [Row details](/docs/row-details) |
 | `detailsColumnPosition: "right"` | Table | The details lane on the right edge, inside the edit lane, instead of the left. See [Row details](/docs/row-details) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.1.4",
+  "version": "2.3.0",
   "description": "A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.",
   "license": "MIT",
   "type": "module",

package/skills/appearance/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/styling.md'
   - 'Jielga/react:packages/tmdatagrid/docs/toolbar.md'
@@ -250,7 +250,9 @@ const labels = {
 `TMDataGridLabels` is the full dictionary type, so a missing key in a new
 translation is a compile error. The resolved dictionary comes back as
 `grid.labels` and from `useTMDataGridContext().labels`, so a component of your
-own uses the same strings as the built-in parts.
+own uses the same strings as the built-in parts. Every key, with its English
+default and where the grid shows it, is in
+[references/labels.md](references/labels.md).
 
 ## Common mistakes
 
@@ -319,7 +321,7 @@ const { canSort } = getColumnCapabilities(column, features);
 if (!canSort) return null;
 ```
 
-Source: `packages/tmdatagrid/docs/toolbar.md` (Why `features` is a second argument).
+Source: `packages/tmdatagrid/docs/toolbar.md` (Reading options reactively).
 
 ### MEDIUM An inline `labels` object
 
@@ -370,7 +372,7 @@ Source: `packages/tmdatagrid/docs/toolbar.md` (The built-in parts).
 | `grid.labels` | Hook return | `TMDataGridLabels` | – | The resolved dictionary. |
 | `TMDATAGRID_LABELS_EN` · `TMDATAGRID_LABELS_SV` | Exports | `TMDataGridLabels` | – | The English base, and a complete Swedish dictionary. |
 | `TMDataGridLabels` · `TMDataGridLabelsOverride` | Exports | types | – | The full dictionary, and a partial one. |
-| `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. |
 
 The CSS layer name `tmdatagrid` in `styles.layer.css` is public API and never

package/skills/appearance/references/labels.md

@@ -0,0 +1,126 @@
+# TMDataGrid labels
+
+Reference for the `appearance` skill: every key of `TMDataGridLabels`, its English default, and where the grid shows it; a function label shows its template.
+`TMDataGridLabels` has a fixed set of keys, so a full translation sets every key.
+The `labels` option takes a partial override, `TMDataGridLabelsOverride`, merged over English key by key; `operators` merges per operator.
+
+| 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. |

package/skills/cell-selection/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/cell-selection.md'
   - 'Jielga/react:packages/tmdatagrid/src/core/cellNavigation.ts'
@@ -215,7 +215,7 @@ Source: `packages/tmdatagrid/docs/cell-selection.md` (Copy and export).
 | --- | --- | --- | --- | --- |
 | `cellSelection` | Option | `TMDataGridCellSelectionMode`: `"none" \| "single" \| "range"` | `"none"`, or `"single"` under `editing` | Turns the cursor, and the rectangle, on. |
 | `onFocusedCellChange` | Callback | `(cell \| null) => void` | – | Follows the cursor. |
-| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row of the Export cells item. |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | Format, file name and header row of the Export cells item. |
 | `ui.state.focusedCell` | UI state | `{ rowId, columnId } \| null` | `null` | The cursor. |
 | `ui.state.cellRange` | UI state | `{ anchor, focus } \| null` | `null` | The rectangle's two corners. |
 | `ui.actions.setFocusedCell` · `setCellRange` | UI actions | – | – | Move either from your own code. |