@jielga/tmdatagrid 2.0.0-beta.8 → 2.0.0

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,45 +71,7 @@ const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
 meta: { edit: { editor: SalaryEditor } },
 ```
 
-Source: `src/docs/editors.md`, `src/tmdatagrid/core/editEngine.ts`.
-
-## HIGH A custom editor that binds no error text
-
-The built-in editors bind the field's first error to the input's `error` prop.
-A custom editor that binds nothing still blocks the commit, but all the user
-sees is `data-invalid` on the cell - the row stays open with no message
-anywhere on screen, which reads as a broken grid rather than a rejected value.
-
-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 error = field.state.meta.errors
-    .map((e) => (typeof e === "string" ? e : e?.message))
-    .find(Boolean);
-  return (
-    <Slider
-      value={field.state.value}
-      onChange={field.handleChange}
-      onChangeEnd={() => void commit()}
-      error={error}
-    />
-  );
-};
-```
-
-An entry of `field.state.meta.errors` is a string from a function validator,
-or an issue carrying a `message` from a schema.
-
-Source: `src/docs/editors.md` (Writing your own).
+Source: `packages/tmdatagrid/docs/editors.md`, `packages/tmdatagrid/src/core/editEngine.ts`.
 
 ## HIGH A cross-field rule under `editing.mode: "cell"`
 
@@ -120,7 +82,7 @@ other column's old value, and the row cannot be saved.
 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
 
@@ -147,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`
 
@@ -170,7 +132,7 @@ onCommit: async ({ rowId, value }) => {
 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
 
@@ -186,12 +148,14 @@ const hasOpenDraft = useSelector(grid.edit.store, (s) => s.openRowIds.length > 0
 
 <Button type="submit" disabled={!canSubmit || hasOpenDraft}>Save</Button>
 // or commit and flush instead of blocking:
-await grid.edit.commitAll();
-const flushed = await grid.edit.saveDrafts();
-if (flushed) await form.handleSubmit();
+const committed = await grid.edit.commitAll();
+const flushed = committed.ok ? await grid.edit.saveDrafts() : undefined;
+if (flushed?.ok) await form.handleSubmit();
 ```
 
-Source: `src/docs/query-builder.md` (Which mode, Submitting).
+Both results are objects, so test `.ok`: `if (await grid.edit.saveDrafts())` is always true.
+
+Source: `packages/tmdatagrid/docs/query-builder.md` (Which mode, Submitting).
 
 ## HIGH A bulk write built from `begin`, `getForm` and `commit`
 
@@ -223,40 +187,51 @@ 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: `src/tmdatagrid/core/editEngine.ts` (`begin`, `writeFields`).
+Source: `packages/tmdatagrid/src/core/editEngine.ts` (`begin`, `writeFields`).
 
-## MEDIUM A computed column frozen while a row is edited
+## MEDIUM Reading an open row's values off `row.original` outside a cell
 
-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.
+Inside a `cell` renderer, `row.original` and `getValue()` are the row as
+shown: the open form's values while the row is edited, the committed draft
+after ✓, and `data` otherwise - a computed column follows the draft as it is
+typed, and a button in a cell sends the draft the user sees. Outside it, the
+row callbacks (`onRowClick`, `renderRowContextMenu`, `rowClassName`) and any
+code holding a row id see `data`, or the committed draft, and never an open
+form's values.
 
-Correct: read the drafted row from `edit.store` inside the cell renderer:
+Correct: reach the row as shown by id:
 
 ```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;
-}
+const shown = grid.edit.getRowValues(row.id) ?? row.original;
 ```
 
-Source: `src/docs/editing.md` (Draft lifetime).
+Source: `packages/tmdatagrid/docs/editing.md` (How a draft renders).
 
 ## MEDIUM Reading a commit's result as the saved value
 
-`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.
+`edit.commit(rowId)` resolves a `boolean`: `false` when validation or a rejected commit kept the row open.
+`edit.commitAll()` resolves `{ ok, committed, open }`, and `edit.saveDrafts()` resolves `{ ok, saved, kept, reopened }`.
+Each id is in exactly one list, and `ok` is `false` when any row stayed open, was kept in the draft store, or was reopened with an error.
+Ignoring the result reports a save that did not happen, and testing the object itself is always true.
+
+Wrong:
 
 ```tsx
-const saved = await grid.edit.saveDrafts();
-notifications.show({ message: saved ? "Saved" : "Some rows need attention" });
+if (await grid.edit.saveDrafts()) notifications.show({ message: "Saved" });
 ```
 
-Source: `src/tmdatagrid/core/editEngine.ts` (`TMDataGridEditApi`).
+Correct:
+
+```tsx
+const { ok, kept, reopened } = await grid.edit.saveDrafts();
+notifications.show({
+  message: ok
+    ? "Saved"
+    : `${kept.length} rows not saved, ${reopened.length} rows need attention`,
+});
+```
+
+Source: `packages/tmdatagrid/src/core/editEngine.ts` (`TMDataGridEditApi`).
 
 ## MEDIUM Expecting `editing.onRowDelete` to fire under a draft store
 
@@ -266,4 +241,37 @@ Under `draft: true` it only toggles a deletion mark, so nothing is removed until
 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/adding-rows.md`.
+
+## 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

@@ -9,14 +9,14 @@ kind.
 | --- | --- | --- | --- |
 | `editing` | `TMDataGridEditingOptions` | off | The editing namespace. Setting it turns editing on. |
 | `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 parks in the grid's draft store until `edit.saveDrafts()`. |
+| `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: true` only. Keeps entered new rows pinned in the entry block until the save, 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
@@ -28,8 +28,7 @@ the type.
 | Name | Argument | What it does |
 | --- | --- | --- |
 | `editing.onCommit` | `{ rowId, value, original, changes, source }` | Applies one row's change. Reject to keep the draft and show the error. |
-| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. 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.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. May return a `TMDataGridSaveDraftsResponse` naming the ids that failed; they stay in the draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
 | `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
 | `editing.onRowDelete` | `{ rowId, row }` | Deletes a row. Shows the trash; under `draft: true`, `onSaveDrafts` shows it too. |
 
@@ -54,24 +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 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 parks the row - 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. Open rows are left alone and stay open. |
+| `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<TMDataGridCommitAllResult>` | Submits every open row. Rows that fail stay open. Resolves `{ ok, committed, open }`: every row open at the call is in exactly one list, and `ok` is `false` when one stayed open. |
+| `saveDrafts` | `() => Promise<TMDataGridSaveDraftsResult>` | 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. Resolves `{ ok, saved, kept, reopened }` over row ids and temp ids, all kinds mixed: `saved` left the draft store, `kept` is still in it for the next save (reported failed by `onSaveDrafts`, sent when it threw, or a deletion whose per-row `onRowDelete` threw), `reopened` is open again with an error (a table rule, or a throwing per-row `onCommit` / `onRowAdd`). `ok` is `false` when anything was kept or reopened. A call during a save joins it and resolves the same result. |
 | `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>` | **Deprecated** - `commitAll()` then `saveDrafts()`. |
 | `clearCell` | `(rowId, columnId) => Promise<boolean>` | What Delete does: writes the type's empty value and commits. |
-| `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 parks 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. |
+| `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. |
+| `addRows` | `(rows, options?) => Promise<TMDataGridAddRowsResult>` | Opens a batch in one write, each row seeded as `addRow` seeds. `{ commit: true }` submits each as it lands - valid rows commit, invalid ones stay open with their errors. Resolves `{ ok, committed, open }`; `ok` is `false` when a row stayed open. |
+| `deleteRow` | `(rowId) => void` | `editing.onRowDelete`, or a deletion mark under `draft: true`. Idempotent: a second call leaves the row marked; `restoreRow` is the undo. |
 | `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. Both halves: the column's and the row's. |
 | `canEditRow` | `(row) => boolean` | The pencil's gate. |
 | `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. |
+| `getRowValues` | `(rowId) => TData \| undefined` | The row as shown: the open form's values, else the committed draft, else the `data` value. `undefined` for an unknown row. |
+| `getRows` | `() => ReadonlyArray<TMDataGridEditRowSnapshot>` | Every row as shown, from the core row model: drafts overlaid, entry rows appended, deletion-marked rows included and flagged `deleted`. |
 | `state` | `TMDataGridEditState` | Snapshot, for reads outside React. |
 | `store` | `Store<TMDataGridEditState>` | For `useSelector`. |
 
@@ -81,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, committed or not. A row is *open* when it is in
-  // here and not in `committedRowIds`.
+  // 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,
     {
@@ -96,13 +96,20 @@ type TMDataGridEditState = {
       values: TMDataGridRowData;
     }
   >;
-  // The draft store's edit slice: existing rows whose form passed its submit,
-  // parked for `saveDrafts`. Empty without `editing.draft`.
+  // 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;
 };
 ```
 
@@ -114,12 +121,13 @@ type TMDataGridEditState = {
 | `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. |
+| `hasPendingEdits` | Export | `(state) => boolean` - unsaved work: an open row with a changed value, any entry row, the draft store, or a save in flight. `useSelector(grid.edit.store, hasPendingEdits)` for a navigation blocker; do not use `openRowIds.length`, which also counts committed rows and rows that are only open. |
 | `getEditFieldName` | Export | `(column) => string` - the data path a column's edits write to. |
 | `normalizeFieldValidate` | Export | `(validate) => validators` - a bare schema into Form's shape. |
 | `TMDataGridStringEditor` … `TMDataGridMultiSelectEditor` | Exports | The six built-in editors, for wrapping. |
 
 Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
-`TMDataGridEditCommitArgs`, `TMDataGridEditCommitDraftsArgs`,
+`TMDataGridEditCommitArgs`, `TMDataGridSaveDraftsArgs`,
 `TMDataGridEditChange`, `TMDataGridEditorArgs`, `TMDataGridEditorComponent`,
 `TMDataGridEditField`, `TMDataGridEditRowProjection`, `TMDataGridFieldValidate`,
 `TMDataGridRowValidators`, `TMDataGridRowEditForm`, `TMDataGridRowAddArgs`,
@@ -143,11 +151,11 @@ The trash itself shows when the deletion has somewhere to report to:
 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 parked 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 park again. A parked row hides `delete-row`.
+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.
 
@@ -156,11 +164,11 @@ Every 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. |
+| `--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-committed` | Entry row attributes | On an entry row; `data-committed` once it is committed, awaiting the save. |
-| `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`. |
 | `data-dg-part="row-state"` | Part | The draft store's change marker, with `data-row-id` and `data-state` of `new`, `edited` or `deleted`. |

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

@@ -63,11 +63,11 @@ Bind any control to `field` exactly as inside any TanStack Form:
 `field.state.value`, `field.state.meta.errors`, `field.handleChange`,
 `field.handleBlur`.
 
-Binding `field.state.meta.errors` is what shows a refused commit: the built-in
-editors pass the first error to the input's `error` prop, and an editor that
-binds nothing leaves a blocked save as `data-invalid` on the cell with no
-message on screen. An entry is a string from a function validator, or an issue
-carrying a `message` from a schema.
+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";
@@ -193,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
@@ -224,8 +229,8 @@ const grid = useTMDataGrid({
 ```
 
 Issues with a path land on the matching column's cell; pathless issues land on
-the row, where the message shows in the edit lane's tooltip - on the open
-row's ✓, and on the parked row's marker. A nested schema's issues follow the
+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"`.
 
@@ -261,9 +266,9 @@ 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 parked row during
-`saveDrafts`: a draft that a later edit invalidated fails there, keeps its
-markers, and the save resolves `false`.
+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`.
 
 ## Server-side errors
 
@@ -283,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
 
@@ -294,11 +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. In the lane's tooltip: the open row's ✓, or the parked row's marker |
+| 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].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`.
+in the store; read it from `edit.getForm(rowId)?.state.errors` on the open
+row that carries it.