@jielga/tmdatagrid 2.0.0 → 2.1.0

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.1.0'
 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.1.0'
 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.1.0'
 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.1.0'
+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.1.0'
 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

@@ -9,15 +9,15 @@ description: >
   onCellDoubleClick / onCellContextMenu, the renderRowContextMenu slot with its
   internalItems handback, renderColumnMenuItems and rowContextMenuProps, per-row
   styling with rowStyle, rowClassName, striped and the --row-bg rule, the row
-  details panel through renderDetails and DETAILS_COLUMN_ID, row pinning with
-  enableRowPinning and row.pin, and the row-number gutter through
-  enableRowNumbers. Load when selecting rows, reacting to a click, opening a
-  detail panel, colouring rows by their data, pinning rows to an edge, or
-  numbering them.
+  details panel through renderDetails, detailsColumnPosition and
+  DETAILS_COLUMN_ID, row pinning with enableRowPinning and row.pin, and the
+  row-number gutter through enableRowNumbers. Load when selecting rows, reacting
+  to a click, opening a detail panel, colouring rows by their data, pinning rows
+  to an edge, or numbering them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0'
+  library_version: '2.1.0'
 sources:
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-interaction.md'
@@ -235,8 +235,9 @@ const grid = useTMDataGrid({
 Each panel is measured, so heights need not be uniform.
 `renderDetailsEstHeight` (default `160`) is what the virtualizer assumes for one
 it has not measured yet. A generated chevron column, `DETAILS_COLUMN_ID`, is
-prepended and pinned left after the checkbox and tree lanes; it cannot be
-hidden, moved, resized or unpinned, and its header opens and closes every panel.
+pinned left after the checkbox and tree lanes, or right, inside the edit lane,
+under `detailsColumnPosition: "right"`; it cannot be hidden, moved, resized or
+unpinned, and its header opens and closes every panel.
 
 Which rows are open is TanStack's own `expanded` state, so anything can open
 one - `row.toggleExpanded()` from a menu item, `initialState.expanded`,