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

package/skills/editing/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: editing
 description: >
-  Edit cells and rows in TMDataGrid. Covers editMode with its four policies
-  (cell, cellConfirm, row, batch), the required getRowId, onEditCommit and
-  onEditCommitBatch, why the grid never mutates data, per-column gating with
-  meta.edit.enabled and meta.edit.field, the six built-in editors picked by
-  meta.type, custom editors through meta.edit.editor, per-keystroke value
-  mapping with meta.edit.mapValue, field validation with meta.edit.validate and
-  cross-field rules with rowValidators (Standard Schema and Zod), adding and
-  deleting rows with edit.addRow, newRowDefaults, onRowAdd and onRowDelete, the
+  Edit cells and rows in TMDataGrid. Covers the editing option with its four
+  mode policies (cell, cellConfirm, row, draft), the required getRowId,
+  editing.onCommit and editing.onCommitDrafts, why the grid never mutates data,
+  per-column gating with meta.edit.enabled and meta.edit.field, the six built-in
+  editors picked by meta.type, custom editors through meta.edit.editor,
+  per-keystroke value mapping with meta.edit.mapValue, field validation with
+  meta.edit.validate and cross-field rules with editing.rowValidators (Standard
+  Schema and Zod), adding and deleting rows with edit.addRow,
+  editing.newRowDefaults, editing.onRowAdd and editing.onRowDelete, the
   generated edit lane, TMDataGrid.EditActions with its renderActions slot, and
   the public edit engine (begin, commit, cancel, submitAll, getForm, store).
   Load when making a grid editable, choosing an edit mode, wiring a save,
@@ -16,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.0'
+  library_version: '2.0.0-beta.2'
 sources:
   - 'Jielga/TMDataGrid:src/docs/editing.md'
   - 'Jielga/TMDataGrid:src/docs/query-builder.md'
@@ -27,15 +28,15 @@ sources:
 
 # TMDataGrid - Editing
 
-`editMode` turns editing on and picks how commits happen. Three facts decide
-every wiring question below:
+The `editing` option turns editing on, and `editing.mode` picks how commits
+happen. Three facts decide every wiring question below:
 
-- **The grid never mutates `data`.** `onEditCommit` applies the change wherever
-  the data actually lives, and the new rows arrive back through `data`.
+- **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.
-- **`getRowId` is required** once `editMode` is set, and it must be the record's
+- **`getRowId` is required** once `editing` is set, and it must be the record's
   own identity. Drafts are keyed by it.
 
 `@tanstack/react-form` becomes a peer dependency once editing is used.
@@ -49,15 +50,17 @@ const grid = useTMDataGrid({
   data: employees,
   columns,
   getRowId: (row) => String(row.id),
-  editMode: "cell",
-  // The grid writes nothing: apply the change, and the edited row arrives
-  // back through `data`.
-  onEditCommit: ({ rowId, value }) =>
-    setEmployees((previous) =>
-      previous.map((employee) =>
-        String(employee.id) === rowId ? value : employee,
+  editing: {
+    mode: "cell",
+    // The grid writes nothing: apply the change, and the edited row arrives
+    // back through `data`.
+    onCommit: ({ rowId, value }) =>
+      setEmployees((previous) =>
+        previous.map((employee) =>
+          String(employee.id) === rowId ? value : employee,
+        ),
       ),
-    ),
+  },
 });
 
 <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
@@ -65,59 +68,73 @@ const grid = useTMDataGrid({
 </TMDataGrid>;
 ```
 
-The editing options travel together, and the types say so: passing any of them
-without `editMode` is a compile error, `getRowId` stops being optional the
-moment `editMode` is set, and `onEditCommitBatch` exists only under
-`editMode: "batch"`.
+Two rules are compile errors, not options that silently do nothing: `editing`
+requires `getRowId`, and `editing.onCommitDrafts` exists only under
+`editing.mode: "draft"`. Draft _without_ `onCommitDrafts` is fine: `submitAll`
+falls back to the per-row `editing.onCommit` loop.
 
 ## The four modes
 
-One axis, four policies over the same engine.
+All four use the same engine and the same forms. `editing.mode` sets what counts
+as a commit, and which controls trigger it.
 
-| Mode | Commits on | Cancels on | Chrome |
+| Mode | Commits on | Cancels on | Controls |
 | --- | --- | --- | --- |
 | `"cell"` | Enter, Tab, blur | Escape | none |
 | `"cellConfirm"` | ✓ or Enter; blur keeps the draft | ✕ or Escape | ✓ / ✕ beside the input |
 | `"row"` | Save in the edit lane, or Ctrl+Enter | Cancel, or Escape | generated edit lane |
-| `"batch"` | `edit.submitAll()` | `edit.cancelAll()` | `TMDataGrid.EditActions` |
+| `"draft"` | `edit.submitAll()` | `edit.cancelAll()`, or per row in the lane | `TMDataGrid.EditActions` + the edit lane |
 
 Which to pick: `"cell"` for saved-as-you-go 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; `"batch"` for many edits sent as one
+the save or a rule spans two columns; `"draft"` for many edits sent as one
 transaction.
 
 An editor opens on double-click, or with the cell cursor on the cell: Enter, F2,
-or just typing, where the character replaces the value. Delete or Backspace
-clears the value and commits without opening an editor. Editing brings cell
-selection with it: `cellSelection` defaults to `"single"` while `editMode` is
-set. Every open gesture puts the caret in the cell it named, and `edit.addRow()`
-in the new row's first editable cell. The grid places it rather than the editor,
-so a `meta.edit.editor` gets it without doing anything to earn it.
-
-Under `"row"` the pencil - or a double-click on any cell, which puts the caret
-in the cell clicked - opens every editable cell of the row, and ✓ saves them as
-one commit. Rows accumulate: opening a second row leaves the first open, and
-each row's ✓ and ✕ act on that row alone, so no row is closed or saved to make
-space for the next.
-
-Under `"batch"` nothing leaves the grid until `submitAll`. Enter and Tab park
-the draft, dirty-marked, Escape drops that one draft, and drafts accumulate
-across rows. `submitAll` then commits every open row: through the per-row
-`onEditCommit` loop by default, or through one
-`onEditCommitBatch({ rows, added, deleted })` call when that is set. Rows
-failing validation stay open either way, and a rejected batch keeps every
-draft.
+or typing, where the first character replaces the value. Delete or Backspace
+clears the value and commits without opening an editor; under `"draft"` the
+cleared value is held with the other drafts instead. Editing implies cell
+selection: `cellSelection` defaults to `"single"` while `editing` is set. The
+grid places the caret in the cell that was opened, and `edit.addRow()` places it
+in the new row's first editable cell, so a `meta.edit.editor` receives focus
+without handling it itself.
+
+Under `"row"` the pencil, or a double-click on any cell, which puts the caret in
+the cell clicked, opens every editable cell of the row, and ✓ saves them as one
+commit. Rows accumulate: opening a second row leaves the first open, and each
+row's ✓ and ✕ act on that row alone.
+
+Under `"draft"` nothing reaches a callback until `submitAll`. Enter and Tab hold
+the draft, Tab moving on to the next editable cell, Escape drops that one draft,
+and drafts accumulate across rows, surviving filters, sorts and scrolling.
+`edit.commit(rowId)` validates and holds the draft too, so there is no per-row
+escape hatch to the consumer. A held draft 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 edit lane is the change indicator and the per-row undo: an edited row shows
+a pencil icon and Revert, which drops that row's draft; a new row a plus icon, a
+pencil that reopens it, and ✕; a row marked for deletion a trash icon and
+Restore. A row holding a dirty draft hides the trash - revert first, then
+delete. A row blocked by validation turns its icon red with the message in the
+tooltip.
+
+`submitAll` then commits every pending change: through the per-row
+`editing.onCommit` / `editing.onRowAdd` / `editing.onRowDelete` loop by default,
+or through one `editing.onCommitDrafts({ rows, added, deleted })` call when that
+is set. Rows failing validation stay open either way, and a rejected save keeps
+every draft.
 
 ## What a commit receives
 
-`onEditCommit` is handed `{ rowId, value, original, changes, source }`: `value`
-is the whole edited row for consumers who save records, `changes` the per-field
-diff (`columnId`, `field`, `previous`, `next`) for consumers who PATCH, one
-entry in cell mode.
+`editing.onCommit` is handed `{ rowId, value, original, changes, source }`.
+`value` is the whole edited row, for saving a record; `changes` is the per-field
+diff (`columnId`, `field`, `previous`, `next`), for a PATCH, and holds one entry
+in cell mode.
 
-The engine drops the draft only when `onEditCommit` resolves. A slow save keeps
-the draft on screen with a busy marker; a **rejection keeps the form open** with
-the error on the row, which is how a failed save stays visible.
+The engine drops the draft only when `editing.onCommit` resolves. A slow save
+keeps the draft on screen with a busy marker, and a **rejection keeps the form
+open** with the error on the row.
 
 ## Which cells edit
 
@@ -130,7 +147,7 @@ records, so `accessorKey: "address.city"` edits `values.address.city`.
 | `meta.edit.enabled: false` | The column never edits |
 | `meta.edit.enabled: (row) => boolean` | Per row, per column |
 | `meta.edit.field: "lastName"` | The path an `accessorFn` column writes to |
-| `isRowEditable: (row) => boolean` | The whole row, in every mode |
+| `editing.isRowEditable: (row) => boolean` | The whole row, in every mode |
 
 Group rows and the generated lanes (checkbox, row number, details, edit) never
 edit.
@@ -157,8 +174,8 @@ one, with the export that wraps it, is in
 [references/editors-and-validation.md](references/editors-and-validation.md#the-built-in-editors).
 
 `meta.edit.editor` replaces one, `meta.edit.validate` guards the field, and
-`rowValidators` carries cross-field rules. The validators are TanStack Form's
-own, Standard Schema included, so a Zod schema passes straight through:
+`editing.rowValidators` carries cross-field rules. The validators are TanStack
+Form's own, Standard Schema included, so a Zod schema passes straight through:
 
 ```tsx
 import { z } from "zod";
@@ -166,7 +183,7 @@ import { z } from "zod";
 // Field level, on the column. A bare schema means { onChange: schema }.
 meta: { edit: { validate: z.string().min(2, "At least two characters") } }
 
-// Form level, on the hook. Cross-field rules, under "row" or "batch".
+// Form level, inside `editing`. Cross-field rules, under "row" or "draft".
 rowValidators: {
   onSubmit: z
     .object({ salary: z.number().positive(), status: z.string() })
@@ -179,10 +196,10 @@ 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.
 
-`meta.edit.mapValue` rewrites a value rather than 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 validators judge and what commits.
+`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
+validators check and what is committed.
 
 ```tsx
 meta: { edit: { mapValue: ({ value }) => String(value).toUpperCase() } }
@@ -193,19 +210,30 @@ Detail for all three: [references/editors-and-validation.md](references/editors-
 ## Adding and deleting rows
 
 `edit.addRow()` opens an entry row in a sticky block under the header, seeded
-from `newRowDefaults`. Enter, or the lane's ✓, commits the add through
-`onRowAdd` under the immediate modes; batch parks it for `submitAll`. Escape, or
-✕, discards it.
+from `editing.newRowDefaults`. Enter, or the lane's ✓, commits the add through
+`editing.onRowAdd` under the immediate modes; under draft mode it enters the
+row, which is validated, held with the other drafts, and reported in
+`submitAll`'s `added`. Escape, or ✕, discards the entry.
+
+Under `"draft"` an entered row renders as a value row with no inputs, marked
+`data-new` and `data-confirmed` and tinted with `--dg-row-new-bg`. By default it
+joins the scrolling flow above the body rows; `editing.newRowsSticky: true`
+keeps entered rows pinned in the entry block until Save all. Double-click, or
+the lane's pencil, reopens it; ✕ removes it. To limit how many entry rows are
+open at once, gate the Add button on
+`useSelector(grid.edit.store, (s) => s.newRows.some((n) => !n.confirmed))`.
 
 ```tsx
 const grid = useTMDataGrid({
   data: employees,
   columns,
   getRowId: (row) => String(row.id),
-  editMode: "batch",
-  newRowDefaults: () => ({ id: 0, firstName: "", salary: 30_000 }),
-  onEditCommitBatch: async ({ rows, added, deleted }) => {
-    await api.saveBatch({ rows, added, deleted });
+  editing: {
+    mode: "draft",
+    newRowDefaults: () => ({ id: 0, firstName: "", salary: 30_000 }),
+    onCommitDrafts: async ({ rows, added, deleted }) => {
+      await api.saveBatch({ rows, added, deleted });
+    },
   },
 });
 
@@ -216,25 +244,27 @@ const grid = useTMDataGrid({
 </TMDataGrid.Toolbar>;
 ```
 
-`edit.deleteRow(rowId)` calls `onRowDelete({ rowId, row })` straight away under
-the immediate modes, so a confirmation belongs inside that callback. Under batch
-it toggles a mark instead: the row renders struck through and inert
-(`data-deleted`), the lane's trash becomes a restore, and `submitAll` reports
-the ids in `deleted`. Adds and deletes are applied by you, the same as edits -
-the engine's `tempId` (`__new__1`, …) never needs to become a real id.
+`edit.deleteRow(rowId)` calls `editing.onRowDelete({ rowId, row })` immediately
+under the immediate modes, so put any confirmation inside that callback. Under
+draft mode it toggles a mark instead: the row renders struck through and inert
+(`data-deleted`), the lane shows Restore, and `submitAll` reports the ids in
+`deleted`. You apply adds and deletes, the same as edits. The engine's `tempId`
+(`__new__1`, …) does not need to become a real id.
 
-## The chrome
+## The built-in controls
 
-The generated edit lane (`EDIT_COLUMN_ID`, pinned right) appears when `editMode`
-is `"row"`, or `onRowDelete` is set, or `editMode` is `"batch"` with
-`onEditCommitBatch` set. Nothing else conjures it, and `"cell"` mode has no
-chrome at all by design.
+The generated edit lane (`EDIT_COLUMN_ID`, pinned right) appears when
+`editing.mode` is `"row"` or `"draft"`, or when `editing.onRowDelete` is set.
+Nothing else adds it, and `"cell"` mode renders no controls of its own. Under
+`"row"` it holds Save and Cancel while a row is open; under `"draft"` it holds
+the row-state marker with Revert and Restore, and Save and Cancel never appear.
+Every control carries a tooltip from the labels.
 
 `TMDataGrid.EditActions` is Save with the pending count plus Discard. It greys
 out while nothing is pending, spins while a submit is in flight, renders nothing
-while editing is off, and works under any mode, not only batch.
+while editing is off, and works under any mode, not only draft.
 
-`renderActions` replaces the pair while handing over its pieces:
+`renderActions` replaces the pair and hands over its pieces:
 
 ```tsx
 <TMDataGrid.EditActions
@@ -252,248 +282,59 @@ while editing is off, and works under any mode, not only batch.
 
 ## The engine: `edit`
 
-`grid.edit` is public, and everything the chrome does goes through it:
+`grid.edit` is public, and everything the built-in controls do goes through it:
 `begin` and `commit`, `cancel` / `cancelAll`, `submitAll`, `addRow` /
-`deleteRow`, `getForm`, and `store` for `useSelector`. Every member with its
-signature, the gates, `clearCell`, `deactivate`, and the `edit.store` shape are
-in [references/editing-api.md](references/editing-api.md#the-edit-engine).
-
-```tsx
-import { useSelector } from "@tanstack/react-store";
+`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)).
+Every member with its signature, the gates, `clearCell`, `deactivate`, and the
+`edit.store` shape are in
+[references/editing-api.md](references/editing-api.md#the-edit-engine).
 
-const pendingCount = useSelector(
-  grid.edit.store,
-  (state) => state.openRowIds.length + state.deletedRowIds.length,
-);
-```
-
-`getForm` is the *one row, one form* promise made public: render that same form
-in a drawer and it shares values, dirty state and errors with the inline cells,
-because it is the same `FormApi`.
+`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`.
 
 ## Inside an outer form
 
-A `@tanstack/react-form` form can own the row array, with the grid as a
-controlled field: `data` from `field.state.value`, and `onEditCommit` /
-`onRowAdd` / `onRowDelete` composing the next array into `field.handleChange`.
-Use `editMode: "row"` so a row reaches the form on approval, map by row id
-(never index), and mint negative ids for new rows.
+A `@tanstack/react-form` form can hold the row array, with the grid as a
+controlled field: `data` from `field.state.value`, and `editing.onCommit` /
+`editing.onRowAdd` / `editing.onRowDelete` composing the next array into
+`field.handleChange`. Use `editing.mode: "row"` so a row reaches the form on
+approval, map by row id (never index), and assign negative ids to new rows.
 
-The validation split is structural, not stylistic: **a rule decidable from one
-row belongs to the grid (`meta.edit.validate`, `rowValidators`); a rule needing the
-other rows or the collection ("has rows", "no duplicates") belongs to the
-form's field validator.** A row's form cannot see the array, and `edit.store`
-publishes field names, never values, so the form cannot see a draft.
+The validation split follows from what each side can see: **a rule decidable
+from one row belongs to the grid (`meta.edit.validate`,
+`editing.rowValidators`); a rule needing the other rows or the collection ("has
+rows", "no duplicates") belongs to the form's field validator.** A row's form
+cannot see the array, and `edit.store` publishes field names but not values, so
+the form cannot see a draft.
 
 ## Common mistakes
 
-### CRITICAL Expecting the grid to write into `data`
-
-The grid holds no copy of the rows. Without `onEditCommit` an edit commits, the
-draft clears, and the cell snaps back to the value in `data`, which looks like
-the edit was silently discarded.
-
-Wrong:
-
-```tsx
-useTMDataGrid({ data: employees, columns, getRowId, editMode: "cell" });
-```
-
-Correct:
-
-```tsx
-useTMDataGrid({
-  data: employees,
-  columns,
-  getRowId,
-  editMode: "cell",
-  onEditCommit: ({ rowId, value }) =>
-    setEmployees((previous) =>
-      previous.map((employee) =>
-        String(employee.id) === rowId ? value : employee,
-      ),
-    ),
-});
-```
-
-Source: `src/docs/editing.md`, `src/tmdatagrid/core/editEngine.ts`.
-
-### CRITICAL `getRowId` built from the row index
-
-`getRowId` satisfies the compiler with any string, so an index-based id passes.
-Drafts are keyed by it, so after a sort or a filter the draft is applied to
-whichever record now sits at that index.
-
-Wrong:
-
-```tsx
-getRowId: (row, index) => String(index),
-```
-
-Correct:
-
-```tsx
-getRowId: (row) => String(row.id),
-```
-
-Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
-
-### HIGH A cell editor defined inside the component
-
-`meta.edit.editor` is rendered as JSX, so its identity is its component type. An
-inline arrow is a new type on every render, which unmounts the open editor and
-loses what was being typed.
-
-Wrong:
-
-```tsx
-meta: { edit: { editor: ({ field }) => <Slider value={field.state.value} /> } },
-```
-
-Correct:
-
-```tsx
-// Module scope, referenced by name.
-const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
-  <Slider
-    value={Number(field.state.value ?? 0)}
-    onChange={(next) => field.handleChange(next)}
-    onChangeEnd={() => void commit()}
-  />
-);
-
-meta: { edit: { editor: SalaryEditor } },
-```
-
-Source: `src/docs/editors.md`, `src/tmdatagrid/core/editEngine.ts`.
-
-### HIGH A cross-field rule under `editMode: "cell"`
-
-Under `"cell"` each cell commits on its own, so a rule spanning two columns can
-never be satisfied by either one: the first cell edited is rejected against the
-other column's old value, and the row cannot be saved at all.
-
-Wrong:
-
-```tsx
-useTMDataGrid({ editMode: "cell", rowValidators: { onSubmit: endAfterStart } });
-```
-
-Correct:
-
-```tsx
-// "row" (or "batch") validates the whole row in one commit.
-useTMDataGrid({ editMode: "row", rowValidators: { onSubmit: endAfterStart } });
-```
-
-Source: `src/docs/editors.md` (cross-field rules want a mode that commits the
-whole row at once).
-
-### HIGH An `accessorFn` column that never opens an editor
-
-Editability follows the data path, not the column. A column built on an accessor
-function has no `accessorKey`, so it maps to nothing and stays read-only while
-every other column edits. No warning is raised.
-
-Wrong:
-
-```tsx
-columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
-  id: "fullName",
-  header: "Full name",
-});
-```
-
-Correct:
-
-```tsx
-columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
-  id: "fullName",
-  header: "Full name",
-  meta: { label: "Full name", edit: { field: "lastName" } },
-});
-```
-
-Source: `src/docs/editing.md` (Which cells edit).
-
-### HIGH Swallowing the error in `onEditCommit`
-
-The draft is dropped when `onEditCommit` resolves. A `try/catch` that logs the
-failure resolves it, so a save that failed on the server clears the editor and
-the grid shows the old value as though nothing happened.
-
-Wrong:
+Each one compiles and raises no warning. The reason and the fix for every entry
+are in [references/common-mistakes.md](references/common-mistakes.md).
 
-```tsx
-onEditCommit: async ({ rowId, changes }) => {
-  try {
-    await api.patch(rowId, changes);
-  } catch (error) {
-    console.error(error);
-  }
-},
-```
-
-Correct:
-
-```tsx
-// Reject: the form stays open with the error on the row.
-onEditCommit: async ({ rowId, changes }) => {
-  await api.patch(rowId, changes);
-},
-```
-
-Source: `src/tmdatagrid/useTMDataGrid.tsx` (`onEditCommit`).
-
-### 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 `"batch"` *every* edit is until
-`submitAll()` - so a form submit saves stale rows and collection rules pass
-over pending values.
-
-Correct:
-
-```tsx
-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();
-if (flushed) await form.handleSubmit();
-```
-
-Source: `src/docs/query-builder.md` (Which mode, Submitting).
-
-### 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.
-
-```tsx
-const saved = await grid.edit.submitAll();
-notifications.show({ message: saved ? "Saved" : "Some rows need attention" });
-```
-
-Source: `src/tmdatagrid/core/editEngine.ts` (`TMDataGridEditApi`).
-
-### MEDIUM Expecting `onRowDelete` to fire under batch
-
-Under the immediate modes `edit.deleteRow` calls `onRowDelete` at once. Under
-`"batch"` it only toggles a deletion mark, and the ids arrive later in
-`submitAll`'s `deleted`, so a batch grid that deletes through `onRowDelete`
-alone never removes anything. Handle `deleted` in `onEditCommitBatch`.
-
-Source: `src/docs/editing.md` (Adding and deleting rows).
+| Severity | Mistake |
+| --- | --- |
+| 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 cross-field rule under `mode: "cell"` - `rowValidators` needs `"row"` or `"draft"` |
+| 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 |
+| HIGH | Submitting an outer form while the grid holds a draft - it saves stale rows |
+| 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 `submitAll` |
 
 ## References
 
 - [Editors and validation](references/editors-and-validation.md) - the editor
-  contract, wrapping a built-in, what `mapValue` leaves alone, field and row
+  API, wrapping a built-in, what `mapValue` leaves alone, field and row
   validators, server-side errors.
 - [Editing API](references/editing-api.md) - every option, callback, column meta
-  field, export, CSS variable and data attribute editing owns.
+  field, export, CSS variable and data attribute belonging to editing.
+- [Common mistakes](references/common-mistakes.md) - the failure modes above,
+  each with its wrong and correct form.
 
 See also: the `columns` skill for `meta.type` and the shared `meta.options`
 source, and the `testing` skill for driving editors from a test.