@trackunit/react-table 2.11.7 → 2.11.8-alpha-775ca1816d6.0

package/index.esm.js

@@ -3,7 +3,7 @@ import { registerTranslations, useNamespaceTranslation, NamespaceTrans } from '@
 import { Icon, MenuItem, Button, Tooltip, useOverflowItems, MoreMenu, MenuContent, Spacer, usePersistedState, useDebounce, Text, cvaInteractableItem, Popover, PopoverTrigger, IconButton, PopoverContent, cvaMenuList, cvaMenu, useBidirectionalScroll, noPagination, Card, HorizontalOverflowScroller, Spinner, EmptyState, SkeletonLabel } from '@trackunit/react-components';
 import { Link } from '@tanstack/react-router';
 import { objectValues, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, objectKeys, nonNullable, objectEntries } from '@trackunit/shared-utils';
-import { useMemo, Children, cloneElement, useCallback, useRef, useEffect, useState, createElement } from 'react';
+import { useMemo, Children, cloneElement, useEffect, useState, useCallback, useRef, createElement } from 'react';
 import { cva } from '@trackunit/css-class-variance-utilities';
 import { useCurrentUser } from '@trackunit/react-core-hooks';
 import { z } from 'zod';
@@ -364,142 +364,88 @@ const ActionSheet = ({ actions, dropdownActions, moreActions = [], selections, r
 };
 
 /**
- * Short keys used in URL-hash-encoded table state to minimize fragment
- * length. localStorage continues to use the full key names. The full URL
- * still benefits from the shorter payload — even though the hash fragment
- * is no longer subject to the AWS WAF query-string cap, the resulting
- * fragment is what shows in shared links and browser history entries.
+ * The URL projection of table state: everything except `expanded`.
+ *
+ * Row expansion is per-session, per-user detail and would make a shared link
+ * open rows the recipient has no interest in, so it lives only in
+ * localStorage. `usePersistedState`'s `mergeWithStorageOnRead` restores it on
+ * load. The remaining fields are written as-is; the gzip step in
+ * `useCustomEncoding` handles the size, and a value that reads back to the
+ * same shape it was written from cannot drift from storage.
  */
-const URL_KEY_MAP = {
-    columnOrder: "co",
-    columnVisibility: "cv",
-    sorting: "s",
-    columnPinning: "cp",
-    columnSizing: "cs",
-};
-const REVERSE_URL_KEY_MAP = Object.fromEntries(Object.entries(URL_KEY_MAP).map(([full, short]) => [short, full]));
-const compactPinningSchema = z.object({
-    l: z.array(z.string()).optional(),
-    r: z.array(z.string()).optional(),
-    left: z.array(z.string()).optional(),
-    right: z.array(z.string()).optional(),
-});
+const toTableUrlValue = ({ expanded: _expanded, ...shareable }) => shareable;
 /**
- * Compacts table state for URL encoding:
- * - Uses short keys (co, cv, s, cp)
- * - Stores columnVisibility as a visible-column array only
- * - Stores columnOrder as visible-column order when columnVisibility is available
- * - Drops empty pinning arrays
- * - Excludes `expanded` (not shareable)
+ * Short keys used by the compact URL format that was written before the hash
+ * carried the full state. Links and bookmarks with that format still exist,
+ * so reads keep accepting it.
  */
-const compactForUrl = (state) => {
-    const compact = {};
-    const columnVisibilityEntries = state.columnVisibility
-        ? Object.entries(state.columnVisibility).filter(([key]) => key !== VISIBLE_ONLY_COLUMN_VISIBILITY_KEY)
-        : undefined;
-    const visibleColumns = columnVisibilityEntries?.filter(([, visible]) => visible).map(([key]) => key) ?? [];
-    const visibleColumnSet = new Set(visibleColumns);
-    const hasColumnVisibility = (columnVisibilityEntries?.length ?? 0) > 0;
-    if (hasColumnVisibility) {
-        compact[URL_KEY_MAP.columnVisibility] = visibleColumns;
-    }
-    if (state.columnOrder && state.columnOrder.length > 0) {
-        compact[URL_KEY_MAP.columnOrder] = hasColumnVisibility
-            ? [
-                ...state.columnOrder.filter(columnId => visibleColumnSet.has(columnId)),
-                ...visibleColumns.filter(columnId => !state.columnOrder?.includes(columnId)),
-            ]
-            : state.columnOrder;
-    }
-    if (state.sorting && state.sorting.length > 0) {
-        compact[URL_KEY_MAP.sorting] = state.sorting;
-    }
-    if (state.columnSizing && Object.keys(state.columnSizing).length > 0) {
-        compact[URL_KEY_MAP.columnSizing] = state.columnSizing;
-    }
-    if (state.columnPinning) {
-        const pinning = {};
-        if (state.columnPinning.left && state.columnPinning.left.length > 0) {
-            pinning.l = state.columnPinning.left;
-        }
-        if (state.columnPinning.right && state.columnPinning.right.length > 0) {
-            pinning.r = state.columnPinning.right;
-        }
-        if (Object.keys(pinning).length > 0) {
-            compact[URL_KEY_MAP.columnPinning] = pinning;
-        }
-    }
-    return compact;
+const LEGACY_URL_KEY_MAP = {
+    co: "columnOrder",
+    cv: "columnVisibility",
+    s: "sorting",
+    cp: "columnPinning",
+    cs: "columnSizing",
 };
-const compactRecordSchema = z.record(z.string(), z.unknown());
-const visibilityArraySchema = z.array(z.string());
-const compactVisibilitySchema = z
+const recordSchema = z.record(z.string(), z.unknown());
+const legacyVisibleListSchema = z.array(z.string());
+const legacyVisibilitySchema = z
     .object({
     v: z.array(z.string()).optional(),
     h: z.array(z.string()).optional(),
 })
     .strict();
+const legacyPinningSchema = z.object({
+    l: z.array(z.string()).optional(),
+    r: z.array(z.string()).optional(),
+    left: z.array(z.string()).optional(),
+    right: z.array(z.string()).optional(),
+});
 /**
- * Expands a compact URL-decoded object back into full TableColumnOptions shape.
+ * Normalises a decoded URL value into the full `TableColumnOptions` shape.
+ *
+ * A value written by {@link toTableUrlValue} passes through unchanged, except
+ * that a `columnPinning` with one side missing gets the other side filled in
+ * as `[]`. Values in the legacy compact format are expanded:
+ * - short keys (`co`, `cv`, `s`, `cp`, `cs`) become full names;
+ * - a `columnVisibility` array of visible column IDs becomes a visible-only
+ *   map (see `VISIBLE_ONLY_COLUMN_VISIBILITY_KEY`);
+ * - a `columnVisibility` `{ v, h }` pair becomes explicit booleans;
+ * - `columnPinning` `{ l, r }` becomes `{ left, right }`.
+ *
+ * Non-object input is returned as-is so validation can reject it.
  */
-const expandFromUrl = (decoded) => {
-    const parsed = compactRecordSchema.safeParse(decoded);
+const fromTableUrlValue = (decoded) => {
+    const parsed = recordSchema.safeParse(decoded);
     if (!parsed.success) {
         return decoded;
     }
     const expanded = {};
     for (const [key, value] of Object.entries(parsed.data)) {
-        const fullKey = REVERSE_URL_KEY_MAP[key] ?? key;
-        expanded[fullKey] = value;
+        expanded[LEGACY_URL_KEY_MAP[key] ?? key] = value;
     }
-    const visibilityResult = visibilityArraySchema.safeParse(expanded.columnVisibility);
-    if (visibilityResult.success) {
+    const visibleList = legacyVisibleListSchema.safeParse(expanded.columnVisibility);
+    if (visibleList.success) {
         expanded.columnVisibility = Object.fromEntries([
             [VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, true],
-            ...visibilityResult.data.map(col => [col, true]),
+            ...visibleList.data.map(col => [col, true]),
         ]);
     }
-    const compactVisibilityResult = compactVisibilitySchema.safeParse(expanded.columnVisibility);
-    if (compactVisibilityResult.success) {
+    const legacyVisibility = legacyVisibilitySchema.safeParse(expanded.columnVisibility);
+    if (legacyVisibility.success) {
         expanded.columnVisibility = Object.fromEntries([
-            ...(compactVisibilityResult.data.v ?? []).map(col => [col, true]),
-            ...(compactVisibilityResult.data.h ?? []).map(col => [col, false]),
+            ...(legacyVisibility.data.v ?? []).map(col => [col, true]),
+            ...(legacyVisibility.data.h ?? []).map(col => [col, false]),
         ]);
     }
-    const pinningResult = compactPinningSchema.safeParse(expanded.columnPinning);
-    if (pinningResult.success) {
+    const legacyPinning = legacyPinningSchema.safeParse(expanded.columnPinning);
+    if (legacyPinning.success) {
         expanded.columnPinning = {
-            left: pinningResult.data.l ?? pinningResult.data.left ?? [],
-            right: pinningResult.data.r ?? pinningResult.data.right ?? [],
+            left: legacyPinning.data.l ?? legacyPinning.data.left ?? [],
+            right: legacyPinning.data.r ?? legacyPinning.data.right ?? [],
         };
     }
     return expanded;
 };
-/**
- * Provides transform functions for compacting table state before URL encoding
- * and expanding it back after URL decoding.
- *
- * The compaction strategy:
- * - Short property keys (columnOrder → co, columnVisibility → cv, etc.)
- * - columnVisibility stored as an array of visible column names only
- * - columnOrder stored as visible-column order when visibility is available
- * - columnSizing stored under a short key (`cs`)
- * - `expanded` is excluded from the URL and restored from localStorage via
- *   `usePersistedState`'s `mergeWithStorageOnRead`
- * - Empty pinning arrays are excluded
- *
- * These transforms are designed to plug into {@link usePersistedState}'s
- * `toUrlValue` and `fromUrlValue` options.
- */
-const useCompactTableUrl = () => {
-    const toUrlValue = useCallback((state) => {
-        return compactForUrl(state);
-    }, []);
-    const fromUrlValue = useCallback((decoded) => {
-        return expandFromUrl(decoded);
-    }, []);
-    return useMemo(() => ({ toUrlValue, fromUrlValue }), [toUrlValue, fromUrlValue]);
-};
 
 const PERSISTENCE_KEY_MAX_LENGTH = 15;
 const camelCaseRegex = /^[a-z][a-zA-Z0-9]*$/;
@@ -531,68 +477,77 @@ const validateTableState = (raw) => {
     return result.success ? result.data : undefined;
 };
 /**
- * Changes reported before `clientSideUserId` resolves carry no owner — the user
- * was already editing while their id was in flight — so the identity that
- * resolves adopts them. Once a defined identity owns the reported state it must
- * not be adopted by a later identity, including a brief window where the
- * current id is unset: treating that gap as unowned would copy one person's
- * layout into the next user's scoped storage.
+ * Drops fields that hold nothing (empty arrays, empty maps, pinning with no
+ * side) so a reset column is removed from storage rather than stored as empty.
  */
-const isOwnedByCurrentUser = (ownerId, clientSideUserId) => ownerId === undefined || ownerId === clientSideUserId;
+const pruneEmptyFields = (state) => {
+    const { columnOrder, columnSizing, columnVisibility, sorting, columnPinning, expanded } = state;
+    const pruned = {};
+    if (columnOrder && columnOrder.length > 0) {
+        pruned.columnOrder = columnOrder;
+    }
+    if (columnSizing && objectKeys(columnSizing).length > 0) {
+        pruned.columnSizing = columnSizing;
+    }
+    if (columnVisibility && objectKeys(columnVisibility).length > 0) {
+        pruned.columnVisibility = columnVisibility;
+    }
+    if (sorting && sorting.length > 0) {
+        pruned.sorting = sorting;
+    }
+    if (columnPinning && ((columnPinning.left?.length ?? 0) > 0 || (columnPinning.right?.length ?? 0) > 0)) {
+        pruned.columnPinning = columnPinning;
+    }
+    if (expanded === true || (typeof expanded === "object" && objectKeys(expanded).length > 0)) {
+        pruned.expanded = expanded;
+    }
+    return pruned;
+};
+const URL_WRITE_DEBOUNCE_MS = 300;
 /**
  * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
- * the URL **hash fragment** and localStorage.
+ * localStorage and the URL **hash fragment**.
  *
  * Storage scope:
- * - URL hash (shareable): `columnOrder`, `columnVisibility`, `sorting`, `columnPinning`, `columnSizing`.
- * - localStorage: everything above plus `expanded`.
+ * - localStorage: everything, scoped to the current user.
+ * - URL hash (shareable): everything except `expanded`.
  *
  * The hash slot is used instead of search params because some deployments
  * route through AWS WAF, whose `SizeRestrictions_QUERYSTRING` managed rule
  * caps the query string at ~5000 bytes — easily breached by wide tables.
  * The fragment is client-only and bypasses that cap entirely (subject to a
- * 64 KiB soft limit enforced by `useHashParamSync`).
- *
- * Legacy compatibility: shared links that still use `?<persistenceKey>Tp=`
- * search params from before the hash migration are decoded on first load
- * and the search param is stripped via a `replace` navigation so old
- * bookmarks and forwarded URLs continue to restore state without polluting
- * browser history.
- *
- * On mount, state is loaded from the hash (or legacy search param as a
- * one-shot fallback) and merged with localStorage so fields omitted from
- * the URL, such as `expanded`, still survive reloads. Opening that URL
- * saves the merged layout for the account that loaded the page, so a
- * pasted link sticks without a further edit. An account that becomes
- * current later, while the same URL is still open, does not receive that
- * write — their storage changes only when they edit the table. Switching
- * back to the opener does not write the hash that is on screen then.
- *
- * A layout that exists only in localStorage is not copied into the hash on
- * load. Doing that put the current layout into every history entry, so a
- * later visit via history, a bookmark, or a login redirect replayed an
- * older layout and saved it over the current one (GLU-2396). The hash is
- * written when the user changes the table, replacing the current history
- * entry, or when they open a URL that already carries one. A push per edit
- * would leave the same replayable entries behind.
- *
- * `onTableStateChange` takes a *partial* state and merges it into whatever
- * was reported earlier in the session, so a consumer can report a single
- * slice (e.g. only `expanded`) without the omitted fields falling back to
- * their mount-time values. A field reported empty is dropped from the stored
- * state, and once every field is empty the entry is removed altogether.
- *
- * Reported state is scoped to the identity that reported it: when the current
- * user changes, state reported by the previous user is discarded instead of
- * being written to the new user's storage. A layout shared through the URL
- * renders for anyone. It is saved for the account that opened the page, and
- * only becomes a later account's layout once that account changes the table.
- *
- * The hash always wins on load so a link or bookmark renders the same layout
- * for whoever opens it. Each hash write is stamped with the identity that
- * wrote it; the stamp is read only by the login redirect, which drops a hash
- * left behind by a *different* account that also uses this browser so
- * accounts sharing a PC do not hand their layouts to each other (GLU-2396).
+ * 64 KiB soft limit enforced by the URL sync).
+ *
+ * On load the hash wins, so a link or bookmark renders the same layout for
+ * whoever opens it, and localStorage fills in what the hash omits (`expanded`).
+ * Opening a URL that carries a layout saves it for the account that loaded the
+ * page, so a pasted link sticks without a further edit. A layout that exists
+ * only in localStorage is never copied into the hash on load: doing that put
+ * the current layout into every history entry, so a later visit via history,
+ * a bookmark, or a login redirect replayed an older layout and saved it over
+ * the current one (GLU-2396).
+ *
+ * `onTableStateChange` takes a *partial* state and merges it into whatever was
+ * reported earlier in the session, so a consumer can report a single slice
+ * (e.g. only `expanded`) without the omitted fields falling back to their
+ * mount-time values. A field reported empty is dropped from the stored state,
+ * and once every field is empty the entry is removed altogether.
+ *
+ * Each change is written to localStorage as soon as it is reported, so
+ * navigating away right after an edit cannot lose it. The hash is written
+ * after a {@link URL_WRITE_DEBOUNCE_MS} quiet period, replacing the current
+ * history entry: a drag or a run of toggles leaves one entry, not one per step.
+ *
+ * Every hash write is stamped with the identity that wrote it. The stamp is
+ * read only by the login redirect, which drops a hash left behind by another
+ * account that also uses this browser, so accounts sharing a PC do not hand
+ * their layouts to each other (GLU-2396).
+ *
+ * `clientSideUserId` only moves from unresolved to resolved while this hook
+ * is mounted; switching, impersonating, or releasing an identity reloads the
+ * page or navigates away from the table. Changes reported before the id
+ * resolves are held in React state and written to the user's scoped storage
+ * once it does.
  *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
@@ -602,145 +557,69 @@ const isOwnedByCurrentUser = (ownerId, clientSideUserId) => ownerId === undefine
  * @throws {Error} If persistenceKey is not camelCase or exceeds 15 characters.
  */
 const useTablePersistence = (persistenceKey) => {
-    const parseResult = persistenceKeySchema.safeParse(persistenceKey);
-    if (!parseResult.success) {
-        throw new Error(parseResult.error.errors.map(e => e.message).join(", "));
-    }
+    // The key is a constant per table; validate it once rather than every render.
+    useMemo(() => {
+        const parseResult = persistenceKeySchema.safeParse(persistenceKey);
+        if (!parseResult.success) {
+            throw new Error(parseResult.error.errors.map(e => e.message).join(", "));
+        }
+    }, [persistenceKey]);
     const { clientSideUserId } = useCurrentUser();
     const localStorageEnabled = clientSideUserId !== undefined;
-    const { toUrlValue, fromUrlValue } = useCompactTableUrl();
-    const { initialState, persistState, clearState, commitHydratedState } = usePersistedState({
+    const { initialState, persistToStorage, persistToUrl } = usePersistedState({
         key: `${persistenceKey}Tp`,
         validate: validateTableState,
-        toUrlValue,
-        fromUrlValue,
+        toUrlValue: toTableUrlValue,
+        fromUrlValue: fromTableUrlValue,
         // Replace, so a second edit updates this visit's history entry. A push
         // per column change left older layouts in history, and a later full load
         // of one of them saved that layout over the newer one (GLU-2396).
         replace: true,
         clientSideUserId,
         localStorageEnabled,
-        // `toUrlValue` strips fields that should not be shareable from the URL.
-        // The merge restores omitted fields from localStorage on read so they
-        // survive reloads.
+        // `expanded` is kept out of the URL; the merge restores it from
+        // localStorage on read so it survives reloads.
         mergeWithStorageOnRead: true,
-        // Move the persisted blob into the URL hash so it bypasses the AWS WAF
-        // query-string cap. `usePersistedState` also migrates any legacy
-        // `?<key>=...` search param into the hash on first load.
         urlLocation: "hash",
-        // The hash outlives the session that wrote it and is carried through the
-        // login redirect to the next account on the same browser. Stamp it with
-        // the writing identity so the redirect can drop another account's layout
-        // (GLU-2396). Reads are unaffected: the URL still wins for everyone.
         stampUrlWithIdentity: true,
     });
-    // Identity that reported the state currently held in `pendingState`.
-    const pendingOwnerIdRef = useRef(undefined);
-    // Set after the account that opened this page has had its one commit.
-    // A later account, and a switch back to the opener, must not write the
-    // hash that is on screen at that moment into storage. The ref stays empty
-    // until the commit succeeds, so a stale snapshot can still retry.
-    const openingUserIdRef = useRef(undefined);
+    // Opening a shared URL saves its layout for the account that opened it.
+    // `persistToStorage` dedupes against what storage held, so this writes only
+    // when the hash changed something; a reload of the account's own link, or a
+    // layout that came from storage alone, writes nothing. `initialState` is
+    // re-read in the render where `clientSideUserId` resolves, so the write
+    // always sees the merge for the resolved account.
     useEffect(() => {
-        if (clientSideUserId === undefined || openingUserIdRef.current !== undefined) {
-            return;
-        }
-        if (!commitHydratedState()) {
-            return;
-        }
-        openingUserIdRef.current = clientSideUserId;
-    }, [clientSideUserId, commitHydratedState]);
-    const [pendingState, setPendingState] = useState(null);
-    const debouncedPending = useDebounce(pendingState, { delay: 300 });
-    const hasReportedChange = debouncedPending !== null;
-    const currentState = useMemo(() => {
-        if (!debouncedPending && !initialState) {
-            return undefined;
+        if (initialState !== undefined) {
+            persistToStorage(initialState);
         }
-        const columnOrder = debouncedPending?.state.columnOrder ?? initialState?.columnOrder;
-        const columnSizing = debouncedPending?.state.columnSizing ?? initialState?.columnSizing;
-        const columnVisibility = debouncedPending?.state.columnVisibility ?? initialState?.columnVisibility;
-        const sorting = debouncedPending?.state.sorting ?? initialState?.sorting;
-        const columnPinning = debouncedPending?.state.columnPinning ?? initialState?.columnPinning;
-        const expanded = debouncedPending?.state.expanded ?? initialState?.expanded;
-        const state = {};
-        if (columnOrder && columnOrder.length > 0) {
-            state.columnOrder = columnOrder;
-        }
-        if (columnSizing && objectKeys(columnSizing).length > 0) {
-            state.columnSizing = columnSizing;
-        }
-        if (columnVisibility && objectKeys(columnVisibility).length > 0) {
-            state.columnVisibility = columnVisibility;
-        }
-        if (sorting && sorting.length > 0) {
-            state.sorting = sorting;
-        }
-        if (columnPinning && ((columnPinning.left?.length ?? 0) > 0 || (columnPinning.right?.length ?? 0) > 0)) {
-            state.columnPinning = columnPinning;
-        }
-        if (expanded === true || (typeof expanded === "object" && objectKeys(expanded).length > 0)) {
-            state.expanded = expanded;
-        }
-        return objectKeys(state).length > 0 || hasReportedChange ? state : undefined;
-    }, [debouncedPending, hasReportedChange, initialState]);
+    }, [initialState, persistToStorage]);
+    // Everything reported in this session, merged. `null` until the first report
+    // so a mount with no edits writes nothing.
+    const [reportedState, setReportedState] = useState(null);
     const onTableStateChange = useCallback((newTableState) => {
         if (!newTableState) {
             return;
         }
-        const reporterId = clientSideUserId;
-        const previousOwnerId = pendingOwnerIdRef.current;
-        if (!isOwnedByCurrentUser(previousOwnerId, reporterId)) {
-            if (reporterId === undefined) {
-                return;
-            }
-            pendingOwnerIdRef.current = reporterId;
-            // State left behind by another identity is dropped rather than merged, so
-            // this user's change builds on their own persisted state.
-            setPendingState({ ownerId: reporterId, state: { ...newTableState } });
-            return;
-        }
-        if (reporterId !== undefined) {
-            pendingOwnerIdRef.current = reporterId;
-        }
-        setPendingState(previousState => ({
-            ownerId: reporterId,
-            state: { ...previousState?.state, ...newTableState },
-        }));
-    }, [clientSideUserId]);
+        setReportedState(previous => ({ ...previous, ...newTableState }));
+    }, []);
+    // `undefined` before any report; afterwards the full layout to persist,
+    // `{}` meaning "remove the entry".
+    const currentState = useMemo(() => reportedState === null ? undefined : pruneEmptyFields({ ...initialState, ...reportedState }), [initialState, reportedState]);
     useEffect(() => {
-        // User edits write the URL and storage. Opening a shared URL writes
-        // storage on its own, via `commitHydratedState`, and must not be echoed
-        // through here — `persistState` treats the hydrated value as already saved.
-        if (!hasReportedChange || !currentState) {
-            return;
-        }
-        // Writing here after the current user changed would copy the previous
-        // user's reported state into this user's scoped storage — the debounced
-        // state outlives the identity that produced it.
-        const debouncedOwnerId = debouncedPending.ownerId;
-        const pendingOwnerId = pendingOwnerIdRef.current;
-        const hasCrossUserOwner = !isOwnedByCurrentUser(debouncedOwnerId, clientSideUserId) ||
-            !isOwnedByCurrentUser(pendingOwnerId, clientSideUserId);
-        const ownerChangedDuringDebounce = pendingOwnerId !== undefined && debouncedOwnerId !== pendingOwnerId;
-        if (hasCrossUserOwner || ownerChangedDuringDebounce) {
+        if (currentState === undefined) {
             return;
         }
-        // State reported before identity resolution is adopted by the first
-        // identity that resolves. Hydration-only runs cannot reach this branch.
-        if (debouncedOwnerId === undefined && clientSideUserId !== undefined) {
-            pendingOwnerIdRef.current = clientSideUserId;
-        }
-        if (objectKeys(currentState).length === 0) {
-            clearState();
+        persistToStorage(objectKeys(currentState).length > 0 ? currentState : undefined);
+    }, [currentState, persistToStorage]);
+    const debouncedState = useDebounce(currentState, { delay: URL_WRITE_DEBOUNCE_MS });
+    useEffect(() => {
+        if (debouncedState === undefined) {
             return;
         }
-        persistState(currentState);
-    }, [clearState, clientSideUserId, currentState, debouncedPending, hasReportedChange, persistState]);
-    return useMemo(() => ({
-        onTableStateChange,
-        initialState,
-    }), [initialState, onTableStateChange]);
+        persistToUrl(objectKeys(debouncedState).length > 0 ? debouncedState : undefined);
+    }, [debouncedState, persistToUrl]);
+    return useMemo(() => ({ onTableStateChange, initialState }), [initialState, onTableStateChange]);
 };
 
 const cvaColumnFilterGrabbable = cva({
@@ -1781,6 +1660,8 @@ const useColumnHelper = () => {
     }, []);
 };
 
+const areSameSequence = (left, right) => left.length === right.length && left.every((value, index) => value === right[index]);
+const isSamePinning = (left, right) => areSameSequence(left.left ?? [], right.left ?? []) && areSameSequence(left.right ?? [], right.right ?? []);
 const computeMergedPinning = (initialPinning, columnConfigPinning) => {
     const leftPinning = initialPinning?.left;
     const mergedLeft = leftPinning !== undefined && leftPinning.length > 0 ? [...leftPinning] : [...(columnConfigPinning.left ?? [])];
@@ -1809,6 +1690,12 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  *
  * `onTableStateChange` is called with the field that changed, not the whole state, so anything
  * storing it has to merge each report into what it already holds. `useTablePersistence` does.
+ * Within that field only what differs from the column definitions is reported — visibility
+ * entries equal to `meta.hiddenByDefault`, sizes equal to `size`, an order equal to the
+ * definition order, a pinning equal to `meta.pinned` — and an emptied field is reported empty.
+ * Defaults therefore belong on the column definitions; a value in `initialState` is read as
+ * saved state, not as a default. Columns without an explicit `id` take no part in the
+ * defaults (as before), so they are always reported once they are in the state.
  *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
@@ -1843,42 +1730,52 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  */
 const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProps }) => {
     const stableColumns = useMemo(() => JSON.stringify(columns), [columns]);
-    const updatedInitialColumnVisibility = useMemo(() => {
+    // The column definitions are the single source of defaults: `meta.hiddenByDefault`, definition
+    // order, `meta.pinned`, and `size`. They seed the state when `initialState` says nothing, and
+    // they are the baseline for what `onTableStateChange` reports (see `persistTableState`).
+    // Consumers that want a different default should set it on the column, not in `initialState`:
+    // a value in `initialState` is treated as saved state.
+    const columnDefaults = useMemo(() => {
         const columnsList = JSON.parse(stableColumns);
+        const visibilityById = {};
+        const lockedVisibleIds = new Set();
+        const order = [];
+        columnsList.forEach(column => {
+            if (column.id === undefined) {
+                return;
+            }
+            order.push(column.id);
+            const columnCannotHide = reactTableProps.enableHiding === false || column.enableHiding === false;
+            if (columnCannotHide) {
+                lockedVisibleIds.add(column.id);
+            }
+            visibilityById[column.id] = columnCannotHide ? true : column.meta?.hiddenByDefault !== true;
+        });
+        return { visibilityById, lockedVisibleIds, order };
+    }, [stableColumns, reactTableProps.enableHiding]);
+    const updatedInitialColumnVisibility = useMemo(() => {
         const initialStateColumnVisibility = initialState?.columnVisibility;
         const shouldHideColumnsMissingFromInitialVisibility = initialStateColumnVisibility?.[VISIBLE_ONLY_COLUMN_VISIBILITY_KEY] === true;
-        const resultFromInitialState = initialStateColumnVisibility
-            ? Object.fromEntries(columnsList
-                .map((column) => {
-                if (column.id && initialStateColumnVisibility[column.id] !== undefined) {
-                    const columnCannotHide = reactTableProps.enableHiding === false || column.enableHiding === false;
-                    return [column.id, columnCannotHide ? true : initialStateColumnVisibility[column.id]];
-                }
-                return null;
-            })
-                .filter(nonNullable))
-            : {};
-        columnsList.forEach((column) => {
-            if (column.id && resultFromInitialState[column.id] === undefined) {
-                const columnCannotHide = reactTableProps.enableHiding === false || column.enableHiding === false;
-                resultFromInitialState[column.id] = columnCannotHide
-                    ? true
-                    : shouldHideColumnsMissingFromInitialVisibility
-                        ? false
-                        : column.meta?.hiddenByDefault !== true;
+        return Object.fromEntries(objectEntries(columnDefaults.visibilityById).map(([columnId, visibleByDefault]) => {
+            if (columnDefaults.lockedVisibleIds.has(columnId)) {
+                return [columnId, true];
             }
-        });
-        return resultFromInitialState;
-    }, [stableColumns, initialState?.columnVisibility, reactTableProps.enableHiding]);
+            const savedVisibility = initialStateColumnVisibility?.[columnId];
+            if (savedVisibility !== undefined) {
+                return [columnId, savedVisibility];
+            }
+            return [columnId, shouldHideColumnsMissingFromInitialVisibility ? false : visibleByDefault];
+        }));
+    }, [columnDefaults, initialState?.columnVisibility]);
     const updatedInitialColumnOrder = useMemo(() => {
         const resultFromInitialState = initialState?.columnOrder ? [...initialState.columnOrder] : [];
-        JSON.parse(stableColumns).forEach((column) => {
-            if (column.id && !resultFromInitialState.includes(column.id)) {
-                resultFromInitialState.push(column.id);
+        columnDefaults.order.forEach(columnId => {
+            if (!resultFromInitialState.includes(columnId)) {
+                resultFromInitialState.push(columnId);
             }
         });
         return resultFromInitialState;
-    }, [stableColumns, initialState?.columnOrder]);
+    }, [columnDefaults, initialState?.columnOrder]);
     const stableUpdatedInitialColumnPinning = useMemo(() => {
         const pinningState = { left: [], right: [] };
         JSON.parse(stableColumns).forEach((column) => {
@@ -1936,23 +1833,46 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
     // A ref exposes the latest derived state to the change callbacks without making them depend on
     // it (callbacks run on user events, outside render). Every managed key on `state` is always
     // defined — it originates from `baseState` — so the callbacks read it directly.
+    //
+    // `applyUpdate` resolves a TanStack updater against that ref and advances the ref at once, so
+    // several updaters fired from one event (the column menu's Reset toggles every column that
+    // differs from its default in a single click) build on each other instead of each starting
+    // from the state as of the last render.
     const stateRef = useRef(state);
     stateRef.current = state;
+    const applyUpdate = (key, value) => {
+        const current = stateRef.current[key];
+        const next = typeof value === "function" ? value(current) : value;
+        stateRef.current = { ...stateRef.current, [key]: next };
+        setUserEdits(prev => ({ ...prev, [key]: next }));
+        return next;
+    };
     // Reports only the field that changed — `useTablePersistence` merges partial reports — so a
-    // change can never store another field's unsettled or transient value. Column sizes matching
-    // their default are dropped so only meaningful overrides are stored.
+    // change can never store another field's unsettled or transient value. Within a field, only
+    // what differs from the column defaults is reported: visibility entries equal to
+    // `hiddenByDefault`, sizes equal to the default size, an order equal to the definition order and
+    // a pinning equal to `meta.pinned` all read back the same when absent, so storing them would only
+    // freeze today's defaults under the user's layout and bloat what is shared. A field with nothing
+    // left is reported empty so the store can drop it.
     const persistTableState = useCallback((nextState) => {
         if (!onTableStateChange) {
             return;
         }
-        const nextColumnSizing = nextState.columnSizing;
-        if (!nextColumnSizing) {
-            onTableStateChange(nextState);
-            return;
+        const reported = { ...nextState };
+        if (nextState.columnVisibility) {
+            reported.columnVisibility = Object.fromEntries(objectEntries(nextState.columnVisibility).filter(([columnId, visible]) => columnDefaults.visibilityById[columnId] !== visible));
+        }
+        if (nextState.columnSizing) {
+            reported.columnSizing = Object.fromEntries(objectEntries(nextState.columnSizing).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
+        }
+        if (nextState.columnOrder && areSameSequence(nextState.columnOrder, columnDefaults.order)) {
+            reported.columnOrder = [];
+        }
+        if (nextState.columnPinning && isSamePinning(nextState.columnPinning, stableUpdatedInitialColumnPinning)) {
+            reported.columnPinning = { left: [], right: [] };
         }
-        const columnSizingToPersist = Object.fromEntries(objectEntries(nextColumnSizing).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
-        onTableStateChange({ ...nextState, columnSizing: columnSizingToPersist });
-    }, [onTableStateChange, defaultColumnSizingById]);
+        onTableStateChange(reported);
+    }, [onTableStateChange, columnDefaults, defaultColumnSizingById, stableUpdatedInitialColumnPinning]);
     const table = useReactTable({
         manualSorting: true,
         enableSortingRemoval: true,
@@ -1961,44 +1881,27 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
         getCoreRowModel: getCoreRowModel(),
         ...reactTableProps,
         onColumnVisibilityChange: value => {
-            const current = stateRef.current.columnVisibility;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, columnVisibility: next }));
-            persistTableState({ columnVisibility: next });
+            persistTableState({ columnVisibility: applyUpdate("columnVisibility", value) });
             reactTableProps.onColumnVisibilityChange?.(value);
         },
         onColumnSizingChange: value => {
-            const current = stateRef.current.columnSizing;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, columnSizing: next }));
-            persistTableState({ columnSizing: next });
+            persistTableState({ columnSizing: applyUpdate("columnSizing", value) });
             reactTableProps.onColumnSizingChange?.(value);
         },
         onColumnOrderChange: value => {
-            const current = stateRef.current.columnOrder;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, columnOrder: next }));
-            persistTableState({ columnOrder: next });
+            persistTableState({ columnOrder: applyUpdate("columnOrder", value) });
             reactTableProps.onColumnOrderChange?.(value);
         },
         onSortingChange: value => {
-            const current = stateRef.current.sorting;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, sorting: next }));
-            persistTableState({ sorting: next });
+            persistTableState({ sorting: applyUpdate("sorting", value) });
             reactTableProps.onSortingChange?.(value);
         },
         onColumnPinningChange: value => {
-            const current = stateRef.current.columnPinning;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, columnPinning: next }));
-            persistTableState({ columnPinning: next });
+            persistTableState({ columnPinning: applyUpdate("columnPinning", value) });
             reactTableProps.onColumnPinningChange?.(value);
         },
         onExpandedChange: value => {
-            const current = stateRef.current.expanded;
-            const next = typeof value === "function" ? value(current) : value;
-            setUserEdits(prev => ({ ...prev, expanded: next }));
+            const next = applyUpdate("expanded", value);
             if (reactTableProps.state?.expanded === undefined) {
                 persistTableState({ expanded: next });
             }