@jielga/tmdatagrid 2.4.0 → 2.6.0

package/src/components/editors/TMDataGridDateEditor.tsx

@@ -1,9 +1,32 @@
-import { TextInput } from "@mantine/core";
+import { TextInput, type TextInputProps } from "@mantine/core";
 import { useRef } from "react";
 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 TMDataGridDateEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `TextInput`. The grid keeps `type`, the value,
+   * `onChange`, `error`, `size` and the accessible name; `onBlur` runs after
+   * the grid's own.
+   */
+  inputProps?: Omit<
+    TextInputProps,
+    | "type"
+    | "value"
+    | "defaultValue"
+    | "onChange"
+    | "error"
+    | "size"
+    | "aria-label"
+  > &
+    EditorDataAttributes;
+};
 
 /**
  * The built-in editor for `meta.type: "date"` - the native
@@ -14,7 +37,8 @@ export function TMDataGridDateEditor({
   field,
   column,
   size,
-}: TMDataGridEditorArgs) {
+  inputProps,
+}: TMDataGridDateEditorProps) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
@@ -32,8 +56,9 @@ export function TMDataGridDateEditor({
 
   return (
     <TextInput
-      size={size}
       w="100%"
+      {...inputProps}
+      size={size}
       type="date"
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
@@ -48,7 +73,10 @@ export function TMDataGridDateEditor({
           writesDates.current ? new Date(`${next}T00:00:00`) : next,
         );
       }}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );

package/src/components/editors/TMDataGridMultiSelectEditor.tsx

@@ -1,4 +1,4 @@
-import { MultiSelect } from "@mantine/core";
+import { MultiSelect, type MultiSelectProps } from "@mantine/core";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import {
   optionsToComboboxData,
@@ -6,7 +6,35 @@ import {
 } from "../../core/columnOptions";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldInvalid, useFieldValue } from "./editorShared";
+import {
+  useFieldInvalid,
+  useFieldValue,
+  type EditorDataAttributes,
+} from "./editorShared";
+
+export type TMDataGridMultiSelectEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `MultiSelect`. The grid keeps `data`, the value,
+   * `onChange`, `error`, `size`, the accessible name and
+   * `comboboxProps.withinPortal`; `onBlur` runs after the grid's own.
+   */
+  inputProps?: Omit<
+    MultiSelectProps,
+    | "data"
+    | "value"
+    | "defaultValue"
+    | "onChange"
+    | "error"
+    | "size"
+    | "aria-label"
+    | "comboboxProps"
+  > & {
+    comboboxProps?: Omit<
+      NonNullable<MultiSelectProps["comboboxProps"]>,
+      "withinPortal"
+    >;
+  } & EditorDataAttributes;
+};
 
 /**
  * The built-in editor for `meta.type: "multiSelect"` - cells holding string
@@ -19,16 +47,18 @@ export function TMDataGridMultiSelectEditor({
   row,
   table,
   size,
-}: TMDataGridEditorArgs) {
+  inputProps,
+}: TMDataGridMultiSelectEditorProps) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
   return (
     <MultiSelect
-      size={size}
       w="100%"
       searchable
-      comboboxProps={{ withinPortal: false }}
+      {...inputProps}
+      size={size}
+      comboboxProps={{ ...inputProps?.comboboxProps, withinPortal: false }}
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
       data={optionsToComboboxData(
@@ -36,7 +66,10 @@ export function TMDataGridMultiSelectEditor({
       )}
       value={Array.isArray(value) ? value.map(String) : []}
       onChange={(next) => field.handleChange(next)}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );

package/src/components/editors/TMDataGridNumberEditor.tsx

@@ -1,17 +1,37 @@
-import { NumberInput } from "@mantine/core";
+import { NumberInput, type NumberInputProps } from "@mantine/core";
 import { useState } from "react";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
 import {
+  mergeRefs,
   selectAllOnFocus,
   useCaretKeeper,
   useFieldInvalid,
   useFieldValue,
+  type EditorDataAttributes,
 } from "./editorShared";
 
+export type TMDataGridNumberEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `NumberInput`. The grid keeps the value, `onChange`,
+   * `error`, `size` and the accessible name; `onFocus` and `onBlur` run after
+   * the grid's own, and `ref` receives the input beside the grid's ref.
+   */
+  inputProps?: Omit<
+    NumberInputProps,
+    "value" | "defaultValue" | "onChange" | "error" | "size" | "aria-label"
+  > &
+    EditorDataAttributes;
+};
+
 /** The built-in editor for `meta.type: "number"`. */
-export function TMDataGridNumberEditor({ field, column, size }: TMDataGridEditorArgs) {
+export function TMDataGridNumberEditor({
+  field,
+  column,
+  size,
+  inputProps,
+}: TMDataGridNumberEditorProps) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
@@ -31,11 +51,15 @@ export function TMDataGridNumberEditor({ field, column, size }: TMDataGridEditor
     : value === null;
   return (
     <NumberInput
-      ref={inputRef}
-      size={size}
       w="100%"
-      onFocus={selectAllOnFocus}
       hideControls
+      {...inputProps}
+      ref={mergeRefs(inputRef, inputProps?.ref)}
+      size={size}
+      onFocus={(event) => {
+        selectAllOnFocus(event);
+        inputProps?.onFocus?.(event);
+      }}
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
       value={
@@ -63,7 +87,10 @@ export function TMDataGridNumberEditor({ field, column, size }: TMDataGridEditor
           next !== "" && Number.isFinite(parsed) ? parsed : null,
         );
       }}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );

package/src/components/editors/TMDataGridSelectEditor.tsx

@@ -1,4 +1,4 @@
-import { Select } from "@mantine/core";
+import { Select, type SelectProps } from "@mantine/core";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import {
   optionsToComboboxData,
@@ -6,7 +6,35 @@ import {
 } from "../../core/columnOptions";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldInvalid, useFieldValue } from "./editorShared";
+import {
+  useFieldInvalid,
+  useFieldValue,
+  type EditorDataAttributes,
+} from "./editorShared";
+
+export type TMDataGridSelectEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `Select`. The grid keeps `data`, the value,
+   * `onChange`, `error`, `size`, the accessible name and
+   * `comboboxProps.withinPortal`; `onBlur` runs after the grid's own.
+   */
+  inputProps?: Omit<
+    SelectProps,
+    | "data"
+    | "value"
+    | "defaultValue"
+    | "onChange"
+    | "error"
+    | "size"
+    | "aria-label"
+    | "comboboxProps"
+  > & {
+    comboboxProps?: Omit<
+      NonNullable<SelectProps["comboboxProps"]>,
+      "withinPortal"
+    >;
+  } & EditorDataAttributes;
+};
 
 /**
  * The built-in editor for `meta.type: "select"`. Options come from the same
@@ -20,18 +48,20 @@ export function TMDataGridSelectEditor({
   table,
   size,
   commit,
-}: TMDataGridEditorArgs) {
+  inputProps,
+}: TMDataGridSelectEditorProps) {
   const { labels, features } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
   return (
     <Select
-      size={size}
       w="100%"
       searchable
+      {...inputProps}
+      size={size}
       // Inside the cell, so picking an option is not a click-away - the same
       // reason the filter panel keeps its dropdowns unportalled.
-      comboboxProps={{ withinPortal: false }}
+      comboboxProps={{ ...inputProps?.comboboxProps, withinPortal: false }}
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
       data={optionsToComboboxData(
@@ -44,7 +74,10 @@ export function TMDataGridSelectEditor({
         // The confirming modes leave the draft for their explicit commit.
         if (next !== null && features.editMode === "cell") void commit();
       }}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );

package/src/components/editors/TMDataGridStringEditor.tsx

@@ -1,26 +1,50 @@
-import { TextInput } from "@mantine/core";
+import { TextInput, type TextInputProps } from "@mantine/core";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
 import {
+  mergeRefs,
   selectAllOnFocus,
   useCaretKeeper,
   useFieldInvalid,
   useFieldValue,
+  type EditorDataAttributes,
 } from "./editorShared";
 
+export type TMDataGridStringEditorProps = TMDataGridEditorArgs & {
+  /**
+   * Props for the Mantine `TextInput`. The grid keeps the value, `onChange`,
+   * `error`, `size` and the accessible name; `onFocus` and `onBlur` run after
+   * the grid's own, and `ref` receives the input beside the grid's ref.
+   */
+  inputProps?: Omit<
+    TextInputProps,
+    "value" | "defaultValue" | "onChange" | "error" | "size" | "aria-label"
+  > &
+    EditorDataAttributes;
+};
+
 /** The built-in editor for `meta.type: "string"` (and the default). */
-export function TMDataGridStringEditor({ field, column, size }: TMDataGridEditorArgs) {
+export function TMDataGridStringEditor({
+  field,
+  column,
+  size,
+  inputProps,
+}: TMDataGridStringEditorProps) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
   const invalid = useFieldInvalid(field);
   const { inputRef, remember } = useCaretKeeper();
   return (
     <TextInput
-      ref={inputRef}
-      size={size}
       w="100%"
-      onFocus={selectAllOnFocus}
+      {...inputProps}
+      ref={mergeRefs(inputRef, inputProps?.ref)}
+      size={size}
+      onFocus={(event) => {
+        selectAllOnFocus(event);
+        inputProps?.onFocus?.(event);
+      }}
       aria-label={labels.editCell(getColumnLabel(column))}
       data-dg-part="editor-input"
       value={typeof value === "string" ? value : ""}
@@ -28,7 +52,10 @@ export function TMDataGridStringEditor({ field, column, size }: TMDataGridEditor
         remember(event.currentTarget);
         field.handleChange(event.currentTarget.value);
       }}
-      onBlur={field.handleBlur}
+      onBlur={(event) => {
+        field.handleBlur();
+        inputProps?.onBlur?.(event);
+      }}
       error={invalid}
     />
   );

package/src/components/editors/editorShared.ts

@@ -1,8 +1,34 @@
 import { useStore } from "@tanstack/react-form";
-import { useLayoutEffect, useRef, type RefObject } from "react";
+import {
+  useLayoutEffect,
+  useRef,
+  type Ref,
+  type RefCallback,
+  type RefObject,
+} from "react";
 import { isInputElement } from "../../core/dom";
 import { firstErrorText, type TMDataGridEditField } from "../../core/editEngine";
 
+/**
+ * `data-*` attributes for a built-in editor's `inputProps`. JSX accepts them
+ * on any element, but a props object literal only takes declared keys.
+ */
+export type EditorDataAttributes = {
+  [attribute: `data-${string}`]: string | number | boolean | undefined;
+};
+
+/** One ref callback feeding the grid's own ref and the consumer's. */
+export function mergeRefs<T>(
+  ...refs: Array<Ref<T> | undefined>
+): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(node);
+      else if (ref !== null && ref !== undefined) ref.current = node;
+    }
+  };
+}
+
 /** The field's live value - one subscription, on the field's own store. */
 export function useFieldValue(field: TMDataGridEditField): unknown {
   return useStore(field.store, (state) => state.value as unknown);

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,
@@ -141,12 +143,30 @@ export { DgRangeSliderFilter } from "./components/filters/DgRangeSliderFilter";
 export { DgDateRangeFilter } from "./components/filters/DgDateRangeFilter";
 export { DgAutocompleteFilter } from "./components/filters/DgAutocompleteFilter";
 export { DgTriStateFilter } from "./components/filters/DgTriStateFilter";
-export { TMDataGridStringEditor } from "./components/editors/TMDataGridStringEditor";
-export { TMDataGridNumberEditor } from "./components/editors/TMDataGridNumberEditor";
-export { TMDataGridBooleanEditor } from "./components/editors/TMDataGridBooleanEditor";
-export { TMDataGridDateEditor } from "./components/editors/TMDataGridDateEditor";
-export { TMDataGridSelectEditor } from "./components/editors/TMDataGridSelectEditor";
-export { TMDataGridMultiSelectEditor } from "./components/editors/TMDataGridMultiSelectEditor";
+export {
+  TMDataGridStringEditor,
+  type TMDataGridStringEditorProps,
+} from "./components/editors/TMDataGridStringEditor";
+export {
+  TMDataGridNumberEditor,
+  type TMDataGridNumberEditorProps,
+} from "./components/editors/TMDataGridNumberEditor";
+export {
+  TMDataGridBooleanEditor,
+  type TMDataGridBooleanEditorProps,
+} from "./components/editors/TMDataGridBooleanEditor";
+export {
+  TMDataGridDateEditor,
+  type TMDataGridDateEditorProps,
+} from "./components/editors/TMDataGridDateEditor";
+export {
+  TMDataGridSelectEditor,
+  type TMDataGridSelectEditorProps,
+} from "./components/editors/TMDataGridSelectEditor";
+export {
+  TMDataGridMultiSelectEditor,
+  type TMDataGridMultiSelectEditorProps,
+} from "./components/editors/TMDataGridMultiSelectEditor";
 export {
   mergeLabels,
   TMDATAGRID_LABELS_EN,

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> =