@jielga/tmdatagrid 2.3.0 → 2.4.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

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.4.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.4.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.4.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.4.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:
 

package/skills/data/SKILL.md

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

package/skills/editing/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.4.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/draft-store.md'

package/skills/filtering/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.4.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.4.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.4.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. |

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.4.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.4.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 |