@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/docs/editing.md

@@ -0,0 +1,303 @@
+# Editing
+
+`@tanstack/react-form` becomes a peer dependency once editing is used.
+
+Editing is turned on with the `editing` option.
+Two settings inside it work independently:
+
+- `mode` - what counts as a commit: leaving the cell, confirming the cell, or saving the row
+- `draft` - where a commit goes: to your `onCommit` callback at once, or into the grid's [draft store](/docs/draft-store) until the user presses Save
+
+The grid never modifies `data`.
+You apply each commit in your callback, and the new values arrive back through `data`.
+
+A row is in one of three places:
+
+| Place | What it holds | Enters by | Leaves by |
+| --- | --- | --- | --- |
+| **data** | Your rows, the only source of truth | - | - |
+| **form state** | A row being edited, in its own TanStack Form | `edit.begin`, `edit.addRow` | `edit.commit`, `edit.cancel` |
+| **draft store** | Rows that passed their commit, held as values inside the grid until Save | `edit.commit` under `draft: true` | `edit.saveDrafts`, `edit.cancel` |
+
+A row is **open** while it is in form state, and **committed** once it is in the draft store.
+Without `draft: true` a commit goes straight to `onCommit` and the form is dropped, so the draft store stays empty.
+
+## Set up editing
+
+The smallest setup is cell mode with an `onCommit` that applies each change:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  getRowId: (row) => String(row.id),
+  editing: {
+    mode: "cell",
+    onCommit: async ({ rowId, value, changes }) => {
+      // changes is a list of descriptors, not a patch object
+      await api.patch(rowId, Object.fromEntries(changes.map((c) => [c.field, c.next])));
+    },
+  },
+});
+```
+
+`onCommit` receives `{ rowId, value, original, changes, source }`:
+
+- `value` - the whole row as edited
+- `original` - the row as editing began
+- `changes` - the per-field diff, `Array<{ columnId, field, previous, next }>`, one entry in cell mode
+- `source` - the `mode` the commit came from
+
+`editing` requires `getRowId`: drafts are keyed by row id, and the index fallback would name a different record after a sort.
+`onSaveDrafts` is accepted only under `draft: true`.
+Both are compile errors, not options that silently do nothing.
+
+The `editing` object can be written inline.
+Its callbacks are read through a ref on every render, so its identity does not matter.
+
+Editing turns on cell selection: `cellSelection` defaults to `"single"` while `editing` is set.
+
+## Modes
+
+`editing.mode` sets what counts as a commit and which controls trigger it.
+All three modes use the same engine and the same forms.
+
+| Mode            | Commit                                     | Cancel            | Controls                 |
+| --------------- | ------------------------------------------ | ----------------- | ------------------------ |
+| `"cell"`        | Enter, Tab or leaving the cell             | Escape            | none                     |
+| `"cellConfirm"` | ✓ or Enter; Tab walks input, ✓, ✕ and then leaves, keeping the draft | ✕ or Escape       | ✓ / ✕ beside the input   |
+| `"row"`         | ✓ in the edit lane, or Enter               | ✕, or Escape      | generated edit lane      |
+
+An entry row from `edit.addRow()` is row-shaped in every mode: every editable cell opens at once, Tab walks them, and Enter, or the lane's ✓, commits it.
+
+```demo
+file: editing/CellEditing.tsx
+hint: Double-click a cell, or press Enter or F2, or start typing on it.
+height: 440
+```
+
+### Opening an editor
+
+An editor opens on double-click, or, with the cell cursor on the cell, on Enter, F2 or typing, where the first character replaces the value as in a spreadsheet.
+The grid places the caret in the opened cell, so a `meta.edit.editor` receives focus without handling it itself.
+A row added with `edit.addRow()` opens the same way, with the caret in its first editable cell.
+
+Delete or Backspace clears the value and commits it without opening an editor.
+The commit is validated: a column rule that rejects the empty value refuses the clear and marks the cell.
+Under `draft: true` the cleared value goes into the draft store with the rest.
+
+A commit that fails validation keeps the editor open and marked invalid, with the message in its tooltip, until the value is fixed or Escape drops the edit.
+
+### Row editing
+
+The pencil in the edit lane opens every cell of the row at once, and ✓ commits them as one commit.
+Double-clicking a cell opens the whole row, with the caret in the clicked cell.
+Cross-field rules belong in this mode, because the whole row is validated together.
+Opening a second row leaves the first one open, and each row's ✓ and ✕ act on that row alone.
+
+```demo
+file: editing/RowEditing.tsx
+hint: Put a Sales row over 60 000 kr and Save reports why it is rejected.
+height: 440
+```
+
+## Edit lane
+
+The edit lane is the generated column at the end of every row, with the id `EDIT_COLUMN_ID`.
+The grid adds it under `mode: "row"`, under `draft: true`, or when `onRowDelete` is set.
+What it shows depends on the row's state:
+
+| Row state | Icon | Actions |
+| --- | --- | --- |
+| Open | - | The mode's controls: ✓ ("Save row") commits the row, ✕ ("Cancel edit") cancels the edit |
+| Committed edit | Pencil | Revert drops the row's draft |
+| Committed new row | Plus | Pencil reopens it, ✕ removes it |
+| Marked for deletion | Trash | Restore removes the mark |
+
+A committed row is never offered ✓ again; `TMDataGrid.DraftActions` sends it.
+A committed row also hides the trash: revert first, then delete.
+The trash shows when a deletion has somewhere to go: `onRowDelete` is set, or under `draft: true`, `onSaveDrafts` is.
+
+If validation blocks a row, its icon turns red and the tooltip shows the message; this covers the open row's ✓ and an entry row's ✓ alike.
+A pathless issue from `rowValidators` has no cell to land on, so that tooltip is where its message shows.
+
+## Which cells edit
+
+A column is editable when it maps to a data path: its `accessorKey`, or `meta.edit.field` for a column built on `accessorFn`.
+Dot paths reach into nested records: `accessorKey: "address.city"` edits `values.address.city`, and issues from a nested schema map to the right column.
+
+| Gate | Effect |
+| --- | --- |
+| `editing.columns: string[]` | Only the named columns edit |
+| `meta.edit.enabled: false` | The column never edits |
+| `meta.edit.enabled: (row) => boolean` | Per row, per column |
+| `editing.isRowEditable: (row) => boolean` | The whole row, in every mode |
+
+Group rows and the generated lanes never edit.
+
+`editing.columns` lists the column ids that take edits.
+By default, every column that maps to a data path is editable.
+
+```tsx
+editing: { mode: "cell", columns: ["targetPct", "note"] }
+```
+
+It gates before `meta.edit`, never past it: a column left out takes no edits whatever its own meta says, and a listed column still answers to its `meta.edit.enabled`.
+The same list decides which cells an entry row opens.
+
+`edit.isColumnEditable(column)` answers the column's half of the question on its own, for a toolbar or a menu with no row in hand: the column maps to a field, `editing.columns` lists it when that is set, and `meta.edit.enabled` is not `false`.
+A per-row `enabled` predicate is the row's half, and `edit.canEditCell(row, column)` asks both.
+
+```demo
+file: editing/EditableGating.tsx
+hint: ID never edits · Salary is closed on Terminated rows · rows under 25 are closed entirely · Full name is computed but writes to Last name.
+height: 440
+```
+
+## How a draft renders
+
+Forms live outside the DOM, keyed by row id.
+Scrolling an editing row away unmounts its editor; the form keeps its values, dirty state and errors, and the editor remounts over the same form when the row returns.
+
+A cell whose row holds a draft renders the draft value through the column's own `cell` renderer, in every mode; a `"cellConfirm"` draft kept when the caret left shows what was typed, not the value in `data`.
+Cell corners show the state: blue for a dirty draft, red for a validation error, and the row carries `data-dirty`.
+An entry row's cells take the red corner, never the blue one.
+
+A validation message outlives the editor that found it: the cell keeps its red corner and the lane carries the text until that field's value changes.
+While an editor is open, the field's message shows in a tooltip on it, opened by focus and by hover.
+
+Inside a `cell` renderer, `row.original` and `getValue()` are the row as shown, in every data column: the open form's values while the row is edited, the committed draft after ✓, and `data` otherwise.
+A column computed from other fields follows the draft as it is typed, and a button in a cell sends the draft the user sees.
+A handler with no cell context, a toolbar action or a callback that received only an id, reaches the same row with `edit.getRowValues(rowId)`.
+
+```demo
+file: editing/ActionCell.tsx
+hint: Double-click a row, change the salary, press Use: the button gets the draft, and data is untouched until Save.
+height: 320
+```
+
+## Styling pending rows
+
+Rows publish what they hold, for styling and for tests:
+
+| Attribute | On | Means |
+| --- | --- | --- |
+| `data-dirty` | Body row, cell | Values typed in, committed or not |
+| `data-draft` | Body row, entry row | Committed into the draft store, waiting for Save |
+| `data-deleted` | Body row | Marked for deletion |
+| `data-new` | Body row, entry row | An entered row, committed (body) or not (entry block) |
+
+A row attribute is present, with the value `"true"`, only on the rows it applies to, so `[data-draft]` and `[data-draft="true"]` match the same rows.
+A cell's `data-dirty` is present only while the cell is dirty.
+
+The grid styles none of them beyond the corners, the strike-through and the new-row tint.
+To highlight every row pending a save, and to let the user toggle it, use `rowStyle` on the Table:
+
+```tsx
+<TMDataGrid.Table
+  rowStyle={(row) =>
+    showPending && grid.edit.state.committedRowIds.includes(row.id)
+      ? { "--row-bg": "color-mix(in srgb, var(--mantine-color-yellow-6) 15%, transparent)" }
+      : undefined
+  }
+/>
+```
+
+`rowClassName` takes a class instead.
+For CSS alone, target the attribute: `[data-dg-part="row"][data-draft="true"]`.
+
+## The edit API
+
+The built-in controls do everything through `edit`, which is public.
+
+| Member | Does |
+| --- | --- |
+| `edit.begin({ rowId, columnId })` | Opens a row into form state. On a committed row, takes it back out of the draft store |
+| `edit.commit(rowId)` | Submits one row: into the draft store under `draft: true`, to `onCommit` otherwise. Resolves `false` if validation blocked it |
+| `edit.commitAll()` | Submits every open row. Resolves `{ ok, committed, open }` - the rows that committed and the rows still open; `ok` is `false` when one stayed open |
+| `edit.saveDrafts()` | Sends the draft store. Open rows are left alone. Resolves `{ ok, saved, kept, reopened }` - the ids that left the store, stayed in it for the next save, or reopened with an error; `ok` is `false` when anything was kept or reopened |
+| `edit.cancel(rowId)` / `edit.cancelAll()` | Drops drafts - form state and the draft store alike |
+| `edit.setCellValue(rowId, columnId, value)` | Writes one cell and commits the row, with no editor. Resolves `false` if the cell takes no edit, or validation refused the value |
+| `edit.setRowValues(rowId, values)` | The same for several cells of one row, in one commit. All or nothing |
+| `edit.clearCell(rowId, columnId)` | Writes the type's empty value and commits it - what Delete does |
+| `edit.addRow(values?)` | Opens one entry row, seeded over `newRowDefaults` |
+| `edit.addRows(rows, options?)` | Opens a batch; `{ commit: true }` submits the rows too - one publish for the lot under `draft: true`. Resolves `{ ok, committed, open }` |
+| `edit.deleteRow(rowId)` | Deletes a row, or marks it deleted under `draft: true`. Idempotent; discards an entry row; ignores an unknown id |
+| `edit.deleteRows(rowIds)` | `deleteRow` over a list in one call - safe to feed a selection as it stands |
+| `edit.restoreRow(rowId)` | Removes a row's deletion mark - what the lane's Restore calls |
+| `edit.canEditCell(row, column)` | Whether a cell may open an editor: the column takes edits and the row does too |
+| `edit.canEditRow(row)` | Whether a row takes edits at all - what shows the edit lane's pencil |
+| `edit.isColumnEditable(column)` | Whether a column takes edits at all, with no row in hand |
+| `edit.getForm(rowId)` | The open row's live `FormApi`; `undefined` for a committed row |
+| `edit.getRowValues(rowId)` | The row as shown: its draft where one is held, else the `data` value. `undefined` for an unknown row |
+| `edit.getRows()` | Every row as shown - drafts overlaid, entry rows appended, deletion-marked rows included and flagged `deleted` |
+| `edit.store` | Open rows, committed rows, active cell, dirty and error projections, draft values, the committed values the table shows (`committedValues`), entry rows, deletion marks, and `isSaving` |
+
+`commit`, `commitAll`, `saveDrafts`, `setCellValue`, `setRowValues`, `clearCell` and `addRows` return promises.
+Await each call before starting the next when driving edits in a loop.
+
+`getForm` returns the open row's own `FormApi`.
+Render it in a drawer or side panel and it shares values, dirty state and errors with the inline cells.
+A committed row has no form, so `getForm` returns `undefined` for it; call `begin` first, which reopens the row with a form seeded from the committed values.
+
+`getRowValues` and `getRows` read what the grid shows rather than what `data` holds: an open form's values, a committed draft, or the `data` value when neither exists.
+`getRows` walks the core row model, so it is unfiltered and never contains group rows, and it filters nothing out: a row marked deleted comes back flagged `deleted`, an entry row flagged `isNew` under its temp id.
+The order is the core row model's, committed new rows ahead of the `data` rows, and then the entry rows the table does not hold: the ones still being typed into, and the committed ones under `newRowsSticky`.
+
+```tsx
+const selected = grid.table
+  .getSelectedRowModel()
+  .rows.flatMap((row) => grid.edit.getRowValues(row.id) ?? []);
+
+const surviving = grid.edit.getRows().filter((row) => !row.deleted);
+```
+
+For the inverse, a `@tanstack/react-form` form _around_ the grid holding the row array, see [A query builder form](/docs/query-builder).
+
+### Bulk actions
+
+`edit.setCellValue(rowId, columnId, value)` writes one cell and commits its row without an editor ever opening, for a toolbar action or a bulk fill.
+The row need not be mounted, so a selected row inside a collapsed group takes the write like any other.
+
+```tsx
+for (const row of grid.table.getSelectedRowModel().rows) {
+  await grid.edit.setCellValue(row.id, "targetPct", equalWeight(row.original));
+}
+```
+
+Under `draft: true` each row is committed into the draft store like a typed edit: the whole batch saves at once through `edit.saveDrafts()`, carries the same markers, and is reverted row by row from the edit lane.
+
+`edit.setRowValues(rowId, values)` does the same for several cells of one row in a single commit: one `onCommit` call and one draft entry rather than one per column.
+Keys are column ids, and it is all or nothing: if any named cell takes no edit, nothing is written and it resolves `false`.
+
+```tsx
+await grid.edit.setRowValues(row.id, { status: "Closed", closedOn: today() });
+```
+
+Both resolve `false` when the cell takes no edit - no such row or column, `editing.columns` excludes it, `meta.edit.enabled` is off, or the row is not editable - and when validation refuses the value, which leaves the row open carrying its errors.
+`value` is the stored value: no editor runs, so `meta.edit.mapValue` does not run either, while `meta.edit.validate` does.
+
+## Reference
+
+| Name                          | Kind           | Type                                             | Default           | What it does                                                                                     |
+| ----------------------------- | -------------- | ------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------ |
+| `editing`                     | Option         | `TMDataGridEditingOptions`                       | –                 | Turns editing on. One object holding both axes and every editing callback.                       |
+| `editing.mode`                | Member         | `"cell" \| "cellConfirm" \| "row"`               | –                 | Picks what counts as a commit and which controls trigger it.                                     |
+| `TMDataGridEditMode` | Type | `"cell" \| "cellConfirm" \| "row"` | – | The type of `editing.mode`. |
+| `editing.draft`               | Member         | `boolean`                                        | `false`           | Holds commits in the draft store for `edit.saveDrafts()` instead of sending them out.             |
+| `getRowId`                    | Table option   | `(row) => string`                                | –                 | Required once `editing` is set. Drafts are keyed by it.                                          |
+| `editing.columns`             | Member         | `ReadonlyArray<string>`                          | Every mapped column | The column ids that take edits. Gates before `meta.edit`, never past it.                       |
+| `editing.isRowEditable`       | Member         | `(row) => boolean`                               | –                 | Closes a whole row to editing.                                                                   |
+| `editing.rowValidators`       | Member         | TanStack Form validators                         | –                 | Form-level rules for the whole editing row. See [Editors](/docs/editors).                        |
+| `editing.tableValidators`     | Member         | `TMDataGridTableValidators`                      | –                 | Cross-row rules, handed the collection with every draft overlaid. See [Editors](/docs/editors#cross-row-rules). |
+| `editing.onCommit`            | Callback       | `({ rowId, value, original, changes, source }) => void \| Promise` | – | Applies one row's change. Reject to keep the draft.                                              |
+| `TMDataGridEditCommitArgs` · `TMDataGridEditChange` | Types | – | – | What `onCommit` receives, and one entry of its `changes`. |
+| `meta.edit.enabled`           | Column meta    | `boolean \| (row) => boolean`                    | `true`            | Whether a column's cells edit.                                                                   |
+| `meta.edit.field`             | Column meta    | `string`                                         | The `accessorKey` | The data path an edit writes to.                                                                 |
+| `meta.edit.mapValue`          | Column meta    | `({ value, previous, row, column }) => unknown`  | –                 | Maps each value an editor writes. See [Editors](/docs/editors#mapping-the-value-as-it-is-typed). |
+| `EDIT_COLUMN_ID`              | Export         | `"__edit__"`                                     | –                 | Id of the generated edit lane.                                                                   |
+| `clearedValueForType`         | Export         | `(type) => unknown`                              | –                 | What Delete writes for each column type.                                                         |
+| `TMDataGridEditState` · `TMDataGridEditRowProjection` | Types | – | – | The value of `edit.state` and `edit.store`, and one open row's entry in its `rows`. |
+| `TMDataGridEditRowSnapshot` | Type | `{ rowId, value, isNew, deleted }` | – | One row of `edit.getRows()`. |
+| `data-dirty`                  | Data attribute | –                                                | –                 | On a body row holding a dirty draft.                                                             |
+| `data-draft`                  | Data attribute | –                                                | –                 | On a body row or entry row committed into the draft store, waiting for a save.                   |

package/docs/editors.md

@@ -0,0 +1,250 @@
+# Editors and validation
+
+Which control a cell opens when editing starts, what the value becomes on the
+way in, and what prevents a bad one being committed. All three follow from the
+column: `meta.type` picks the editor, and `meta.edit` holds the rest.
+
+```demo
+file: editing/EditorsAndValidation.tsx
+hint: Type a single letter into String, or 5 into Number, to see validation reject it.
+height: 440
+```
+
+## The built-in editors
+
+`meta.type` picks one, and `meta.options` feeds the select editors from the same
+source the filter panel reads. Neither lives under `meta.edit`.
+
+| `meta.type` | Editor | Writes |
+| --- | --- | --- |
+| `string` (default) | Text input | `string` |
+| `number` | Number input | `number`, or `null` while the cell is empty or the text is not yet a number |
+| `boolean` | Checkbox | `boolean` |
+| `date` | Native `<input type="date">` | A `Date`, or the `"YYYY-MM-DD"` string; `null` when cleared |
+| `select` | Searchable select from `meta.options`. Commits on pick under `"cell"` | `string \| null` |
+| `multiSelect` | Multi-select, same source | `string[]` |
+
+**Writes** is the value the editor puts into the draft: what `meta.edit.mapValue` is handed, what `meta.edit.validate` checks, and what a commit carries in `value` and in `changes[].next`.
+
+The number editor writes `null` rather than `NaN` while the text does not parse, so a half-typed number leaves the field empty instead of committing a number no rule can describe.
+The date editor picks between its two types once, when it opens, from what the cell held: a `Date` cell keeps receiving `Date`s and a string cell keeps receiving `"YYYY-MM-DD"` strings, so clearing and retyping cannot flip the type.
+
+Each is a named export (`TMDataGridStringEditor`, `TMDataGridNumberEditor`,
+`TMDataGridBooleanEditor`, `TMDataGridDateEditor`, `TMDataGridSelectEditor`,
+`TMDataGridMultiSelectEditor`), so a custom editor can wrap one instead of
+starting from scratch.
+
+## Writing your own
+
+`meta.edit.editor` fills the same slot as the built-ins. It is a **component**,
+rendered as JSX, so hooks may be used inside, and it receives the live TanStack
+Form `field` API. Bind any control to it as you would inside a form:
+
+```tsx
+const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
+  <Slider
+    value={field.state.value}
+    onChange={field.handleChange}
+    onChangeEnd={() => void commit()}
+  />
+);
+
+meta: { edit: { editor: SalaryEditor } }
+```
+
+**Define editors at module scope.** An inline arrow function gets a new identity
+on every render, which remounts the editor mid-edit and discards what was typed.
+
+The field's validation message is shown by the host, in a tooltip on the
+editor: open while the input is focused, and on hover. A custom editor gets the
+same tooltip, so it renders no message of its own.
+
+The built-in editors mark the input invalid and add no inline text, since the
+message would be clipped by the width of the cell. A custom editor does the
+same by binding a boolean to the control's `error` prop:
+
+```tsx
+const hasError = field.state.meta.errors.length > 0;
+
+<Slider value={field.state.value} onChange={field.handleChange} error={hasError} />;
+```
+
+## Mapping the value as it is typed
+
+A column can rewrite every value on its way into the draft: uppercase a code,
+strip spaces out of an IBAN, clamp a number into range. `meta.edit.mapValue`
+runs on each write an editor makes, which is each keystroke for a text input and
+each pick for a select.
+
+```demo
+file: editing/MappedInput.tsx
+hint: Type into either column. Code uppercases, Reference keeps digits only.
+height: 420
+```
+
+```tsx
+meta: {
+  edit: {
+    mapValue: ({ value }) =>
+      typeof value === "string" ? value.toUpperCase() : value,
+  },
+}
+```
+
+What it returns is what the cell shows, what the validators check and what is
+committed.
+
+The map is applied inside the editor host, around the field every editor writes
+through, so one declaration covers all six built-in editors, your own
+`meta.edit.editor`, and the character that opened the editor when typing started
+the edit.
+
+Some writes are not mapped: the value the editor opens with, and the writes that go through the form rather than through an editor - `edit.clearCell()`, the Delete key, `edit.setCellValue()` and `edit.setRowValues()`.
+An editor calling `field.setValue` instead of `field.handleChange` also bypasses the map.
+`handleChange` is the mapped path.
+
+The map receives the row and column as well, so it can depend on the record
+being edited:
+
+```tsx
+meta: {
+  edit: {
+    mapValue: ({ value, row }) =>
+      row.original.country === "SE" && typeof value === "string"
+        ? value.replace(/ /g, "")
+        : value,
+  },
+}
+```
+
+`previous` is the value the field held before this write, which a mask needs in
+order to tell an insertion from a deletion.
+
+### Keeping the caret
+
+A mapped value differs from the one the input holds, so React writes the new
+value into the DOM node and the browser collapses the selection to the end of
+the field.
+
+The built-in string and number editors restore the caret to where it was typed,
+shifted by however much the map changed the length, so a mask that inserts or
+strips characters keeps the caret beside the same text.
+
+A custom editor rendering its own input has the same problem, and solves it the
+same way: record `selectionStart` as the value is handed over, and restore it in
+a layout effect once the mapped value has rendered.
+
+## Validation
+
+The validators are TanStack Form's own: a Standard Schema (Zod, Valibot,
+ArkType) or a plain function returning an error message or nothing.
+
+```tsx
+// Per column: field-level validators. A bare schema or function means { onChange: it }.
+meta: { edit: { validate: z.string().min(2, "Too short") } }
+
+// The same rule without a schema library:
+meta: {
+  edit: {
+    validate: ({ value }: { value: unknown }) =>
+      typeof value === "string" && value.length < 2 ? "Too short" : undefined,
+  },
+}
+
+// Per row: form-level validators - cross-field rules live here.
+useTMDataGrid({
+  editing: {
+    mode: "cell",
+    rowValidators: {
+      onSubmit: z.object({ salary: z.number().positive() })
+        .refine((r) => r.status !== "Terminated" || r.salary === 0, {
+          message: "A terminated employee has no salary",
+        }),
+    },
+  },
+});
+```
+
+A plain function is typed `TMDataGridValidator`, whose `value` is `never`, so annotate the parameter - `{ value: unknown }`, or the type the column's editor writes - rather than leaving it to be inferred.
+
+Pathed issues land on the matching cells; pathless ones on the row, where the
+message shows in the edit lane's tooltip on the open row's ✓. To show a
+pathless message somewhere of your own, read it from
+`edit.getForm(rowId)?.state.errors` on the open row that carries it;
+`edit.store` carries the flag (`hasRowError`) and the field messages
+(`errorMessages`), not the row text.
+
+A commit blocked by validation keeps the editor open, invalid, with the message
+in its tooltip. A rejected `editing.onCommit` keeps the draft too, with the
+error on the row. Server-side field errors can be returned natively through
+`editing.rowValidators.onSubmitAsync`'s `{ form, fields }` shape.
+
+Cross-field rules need a mode that commits the whole row at once. Under
+`"cell"` each cell commits alone, so a rule spanning two columns cannot be
+satisfied by either one. Use `editing.rowValidators.onSubmit` with `"row"`. See
+[Editing](/docs/editing#row-editing).
+
+A rule about the whole collection, such as "no duplicates" or "shares sum to
+100", is neither a field rule nor a row rule. It takes
+`editing.tableValidators` - see [Cross-row rules](#cross-row-rules).
+
+## Cross-row rules
+
+`editing.tableValidators` holds the rules that need the other rows: no
+duplicate keys, no overlapping ranges, allocations summing to a total. Its
+validators receive the committing row and `rows`, the collection as it would
+stand if the commit landed - every draft overlaid, entry rows appended,
+deletion-marked rows removed:
+
+```tsx
+editing: {
+  mode: "cell",
+  draft: true,
+  tableValidators: {
+    onSubmit: ({ value, rowId, rows }) =>
+      rows.some((r) => r.rowId !== rowId && r.value.code === value.code)
+        ? { fields: { code: "Codes must be unique" } }
+        : undefined,
+  },
+}
+```
+
+The result is the `rowValidators` vocabulary: nothing passes, a string is a
+row-level message, and `{ form, fields }` lands pathed issues on the
+committing row's cells. `onSubmit` runs first, and its failure stands without
+`onSubmitAsync` running.
+
+The rules run at every commit, after the row's own validators, and again for
+every committed row during `saveDrafts`, where they are the only rules that
+run: column rules and `rowValidators` saw the same values at commit. A
+committed row that a later edit has invalidated is reopened with its errors,
+the valid rows are sent, and the save reports it in `reopened`. Errors land on the
+committing row only; the row it clashes with is not marked.
+
+`rows` is unfiltered, so a rule sees the whole collection whatever the view
+shows, and it never contains group rows.
+
+```demo
+file: editing/TableValidation.tsx
+hint: Give two teams the same code, or push the shares past 100, and the commit is refused. Drafts count - a clash with a pending edit is caught too.
+height: 380
+```
+
+A grid inside an outer form can put collection rules in the form's own field
+validator instead. See [A query builder form](/docs/query-builder).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `meta.edit.editor` | Column meta | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. |
+| `meta.edit.validate` | Column meta | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema or function means `onChange`. |
+| `meta.edit.mapValue` | Column meta | `TMDataGridEditValueMap` | – | Maps each value an editor writes, before it reaches the draft. |
+| `editing.rowValidators` | Option | `TMDataGridRowValidators` | – | Form-level validation, for cross-field rules. |
+| `editing.tableValidators` | Option | `TMDataGridTableValidators` | – | Cross-row rules, handed the collection with every draft overlaid. See [Cross-row rules](#cross-row-rules). |
+| `TMDataGridTableValidateArgs` | Export | type | – | What a table validator receives: `value`, `rowId`, `isNew`, `rows`. |
+| `TMDataGridEditorArgs` | Export | type | – | What an editor component receives: `field`, `commit`, `cancel`, `row`, `column`. |
+| `TMDataGridEditValueMapArgs` | Export | type | – | What `mapValue` receives: `value`, `previous`, `row`, `column`, `table`. |
+| `TMDataGridStringEditor` · `NumberEditor` · `BooleanEditor` · `DateEditor` · `SelectEditor` · `MultiSelectEditor` | Exports | components | – | The six built-ins, for wrapping. |
+| `normalizeFieldValidate` | Export | `(validate) => validators` | – | Turns a bare schema into TanStack Form's validator shape. |
+| `getEditFieldName` | Export | `(column) => string` | – | The data path a column's edits write to. |