@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/skills/editing/references/common-mistakes.md

@@ -22,7 +22,7 @@ useTMDataGrid({
 Correct: wire `editing.onCommit` to apply the change where the data lives, as
 in the skill's Setup section.
 
-Source: `src/docs/editing.md`, `src/tmdatagrid/core/editEngine.ts`.
+Source: `packages/tmdatagrid/docs/editing.md`, `packages/tmdatagrid/src/core/editEngine.ts`.
 
 ## CRITICAL `getRowId` built from the row index
 
@@ -42,7 +42,7 @@ Correct:
 getRowId: (row) => String(row.id),
 ```
 
-Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
+Source: `packages/tmdatagrid/src/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
 
 ## HIGH A cell editor defined inside the component
 
@@ -71,7 +71,7 @@ const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
 meta: { edit: { editor: SalaryEditor } },
 ```
 
-Source: `src/docs/editors.md`, `src/tmdatagrid/core/editEngine.ts`.
+Source: `packages/tmdatagrid/docs/editors.md`, `packages/tmdatagrid/src/core/editEngine.ts`.
 
 ## HIGH A cross-field rule under `editing.mode: "cell"`
 
@@ -79,10 +79,10 @@ Under `"cell"` each cell commits on its own, so a rule spanning two columns
 cannot be satisfied by either one: the first cell edited is rejected against the
 other column's old value, and the row cannot be saved.
 
-Correct: `editing.rowValidators` needs `mode: "row"` or `"draft"`, which
-validate the whole row in one commit.
+Correct: `editing.rowValidators` needs `mode: "row"`, which validates the
+whole row in one commit.
 
-Source: `src/docs/editors.md` (Validation).
+Source: `packages/tmdatagrid/docs/editors.md` (Validation).
 
 ## HIGH An `accessorFn` column that never opens an editor
 
@@ -109,7 +109,7 @@ columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
 });
 ```
 
-Source: `src/docs/editing.md` (Which cells edit).
+Source: `packages/tmdatagrid/docs/editing.md` (Which cells edit).
 
 ## HIGH Swallowing the error in `editing.onCommit`
 
@@ -120,9 +120,9 @@ and the grid shows the old value as though nothing happened.
 Wrong:
 
 ```tsx
-onCommit: async ({ rowId, changes }) => {
+onCommit: async ({ rowId, value }) => {
   try {
-    await api.patch(rowId, changes);
+    await api.put(rowId, value);
   } catch (error) {
     console.error(error);
   }
@@ -132,12 +132,13 @@ onCommit: async ({ rowId, changes }) => {
 Correct: no `catch` - let the rejection propagate, and the form stays open
 with the error on the row.
 
-Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
+Source: `packages/tmdatagrid/src/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
 
 ## HIGH Submitting an outer form while the grid holds a draft
 
 The outer form's array contains only committed rows. Under any mode a mid-edit
-row is invisible to it, and under `"draft"` every edit is until `submitAll()`,
+row is invisible to it, and under `draft: true` every edit is until
+`saveDrafts()`,
 so a form submit saves stale rows and collection rules skip pending values.
 
 Correct:
@@ -146,32 +147,118 @@ Correct:
 const hasOpenDraft = useSelector(grid.edit.store, (s) => s.openRowIds.length > 0);
 
 <Button type="submit" disabled={!canSubmit || hasOpenDraft}>Save</Button>
-// or flush instead of blocking:
-const flushed = await grid.edit.submitAll();
+// or commit and flush instead of blocking:
+await grid.edit.commitAll();
+const flushed = await grid.edit.saveDrafts();
 if (flushed) await form.handleSubmit();
 ```
 
-Source: `src/docs/query-builder.md` (Which mode, Submitting).
+Source: `packages/tmdatagrid/docs/query-builder.md` (Which mode, Submitting).
+
+## HIGH A bulk write built from `begin`, `getForm` and `commit`
+
+`edit.setCellValue(rowId, columnId, value)` writes one cell and commits its row, so a fill over the selection is one call per row.
+Reaching instead for `begin`, then `getForm(rowId)?.setFieldValue(...)`, then `commit` looks equivalent and is not: under `editing.mode: "cell"`, `begin` defers behind a pending commit whenever another row is open, so `getForm(rowId)` returns `undefined` immediately after it and the optional chain writes nothing.
+The `commit` that follows finds no form and resolves `true`, reporting a write that never happened.
+
+Wrong:
+
+```tsx
+for (const row of grid.table.getSelectedRowModel().rows) {
+  grid.edit.begin({ rowId: row.id, columnId: "targetPct" });
+  grid.edit.getForm(row.id)?.setFieldValue("targetPct", next(row.original));
+  await grid.edit.commit(row.id);
+}
+```
+
+Correct:
+
+```tsx
+for (const row of grid.table.getSelectedRowModel().rows) {
+  await grid.edit.setCellValue(row.id, "targetPct", next(row.original));
+}
+
+// Several cells of one row: one commit, one draft entry.
+await grid.edit.setRowValues(rowId, { status: "Closed", closedOn: today() });
+```
+
+Both write the stored value through the row's form, so `meta.edit.mapValue` does not run - no editor is involved - while `meta.edit.validate` does, at the commit.
+A refused value leaves the row open carrying its errors and the call resolves `false`, so read the result rather than assuming the fill landed.
+
+Source: `packages/tmdatagrid/src/core/editEngine.ts` (`begin`, `writeFields`).
+
+## MEDIUM A computed column frozen while a row is edited
+
+A held draft is displayed by the column that owns the field. A column computed
+from other fields - `accessorFn` or `display` - reads `row.original`, which is
+`data`, so it keeps showing the saved record while the values it derives from
+are being typed.
+
+Correct: read the drafted row from `edit.store` inside the cell renderer:
+
+```tsx
+function useDraftedRow(rowId: string, original: Product): Product {
+  const { edit } = useTMDataGridContext();
+  const values = useSelector(edit.store, (state) => state.rows[rowId]?.values);
+  return (values as Product | undefined) ?? original;
+}
+```
+
+Source: `packages/tmdatagrid/docs/editing.md` (Draft lifetime).
 
 ## MEDIUM Reading a commit's result as the saved value
 
-`edit.commit(rowId)` and `edit.submitAll()` resolve to a `boolean` saying
-whether the form closed, and resolve `false` when validation or a rejected save
-kept it open. Ignoring the result reports a save that did not happen.
+`edit.commit(rowId)`, `edit.commitAll()` and `edit.saveDrafts()` resolve to a
+`boolean` saying whether everything landed, and resolve `false` when validation
+or a rejected save kept a row open. Ignoring the result reports a save that did
+not happen.
 
 ```tsx
-const saved = await grid.edit.submitAll();
+const saved = await grid.edit.saveDrafts();
 notifications.show({ message: saved ? "Saved" : "Some rows need attention" });
 ```
 
-Source: `src/tmdatagrid/core/editEngine.ts` (`TMDataGridEditApi`).
+Source: `packages/tmdatagrid/src/core/editEngine.ts` (`TMDataGridEditApi`).
 
-## MEDIUM Expecting `editing.onRowDelete` to fire under draft
+## MEDIUM Expecting `editing.onRowDelete` to fire under a draft store
 
-Under the immediate modes `edit.deleteRow` calls `editing.onRowDelete` at once.
-Under `"draft"` it only toggles a deletion mark, so nothing is removed until
-`submitAll`: the ids arrive as `deleted` in `editing.onCommitDrafts`, or, with
+Without `editing.draft`, `edit.deleteRow` calls `editing.onRowDelete` at once.
+Under `draft: true` it only toggles a deletion mark, so nothing is removed until
+`saveDrafts`: the ids arrive as `deleted` in `editing.onSaveDrafts`, or, with
 no such callback, in the per-row `editing.onRowDelete` loop. A confirmation
 placed inside `editing.onRowDelete` therefore guards the save, not the trash.
 
-Source: `src/docs/editing.md` (Adding and deleting rows).
+Source: `packages/tmdatagrid/docs/editing.md` (Adding and deleting rows).
+
+## MEDIUM A custom editor that binds no invalid state
+
+The message is the host's: it shows in a tooltip on the editor whatever the
+editor is. The invalid styling is the editor's own, and one that binds nothing
+keeps its normal border while the commit is refused, so the only marks on
+screen are the tooltip and `data-invalid` on the cell.
+
+Wrong:
+
+```tsx
+const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
+  <Slider value={field.state.value} onChange={field.handleChange} onChangeEnd={() => void commit()} />
+);
+```
+
+Correct:
+
+```tsx
+const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => {
+  const hasError = field.state.meta.errors.length > 0;
+  return (
+    <Slider
+      value={field.state.value}
+      onChange={field.handleChange}
+      onChangeEnd={() => void commit()}
+      error={hasError}
+    />
+  );
+};
+```
+
+Source: `packages/tmdatagrid/docs/editors.md` (Writing your own).

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

@@ -8,26 +8,30 @@ kind.
 | Name | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `editing` | `TMDataGridEditingOptions` | off | The editing namespace. Setting it turns editing on. |
-| `editing.mode` | `"cell" \| "cellConfirm" \| "row" \| "draft"` | – | Picks the commit policy. |
+| `editing.mode` | `"cell" \| "cellConfirm" \| "row"` | – | What counts as a commit, and which controls trigger it. |
+| `editing.draft` | `boolean` | `false` | Where a commit goes. On, it is held in the grid's draft store until `edit.saveDrafts()`. |
 | `getRowId` | `(row) => string` | – | A TanStack table option, required once `editing` is set. Drafts are keyed by it. |
+| `editing.columns` | `ReadonlyArray<string>` | every column mapping to a data path | The column ids that take edits. Gates before `meta.edit`, never past it: a column left out takes no edits whatever its meta says, and a listed column still answers to its `meta.edit.enabled`. Also decides which cells an entry row opens. |
 | `editing.isRowEditable` | `(row) => boolean` | – | Closes a whole row to editing, in every mode. |
 | `editing.rowValidators` | `TMDataGridRowValidators` | – | Form-level validation. Cross-field rules live here. |
+| `editing.tableValidators` | `TMDataGridTableValidators` | – | Cross-row rules, handed the collection with every draft overlaid. |
 | `editing.newRowDefaults` | `TData \| (() => TData)` | – | Seeds the entry row's form. A function is called per added row. |
-| `editing.newRowsSticky` | `boolean` | `false` | Draft mode only. Keeps entered new rows pinned in the entry block until Save all, instead of letting them scroll with the body. |
+| `editing.newRowsSticky` | `boolean` | `false` | `draft: true` only. Keeps committed entry rows in the sticky entry block, out of the body's sort and out of the row count, until the save. Off, a committed entry row becomes a body row. |
 | `cellSelection` | `"none" \| "single" \| "range"` | `"single"` while `editing` is set | Editing turns the cell cursor on; set it explicitly to override. |
 
 Passing any other member of `editing` without `mode` is a compile error, and
-`onCommitDrafts` and `newRowsSticky` exist only in the `"draft"` branch of the
-type.
+`onSaveDrafts` and `newRowsSticky` exist only in the `draft: true` branch of
+the type.
 
 ## Callbacks
 
 | 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.onCommitDrafts` | `{ rows, added, deleted }` | Draft mode only. One call for the entire save. Without it, `submitAll` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onCommitDrafts` | `{ updated, created, deleted }` | **Deprecated** - renamed to `onSaveDrafts`. Still honoured; the new name wins if both are set. |
 | `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
-| `editing.onRowDelete` | `{ rowId, row }` | Deletes a row under the immediate modes, and puts the trash can in the edit lane. |
+| `editing.onRowDelete` | `{ rowId, row }` | Deletes a row. Shows the trash; under `draft: true`, `onSaveDrafts` shows it too. |
 
 `changes` entries are `{ columnId, field, previous, next }`; `field` is the data
 path, which may be dotted.
@@ -49,19 +53,25 @@ path, which may be dotted.
 
 | Member | Signature | Notes |
 | --- | --- | --- |
-| `begin` | `({ rowId, columnId }) => void` | Row mode opens the entire row either way. `columnId` selects which cell takes the caret; `null` (the pencil) uses its first editable one. On an entered new row it reopens the row, flipping `confirmed` back to `false`. |
-| `commit` | `(rowId) => Promise<boolean>` | `false` keeps the form open with its errors. Under `"draft"` it validates and holds the draft: no consumer callback runs until `submitAll`. |
+| `begin` | `({ rowId, columnId }) => void` | Row mode opens the entire row either way. `columnId` selects which cell takes the caret; `null` (the pencil) uses its first editable one. On a committed row it reopens it, taking it back out of the draft store. |
+| `commit` | `(rowId) => Promise<boolean>` | The OK gesture: submits the row's form. `false` keeps it open with its errors, and the message outlives the editor that found it. Under `draft: true` a pass commits the row into the draft store - no consumer callback runs until `saveDrafts`. Column rules run whether or not an editor is mounted. |
+| `commitAll` | `() => Promise<boolean>` | Submits every open row. Rows that fail stay open. `false` when one did. |
+| `saveDrafts` | `() => Promise<boolean>` | Sends the draft store, re-running `editing.tableValidators` only; a committed row that fails is reopened with its errors. Open rows are left alone and stay open. |
 | `cancel` | `(rowId) => void` | Drops one draft. |
 | `cancelAll` | `() => void` | Drops every draft. |
 | `deactivate` | `() => void` | Closes the editor without touching the draft, as blur does under `"cellConfirm"`. |
-| `submitAll` | `() => Promise<boolean>` | Draft mode's Save all. `true` when every row landed. |
+| `submitAll` | `() => Promise<boolean>` | **Deprecated** - `commitAll()` then `saveDrafts()`. |
 | `clearCell` | `(rowId, columnId) => Promise<boolean>` | What Delete does: writes the type's empty value and commits. |
-| `addRow` | `() => string` | Opens an entry row, returns its `tempId`. |
-| `deleteRow` | `(rowId) => void` | `editing.onRowDelete` under the immediate modes, a deletion mark under draft mode. Toggles: a second call restores the row. |
-| `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. |
+| `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<{ committed, open }>` | 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. |
+| `deleteRow` | `(rowId) => void` | `editing.onRowDelete`, or a deletion mark under `draft: true`. Toggles: a second call restores the row. |
+| `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. |
+| `isColumnEditable` | `(column) => boolean` | The column's half alone, with no row in hand: it maps to a field, `editing.columns` lists it when that is set, and `meta.edit.enabled` is not `false`. |
 | `canDeleteRows` | `() => boolean` | Whether the delete control should be shown. |
-| `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The row's live `FormApi`. |
+| `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The open row's live `FormApi`; `undefined` for a committed row. |
 | `state` | `TMDataGridEditState` | Snapshot, for reads outside React. |
 | `store` | `Store<TMDataGridEditState>` | For `useSelector`. |
 
@@ -71,10 +81,10 @@ path, which may be dotted.
 type TMDataGridEditState = {
   // The cell the last open gesture named - where the caret goes.
   active: { rowId: string; columnId: string | null } | null;
-  // Rows with a live form. One under `"cell"`; as many as the user opened
-  // under `"row"`, `"cellConfirm"` and `"draft"` - which rows are editing.
+  // Every row the grid holds work for: open rows and committed rows. A row
+  // is *open* when it is in here and not in `committedRowIds`.
   openRowIds: ReadonlyArray<string>;
-  // One `TMDataGridEditRowProjection` per open row.
+  // One `TMDataGridEditRowProjection` per row in `openRowIds`.
   rows: Record<
     string,
     {
@@ -86,10 +96,20 @@ type TMDataGridEditState = {
       values: TMDataGridRowData;
     }
   >;
-  // `confirmed` is draft mode's "entered, awaiting Save all". Under the
-  // immediate modes a confirm commits through `onRowAdd`, so it stays `false`.
-  newRows: ReadonlyArray<{ tempId: string; confirmed: boolean }>;
+  // The draft store's edit slice: existing rows that passed their commit,
+  // held as values for `saveDrafts`. Empty without `editing.draft`.
+  committedRowIds: ReadonlyArray<string>;
+  // What a committed row *is* to the table: the draft store's values per row,
+  // snapshotted at each commit and kept across a reopen, so the row holds its
+  // place until it commits again or is dropped. The grid feeds these to the
+  // table in place of the consumer's records.
+  committedValues: Readonly<Record<string, TMDataGridRowData>>;
+  // `committed` is "in the store, awaiting the save". Without `editing.draft`
+  // a commit adds through `onRowAdd`, so it stays `false`.
+  newRows: ReadonlyArray<{ tempId: string; committed: boolean }>;
   deletedRowIds: ReadonlyArray<string>;
+  // `true` while `saveDrafts` is in flight.
+  isSaving: boolean;
 };
 ```
 
@@ -97,8 +117,8 @@ type TMDataGridEditState = {
 
 | Name | Kind | What it is |
 | --- | --- | --- |
-| `TMDataGrid.EditActions` | Component | Save with the pending count, and Discard. Any mode; renders nothing while editing is off. Takes `renderActions` over `{ state, actions, Controls }`. |
-| `TMDataGridEditActions` | Export | The same component, for use outside the namespace. |
+| `TMDataGrid.DraftActions` | Component | Save with the draft-store count, Discard, and a note counting the rows still open. Any mode; renders nothing while editing is off. Takes `renderActions` over `{ state, actions, Controls }` - `state.openRowIds` and `actions.scrollToFirstOpenRow(align?)` reach the rows left open. |
+| `TMDataGridDraftActions` | Export | The same component, for use outside the namespace. |
 | `EDIT_COLUMN_ID` | Export | `"__edit__"`, the generated edit lane's id. |
 | `clearedValueForType` | Export | `(type) => unknown` - what Delete writes per column type. |
 | `getEditFieldName` | Export | `(column) => string` - the data path a column's edits write to. |
@@ -118,20 +138,24 @@ Generated, pinned right, id `EDIT_COLUMN_ID`. It appears when any of these
 holds:
 
 - `editing.mode: "row"` - the lane is Save and Cancel's home
-- `editing.mode: "draft"` - the lane is the change indicator and the per-row
-  revert, and `editing.onCommitDrafts` is not required for it
+- `editing.draft` - the lane is the change indicator and the per-row revert,
+  and `editing.onSaveDrafts` is not required for it
 - `editing.onRowDelete` is set - the trash can has somewhere to report to
 
-`"cell"` and `"cellConfirm"` have no lane unless `editing.onRowDelete` asks for
-one.
+`"cell"` and `"cellConfirm"` have no lane unless `editing.draft` or
+`editing.onRowDelete` asks for one.
 
-What the lane holds depends on the mode. Under `"row"` an open row shows
-`save-row` and `cancel-row`; those two never render under `"draft"`. Under
-`"draft"` every changed row shows `row-state`, whose `data-state` is `new`,
-`edited` or `deleted`, together with `revert-row` on an edited row,
-`restore-row` on one marked for deletion, and `edit-row` plus `discard-new-row`
-on an entered new row. A row holding a dirty draft hides `delete-row`. Every
-control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
+The trash itself shows when the deletion has somewhere to report to:
+`onRowDelete` is set, or under `draft: true`, `onSaveDrafts` is - a deletion
+mark is part of the save.
+
+What the lane holds follows the row's state, one axis each. An open row shows
+the mode's own controls, `save-row` and `cancel-row`. A committed row shows
+`row-state` instead, whose `data-state` is `new`, `edited` or `deleted`,
+together with `revert-row` on an edited row, `restore-row` on one marked for
+deletion, and `edit-row` plus `discard-new-row` on an entered new row - never a
+save, which the engine would only commit again. A committed row hides `delete-row`.
+Every control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
 `rowStateEdited` and `rowStateDeleted` among them.
 
 ## Styling and test hooks
@@ -139,17 +163,17 @@ control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
 | Name | Kind | What it is |
 | --- | --- | --- |
 | `--dg-entry-height` | CSS variable | Height of the sticky entry block. From `size`. |
-| `--dg-row-new-bg` | CSS variable | Background of an entered new row. A green tint. |
-| `data-deleted` | Row attribute | On a row marked for deletion under draft mode. |
+| `--dg-row-new-bg` | CSS variable | Background of a committed new row, in the body or the entry block. A green tint. |
+| `data-deleted` | Row attribute | On a row marked for deletion under `draft: true`. |
 | `data-dirty` | Row attribute | On a body row holding a dirty draft. Also on the cell whose field is dirty. |
-| `data-new` / `data-confirmed` | Entry row attributes | On an entry row; `data-confirmed` once it is entered, awaiting Save all. |
-| `data-dg-entry-flow-block` | Attribute | The in-flow block above the body rows holding entered new rows, unless `editing.newRowsSticky` keeps them in the sticky entry block. |
+| `data-new` | Row attribute | On a body row that is a committed new row, and on an entry row. |
+| `data-committed` | Entry row attribute | On an entry row once it is committed, awaiting the save. Seen only under `editing.newRowsSticky`. |
 | `data-dg-part="editor-input"` | Part | The control inside an editing cell. |
-| `data-dg-part="save-row"` / `"cancel-row"` | Parts | The edit lane's buttons on an open row, with `data-row-id`. Row mode only. |
-| `data-dg-part="row-state"` | Part | Draft mode's change marker, with `data-row-id` and `data-state` of `new`, `edited` or `deleted`. |
+| `data-dg-part="save-row"` / `"cancel-row"` | Parts | The edit lane's buttons on an open row, with `data-row-id`. |
+| `data-dg-part="row-state"` | Part | The draft store's change marker, with `data-row-id` and `data-state` of `new`, `edited` or `deleted`. |
 | `data-dg-part="revert-row"` / `"restore-row"` | Parts | Drops a row's draft, and undoes a deletion mark, with `data-row-id`. |
 | `data-dg-part="edit-row"` / `"delete-row"` | Parts | The idle lane's pencil and trash, with `data-row-id`. `edit-row` also reopens an entered new row. |
 | `data-dg-part="confirm-new-row"` / `"discard-new-row"` | Parts | An entry row's ✓ and ✕, with `data-row-id`. |
-| `data-dg-part="save-all"` / `"discard-all"` | Parts | `EditActions`. |
+| `data-dg-part="save-all"` / `"discard-all"` | Parts | `DraftActions`. |
 
 See the `testing` skill for how to compose these into selectors.

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

@@ -8,14 +8,20 @@ bad value being committed. Both follow from the column.
 `meta.type` picks one, `meta.options` feeds the two select editors from the same
 declaration the filter panel reads.
 
-| `meta.type` | Editor | Export |
-| --- | --- | --- |
-| `"string"` (default) | Text input | `TMDataGridStringEditor` |
-| `"number"` | Number input | `TMDataGridNumberEditor` |
-| `"boolean"` | Checkbox | `TMDataGridBooleanEditor` |
-| `"date"` | Native `<input type="date">`, ISO `YYYY-MM-DD` | `TMDataGridDateEditor` |
-| `"select"` | Searchable select, commits on pick under `"cell"` | `TMDataGridSelectEditor` |
-| `"multiSelect"` | Multi-select, same source | `TMDataGridMultiSelectEditor` |
+| `meta.type` | Editor | Writes | Export |
+| --- | --- | --- | --- |
+| `"string"` (default) | Text input | `string` | `TMDataGridStringEditor` |
+| `"number"` | Number input | `number`, or `null` while the cell is empty or the text is not yet a number | `TMDataGridNumberEditor` |
+| `"boolean"` | Checkbox | `boolean` | `TMDataGridBooleanEditor` |
+| `"date"` | Native `<input type="date">` | A `Date`, or the ISO `"YYYY-MM-DD"` string; `null` when cleared | `TMDataGridDateEditor` |
+| `"select"` | Searchable select, commits on pick under `"cell"` | `string \| null` | `TMDataGridSelectEditor` |
+| `"multiSelect"` | Multi-select, same source | `string[]` | `TMDataGridMultiSelectEditor` |
+
+**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.
+A validator for a date column has to accept whichever of the two that column's data holds.
 
 ```tsx
 columnHelper.accessor("department", {
@@ -57,6 +63,12 @@ Bind any control to `field` exactly as inside any TanStack Form:
 `field.state.value`, `field.state.meta.errors`, `field.handleChange`,
 `field.handleBlur`.
 
+The message itself is the host's: it shows in a tooltip on the editor, opened
+by focus and by hover, for a custom editor as much as a built-in one. What an
+editor binds is the invalid state - the built-ins pass a boolean to the input's
+`error` prop for the border alone, and an editor that binds nothing looks
+unchanged while the commit is refused.
+
 ```tsx
 import { Slider } from "@mantine/core";
 import type { TMDataGridEditorComponent } from "@jielga/tmdatagrid";
@@ -155,6 +167,9 @@ Left unmapped on purpose:
   edited, mark a pristine row dirty and swallow the select-all.
 - `edit.clearCell()`, the Delete key: it writes the type's empty value through
   the form, so there is no input to map.
+- `edit.setCellValue()` and `edit.setRowValues()`: they write through the form
+  too, and the caller passes the stored value itself. `meta.edit.validate` still
+  runs on the commit.
 - An editor calling `field.setValue`. `handleChange` is the mapped path.
 
 The built-in string and number editors restore the caret after a mapped write,
@@ -178,8 +193,13 @@ meta: { edit: { validate: z.string().min(2, "At least two characters") } }
 // Object form: pick the trigger.
 meta: { edit: { validate: { onBlur: z.string().email("Not an email address") } } }
 
-// A plain function works too.
-meta: { edit: { validate: ({ value }) => (value > 0 ? undefined : "Must be positive") } }
+// A plain function works too. `value` is typed `never`, so annotate the parameter.
+meta: {
+  edit: {
+    validate: ({ value }: { value: unknown }) =>
+      typeof value === "number" && value > 0 ? undefined : "Must be positive",
+  },
+}
 ```
 
 `normalizeFieldValidate(validate)` is exported for consumers building their own
@@ -209,12 +229,46 @@ const grid = useTMDataGrid({
 ```
 
 Issues with a path land on the matching column's cell; pathless issues land on
-the row. A nested schema's issues follow the same rule, so a `address.city`
-issue lands on the column whose `editField` is `"address.city"`.
+the row, where the message shows in the edit lane's tooltip on the open
+row's ✓. A nested schema's issues follow the
+same rule, so a `address.city` issue lands on the column whose `editField` is
+`"address.city"`.
 
 Cross-field rules need a mode that commits the whole row at once. Under `"cell"`
 each cell commits alone, so the rule is evaluated against the other column's
-unedited value and cannot pass. Use `"row"` or `"draft"`.
+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 }`:
+`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
+rows removed. `rows` is unfiltered and never contains group rows.
+
+```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, `{ form, fields }` lands pathed issues on the committing
+row's cells. `onSubmit` runs first, and its failure stands without
+`onSubmitAsync` running. Errors land on the committing row only.
+
+The rules run at every commit - typed, ✓, `edit.setCellValue`, an entry
+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 resolves `false`.
 
 ## Server-side errors
 
@@ -234,9 +288,9 @@ rowValidators: {
 },
 ```
 
-A commit blocked by validation keeps the editor open with the message on the
-input. A rejected `editing.onCommit` keeps the draft too, with the error on the
-row.
+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.
 
 ## Where the state shows
 
@@ -245,9 +299,13 @@ row.
 | The cell's own value | A held draft is displayed: the cell renders the draft value through the column's `cell` renderer, in every mode |
 | Blue cell corner | The field is dirty against its original value |
 | Red cell corner | The field carries a validation error |
-| Row error text | A pathless rule failed, or a commit was rejected |
+| Field error message | In a tooltip on the open editor, shown while the input has focus and on hover |
+| Row error text | A pathless rule failed, or a commit was rejected. In the lane's tooltip, on the open row's ✓ |
 | `data-dirty` on the row | The row holds a dirty draft |
 
 The same information is readable from `edit.store`: `rows[rowId].dirtyFields`,
-`rows[rowId].errorFields`, `rows[rowId].hasRowError`,
-`rows[rowId].isSubmitting`, and `rows[rowId].values` for the draft itself.
+`rows[rowId].errorFields`, `rows[rowId].errorMessages` (`{ field, message }`
+pairs), `rows[rowId].hasRowError`, `rows[rowId].isSubmitting`, and
+`rows[rowId].values` for the draft itself. The pathless message's text is not
+in the store; read it from `edit.getForm(rowId)?.state.errors` on the open
+row that carries it.