@jielga/tmdatagrid 2.2.0 → 2.3.0

package/src/core/persistence.ts

@@ -1,5 +1,7 @@
 import type { TableState } from "@tanstack/react-table";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { sameStateValue } from "./controlledState";
+import { filterNarrowsRows } from "./filterOperators";
 
 type GridState = TableState<TMDataGridFeatures>;
 
@@ -65,11 +67,32 @@ export type TMDataGridPersistKey<TSlice extends string> =
 /** Same values as Mantine's `StorageType`, which the package does not re-export. */
 export type TMDataGridStorageMode = "localStorage" | "sessionStorage";
 
+/**
+ * Reads and writes the one URL search param that `urlKey` names. Replaces the
+ * default, which reads `window.location.search` and writes with
+ * `history.replaceState`, for a router that owns the URL.
+ */
+export type TMDataGridUrlStorage = {
+  /** The param's current value, or `null` when the URL has none. */
+  get(name: string): string | null;
+  /** Sets the param to `value`, or removes it when `value` is `null`. */
+  set(name: string, value: string | null): void;
+};
+
 export type TMDataGridPersistence = {
   /** Key for filters, global filter, sorting and pagination. */
   dataKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
   /** Key for column visibility, sizing, order and pinning. */
   settingsKey?: TMDataGridPersistKey<TMDataGridSettingsSlice>;
+  /**
+   * Search param for data slices kept in the URL, so a link opens the grid on
+   * the same state. Takes the slices it lists away from `dataKey`. The param
+   * holds only the slices that differ from the initial state, and carries no
+   * version stamp.
+   */
+  urlKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
+  /** Where `urlKey` reads and writes. Defaults to the browser's URL. */
+  urlStorage?: TMDataGridUrlStorage;
   /** Which storage area to use. Defaults to `"localStorage"`. */
   storageMode?: TMDataGridStorageMode;
   /** Serializes a payload before it is stored. Defaults to `JSON.stringify`. */
@@ -104,6 +127,59 @@ function resolveKey<TSlice extends string>(
   return { key, slices: slices as ReadonlyArray<keyof GridState> };
 }
 
+/**
+ * The browser's URL. Writes replace the current history entry and never push
+ * one: a filter change is not a navigation, and Back should leave the page
+ * rather than undo filters one at a time. Path, hash, every other param and
+ * `history.state` are kept - a router keeps its own bookkeeping there.
+ */
+const defaultUrlStorage: TMDataGridUrlStorage = {
+  get: (name) => new URLSearchParams(window.location.search).get(name),
+  set: (name, value) => {
+    // Spliced by hand rather than through `URLSearchParams`, whose serializer
+    // re-encodes every param (`/a%20b` comes back as `%2Fa+b`). Only the
+    // grid's own pair changes; every other entry is kept byte for byte.
+    const { pathname, search, hash, href } = window.location;
+    const entries = search
+      .replace(/^\?/, "")
+      .split("&")
+      .filter((entry) => entry !== "");
+    const kept = entries.filter((entry) => paramEntryKey(entry) !== name);
+    if (value === null && kept.length === entries.length) return;
+    if (value !== null) {
+      kept.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+    }
+    const next = `${pathname}${kept.length === 0 ? "" : `?${kept.join("&")}`}${hash}`;
+    if (new URL(next, href).href === href) return;
+    window.history.replaceState(window.history.state, "", next);
+  },
+};
+
+/** The decoded key of one `key=value` query entry, `+` read as a space. */
+function paramEntryKey(entry: string): string {
+  const separator = entry.indexOf("=");
+  const raw = (separator === -1 ? entry : entry.slice(0, separator)).replaceAll(
+    "+",
+    " ",
+  );
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    // A malformed escape cannot be the grid's own key, which it encoded.
+    return raw;
+  }
+}
+
+function resolveUrlStorage(
+  persistence: TMDataGridPersistence | undefined,
+): TMDataGridUrlStorage | null {
+  if (!persistence) return null;
+  if (persistence.urlStorage) return persistence.urlStorage;
+  // Absent under SSR, like web storage. Access that throws is caught where the
+  // param is read or written.
+  return typeof window === "undefined" ? null : defaultUrlStorage;
+}
+
 function resolveStorage(
   persistence: TMDataGridPersistence | undefined,
 ): Storage | null {
@@ -213,30 +289,44 @@ function isValidSlice(slice: keyof GridState, value: unknown): boolean {
   return guard === undefined || guard(value);
 }
 
-function readSlices(
-  storage: Storage | null,
-  resolved: ResolvedKey | null,
-  deserialize: (value: string) => unknown,
-): Partial<GridState> {
-  if (!storage || !resolved) return {};
+function readSlices({
+  read,
+  resolved,
+  deserialize,
+  versioned,
+}: {
+  /** Returns the raw payload stored under a key, or `null`. */
+  read: ((key: string) => string | null) | null;
+  resolved: ResolvedKey | null;
+  deserialize: (value: string) => unknown;
+  /** Whether the payload must carry the current version stamp. */
+  versioned: boolean;
+}): Partial<GridState> {
+  if (!read || !resolved) return {};
   try {
-    const raw = storage.getItem(resolved.key);
+    const raw = read(resolved.key);
     if (!raw) return {};
     const parsed = deserialize(raw);
     if (typeof parsed !== "object" || parsed === null) return {};
 
     const record = parsed as Record<string, unknown>;
-    if (record[VERSION_FIELD] !== PERSIST_PAYLOAD_VERSION) return {};
+    if (versioned && record[VERSION_FIELD] !== PERSIST_PAYLOAD_VERSION) {
+      return {};
+    }
     const restored: Record<string, unknown> = {};
     // Only copy the selected slices. A payload written before the selection was
     // narrowed cannot reintroduce slices the caller has since opted out of.
     for (const slice of resolved.slices) {
       if (!(slice in record)) continue;
-      if (!isValidSlice(slice, record[slice])) continue;
+      // A `null` slice stands for `undefined` - see the writers. An own key
+      // holding `undefined` still overrides `initialState` in the merge, which
+      // is the point: the user cleared the slice. The slice's guard then
+      // judges `undefined`, so only a slice that may be `undefined` (the
+      // untyped global filter) restores that way.
+      const value = record[slice] === null ? undefined : record[slice];
+      if (!isValidSlice(slice, value)) continue;
       restored[slice] =
-        slice === "columnPinning"
-          ? normalizeColumnPinning(record[slice])
-          : record[slice];
+        slice === "columnPinning" ? normalizeColumnPinning(value) : value;
     }
     return restored as Partial<GridState>;
   } catch {
@@ -252,7 +342,13 @@ function writeSlices(
 ): void {
   if (!storage || !resolved) return;
   const payload: Record<string, unknown> = { [VERSION_FIELD]: PERSIST_PAYLOAD_VERSION };
-  for (const slice of resolved.slices) payload[slice] = state[slice];
+  for (const slice of resolved.slices) {
+    // `null` for a slice the user cleared to `undefined` - the global filter
+    // over an `initialState.globalFilter`. JSON drops an `undefined` key, and
+    // a missing slice means the initial state, so a reload would come back on
+    // the very value the user cleared. readSlices turns it back.
+    payload[slice] = state[slice] === undefined ? null : state[slice];
+  }
   try {
     storage.setItem(resolved.key, serialize(payload as Partial<GridState>));
   } catch {
@@ -260,9 +356,100 @@ function writeSlices(
   }
 }
 
+/**
+ * Writes the URL payload: the selected slices that differ from `baseline`,
+ * with no version stamp, or no param at all when none differs.
+ *
+ * Only the difference goes in, so a link names what the user changed and not
+ * what the page starts with anyway: the address bar stays short, and an old
+ * link does not pin a default the page has since changed. No stamp, because a
+ * bookmarked link has to survive a release; the shape guards and the
+ * realignment on read are what keep an old link safe.
+ */
+function writeUrlSlices({
+  urlStorage,
+  resolved,
+  state,
+  baseline,
+  excludedFilterColumnIds,
+  serialize,
+}: {
+  urlStorage: TMDataGridUrlStorage | null;
+  resolved: ResolvedKey | null;
+  state: GridState;
+  baseline: Partial<GridState>;
+  excludedFilterColumnIds: ReadonlySet<string>;
+  serialize: (value: Partial<GridState>) => string;
+}): void {
+  if (!urlStorage || !resolved) return;
+  const payload: Record<string, unknown> = {};
+  for (const slice of resolved.slices) {
+    // Both sides reduced the same way, so a change to an opted-out column or
+    // to a filter that narrows nothing does not put the param in the URL.
+    const value =
+      slice === "columnFilters"
+        ? linkableColumnFilters(state.columnFilters, excludedFilterColumnIds)
+        : state[slice];
+    const initial =
+      slice === "columnFilters"
+        ? linkableColumnFilters(baseline.columnFilters, excludedFilterColumnIds)
+        : baseline[slice];
+    if (sameStateValue(value, initial)) continue;
+    // `null` for a slice the user cleared to `undefined` - the global filter
+    // over an `initialState.globalFilter`. JSON drops an `undefined` key, and
+    // a missing slice means the initial state, so the link would reopen on
+    // the very value the user cleared. readSlices turns it back.
+    payload[slice] = value === undefined ? null : value;
+  }
+  try {
+    const next =
+      Object.keys(payload).length === 0
+        ? null
+        : serialize(payload as Partial<GridState>);
+    // Unchanged: no write. A router-backed storage may navigate on every
+    // `set`, and the debounced write runs after a resize or a selection too.
+    if (urlStorage.get(resolved.key) === next) return;
+    urlStorage.set(resolved.key, next);
+  } catch {
+    // History access refused, or a router's own storage threw. Best effort,
+    // like storage.
+  }
+}
+
+function withoutColumnFilters(
+  filters: GridState["columnFilters"] | undefined,
+  excluded: ReadonlySet<string>,
+): GridState["columnFilters"] | undefined {
+  if (filters === undefined || excluded.size === 0) return filters;
+  return filters.filter((filter) => !excluded.has(filter.id));
+}
+
+/**
+ * The column filters a link carries: not on an opted-out column, and narrowing
+ * the rows. A filter that narrows nothing is a row the filter panel seeded or
+ * the user has not filled in yet; in a link it would only reopen an empty row.
+ */
+function linkableColumnFilters(
+  filters: GridState["columnFilters"] | undefined,
+  excluded: ReadonlySet<string>,
+): GridState["columnFilters"] | undefined {
+  return withoutColumnFilters(filters, excluded)?.filter(filterNarrowsRows);
+}
+
 function resolveKeys(persistence: TMDataGridPersistence | undefined) {
+  const url = resolveKey(persistence?.urlKey, DATA_STATE_SLICES);
+  const data = resolveKey(persistence?.dataKey, DATA_STATE_SLICES);
   return {
-    data: resolveKey(persistence?.dataKey, DATA_STATE_SLICES),
+    url,
+    // A slice lives in one group. The URL takes what both keys list, so a
+    // stored copy can never override the link that was opened.
+    data:
+      data !== null && url !== null
+        ? {
+            key: data.key,
+            slices: data.slices.filter((slice) => !url.slices.includes(slice)),
+          }
+        : data,
     settings: resolveKey(persistence?.settingsKey, SETTINGS_STATE_SLICES),
   };
 }
@@ -271,8 +458,27 @@ function resolveKeys(persistence: TMDataGridPersistence | undefined) {
 export function hasPersistenceKeys(
   persistence: TMDataGridPersistence | undefined,
 ): boolean {
-  const { data, settings } = resolveKeys(persistence);
-  return data !== null || settings !== null;
+  const { url, data, settings } = resolveKeys(persistence);
+  return url !== null || data !== null || settings !== null;
+}
+
+/**
+ * The data slices that a `dataKey` tuple names and `urlKey` also lists;
+ * `urlKey` takes them. A bare `dataKey` names no slice, so it reports nothing:
+ * "every data slice" plus a `urlKey` is the ordinary setup, and resolveKeys
+ * hands the URL its slices without a word. Only a slice named twice is a
+ * contradiction worth reporting.
+ */
+export function findOverlappingSlices(
+  persistence: TMDataGridPersistence | undefined,
+): TMDataGridDataSlice[] {
+  if (typeof persistence?.dataKey === "string") return [];
+  const url = resolveKey(persistence?.urlKey, DATA_STATE_SLICES);
+  const data = resolveKey(persistence?.dataKey, DATA_STATE_SLICES);
+  if (url === null || data === null) return [];
+  return DATA_STATE_SLICES.filter(
+    (slice) => url.slices.includes(slice) && data.slices.includes(slice),
+  );
 }
 
 const defaultDeserialize = (value: string): unknown => JSON.parse(value);
@@ -290,11 +496,34 @@ export function collectLeafColumnIds(
   defs: ReadonlyArray<unknown>,
   into: string[] = [],
 ): string[] {
+  forEachLeafColumnDef(defs, (id) => into.push(id));
+  return into;
+}
+
+/**
+ * The leaf column ids whose `meta.filter.url` is `false`, by the same id
+ * derivation as {@link collectLeafColumnIds}. Their filters stay out of the
+ * `urlKey` param, on read and on write.
+ */
+export function collectUrlExcludedColumnIds(
+  defs: ReadonlyArray<unknown>,
+  into: string[] = [],
+): string[] {
+  forEachLeafColumnDef(defs, (id, record) => {
+    if (prop(prop(record.meta, "filter"), "url") === false) into.push(id);
+  });
+  return into;
+}
+
+function forEachLeafColumnDef(
+  defs: ReadonlyArray<unknown>,
+  visit: (id: string, record: Record<string, unknown>) => void,
+): void {
   for (const def of defs) {
     if (typeof def !== "object" || def === null) continue;
     const record = def as Record<string, unknown>;
     if (Array.isArray(record.columns) && record.columns.length > 0) {
-      collectLeafColumnIds(record.columns, into);
+      forEachLeafColumnDef(record.columns, visit);
       continue;
     }
     const accessorKey =
@@ -303,9 +532,8 @@ export function collectLeafColumnIds(
       (typeof record.id === "string" ? record.id : undefined) ??
       accessorKey?.replaceAll(".", "_") ??
       (typeof record.header === "string" ? record.header : undefined);
-    if (id !== undefined) into.push(id);
+    if (id !== undefined) visit(id, record);
   }
-  return into;
 }
 
 /**
@@ -351,8 +579,25 @@ function realignToColumns(
   return realigned;
 }
 
+/** What the `urlKey` group needs beyond the persistence config itself. */
+export type TMDataGridUrlPersistInputs = {
+  /**
+   * The state the table starts with when nothing is restored: the grid's
+   * defaults merged with `initialState`. The URL carries only the slices that
+   * differ from it. Without it, every slice that has a value is written. On
+   * read, a column opted out of the URL keeps its filter from it.
+   */
+  baseline?: Partial<GridState>;
+  /** See {@link collectUrlExcludedColumnIds}. */
+  excludedFilterColumnIds?: ReadonlyArray<string>;
+  /** Whether a write touches the URL. Defaults to `true`; ignored on read. */
+  writeUrl?: boolean;
+};
+
 /**
- * State to merge into `initialState`, read once on mount.
+ * State to merge into `initialState`, read once on mount: settings, then data,
+ * then the URL. The groups are disjoint, since the URL takes the slices it
+ * shares with `dataKey`.
  *
  * With `knownColumnIds` - every id the grid is about to construct, generated
  * lanes included - the column-shaped slices are realigned first; see
@@ -361,28 +606,79 @@ function realignToColumns(
 export function readPersistedState(
   persistence?: TMDataGridPersistence,
   knownColumnIds?: ReadonlyArray<string>,
+  {
+    baseline = {},
+    excludedFilterColumnIds = [],
+  }: TMDataGridUrlPersistInputs = {},
 ): Partial<GridState> {
   const storage = resolveStorage(persistence);
-  const { data, settings } = resolveKeys(persistence);
+  const readStorage = storage ? (key: string) => storage.getItem(key) : null;
+  const urlStorage = resolveUrlStorage(persistence);
+  const readUrl = urlStorage ? (key: string) => urlStorage.get(key) : null;
+  const { url, data, settings } = resolveKeys(persistence);
   const deserialize = persistence?.deserialize ?? defaultDeserialize;
+  const fromUrl = readSlices({
+    read: readUrl,
+    resolved: url,
+    deserialize,
+    versioned: false,
+  });
+  if (fromUrl.columnFilters) {
+    // The link never speaks for an opted-out column - the write leaves those
+    // out of both sides - so such a column keeps its initial filter, which
+    // the restored slice would otherwise replace along with the rest.
+    const excluded = new Set(excludedFilterColumnIds);
+    fromUrl.columnFilters = [
+      ...(baseline.columnFilters ?? []).filter((filter) =>
+        excluded.has(filter.id),
+      ),
+      ...(withoutColumnFilters(fromUrl.columnFilters, excluded) ?? []),
+    ];
+  }
   const restored = {
-    ...readSlices(storage, settings, deserialize),
-    ...readSlices(storage, data, deserialize),
+    ...readSlices({
+      read: readStorage,
+      resolved: settings,
+      deserialize,
+      versioned: true,
+    }),
+    ...readSlices({
+      read: readStorage,
+      resolved: data,
+      deserialize,
+      versioned: true,
+    }),
+    ...fromUrl,
   };
   return knownColumnIds === undefined
     ? restored
     : realignToColumns(restored, new Set(knownColumnIds));
 }
 
-/** Writes both payloads. Called on every table state change. */
+/** Writes every configured payload. Called on every table state change. */
 export function writePersistedState(
   state: GridState,
   persistence?: TMDataGridPersistence,
+  {
+    baseline = {},
+    excludedFilterColumnIds = [],
+    writeUrl = true,
+  }: TMDataGridUrlPersistInputs = {},
 ): void {
+  const { url, data, settings } = resolveKeys(persistence);
+  const serialize = persistence?.serialize ?? defaultSerialize;
+  if (writeUrl) {
+    writeUrlSlices({
+      urlStorage: resolveUrlStorage(persistence),
+      resolved: url,
+      state,
+      baseline,
+      excludedFilterColumnIds: new Set(excludedFilterColumnIds),
+      serialize,
+    });
+  }
   const storage = resolveStorage(persistence);
   if (!storage) return;
-  const { data, settings } = resolveKeys(persistence);
-  const serialize = persistence?.serialize ?? defaultSerialize;
   writeSlices(storage, data, state, serialize);
   writeSlices(storage, settings, state, serialize);
 }

package/src/index.ts

@@ -262,6 +262,7 @@ export {
   type TMDataGridPersistKey,
   type TMDataGridSettingsSlice,
   type TMDataGridStorageMode,
+  type TMDataGridUrlStorage,
 } from "./core/persistence";
 export type {
   TMDataGridCellEventArgs,

package/src/useTMDataGrid.tsx

@@ -28,6 +28,7 @@ import {
   type DeepValue,
   type DisplayColumnDef,
   filterFns,
+  getInitialTableState,
   type GroupColumnDef,
   globalFilteringFeature,
   type IdentifiedColumnDef,
@@ -103,6 +104,8 @@ import {
 } from "./core/labels";
 import {
   collectLeafColumnIds,
+  collectUrlExcludedColumnIds,
+  findOverlappingSlices,
   hasPersistenceKeys,
   readPersistedState,
   type TMDataGridPersistence,
@@ -819,8 +822,9 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
       }
   ) & {
   /**
-   * Restore and persist table state across mounts. Two keys, because the two
-   * kinds of state have different lifetimes - see {@link TMDataGridPersistence}.
+   * Restore and persist table state across mounts. Two storage keys, because
+   * the two kinds of state have different lifetimes, and a URL search param
+   * for the data slices a link should carry - see {@link TMDataGridPersistence}.
    *
    * Keep the object referentially stable (module scope or `useMemo`); it is a
    * dependency of the subscription that writes back.
@@ -1132,6 +1136,17 @@ function withoutControlColumnVisibility(
   return scrubbed;
 }
 
+/**
+ * The pagination the table starts with before anything is restored. Shared by
+ * the table's `initialState` and the persistence baseline, so the URL param
+ * compares against the page size the table really starts on.
+ */
+function startingPagination(
+  initial: Partial<TableState<TMDataGridFeatures>> | undefined,
+): TableState<TMDataGridFeatures>["pagination"] {
+  return { pageIndex: 0, pageSize: 25, ...initial?.pagination };
+}
+
 /**
  * Point every column at the operator-dispatching filter function, and take
  * the aggregation defaults back off, unless the column opted into its own.
@@ -1377,13 +1392,34 @@ export function useTMDataGrid<TData extends RowData>({
     editColumnLabel,
   ]);
 
+  // Leaf columns whose filter stays out of the `urlKey` param. Follows the
+  // columns, since the write subscription below outlives a column change.
+  const urlExcludedColumnIds = useMemo(
+    () => collectUrlExcludedColumnIds(columns),
+    [columns],
+  );
+  // What the table would start with if nothing were restored: TanStack's
+  // feature defaults under the consumer's `initialState`, with the grid's own
+  // page size. The `urlKey` param carries only the slices that differ from
+  // it, and an opted-out column keeps its filter from it on read. Only the
+  // data slices are used, so the layout part of the `initialState` recipe
+  // below is not repeated here. Read once on mount, like `initialState`.
+  const [persistBaseline] = useState(() =>
+    getInitialTableState(tmDataGridFeatures, {
+      ...options.initialState,
+      pagination: startingPagination(options.initialState),
+    }),
+  );
   // Read once on mount: `initialState` is only consumed on the first render,
   // and re-reading later would fight the user's live edits.
   // Realigned against the ids this render is about to construct - lanes
   // included - so a column removed between deploys does not leave a ghost
   // sort, filter or width behind.
   const [persistedState] = useState(() =>
-    readPersistedState(persist, collectLeafColumnIds(columns)),
+    readPersistedState(persist, collectLeafColumnIds(columns), {
+      baseline: persistBaseline,
+      excludedFilterColumnIds: urlExcludedColumnIds,
+    }),
   );
 
   // Restored grouping decides whether the tree column starts out visible, so a
@@ -1731,9 +1767,7 @@ export function useTMDataGrid<TData extends RowData>({
           options.initialState?.columnPinning?.end,
       }),
       pagination: {
-        pageIndex: 0,
-        pageSize: 25,
-        ...options.initialState?.pagination,
+        ...startingPagination(options.initialState),
         ...persistedState.pagination,
       },
     },
@@ -1826,6 +1860,19 @@ export function useTMDataGrid<TData extends RowData>({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // A slice listed under both `dataKey` and `urlKey` is handled by `urlKey`
+  // alone - see resolveKeys in persistence.ts. Reported once, because the
+  // consumer most likely expects the stored copy to still apply.
+  useEffect(() => {
+    for (const slice of findOverlappingSlices(persist)) {
+      console.error(
+        `TMDataGrid: persist.dataKey and persist.urlKey both list ${slice} - a slice lives in one group; urlKey takes it.`,
+      );
+    }
+    // A mount-time contract, like the checks above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // The tree column appears with the first grouped column and goes away with
   // the last, so an ungrouped grid looks exactly as it did before grouping
   // existed. Driven from a subscription rather than by rebuilding the column
@@ -1892,33 +1939,67 @@ export function useTMDataGrid<TData extends RowData>({
   // selection - and `setItem` serialises synchronously on the main thread. The
   // trailing edge is enough: storage only has to agree with the table once the
   // user stops.
+  //
+  // The `urlKey` inputs are read through a ref: the excluded columns follow
+  // the column defs, and re-subscribing on a column change would write once
+  // more for nothing.
+  const urlPersistInputsRef = useRef({
+    baseline: persistBaseline,
+    excludedFilterColumnIds: urlExcludedColumnIds,
+  });
+  urlPersistInputsRef.current = {
+    baseline: persistBaseline,
+    excludedFilterColumnIds: urlExcludedColumnIds,
+  };
+  // Keyed on the store, not the table: `useTable` returns a new copy of the
+  // table on every render (it memoizes on the options object, built inline
+  // above), while every copy shares the one store. Keyed on the table, each
+  // render re-ran this effect, whose cleanup flushed and whose setup wrote
+  // again at once - no debounce at all.
+  const tableStore = table.store;
   useEffect(() => {
     if (!hasPersistenceKeys(persist)) return;
-    writePersistedState(table.store.state, persist);
+    writePersistedState(tableStore.state, persist, urlPersistInputsRef.current);
 
     let timeout: ReturnType<typeof setTimeout> | undefined;
     let pending: TableState<TMDataGridFeatures> | null = null;
 
-    const flush = () => {
+    const flush = ({ writeUrl }: { writeUrl: boolean }) => {
       timeout = undefined;
       if (pending === null) return;
-      writePersistedState(pending, persist);
+      writePersistedState(pending, persist, {
+        ...urlPersistInputsRef.current,
+        writeUrl,
+      });
       pending = null;
     };
 
-    const subscription = table.store.subscribe((state) => {
+    // Where the grid was when it subscribed, to tell an unmount by navigation
+    // from an in-page one - see the cleanup.
+    const subscribedPathname =
+      typeof window === "undefined" ? null : window.location.pathname;
+
+    const subscription = tableStore.subscribe((state) => {
       pending = state;
       if (timeout !== undefined) clearTimeout(timeout);
-      timeout = setTimeout(flush, PERSIST_DEBOUNCE_MS);
+      timeout = setTimeout(() => flush({ writeUrl: true }), PERSIST_DEBOUNCE_MS);
     });
 
     return () => {
       subscription.unsubscribe();
       if (timeout !== undefined) clearTimeout(timeout);
-      // An unmount mid-debounce would otherwise drop the last change.
-      flush();
+      // An unmount mid-debounce would otherwise drop the last change. The URL
+      // only while still on the page: an SPA navigation changes the pathname
+      // before React unmounts the grid, so the param would land on the next
+      // page's URL. An in-page unmount - a modal closing, a tab panel
+      // switching - leaves the pathname alone and keeps its last filter.
+      flush({
+        writeUrl:
+          subscribedPathname !== null &&
+          subscribedPathname === window.location.pathname,
+      });
     };
-  }, [persist, table]);
+  }, [persist, tableStore]);
 
   const ui = useCreateStore<TMDataGridUiState, TMDataGridUiActions>(
     {