@jielga/tmdatagrid 2.0.0 → 2.0.1

package/docs/columns.md

@@ -263,6 +263,7 @@ column can be placed in front of it.
 | `meta.edit` | Column meta | `TMDataGridColumnEditOptions` | – | How the column edits: `enabled`, `field`, `editor`, `validate`, `mapValue`. |
 | `resolveColumnOptions` | Export | `({ table, column, row? }) => options` | – | Normalises all three `meta.options` forms. |
 | `optionsToComboboxData` | Export | `(options) => ComboboxData` | – | Options as Mantine `Select` data. |
-| `getColumnLabel` · `getColumnType` · `isControlColumn` | Exports | `(column) => …` | – | How the built-in controls read a column. |
+| `getColumnLabel` · `getColumnType` | Exports | `(column) => …` | – | How the built-in controls read a column. |
+| `isControlColumn` | Export | `(columnId) => boolean` | – | Whether a column id is one of the generated control lanes: checkbox, details, edit or row number. |
 | `isGeneratedColumn` | Export | `(columnId) => boolean` | – | Whether the grid generated the column - the four control lanes plus the tree column. |
 | `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | `string` | – | Ids of the five generated lanes. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/styling.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/cell-selection.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/cellNavigation.ts'
@@ -213,16 +213,18 @@ Source: `packages/tmdatagrid/docs/cell-selection.md` (Copy and export).
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `cellSelection` | Option | `"none" \| "single" \| "range"` | `"none"`, or `"single"` under `editing` | Turns the cursor, and the rectangle, on. |
+| `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. |
 | `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. |
 | `buildExportData` | Export | `({ table, rows, bounds }) => TMDataGridExportData` | – | The rectangle's values, with `bounds`; the whole grid without. |
-| `toClipboardText` · `writeClipboardText` | Exports | – | – | The pieces behind Ctrl+C. |
+| `toClipboardText` · `writeClipboardText` | Exports | `(data, options?) => string` · `(text) => Promise<boolean>` | – | The pieces behind Ctrl+C: the tab-separated text, and the write that reports whether it landed. |
+| `TMDataGridClipboardTextOptions` | Type | `{ decimalComma?, escapeFormulas? }` | `true` · `true` | The options of `toClipboardText`. |
 | `formatExportValue` | Export | `(value, options) => string` | – | One value, formatted as the text formats would. |
 | `resolveRangeBounds` | Export | `({ range, rowIndexOf, columnIndexOf }) => TMDataGridRangeBounds \| null` | – | The range as row and column indices - the `bounds` for `buildExportData`, over `getDisplayedRows`. |
+| `ResolveRangeBoundsArgs` · `TMDataGridRangeBounds` | Types | – · `{ top, bottom, left, right }` | – | What `resolveRangeBounds` takes, and what it returns. |
 | `data-focused` | Data attribute | – | – | On the focused cell. |
 | `data-edge-top` · `-bottom` · `-left` · `-right` | Data attributes | – | – | On cells at the rectangle's border. |
 

package/skills/columns/SKILL.md

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/columns.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/column-layout.md'
@@ -93,23 +93,9 @@ 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`:
-
-| Field | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `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. |
-
-`meta.edit`:
-
-| Field | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
-| `field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
-| `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
-| `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
-| `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+`meta.filter` holds `operators`, `defaultOperator` and `control`; `meta.edit`
+holds `enabled`, `field`, `editor`, `validate` and `mapValue`. Their fields are
+in [references/columns-api.md](references/columns-api.md).
 
 ```tsx
 meta: {
@@ -119,6 +105,14 @@ meta: {
 }
 ```
 
+The type of `meta` is `TMDataGridColumnMeta<TData>`. On a column declared with
+`createTMDataGridColumnHelper<TData>()`, the `row` that a `meta.options`
+function and a `meta.edit.enabled` function receive is
+`Row<TMDataGridFeatures, TData>`, so `row.original` needs no cast and no
+annotation. A column written without the helper keeps the untyped row,
+`Row<TMDataGridFeatures, TMDataGridRowData>`, where `row.original` is
+`Record<string, unknown>`.
+
 `enableOrdering` lives in `meta` because column ordering is the one feature
 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.
@@ -141,6 +135,28 @@ columnHelper.accessor("department", {
 Dates travel as ISO `YYYY-MM-DD` strings and booleans as `"true"` / `"false"`,
 so the filter model stays plain JSON whatever the type.
 
+### meta.options
+
+`meta.options` is a list of `TMDataGridOption`s
+(`{ value, label?, color?, disabled?, group? }`) or bare strings, `"faceted"`
+for the distinct values in the data, or a function of `TMDataGridOptionsArgs`
+(`{ table, column, row? }`). `row` is set when a cell editor asks and absent for
+the filter panel:
+
+```tsx
+meta: {
+  type: "select",
+  options: ({ row }) => (row ? citiesFor(row.original.country) : allCities),
+}
+```
+
+`resolveColumnOptions({ table, column, row? })` normalises all three forms into
+`Array<TMDataGridOption>` for a custom control, and `optionsToComboboxData`
+turns that list into Mantine `Select` / `MultiSelect` data. A select column with
+no options still filters, on the faceted values.
+
+Source: `packages/tmdatagrid/docs/columns.md` (Options).
+
 ## Sizing
 
 Columns are fluid. Each track is `minmax(minSize, flex fr)`.
@@ -276,7 +292,7 @@ asks for it.
 
 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(column)`
+region, so no column can be placed in front of it. `isControlColumn(columnId)`
 identifies them.
 
 ## Common mistakes
@@ -466,28 +482,11 @@ columnHelper.accessor("pctOfTotal", { header: "Share" });
 
 Source: `packages/tmdatagrid/docs/columns.md` (Columns derived from the other rows).
 
-## Reference
-
-| Name | Kind | Type | Default | What it does |
-| --- | --- | --- | --- | --- |
-| `createTMDataGridColumnHelper` | Export | `<TData>() => helper` | – | The typed column helper. |
-| `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / – | Width bounds, and the fixed width once one applies. |
-| `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. |
-| `sortFn` | Column option | name or `(rowA, rowB, columnId) => number` | `"auto"` | The comparator for one column. Not v8's `sortingFn`. |
-| `initialState.columnOrder` · `.columnPinning` · `.columnVisibility` · `.columnSizing` | Table options | – | – | Layout at mount. Settings slices, persisted under `settingsKey`. |
-| `initialState.sorting` | Table option | `Array<{ id, desc }>` | `[]` | Sort at mount. A data slice, persisted under `dataKey`. |
-| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning and widths. |
-| `moveColumn` | Export | `({ table, columnId, targetId, side }) => void` | – | Moves a column beside another. |
-| `moveColumnByStep` | Export | `({ table, columnId, direction }) => void` | – | Moves it one place. |
-| `getStepTargetColumn` | Export | `(args) => Column \| null` | – | What a step would swap with, or `null` at a region edge. |
-| `getColumnRegion` | Export | `(columnPinning, columnId) => "start" \| "center" \| "end"` | – | Which pinned region a column is in. |
-| `getColumnCapabilities(column, features).canReorder` | Export | `boolean` | – | Whether this column may move at all. |
-| `autosizeColumn` | Export | `({ table, columnId, container }) => void` | – | Fits a column to its mounted content. |
-| `getColumnLabel` · `getColumnType` · `getColumnDefaultOperator` · `isControlColumn` | Exports | – | – | What the built-in controls read off a column. |
-| `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | ids | – | The generated lanes. |
-| `TMDataGrid.Menu.Columns` · `TMDataGrid.ColumnsPanel` | Components | `searchable` · Mantine `BoxProps` | – | The column chooser, as menu items and as plain controls. Style props set on the panel. |
+## References
+
+- [Columns API](references/columns-api.md) - every column option, column meta
+  field, export and type belonging to defining, sizing, hiding, pinning,
+  ordering and sorting columns.
 
 See also: the `filtering` skill for operators and filter controls, the `editing`
 skill for the editing meta fields, and the `grouping` skill for what grouping

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

@@ -0,0 +1,59 @@
+# Columns API
+
+Reference for the `columns` skill.
+
+## meta.filter and meta.edit
+
+`meta.filter` belongs to the `filtering` skill:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `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. |
+
+`meta.edit` belongs to the `editing` skill, and only acts once `editing` is set:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. `row` is typed by the column helper. |
+| `field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
+| `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
+| `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
+| `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+
+## Exports and options
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `createTMDataGridColumnHelper` | Export | `<TData>() => TMDataGridColumnHelper<TData>` | – | The typed column helper. `meta` callbacks receive `Row<TMDataGridFeatures, TData>`. |
+| `TMDataGridColumnHelper` | Type | – | – | The helper's type. |
+| `TMDataGridColumnMeta` | Type | `TMDataGridColumnMeta<TData = TMDataGridRowData>` | – | The type of `meta`. Typed against the row when the column is declared with the helper. |
+| `meta.options` | Column meta | `TMDataGridOptionsSource`: array \| `"faceted"` \| `(args: TMDataGridOptionsArgs) => …` | – | The choices of a `select` / `multiSelect` column. |
+| `TMDataGridOption` | Type | `{ value, label?, color?, disabled?, group? }` | – | One choice. A bare string is shorthand for `{ value }`. |
+| `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. |
+| `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. |
+| `sortFn` | Column option | name or `(rowA, rowB, columnId) => number` | `"auto"` | The comparator for one column. Not v8's `sortingFn`. |
+| `initialState.columnOrder` · `.columnPinning` · `.columnVisibility` · `.columnSizing` | Table options | – | – | Layout at mount. Settings slices, persisted under `settingsKey`. |
+| `initialState.sorting` | Table option | `Array<{ id, desc }>` | `[]` | Sort at mount. A data slice, persisted under `dataKey`. |
+| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning and widths. |
+| `moveColumn` | Export | `({ table, columnId, targetId, side }) => void` | – | Moves a column beside another. |
+| `moveColumnByStep` | Export | `({ table, columnId, direction }) => void` | – | Moves it one place. `direction` is `-1` or `1`. |
+| `MoveColumnArgs` · `ColumnStepArgs` | Types | – | – | What `moveColumn` takes, and what `moveColumnByStep` and `getStepTargetColumn` take. |
+| `TMDataGridDropSide` | Type | `"before" \| "after"` | – | The `side` of `MoveColumnArgs`: which edge of the target column the moved column lands on. |
+| `getStepTargetColumn` | Export | `(args) => Column \| null` | – | What a step would swap with, or `null` at a region edge. |
+| `getColumnRegion` | Export | `(columnPinning, columnId) => TMDataGridColumnRegion` | – | Which pinned region a column is in. |
+| `TMDataGridColumnRegion` | Type | `"start" \| "center" \| "end"` | – | What `getColumnRegion` returns. |
+| `keepGeneratedColumnsOutermost` | Export | `(columnPinning) => ColumnPinningState` | – | Puts the generated lanes back on the outside of both pinned lanes. The grid runs it after every pin; call it on a `columnPinning` you write yourself. |
+| `getColumnCapabilities(column, features).canReorder` | Export | `boolean` | – | Whether this column may move at all. |
+| `autosizeColumn` | Export | `({ table, columnId, container }) => void` | – | Fits a column to its mounted content. |
+| `getColumnLabel` · `getColumnType` · `getColumnDefaultOperator` · `isControlColumn` | Exports | – | – | What the built-in controls read off a column. |
+| `isGeneratedColumn` | Export | `(columnId) => boolean` | – | Whether the grid generated the column - the four control lanes plus the tree column. |
+| `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | ids | – | The generated lanes. |
+| `TMDataGrid.Menu.Columns` · `TMDataGrid.ColumnsPanel` | Components | `searchable` · Mantine `BoxProps` | – | The column chooser, as menu items and as plain controls. Style props set on the panel. |
+| `TMDataGridColumnSearchable` | Type | `boolean \| "auto"` | `"auto"` | The `searchable` prop of both: a search box from six hideable columns under `"auto"`, `true` always, `false` never. |

package/skills/data/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/scrolling.md'
@@ -354,13 +354,17 @@ Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 | `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 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. |
-| `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. |
+| `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. |
+| `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. |
 | `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. |
@@ -371,6 +375,26 @@ Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 | `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. |
+| `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. |
+| `ui.state.exportPicker` | UI state | `TMDataGridExportPickerRequest \| null` | `null` | The column picker while open: `{ rows, options }`. |
+| `getExportableColumns` | Export | `(table) => Array<Column>` | – | Every column an export could take, hidden ones included. The list the picker shows. |
+| `useTMDataGridExport` | Hook | `(overrides?) => TMDataGridExportApi` | – | `exportAll`, `exportSelected`, `selectedCount`, `canExportSelected`. |
+| `exportGrid` | Export | `(args: ExportGridArgs) => Promise<void>` | – | Downloads the grid from outside a component. `ExportGridArgs` is `{ table, rows?, options? }`. |
+| `buildExportData` | Export | `(args: BuildExportDataArgs) => TMDataGridExportData` | – | The columns, labels and values a format writes. `BuildExportDataArgs` is `{ table, rows?, columns?, bounds? }`. |
+| `TMDataGridExportRows` · `TMDataGridExportColumns` | Types | `"all" \| "selected" \| rows` · `"visible" \| "all" \| ReadonlyArray<string>` | `"all"` · `"visible"` | Which rows and which columns an export takes. |
+| `writeExportFile` | Export | `(data, settings) => Promise<void>` | – | Writes export data in a format and downloads it. |
+| `downloadFile` | Export | `({ fileName, content, mimeType }) => void` | – | Downloads a string or a `Blob`. |
+| `csvExcelFormat` · `csvFormat` · `tsvFormat` · `jsonFormat` | Exports | `(options?) => TMDataGridExportFormat` | – | The built-in formats. |
+| `TMDataGridCsvFormatOptions` · `TMDataGridTsvFormatOptions` · `TMDataGridJsonFormatOptions` | Types | – | – | The options of `csvExcelFormat` and `csvFormat`, of `tsvFormat`, and of `jsonFormat`. |
+| `TMDataGridExportWriteOptions` | Type | `{ includeHeaders }` | – | The second argument of a format's `write`. |
+| `guardFormula` · `formatExportValue` | Exports | `(text) => string` · – | – | The formula guard and the text rule, for a format of your own. |
+| `resolveExportOptions` | Export | `(...overrides) => TMDataGridExportSettings` | – | The defaults with overrides folded over, `undefined` fields skipped. |
+| `countSelectedExportRows` | Export | `(table) => number` | – | How many rows `"selected"` would write. |
+| `DEFAULT_EXPORT_OPTIONS` | Constant | `TMDataGridExportSettings` | – | The defaults `exportOptions` merges over. |
+| `TMDataGridExportSettings` | Type | `Required<TMDataGridExportOptions>` | – | Export options with every field set. |
 
 See also: the `server-side` skill for `manualPagination` and `onReachEnd`, and
 the `grouping` skill for why the pager suspends.

package/skills/editing/SKILL.md

@@ -18,13 +18,14 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/draft-store.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/adding-rows.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/query-builder.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editors.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/portfolio-rebalancer.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/editEngine.ts'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
 ---
@@ -259,6 +260,11 @@ tableValidators: {
 }
 ```
 
+Columns derived from the other rows (a weight as a share of the total) plus a
+table-wide rule (targets may not total more than 100%) are worked through in
+[references/editors-and-validation.md](references/editors-and-validation.md),
+from `packages/tmdatagrid/docs/portfolio-rebalancer.md`.
+
 `meta.edit.mapValue` rewrites a value instead of rejecting it: uppercase a code,
 strip spaces from an IBAN, clamp a number. It runs on every write an editor
 makes, so a text input maps per keystroke, and what it returns is what the
@@ -468,8 +474,9 @@ are in [references/common-mistakes.md](references/common-mistakes.md).
 ## References
 
 - [Editors and validation](references/editors-and-validation.md) - the editor
-  API, wrapping a built-in, what `mapValue` leaves alone, field and row
-  validators, server-side errors.
+  API, wrapping a built-in, what `mapValue` leaves alone, field, row and
+  cross-row validators, derived columns with a table-wide rule, server-side
+  errors.
 - [Editing API](references/editing-api.md) - every option, callback, column meta
   field, export, CSS variable and data attribute belonging to editing.
 - [Common mistakes](references/common-mistakes.md) - the failure modes above,

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

@@ -28,7 +28,7 @@ the type.
 | Name | Argument | What it does |
 | --- | --- | --- |
 | `editing.onCommit` | `{ rowId, value, original, changes, source }` | Applies one row's change. Reject to keep the draft and show the error. |
-| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. May return a `TMDataGridSaveDraftsResponse` naming the ids that failed; they stay in the draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. May return a `TMDataGridSaveDraftsResponse` naming the ids that failed; they stay in the draft store. Each of its buckets is a `TMDataGridSaveOutcomes`: `boolean \| Record<string, boolean>`, where `false` keeps an entry's draft and an id the map does not name counts as saved. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
 | `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
 | `editing.onRowDelete` | `{ rowId, row }` | Deletes a row. Shows the trash; under `draft: true`, `onSaveDrafts` shows it too. |
 
@@ -63,7 +63,7 @@ path, which may be dotted.
 | `setCellValue` | `(rowId, columnId, value) => Promise<boolean>` | Writes one cell and commits the row, with no editor - toolbar actions and bulk fills. The row need not be mounted; a row inside a collapsed group takes the write. `value` is the stored value, so `meta.edit.mapValue` does not run and `meta.edit.validate` does. Under `draft: true` the row is committed into the draft store like any hand-made edit. `false` when the cell takes no edit, or when validation refused the value and left the row open with its errors. |
 | `setRowValues` | `(rowId, values) => Promise<boolean>` | `setCellValue` for several cells of one row in a single commit - one consumer call and one draft entry. Keys are column ids. All or nothing: if any named cell takes no edit, nothing is written and it resolves `false`. |
 | `addRow` | `(values?) => string` | Opens an entry row, returns its `tempId`. `values` overrides `editing.newRowDefaults` key by key for that row; with no argument the row is `newRowDefaults` alone. |
-| `addRows` | `(rows, options?) => Promise<TMDataGridAddRowsResult>` | Opens a batch in one write, each row seeded as `addRow` seeds. `{ commit: true }` submits each as it lands - valid rows commit, invalid ones stay open with their errors. Resolves `{ ok, committed, open }`; `ok` is `false` when a row stayed open. |
+| `addRows` | `(rows, options?: TMDataGridAddRowsOptions) => Promise<TMDataGridAddRowsResult>` | Opens a batch in one write, each row seeded as `addRow` seeds. `{ commit: true }` submits each as it lands - valid rows commit, invalid ones stay open with their errors. Resolves `{ ok, committed, open }`; `ok` is `false` when a row stayed open. |
 | `deleteRow` | `(rowId) => void` | `editing.onRowDelete`, or a deletion mark under `draft: true`. Idempotent: a second call leaves the row marked; `restoreRow` is the undo. |
 | `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. Both halves: the column's and the row's. |
 | `canEditRow` | `(row) => boolean` | The pencil's gate. |
@@ -131,7 +131,9 @@ Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
 `TMDataGridEditChange`, `TMDataGridEditorArgs`, `TMDataGridEditorComponent`,
 `TMDataGridEditField`, `TMDataGridEditRowProjection`, `TMDataGridFieldValidate`,
 `TMDataGridRowValidators`, `TMDataGridRowEditForm`, `TMDataGridRowAddArgs`,
-`TMDataGridRowDeleteArgs`, `TMDataGridEditingOptions`.
+`TMDataGridRowDeleteArgs`, `TMDataGridEditingOptions`,
+`TMDataGridSaveOutcomes`, `TMDataGridAddRowsOptions`,
+`TMDataGridEditValueMapArgs`, `TMDataGridTableValidateArgs`.
 
 ## The edit lane
 

package/skills/editing/references/editors-and-validation.md

@@ -157,6 +157,10 @@ meta: {
 }
 ```
 
+The map receives `TMDataGridEditValueMapArgs`: `{ value, previous, row, column, table }`.
+Unlike `meta.edit.enabled`, its `row` is `Row<TMDataGridFeatures, TMDataGridRowData>`
+with or without the column helper.
+
 The grid applies it in the editor host, around the field every editor writes
 through, so it covers the six built-ins, a custom `meta.edit.editor`, and the
 type-to-edit seed character.
@@ -241,7 +245,8 @@ unedited value and cannot pass. Use `"row"`.
 ## Cross-row rules
 
 `editing.tableValidators` holds the rules that need the other rows. Its
-`onSubmit` / `onSubmitAsync` receive `{ value, rowId, isNew, rows }`:
+`onSubmit` / `onSubmitAsync` receive `TMDataGridTableValidateArgs`,
+`{ value, rowId, isNew, rows }`:
 `value` is the committing row as drafted, and `rows` is
 `Array<{ rowId, value }>` - the collection as it would stand if the commit
 landed, with every draft overlaid, entry rows appended and deletion-marked
@@ -270,6 +275,56 @@ row's - after the row's own validators, and again for every committed row during
 `saveDrafts`, the only rules that run there: a committed row that a later edit
 invalidated is reopened with its errors, and the save reports it in `reopened`.
 
+## Derived columns and a table-wide rule
+
+A column whose value depends on the other rows - a weight as a share of the
+total - cannot be an `accessorFn`, which is handed one row. Derive the whole
+collection with `useMemo` and pass the finished rows as `data`;
+`editing.onCommit` writes back to the source array, and the derived rows arrive
+on the next render. Under `mode: "cell"` with no draft store, every dependent
+column follows the commit.
+
+```tsx
+const positions = useMemo(() => {
+  const valued = holdings.map((h) => ({ ...h, marketValue: h.price * h.shares }));
+  const total = valued.reduce((sum, h) => sum + h.marketValue, 0);
+  return valued.map((h) => ({
+    ...h,
+    currentPct: (h.marketValue / total) * 100,
+    drift: h.targetPct - (h.marketValue / total) * 100,
+  }));
+}, [holdings]);
+```
+
+A rule over the whole collection, such as targets that may not total more than
+100%, is a `tableValidators` rule, while a bound on one cell (between 0 and 100)
+stays on `meta.edit.validate`. `editing.columns` keeps every other column
+read-only:
+
+```tsx
+editing: {
+  mode: "cell",
+  // Only the target weight takes edits; everything else is market data.
+  columns: ["targetPct"],
+  onCommit: ({ rowId, value }) =>
+    setHoldings((previous) =>
+      previous.map((h) => (h.id === rowId ? { ...h, targetPct: value.targetPct } : h)),
+    ),
+  tableValidators: {
+    // `rows` already holds the committing row's drafted value.
+    onSubmit: ({ rows }) => {
+      const total = rows.reduce((sum, r) => sum + Number(r.value.targetPct ?? 0), 0);
+      return total > 100.005
+        ? { fields: { targetPct: `Targets would total ${pct(total)}` } }
+        : undefined;
+    },
+  },
+}
+```
+
+Source: `packages/tmdatagrid/docs/portfolio-rebalancer.md`, and the demo
+`apps/docs/src/examples/demos/recipes/PortfolioRebalancer.tsx`.
+
 ## Server-side errors
 
 `editing.rowValidators.onSubmitAsync` returns TanStack Form's `{ form, fields }`

package/skills/filtering/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/quick-search.md'
@@ -424,20 +424,26 @@ Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 | `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
 | `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
-| `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
+| `quickSearchMode` | Option | `TMDataGridQuickSearchMode`: `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |
 | `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. Removes the input, or one column's participation. |
 | `globalFilterFn` | Table option | filter fn | fuzzy | Overrides the matching, and the ranking with it. |
 | `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"`, Mantine `BoxProps` | `"row"` | The panel of filter rows, as a plain block. Style props set on it. |
+| `TMDataGridFilterPanelProps` · `TMDataGridFilterPanelLayout` | Types | – · `"row" \| "stacked"` | – | The props of `TMDataGrid.FilterPanel`, and the type of its `layout`. For wrapping the panel in a component of your own. |
 | `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |
-| `TMDataGridFilterControlArgs.layout` | Type | `"row" \| "stacked" \| "header"` | – | How much room a value control has, and whether it names itself. |
-| `filterValueShape` | Export | `(operator) => "scalar" \| "set" \| "range"` | – | Which shape an operator's value takes. |
+| `TMDataGridFiltersSettings` | Type | `Required<TMDataGridFiltersOptions>` | – | The `filters` option with its defaults filled in, as `api.filters`. |
+| `TMDataGridFilterSurface` · `TMDataGridFilterSidebarSide` | Types | `"popup" \| "sidebar" \| "none"` · `"left" \| "right"` | – | The types of `filters.surface` and `filters.sidebarSide`. |
+| `TMDataGridFilterControlArgs.layout` | Type | `TMDataGridFilterControlLayout` | – | How much room a value control has, and whether it names itself. |
+| `TMDataGridFilterControlLayout` | Type | `"row" \| "stacked" \| "header"` | – | The type of `layout` on `TMDataGridFilterControlArgs`. `"header"` is the cell of the `inHeader` row. |
+| `filterValueShape` | Export | `(operator) => TMDataGridFilterValueShape` | – | Which shape an operator's value takes. |
+| `TMDataGridFilterValueShape` | Type | `"scalar" \| "set" \| "range"` | – | What `filterValueShape` returns. |
 | `TMDataGrid.FilterButton` | Component | – | – | Toolbar button opening the panel, with an active count. |
 | `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, Mantine `BoxProps` | – | Active filters as removable pills, renderable anywhere. Style props set on the wrapper. |
 | `TMDataGrid.Search` | Component | `placeholder`, `debounce` (`250`), `w` (`220`) | – | The debounced quick-search input. |
 | `openColumnFilter` | Export | `(api, columnId) => void` | – | Opens the panel on a column. |
 | `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value narrows anything. |
-| `activeColumnFilters` | Export | `(columnFilters \| table) => Array<{ id, value }>` | – | The filters in the grid's own value shape that narrow anything, typed. |
+| `activeColumnFilters` | Export | `(columnFilters \| table) => Array<TMDataGridColumnFilter>` | – | The filters in the grid's own value shape that narrow anything, typed. |
+| `TMDataGridColumnFilter` | Type | `{ id, value }` | – | One entry of `columnFilters`, with `value` typed as `TMDataGridFilterValue`. |
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
 | `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | One column's list after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |

package/skills/getting-started/SKILL.md

@@ -5,16 +5,20 @@ description: >
   Mantine. Covers useTMDataGrid, the TMDataGrid root, context, the component
   catalog (Table, Footer, Toolbar, Spacer, SummaryCount, Search,
   LoadingIndicator, DraftActions, FilterButton, Menu, FilterPanel, FilterPills,
-  ColumnsPanel), the size scale and the bounded-height layout requirement. Load
-  when adding a grid, choosing which parts to render, or when rows do not
-  appear.
+  ColumnsPanel) with their props types, the size scale, the bounded-height
+  layout requirement, and rendering rows without TMDataGrid.Table through
+  getDisplayedRows (a card view). Load when adding a grid, choosing which parts
+  to render, replacing the Table with a renderer of your own, or when rows do
+  not appear.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/anatomy.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/components.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/card-view.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/sizes.ts'
 ---
@@ -131,6 +135,7 @@ TanStack ships state and APIs for both but no `enable` option.
 | Configure the hook, or persist state | `options` |
 | Theme, size, compose the toolbar, translate | `appearance` |
 | Write tests against a grid | `testing` |
+| Upgrade code written against a 2.0 beta | `migrating-to-2` |
 
 ## Layout
 
@@ -156,7 +161,7 @@ flex column.
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
 | `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
-| `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. |
+| `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. Also exported as `TMDataGridSearch`. |
 | `TMDataGrid.LoadingIndicator` | - | Small spinner while `meta.loading` is `true` and rows stay on screen. |
 | `TMDataGrid.DraftActions` | `renderActions` | Save with the pending count, and Discard. Renders nothing while editing is off - see the `editing` skill. |
 | `TMDataGrid.FilterButton` | - | Toggles the filter surface, seeding a filter row on the first filterable column. Renders nothing if no column is filterable, or under `filters.surface: "none"`. |
@@ -165,6 +170,29 @@ flex column.
 | `TMDataGrid.ColumnsPanel` | - | The column chooser as plain controls, for a Popover or a Drawer. |
 | `TMDataGrid.FilterPills` | `api`, `size` (default `"sm"`), `showClearAll` (default `true`), `onPillClick(columnId)`, `className` | One pill per active filter, ✕ to clear it. Takes the api as a prop, so it can be rendered outside the grid. Also exported as `TMDataGridFilterPills`. |
 
+Each component's props type is exported, for wrapping a part in a component of
+your own:
+
+| Component | Props type |
+| --- | --- |
+| `TMDataGrid` | `TMDataGridProps<TData>`: the fields of `TMDataGridApi<TData>`, plus `children`, `size`, `className`, `style`, `id` and `data-testid` |
+| `TMDataGrid.Table` | `TMDataGridTableProps<TData>` |
+| `TMDataGrid.Toolbar` | `TMDataGridToolbarProps`: `children`, `withBottomBorder` (default `false`), Mantine `BoxProps` |
+| `TMDataGrid.Search` · `TMDataGridSearch` | `TMDataGridSearchProps` |
+| `TMDataGrid.Footer` | `TMDataGridFooterProps` |
+| `TMDataGrid.Menu` | `TMDataGridMenuProps`: `children`, `icon`, `label`, Mantine `MenuProps` |
+| `TMDataGrid.Menu.Columns` | `TMDataGridMenuColumnsProps`: `searchable` |
+| `TMDataGrid.Menu.Export` · `.ExportSelected` | `TMDataGridMenuExportProps`: per-item `exportOptions` overrides, `columns` (which also takes `"custom"`), `label` |
+| `TMDataGrid.ColumnsPanel` | `TMDataGridColumnsPanelProps`: `searchable`, Mantine `BoxProps` |
+| `TMDataGrid.FilterPanel` | `TMDataGridFilterPanelProps`: `layout`, Mantine `BoxProps` |
+| `TMDataGrid.FilterPills` · `TMDataGridFilterPills` | `TMDataGridFilterPillsProps<TData>` |
+| `TMDataGrid.DraftActions` · `TMDataGridDraftActions` | `TMDataGridDraftActionsProps`: `renderActions` |
+
+`renderActions` on `TMDataGrid.DraftActions` receives
+`TMDataGridDraftActionsSlotArgs`, `{ state, actions, Controls }`, typed
+`TMDataGridDraftActionsState`, `TMDataGridDraftActionsActions` and
+`TMDataGridDraftActionsControls`. The fields are in the `editing` skill.
+
 Pass the row type so `onRowClick` stays typed:
 
 ```tsx
@@ -249,6 +277,76 @@ The virtualizer needs row height as a number, so it cannot come from CSS alone.
 `SIZE_ROW_HEIGHT` is the exported source of these values and the stylesheet
 mirrors them. Set `meta.rowHeight` for a height outside the scale.
 
+## Render rows without TMDataGrid.Table
+
+To show the rows as something other than a table - cards, a list - keep
+`useTMDataGrid` and `<TMDataGrid>`, and replace `TMDataGrid.Table` with a
+renderer of your own. `TMDataGrid` renders no rows itself, and every other part
+works without the Table, so the toolbar stays. Search, filters, sorting, column
+visibility and row selection write the same table state the grid would.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  getRowId: (row) => String(row.id),
+  // The popup and the sidebar belong to TMDataGrid.Table.
+  filters: { surface: "none" },
+});
+
+<TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
+  <TMDataGrid.Toolbar>
+    <TMDataGrid.Search />
+    <TMDataGrid.SummaryCount />
+    <TMDataGrid.Menu>
+      <TMDataGrid.Menu.Columns />
+    </TMDataGrid.Menu>
+  </TMDataGrid.Toolbar>
+  <TMDataGrid.FilterPanel layout="stacked" />
+  <CardList table={grid.table} features={grid.features} />
+</TMDataGrid>;
+```
+
+Read the rows with `getDisplayedRows(table, features)`: the rows the Table
+would render, in render order - filtered, sorted, the current page when paging
+is active, pinned rows left out. Call it inside a selector with a shallow
+compare:
+
+```tsx
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import { getDisplayedRows } from "@jielga/tmdatagrid";
+
+const rows = useSelector(table.store, () => getDisplayedRows(table, features), {
+  compare: shallow,
+});
+```
+
+The table identity never changes, so the React Compiler caches a bare
+`getDisplayedRows(table, features)` call and the list stops following filters
+and sorting. The shallow compare re-renders the list only when the rows change.
+Read `row.getVisibleCells()` the same way, inside
+`useSelector(table.store, () => row.getVisibleCells())`, and skip the generated
+columns with `isGeneratedColumn(cell.column.id)` - the checkbox column is among
+the visible cells while row selection is on. Render each value through the
+column's own renderer: `flexRender(cell.column.columnDef.cell, cell.getContext())`.
+
+The following belong to `TMDataGrid.Table` and are not available without it:
+
+- the header, with click-to-sort, resizing, dragging and the column menus -
+  sort from a control of your own with `table.setSorting`
+- the filter popup and sidebar - set `filters: { surface: "none" }` and place
+  `TMDataGrid.FilterPanel` yourself
+- row details, row pinning, cell selection and editing in cells
+- `scrollToRow`, which returns `false` while no Table is mounted
+
+Virtualize the list yourself, for example with `useVirtualizer` from
+`@tanstack/react-virtual`.
+
+Source: `packages/tmdatagrid/docs/card-view.md`,
+`packages/tmdatagrid/docs/anatomy.md` (Which rows it renders), and the demo
+`apps/docs/src/examples/demos/recipes/CardView.tsx`.
+
 ## Helpers
 
 | Export | Description |

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/grouping.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/summary-row.md'

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

@@ -0,0 +1,244 @@
+---
+name: migrating-to-2
+description: >
+  Upgrade code written against a 2.0.0-beta release of TMDataGrid to 2.0.0, as a
+  checklist to run over a codebase. Covers the edit.commitAll / saveDrafts /
+  addRows result objects and the silent `if (await saveDrafts())` trap, the
+  onSaveDrafts return type renamed to TMDataGridSaveDraftsResponse, every
+  removed name with its replacement (submitAll, onCommitDrafts, rows / added,
+  pendingCount, cellExport, exportGridToCsv, the cell-matrix functions,
+  toExcelCsv, downloadTextFile, labels.exportCsv), the helpers no longer
+  exported, removing row annotations and casts from meta.options and
+  meta.edit.enabled callbacks, and the behaviour changes. Load when upgrading
+  @jielga/tmdatagrid from a 2.0 beta, or when an import or a property from the
+  beta no longer resolves.
+metadata:
+  type: lifecycle
+  library: '@jielga/tmdatagrid'
+  library_version: '2.0.1'
+sources:
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/migrating-to-2.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/index.ts'
+---
+
+# TMDataGrid - Migrating from the 2.0 beta to 2.0.0
+
+2.0.0 removes every name deprecated during the 2.0 beta, stops exporting a set
+of internal helpers, and changes what three edit calls resolve. Run the steps
+below in order over the codebase. Step 1 finds code that still compiles but
+behaves differently; the compiler finds most of the rest.
+
+## 1. CRITICAL Read `ok` from commitAll and saveDrafts
+
+`edit.commitAll()` and `edit.saveDrafts()` resolve an object instead of a
+`boolean`. A truthiness check on the old `boolean` still compiles and is now
+always true, so a failed save reports success with no error.
+
+Search for: `commitAll(` and `saveDrafts(`, including the `actions.save` and
+`actions.commitAll` of a `TMDataGrid.DraftActions` `renderActions` slot, which
+resolve the same objects.
+
+| Call | Resolves |
+| --- | --- |
+| `edit.commitAll()` · `actions.commitAll()` | `TMDataGridCommitAllResult`: `{ ok, committed, open }` |
+| `edit.saveDrafts()` · `actions.save()` | `TMDataGridSaveDraftsResult`: `{ ok, saved, kept, reopened }` |
+| `edit.addRows(rows, options)` | `TMDataGridAddRowsResult`: `{ ok, committed, open }` - `ok` is new |
+| `edit.commit(rowId)` | `boolean`, unchanged |
+
+Wrong (compiles, always true):
+
+```tsx
+if (await grid.edit.saveDrafts()) notify("Saved");
+const done = await grid.edit.commitAll();
+if (!done) return;
+```
+
+Correct:
+
+```tsx
+const { ok, kept, reopened } = await grid.edit.saveDrafts();
+if (ok) notify("Saved");
+else notify(`${kept.length + reopened.length} rows need attention`);
+
+const { ok: committed } = await grid.edit.commitAll();
+if (!committed) return;
+```
+
+Each list holds row ids, and temp ids for new rows. `ok` is `true` when `open`
+is empty, or, for `saveDrafts()`, when `kept` and `reopened` are both empty.
+Also check every other use of the result: `.then((saved) => ...)`, a `return`
+of it from a `boolean` function, `!result`, `result ? ... : ...` and
+`Boolean(result)`.
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Read the batch edit results).
+
+## 2. Rename the onSaveDrafts return type
+
+The type of what `editing.onSaveDrafts` may return is renamed
+`TMDataGridSaveDraftsResponse`. `TMDataGridSaveDraftsResult` is now the type
+`edit.saveDrafts()` resolves, so code that kept the old name for the callback
+fails to compile.
+
+Search for: `TMDataGridSaveDraftsResult`. Where it types an `onSaveDrafts`
+callback or its return value, replace it:
+
+```tsx
+// beta
+import type { TMDataGridSaveDraftsResult } from "@jielga/tmdatagrid";
+
+// 2.0.0
+import type { TMDataGridSaveDraftsResponse } from "@jielga/tmdatagrid";
+```
+
+Where it types the value of `await edit.saveDrafts()`, keep it.
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Rename the onSaveDrafts return type).
+
+## 3. Replace removed names
+
+Search for each name in the first column and replace it:
+
+| Removed | Use instead |
+| --- | --- |
+| `edit.submitAll()` | `edit.commitAll()`, then `edit.saveDrafts()` |
+| `editing.onCommitDrafts` | `editing.onSaveDrafts` |
+| `rows` and `added` in the `onSaveDrafts` payload | `updated` and `created` |
+| `TMDataGridEditCommitDraftsArgs` | `TMDataGridSaveDraftsArgs` |
+| `state.pendingCount` in a `TMDataGrid.DraftActions` slot | `state.draftCount` or `state.openCount` |
+| `cellExport` on `TMDataGrid.Table` | `exportOptions` on `useTMDataGrid` |
+| `exportGridToCsv` | `exportGrid` |
+| `TMDataGridCellExportOptions`, `DEFAULT_CELL_EXPORT_OPTIONS`, `fromCellExportOptions` | `TMDataGridExportOptions`, `DEFAULT_EXPORT_OPTIONS` |
+| `buildCellMatrix`, `buildGridCellMatrix`, `BuildCellMatrixArgs`, `TMDataGridCellMatrix` | `buildExportData`, `BuildExportDataArgs`, `TMDataGridExportData` |
+| `toExcelCsv` | `csvExcelFormat` |
+| `downloadTextFile` | `downloadFile` |
+| `labels.exportCsv` | `labels.exportCells` |
+
+Search for `onSaveDrafts` as well, and check what each callback reads off its
+payload.
+
+### submitAll
+
+`submitAll()` was `commitAll()` followed by `saveDrafts()`. Call both, and
+combine the results where one answer is needed:
+
+```tsx
+const committed = await grid.edit.commitAll();
+const saved = await grid.edit.saveDrafts();
+const ok = committed.ok && saved.ok;
+```
+
+### The CSV export options
+
+`separator` and `decimalComma` move into a format; `includeHeaders` and
+`fileName` stay in the options. `exportOptions` on the hook applies to every
+export the grid offers, the cell-range menu included.
+
+```tsx
+// beta
+<TMDataGrid.Table cellExport={{ separator: ",", decimalComma: false, fileName: "orders" }} />;
+exportGridToCsv({ table, options: { separator: ",", decimalComma: false } });
+
+// 2.0.0
+const exportOptions = {
+  format: csvExcelFormat({ separator: ",", decimalComma: false }),
+  fileName: "orders",
+} satisfies TMDataGridExportOptions;
+
+const grid = useTMDataGrid({ data, columns, exportOptions });
+await exportGrid({ table: grid.table, options: exportOptions });
+```
+
+### The matrix functions
+
+The export functions now return values, not text. A format writes the text:
+
+```tsx
+// beta
+const csv = toExcelCsv(buildGridCellMatrix({ table }), { separator: ";" });
+downloadTextFile({ fileName: "export.csv", text: csv });
+
+// 2.0.0
+const data = buildExportData({ table });
+const csv = await csvExcelFormat().write(data, { includeHeaders: true });
+downloadFile({ fileName: "export.csv", content: csv, mimeType: "text/csv;charset=utf-8" });
+```
+
+For a cell range, pass `rows` and `bounds` to `buildExportData` instead of
+`rows`, `columns` and `bounds` to `buildCellMatrix`. `toClipboardText(data)`
+writes the tab-separated text for the clipboard.
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Replace removed names).
+
+## 4. Remove annotations and casts from meta callbacks
+
+The `row` that `meta.options` and `meta.edit.enabled` callbacks receive is
+typed with the row type of `createTMDataGridColumnHelper<TData>()`:
+`Row<TMDataGridFeatures, TData>`. A callback whose parameter is annotated with
+the untyped row no longer compiles.
+
+Search for: `options:` and `enabled:` inside column `meta`, and
+`Row<TMDataGridFeatures, TMDataGridRowData>` or `as ` casts on `row.original`
+next to them. Remove the annotation and the cast:
+
+```tsx
+// beta
+meta: {
+  edit: {
+    enabled: (row: Row<TMDataGridFeatures, TMDataGridRowData>) =>
+      (row.original as Employee).status !== "Terminated",
+  },
+}
+
+// 2.0.0
+meta: {
+  edit: { enabled: (row) => row.original.status !== "Terminated" },
+}
+```
+
+Columns built without the helper keep the untyped row,
+`Row<TMDataGridFeatures, TMDataGridRowData>`; leave those as they are.
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Remove annotations from meta callbacks).
+
+## 5. Replace helpers that are no longer exported
+
+These names are internal to the grid and are no longer exported from
+`@jielga/tmdatagrid`. An import of one fails to compile. Search the imports
+from `@jielga/tmdatagrid` for each:
+
+| Removed | Use instead |
+| --- | --- |
+| `getDefaultOperator` | `getColumnDefaultOperator(column)` |
+| `isColumnEditableForRow` | `edit.canEditCell(row, column)` |
+| `isColumnReorderable` | `getColumnCapabilities(column, features).canReorder` |
+| `measureColumnContentWidth` | `autosizeColumn` |
+| `tmDataGridFeatures` | The `TMDataGridFeatures` type |
+| `isSameCell`, `resolveCellMove`, `ResolveCellMoveArgs`, `TMDataGridCellCoords`, `TMDataGridCellNav` | No public replacement; internal to the grid. |
+| `boundsCellCount`, `boundsEdges`, `isWithinBounds` | No public replacement; internal to the grid. |
+| `getColumnFilterControl` | No public replacement; internal to the grid. |
+| `TMDataGridColumnLayout` | No public replacement; internal to the grid. |
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Replace un-exported helpers).
+
+## 6. Check the behaviour changes
+
+- Under `editing.draft` without `onSaveDrafts`, a deletion whose
+  `onRowDelete` throws keeps its deletion mark and is reported in `kept`. In
+  the beta, `saveDrafts()` rejected and the mark was lost. Search for a
+  `try` / `catch` around `saveDrafts()` that expected the rejection, and read
+  `kept` instead.
+- The Swedish labels `TMDATAGRID_LABELS_SV` say "Välj" for selecting: "Välj
+  alla", "Välj alla rader", "Välj rad" and "Välj grupp". Update tests that find
+  these controls by their Swedish name.
+
+Source: `packages/tmdatagrid/docs/migrating-to-2.md` (Behaviour changes).
+
+## 7. Verify
+
+Run the project's typecheck: an import of a removed or un-exported name, and a
+meta callback annotated with the untyped row, fail there. Then run the tests
+that save or commit edits, since the truthiness check of step 1 and the
+behaviour changes of step 6 compile.
+
+See also: the `editing` skill for the result objects and the draft store, and
+the `data` skill for the export API.

package/skills/options/SKILL.md

@@ -14,9 +14,10 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/use-tm-data-grid.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/persistence.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/persistence.ts'
 ---
@@ -30,6 +31,8 @@ const grid = useTMDataGrid<TData>(options);
 // { table, ui, edit, features, labels, resetSettings, scrollToRow }
 ```
 
+The signature is
+`useTMDataGrid<TData>(options: UseTMDataGridOptions<TData>): TMDataGridApi<TData>`.
 Spread the result onto `TMDataGrid`.
 
 ## Options
@@ -124,9 +127,9 @@ changes. Separate keys let one group be cleared without touching the other.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `dataKey` | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
-| `settingsKey` | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
-| `storageMode` | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. |
+| `dataKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
+| `settingsKey` | `TMDataGridPersistKey<TMDataGridSettingsSlice>`: `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `storageMode` | `TMDataGridStorageMode`: `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
 
@@ -168,7 +171,8 @@ survives the data changing under it the way the column layout does. `expanded` i
 a data slice for the opposite reason.
 
 `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` export the same values. Slice
-names are typed per group, so only valid names are accepted.
+names are typed per group, `TMDataGridDataSlice` and `TMDataGridSettingsSlice`,
+so only valid names are accepted.
 
 Restoring happens once on mount through `initialState`. Writing is a subscription
 to the table store, so state changed directly through the table API is persisted
@@ -176,12 +180,20 @@ too. Only selected slices are read back, and unrecognised keys are ignored. All
 storage access is guarded - if storage is unavailable, disabled or full,
 persistence is skipped rather than throwing.
 
+A payload from another version is dropped whole, not migrated. Payloads carry
+the exported `PERSIST_PAYLOAD_VERSION`; anything else, including everything
+written by a 0.x build, is discarded. Restored state is realigned against the
+columns that exist: entries naming a column removed between deploys are
+dropped.
+
+Source: `packages/tmdatagrid/docs/persistence.md` (Behaviour).
+
 ## Return value
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
-| `ui` | `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
+| `ui` | `TMDataGridUiStore`: `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
 | `edit` | `TMDataGridEditApi` | The edit engine, inert until `editing` is set. See the `editing` skill. |
 | `features` | `TMDataGridFeatureFlags` | Table-level feature switches, re-read on each render. |
 | `labels` | `TMDataGridLabels` | The resolved label set, overrides merged over English. |

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-interaction.md'

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

@@ -6,7 +6,7 @@ Reference for the `rows` skill.
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `selectionMode` | Option | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a row click does. |
+| `selectionMode` | Option | `TMDataGridSelectionMode`: `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a row click does. |
 | `enableRowSelection` | Table option | `boolean \| ((row) => boolean)` | `true` | `false` removes the checkbox column and row-click selection. |
 | `enableMultiRowSelection` | Table option | `boolean` | `true` | `false` limits the selection to one row and drops group checkboxes. |
 | `showSelectedBackground` | Option | `boolean` | Follows the mode | Whether selected rows take a background tint. |
@@ -14,7 +14,8 @@ Reference for the `rows` skill.
 | `onHighlightedRowChange` | Callback | `(rowId: string \| null) => void` | – | Fires when the highlight moves. |
 | `SELECT_COLUMN_ID` | Export | `"__select__"` | – | Id of the generated checkbox column. |
 | `getSelectableRowIds` | Export | `(table) => string[]` | – | Ids the header checkbox would select. |
-| `resolveRowSelectionClick` | Export | `(args) => ResolvedRowSelection` | – | The desktop-list click rules, for a custom surface. |
+| `resolveRowSelectionClick` | Export | `(args: ResolveRowSelectionClickArgs) => ResolvedRowSelection` | – | The desktop-list click rules, for a custom surface. |
+| `ResolveRowSelectionClickArgs` · `TMDataGridRowClickModifiers` | Types | `{ rows, rowId, anchorRowId, modifiers, selection }` · `{ toggle, extend }` | – | What `resolveRowSelectionClick` takes, and its `modifiers`. |
 | `getDisplayedRows` | Export | `(table) => Row[]` | – | The rows currently on screen, paging respected. |
 | `isPagingActive` | Export | `(table) => boolean` | – | Whether a pager is in play. |
 
@@ -31,11 +32,13 @@ All are props of `TMDataGrid.Table`, not hook options.
 | `onCellClick` | `(args) => void` | Cell click. `args` is `TMDataGridCellEventArgs`. |
 | `onCellDoubleClick` | `(args) => void` | Cell double-click. |
 | `onCellContextMenu` | `(args) => void` | Cell right-click. |
-| `renderRowContextMenu` | `({ table, row, cell, close, internalItems }) => ReactNode` | Contents of the row's context menu. `null` for no menu. Reading `internalItems` hands the composition over. |
-| `renderColumnMenuItems` | `({ column, table, internalItems }) => ReactNode[]` | Contents of a column's menu. An empty list removes the button. |
+| `renderRowContextMenu` | `TMDataGridRowContextMenuRenderer`: `(args: TMDataGridRowContextMenuArgs) => ReactNode` | Contents of the row's context menu. `null` for no menu. Reading `internalItems` hands the composition over. |
+| `renderColumnMenuItems` | `TMDataGridColumnMenuItemsRenderer`: `(args: TMDataGridColumnMenuItemsArgs) => ReactNode[]` | Contents of a column's menu. An empty list removes the button. |
 | `rowContextMenuProps` | `MenuProps` | Passed to the Mantine `Menu` unchanged, apart from its open state. |
 
-`TMDataGridCellEventArgs` is `{ cell, row, column, event }`. The context-menu
+`TMDataGridCellEventArgs` is `{ cell, row, column, event }`.
+`TMDataGridRowContextMenuArgs` is `{ table, row, cell, close, internalItems }`,
+and `TMDataGridColumnMenuItemsArgs` is `{ column, table, internalItems }`. The context-menu
 slot's `cell` is `null` only when a custom cell renderer stopped the
 event. One `Menu` serves the whole body rather than one per row: a closed
 Mantine `Popover` still runs its hooks on every render, and the virtualized body
@@ -76,13 +79,14 @@ Row data attributes:
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `renderDetails` | Option | `({ row, table }) => ReactNode` | – | Contents of the panel. Setting it adds the lane. |
+| `renderDetails` | Option | `TMDataGridDetailsRenderer`: `(args: TMDataGridDetailsArgs) => ReactNode` | – | Contents of the panel. Setting it adds the lane. `TMDataGridDetailsArgs` is `{ row, table }`. |
 | `renderDetailsEstHeight` | Option | `number` | `160` | Height the virtualizer assumes for an unmeasured panel. |
 | `initialState.expanded` | Table option | `ExpandedState` | `{}` | Rows open at mount. A `data` slice, so it persists. |
 | `autoResetExpanded` | Table option | `boolean` | `true` | `false` keeps panels open when `data` changes. |
 | `DETAILS_COLUMN_ID` | Export | `"__details__"` | – | Id of the generated chevron column. |
 | `resolveExpandAll` | Export | `(args) => ExpandedState` | – | Expand or collapse every group, or every panel, but not both. |
 | `areAllRowsExpanded` | Export | `(args) => boolean` | – | Whether every row of one target is open. |
+| `TMDataGridExpandAllArgs` · `TMDataGridExpandTarget` | Types | `{ rows, expanded, target }` · `"groups" \| "details"` | – | What `areAllRowsExpanded` takes (`resolveExpandAll` also takes `expand`), and its `target`. |
 | `data-dg-part="details"` | Data attribute | – | – | The panel element, carrying the row's `data-row-id`. |
 
 One `expanded` state opens two unrelated things - a group row into its children,

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-side.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-query.md'

package/skills/testing/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/TMDataGrid:playwright/support/DataGrid.ts'

package/skills/testing-components/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/test/gallery/main.tsx'

package/skills/testing-editing/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.0.1'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editing.md'