@jielga/tmdatagrid 2.3.0 → 2.5.0

package/src/core/filterOperators.ts

@@ -6,6 +6,9 @@ import type {
   TableFeatures,
 } from "@tanstack/react-table";
 import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridOption } from "./columnOptions";
+import type { TMDataGridLabels } from "./labels";
+import { formatValueText } from "./valueText";
 
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -75,7 +78,7 @@ export const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string> =
   isNotEmpty: "is not empty",
 };
 
-const STRING_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const STRING_OPERATORS = [
   "contains",
   "equals",
   "notEquals",
@@ -83,9 +86,9 @@ const STRING_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "endsWith",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
-const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const NUMBER_OPERATORS = [
   "equals",
   "notEquals",
   "greaterThan",
@@ -95,12 +98,12 @@ const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "between",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 // `equals` doubles as a date's "is": it compares by calendar day whenever the
 // cell holds a Date (see matchesFilter), so a separate `is` operator would be
 // the same comparison under a second name.
-const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const DATE_OPERATORS = [
   "equals",
   "notEquals",
   "before",
@@ -110,23 +113,23 @@ const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "between",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
-const BOOLEAN_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const BOOLEAN_OPERATORS = [
   "equals",
   "notEquals",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 // One set for both select types: the operators are about membership in the
 // filter's set, which reads the same whether the cell holds one value or many.
-const SELECT_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const SELECT_OPERATORS = [
   "isAnyOf",
   "isNoneOf",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 /** Operators that ignore the value input (the input is disabled for these). */
 const VALUELESS_OPERATORS: readonly TMDataGridFilterOperator[] = [
@@ -143,16 +146,27 @@ const ARRAY_OPERATORS: readonly TMDataGridFilterOperator[] = [
 /** Operators whose value is a `[min, max]` pair. */
 const RANGE_OPERATORS: readonly TMDataGridFilterOperator[] = ["between"];
 
-const OPERATORS_BY_TYPE: Record<
-  TMDataGridColumnType,
-  readonly TMDataGridFilterOperator[]
-> = {
+const OPERATORS_BY_TYPE = {
   string: STRING_OPERATORS,
   number: NUMBER_OPERATORS,
   boolean: BOOLEAN_OPERATORS,
   date: DATE_OPERATORS,
   select: SELECT_OPERATORS,
   multiSelect: SELECT_OPERATORS,
+} as const satisfies Record<
+  TMDataGridColumnType,
+  readonly TMDataGridFilterOperator[]
+>;
+
+/**
+ * The operators each column type offers, as a type: the same lists the filter
+ * panel offers, so a typed link can never name an operator the panel lacks.
+ *
+ * @internal Feeds the typed links in urlState.ts; not exported from the
+ * package.
+ */
+export type OperatorsByColumnType = {
+  [TType in TMDataGridColumnType]: (typeof OPERATORS_BY_TYPE)[TType][number];
 };
 
 const DEFAULT_OPERATOR_BY_TYPE: Record<
@@ -307,30 +321,39 @@ export function activeColumnFilters<TData extends RowData>(
  *
  * The type's default operator is left implicit - "First name: Sofia" reads the
  * way a person would say it - while any other operator is spelled out, since
- * that is the part a reader cannot guess.
+ * that is the part a reader cannot guess. A value with an option reads as the
+ * option's label, and a boolean as `labels.booleanTrue` / `booleanFalse`.
  */
 export function formatFilterLabel({
   label,
   type,
   filter,
   operatorLabels = FILTER_OPERATOR_LABELS,
+  options,
+  labels,
 }: {
   label: string;
   type: TMDataGridColumnType;
   filter: TMDataGridFilterValue;
   /** Localized operator names - `labels.operators`. Defaults to English. */
   operatorLabels?: Record<TMDataGridFilterOperator, string>;
+  /** The column's options, so a value reads as its option's label. */
+  options?: ReadonlyArray<TMDataGridOption>;
+  /** What a boolean value reads as. Defaults to English. */
+  labels?: Pick<TMDataGridLabels, "booleanTrue" | "booleanFalse">;
 }): string {
   const { operator, value } = filter;
   if (!operatorNeedsValue(operator)) {
     return `${label} ${operatorLabels[operator]}`;
   }
+  const valueText = (entry: string) =>
+    formatValueText(String(entry).trim(), { type, options, labels });
   const text =
     operator === "between" && Array.isArray(value)
-      ? value.map((entry) => String(entry).trim()).join("–")
+      ? value.map(valueText).join("–")
       : Array.isArray(value)
-        ? value.join(", ")
-        : String(value).trim();
+        ? value.map(valueText).join(", ")
+        : valueText(String(value));
   if (operator === getDefaultOperator(type)) return `${label}: ${text}`;
   return `${label} ${operatorLabels[operator]} ${text}`;
 }

package/src/core/grouping.ts

@@ -1,5 +1,6 @@
 import type { Row, RowData } from "@tanstack/react-table";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { formatValueText, type TMDataGridValueTextOptions } from "./valueText";
 
 /**
  * The data rows under a group row, at any depth.
@@ -29,14 +30,21 @@ const BLANK_GROUP_LABEL = "(Blank)";
  * Deliberately not the grouped column's own `cell` renderer: that renderer is
  * written for a data row and is free to reach into `row.original`, which on a
  * group row is the first leaf's record rather than anything about the group.
+ * `options` carries what the chrome knows of the column instead - its type,
+ * its option labels and the boolean labels.
  */
 export function formatGroupValue(
   value: unknown,
   blankLabel = BLANK_GROUP_LABEL,
+  options?: TMDataGridValueTextOptions,
 ): string {
-  if (value === null || value === undefined || value === "") {
+  if (
+    value === null ||
+    value === undefined ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0)
+  ) {
     return blankLabel;
   }
-  if (value instanceof Date) return value.toLocaleDateString();
-  return String(value);
+  return formatValueText(value, options);
 }

package/src/core/labels.ts

@@ -2,6 +2,7 @@ import {
   FILTER_OPERATOR_LABELS,
   type TMDataGridFilterOperator,
 } from "./filterOperators";
+import { BOOLEAN_LABELS_EN } from "./valueText";
 
 /**
  * Every user-facing string in the grid - menu items, panels, tooltips, the
@@ -55,7 +56,7 @@ export type TMDataGridLabels = {
   filterTo: string;
   /** `DgTriStateFilter`'s no-filter segment. */
   filterAll: string;
-  /** What a boolean column's `true` reads as - its filter choice and cell text. */
+  /** What a boolean `true` reads as - its filter choice, filter pill and group row. */
   booleanTrue: string;
   booleanFalse: string;
   addFilter: string;
@@ -225,8 +226,8 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   filterFrom: "From",
   filterTo: "To",
   filterAll: "All",
-  booleanTrue: "Yes",
-  booleanFalse: "No",
+  booleanTrue: BOOLEAN_LABELS_EN.booleanTrue,
+  booleanFalse: BOOLEAN_LABELS_EN.booleanFalse,
   addFilter: "Add filter",
   clearAllFilters: "Clear all",
   closeFilters: "Close filters",

package/src/core/persistence.ts

@@ -515,7 +515,15 @@ export function collectUrlExcludedColumnIds(
   return into;
 }
 
-function forEachLeafColumnDef(
+/**
+ * Visits every leaf column definition under `defs` with the id TanStack gives
+ * it: `id`, else the `accessorKey` with dots replaced by underscores, else a
+ * string `header`.
+ *
+ * @internal Shared by persistence and the typed links in urlState.ts; not
+ * exported from the package.
+ */
+export function forEachLeafColumnDef(
   defs: ReadonlyArray<unknown>,
   visit: (id: string, record: Record<string, unknown>) => void,
 ): void {

package/src/core/urlState.ts

@@ -0,0 +1,439 @@
+import type { TMDataGridColumnType } from "./filterOperators";
+import type {
+  OperatorsByColumnType,
+  TMDataGridColumnFilter,
+  TMDataGridFilterOperator,
+  TMDataGridFilterValue,
+} from "./filterOperators";
+import {
+  DATA_STATE_SLICES,
+  forEachLeafColumnDef,
+  type TMDataGridDataSlice,
+  type TMDataGridPersistence,
+  type TMDataGridPersistKey,
+  type TMDataGridUrlStorage,
+} from "./persistence";
+
+/**
+ * Typed deep links.
+ *
+ * `createTMDataGridColumnHelper` returns columns that carry, in their type
+ * only, what a link needs to know about them: the id, the `meta.type`, the
+ * value type, the offered operators, and whether the column can be filtered,
+ * sorted and put in the URL. `createTMDataGridUrlState` reads that from the
+ * grid's own columns, so a link can name only what the grid can show: a
+ * filter on a column the grid lacks, an operator its type does not offer or a
+ * value of the wrong type is a compile error, not a link that silently opens
+ * unfiltered.
+ *
+ * Nothing here is visible at runtime except the definition object. The
+ * column brand is a type, never a property.
+ */
+
+// ---------------------------------------------------------------------------
+// The column brand
+// ---------------------------------------------------------------------------
+
+/**
+ * What a column built with `createTMDataGridColumnHelper` tells a typed link
+ * about itself. Read from literal values in the column definition: a value
+ * that is not a literal (`enableSorting: isAdmin`) reads as "not allowed".
+ */
+export type TMDataGridColumnInfo = {
+  /** The column id, by TanStack's rule: `id`, else the accessor key with `.` replaced by `_`. */
+  id: string;
+  /** `meta.type`, `"string"` when unset. */
+  type: TMDataGridColumnType;
+  /** The value type the accessor returns. */
+  value: unknown;
+  /** `meta.filter.operators`, every operator when unset. */
+  operators: TMDataGridFilterOperator;
+  /** `enableColumnFilter` is not `false`. */
+  filterable: boolean;
+  /** `enableSorting` is not `false`. */
+  sortable: boolean;
+  /** `meta.filter.url` is not `false`. */
+  url: boolean;
+};
+
+declare const columnInfo: unique symbol;
+
+/**
+ * The type-only brand a column helper column carries. Never present at
+ * runtime, so spreading, cloning or serializing a column is unaffected.
+ */
+export type TMDataGridTypedColumn<TInfo extends TMDataGridColumnInfo> = {
+  readonly [columnInfo]: TInfo;
+};
+
+/** The info of every leaf column in `TColumn`, a group's children included. */
+export type TMDataGridColumnInfoOf<TColumn> =
+  TColumn extends TMDataGridTypedColumn<infer TInfo> ? TInfo : never;
+
+/** `"address.city"` becomes `"address_city"`, as TanStack derives the id. */
+type DotsToUnderscores<S extends string> = S extends `${infer Head}.${infer Tail}`
+  ? `${Head}_${DotsToUnderscores<Tail>}`
+  : S;
+
+/**
+ * The column id the helper's `accessor` call produces: the explicit `id`,
+ * else the accessor key. An accessor function without an `id` gets `never`,
+ * which no link can name.
+ */
+export type TMDataGridAccessorColumnId<TAccessor, TId extends string> = [TId] extends [never]
+  ? TAccessor extends string
+    ? DotsToUnderscores<TAccessor>
+    : never
+  : TId;
+
+/**
+ * The column options whose literal values a typed link reads. Intersected into
+ * the column helper's parameter so each one is inferred as a literal.
+ *
+ * @internal
+ */
+export type TMDataGridColumnInfoHints<
+  TId extends string,
+  TType extends TMDataGridColumnType,
+  TOperator extends TMDataGridFilterOperator,
+  TFilterable extends boolean,
+  TSortable extends boolean,
+  TUrl extends boolean,
+> = {
+  id?: TId;
+  enableColumnFilter?: TFilterable;
+  enableSorting?: TSortable;
+  meta?: {
+    type?: TType;
+    filter?: { operators?: ReadonlyArray<TOperator>; url?: TUrl };
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Link input
+// ---------------------------------------------------------------------------
+
+/** A `Date`, or an ISO `YYYY-MM-DD` string. */
+export type TMDataGridDateInput = Date | string;
+
+/** One choice of a select column: the value, or an element of an array value. */
+type OptionOf<TValue> =
+  NonNullable<TValue> extends ReadonlyArray<infer TElement> ? TElement : NonNullable<TValue>;
+
+type ScalarInput = {
+  string: string;
+  number: number;
+  date: TMDataGridDateInput;
+  boolean: boolean;
+  select: string;
+  multiSelect: string;
+};
+
+type RangeEnd<TType extends TMDataGridColumnType> = TType extends "date"
+  ? TMDataGridDateInput
+  : TType extends "number"
+    ? number
+    : string;
+
+/** One filter on one column: an operator, and the value that operator takes. */
+type FilterInputFor<
+  TType extends TMDataGridColumnType,
+  TValue,
+  TOperator extends TMDataGridFilterOperator,
+> = TOperator extends "isEmpty" | "isNotEmpty"
+  ? { operator: TOperator }
+  : TOperator extends "isAnyOf" | "isNoneOf"
+    ? { operator: TOperator; value: ReadonlyArray<OptionOf<TValue>> }
+    : TOperator extends "between"
+      ? {
+          operator: TOperator;
+          /** `null` leaves that end open. */
+          value: readonly [from: RangeEnd<TType> | null, to: RangeEnd<TType> | null];
+        }
+      : { operator: TOperator; value: ScalarInput[TType] };
+
+/** Columns a link may filter: filterable, and not kept out of the URL. */
+type LinkFilterable<TInfo extends TMDataGridColumnInfo> = Extract<
+  TInfo,
+  { filterable: true; url: true }
+>;
+
+/**
+ * The `filters` a link accepts: one optional entry per filterable column.
+ * With no filterable column it accepts no entry at all - an empty object type
+ * would let any key through, since TypeScript skips the unknown-key check
+ * against `{}`.
+ */
+export type TMDataGridUrlFiltersInput<TInfo extends TMDataGridColumnInfo> = [
+  LinkFilterable<TInfo>,
+] extends [never]
+  ? Record<string, never>
+  : {
+      [TColumn in LinkFilterable<TInfo> as TColumn["id"]]?: FilterInputFor<
+        TColumn["type"],
+        TColumn["value"],
+        Extract<OperatorsByColumnType[TColumn["type"]], TColumn["operators"]>
+      >;
+    };
+
+/** The ids a link may sort by. */
+export type TMDataGridUrlSortableId<TInfo extends TMDataGridColumnInfo> = Extract<
+  TInfo,
+  { sortable: true }
+>["id"];
+
+type Carries<
+  TSlices extends ReadonlyArray<TMDataGridDataSlice>,
+  TSlice extends TMDataGridDataSlice,
+> = TSlice extends TSlices[number] ? true : false;
+
+/** What a link may set: only the slices the definition carries, only the grid's columns. */
+export type TMDataGridUrlInput<
+  TInfo extends TMDataGridColumnInfo,
+  TSlices extends ReadonlyArray<TMDataGridDataSlice>,
+> = (Carries<TSlices, "columnFilters"> extends true
+  ? { filters?: TMDataGridUrlFiltersInput<TInfo> }
+  : unknown) &
+  (Carries<TSlices, "globalFilter"> extends true ? { globalFilter?: string } : unknown) &
+  (Carries<TSlices, "sorting"> extends true
+    ? {
+        sorting?: ReadonlyArray<{
+          id: TMDataGridUrlSortableId<TInfo>;
+          /** Defaults to `false`. */
+          desc?: boolean;
+        }>;
+      }
+    : unknown) &
+  (Carries<TSlices, "pagination"> extends true
+    ? { pagination?: { pageIndex: number; pageSize: number } }
+    : unknown);
+
+// ---------------------------------------------------------------------------
+// The payload and the definition
+// ---------------------------------------------------------------------------
+
+/** What the grid keeps in its URL param: the data slices, in the grid's own state shape. */
+export type TMDataGridUrlPayload = {
+  columnFilters?: Array<TMDataGridColumnFilter>;
+  /** `null` is a search the user cleared, as opposed to one the link does not set. */
+  globalFilter?: string | null;
+  sorting?: Array<{ id: string; desc: boolean }>;
+  pagination?: { pageIndex: number; pageSize: number };
+  expanded?: true | Record<string, boolean>;
+};
+
+/**
+ * A router's search, read and written as values rather than strings, for
+ * routers that keep objects in their search params and encode them
+ * themselves, such as TanStack Router.
+ */
+export type TMDataGridUrlSearchStorage = {
+  /** The param's current value in the router's search, or `undefined`. */
+  get(name: string): unknown;
+  /** Sets the param to `value`, or removes it on `undefined`. */
+  set(name: string, value: TMDataGridUrlPayload | undefined): void;
+};
+
+export type TMDataGridUrlState<
+  TKey extends string,
+  TSlices extends ReadonlyArray<TMDataGridDataSlice>,
+  TInfo extends TMDataGridColumnInfo,
+> = {
+  /** The URL search param. */
+  readonly key: TKey;
+  /** The data slices the param carries. */
+  readonly slices: TSlices;
+  /** For `persist.urlKey`. */
+  readonly urlKey: TMDataGridPersistKey<TMDataGridDataSlice>;
+  /** The param's value for a link, or `undefined` when the input sets nothing. */
+  payload(input: TMDataGridUrlInput<TInfo, TSlices>): TMDataGridUrlPayload | undefined;
+  /** The search object for a router link, `{ [key]: payload }`. */
+  search(input: TMDataGridUrlInput<TInfo, TSlices>): {
+    [K in TKey]: TMDataGridUrlPayload | undefined;
+  };
+  /**
+   * The search params for a plain link, encoded the way the grid's default
+   * `serialize` encodes them. Pass the `serialize` you gave `persist`, if any.
+   */
+  searchParams(
+    input: TMDataGridUrlInput<TInfo, TSlices>,
+    options?: { serialize?: (payload: TMDataGridUrlPayload) => string },
+  ): URLSearchParams;
+  /**
+   * A route search validator: keeps the param when it is an object and drops
+   * anything else. The grid checks every slice itself when it reads the param.
+   */
+  validateSearch(search: Record<string, unknown>): {
+    [K in TKey]?: TMDataGridUrlPayload;
+  };
+  /**
+   * `urlKey`, plus a `urlStorage` over `storage` when one is given. Without
+   * one, the grid reads and writes the browser's URL itself.
+   */
+  persist(
+    storage?: TMDataGridUrlSearchStorage,
+  ): Pick<TMDataGridPersistence, "urlKey" | "urlStorage">;
+};
+
+/**
+ * Defines a grid's deep links from its columns. `columns` is the array the
+ * grid renders, built with `createTMDataGridColumnHelper`; it decides which
+ * filters, operators, values and sorts a link may name.
+ */
+export function createTMDataGridUrlState<
+  const TKey extends string,
+  TColumns extends ReadonlyArray<unknown>,
+  const TSlices extends ReadonlyArray<TMDataGridDataSlice> = typeof DATA_STATE_SLICES,
+>(options: {
+  /** The URL search param. */
+  key: TKey;
+  /** The grid's columns. */
+  columns: TColumns;
+  /** The data slices the param carries. Defaults to every data slice. */
+  slices?: TSlices;
+}): TMDataGridUrlState<TKey, TSlices, TMDataGridColumnInfoOf<TColumns[number]>> {
+  const { key, columns } = options;
+  const slices = (options.slices ?? DATA_STATE_SLICES) as TSlices;
+  const urlKey: TMDataGridPersistKey<TMDataGridDataSlice> = options.slices
+    ? [key, options.slices]
+    : key;
+
+  const columnTypes = new Map<string, TMDataGridColumnType>();
+  forEachLeafColumnDef(columns, (id, record) => {
+    const type = (record.meta as { type?: TMDataGridColumnType } | undefined)?.type;
+    columnTypes.set(id, type ?? "string");
+  });
+
+  const payload = (input: LooseUrlInput): TMDataGridUrlPayload | undefined =>
+    toPayload(input, columnTypes, slices);
+
+  return {
+    key,
+    slices,
+    urlKey,
+    payload: (input) => payload(input as LooseUrlInput),
+    search: (input) =>
+      ({ [key]: payload(input as LooseUrlInput) }) as {
+        [K in TKey]: TMDataGridUrlPayload | undefined;
+      },
+    searchParams: (input, { serialize = JSON.stringify } = {}) => {
+      const value = payload(input as LooseUrlInput);
+      const params = new URLSearchParams();
+      if (value !== undefined) params.set(key, serialize(value));
+      return params;
+    },
+    validateSearch: (search) => {
+      const value = search[key];
+      return (isPlainObject(value) ? { [key]: value } : {}) as {
+        [K in TKey]?: TMDataGridUrlPayload;
+      };
+    },
+    persist: (storage) =>
+      storage ? { urlKey, urlStorage: toUrlStorage(storage) } : { urlKey },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Runtime
+// ---------------------------------------------------------------------------
+
+type LooseFilterInput = { operator: TMDataGridFilterOperator; value?: unknown };
+
+type LooseUrlInput = {
+  filters?: Record<string, LooseFilterInput | undefined>;
+  globalFilter?: string;
+  sorting?: ReadonlyArray<{ id: string; desc?: boolean }>;
+  pagination?: { pageIndex: number; pageSize: number };
+};
+
+/**
+ * The input in the grid's own state shape. A slice the definition does not
+ * carry is left out even when an untyped caller passes it, since the grid
+ * would ignore it in the URL anyway.
+ */
+function toPayload(
+  input: LooseUrlInput,
+  columnTypes: ReadonlyMap<string, TMDataGridColumnType>,
+  slices: ReadonlyArray<TMDataGridDataSlice>,
+): TMDataGridUrlPayload | undefined {
+  const payload: TMDataGridUrlPayload = {};
+
+  if (input.filters && slices.includes("columnFilters")) {
+    const columnFilters = Object.entries(input.filters).flatMap(([id, filter]) =>
+      filter ? [{ id, value: toFilterValue(filter, columnTypes.get(id)) }] : [],
+    );
+    if (columnFilters.length > 0) payload.columnFilters = columnFilters;
+  }
+  if (input.globalFilter && slices.includes("globalFilter")) {
+    payload.globalFilter = input.globalFilter;
+  }
+  if (input.sorting && input.sorting.length > 0 && slices.includes("sorting")) {
+    payload.sorting = input.sorting.map(({ id, desc = false }) => ({ id, desc }));
+  }
+  if (input.pagination && slices.includes("pagination")) {
+    payload.pagination = {
+      pageIndex: input.pagination.pageIndex,
+      pageSize: input.pagination.pageSize,
+    };
+  }
+
+  return Object.keys(payload).length === 0 ? undefined : payload;
+}
+
+/** Native values in, the grid's filter envelope out: every value a string. */
+function toFilterValue(
+  filter: LooseFilterInput,
+  type: TMDataGridColumnType | undefined,
+): TMDataGridFilterValue {
+  const { operator, value } = filter;
+  if (operator === "isEmpty" || operator === "isNotEmpty") {
+    return { operator, value: "" };
+  }
+  if (operator === "isAnyOf" || operator === "isNoneOf") {
+    return { operator, value: (value as ReadonlyArray<unknown>).map(String) };
+  }
+  if (operator === "between") {
+    const [from, to] = value as readonly [unknown, unknown];
+    return { operator, value: [toFilterString(from, type), toFilterString(to, type)] };
+  }
+  return { operator, value: toFilterString(value, type) };
+}
+
+function toFilterString(value: unknown, type: TMDataGridColumnType | undefined): string {
+  if (value === null || value === undefined) return "";
+  if (value instanceof Date) return localIsoDay(value);
+  // The date controls write `YYYY-MM-DD`; a full ISO timestamp is cut to it.
+  if (type === "date" && typeof value === "string") return value.slice(0, 10);
+  return String(value);
+}
+
+/** The calendar day in local time. `toISOString()` would give the UTC day. */
+function localIsoDay(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/**
+ * The grid reads and writes its param as the string `serialize` produced
+ * (JSON by default); a router like TanStack Router keeps the parsed object and
+ * encodes it itself. Both directions go through JSON, so the grid's "the param
+ * is unchanged, skip the write" comparison keeps holding.
+ */
+function toUrlStorage(storage: TMDataGridUrlSearchStorage): TMDataGridUrlStorage {
+  return {
+    get: (name) => {
+      const value = storage.get(name);
+      if (value === undefined || value === null) return null;
+      // A router that left the value as text hands back what the grid wrote.
+      return typeof value === "string" ? value : JSON.stringify(value);
+    },
+    set: (name, value) => {
+      storage.set(name, value === null ? undefined : (JSON.parse(value) as TMDataGridUrlPayload));
+    },
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}