@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/skills/editing/SKILL.md

@@ -18,13 +18,16 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/editing.md'
-  - 'Jielga/TMDataGrid:src/docs/query-builder.md'
-  - 'Jielga/TMDataGrid:src/docs/editors.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/editEngine.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editing.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/draft-store.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/adding-rows.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/query-builder.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/editors.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/portfolio-rebalancer.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/editEngine.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
 ---
 
 # TMDataGrid - Editing
@@ -34,9 +37,10 @@ happen. Three facts decide every wiring question below:
 
 - **The grid never mutates `data`.** `editing.onCommit` applies the change
   wherever the data lives, and the updated rows arrive back through `data`.
-- **One row, one form.** Each editing row gets its own TanStack Form, keyed by
-  row id and living outside the DOM, so a draft survives scrolling, sorting and
-  filtering.
+- **One row, one form, while it is open.** Each row being edited gets its own
+  TanStack Form, keyed by row id and living outside the DOM, so a draft
+  survives scrolling, sorting and filtering. A committed row holds values, not
+  a form.
 - **`getRowId` is required** once `editing` is set, and it must be the record's
   own identity. Drafts are keyed by it.
 
@@ -85,13 +89,15 @@ They are independent, and every pair is legal.
 | `"cellConfirm"` | ✓ or Enter; Tab walks input, ✓, ✕ and then leaves, keeping the draft | ✕ or Escape | ✓ / ✕ beside the input |
 | `"row"` | Save in the edit lane, or Enter | Cancel, or Escape | generated edit lane |
 
+Leaving a cell commits it only once the value passes: a refused commit keeps the editor open, invalid, with the message in its tooltip, until the value is fixed or Escape drops it.
+
 | `editing.draft` | Where a commit goes |
 | --- | --- |
 | `false` (default) | Straight out: `onCommit`, `onRowAdd`, `onRowDelete` |
 | `true` | Into the grid's draft store, until `edit.saveDrafts()` sends the lot |
 
 Which to pick: `"cell"` for spreadsheet feel; `"cellConfirm"` when a stray click must not fire a request; `"row"` when the row is the unit of the save or a rule spans two columns.
-Add `draft: true` for many edits sent as one transaction - `{ mode: "row", draft: true }` parks a whole row from the lane's ✓, `{ mode: "cell", draft: true }` parks a row as the caret leaves it.
+Add `draft: true` for many edits sent as one transaction - `{ mode: "row", draft: true }` commits a whole row from the lane's ✓, `{ mode: "cell", draft: true }` commits a row as the caret leaves it.
 
 An editor opens on double-click, or with the cell cursor on the cell: Enter, F2,
 or typing, where the first character replaces the value. Delete or Backspace
@@ -108,11 +114,11 @@ commit. Rows accumulate: opening a second row leaves the first open, and each
 row's ✓ and ✕ act on that row alone.
 
 Under `draft: true` nothing reaches a callback until `saveDrafts`.
-The mode's own commit gesture parks the row instead of sending it, Escape drops that one draft, and parked rows accumulate.
-`edit.commit(rowId)` parks too, so there is no per-row escape hatch to the consumer.
-A parked row is displayed: the cell renders the draft value through the column's own `cell` renderer, with the blue corner marking it dirty and `data-dirty` on the row.
+The mode's own commit gesture puts the row in the draft store instead of sending it, Escape drops that one draft, and committed rows accumulate.
+`edit.commit(rowId)` goes to the draft store too, so there is no per-row escape hatch to the consumer.
+A committed row is displayed: the cell renders the draft value through the column's own `cell` renderer, with the blue corner marking it dirty and `data-dirty` on the row.
 It is a row like any other to the table: sorting, filtering, quick search, grouping, aggregates, export, selection, the row counts, `edit.getRows()` and `editing.tableValidators` all read its draft values, and the row callbacks receive it with the draft as `row.original`.
-A parked row that stops matching a filter leaves the view, and the Save bar still counts it.
+A committed row that stops matching a filter leaves the view, and the Save bar still counts it.
 `data` itself is never modified, and only top-level rows are overlaid - `getSubRows` children keep their `data` values.
 An entry row is row-shaped in every mode - every editable cell open at once, the browser's Tab, and the lane's ✓ to enter it.
 
@@ -131,10 +137,22 @@ a list of row ids. Rows failing validation stay open either way.
 
 `onSaveDrafts` decides how much of the store is cleared: returning nothing
 saves everything, throwing saves nothing, and returning
-`{ updated, created, deleted }` saves everything except the ids reported
-`false`. Each key takes `false` for the whole bucket or a map of id to result;
-an unnamed id saved. A kept row stays committed, so the next `saveDrafts()`
-retries it, and `saveDrafts()` resolves `false` when anything was kept.
+`{ updated, created, deleted }` (a `TMDataGridSaveDraftsResponse`) saves
+everything except the ids reported `false`. Each key takes `false` for the
+whole bucket or a map of id to result; an unnamed id saved. A kept row stays
+committed, so the next `saveDrafts()` retries it.
+
+`saveDrafts()` resolves a `TMDataGridSaveDraftsResult`, `{ ok, saved, kept, reopened }`.
+Every id the save took from the draft store is in exactly one list - row ids for edits and deletions, temp ids for new rows, all kinds mixed:
+
+- `saved` - left the draft store; the consumer accepted it
+- `kept` - still in the draft store, still committed, retried by the next save: an id `onSaveDrafts` returned as failed, every id it was sent when it threw, or, without `onSaveDrafts`, a deletion whose `onRowDelete` threw
+- `reopened` - open again with an error: a table rule rejected it, or on the per-row path its `onCommit` / `onRowAdd` threw
+- `ok` - `true` when `kept` and `reopened` are both empty
+
+On the per-row path a deletion always leaves the store and is reported in `saved`.
+An empty store resolves `{ ok: true, saved: [], kept: [], reopened: [] }`.
+Rows still open are in no list.
 
 Rows carry `data-dirty` (values typed in), `data-draft` (committed, waiting for
 Save), `data-deleted` and `data-new` - a committed new row in the body, or an
@@ -216,7 +234,11 @@ rowValidators: {
 ```
 
 Pathed issues land on the matching cells, pathless ones on the row, and cell
-corners mark both: blue for a dirty draft, red for a validation error.
+corners mark both: blue for a dirty draft, red for a validation error. A
+field's message shows in a tooltip on the open editor, which the host renders
+for a custom editor as much as a built-in one; the plain-function form of a
+validator types `value` as `never`, so annotate the parameter -
+`({ value }: { value: unknown })`.
 
 `editing.tableValidators` carries the rules that need the other rows - no
 duplicate keys, no overlapping ranges, shares summing to a total. Its
@@ -225,8 +247,9 @@ duplicate keys, no overlapping ranges, shares summing to a total. Its
 overlaid, committed new rows among them, the entry rows the table does not hold
 appended, deletion-marked rows removed. Each row appears once. Same result
 vocabulary as `rowValidators`; errors land on the committing row. The rules
-re-run per parked row during `saveDrafts`, so a draft a later edit
-invalidated blocks the save.
+re-run per committed row during `saveDrafts`, the only validation that runs
+there: a committed row a later edit invalidated is reopened with its errors
+and the save reports it in `reopened`.
 
 ```tsx
 tableValidators: {
@@ -237,6 +260,11 @@ tableValidators: {
 }
 ```
 
+Columns derived from the other rows (a weight as a share of the total) plus a
+table-wide rule (targets may not total more than 100%) are worked through in
+[references/editors-and-validation.md](references/editors-and-validation.md),
+from `packages/tmdatagrid/docs/portfolio-rebalancer.md`.
+
 `meta.edit.mapValue` rewrites a value instead of rejecting it: uppercase a code,
 strip spaces from an IBAN, clamp a number. It runs on every write an editor
 makes, so a text input maps per keystroke, and what it returns is what the
@@ -255,8 +283,8 @@ from `editing.newRowDefaults`. `edit.addRow(values)` overrides that seed key by
 key, so `addRow()` opens the `newRowDefaults` row and `addRow(values)` opens it
 with those fields filled in - pass a whole row to duplicate it. Enter, or the
 lane's ✓, commits the add through `editing.onRowAdd`; under `draft: true` it
-parks the row in the draft store, validated, and
-`saveDrafts` reports it in `added`. Escape, or ✕, discards the entry. An entry
+commits the row into the draft store, validated, and
+`saveDrafts` reports it in `created`. Escape, or ✕, discards the entry. An entry
 row never OK'd is not part of a save - it stays open.
 
 Under `draft: true` a committed entry row leaves the entry block and becomes a
@@ -297,13 +325,14 @@ const grid = useTMDataGrid({
 `edit.addRows(rows, options?)` opens a batch in one write. `{ commit: true }`
 submits each row as it lands - the import case: valid rows are committed,
 invalid ones stay open in the entry block with their errors, and the result
-(`{ committed, open }`) says which went which way. Column rules are enforced
-even though the rows never had an editor on screen, because the engine runs
-`meta.edit.validate` itself at commit.
+(`{ ok, committed, open }`) says which went which way; `ok` is `true` when
+`open` is empty. Column rules are enforced even though the rows never had an
+editor on screen, because the engine runs `meta.edit.validate` itself at
+commit.
 
 ```tsx
-const { committed, open } = await grid.edit.addRows(parsed, { commit: true });
-if (open.length > 0) notify(`${open.length} rows need attention`);
+const { ok, open } = await grid.edit.addRows(parsed, { commit: true });
+if (!ok) notify(`${open.length} rows need attention`);
 await grid.edit.saveDrafts();
 ```
 
@@ -318,8 +347,8 @@ it toggles a mark instead: the row renders struck through and inert
 
 The generated edit lane (`EDIT_COLUMN_ID`, pinned right) appears when `editing.mode` is `"row"`, when `editing.draft` is on, or when `editing.onRowDelete` is set.
 Nothing else adds it.
-It holds one thing per axis: the mode's own controls while a row is open - Save and Cancel under `"row"` - and, once a row is parked, the row-state marker with Revert or Restore.
-A parked row never offers a save.
+It holds one thing per axis: the mode's own controls while a row is open - Save and Cancel under `"row"` - and, once a row is committed, the row-state marker with Revert or Restore.
+A committed row never offers a save.
 The trash shows when the deletion has somewhere to report to: `onRowDelete` is set, or under `draft: true`, `onSaveDrafts` is.
 If validation blocks a row, its marker - or the open row's ✓ - turns red with the message in the tooltip, which is where a pathless `rowValidators` message shows.
 Every control carries a tooltip from the labels.
@@ -353,10 +382,10 @@ while editing is off, and works under any mode, not only draft.
 ```
 
 `state` is
-`{ draftCount, openCount, openRowIds, pendingCount, isSubmitting }` -
-`pendingCount` deprecated, reading as `draftCount + openCount`. `actions` is
+`{ draftCount, openCount, openRowIds, isSubmitting, isSaving }`. `actions` is
 `{ save, commitAll, discard, scrollToRow, scrollToFirstOpenRow }`, and
 `Controls` is `{ Save, Discard, OpenRowsNote }`.
+`actions.save` and `actions.commitAll` resolve what `edit.saveDrafts()` and `edit.commitAll()` resolve.
 
 The grid is always virtualized, so an open row far down the list has no element
 to scroll to. `actions.scrollToFirstOpenRow(align?)` moves the virtualizer to
@@ -376,16 +405,20 @@ row it reaches.
 `setCellValue` / `setRowValues` / `clearCell`, `addRow` / `addRows` /
 `deleteRow`, `getForm`, and `store` for `useSelector` (an example is under
 [Submitting an outer form](#high-submitting-an-outer-form-while-the-grid-holds-a-draft)).
-`edit.store` publishes each open or parked row's drafted values as
-`rows[rowId].values`, which is what a computed cell or a cross-row check reads
-- `useTMDataGridContext()` reaches the engine from inside a cell renderer.
+`commitAll()` resolves a `TMDataGridCommitAllResult`, `{ ok, committed, open }`: every row open at the call is in exactly one list, and `ok` is `true` when `open` is empty.
+`commit(rowId)` alone resolves a plain boolean.
+`edit.store` publishes each open or committed row's drafted values as
+`rows[rowId].values`, which is what a cross-row check reads. A `cell`
+renderer needs no lookup: its `row.original` is already the row as shown, and
+`getRowValues(rowId)` is the same row for a handler with no cell context.
 Every member with its signature, the gates, `isColumnEditable`, `deactivate`,
 and the `edit.store` shape are in
 [references/editing-api.md](references/editing-api.md#the-edit-engine).
 
-`getForm` exposes the row's form: render it in a drawer and it shares values,
-dirty state and errors with the inline cells, because it is the same
-`FormApi`.
+`getForm` exposes an open row's form: render it in a drawer and it shares
+values, dirty state and errors with the inline cells, because it is the same
+`FormApi`. It is `undefined` for a committed row, which holds values and no
+form; `begin` reopens the row with a form seeded from them.
 
 `edit.setCellValue(rowId, columnId, value)` writes one cell and commits its row with no editor open, which is what a toolbar action or a bulk fill wants.
 The row need not be mounted, so a selected row inside a collapsed group takes the write like any other.
@@ -397,7 +430,7 @@ for (const row of grid.table.getSelectedRowModel().rows) {
 }
 ```
 
-Under `draft: true` each row parks in the draft store like any hand-made edit, with the same change markers and the same per-row revert, and the basket leaves through `saveDrafts`.
+Under `draft: true` each row is committed into the draft store like any hand-made edit, with the same change markers and the same per-row revert, and the basket leaves through `saveDrafts`.
 `value` is the stored value: no editor runs, so `meta.edit.mapValue` does not run either, while `meta.edit.validate` does.
 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.
 
@@ -428,7 +461,6 @@ are in [references/common-mistakes.md](references/common-mistakes.md).
 | CRITICAL | Expecting the grid to write into `data` - without `editing.onCommit` the cell reverts |
 | CRITICAL | `getRowId` built from the row index - drafts follow the index, not the record |
 | HIGH | A cell editor defined inside the component - a new type per render unmounts the editor |
-| HIGH | A custom editor that binds no error text - a refused commit shows no message; bind `field.state.meta.errors` |
 | HIGH | A cross-field rule under `mode: "cell"` - `rowValidators` needs `"row"` |
 | HIGH | An `accessorFn` column with no `meta.edit.field` - it maps to nothing and stays read-only |
 | HIGH | Swallowing the error in `editing.onCommit` - a resolved catch drops the draft |
@@ -437,12 +469,14 @@ are in [references/common-mistakes.md](references/common-mistakes.md).
 | MEDIUM | A computed column frozen while a row is edited - `accessorFn` reads `data`; read the draft from `edit.store`'s `rows[rowId].values` |
 | MEDIUM | Reading a commit's result as the saved value - it is a `boolean` about the form |
 | MEDIUM | Expecting `editing.onRowDelete` to fire under draft - the mark waits for `saveDrafts` |
+| MEDIUM | A custom editor that binds no invalid state - the host shows the message in a tooltip, but the control keeps its normal border; bind a boolean to `error` |
 
 ## References
 
 - [Editors and validation](references/editors-and-validation.md) - the editor
-  API, wrapping a built-in, what `mapValue` leaves alone, field and row
-  validators, server-side errors.
+  API, wrapping a built-in, what `mapValue` leaves alone, field, row and
+  cross-row validators, derived columns with a table-wide rule, server-side
+  errors.
 - [Editing API](references/editing-api.md) - every option, callback, column meta
   field, export, CSS variable and data attribute belonging to editing.
 - [Common mistakes](references/common-mistakes.md) - the failure modes above,

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,7 +9,7 @@ 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. |
@@ -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. Each of its buckets is a `TMDataGridSaveOutcomes`: `boolean \| Record<string, boolean>`, where `false` keeps an entry's draft and an id the map does not name counts as saved. 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?: TMDataGridAddRowsOptions) => 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,8 +96,8 @@ 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
@@ -108,6 +108,8 @@ type TMDataGridEditState = {
   // 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;
 };
 ```
 
@@ -119,16 +121,19 @@ 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`,
-`TMDataGridRowDeleteArgs`, `TMDataGridEditingOptions`.
+`TMDataGridRowDeleteArgs`, `TMDataGridEditingOptions`,
+`TMDataGridSaveOutcomes`, `TMDataGridAddRowsOptions`,
+`TMDataGridEditValueMapArgs`, `TMDataGridTableValidateArgs`.
 
 ## The edit lane
 
@@ -148,11 +153,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.