@jielga/tmdatagrid 2.3.0 → 2.5.0

package/docs/columns.md

@@ -47,6 +47,13 @@ addresses the column by id - `initialState`, `editing.columns`, `moveColumn`,
 a test selector - takes the underscore form; the dotted form silently matches
 nothing.
 
+Each column the helper returns also carries, in its type only, its id,
+`meta.type`, value type, `meta.filter.operators`, and its `enableColumnFilter`,
+`enableSorting` and `meta.filter.url` switches.
+[Typed links](/docs/persistence#typed-links) read them, so a link into the grid
+can name only the filters and sorts its columns offer.
+Only literal values count: `enableSorting: isAdmin` reads as not sortable.
+
 ### Columns derived from the other rows
 
 `accessorFn` is handed one row, so a value that depends on the rest - a share
@@ -118,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/docs/filtering.md

@@ -206,6 +206,7 @@ file: columns/FilterPanelPlaced.tsx
 ## TMDataGrid.FilterPills
 
 One pill per active filter - `First name: Sofia ✕` - where the ✕ clears that filter and a click on the label sends the user to that column's control through [openColumnFilter](#opencolumnfilter).
+A value with an option reads as the option's label, and a boolean value as `labels.booleanTrue` or `labels.booleanFalse`.
 Half-typed filters produce no pill.
 The label spells the operator out unless it is the column type's default: `Age is greater than 30`, but `First name: Sofia`.
 
@@ -447,7 +448,7 @@ stays, empty.
 | `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | The list one column offers after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
 | `TMDataGridFilterValueInput` | Export | component | – | The default value control, for falling back to. |
-| `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
+| `formatFilterLabel` | Export | `({ label, type, filter, operatorLabels?, options?, labels? }) => string` | – | The one-line description used on the pills. `operatorLabels` names the operators, `options` gives a value its option's label, and `labels` gives a boolean its `booleanTrue` / `booleanFalse`; each defaults to English or to the value itself. |
 | `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` · `filterValueShape` | Exports | – | – | What shape of value an operator expects. |
 | `TMDataGridFilterValueShape` | Type | `"scalar" \| "set" \| "range"` | – | What `filterValueShape` returns for an operator. |
 | `TMDataGridFiltersOptions` · `TMDataGridFiltersSettings` · `TMDataGridFilterSurface` · `TMDataGridFilterSidebarSide` | Types | – | – | The `filters` option, and the resolved form of it on `api.filters`. |

package/docs/grouping.md

@@ -160,7 +160,7 @@ server-side can set `enableGrouping: true` alongside `manualGrouping: true`. See
 | `aggregationFn` | Column option | `TMDataGridAggregationName \| fn` | – | How a column fills in its group cells. Unset leaves them blank. |
 | `aggregatedCell` | Column option | `(ctx) => ReactNode` | `cell` over the aggregate when `aggregationFn` is set, else blank | Renders a group row's value differently from a data row's. |
 | `GROUP_COLUMN_ID` | Export | `"__group__"` | – | Id of the generated tree column. |
-| `formatGroupValue` | Export | `(value) => string` | – | How the tree lane renders a group's value. |
+| `formatGroupValue` | Export | `(value, blankLabel?, { type?, options?, labels? }?) => string` | – | How the tree lane writes a group's value: `blankLabel` for an empty value, an option's label for a value with an option, `labels.booleanTrue` / `booleanFalse` for a boolean, and `toLocaleDateString()` for a `Date`. |
 | `getGroupDataRows` | Export | `(row) => Row[]` | – | Every record under a group row, at any depth. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
 | `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |

package/docs/localization.md

@@ -111,8 +111,8 @@ shows it; a function label shows its template:
 | `filterFrom` | `From` | The lower bound of a `between` filter: its input, or its slider thumb. |
 | `filterTo` | `To` | The upper bound of a `between` filter: its input, or its slider thumb. |
 | `filterAll` | `All` | The no-filter segment of the tri-state filter. |
-| `booleanTrue` | `Yes` | The `true` choice of a boolean filter value control and of the tri-state filter. |
-| `booleanFalse` | `No` | The `false` choice of a boolean filter value control and of the tri-state filter. |
+| `booleanTrue` | `Yes` | The `true` choice of a boolean filter value control and of the tri-state filter, and a `true` value on a filter pill and in a group row. |
+| `booleanFalse` | `No` | The `false` choice of a boolean filter value control and of the tri-state filter, and a `false` value on a filter pill and in a group row. |
 | `addFilter` | `Add filter` | Button in `TMDataGrid.FilterPanel`. |
 | `clearAllFilters` | `Clear all` | Button in `TMDataGrid.FilterPanel` and in `TMDataGrid.FilterPills`. |
 | `closeFilters` | `Close filters` | `aria-label` of the close button of the filter popup and sidebar. |
@@ -134,7 +134,7 @@ shows it; a function label shows its template:
 | `moveRight` | `Move right` | Column menu item. |
 | `autosizeColumn` | `Autosize column` | Column menu item. |
 | `hideColumn` | `Hide column` | Column menu item. |
-| `filterOn` | `` `Filter on ${column}` `` | `aria-label` of the header filter button, of a header filter cell, and of the value control in it. |
+| `filterOn` | `` `Filter on ${column}` `` | `aria-label` of the header filter button, of the header filter cell of a column that can filter, and of the value control in it. |
 | `sortColumn` | `` `Sort ${column}` `` | `aria-label` of the header sort button. |
 | `columnMenu` | `` `${column} column menu` `` | `aria-label` of the column menu trigger. |
 | `rowsPerPage` | `Rows per page:` | `TMDataGrid.Footer`: the text before the page size select. |

package/docs/persistence.md

@@ -116,6 +116,55 @@ The column's filter is then not persisted anywhere. A filter on it in
 `initialState` still applies when a link is opened. The flag has no effect
 unless `urlKey` carries `columnFilters`.
 
+### Typed links
+
+`createTMDataGridUrlState` defines a grid's deep links from its columns.
+Pass it the array the grid renders, built with `createTMDataGridColumnHelper`:
+
+```tsx
+const columns = columnHelper.columns([
+  columnHelper.accessor("department", { header: "Department", meta: { type: "select" } }),
+  columnHelper.accessor("salary", { header: "Salary", meta: { type: "number" } }),
+  columnHelper.accessor("email", { header: "Email", enableColumnFilter: false }),
+]);
+
+export const employeesUrl = createTMDataGridUrlState({
+  key: "employees",
+  columns,
+  slices: ["columnFilters", "sorting"],
+});
+
+// The grid
+const persist = { urlKey: employeesUrl.urlKey } satisfies TMDataGridPersistence;
+
+// A link from anywhere in the app
+const href = `/employees?${employeesUrl.searchParams({
+  filters: { department: { operator: "isAnyOf", value: ["Design"] } },
+  sorting: [{ id: "salary", desc: true }],
+})}`;
+```
+
+A link may name only what the grid's columns offer:
+
+- `filters` takes the columns that can be filtered: `enableColumnFilter` is not `false` and `meta.filter.url` is not `false`.
+- The operators are the ones the column's `meta.type` offers, narrowed by `meta.filter.operators`.
+- The value has the column's type: a `number` for a number column, a `Date` or a `YYYY-MM-DD` string for a date column, the column's own values for a select column, and no value for `isEmpty` and `isNotEmpty`.
+- `sorting` takes the columns whose `enableSorting` is not `false`.
+- Only the slices in `slices` are accepted. By default, every data slice is.
+
+Anything else is a type error.
+The column helper reads these switches from literal values, so `enableSorting: isAdmin` reads as not sortable.
+A column with an accessor function is named by its `id`; without an `id` it cannot be named.
+Columns built without the helper offer nothing to a link.
+
+The definition builds the link in three forms:
+
+- `searchParams(input)` - `URLSearchParams` for a plain URL, encoded the way the default `serialize` encodes the param
+- `search(input)` - `{ [key]: payload }`, for a router that keeps objects in its search
+- `payload(input)` - the param's value alone, in the grid's state shape
+
+Pass `searchParams` the same `serialize` as `persist` when you set one.
+
 ### Routers that own the URL
 
 `urlStorage` replaces the default read and write of the param, for a router
@@ -152,6 +201,31 @@ const persist = useMemo(
 );
 ```
 
+A router that keeps objects in its search params and encodes them itself,
+such as TanStack Router, takes the payload as an object.
+Pass its search to `persist` on a typed link definition:
+
+```tsx
+const router = useRouter();
+const persist = useMemo(
+  () =>
+    employeesUrl.persist({
+      get: (name) => (router.state.location.search as Record<string, unknown>)[name],
+      set: (name, value) =>
+        void router.navigate({
+          to: ".",
+          search: (prev: Record<string, unknown>) => ({ ...prev, [name]: value }),
+          replace: true,
+        }),
+    }),
+  [router],
+);
+```
+
+`get` returns the param's value, or `undefined`; `set` receives the payload, or `undefined` to remove the param.
+Leave `serialize` and `deserialize` at their defaults with `persist(storage)`, since the router does the encoding.
+[Typed links with TanStack Router](/docs/typed-deep-links) puts the route, the grid and the links together.
+
 ## Behaviour
 
 **Restoring happens once**, on mount, through `initialState`. Writing is a
@@ -201,6 +275,20 @@ its `StorageType`.
 | `urlKey` | persist field | `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](#deep-links). |
 | `urlStorage` | persist field | `TMDataGridUrlStorage` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `TMDataGridUrlStorage` | Type | `{ get(name): string \| null; set(name, value: string \| null): void }` | – | The type of `urlStorage`. |
+| `createTMDataGridUrlState` | Export | `({ key, columns, slices? }) => TMDataGridUrlState` | – | Defines typed links into the grid from its columns. See [Typed links](#typed-links). |
+| `key` | Definition field | `string` | – | The URL search param. |
+| `slices` | Definition field | `TMDataGridDataSlice[]` | Every data slice | The data slices the param carries. |
+| `urlKey` | Definition field | `TMDataGridPersistKey` | – | For `persist.urlKey`: the key, or `[key, slices]` when `slices` is set. |
+| `searchParams` | Definition method | `(input, { serialize? }) => URLSearchParams` | `serialize`: `JSON.stringify` | The link as search params. Empty when the input sets nothing. |
+| `search` | Definition method | `(input) => { [key]: TMDataGridUrlPayload \| undefined }` | – | The link as a router search object. |
+| `payload` | Definition method | `(input) => TMDataGridUrlPayload \| undefined` | – | The param's value, or `undefined` when the input sets nothing. |
+| `validateSearch` | Definition method | `(search) => { [key]?: TMDataGridUrlPayload }` | – | A route search validator. Keeps the param when it is an object. |
+| `persist` | Definition method | `(storage?: TMDataGridUrlSearchStorage) => { urlKey, urlStorage? }` | – | Spread into `persist`. If not given a storage, the grid uses the browser's URL. |
+| `TMDataGridUrlInput` | Type | `{ filters?, globalFilter?, sorting?, pagination? }` | – | What a link may set, typed from the columns and `slices`. |
+| `TMDataGridUrlPayload` | Type | `{ columnFilters?, globalFilter?, sorting?, pagination?, expanded? }` | – | The param's value, in the grid's state shape. |
+| `TMDataGridUrlSearchStorage` | Type | `{ get(name): unknown; set(name, value: TMDataGridUrlPayload \| undefined): void }` | – | A router search read and written as values. |
+| `TMDataGridColumnInfo` · `TMDataGridColumnInfoOf` · `TMDataGridTypedColumn` | Types | – | – | What a helper column tells a link about itself: id, type, value, operators, and its filter, sort and URL switches. |
+| `TMDataGridUrlFiltersInput` · `TMDataGridUrlSortableId` · `TMDataGridDateInput` | Types | – | – | The parts of `TMDataGridUrlInput`. |
 | `meta.filter.url` | Column meta | `boolean` | `true` | Determines whether the column's filter is written to the URL under `urlKey`. |
 | `TMDataGridPersistKey` | Type | `string \| [string, slices]` | – | The type of `dataKey`, `settingsKey` and `urlKey`. |
 | `storageMode` | persist field | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |

package/docs/typed-deep-links.md

@@ -0,0 +1,169 @@
+# Typed links with TanStack Router
+
+Links into a grid, built from the grid's own columns and checked by both the grid's types and the router's.
+The grid's URL param lives in the router's search, and the router encodes it.
+
+```demo
+file: recipes/RouterDeepLinks.tsx
+hint: Go to Links and open one. Change a filter or the search, and watch the address follow.
+extraSources: data/employeeLinks.tsx, data/EmployeeLinksGrid.tsx
+height: 640
+```
+
+## Define the links from the columns
+
+Build the columns with `createTMDataGridColumnHelper`, and pass the same array to `createTMDataGridUrlState`:
+
+```tsx
+export const employeesLink = createTMDataGridUrlState({
+  key: "emp",
+  columns: employeeLinkColumns,
+  slices: ["columnFilters", "globalFilter", "sorting"],
+});
+```
+
+The columns decide what a link may name.
+In this demo, `location` sets `meta.filter.url: false`, so no link can filter it.
+[Typed links](/docs/persistence#typed-links) lists the rules.
+
+## Validate the route's search
+
+Pass the definition's `validateSearch` to the route that renders the grid:
+
+```tsx
+const employeesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/employees",
+  validateSearch: employeesLink.validateSearch,
+  component: EmployeesPage,
+});
+```
+
+A route with search params of its own spreads it into its validator:
+
+```tsx
+validateSearch: (search) => ({
+  ...employeesLink.validateSearch(search),
+  tab: search.tab === "chart" ? "chart" : "table",
+}),
+```
+
+## Keep the grid's param in the router
+
+Pass the router's search to the definition's `persist`:
+
+```tsx
+const router = useRouter();
+const persist = useMemo(
+  () =>
+    employeesLink.persist({
+      get: (name) => (router.state.location.search as Record<string, unknown>)[name],
+      set: (name, value) =>
+        void router.navigate({
+          to: ".",
+          search: (prev: Record<string, unknown>) => ({ ...prev, [name]: value }),
+          replace: true,
+        }),
+    }),
+  [router],
+);
+```
+
+The grid writes through `router.navigate`, so the router sees every change.
+`replace: true` keeps a filter change out of the history, as the grid's own URL writes do.
+With `createHashHistory()`, the param is written after the `#`, with the rest of the router's search.
+
+## Link into the grid
+
+Pass `search` to the link:
+
+```tsx
+<Link
+  to="/employees"
+  search={employeesLink.search({
+    filters: {
+      salary: { operator: "between", value: [40_000, 60_000] },
+      status: { operator: "isAnyOf", value: ["Active"] },
+    },
+    sorting: [{ id: "salary", desc: true }],
+  })}
+>
+  Active, highest salary first
+</Link>
+```
+
+`search` fails to compile on a column the grid does not have, an operator the column does not offer, or a value of the wrong type.
+The router then checks the result against the route's search.
+
+## Readable URLs
+
+By default, TanStack Router writes the param as JSON and escapes it with `URLSearchParams`, so every brace and quote is percent-escaped.
+To write it readable, encode the values with [JSURL2](https://github.com/wmertens/jsurl2) and escape them with `encodeURIComponent`, which leaves JSURL2's `(`, `)`, `~` and `!` as they are:
+
+```tsx
+import { parse, stringify } from "jsurl2";
+
+function toSearchValue(value: unknown): string {
+  if (typeof value === "object" && value !== null) return stringify(value);
+  if (typeof value !== "string") return String(value);
+  try {
+    parse(value);
+    return stringify(value);
+  } catch {
+    return value;
+  }
+}
+
+function stringifySearch(search: Record<string, unknown>): string {
+  const pairs = Object.entries(search).flatMap(([key, value]) =>
+    value === undefined
+      ? []
+      : [`${encodeURIComponent(key)}=${encodeURIComponent(toSearchValue(value))}`],
+  );
+  return pairs.length === 0 ? "" : `?${pairs.join("&")}`;
+}
+
+const router = createRouter({
+  routeTree,
+  parseSearch: parseSearchWith(parse),
+  stringifySearch,
+});
+```
+
+TanStack Router's own `stringifySearchWith(stringify)` encodes the values as JSURL2 too, but its `URLSearchParams` escapes JSURL2's delimiters again.
+
+```demo
+file: recipes/ReadableSearch.tsx
+hint: The same links as above. Compare the two addresses.
+extraSources: data/employeeLinks.tsx, data/EmployeeLinksGrid.tsx
+height: 600
+```
+
+The serializer applies to every route, and the grid is unaffected.
+JSURL2's `parse` also reads JSON, so a link written before the switch still opens.
+
+## Links without a router
+
+Without a router, leave out the storage: the grid reads and writes the browser's URL.
+Build a link with `searchParams`:
+
+```tsx
+const persist = employeesLink.persist();
+
+const href = `/employees?${employeesLink.searchParams({
+  filters: { department: { operator: "isAnyOf", value: ["Design"] } },
+})}`;
+```
+
+```demo
+file: recipes/PlainLinks.tsx
+hint: Each link loads this page with the grid's param set.
+extraSources: data/employeeLinks.tsx
+height: 560
+```
+
+## Links to the page the grid is on
+
+The grid reads its param once, when it mounts.
+Note that a link to the route the grid is already on changes the URL but not the grid.
+Link to such a route from another route, or remount the grid on the navigation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.3.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.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/styling.md'
   - 'Jielga/react:packages/tmdatagrid/docs/toolbar.md'

package/skills/appearance/references/labels.md

@@ -44,8 +44,8 @@ The `labels` option takes a partial override, `TMDataGridLabelsOverride`, merged
 | `filterFrom` | `From` | The lower bound of a `between` filter: its input, or its slider thumb. |
 | `filterTo` | `To` | The upper bound of a `between` filter: its input, or its slider thumb. |
 | `filterAll` | `All` | The no-filter segment of the tri-state filter. |
-| `booleanTrue` | `Yes` | The `true` choice of a boolean filter value control and of the tri-state filter. |
-| `booleanFalse` | `No` | The `false` choice of a boolean filter value control and of the tri-state filter. |
+| `booleanTrue` | `Yes` | The `true` choice of a boolean filter value control and of the tri-state filter, and a `true` value on a filter pill and in a group row. |
+| `booleanFalse` | `No` | The `false` choice of a boolean filter value control and of the tri-state filter, and a `false` value on a filter pill and in a group row. |
 | `addFilter` | `Add filter` | Button in `TMDataGrid.FilterPanel`. |
 | `clearAllFilters` | `Clear all` | Button in `TMDataGrid.FilterPanel` and in `TMDataGrid.FilterPills`. |
 | `closeFilters` | `Close filters` | `aria-label` of the close button of the filter popup and sidebar. |
@@ -67,7 +67,7 @@ The `labels` option takes a partial override, `TMDataGridLabelsOverride`, merged
 | `moveRight` | `Move right` | Column menu item. |
 | `autosizeColumn` | `Autosize column` | Column menu item. |
 | `hideColumn` | `Hide column` | Column menu item. |
-| `filterOn` | `` `Filter on ${column}` `` | `aria-label` of the header filter button, of a header filter cell, and of the value control in it. |
+| `filterOn` | `` `Filter on ${column}` `` | `aria-label` of the header filter button, of the header filter cell of a column that can filter, and of the value control in it. |
 | `sortColumn` | `` `Sort ${column}` `` | `aria-label` of the header sort button. |
 | `columnMenu` | `` `${column} column menu` `` | `aria-label` of the column menu trigger. |
 | `rowsPerPage` | `Rows per page:` | `TMDataGrid.Footer`: the text before the page size select. |

package/skills/cell-selection/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.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.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/columns.md'
   - 'Jielga/react:packages/tmdatagrid/docs/column-layout.md'
@@ -61,6 +61,9 @@ replaces the dots: `accessorKey: "address.city"` makes column id
 addresses the column by id - `initialState`, `editing.columns`, `moveColumn`,
 a test selector - takes the underscore form.
 
+Helper columns, groups included, carry their id, `meta.type`, value type, `meta.filter.operators` and filter, sort and URL switches in their type (`TMDataGridColumnInfo`).
+`createTMDataGridUrlState` (the `options` skill) reads them to type deep links; only literal values count.
+
 `columnHelper.group` nests columns under a shared header; `columns` takes
 another `columnHelper.columns` call, not a bare array:
 
@@ -95,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.3.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.3.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.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/react:packages/tmdatagrid/docs/quick-search.md'
@@ -197,6 +197,7 @@ No props.
 
 One pill per **active** filter, `First name: Sofia ✕`, where the ✕ clears it and a click on the label calls `openColumnFilter`.
 The label spells the operator out unless it is the type's default: `Age is greater than 30`, but `First name: Sofia`.
+A value with an option reads as the option's label, and a boolean value as `labels.booleanTrue` or `labels.booleanFalse`.
 It takes the grid as an `api` prop instead of reading context, so it renders anywhere on the page.
 
 ```tsx
@@ -481,7 +482,7 @@ Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
 | `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | One column's list after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
-| `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
+| `formatFilterLabel` | Export | `({ label, type, filter, operatorLabels?, options?, labels? }) => string` | – | The one-line description used on the pills. `operatorLabels` names the operators, `options` gives a value its option's label, and `labels` gives a boolean its `booleanTrue` / `booleanFalse`; each defaults to English or to the value itself. |
 | `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator expects. |
 | `TMDataGridFilterValueInput` | Export | component | – | The default value control, for falling back to. |
 | `DgRangeSliderFilter` · `DgDateRangeFilter` · `DgAutocompleteFilter` · `DgTriStateFilter` | Exports | components | – | The four ready-made controls. |

package/skills/getting-started/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/react:packages/tmdatagrid/docs/anatomy.md'
@@ -355,7 +355,7 @@ Source: `packages/tmdatagrid/docs/card-view.md`,
 | `openColumnFilter(api, columnId)` | Adds an empty filter for a column and opens the panel. |
 | `getColumnLabel(column)` | `meta.label`, a string header, or the column id. |
 | `getColumnType(column)` | `meta.type`, defaulting to `"string"`. |
-| `formatFilterLabel({ label, type, filter })` | The one-line filter description used on the pills. |
+| `formatFilterLabel({ label, type, filter, operatorLabels?, options?, labels? })` | The one-line filter description used on the pills. |
 | `moveColumn({ table, columnId, targetId, side })` | Moves a column next to another. See the `columns` skill. |
 | `moveColumnByStep({ table, columnId, direction })` | Moves a column one position within its region. |
 | `SELECT_COLUMN_ID` | Id of the generated checkbox column. |

package/skills/grouping/SKILL.md

@@ -14,7 +14,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/grouping.md'
   - 'Jielga/react:packages/tmdatagrid/docs/summary-row.md'
@@ -275,7 +275,7 @@ Source: `packages/tmdatagrid/docs/grouping.md` (Server-side grids).
 | `aggregateColumn` | Export | `({ table, columnId, fn }) => unknown` | `fn: "sum"` | Aggregates over every filtered row, all pages. |
 | `TMDataGridAggregationName` | Export | type | – | The registered function names. |
 | `GROUP_COLUMN_ID` | Export | `"__group__"` | – | Id of the generated tree column. |
-| `formatGroupValue` | Export | `(value) => string` | – | How the tree lane renders a group's value. |
+| `formatGroupValue` | Export | `(value, blankLabel?, { type?, options?, labels? }?) => string` | – | How the tree lane writes a group's value: `blankLabel` for an empty value, an option's label for a value with an option, `labels.booleanTrue` / `booleanFalse` for a boolean, and `toLocaleDateString()` for a `Date`. |
 | `getGroupDataRows` | Export | `(row) => Row[]` | – | Every record under a group row, at any depth. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
 | `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |