@jielga/tmdatagrid 2.0.0-beta.9 → 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.9'
+  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.9'
+  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.
 
@@ -85,13 +88,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 +113,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 +136,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 +233,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 +246,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: {
@@ -255,8 +277,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 +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();
 ```
 
@@ -318,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.
@@ -353,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
@@ -376,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.
@@ -397,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.
 
@@ -428,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 |
@@ -437,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
 

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).