@jielga/tmdatagrid 2.2.0 → 2.4.0

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/docs/use-tm-data-grid.md

@@ -181,13 +181,16 @@ toolbar components can read the same strings as the built-in parts.
 ## persist
 
 Restores table state on mount and writes it back on every change. State is
-split across two keys: `settingsKey` for the column layout, `dataKey` for
-filters, sorting and pagination. Either can be cleared without the other.
+split across three keys: `settingsKey` for the column layout, `dataKey` for
+filters, sorting and pagination, and `urlKey` for data slices kept in the URL
+as a deep link. Each can be cleared without the others.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataKey` | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `urlKey` | `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](/docs/persistence#deep-links). |
+| `urlStorage` | `TMDataGridUrlStorage` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `storageMode` | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. Use `"sessionStorage"` for per-tab state. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes a payload before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
@@ -222,6 +225,7 @@ const persist = {
 | Group | Available slices |
 | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey`. |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
 
 The exported `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` arrays contain the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "2.2.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.2.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.2.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

@@ -4,7 +4,7 @@ description: >
   Define and arrange TMDataGrid columns. Covers createTMDataGridColumnHelper,
   every column meta field (label, type, options, flex, align, colSpan, autoSize,
   enableOrdering, and the meta.filter and meta.edit namespaces holding
-  operators, defaultOperator, control, enabled, field, editor, validate and
+  operators, defaultOperator, control, url, enabled, field, editor, validate and
   mapValue), the six column types, fluid minmax sizing versus fixed width with
   minSize / maxSize / size, autosizing and autosizeColumn, hiding through
   enableHiding and the columns panel, pinning and why a pinned column becomes
@@ -16,7 +16,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.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:
 
@@ -94,7 +97,7 @@ What the column **is** stays flat; what the filter panel and the edit engine do
 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` and `control`; `meta.edit`
+`meta.filter` holds `operators`, `defaultOperator`, `control` and `url`; `meta.edit`
 holds `enabled`, `field`, `editor`, `validate` and `mapValue`. Their fields are
 in [references/columns-api.md](references/columns-api.md).
 

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

@@ -11,6 +11,7 @@ Reference for the `columns` skill.
 | `operators` | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. For a backend that answers only some. |
 | `defaultOperator` | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter on this column starts with. |
 | `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
+| `url` | `boolean` | `true` | Whether the column's filter is written to the URL under `persist.urlKey`. `false` keeps it out of the link, and out of storage. |
 
 `meta.edit` belongs to the `editing` skill, and only acts once `editing` is set:
 

package/skills/data/SKILL.md

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

@@ -4,21 +4,21 @@ description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
   meta.type offers each, meta.filter.operators to offer a column only a subset
-  of them, meta.filter.defaultOperator, isFilterActive and the half-typed
-  filter, the filters option and its surfaces (popup, sidebar, none, plus
-  inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
-  TMDataGrid.FilterButton, TMDataGrid.FilterPills with its api prop,
-  openColumnFilter, replacing a value control with DgRangeSliderFilter /
-  DgDateRangeFilter / DgAutocompleteFilter / DgTriStateFilter or a
-  meta.filter.control component, per-column filterFn, and the quick search:
-  TMDataGrid.Search, quickSearchMode fuzzy or contains, fuzzyGlobalFilterFn,
-  enableMatchHighlighting and enableGlobalFilter. Load when adding filters,
-  choosing operators, building a filter control, showing active filters outside
-  the grid, or wiring a search box.
+  of them, meta.filter.defaultOperator, meta.filter.url for deep links,
+  isFilterActive and the half-typed filter, the filters option and its surfaces
+  (popup, sidebar, none, plus inHeader for header filters),
+  TMDataGrid.FilterPanel and its layout prop, TMDataGrid.FilterButton,
+  TMDataGrid.FilterPills with its api prop, openColumnFilter, replacing a value
+  control with DgRangeSliderFilter / DgDateRangeFilter / DgAutocompleteFilter /
+  DgTriStateFilter or a meta.filter.control component, per-column filterFn, and
+  the quick search: TMDataGrid.Search, quickSearchMode fuzzy or contains,
+  fuzzyGlobalFilterFn, enableMatchHighlighting and enableGlobalFilter. Load when
+  adding filters, choosing operators, building a filter control, showing active
+  filters outside the grid, or wiring a search box.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.4.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/react:packages/tmdatagrid/docs/quick-search.md'
@@ -105,6 +105,18 @@ columnHelper.accessor("customer", {
 `getColumnDefaultOperator(column)` the operator a fresh filter opens on. The
 `server-side` skill shows the list typed together with the API mapping table.
 
+`meta.filter.url` determines whether the column's filter goes into the URL
+search param when `persist.urlKey` carries `columnFilters`. By default it does.
+Set it to `false` for a filter that should not travel in a shared link; the
+filter is then not persisted anywhere. The `options` skill covers `urlKey`.
+
+```tsx
+columnHelper.accessor("owner", {
+  header: "Owner",
+  meta: { filter: { url: false } },
+});
+```
+
 ## The filters option
 
 `filters` on `useTMDataGrid` picks the surface. It is read field by field, so an
@@ -185,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
@@ -469,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.2.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.2.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.2.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

@@ -9,21 +9,23 @@ description: >
   labels, editing, filters, exportOptions, enableColumnOrdering,
   enablePagination, resetPageOnQueryChange, enableRowNumbers, selectionMode,
   showSelectedBackground, cellSelection, renderDetails, overscan,
-  quickSearchMode), persist with dataKey/settingsKey slices and storageMode, 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.
+  quickSearchMode), persist with dataKey/settingsKey slices, storageMode and
+  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.2.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
@@ -160,14 +162,17 @@ const grid = useTMDataGrid({
 ## persist
 
 Restores table state on mount and writes it back on every change. State is split
-across two keys because the groups have different lifetimes: column configuration
-stays valid indefinitely, while filters and pagination go stale as the data
-changes. Separate keys let one group be cleared without touching the other.
+across three keys because the groups have different lifetimes: column configuration
+stays valid indefinitely, filters and pagination go stale as the data
+changes, and a deep link has to travel with the page URL. Separate keys let one
+group be cleared without touching the others.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | `TMDataGridPersistKey<TMDataGridSettingsSlice>`: `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `urlKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](#deep-links). |
+| `urlStorage` | `TMDataGridUrlStorage`: `{ get(name): string \| null; set(name, value: string \| null): void }` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `storageMode` | `TMDataGridStorageMode`: `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
@@ -203,6 +208,7 @@ const persist = {
 | Group | Available slices |
 | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey`. |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
 
 `grouping` is a settings slice because it names columns rather than values, so it
@@ -227,6 +233,95 @@ dropped.
 
 Source: `packages/tmdatagrid/docs/persistence.md` (Behaviour).
 
+### Deep links
+
+`urlKey` keeps data slices in one URL search param, so a link to the page opens
+the grid on the same filters. The string is the param name; a bare key takes
+every data slice, a tuple a subset, as with `dataKey`.
+
+```tsx
+const persist = {
+  settingsKey: "employees.settings",
+  // Sorting is remembered per browser; the filters travel in the link.
+  dataKey: ["employees.data", ["sorting"]],
+  urlKey: ["employees", ["columnFilters", "globalFilter"]],
+} satisfies TMDataGridPersistence;
+```
+
+- A slice lives in one group. A slice listed under `urlKey` is taken out of
+  `dataKey`: a bare `dataKey` hands it over silently, while a `dataKey` tuple
+  that names the slice explicitly is reported with `console.error` on mount.
+- The param carries only the slices whose value differs from the initial state
+  (`initialState` merged over the grid defaults), and only the column filters
+  that are active. When nothing differs, the param is removed. A link without the param, or without a slice, opens on the
+  initial state; a URL slice never falls back to storage.
+- Writes use `history.replaceState`, never `pushState`. Only the grid's own
+  param changes; the path, the hash, other params and `history.state` are kept.
+  Two grids on one page use two keys.
+- The URL payload has no version stamp, so a bookmarked link survives a
+  release. The shape guards and the realignment against existing columns apply
+  as for storage, and `serialize` / `deserialize` apply to the URL payload too.
+- `meta.filter.url: false` on a column keeps its filter out of the param, on
+  read and on write. The column's filter is then not persisted anywhere, and a
+  filter on it in `initialState` still applies when a link is opened. The
+  flag has no effect unless `urlKey` carries `columnFilters`.
+- `urlStorage` replaces the default read and write of the param, for a router
+  that owns the URL. `get` returns the param's string or `null`; `set` receives
+  the string, or `null` to remove the param. `set` is only called when the
+  value changed. Keep `persist` referentially stable here too: react-router
+  rebuilds `setSearchParams` on every URL change, so read it through a ref.
+
+```tsx
+// react-router: let the router do the replace.
+const [, setSearchParams] = useSearchParams();
+const setSearchParamsRef = useRef(setSearchParams);
+setSearchParamsRef.current = setSearchParams;
+
+const persist = useMemo(
+  () =>
+    ({
+      urlKey: ["employees", ["columnFilters"]],
+      urlStorage: {
+        get: (name) => new URLSearchParams(window.location.search).get(name),
+        set: (name, value) =>
+          setSearchParamsRef.current(
+            (prev) => {
+              if (value === null) prev.delete(name);
+              else prev.set(name, value);
+              return prev;
+            },
+            { replace: true },
+          ),
+      },
+    }) satisfies TMDataGridPersistence,
+  [],
+);
+```
+
+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 |