@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/docs/persistence.md

@@ -0,0 +1,114 @@
+# Persistence
+
+Restores table state on mount and writes it back on every change, so users
+return to the grid as they left it.
+
+State is split across **two keys**: `settingsKey` for the column layout, which
+stays valid indefinitely, and `dataKey` for filters, sorting and pagination,
+which go stale as the data underneath them changes. Either can be cleared
+without touching the other.
+
+```tsx
+// Module scope: the object is a dependency of the write subscription.
+const persist = {
+  dataKey: "employees.data",
+  settingsKey: "employees.settings",
+} satisfies TMDataGridPersistence;
+
+const grid = useTMDataGrid({ data, columns, persist });
+```
+
+Both keys are optional - pass only `settingsKey` to remember the layout but
+never the filters.
+
+```demo
+file: data/Persistence.tsx
+hint: Sort, filter and hide a column, then reload the page. It all comes back; the page index does not.
+extraSources: data/employeeColumns.tsx
+```
+
+## The two groups
+
+| Group | Slices | Lifetime |
+| --- | --- | --- |
+| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` | As long as the data means the same thing |
+| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` | Indefinite. This is the user's layout |
+
+`DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` are exported with the same
+values. Slice names are typed per group, so only valid names compile.
+
+Settings saved by 1.x with the old `columnPinning` keys `left` and `right` are
+read and migrated to `start` and `end`.
+
+## Persisting only some of it
+
+A key on its own persists every slice in its group. Pass a tuple to narrow it:
+
+```tsx
+const persist = {
+  // Restore filters and sorting, but always start on the first page.
+  dataKey: ["employees.data", ["columnFilters", "sorting"]],
+  // Restore column layout but not widths.
+  settingsKey: ["employees.settings", ["columnVisibility", "columnOrder"]],
+  storageMode: "sessionStorage",
+} satisfies TMDataGridPersistence;
+```
+
+Only the selected slices are read back, so a payload written before you narrowed
+the selection cannot reintroduce slices you have since opted out of.
+
+## Behaviour
+
+**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 too.
+
+**A payload from another version is dropped whole**, not migrated. Payloads
+carry the exported `PERSIST_PAYLOAD_VERSION`, and anything else, including
+everything written by a 0.x build, which had no stamp, is discarded.
+
+**Restored state is realigned against the columns that exist.** Entries naming a
+column removed between deploys are dropped: a stale id in the order, a width for
+a column that no longer exists, or a sort or filter that would be active with no
+column to show it. New columns need no handling, since TanStack appends columns
+missing from `columnOrder` in definition order.
+
+**Storage access is guarded.** If storage is unavailable, disabled or full,
+persistence is skipped rather than throwing.
+
+**Keys are not namespaced.** Include a tenant or user identifier if several
+people can share a browser profile.
+
+## Resetting
+
+`resetSettings()` puts the settings state back to what a first visit with clean
+storage would have shown (your `initialState` plus the structural lanes), and,
+with persistence configured, writes through to storage like any other change.
+The columns panel's **Reset layout** button calls it.
+
+TanStack's own `resetColumnX()` family cannot do it on a persisted grid: those
+reset to `initialState`, which the mount built *from* the restored payload.
+
+## Relation to Mantine
+
+Persistence does not use Mantine's `useLocalStorage`; the table owns the state
+and storage only mirrors it. The option names follow Mantine's
+`UseStorageOptions` where they apply, and `storageMode` takes the same values as
+its `StorageType`.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `persist` | Option | `TMDataGridPersistence` | – | The whole configuration. Keep it referentially stable. |
+| `dataKey` | persist field | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
+| `settingsKey` | persist field | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `TMDataGridPersistKey` | Type | `string \| [string, slices]` | – | The type of `dataKey` and `settingsKey`. |
+| `storageMode` | persist field | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
+| `TMDataGridStorageMode` | Type | `"localStorage" \| "sessionStorage"` | – | The type of `storageMode`. |
+| `serialize` | persist field | `(value) => string` | `JSON.stringify` | Serializes a payload before storing. |
+| `deserialize` | persist field | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
+| `resetSettings` | Hook return | `() => void` | – | Back to a clean first visit, written through to storage. |
+| `DATA_STATE_SLICES` · `SETTINGS_STATE_SLICES` | Exports | `string[]` | – | The slice names of each group. |
+| `TMDataGridDataSlice` · `TMDataGridSettingsSlice` | Types | – | – | One slice name of each group. |
+| `PERSIST_PAYLOAD_VERSION` | Export | `number` | – | The stamp. A payload from another version is dropped. |

package/docs/portfolio-rebalancer.md

@@ -0,0 +1,94 @@
+# A portfolio rebalancer
+
+A holdings book where one column is a decision and the rest are consequences.
+The user edits **Target**; the grid recomputes drift and the trade to place, totals each sector, and refuses an edit that would allocate more than the whole book.
+
+```demo
+file: recipes/PortfolioRebalancer.tsx
+hint: Type 40 into a Target cell - the commit is refused with the total it would have produced.
+height: 620
+```
+
+## Deriving the rows
+
+`accessorFn` is handed one row, so a column whose value depends on the other rows - a weight as a share of the portfolio - cannot be written as one.
+Derive the whole collection once and hand the grid the finished shape:
+
+```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]);
+```
+
+`editing.onCommit` writes back to `holdings`, the source array, and the derived rows arrive through `data` on the next render.
+Under `editing.mode: "cell"` with no draft store, every dependent column follows the keystroke that committed.
+
+## Gating the one editable column
+
+`editing.columns` lists what takes edits. Everything else is market data and stays read-only whatever its own meta says.
+
+```tsx
+editing: {
+  mode: "cell",
+  columns: ["targetPct"],
+  onCommit: ({ rowId, value }) => save(rowId, value.targetPct),
+}
+```
+
+## The rule that needs the other rows
+
+A target weight is only valid against the rest of the book, so the rule is `editing.tableValidators`, not `meta.edit.validate`.
+`rows` is the collection as it would stand if the commit landed, so the committing row's drafted value is already in it.
+
+```tsx
+tableValidators: {
+  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;
+  },
+}
+```
+
+The bound on a single cell - between 0 and 100 - stays on the column as [`meta.edit.validate`](/docs/editors), because it needs nothing but the value.
+
+## Totals in two places
+
+Sector totals come from `aggregationFn` on each column; the portfolio total comes from a `footer` and [`aggregateColumn`](/docs/summary-row), which follows the filters.
+
+```tsx
+columnHelper.accessor("marketValue", {
+  aggregationFn: "sum",
+  footer: ({ table }) =>
+    money.format(Number(aggregateColumn({ table, columnId: "marketValue" }))),
+});
+```
+
+Summing `targetPct` is meaningful only because the values are shares of one whole: a footer reading `100.0%` says the book is fully allocated.
+
+## Reading drift
+
+Drift is signed, so the cell renders a tint whose strength follows the size of the miss and whose colour follows its direction.
+Rows more than three points out take `--row-bg` as well, which composes under hover and selection instead of replacing them.
+
+```tsx
+<TMDataGrid.Table<Position>
+  rowStyle={(row) =>
+    !row.getIsGrouped() && Math.abs(row.original.drift) >= 3
+      ? { "--row-bg": "color-mix(in srgb, var(--mantine-color-yellow-6) 10%, transparent)" }
+      : undefined
+  }
+/>
+```
+
+A group row is handed to `rowStyle` too, and its `original` is an arbitrary child's record, so the callback guards with `row.getIsGrouped()`.
+[Row styling](/docs/row-styling) covers the rest of the vocabulary.

package/docs/query-builder.md

@@ -0,0 +1,179 @@
+# A query builder form
+
+A search form holds dates, a title filter and a list of extra conditions. The
+conditions are rows, so the condition builder is a grid, wrapped as a form
+field: rows come in through `value`, and approved changes go back out through
+`onChange`.
+
+```demo
+file: recipes/QueryBuilderForm.tsx
+hint: Add a condition and pick Status - the value editor becomes a select. Delete every condition, or repeat one, and Search says why it will not.
+height: 560
+```
+
+The form holds the array; the grid holds the row being edited. The grid never
+mutates `data`, so the form's state is only ever what the user has approved.
+
+## Wrapping the grid as a field
+
+The grid is wrapped once, as an ordinary controlled component:
+
+```tsx
+function ConditionsGrid({ value, onChange }: {
+  value: Array<QueryCondition>;
+  onChange: (next: Array<QueryCondition>) => void;
+}) {
+  const grid = useTMDataGrid({
+    data: value,
+    columns,
+    getRowId: (row) => String(row.id),
+    editing: {
+      mode: "row",
+      rowValidators,
+      onCommit: ({ rowId, value: row }) =>
+        onChange(value.map((c) => (String(c.id) === rowId ? row : c))),
+      onRowAdd: ({ value: row }) =>
+        onChange([...value, { ...row, id: Math.min(0, ...value.map((c) => c.id)) - 1 }]),
+      onRowDelete: ({ rowId }) =>
+        onChange(value.filter((c) => String(c.id) !== rowId)),
+      newRowDefaults: () => ({ id: 0, field: "title", operator: "contains", value: "" }),
+    },
+  });
+  return (
+    <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
+      <TMDataGrid.Table<QueryCondition> />
+    </TMDataGrid>
+  );
+}
+```
+
+And handed to the form as a field:
+
+```tsx
+<form.Field
+  name="conditions"
+  validators={{
+    onChange: ({ value }) =>
+      value.length === 0 ? "Add at least one condition" : undefined,
+  }}
+>
+  {(field) => (
+    <ConditionsGrid value={field.state.value} onChange={field.handleChange} />
+  )}
+</form.Field>
+```
+
+`field.handleChange` is the `onChange`: it writes the array into the form and
+runs the field's validators. `onChange` carries the whole next array rather than
+a diff.
+
+- **Map by row id, never by index.** A sort or a delete moves the index; the
+  draft is keyed by the id.
+- **`data` identity stays stable.** `field.state.value` changes identity only
+  when a row is written, which is what `data` requires.
+  See [useTMDataGrid](/docs/use-tm-data-grid).
+- **New rows count down from `-1`.** `Math.min(0, ...ids) - 1`, so an emptied
+  grid starts at `-1` rather than `-Infinity` and existing negative ids keep
+  descending. The grid's `tempId` never leaves the grid: the id you assign in
+  `editing.onRowAdd` is the one the form sees.
+
+## Where validation belongs
+
+A rule that can be decided from one row belongs to the grid. A rule that needs
+the other rows, or the collection as a whole, belongs to the form.
+
+| Rule | Owner | Written as |
+| --- | --- | --- |
+| "The condition needs a value" | Grid | `editing.rowValidators.onSubmit` |
+| "A date, for a date field" | Grid | `meta.edit.editor` per column |
+| "At least one condition" | Form | the `conditions` field's `onChange` validator |
+| "No two conditions repeat a field and operator" | Form | the same place |
+
+A row's form is seeded with that row's values only, so it cannot see the array,
+and the grid's `edit.store` publishes field names but not values, so the form
+cannot see a draft.
+
+## Editors that follow the row
+
+In a `[field, operator, value]` builder the value cell means something
+different on every row. `meta.edit.editor` receives the row's live form, so one
+component can switch on the *draft* field rather than the committed one, and
+picking a new field resets its dependents:
+
+```tsx
+const FieldEditor: TMDataGridEditorComponent = ({ field, form, size }) => (
+  <Select
+    size={size}
+    data={[...FIELDS]}
+    value={String(field.state.value)}
+    onChange={(next) => {
+      if (next === null) return;
+      field.handleChange(next);
+      form.setFieldValue("operator", OPERATORS[next as QueryField][0]);
+      form.setFieldValue("value", "");
+    }}
+  />
+);
+```
+
+The operator and value editors read the sibling with TanStack Store's
+[`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference):
+`useSelector(form.store, (state) => state.values.field)`, so switching Field
+mid-edit switches them immediately. See
+[Editors and validation](/docs/editors) for the editor's full API.
+
+## Which mode
+
+`editing.mode: "row"`. A condition is approved as a unit: the pencil opens the
+whole row, Save commits it, and `editing.onCommit` hands the form one finished
+condition. The form's rules run at that point.
+
+**Not `draft: true`.** A draft store holds every commit inside the grid and
+calls nothing until `edit.saveDrafts()`, so the form's array goes stale the
+moment typing starts: "at least one condition" counts rows the user may have
+marked for deletion, a duplicate sitting in a draft passes unseen, and the
+form's submit saves an array missing every pending edit.
+
+To use the store anyway, invert where the save happens: `grid.edit.saveDrafts()`
+becomes the only way rows reach the form, and the form's submit is gated on the
+grid holding no draft -
+`useSelector(grid.edit.store, (s) => s.openRowIds.length === 0)`.
+
+## Submitting
+
+The form submits only while the grid holds no draft.
+
+```tsx
+const hasOpenDraft = useSelector(grid.edit.store, (s) => s.openRowIds.length > 0);
+
+<Button type="submit" disabled={!canSubmit || hasOpenDraft}>
+  {hasOpenDraft ? "Finish the open condition" : "Search"}
+</Button>
+```
+
+The alternative is to flush instead of block.
+`await grid.edit.commitAll()` before `form.handleSubmit()` submits every open row through the normal `editing.onCommit` path, in every mode; with `draft: true` follow it with `grid.edit.saveDrafts()`.
+Both resolve `ok: false` when a row stayed open or was reopened with an error, so submit the form only on `ok`:
+
+```tsx
+const committed = await grid.edit.commitAll();
+const saved = committed.ok ? await grid.edit.saveDrafts() : undefined;
+if (saved?.ok) await form.handleSubmit();
+```
+
+Two constraints apply to a native `<form>` around a grid:
+
+- The grid's buttons cannot submit it. Mantine buttons default to
+  `type="button"`, so only your own `type="submit"` button submits.
+- Enter inside a cell editor commits the cell, not the form. The editor
+  prevents the default, so implicit form submission never fires.
+
+## Reference
+
+The pieces this recipe composes:
+
+| Piece | Documented on |
+| --- | --- |
+| `data`, `getRowId`, `editing.mode`, `editing.onCommit`, `editing.onRowAdd`, `editing.onRowDelete`, `editing.newRowDefaults`, `edit.store` | [Editing](/docs/editing) |
+| `editing.rowValidators`, `meta.edit.editor`, the editor contract | [Editors and validation](/docs/editors) |
+| `useForm`, `form.Field`, field validators | TanStack Form's own docs |

package/docs/quick-search.md

@@ -0,0 +1,84 @@
+# Quick search
+
+One box over every column. `TMDataGrid.Search` is a debounced input writing
+TanStack's `globalFilter` state. There is no option to turn it on: render the
+component, or do not.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.Search />
+</TMDataGrid.Toolbar>
+```
+
+```demo
+file: data/QuickSearch.tsx
+hint: Try “Stckholm”. Fuzzy finds it; contains does not.
+extraSources: data/employeeColumns.tsx
+```
+
+## Fuzzy by default
+
+Typos and skipped characters still match, and while the search is the only thing
+narrowing the grid (no sort, no grouping) the rows are ordered by **match
+quality**, best first.
+
+That ordering is derived and never written into `sorting`: no column takes
+`aria-sort`, nothing is written to the persisted slices, and the next sort click
+replaces it.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, quickSearchMode: "contains" });
+```
+
+`"contains"` restores plain substring matching. An explicit `globalFilterFn`
+overrides both, and switches the rank ordering off with it.
+
+`fuzzyGlobalFilterFn` is exported for building your own input over the same
+matching.
+
+## Match highlighting
+
+Opt in with `enableMatchHighlighting: true` and cells mark the matched part of
+their text, while the quick search is active or a `contains` / `starts with` /
+`ends with` column filter is.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enableMatchHighlighting: true });
+```
+
+What is marked is the **contiguous, case-insensitive** occurrence of the search
+term, so a fuzzy typo-match with no contiguous occurrence is not highlighted.
+Equality operators highlight nothing.
+
+**Default-rendered cells only.** A column with its own `cell` renderer is
+excluded: the grid reproduces the default value-to-string render with the marks
+added, and does not modify a custom renderer's output.
+
+The mark colour is `--dg-match-highlight-bg`, a yellow that follows the Mantine
+colour scheme.
+
+## Opting columns out
+
+`enableGlobalFilter: false` on a column takes it out of the search; on the table
+it removes the input entirely. The generated lanes are already excluded.
+
+A search input of your own can skip the component and call
+`table.setGlobalFilter` directly. The state is TanStack's own, so a
+[`manualFiltering`](/docs/server-side) grid forwards it to the server, and it is
+one of the persisted `data` slices.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `TMDataGrid.Search` | Component | – | – | The debounced quick-search input. |
+| `placeholder` | Search prop | `string` | `labels.searchPlaceholder` | Input placeholder. |
+| `debounce` | Search prop | `number` | `250` | Pause before the filter applies, in ms. `0` filters per keystroke. |
+| `w` | Search prop | `number \| string` | `220` | Input width. |
+| `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the search matches. |
+| `TMDataGridQuickSearchMode` | Type | `"fuzzy" \| "contains"` | – | The type of `quickSearchMode`. |
+| `enableMatchHighlighting` | Option | `boolean` | `false` | Mark the matched text in default-rendered cells. |
+| `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. `false` removes the input, or one column's participation. |
+| `globalFilterFn` | Table option | filter fn | `fuzzy` | Overrides the matching, and the rank ordering with it. |
+| `fuzzyGlobalFilterFn` | Export | filter fn | – | The default matcher, for a custom input. |
+| `--dg-match-highlight-bg` | CSS variable | colour | Themed yellow | The mark colour. |

package/docs/row-details.md

@@ -0,0 +1,115 @@
+# Row details
+
+A panel that opens underneath a row, spanning every column, holding whatever
+does not fit in the cells - a summary card, an action strip, a nested table.
+
+Setting `renderDetails` turns the lane on. There is no separate flag.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  renderDetails: ({ row }) => <EmployeeCard employee={row.original} />,
+});
+```
+
+```demo
+file: rows/DetailsPanel.tsx
+hint: Expand a few rows - the panels differ in height, and each one is measured.
+height: 460
+```
+
+The panel is as tall as whatever it renders. The grid measures each one, so
+they need not be uniform. `renderDetailsEstHeight` (default `160`) is what the
+virtualizer assumes for a panel it has not measured yet, which keeps the
+scrollbar accurate for rows that open off screen.
+
+## The details lane
+
+Setting `renderDetails` prepends a generated chevron column,
+`DETAILS_COLUMN_ID` (`"__details__"`), pinned to the left after the checkbox
+and tree columns - `[checkbox, tree, details, …]`.
+
+It is a system lane: as wide as the chevron it holds, with no resize handle and
+no column menu, and it cannot be hidden, moved, resized or unpinned. Its header
+is a control rather than a title, expanding and collapsing every panel at once.
+
+Group rows get no chevron: they expand into their children from the tree lane.
+
+## Opening a row from elsewhere
+
+Which rows are open is TanStack's own `expanded` state, so anything can open
+one - a context menu item, a double-click, a button in your own cell:
+
+```tsx
+<Menu.Item onClick={() => row.toggleExpanded()}>Show details</Menu.Item>
+```
+
+Anything reading `row.getIsExpanded()` inside a cell has to subscribe to the
+store with TanStack Store's
+[`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference), or the
+React Compiler caches the call along with the `row` identity and the control
+never updates:
+
+```tsx
+const expanded = useSelector(row.table.store, () => row.getIsExpanded());
+```
+
+Because it is the standard state, `table.toggleAllRowsExpanded()`,
+`initialState.expanded` and persistence all work with it. It is one of the
+`data` slices, so open panels survive a reload on a
+[persisted](/docs/use-tm-data-grid#persist) grid.
+
+> TanStack resets `expanded` whenever the `data` array changes, which would
+> close every panel on each draft commit. The grid therefore sets
+> `autoResetExpanded: false`; pass `autoResetExpanded: true` to have a new
+> `data` array close the panels.
+
+## The two kinds of expanding
+
+TanStack keeps one `expanded` state, and the grid uses it for two unrelated
+things: opening a group row into its children, and opening a data row into its
+panel. The controls are kept separate. The details header only opens and closes
+panels, and "Expand all groups" in the tree menu only unfolds the tree.
+
+`table.toggleAllRowsExpanded()` is the one that does not distinguish them: it
+writes the state's whole-table form, which is every group and every panel at
+once. `resolveExpandAll` and `areAllRowsExpanded` are exported for anything
+building its own control:
+
+```tsx
+table.setExpanded(
+  resolveExpandAll({
+    rows: table.getPrePaginatedRowModel().flatRows,
+    expanded: table.store.state.expanded,
+    target: "details",
+    expand: true,
+  }),
+);
+```
+
+## Panel behaviour
+
+The panel is a cell spanning the row, inside the row element. It takes the row's
+background, moves with it and is measured with it, but it is **not a row**:
+`aria-rowcount` still counts records, and a click or right-click inside it does
+not select or highlight the row underneath. It carries
+`data-dg-part="details"` with the row's `data-row-id`. See
+[Testing](/docs/testing).
+
+Group rows have no panel. Expanding one opens its children.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `renderDetails` | Option | `({ row, table }) => ReactNode` | – | Contents of the panel. Setting it adds the lane. |
+| `TMDataGridDetailsArgs` | Type | `{ row, table }` | – | What `renderDetails` receives. |
+| `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` | `false` | `true` closes the panels when the `data` array changes. Off by default, so a draft commit keeps them open. |
+| `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 | – | – | What `resolveExpandAll` and `areAllRowsExpanded` take, and its `target`: `"groups"` or `"details"`. |
+| `data-dg-part="details"` | Data attribute | – | – | The panel element, carrying the row's `data-row-id`. |