@jielga/tmdatagrid 2.3.0 → 2.5.0

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

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: lifecycle
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.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

@@ -10,20 +10,22 @@ description: >
   enablePagination, resetPageOnQueryChange, enableRowNumbers, selectionMode,
   showSelectedBackground, cellSelection, renderDetails, overscan,
   quickSearchMode), persist with dataKey/settingsKey slices, storageMode and
-  urlKey deep links, the returned api (table, ui, edit, features, labels,
-  resetSettings, scrollToRow), ui actions, and reading grid state with
-  useSelector over table.store, since table.getState() does not exist in v9.
-  Load when configuring the hook, looking up an option's default, persisting
-  layout or filters, or reacting to grid state from a parent.
+  urlKey and createTMDataGridUrlState deep links, the returned api (table, ui,
+  edit, features, labels, resetSettings, scrollToRow), ui actions, and reading
+  grid state with useSelector over table.store, since table.getState() does not
+  exist in v9. Load when configuring the hook, looking up an option's default,
+  persisting layout or filters, or reacting to grid state from a parent.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/use-tm-data-grid.md'
   - 'Jielga/react:packages/tmdatagrid/docs/persistence.md'
+  - 'Jielga/react:packages/tmdatagrid/docs/typed-deep-links.md'
   - 'Jielga/react:packages/tmdatagrid/src/useTMDataGrid.tsx'
   - 'Jielga/react:packages/tmdatagrid/src/core/persistence.ts'
+  - 'Jielga/react:packages/tmdatagrid/src/core/urlState.ts'
 ---
 
 # TMDataGrid - useTMDataGrid
@@ -298,6 +300,28 @@ const persist = useMemo(
 
 Source: `packages/tmdatagrid/docs/persistence.md` (Deep links).
 
+### Typed links
+
+`createTMDataGridUrlState({ key, columns, slices? })` defines a grid's deep
+links from the columns the grid renders, built with
+`createTMDataGridColumnHelper`. A link can name only the filters, operators,
+values and sorts those columns offer; anything else is a type error. The
+definition gives `urlKey` for `persist`, the link as `searchParams`, `search`
+or `payload`, a route `validateSearch`, and `persist(storage?)`, which keeps
+the param in a router's search such as TanStack Router's.
+
+```tsx
+export const employeesUrl = createTMDataGridUrlState({ key: "employees", columns });
+
+const persist = { urlKey: employeesUrl.urlKey } satisfies TMDataGridPersistence;
+const href = `/employees?${employeesUrl.searchParams({
+  filters: { department: { operator: "isAnyOf", value: ["Design"] } },
+})}`;
+```
+
+Every rule, every member and the TanStack Router setup are in
+[references/typed-links.md](references/typed-links.md).
+
 ## Return value
 
 | Field | Type | Description |

package/skills/options/references/typed-links.md

@@ -0,0 +1,134 @@
+# Typed links
+
+Reference for the `options` skill: `createTMDataGridUrlState`, what a link
+may name, the definition's members, and the TanStack Router setup.
+
+`createTMDataGridUrlState({ key, columns, slices? })` defines a grid's deep
+links from its columns. `columns` is the array the grid renders, built with
+`createTMDataGridColumnHelper`; each helper column carries its id, `meta.type`,
+value type, `meta.filter.operators` and its `enableColumnFilter`,
+`enableSorting` and `meta.filter.url` switches in its type only
+(`TMDataGridColumnInfo`, read with `TMDataGridColumnInfoOf`; the brand type is
+`TMDataGridTypedColumn`).
+
+```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"],
+});
+
+const persist = { urlKey: employeesUrl.urlKey } satisfies TMDataGridPersistence;
+
+const href = `/employees?${employeesUrl.searchParams({
+  filters: { department: { operator: "isAnyOf", value: ["Design"] } },
+  sorting: [{ id: "salary", desc: true }],
+})}`;
+```
+
+What a link may name (`TMDataGridUrlInput`); anything else is a type error:
+
+- `filters` (`TMDataGridUrlFiltersInput`): only columns whose
+  `enableColumnFilter` is not `false` and `meta.filter.url` is not `false`.
+  With no such column, `filters` accepts no key at all.
+- The operator: one the column's `meta.type` offers, narrowed by
+  `meta.filter.operators`.
+- The value: a `number` for a number column (`between` takes
+  `[number | null, number | null]`, `null` leaving that end open); a `Date` or a
+  `YYYY-MM-DD` string for a date column (`TMDataGridDateInput`; a `Date` is
+  written as its local calendar day, a longer string is cut to 10 characters);
+  a `boolean` for a boolean column; a `string` for a string column; an array of
+  the column's own values (the element type for an array value) for `isAnyOf` /
+  `isNoneOf`; no `value` for `isEmpty` / `isNotEmpty`.
+- `sorting` (`TMDataGridUrlSortableId`): only columns whose `enableSorting` is
+  not `false`. `desc` defaults to `false`.
+- `globalFilter` and `pagination` (`{ pageIndex, pageSize }`): only when the
+  definition carries those slices. `slices` defaults to every data slice.
+- A column with an accessor function is named by its `id`; without an `id` it
+  cannot be named. A dotted accessor key is named with underscores
+  (`address_city`).
+- Only literal values count: `enableSorting: isAdmin` reads as not sortable.
+  Columns built without the helper offer nothing. A table-level
+  `enableColumnFilters` or `enableSorting` is not seen.
+
+The definition (`TMDataGridUrlState`):
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | The URL search param. |
+| `slices` | `TMDataGridDataSlice[]` | The data slices the param carries. Default: every data slice. |
+| `urlKey` | `TMDataGridPersistKey` | For `persist.urlKey`: the key, or `[key, slices]` when `slices` is set. |
+| `searchParams(input, { serialize? })` | `URLSearchParams` | The link as search params, encoded with `serialize` (default `JSON.stringify`, as the grid's default). Empty when the input sets nothing. Pass the `serialize` given to `persist`, if any. |
+| `search(input)` | `{ [key]: TMDataGridUrlPayload \| undefined }` | The link as a router search object. |
+| `payload(input)` | `TMDataGridUrlPayload \| undefined` | The param's value in the grid's state shape (filters as `{ id, value: { operator, value } }` with string values), or `undefined` when the input sets nothing. |
+| `validateSearch(search)` | `{ [key]?: TMDataGridUrlPayload }` | A route search validator: keeps the param when it is a plain object, drops anything else. The grid checks each slice itself on read. |
+| `persist(storage?)` | `{ urlKey, urlStorage? }` | Spread into `persist`. Without `storage`, only `urlKey`, and the grid uses the browser's URL. |
+
+`persist(storage)` takes a `TMDataGridUrlSearchStorage`,
+`{ get(name): unknown; set(name, value: TMDataGridUrlPayload | undefined): void }`,
+for a router that keeps objects in its search and encodes them itself, such as
+TanStack Router. `get` returns the param's value or `undefined` (a string value
+is passed to the grid unchanged); `set` receives the payload object, or
+`undefined` to remove the param. The bridge converts with JSON, so leave
+`serialize` and `deserialize` at their defaults with it.
+
+```tsx
+// TanStack Router: the route validates, the grid writes through the router.
+const employeesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/employees",
+  validateSearch: employeesUrl.validateSearch,
+  component: EmployeesPage,
+});
+
+function EmployeesPage() {
+  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],
+  );
+  const grid = useTMDataGrid({ data, columns, persist });
+  // ...
+}
+
+<Link
+  to="/employees"
+  search={employeesUrl.search({
+    filters: { salary: { operator: "between", value: [40_000, 60_000] } },
+  })}
+/>;
+```
+
+- A route with its own search params spreads the validator:
+  `validateSearch: (s) => ({ ...employeesUrl.validateSearch(s), tab: ... })`.
+- With `createHashHistory()` the param sits after the `#` with the rest of the
+  router's search.
+- For URLs without percent escapes, give the router `parseSearch:
+  parseSearchWith(parse)` from `jsurl2`, and a `stringifySearch` that encodes
+  each object value with JSURL2's `stringify` and joins the pairs with
+  `encodeURIComponent`. TanStack Router's own `stringifySearchWith(stringify)`
+  joins them with `URLSearchParams`, which escapes JSURL2's `(`, `)`, `~` and
+  `!` again. JSURL2's `parse` also reads JSON, so older links still open. The
+  grid is unaffected. The full `stringifySearch` is on the
+  `typed-deep-links.md` docs page.
+- The grid reads its param once, on mount. A link to the route the grid is
+  already on changes the URL but not the grid; link from another route, or
+  remount the grid on that navigation.
+
+Source: `packages/tmdatagrid/docs/persistence.md` (Typed links) and
+`packages/tmdatagrid/docs/typed-deep-links.md`.

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.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.3.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.3.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.3.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.3.0'
+  library_version: '2.5.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'

package/src/components/TMDataGridFilterPills.tsx

@@ -2,6 +2,7 @@ import { Box, type BoxProps, Button, Pill, UnstyledButton } from "@mantine/core"
 import type { RowData } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import classes from "./TMDataGridFilterPills.module.css";
+import { resolveColumnOptions } from "../core/columnOptions";
 import { getColumnLabel, getColumnType } from "../core/columnUtils";
 import {
   formatFilterLabel,
@@ -9,7 +10,12 @@ import {
   isTMDataGridFilterValue,
 } from "../core/filterOperators";
 import type { TMDataGridSize } from "../core/sizes";
-import { openColumnFilter, type TMDataGridApi } from "../useTMDataGrid";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import {
+  openColumnFilter,
+  type TMDataGridApi,
+  type TMDataGridTable,
+} from "../useTMDataGrid";
 
 /** Mantine's style props (`mb="sm"`, `hiddenFrom="sm"`) are set on the wrapper. */
 export type TMDataGridFilterPillsProps<TData extends RowData> = BoxProps & {
@@ -55,6 +61,9 @@ export function TMDataGridFilterPills<TData extends RowData>({
   ...others
 }: TMDataGridFilterPillsProps<TData>) {
   const { table, labels } = api;
+  // The options readers take the row-type-erased table, like the rest of the
+  // chrome does through context.
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
   const columnFilters = useSelector(
     table.store,
     (state) => state.columnFilters,
@@ -76,6 +85,7 @@ export function TMDataGridFilterPills<TData extends RowData>({
       <Pill.Group size={size}>
         {activeFilters.map((filter) => {
           const column = table.getColumn(filter.id);
+          const erasedColumn = erased.getColumn(filter.id);
           const label = column ? getColumnLabel(column) : filter.id;
           const value = filter.value;
           // isFilterActive already vouched for the shape; this narrows it.
@@ -125,6 +135,10 @@ export function TMDataGridFilterPills<TData extends RowData>({
                   type: column ? getColumnType(column) : "string",
                   filter: value,
                   operatorLabels: labels.operators,
+                  options: erasedColumn
+                    ? resolveColumnOptions({ table: erased, column: erasedColumn })
+                    : undefined,
+                  labels,
                 })}
               </UnstyledButton>
             </Pill>

package/src/components/TMDataGridGroupColumn.tsx

@@ -8,7 +8,8 @@ import { useSelector } from "@tanstack/react-store";
 import { shallow } from "@tanstack/store";
 import classes from "./TMDataGridGroupColumn.module.css";
 import { ChevronRightIcon } from "./icons";
-import { getColumnLabel } from "../core/columnUtils";
+import { resolveColumnOptions } from "../core/columnOptions";
+import { getColumnLabel, getColumnType } from "../core/columnUtils";
 import { formatGroupValue, getGroupDataRows } from "../core/grouping";
 import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
@@ -30,7 +31,7 @@ export function GroupCell<TData extends RowData>({
 }: {
   row: Row<TMDataGridFeatures, TData>;
 }) {
-  const { labels } = useTMDataGridContext();
+  const { table, labels } = useTMDataGridContext();
   const tabIndex = useBodyControlTabIndex();
   const expanded = useSelector(row.table.store, () => row.getIsExpanded());
 
@@ -38,7 +39,21 @@ export function GroupCell<TData extends RowData>({
   // the indent alone is what places them under their group.
   if (!row.getIsGrouped()) return null;
 
-  const label = formatGroupValue(row.groupingValue, labels.blankGroupValue);
+  // `groupingValue` is TanStack's map key, the value already turned into a
+  // string: `true` arrives as "true", a Date as its English timestamp, `null`
+  // as "null". The first record's grouping value is the value itself.
+  const columnId = row.groupingColumnId;
+  const column = columnId === undefined ? undefined : table.getColumn(columnId);
+  const dataRows = getGroupDataRows(row);
+  const value =
+    columnId === undefined || dataRows[0] === undefined
+      ? row.groupingValue
+      : dataRows[0].getGroupingValue(columnId);
+  const label = formatGroupValue(value, labels.blankGroupValue, {
+    type: column ? getColumnType(column) : undefined,
+    options: column ? resolveColumnOptions({ table, column }) : undefined,
+    labels,
+  });
 
   return (
     <UnstyledButton
@@ -68,7 +83,7 @@ export function GroupCell<TData extends RowData>({
       {/* Data rows, not direct children and not `getLeafRows()`: a nested group
           counts the records under it, never the sub-groups in between. */}
       <span className={classes.groupCount}>
-        ({getGroupDataRows(row).length})
+        ({dataRows.length})
       </span>
     </UnstyledButton>
   );

package/src/components/TMDataGridHeaderFilterRow.tsx

@@ -268,7 +268,13 @@ export function TMDataGridHeaderFilterRow({
           <div
             key={header.id}
             role="columnheader"
-            aria-label={labels.filterOn(getColumnLabel(column))}
+            // Named only where there is a filter: a generated lane or a column
+            // that does not filter holds no control to name.
+            aria-label={
+              column.getCanFilter()
+                ? labels.filterOn(getColumnLabel(column))
+                : undefined
+            }
             data-dg-part="header-filter-cell"
             data-column-id={column.id}
             data-control-column={isControlColumn(column.id) || undefined}

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);