@jielga/tmdatagrid 2.4.0 → 2.5.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/editors.md

@@ -134,6 +134,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 +269,13 @@ 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`. |
 | `TMDataGridEditValueMapArgs` | Export | type | – | What `mapValue` receives: `value`, `previous`, `row`, `column`, `table`. |
+| `TMDataGridEditCommitMapArgs` | Export | type | – | What `mapCommitValue` receives: `value`, `previous`, `row`, `column`, `table`. |
 | `TMDataGridStringEditor` · `NumberEditor` · `BooleanEditor` · `DateEditor` · `SelectEditor` · `MultiSelectEditor` | Exports | components | – | The six built-ins, for wrapping. |
 | `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.4.0",
+  "version": "2.5.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.5.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.5.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.5.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.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/react:packages/tmdatagrid/docs/scrolling.md'

package/skills/editing/SKILL.md

@@ -6,7 +6,7 @@ description: >
   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,
+  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
@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.4.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/draft-store.md'
@@ -274,6 +274,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

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

@@ -133,7 +133,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

@@ -182,6 +182,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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'

package/src/core/editEngine.ts

@@ -367,6 +367,28 @@ export type TMDataGridEditValueMap = (
   args: TMDataGridEditValueMapArgs,
 ) => unknown;
 
+/** What `meta.edit.mapCommitValue` is handed for one field of a row being committed. */
+export type TMDataGridEditCommitMapArgs = {
+  /** The value the field holds as the row is committed. */
+  value: unknown;
+  /** What the field held when editing began. */
+  previous: unknown;
+  /** The row being committed. `undefined` for a row that is being added. */
+  row: ErasedRow | undefined;
+  column: ErasedColumn;
+  table: TMDataGridTable<TMDataGridRowData>;
+};
+
+/**
+ * `meta.edit.mapCommitValue` - the value as the row commits, mapped.
+ *
+ * Runs once per field, not per keystroke, so the user can type what the
+ * mapped value would not allow, like a trailing space.
+ */
+export type TMDataGridEditCommitMap = (
+  args: TMDataGridEditCommitMapArgs,
+) => unknown;
+
 /**
  * `meta.edit` - everything about how this column is edited, in one place,
  * mirroring the `edit.*` engine the grid exposes at runtime.
@@ -419,6 +441,14 @@ export type TMDataGridColumnEditOptions<
    * {@link TMDataGridEditValueMap}.
    */
   mapValue?: TMDataGridEditValueMap;
+  /**
+   * Maps the value of each field the user changed, once, as its row commits -
+   * trim a string the user was free to type spaces into. It runs before the
+   * validators of the submit, and its result is written back into the form,
+   * so the draft, `changes` and `onCommit` hold the mapped value. See
+   * {@link TMDataGridEditCommitMap}.
+   */
+  mapCommitValue?: TMDataGridEditCommitMap;
 };
 
 /** A new row being committed - `onRowAdd`, and `saveDrafts`'s `created`. */
@@ -1822,7 +1852,64 @@ export function createEditEngine(
     );
   };
 
-  const commit = async (rowId: string): Promise<boolean> => {
+  /**
+   * Runs every `meta.edit.mapCommitValue` over the row's form and writes the
+   * results back. An open row maps the fields the user changed - a value that
+   * was already stored is not the user's to have rewritten; a row being added
+   * has no stored value, so every editable field of it is mapped. A field in
+   * `callerFields` holds a value the caller wrote, not the user, and is left
+   * as written. Written without validation: the submit that follows judges
+   * the mapped values.
+   */
+  const applyCommitMaps = (
+    entry: FormEntry,
+    rowId: string,
+    callerFields: ReadonlySet<string>,
+  ) => {
+    const { table } = getContext();
+    const values = entry.form.state.values as TMDataGridRowData;
+    const changed = entry.isNew
+      ? null
+      : new Set(diff(entry.original, values).map((change) => change.columnId));
+    const row = entry.isNew ? undefined : getRow(rowId);
+    for (const column of editableColumns()) {
+      const map = column.columnDef.meta?.edit?.mapCommitValue;
+      if (map === undefined) continue;
+      if (changed !== null && !changed.has(column.id)) continue;
+      const field = getEditFieldName(column);
+      if (field === null || callerFields.has(field)) continue;
+      const value: unknown = getBy(
+        entry.form.state.values as TMDataGridRowData,
+        field,
+      );
+      const mapped = map({
+        value,
+        previous: getBy(entry.original, field),
+        row,
+        column,
+        table,
+      });
+      if (sameValue(value, mapped)) continue;
+      entry.form.setFieldValue(field as never, mapped as never, {
+        dontValidate: true,
+      });
+    }
+  };
+
+  const commit = (rowId: string): Promise<boolean> =>
+    commitRow(rowId, new Set());
+
+  /**
+   * `callerFields` names the fields a caller wrote itself, which no editor
+   * touched - `writeFields` passes the ones it writes, the rows of
+   * `addRows({ commit: true })` pass `"all"`. They hold stored values already,
+   * as `meta.edit.mapValue` has always assumed, so `mapCommitValue` leaves
+   * them alone; every other field the user changed is still mapped.
+   */
+  const commitRow = async (
+    rowId: string,
+    callerFields: ReadonlySet<string> | "all",
+  ): Promise<boolean> => {
     const entry = forms.get(rowId);
     // No form: the row is committed already, or the grid never held it.
     // Either way there is nothing left to decide.
@@ -1830,6 +1917,9 @@ export function createEditEngine(
     // Enter and blur race on the same edit; the second caller joins the
     // first's commit instead of submitting the row twice.
     if (entry.pendingCommit !== null) return entry.pendingCommit;
+    // Before the pristine check: a value mapped back to the original leaves
+    // nothing to commit.
+    if (callerFields !== "all") applyCommitMaps(entry, rowId, callerFields);
     // A pristine form has nothing to say - drop it without a consumer call.
     // Not for a new row: adding an untouched entry is still an add.
     if (
@@ -2030,10 +2120,14 @@ export function createEditEngine(
       // validate side by side. Out to `onRowAdd`, one at a time and in
       // order, so the consumer sees the rows as the file had them.
       const results = getContext().draft
-        ? await Promise.all(tempIds.map((tempId) => commit(tempId)))
+        ? await Promise.all(
+            tempIds.map((tempId) => commitRow(tempId, "all")),
+          )
         : [];
       if (!getContext().draft) {
-        for (const tempId of tempIds) results.push(await commit(tempId));
+        for (const tempId of tempIds) {
+          results.push(await commitRow(tempId, "all"));
+        }
       }
       return splitCommitted(tempIds, results);
     });
@@ -2382,7 +2476,9 @@ export function createEditEngine(
    * round trip would stall every other row's markers and the caret.
    *
    * No editor is involved, so `meta.edit.mapValue` does not run - the caller
-   * writes the stored value itself. Validation is untouched: this is the same
+   * writes the stored value itself - and `meta.edit.mapCommitValue` skips the
+   * fields written here, while still mapping what the user typed elsewhere in
+   * an open row. Validation is untouched: this is the same
    * `commit`, so `meta.edit.validate` and `editing.rowValidators` still decide
    * whether the row lands, and a failure leaves the row open carrying its
    * errors.
@@ -2400,7 +2496,7 @@ export function createEditEngine(
       for (const { field, value } of writes) {
         entry.form.setFieldValue(field as never, value as never);
       }
-      return commit(rowId);
+      return commitRow(rowId, new Set(writes.map(({ field }) => field)));
     };
     const open = forms.get(rowId);
     if (open !== undefined) return write(open);

package/src/index.ts

@@ -110,6 +110,8 @@ export {
   type TMDataGridEditRowProjection,
   type TMDataGridEditRowSnapshot,
   type TMDataGridEditState,
+  type TMDataGridEditCommitMap,
+  type TMDataGridEditCommitMapArgs,
   type TMDataGridEditValueMap,
   type TMDataGridEditValueMapArgs,
   type TMDataGridFieldValidate,

package/src/useTMDataGrid.tsx

@@ -777,7 +777,7 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * One TanStack Form per editing row; drafts survive scrolling because the
  * forms live outside the DOM, keyed by row id. Which columns edit, and with
  * what, is declared per column under `meta.edit`: `meta.type` picks the
- * built-in editor, and `enabled`, `field`, `editor`, `validate` and `mapValue`
+ * built-in editor, and `enabled`, `field`, `editor`, `validate`, `mapValue` and `mapCommitValue`
  * override the rest.
  */
 export type TMDataGridEditingOptions<TData extends RowData> =