@jielga/tmdatagrid 2.4.0 → 2.6.0

package/docs/columns.md

@@ -125,6 +125,7 @@ meta: {
 | `editor` | `TMDataGridEditorComponent` | By `type` | Replaces the cell editor. See [Editors](/docs/editors#writing-your-own). |
 | `validate` | `TMDataGridFieldValidate` | - | Per-cell validation. See [Validation](/docs/editors#validation). |
 | `mapValue` | `TMDataGridEditValueMap` | - | Maps each value an editor writes. See [Mapping the value](/docs/editors#mapping-the-value-as-it-is-typed). |
+| `mapCommitValue` | `TMDataGridEditCommitMap` | - | Maps each changed field once, as its row commits. See [Mapping the value at commit](/docs/editors#mapping-the-value-at-commit). |
 
 ```tsx
 meta: {

package/docs/components.md

@@ -245,7 +245,9 @@ The grid picks one from the column's `meta.type`, and `meta.edit.editor` replace
 | `TMDataGridSelectEditor` | `Select`, committing on pick in `"cell"` mode | `"select"` |
 | `TMDataGridMultiSelectEditor` | `MultiSelect`, committing on Enter or blur | `"multiSelect"` |
 
-Every editor takes the same argument object, `TMDataGridEditorArgs`, so a custom editor can wrap a built-in rather than replace it:
+Each built-in editor also takes `inputProps`, passed to its Mantine control. See [Extending a built-in editor](/docs/editors#extending-a-built-in-editor).
+
+Every editor takes the same argument object, `TMDataGridEditorArgs`:
 
 | Field | Type | What it is |
 | --- | --- | --- |

package/docs/editors.md

@@ -29,10 +29,98 @@ source the filter panel reads. Neither lives under `meta.edit`.
 The number editor writes `null` rather than `NaN` while the text does not parse, so a half-typed number leaves the field empty instead of committing a number no rule can describe.
 The date editor picks between its two types once, when it opens, from what the cell held: a `Date` cell keeps receiving `Date`s and a string cell keeps receiving `"YYYY-MM-DD"` strings, so clearing and retyping cannot flip the type.
 
-Each is a named export (`TMDataGridStringEditor`, `TMDataGridNumberEditor`,
-`TMDataGridBooleanEditor`, `TMDataGridDateEditor`, `TMDataGridSelectEditor`,
-`TMDataGridMultiSelectEditor`), so a custom editor can wrap one instead of
-starting from scratch.
+## Extending a built-in editor
+
+Each built-in editor is a named export that takes `TMDataGridEditorArgs` and `inputProps`.
+To change the Mantine control a built-in renders, pass `args` through whole and add props with `inputProps`:
+
+```tsx
+import { IconBarcode } from "@tabler/icons-react";
+import {
+  TMDataGridStringEditor,
+  type TMDataGridEditorComponent,
+} from "@jielga/tmdatagrid";
+
+const SkuEditor: TMDataGridEditorComponent = (args) => (
+  <TMDataGridStringEditor
+    {...args}
+    inputProps={{ leftSection: <IconBarcode size={14} /> }}
+  />
+);
+
+columnHelper.accessor("sku", {
+  header: "SKU",
+  meta: { edit: { editor: SkuEditor } },
+});
+```
+
+```demo
+file: editing/ExtendedEditors.tsx
+hint: Double-click a cell. SKU has an icon, Price a unit and no negative numbers, Category a dropdown shadow and its own "nothing found" text.
+height: 300
+```
+
+Define the editor at module scope, as for [your own editor](#writing-your-own).
+Spread `args` into the built-in with `{...args}`: its props type requires every field of `TMDataGridEditorArgs`.
+Do not spread or rebuild `field` itself, because it is a live TanStack Form `FieldApi` and a copy loses the binding its methods rely on.
+
+`inputProps` takes the props of the editor's Mantine control and `data-*` attributes, except the props the grid sets itself:
+
+| Editor | Mantine control | `inputProps` type | Set by the grid |
+| --- | --- | --- | --- |
+| `TMDataGridStringEditor` | `TextInput` | `TMDataGridStringEditorProps["inputProps"]` | `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridNumberEditor` | `NumberInput` | `TMDataGridNumberEditorProps["inputProps"]` | `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridBooleanEditor` | `Checkbox` | `TMDataGridBooleanEditorProps["inputProps"]` | `checked`, `defaultChecked`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridDateEditor` | `TextInput` | `TMDataGridDateEditorProps["inputProps"]` | `type`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridSelectEditor` | `Select` | `TMDataGridSelectEditorProps["inputProps"]` | `data`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label`, `comboboxProps.withinPortal` |
+| `TMDataGridMultiSelectEditor` | `MultiSelect` | `TMDataGridMultiSelectEditorProps["inputProps"]` | `data`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label`, `comboboxProps.withinPortal` |
+
+The props the grid sets are left out of each type, so passing one is a type error.
+`data-dg-part` is set after `inputProps`, so the input keeps `data-dg-part="editor-input"`.
+
+- `onFocus` and `onBlur` run after the grid's own handlers.
+  The string and number editors select the value on focus, and every editor calls `field.handleBlur()` on blur, which marks the field as touched and runs its `onBlur` validators.
+- `onBlur` runs when focus leaves the editor, for example on a click outside it.
+  It does not run when Enter, Tab or Escape closes the editor, or when a pick in the select editor commits under `"cell"`, because the editor closes before the focus moves.
+  To run code when an edit ends, use `editing.onCommit`, or `meta.edit.mapCommitValue` to change the committed value.
+- `ref` receives the control's input element; the grid keeps its own ref on it too.
+- `comboboxProps` on the select editors is merged with the grid's, and `withinPortal` is always `false`, because an option picked from a portal is a click outside the cell.
+- The defaults the grid sets on the control can be overridden: `w="100%"` on every editor except the checkbox, `hideControls` on the number editor, and `searchable` on the select editors.
+- The select editors read their options from `meta.options` only, so `data` is not accepted.
+- To change the value as it is typed, use [`meta.edit.mapValue`](#mapping-the-value-as-it-is-typed); `onChange` is the grid's.
+
+Important: do not stop the propagation of Enter, Tab or Escape in an `onKeyDown`, as the grid handles these keys on an ancestor to commit, move and cancel.
+Props that add text around the control, such as `label` and `description`, make the editor taller than the cell, and `aria-labelledby` replaces the grid's translated accessible name.
+
+To place content beside the control instead of inside it, render the built-in inside your own layout:
+
+```tsx
+import { Group, Text } from "@mantine/core";
+import {
+  TMDataGridNumberEditor,
+  TMDataGridSelectEditor,
+  TMDataGridStringEditor,
+  type TMDataGridEditorComponent,
+} from "@jielga/tmdatagrid";
+
+// Content beside the input.
+const SalaryEditor: TMDataGridEditorComponent = (args) => (
+  <Group gap={4} wrap="nowrap" w="100%">
+    <TMDataGridNumberEditor {...args} />
+    <Text size="xs" c="dimmed">
+      per month
+    </Text>
+  </Group>
+);
+
+// A different built-in per row.
+const DepartmentEditor: TMDataGridEditorComponent = (args) =>
+  args.row.original.status === "Terminated" ? (
+    <TMDataGridStringEditor {...args} />
+  ) : (
+    <TMDataGridSelectEditor {...args} />
+  );
+```
 
 ## Writing your own
 
@@ -134,6 +222,35 @@ A custom editor rendering its own input has the same problem, and solves it the
 same way: record `selectionStart` as the value is handed over, and restore it in
 a layout effect once the mapped value has rendered.
 
+## Mapping the value at commit
+
+`meta.edit.mapCommitValue` maps a field once, as its row commits, instead of on every write.
+Use it for a rule the user must be free to break while typing, such as trimming a string: with `mapValue`, a trailing space could never be typed.
+
+```tsx
+meta: {
+  edit: {
+    mapCommitValue: ({ value }) =>
+      typeof value === "string" ? value.trim() : value,
+  },
+}
+```
+
+It runs before the validators of the submit, so a field that trims to `""` fails a required rule.
+The result is written back into the form, so the draft, `changes` and `onCommit` all hold the mapped value.
+An editor still open after the commit shows it too: in row mode, or after a commit the validators refused.
+When a draft is held for `saveDrafts`, the mapped value is what the pending change shows.
+
+It runs for the fields the user changed.
+A stored value nobody edited is left as it is.
+A row being added has no stored value, so every editable field of it is mapped, a field `meta.edit.enabled` keeps the user out of included.
+A field written by `edit.setCellValue()`, `edit.setRowValues()`, `edit.clearCell()` or the Delete key is not mapped, because the caller passes the stored value itself; the other fields the user changed in the same row still are.
+The rows of `edit.addRows({ commit: true })` are not mapped at all.
+
+The map receives `TMDataGridEditCommitMapArgs`: `{ value, previous, row, column, table }`.
+`previous` is the value the field held when editing began, and `row` is `undefined` for a row being added.
+`mapValue` runs first, and its result is what `value` holds here.
+
 ## Validation
 
 The validators are TanStack Form's own: a Standard Schema (Zod, Valibot,
@@ -240,11 +357,15 @@ validator instead. See [A query builder form](/docs/query-builder).
 | `meta.edit.editor` | Column meta | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. |
 | `meta.edit.validate` | Column meta | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema or function means `onChange`. |
 | `meta.edit.mapValue` | Column meta | `TMDataGridEditValueMap` | – | Maps each value an editor writes, before it reaches the draft. |
+| `meta.edit.mapCommitValue` | Column meta | `TMDataGridEditCommitMap` | – | Maps each changed field once, as its row commits. See [Mapping the value at commit](#mapping-the-value-at-commit). |
 | `editing.rowValidators` | Option | `TMDataGridRowValidators` | – | Form-level validation, for cross-field rules. |
 | `editing.tableValidators` | Option | `TMDataGridTableValidators` | – | Cross-row rules, handed the collection with every draft overlaid. See [Cross-row rules](#cross-row-rules). |
 | `TMDataGridTableValidateArgs` | Export | type | – | What a table validator receives: `value`, `rowId`, `isNew`, `rows`. |
-| `TMDataGridEditorArgs` | Export | type | – | What an editor component receives: `field`, `commit`, `cancel`, `row`, `column`. |
+| `TMDataGridEditorArgs` | Export | type | – | What an editor component receives: `field`, `form`, `cell`, `row`, `column`, `table`, `commit`, `cancel`, `size`, `seedText`. See [Editors](/docs/components#editors). |
 | `TMDataGridEditValueMapArgs` | Export | type | – | What `mapValue` receives: `value`, `previous`, `row`, `column`, `table`. |
-| `TMDataGridStringEditor` · `NumberEditor` · `BooleanEditor` · `DateEditor` · `SelectEditor` · `MultiSelectEditor` | Exports | components | – | The six built-ins, for wrapping. |
+| `TMDataGridEditCommitMapArgs` | Export | type | – | What `mapCommitValue` receives: `value`, `previous`, `row`, `column`, `table`. |
+| `TMDataGridStringEditor` · `NumberEditor` · `BooleanEditor` · `DateEditor` · `SelectEditor` · `MultiSelectEditor` | Exports | components | – | The six built-in editors. See [Extending a built-in editor](#extending-a-built-in-editor). |
+| `inputProps` | Built-in editor prop | The Mantine control's props and `data-*` attributes, without the props the grid sets | – | Props passed to the Mantine control of a built-in editor. |
+| `TMDataGridStringEditorProps` · `NumberEditorProps` · `BooleanEditorProps` · `DateEditorProps` · `SelectEditorProps` · `MultiSelectEditorProps` | Exports | types | – | The props of each built-in editor: `TMDataGridEditorArgs` and `inputProps`. |
 | `normalizeFieldValidate` | Export | `(validate) => validators` | – | Turns a bare schema into TanStack Form's validator shape. |
 | `getEditFieldName` | Export | `(column) => string` | – | The data path a column's edits write to. |

package/docs/testing.md

@@ -185,6 +185,7 @@ None of them carries `data-column-id`; scope through the row.
 A column declaring `meta.filter.control` or `meta.edit.editor` renders your component
 in that slot, so `filter-value` and `editor-input` cover the built-ins only.
 `filter-row` and `editor` still apply; scope your own queries through them.
+A built-in editor extended through `inputProps` keeps `editor-input`.
 
 `editor-input` is also where the grid puts the caret when an editor opens. An
 editor that does not publish it is focused on the first focusable element inside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "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

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/styling.md'
   - 'Jielga/react:packages/tmdatagrid/docs/toolbar.md'

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/cell-selection.md'
   - 'Jielga/react:packages/tmdatagrid/src/core/cellNavigation.ts'

package/skills/columns/SKILL.md

@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/columns.md'
   - 'Jielga/react:packages/tmdatagrid/docs/column-layout.md'
@@ -98,7 +98,7 @@ with it sits in their namespaces. `type` and `options` are read by both stages,
 which is why they are in neither.
 
 `meta.filter` holds `operators`, `defaultOperator`, `control` and `url`; `meta.edit`
-holds `enabled`, `field`, `editor`, `validate` and `mapValue`. Their fields are
+holds `enabled`, `field`, `editor`, `validate`, `mapValue` and `mapCommitValue`. Their fields are
 in [references/columns-api.md](references/columns-api.md).
 
 ```tsx

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

@@ -22,6 +22,7 @@ Reference for the `columns` skill.
 | `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
 | `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
 | `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+| `mapCommitValue` | `TMDataGridEditCommitMap` | – | Maps each changed field once, as its row commits. |
 
 ## Column-level feature options
 

package/skills/data/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/react:packages/tmdatagrid/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -5,20 +5,20 @@ description: >
   (mode: cell, cellConfirm, row; draft), the required getRowId, editing.onCommit
   and editing.onSaveDrafts, why the grid never mutates data, gating with
   editing.columns, meta.edit.enabled and meta.edit.field, the built-in editors
-  picked by meta.type, custom editors via meta.edit.editor, value mapping with
-  meta.edit.mapValue, validation at every level - meta.edit.validate,
-  cross-field editing.rowValidators, cross-row editing.tableValidators over the
-  draft-overlaid collection - adding and deleting rows (edit.addRow,
-  newRowDefaults, onRowAdd, onRowDelete), the edit lane, TMDataGrid.DraftActions
-  and renderActions, and the edit engine (begin, commit, commitAll, saveDrafts,
-  addRows, setCellValue, setRowValues, getForm, store). Load when making a grid
-  editable, choosing an edit mode, wiring a save, writing a cell editor,
-  validating an edit, writing cells from a toolbar action or bulk fill, or when
-  cells will not open.
+  (meta.type, inputProps), custom editors via meta.edit.editor, value mapping
+  with mapValue and mapCommitValue, validation at every level -
+  meta.edit.validate, cross-field editing.rowValidators, cross-row
+  editing.tableValidators over the draft-overlaid collection - adding and
+  deleting rows (edit.addRow, newRowDefaults, onRowAdd, onRowDelete), the edit
+  lane, TMDataGrid.DraftActions and renderActions, and the edit engine (begin,
+  commit, commitAll, saveDrafts, addRows, setCellValue, setRowValues, getForm,
+  store). Load when making a grid editable, choosing an edit mode, wiring a
+  save, writing a cell editor, validating an edit, writing cells from a toolbar
+  action or bulk fill, or when cells will not open.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/draft-store.md'
@@ -207,11 +207,9 @@ columnHelper.accessor("salary", {
 
 ## Editors and validation
 
-`meta.type` picks the editor - `"string"` (the default), `"number"`,
-`"boolean"`, `"date"`, `"select"` and `"multiSelect"` - and `meta.options` feeds
-the two select editors from the same declaration the filter panel reads. Each
-one, with the value it writes into the draft and the export that wraps it, is in
-[references/editors-and-validation.md](references/editors-and-validation.md#the-built-in-editors).
+`meta.type` picks the editor - `"string"` (the default), `"number"`, `"boolean"`, `"date"`, `"select"` and `"multiSelect"` - and `meta.options` feeds the two select editors from the same declaration the filter panel reads.
+Each one, with the value it writes into the draft and its export, is in [references/editors-and-validation.md](references/editors-and-validation.md#the-built-in-editors).
+To add a `leftSection`, a unit or a wider dropdown, do not copy a built-in: render it from `meta.edit.editor` with `inputProps` ([Extending a built-in](references/editors-and-validation.md#extending-a-built-in)).
 
 `meta.edit.editor` replaces one, `meta.edit.validate` guards the field, and
 `editing.rowValidators` carries cross-field rules. The validators are TanStack
@@ -274,6 +272,19 @@ validators check and what is committed.
 meta: { edit: { mapValue: ({ value }) => String(value).toUpperCase() } }
 ```
 
+`meta.edit.mapCommitValue` maps once, as the row commits, for a rule the user must be free to break while typing: trimming a string.
+It runs before the submit validators on the fields the user changed, and writes the result back into the form, so the draft store, `changes` and `onCommit` all hold the mapped value.
+Trimming only in `onCommit` or on the server leaves the grid's own state untrimmed.
+
+```tsx
+meta: {
+  edit: {
+    mapCommitValue: ({ value }) =>
+      typeof value === "string" ? value.trim() : value,
+  },
+}
+```
+
 Detail for all three: [references/editors-and-validation.md](references/editors-and-validation.md).
 
 ## Adding and deleting rows
@@ -474,7 +485,7 @@ are in [references/common-mistakes.md](references/common-mistakes.md).
 ## References
 
 - [Editors and validation](references/editors-and-validation.md) - the editor
-  API, wrapping a built-in, what `mapValue` leaves alone, field, row and
+  API, extending a built-in with `inputProps`, what `mapValue` leaves alone, field, row and
   cross-row validators, derived columns with a table-wide rule, server-side
   errors.
 - [Editing API](references/editing-api.md) - every option, callback, column meta

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

@@ -124,7 +124,8 @@ type TMDataGridEditState = {
 | `hasPendingEdits` | Export | `(state) => boolean` - unsaved work: an open row with a changed value, any entry row, the draft store, or a save in flight. `useSelector(grid.edit.store, hasPendingEdits)` for a navigation blocker; do not use `openRowIds.length`, which also counts committed rows and rows that are only open. |
 | `getEditFieldName` | Export | `(column) => string` - the data path a column's edits write to. |
 | `normalizeFieldValidate` | Export | `(validate) => validators` - a bare schema into Form's shape. |
-| `TMDataGridStringEditor` … `TMDataGridMultiSelectEditor` | Exports | The six built-in editors, for wrapping. |
+| `TMDataGridStringEditor` … `TMDataGridMultiSelectEditor` | Exports | The six built-in editors, for extending with `inputProps` or wrapping. |
+| `TMDataGridStringEditorProps` · `TMDataGridNumberEditorProps` · `TMDataGridBooleanEditorProps` · `TMDataGridDateEditorProps` · `TMDataGridSelectEditorProps` · `TMDataGridMultiSelectEditorProps` | Exports | The props of each built-in editor: `TMDataGridEditorArgs` and `inputProps`. |
 
 Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
 `TMDataGridEditCommitArgs`, `TMDataGridSaveDraftsArgs`,
@@ -133,7 +134,8 @@ Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
 `TMDataGridRowValidators`, `TMDataGridRowEditForm`, `TMDataGridRowAddArgs`,
 `TMDataGridRowDeleteArgs`, `TMDataGridEditingOptions`,
 `TMDataGridSaveOutcomes`, `TMDataGridAddRowsOptions`,
-`TMDataGridEditValueMapArgs`, `TMDataGridTableValidateArgs`.
+`TMDataGridEditValueMapArgs`, `TMDataGridEditCommitMapArgs`,
+`TMDataGridTableValidateArgs`.
 
 ## The edit lane
 

package/skills/editing/references/editors-and-validation.md

@@ -94,11 +94,86 @@ columnHelper.accessor("salary", {
 });
 ```
 
-## Wrapping a built-in
+## Extending a built-in
 
-The built-ins take `TMDataGridEditorArgs` as their props, so a custom editor can
-pass the whole object through and render around it instead of starting from
-scratch.
+The built-ins take `TMDataGridEditorArgs` and `inputProps` as their props. To
+change the Mantine control a built-in renders, render it from a
+`meta.edit.editor`, pass `args` through whole, and add props with `inputProps`.
+Extend a built-in rather than copying its source: keeping the caret in place
+while `mapValue` rewrites the value, select-all on focus, the invalid border,
+the translated accessible name and `data-dg-part="editor-input"` all come with
+it. The props type requires every field of `TMDataGridEditorArgs`, so spread
+`{...args}`; never spread or rebuild `field` itself.
+
+```tsx
+import { Text } from "@mantine/core";
+import { IconBarcode } from "@tabler/icons-react";
+import {
+  TMDataGridNumberEditor,
+  TMDataGridSelectEditor,
+  TMDataGridStringEditor,
+  type TMDataGridEditorComponent,
+} from "@jielga/tmdatagrid";
+
+// Module scope. A new identity per render remounts the editor mid-edit.
+const SkuEditor: TMDataGridEditorComponent = (args) => (
+  <TMDataGridStringEditor
+    {...args}
+    inputProps={{ leftSection: <IconBarcode size={14} /> }}
+  />
+);
+
+const PriceEditor: TMDataGridEditorComponent = (args) => (
+  <TMDataGridNumberEditor
+    {...args}
+    inputProps={{ allowNegative: false, rightSection: <Text size="xs">kr</Text> }}
+  />
+);
+
+// comboboxProps is merged with the grid's; withinPortal is not accepted.
+const CategoryEditor: TMDataGridEditorComponent = (args) => (
+  <TMDataGridSelectEditor {...args} inputProps={{ comboboxProps: { shadow: "md" } }} />
+);
+```
+
+| Editor | Mantine control | Set by the grid, left out of `inputProps` |
+| --- | --- | --- |
+| `TMDataGridStringEditor` | `TextInput` | `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridNumberEditor` | `NumberInput` | `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridBooleanEditor` | `Checkbox` | `checked`, `defaultChecked`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridDateEditor` | `TextInput` | `type`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label` |
+| `TMDataGridSelectEditor` | `Select` | `data`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label`, `comboboxProps.withinPortal` |
+| `TMDataGridMultiSelectEditor` | `MultiSelect` | `data`, `value`, `defaultValue`, `onChange`, `error`, `size`, `aria-label`, `comboboxProps.withinPortal` |
+
+- `inputProps` also takes `data-*` attributes; `data-dg-part` stays
+  `"editor-input"`, because the grid sets it after the spread.
+- `onFocus` and `onBlur` run after the grid's own: select-all on focus in the
+  string and number editors, `field.handleBlur()` (touched, `onBlur`
+  validators) in every editor.
+- `onBlur` runs only when focus leaves the editor, such as a click outside it.
+  Enter, Tab, Escape and a committing select pick close the editor before the
+  focus moves, so it does not run. Code for "the edit ended" belongs in
+  `editing.onCommit` or `meta.edit.mapCommitValue`.
+- `ref` receives the input element; the grid's own ref stays attached.
+- `comboboxProps` is merged with the grid's and `withinPortal` is always
+  `false`, because an option picked from a portal is a click outside the cell.
+- A consumer `onKeyDown` must not stop the propagation of Enter, Tab or Escape:
+  the grid handles them on an ancestor.
+- `label` and `description` make the editor taller than the cell;
+  `aria-labelledby` replaces the grid's translated accessible name.
+- `onChange` is the grid's; to rewrite the value as it is typed, use
+  `meta.edit.mapValue`.
+- The grid's defaults can be overridden: `w="100%"` (not on the checkbox),
+  `hideControls` on the number editor, `searchable` on the select editors.
+- The select editors read options from `meta.options` only; `data` is not
+  accepted.
+- The props types are exported: `TMDataGridStringEditorProps`,
+  `TMDataGridNumberEditorProps`, `TMDataGridBooleanEditorProps`,
+  `TMDataGridDateEditorProps`, `TMDataGridSelectEditorProps`,
+  `TMDataGridMultiSelectEditorProps`.
+
+To place content beside the control instead of inside it, render the built-in
+inside your own layout:
 
 ```tsx
 import { Group, Text } from "@mantine/core";
@@ -182,6 +257,30 @@ otherwise drops the caret at the end of the field. A custom editor rendering its
 own input has to do the same: record `selectionStart` on change, restore it in a
 layout effect.
 
+## Mapping the value at commit
+
+`meta.edit.mapCommitValue` maps a field once, as its row commits, where `mapValue` runs on every write.
+Use it for a rule the user must be free to break while typing: trimming a string, because with `mapValue` a trailing space could never be typed.
+
+```tsx
+meta: {
+  edit: {
+    mapCommitValue: ({ value }) =>
+      typeof value === "string" ? value.trim() : value,
+  },
+}
+```
+
+- It runs before the submit validators, so `"   "` trimmed to `""` fails a required rule.
+- The result is written back into the form: the draft store, `changes` and `onCommit` hold the mapped value, and so does an editor still open after the commit (row mode, or a refused commit).
+  Trimming in `onCommit` or on the server instead leaves the grid's own state untrimmed.
+- It maps only the fields the user changed.
+  A row being added maps every editable field.
+- A field written by `edit.setCellValue()`, `edit.setRowValues()`, `edit.clearCell()` or the Delete key is not mapped; the other fields the user changed in that row still are.
+  The rows of `edit.addRows({ commit: true })` are not mapped at all.
+- The map receives `TMDataGridEditCommitMapArgs`: `{ value, previous, row, column, table }`.
+  `previous` is the value when editing began; `row` is `undefined` for a row being added.
+
 ## Field validation
 
 `meta.edit.validate` takes TanStack Form's field-validator vocabulary. A bare schema

package/skills/filtering/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/react:packages/tmdatagrid/docs/quick-search.md'

package/skills/getting-started/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/react:packages/tmdatagrid/docs/anatomy.md'

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/grouping.md'
   - 'Jielga/react:packages/tmdatagrid/docs/summary-row.md'

package/skills/migrating-to-2/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: lifecycle
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/migrating-to-2.md'
   - 'Jielga/react:packages/tmdatagrid/src/index.ts'

package/skills/options/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/use-tm-data-grid.md'
   - 'Jielga/react:packages/tmdatagrid/docs/persistence.md'

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/react:packages/tmdatagrid/docs/row-interaction.md'

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/server-side.md'
   - 'Jielga/react:packages/tmdatagrid/docs/server-query.md'

package/skills/testing/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:playwright/support/DataGrid.ts'

package/skills/testing-components/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/test/gallery/main.tsx'

package/skills/testing-editing/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.6.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
@@ -102,7 +102,9 @@ async saveDrafts(): Promise<void> {
 
 `fillRow` covers the built-in editors. A column with `meta.edit.editor` renders
 the app's own component inside the `editor` part; scope through
-`part("editor", { rowId, columnId })` and fill whatever is inside.
+`part("editor", { rowId, columnId })` and fill whatever is inside. A built-in
+editor rendered through `meta.edit.editor` with `inputProps` keeps
+`editor-input`, so `fillRow` covers it.
 
 ## Recipes
 

package/src/components/editors/TMDataGridBooleanEditor.tsx

@@ -1,26 +1,48 @@
-import { Checkbox } from "@mantine/core";
+import { Checkbox, type CheckboxProps } from "@mantine/core";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldInvalid, useFieldValue } from "./editorShared";
+import {
+  useFieldInvalid,
+  useFieldValue,
+  type EditorDataAttributes,
+} from "./editorShared";
+
+export type TMDataGridBooleanEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `Checkbox`. The grid keeps `checked`, `onChange`,
+   * `error`, `size` and the accessible name; `onBlur` runs after the grid's
+   * own.
+   */
+  inputProps?: Omit<
+    CheckboxProps,
+    "checked" | "defaultChecked" | "onChange" | "error" | "size" | "aria-label"
+  > &
+    EditorDataAttributes;
+};
 
 /** The built-in editor for `meta.type: "boolean"` - a focused checkbox. */
 export function TMDataGridBooleanEditor({
   field,
   column,
   size,
-}: TMDataGridEditorArgs) {
+  inputProps,
+}: TMDataGridBooleanEditorProps) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
   return (
     <Checkbox
+      {...inputProps}
       size={size}
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
       checked={value === true}
       onChange={(event) => field.handleChange(event.currentTarget.checked)}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );