@jielga/tmdatagrid 2.0.0-beta.8 → 2.0.0

package/skills/data/SKILL.md

@@ -10,17 +10,23 @@ description: >
   onReachEnd is better for loading more, the header and pinned-lane depth
   shadows, and the four empty states in precedence order with meta.loading,
   renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator and
-  TMDataGrid.SummaryCount. Load when adding a pager, tuning scrolling, scrolling
-  to a row, or deciding what an empty grid should say.
+  TMDataGrid.SummaryCount, and export: TMDataGrid.Menu.Export and
+  Menu.ExportSelected, useTMDataGridExport, exportGrid, exportOptions, the
+  csvExcel / csv / tsv / json formats, meta.exportValue and meta.enableExport.
+  Load when adding a pager, tuning scrolling, scrolling to a row, deciding what
+  an empty grid should say, or exporting rows to Excel or CSV.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.8'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/pagination.md'
-  - 'Jielga/TMDataGrid:src/docs/scrolling.md'
-  - 'Jielga/TMDataGrid:src/docs/loading-and-empty.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/pagination.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/scrolling.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/loading-and-empty.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/export.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/pagination.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/export.ts'
 ---
 
 # TMDataGrid - Pagination, scrolling and empty states
@@ -77,7 +83,10 @@ pieces, already wired.
 `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are what the default
 footer renders, in that order, so a custom layout can keep the parts it wants
 instead of rebuilding them. They behave exactly as before, including greying out
-under a suspended pager.
+under a suspended pager. `Controls.PageNumber` - the "Page 3 of 200" label a
+server-paged grid usually shows in place of a row range - is a fourth control,
+not in the default footer; put it in through the slot rather than writing it by
+hand.
 
 `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
 `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
@@ -178,6 +187,67 @@ server-driven grid refetching with rows still on screen keeps showing them.
 total, where the total is `meta.totalRowCount` when provided and the pre-filtered
 count otherwise.
 
+## Export
+
+Every filtered and sorted row across every page, or the selected rows, as a
+file. The built-in entry points are menu items; a button of your own uses the
+hook.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: csvFormat(), fileName: "employees" },
+});
+
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.ExportSelected />
+</TMDataGrid.Menu>
+```
+
+```tsx
+function ExportButton() {
+  const { exportAll, exportSelected, selectedCount, canExportSelected } =
+    useTMDataGridExport();
+  return <Button onClick={() => void exportAll()}>Export</Button>;
+}
+```
+
+What is written: the data columns in render order (never the generated lanes,
+never a column with `meta.enableExport: false`), every row after filtering and
+sorting (a grouped grid writes the records under every group, never the group
+rows), and each cell's **value** rather than what it renders -
+`meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+`columns` on `exportOptions`, the items and the functions is `"visible"` (the
+default), `"all"` (hidden columns too) or a list of ids; `columns="custom"` on
+a menu item opens a picker instead - every exportable column, the visible ones
+ticked, Export and Cancel - driven by `ui.state.exportPicker` and
+`ui.actions.openExportPicker`. `TMDataGrid.Menu.ExportSelected` counts and
+writes the ticked rows of the current view, in grid order; it renders nothing
+when row selection is off.
+
+Formats, each a `TMDataGridExportFormat` from a factory:
+
+| Factory | Writes |
+| --- | --- |
+| `csvExcelFormat()` (default) | BOM, `sep=;` line, CRLF, `;` fields, `,` decimal - opens straight into columns in Excel. `separator`, `decimalComma` for another locale. |
+| `csvFormat()` | RFC 4180: `,` fields, `.` decimal, BOM, no `sep=` line - for Google Sheets, Numbers and tooling. |
+| `tsvFormat()` | Tab-separated, the clipboard shape as a file. |
+| `jsonFormat()` | One object per row keyed by column label, numbers as numbers, dates as ISO strings. |
+| `xlsxFormat()` | Excel workbook, from the separate `@jielga/tmdatagrid-xlsx` package. |
+
+The text formats guard against formula injection by default: a value starting
+with `=`, `+`, `-` or `@` that is not a number is prefixed with `'`.
+`escapeFormulas: false` on the format turns that off.
+
+`exportGrid({ table, rows: "all" | "selected" | rows, options })` is the same
+export for code outside a component; `buildExportData` is the step before the
+file. A format of your own is `{ id, extension, mimeType, write(data, { includeHeaders }) }`
+returning a string, a `Blob`, or a promise of either.
+
+Source: `packages/tmdatagrid/docs/export.md`.
+
 ## Common mistakes
 
 ### CRITICAL Turning pagination on to make a large grid fast
@@ -186,7 +256,7 @@ Virtualization is already unconditional, so paging a 200 000-row grid changes
 nothing about rendering cost. It only changes how users navigate. Enable it when
 they should move page by page, not for performance.
 
-Source: `src/docs/pagination.md`, `src/docs/scrolling.md`.
+Source: `packages/tmdatagrid/docs/pagination.md`, `packages/tmdatagrid/docs/scrolling.md`.
 
 ### CRITICAL A variable row height
 
@@ -207,7 +277,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
 ```
 
-Source: `src/docs/scrolling.md` (Row height).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Row height).
 
 ### HIGH `scrollIntoView` on a row that is not mounted
 
@@ -223,7 +293,7 @@ grid.scrollToRow({ rowId: "4000", align: "center" });
 `scrollToRow` returns `false` when the row is not in the current view (filtered
 out, on another page, or an id matching no row) and nothing scrolled.
 
-Source: `src/docs/scrolling.md` (Scrolling to a row).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Scrolling to a row).
 
 ### HIGH Loading more rows from `onScrollToBottom`
 
@@ -231,7 +301,7 @@ It fires at the very bottom, so the user waits at the end of the list for the
 fetch. `onReachEnd` fires a number of rows earlier and latches per row count, so
 a pending fetch is not requested twice.
 
-Source: `src/docs/scrolling.md` (Edge callbacks).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Edge callbacks).
 
 ### HIGH `SummaryCount` reporting the page under manual pagination
 
@@ -250,7 +320,7 @@ useTMDataGrid({
 });
 ```
 
-Source: `src/docs/loading-and-empty.md` (Counting what is there).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (Counting what is there).
 
 ### MEDIUM Rendering an empty message while data is loading
 
@@ -264,7 +334,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { loading: isFetching } });
 ```
 
-Source: `src/docs/loading-and-empty.md` (What wins).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
 
 ### MEDIUM Trusting the pager while grouped
 
@@ -272,7 +342,7 @@ Source: `src/docs/loading-and-empty.md` (What wins).
 grid is rendering the whole tree. A custom pager must read
 `isPagingActive(table, features)` rather than the page count.
 
-Source: `src/docs/pagination.md` (Grouping suspends it).
+Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 
 ## Reference
 
@@ -283,7 +353,7 @@ Source: `src/docs/pagination.md` (Grouping suspends it).
 | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
 | `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
 | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
-| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `pagination` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. |
+| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
 | `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
 | `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot argument. |

package/skills/editing/SKILL.md

@@ -18,13 +18,15 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.8'
+  library_version: '2.0.0'
 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/src/core/editEngine.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
 ---
 
 # TMDataGrid - Editing
@@ -34,9 +36,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.
 
@@ -82,16 +85,18 @@ They are independent, and every pair is legal.
 | Mode | Commits on | Cancels on | Controls |
 | --- | --- | --- | --- |
 | `"cell"` | Enter, Tab, leaving the cell | Escape | none |
-| `"cellConfirm"` | ✓ or Enter; Tab and leaving keep the draft | ✕ or Escape | ✓ / ✕ beside the input |
+| `"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,9 +113,12 @@ 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, surviving filters, sorts and scrolling.
-`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 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.
 
 The edit lane is the change indicator and the per-row undo: an edited row shows
@@ -128,15 +136,27 @@ 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, on entry rows, `data-new`. The grid paints none of
-them; use `rowStyle` / `rowClassName` or the attributes to highlight what is
-pending.
+Save), `data-deleted` and `data-new` - a committed new row in the body, or an
+entry row in the block. The grid paints none of them; use `rowStyle` /
+`rowClassName` or the attributes to highlight what is pending.
 
 ## What a commit receives
 
@@ -213,16 +233,22 @@ 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
 `onSubmit` / `onSubmitAsync` receive `{ value, rowId, isNew, rows }`, where
 `rows` is the collection as it would stand if the commit landed: every draft
-overlaid, entry rows appended, deletion-marked rows removed. Same result
+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: {
@@ -251,16 +277,18 @@ 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` an entered row renders as a value row with no inputs, marked
-`data-new` and `data-committed` and tinted with `--dg-row-new-bg`. By default it
-joins the scrolling flow above the body rows; `editing.newRowsSticky: true`
-keeps committed rows pinned in the entry block until the save. 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
+Under `draft: true` a committed entry row leaves the entry block and becomes a
+body row with no inputs, marked `data-new` and `data-draft`, tinted with
+`--dg-row-new-bg`, and sorted, filtered and counted with the rest on the values
+it was entered with. `editing.newRowsSticky: true` keeps committed rows in the
+entry block until the save instead, out of the body's sort and out of the row
+count. Double-click, or the lane's pencil, reopens it back into the entry block;
+✕ 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.committed))`.
 
 ```tsx
@@ -291,13 +319,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();
 ```
 
@@ -312,8 +341,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.
@@ -347,10 +376,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
@@ -370,16 +399,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.
@@ -391,7 +424,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.
 
@@ -422,7 +455,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 |
@@ -431,6 +463,7 @@ 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