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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.4",
   "description": "A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.",
   "license": "MIT",
   "type": "module",

package/skills/appearance/SKILL.md

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/styling.md'
   - 'Jielga/TMDataGrid:src/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/cell-selection.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/core/cellNavigation.ts'

package/skills/columns/SKILL.md

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/columns.md'
   - 'Jielga/TMDataGrid:src/docs/column-layout.md'

package/skills/data/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/pagination.md'
   - 'Jielga/TMDataGrid:src/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -3,7 +3,7 @@ name: editing
 description: >
   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,
+  editing.onCommit and editing.onSaveDrafts, 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
@@ -11,13 +11,14 @@ description: >
   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,
-  writing a cell editor, validating an edit, or when cells will not open.
+  the public edit engine (begin, commit, commitAll, saveDrafts, addRows,
+  getForm, store). Load when making a grid editable, choosing an edit mode,
+  wiring a save, writing a cell editor, validating an edit, or when cells will
+  not open.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/editing.md'
   - 'Jielga/TMDataGrid:src/docs/query-builder.md'
@@ -69,8 +70,8 @@ const grid = useTMDataGrid({
 ```
 
 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`
+requires `getRowId`, and `editing.onSaveDrafts` exists only under
+`editing.mode: "draft"`. Draft _without_ `onSaveDrafts` is fine: `saveDrafts`
 falls back to the per-row `editing.onCommit` loop.
 
 ## The four modes
@@ -83,7 +84,7 @@ as a commit, and which controls trigger it.
 | `"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 |
-| `"draft"` | `edit.submitAll()` | `edit.cancelAll()`, or per row in the lane | `TMDataGrid.EditActions` + the edit lane |
+| `"draft"` | Enter or the lane's ✓, into the draft store | `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
@@ -104,7 +105,8 @@ the cell clicked, opens every editable cell of the row, and ✓ saves them as on
 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
+Under `"draft"` nothing reaches a callback until `saveDrafts`. Enter commits the
+row into the draft store; Tab holds
 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
@@ -119,11 +121,23 @@ 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
+`saveDrafts` then sends the draft store: 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.
+or through one `editing.onSaveDrafts({ updated, created, deleted })` call when
+that is set. `updated` entries carry a `rowId`, `created` entries a `tempId`, `deleted` is
+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.
+
+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.
 
 ## What a commit receives
 
@@ -210,18 +224,21 @@ 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 `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.
+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 the immediate modes;
+under draft mode it puts the row in the draft store, validated, and
+`saveDrafts` reports it in `added`. Escape, or ✕, discards the entry. An entry
+row never OK'd is not part of a save - it stays open.
 
 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
+`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 entered rows pinned in the entry block until Save all. Double-click, or
+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
-`useSelector(grid.edit.store, (s) => s.newRows.some((n) => !n.confirmed))`.
+`useSelector(grid.edit.store, (s) => s.newRows.some((n) => !n.committed))`.
 
 ```tsx
 const grid = useTMDataGrid({
@@ -231,23 +248,39 @@ const grid = useTMDataGrid({
   editing: {
     mode: "draft",
     newRowDefaults: () => ({ id: 0, firstName: "", salary: 30_000 }),
-    onCommitDrafts: async ({ rows, added, deleted }) => {
-      await api.saveBatch({ rows, added, deleted });
+    onSaveDrafts: async ({ updated, created, deleted }) => {
+      await api.saveBatch({ updated, created, deleted });
     },
   },
 });
 
 <TMDataGrid.Toolbar>
   <Button onClick={() => grid.edit.addRow()}>Add row</Button>
+  <Button onClick={() => grid.edit.addRow({ salary: 50_000 })}>
+    Add senior
+  </Button>
   <TMDataGrid.Spacer />
   <TMDataGrid.EditActions />
 </TMDataGrid.Toolbar>;
 ```
 
+`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.
+
+```tsx
+const { committed, open } = await grid.edit.addRows(parsed, { commit: true });
+if (open.length > 0) notify(`${open.length} rows need attention`);
+await grid.edit.saveDrafts();
+```
+
 `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
+(`data-deleted`), the lane shows Restore, and `saveDrafts` 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.
 
@@ -283,7 +316,8 @@ while editing is off, and works under any mode, not only draft.
 ## The engine: `edit`
 
 `grid.edit` is public, and everything the built-in controls do goes through it:
-`begin` and `commit`, `cancel` / `cancelAll`, `submitAll`, `addRow` /
+`begin` and `commit`, `cancel` / `cancelAll`, `commitAll` / `saveDrafts`,
+`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)).
 Every member with its signature, the gates, `clearCell`, `deactivate`, and the
@@ -324,7 +358,7 @@ are in [references/common-mistakes.md](references/common-mistakes.md).
 | 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` |
+| MEDIUM | Expecting `editing.onRowDelete` to fire under draft - the mark waits for `saveDrafts` |
 
 ## References
 

package/skills/editing/references/common-mistakes.md

@@ -137,7 +137,7 @@ Source: `src/tmdatagrid/useTMDataGrid.tsx` (`TMDataGridEditingCallbacks`).
 ## 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 `"draft"` every edit is until `submitAll()`,
+row is invisible to it, and under `"draft"` every edit is until `saveDrafts()`,
 so a form submit saves stale rows and collection rules skip pending values.
 
 Correct:
@@ -146,8 +146,9 @@ Correct:
 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();
+// or commit and flush instead of blocking:
+await grid.edit.commitAll();
+const flushed = await grid.edit.saveDrafts();
 if (flushed) await form.handleSubmit();
 ```
 
@@ -155,12 +156,13 @@ 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.
+`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.
 
 ```tsx
-const saved = await grid.edit.submitAll();
+const saved = await grid.edit.saveDrafts();
 notifications.show({ message: saved ? "Saved" : "Some rows need attention" });
 ```
 
@@ -170,7 +172,7 @@ Source: `src/tmdatagrid/core/editEngine.ts` (`TMDataGridEditApi`).
 
 Under the immediate modes `edit.deleteRow` calls `editing.onRowDelete` at once.
 Under `"draft"` it only toggles a deletion mark, so nothing is removed until
-`submitAll`: the ids arrive as `deleted` in `editing.onCommitDrafts`, or, with
+`saveDrafts`: the ids arrive as `deleted` in `editing.onSaveDrafts`, or, with
 no such callback, in the per-row `editing.onRowDelete` loop. A confirmation
 placed inside `editing.onRowDelete` therefore guards the save, not the trash.
 

package/skills/editing/references/editing-api.md

@@ -17,7 +17,7 @@ kind.
 | `cellSelection` | `"none" \| "single" \| "range"` | `"single"` while `editing` is set | Editing turns the cell cursor on; set it explicitly to override. |
 
 Passing any other member of `editing` without `mode` is a compile error, and
-`onCommitDrafts` and `newRowsSticky` exist only in the `"draft"` branch of the
+`onSaveDrafts` and `newRowsSticky` exist only in the `"draft"` branch of the
 type.
 
 ## Callbacks
@@ -25,7 +25,8 @@ 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.onCommitDrafts` | `{ rows, added, deleted }` | Draft mode only. One call for the entire save. Without it, `submitAll` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onSaveDrafts` | `{ rows, added, deleted }` | Draft mode only. One call for the whole draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
+| `editing.onCommitDrafts` | `{ rows, added, deleted }` | **Deprecated** - renamed to `onSaveDrafts`. Still honoured; the new name wins if both are set. |
 | `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
 | `editing.onRowDelete` | `{ rowId, row }` | Deletes a row under the immediate modes, and puts the trash can in the edit lane. |
 
@@ -49,14 +50,17 @@ 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 an entered new row it reopens the row, flipping `confirmed` back to `false`. |
-| `commit` | `(rowId) => Promise<boolean>` | `false` keeps the form open with its errors. Under `"draft"` it validates and holds the draft: no consumer callback runs until `submitAll`. |
+| `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. Under `"draft"` a pass puts the row in the draft store - 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. |
 | `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>` | Draft mode's Save all. `true` when every row landed. |
+| `submitAll` | `() => Promise<boolean>` | **Deprecated** - `commitAll()` then `saveDrafts()`. |
 | `clearCell` | `(rowId, columnId) => Promise<boolean>` | What Delete does: writes the type's empty value and commits. |
-| `addRow` | `() => string` | Opens an entry row, returns its `tempId`. |
+| `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` under the immediate modes, a deletion mark under draft mode. Toggles: a second call restores the row. |
 | `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. |
 | `canEditRow` | `(row) => boolean` | The pencil's gate. |
@@ -71,8 +75,8 @@ 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. One under `"cell"`; as many as the user opened
-  // under `"row"`, `"cellConfirm"` and `"draft"` - which rows are editing.
+  // Rows with a live form, committed or not. A row is *open* when it is in
+  // here and not in `committedRowIds`.
   openRowIds: ReadonlyArray<string>;
   // One `TMDataGridEditRowProjection` per open row.
   rows: Record<
@@ -86,9 +90,12 @@ type TMDataGridEditState = {
       values: TMDataGridRowData;
     }
   >;
-  // `confirmed` is draft mode's "entered, awaiting Save all". Under the
-  // immediate modes a confirm commits through `onRowAdd`, so it stays `false`.
-  newRows: ReadonlyArray<{ tempId: string; confirmed: boolean }>;
+  // The draft store's edit slice: existing rows whose form passed its submit,
+  // parked for `saveDrafts`. Empty outside `"draft"`.
+  committedRowIds: ReadonlyArray<string>;
+  // `committed` is draft mode's "in the store, awaiting the save". Under the
+  // immediate modes a commit adds through `onRowAdd`, so it stays `false`.
+  newRows: ReadonlyArray<{ tempId: string; committed: boolean }>;
   deletedRowIds: ReadonlyArray<string>;
 };
 ```
@@ -119,7 +126,7 @@ holds:
 
 - `editing.mode: "row"` - the lane is Save and Cancel's home
 - `editing.mode: "draft"` - the lane is the change indicator and the per-row
-  revert, and `editing.onCommitDrafts` is not required for it
+  revert, and `editing.onSaveDrafts` is not required for it
 - `editing.onRowDelete` is set - the trash can has somewhere to report to
 
 `"cell"` and `"cellConfirm"` have no lane unless `editing.onRowDelete` asks for
@@ -142,7 +149,7 @@ control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
 | `--dg-row-new-bg` | CSS variable | Background of an entered new row. A green tint. |
 | `data-deleted` | Row attribute | On a row marked for deletion under draft mode. |
 | `data-dirty` | Row attribute | On a body row holding a dirty draft. Also on the cell whose field is dirty. |
-| `data-new` / `data-confirmed` | Entry row attributes | On an entry row; `data-confirmed` once it is entered, awaiting Save all. |
+| `data-new` / `data-committed` | Entry row attributes | On an entry row; `data-committed` once it is committed, awaiting the save. |
 | `data-dg-entry-flow-block` | Attribute | The in-flow block above the body rows holding entered new rows, unless `editing.newRowsSticky` keeps them in the sticky entry block. |
 | `data-dg-part="editor-input"` | Part | The control inside an editing cell. |
 | `data-dg-part="save-row"` / `"cancel-row"` | Parts | The edit lane's buttons on an open row, with `data-row-id`. Row mode only. |

package/skills/filtering/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/filtering.md'
   - 'Jielga/TMDataGrid:src/docs/quick-search.md'

package/skills/getting-started/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/getting-started.md'
   - 'Jielga/TMDataGrid:src/docs/anatomy.md'

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/grouping.md'
   - 'Jielga/TMDataGrid:src/docs/summary-row.md'

package/skills/options/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
@@ -62,10 +62,11 @@ rather than forwarded to TanStack.
 | `onFocusedCellChange` | `(cell \| null) => void` | – | Fires whenever the focused cell moves. |
 | `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Defined by the grid. |
 | `columnResizeMode` | `"onChange" \| "onEnd"` | `"onChange"` | Resize update strategy. |
-| `initialState` | `Partial<TableState>` | See below | Merged over the grid defaults. |
+| `initialState` | `Partial<TableState>` | See below | The state the grid starts from, read once on mount. Merged over the grid defaults. |
+| `state` | `Partial<TableState>` | – | Controlled state. Each slice requires its `onXChange` - see below. |
 | `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
 | `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
-| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. `mode` (`"cell" \| "cellConfirm" \| "row" \| "draft"`) picks the commit policy; the object also holds `onCommit`, `onCommitDrafts`, `rowValidators`, `isRowEditable`, `newRowDefaults`, `newRowsSticky`, `onRowAdd` and `onRowDelete` - see the `editing` skill. |
+| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. `mode` (`"cell" \| "cellConfirm" \| "row" \| "draft"`) picks the commit policy; the object also holds `onCommit`, `onSaveDrafts`, `rowValidators`, `isRowEditable`, `newRowDefaults`, `newRowsSticky`, `onRowAdd` and `onRowDelete` - see the `editing` skill. |
 | `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. |
 
 ### Default initial state
@@ -76,6 +77,35 @@ rather than forwarded to TanStack.
 | `columnPinning.left` | The checkbox column, followed by any columns you provide |
 | `globalFilterFn` | `"includesString"` |
 
+### Controlled state
+
+`state` makes a slice controlled: the parent owns the value, the grid reads it
+every render, and all writes go through the matching `onXChange`. Without the
+callback the slice cannot change; the grid logs a console warning in
+development. For a starting value only, use `initialState`.
+
+```tsx
+const [columnVisibility, setColumnVisibility] = useState({ play: false });
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  state: { columnVisibility },
+  onColumnVisibilityChange: setColumnVisibility,
+});
+```
+
+- A key set to `undefined` is ignored; the slice is uncontrolled.
+- Slices compare structurally between renders, so the `state` object can be
+  built inline. `Date`s compare by time; `Map`s and class instances compare by
+  identity and belong in `useState` or `useMemo`.
+- `atoms` also controls a slice, with no callback. Takes precedence over
+  `state` for the same slice.
+- `columnVisibility` toggles user-defined columns only. Entries for the
+  generated columns are ignored; enable or disable those through their feature
+  options. The tree column's entry follows `grouping`.
+- `persist` cannot restore a controlled slice; it still writes it to storage.
+
 ## meta
 
 | Field | Type | Default | Description |

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/row-selection.md'
   - 'Jielga/TMDataGrid:src/docs/row-interaction.md'

package/skills/server-side/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/server-side.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'

package/skills/testing/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.4'
 sources:
   - 'Jielga/TMDataGrid:src/docs/testing.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'

package/src/tmdatagrid/components/TMDataGridCellEditor.tsx

@@ -172,7 +172,11 @@ export function TMDataGridCellEditor({
     onClose({ committed: false, via: "escape" });
   };
 
-  /** Draft: the key closes the editor and leaves the draft for submitAll. */
+  /**
+   * Draft: the key closes the editor and leaves the row open - undecided
+   * form state, which `saveDrafts` does not send. Tab moving along the row
+   * is not a decision about it; Enter is, and commits instead.
+   */
   const deferAndClose = (via: "defer" | "defer-tab" | "defer-shift-tab") => {
     if (closingRef.current) return;
     closingRef.current = true;
@@ -185,12 +189,11 @@ export function TMDataGridCellEditor({
     if (event.key === "Enter") {
       event.preventDefault();
       event.stopPropagation();
-      // In row mode Enter (and Ctrl+Enter, the documented pair) saves the
-      // row; in draft nothing reaches a callback until submitAll, so Enter
-      // parks the draft - and in the entry block it confirms the entry, which
-      // the engine parks the same way.
-      if (isDraft && !inEntryBlock) deferAndClose("defer");
-      else void commitAndClose("enter");
+      // Enter is OK, in every mode: the row's form submits and has to pass
+      // validation. What a commit *does* is the mode's business - the
+      // immediate modes call the consumer, draft mode parks the row in the
+      // draft store for `saveDrafts` - so this key does not branch.
+      void commitAndClose("enter");
     } else if (event.key === "Escape") {
       event.preventDefault();
       event.stopPropagation();