@trackunit/react-table 2.11.11-alpha-7afddbbe4cc.0 → 2.11.11

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, useRef, useEffect, useState, useCallback, createElement } from 'react';
+import { useMemo, Children, cloneElement, useCallback, useRef, useEffect, useState, createElement } from 'react';
 import { cva } from '@trackunit/css-class-variance-utilities';
 import { useCurrentUser } from '@trackunit/react-core-hooks';
 import { z } from 'zod';
@@ -364,88 +364,142 @@ const ActionSheet = ({ actions, dropdownActions, moreActions = [], selections, r
 };
 
 /**
- * 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.
+ * 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.
  */
-const toTableUrlValue = ({ expanded: _expanded, ...shareable }) => shareable;
+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(),
+});
 /**
- * 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.
+ * 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)
  */
-const LEGACY_URL_KEY_MAP = {
-    co: "columnOrder",
-    cv: "columnVisibility",
-    s: "sorting",
-    cp: "columnPinning",
-    cs: "columnSizing",
+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 recordSchema = z.record(z.string(), z.unknown());
-const legacyVisibleListSchema = z.array(z.string());
-const legacyVisibilitySchema = z
+const compactRecordSchema = z.record(z.string(), z.unknown());
+const visibilityArraySchema = z.array(z.string());
+const compactVisibilitySchema = 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(),
-});
 /**
- * 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.
+ * Expands a compact URL-decoded object back into full TableColumnOptions shape.
  */
-const fromTableUrlValue = (decoded) => {
-    const parsed = recordSchema.safeParse(decoded);
+const expandFromUrl = (decoded) => {
+    const parsed = compactRecordSchema.safeParse(decoded);
     if (!parsed.success) {
         return decoded;
     }
     const expanded = {};
     for (const [key, value] of Object.entries(parsed.data)) {
-        expanded[LEGACY_URL_KEY_MAP[key] ?? key] = value;
+        const fullKey = REVERSE_URL_KEY_MAP[key] ?? key;
+        expanded[fullKey] = value;
     }
-    const visibleList = legacyVisibleListSchema.safeParse(expanded.columnVisibility);
-    if (visibleList.success) {
+    const visibilityResult = visibilityArraySchema.safeParse(expanded.columnVisibility);
+    if (visibilityResult.success) {
         expanded.columnVisibility = Object.fromEntries([
             [VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, true],
-            ...visibleList.data.map(col => [col, true]),
+            ...visibilityResult.data.map(col => [col, true]),
         ]);
     }
-    const legacyVisibility = legacyVisibilitySchema.safeParse(expanded.columnVisibility);
-    if (legacyVisibility.success) {
+    const compactVisibilityResult = compactVisibilitySchema.safeParse(expanded.columnVisibility);
+    if (compactVisibilityResult.success) {
         expanded.columnVisibility = Object.fromEntries([
-            ...(legacyVisibility.data.v ?? []).map(col => [col, true]),
-            ...(legacyVisibility.data.h ?? []).map(col => [col, false]),
+            ...(compactVisibilityResult.data.v ?? []).map(col => [col, true]),
+            ...(compactVisibilityResult.data.h ?? []).map(col => [col, false]),
         ]);
     }
-    const legacyPinning = legacyPinningSchema.safeParse(expanded.columnPinning);
-    if (legacyPinning.success) {
+    const pinningResult = compactPinningSchema.safeParse(expanded.columnPinning);
+    if (pinningResult.success) {
         expanded.columnPinning = {
-            left: legacyPinning.data.l ?? legacyPinning.data.left ?? [],
-            right: legacyPinning.data.r ?? legacyPinning.data.right ?? [],
+            left: pinningResult.data.l ?? pinningResult.data.left ?? [],
+            right: pinningResult.data.r ?? pinningResult.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]*$/;
@@ -476,96 +530,69 @@ const validateTableState = (raw) => {
     const result = tableStateSchema.safeParse(raw);
     return result.success ? result.data : undefined;
 };
-/**
- * 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 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;
 /**
  * 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 through a gap where the current
- * id is unset: treating that gap as unowned would copy one person's layout into
- * the next user's scoped storage.
+ * 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.
  */
-const isOwnedBy = (ownerId, clientSideUserId) => ownerId === undefined || ownerId === clientSideUserId;
-/** Whether anything of `state` would reach the URL; a layout of only `expanded` has nothing to share. */
-const hasShareableFields = (state) => objectKeys(toTableUrlValue(state)).length > 0;
+const isOwnedByCurrentUser = (ownerId, clientSideUserId) => ownerId === undefined || ownerId === clientSideUserId;
 /**
  * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
- * localStorage and the URL **hash fragment**.
+ * the URL **hash fragment** and localStorage.
  *
  * Storage scope:
- * - localStorage: everything, scoped to the current user.
- * - URL hash (shareable): everything except `expanded`.
+ * - URL hash (shareable): `columnOrder`, `columnVisibility`, `sorting`, `columnPinning`, `columnSizing`.
+ * - localStorage: everything above plus `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 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).
- *
- * Changes reported before `clientSideUserId` resolves are held in React state
- * and written to the user's scoped storage and stamped into the hash once it
- * does. The id can also change while the table is mounted: releasing an
- * impersonated identity renews the token, and the new claims are published
- * before the page navigates away. Reported state is therefore tagged with the
- * identity that produced it and persisted only while that identity is current,
- * and the layout read on load is committed to storage only for the account
- * that opened the page, so a layout never crosses from one account into
- * another's scoped storage or into their hash on its own. An identity that
- * takes over and then edits saves what it sees on screen — the opener's hash
- * over its own stored layout — under its own key, the same as editing an
- * opened link.
+ * 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).
  *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
@@ -575,104 +602,145 @@ const hasShareableFields = (state) => objectKeys(toTableUrlValue(state)).length
  * @throws {Error} If persistenceKey is not camelCase or exceeds 15 characters.
  */
 const useTablePersistence = (persistenceKey) => {
-    // 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 parseResult = persistenceKeySchema.safeParse(persistenceKey);
+    if (!parseResult.success) {
+        throw new Error(parseResult.error.errors.map(e => e.message).join(", "));
+    }
     const { clientSideUserId } = useCurrentUser();
     const localStorageEnabled = clientSideUserId !== undefined;
-    const { initialState, persistToStorage, persistToUrl } = usePersistedState({
+    const { toUrlValue, fromUrlValue } = useCompactTableUrl();
+    const { initialState, persistState, clearState, commitHydratedState } = usePersistedState({
         key: `${persistenceKey}Tp`,
         validate: validateTableState,
-        toUrlValue: toTableUrlValue,
-        fromUrlValue: fromTableUrlValue,
+        toUrlValue,
+        fromUrlValue,
         // 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,
-        // `expanded` is kept out of the URL; the merge restores it from
-        // localStorage on read so it survives reloads.
+        // `toUrlValue` strips fields that should not be shareable from the URL.
+        // The merge restores omitted fields from localStorage on read so they
+        // survive 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,
     });
-    // Opening a shared URL saves its layout for the account that opened it: the
-    // first identity to resolve while the table is mounted. `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 sees the merge for
-    // the resolved account. An identity that takes over later does not commit:
-    // the hash on screen is the opener's layout, not theirs.
+    // 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);
     useEffect(() => {
-        if (clientSideUserId === undefined) {
+        if (clientSideUserId === undefined || openingUserIdRef.current !== undefined) {
+            return;
+        }
+        if (!commitHydratedState()) {
             return;
         }
-        openingUserIdRef.current ?? (openingUserIdRef.current = clientSideUserId);
-        if (initialState !== undefined && openingUserIdRef.current === clientSideUserId) {
-            persistToStorage(initialState);
+        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;
+        }
+        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;
         }
-    }, [clientSideUserId, initialState, persistToStorage]);
-    // Everything reported in this session, merged, with the identity it belongs
-    // to. `null` until the first report so a mount with no edits writes nothing.
-    // Reports merge into whatever is held, whoever holds it; which identity that
-    // is gets settled in render below, where `clientSideUserId` is current. The
-    // callback stays stable so consumers can hold on to it.
-    const [reported, setReported] = useState(null);
+        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]);
     const onTableStateChange = useCallback((newTableState) => {
         if (!newTableState) {
             return;
         }
-        setReported(previous => ({ ownerId: previous?.ownerId, state: { ...previous?.state, ...newTableState } }));
-    }, []);
-    // Settle ownership in the render where an identity is current: reports made
-    // while no identity was resolved belong to the one that resolves; reports
-    // owned by a different identity are discarded so the current one starts
-    // over from what it sees on screen. While the id is unset nothing is
-    // settled, so edits in the gap stay with their owner and are kept if that
-    // owner comes back.
-    if (reported !== null && clientSideUserId !== undefined && reported.ownerId !== clientSideUserId) {
-        setReported(previous => {
-            if (previous === null || previous.ownerId === clientSideUserId) {
-                return previous;
+        const reporterId = clientSideUserId;
+        const previousOwnerId = pendingOwnerIdRef.current;
+        if (!isOwnedByCurrentUser(previousOwnerId, reporterId)) {
+            if (reporterId === undefined) {
+                return;
             }
-            return previous.ownerId === undefined ? { ...previous, ownerId: clientSideUserId } : null;
-        });
-    }
-    // `undefined` before any report or while the report belongs to another
-    // identity; afterwards the full layout to persist, `{}` meaning "remove the
-    // entry", tagged with the identity it is persisted for.
-    const currentState = useMemo(() => {
-        if (reported === null || !isOwnedBy(reported.ownerId, clientSideUserId)) {
-            return undefined;
+            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;
         }
-        return { ownerId: clientSideUserId, state: pruneEmptyFields({ ...initialState, ...reported.state }) };
-    }, [clientSideUserId, initialState, reported]);
+        if (reporterId !== undefined) {
+            pendingOwnerIdRef.current = reporterId;
+        }
+        setPendingState(previousState => ({
+            ownerId: reporterId,
+            state: { ...previousState?.state, ...newTableState },
+        }));
+    }, [clientSideUserId]);
     useEffect(() => {
-        if (currentState === undefined) {
+        // 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;
         }
-        persistToStorage(objectKeys(currentState.state).length > 0 ? currentState.state : undefined);
-    }, [currentState, persistToStorage]);
-    // The debounced value carries the identity it was computed for, so a change
-    // of identity during the quiet period discards the pending write instead of
-    // stamping the previous identity's layout into the new one's hash. A layout
-    // whose shareable part is empty removes the hash entry even when a
-    // storage-only field such as `expanded` remains.
-    const debouncedState = useDebounce(currentState, { delay: URL_WRITE_DEBOUNCE_MS });
-    useEffect(() => {
-        if (debouncedState === undefined || !isOwnedBy(debouncedState.ownerId, clientSideUserId)) {
+        // 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) {
+            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();
             return;
         }
-        persistToUrl(hasShareableFields(debouncedState.state) ? debouncedState.state : undefined);
-    }, [clientSideUserId, debouncedState, persistToUrl]);
-    return useMemo(() => ({ onTableStateChange, initialState }), [initialState, onTableStateChange]);
+        persistState(currentState);
+    }, [clearState, clientSideUserId, currentState, debouncedPending, hasReportedChange, persistState]);
+    return useMemo(() => ({
+        onTableStateChange,
+        initialState,
+    }), [initialState, onTableStateChange]);
 };
 
 const cvaColumnFilterGrabbable = cva({
@@ -1713,8 +1781,6 @@ 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 ?? [])];
@@ -1743,12 +1809,6 @@ 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.
@@ -1783,47 +1843,42 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  */
 const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProps }) => {
     const stableColumns = useMemo(() => JSON.stringify(columns), [columns]);
-    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 columnsList = JSON.parse(stableColumns);
         const initialStateColumnVisibility = initialState?.columnVisibility;
         const shouldHideColumnsMissingFromInitialVisibility = initialStateColumnVisibility?.[VISIBLE_ONLY_COLUMN_VISIBILITY_KEY] === true;
-        return Object.fromEntries(objectEntries(columnDefaults.visibilityById).map(([columnId, visibleByDefault]) => {
-            if (columnDefaults.lockedVisibleIds.has(columnId)) {
-                return [columnId, true];
-            }
-            const savedVisibility = initialStateColumnVisibility?.[columnId];
-            if (savedVisibility !== undefined) {
-                return [columnId, savedVisibility];
+        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 [columnId, shouldHideColumnsMissingFromInitialVisibility ? false : visibleByDefault];
-        }));
-    }, [columnDefaults, initialState?.columnVisibility]);
+        });
+        return resultFromInitialState;
+    }, [stableColumns, initialState?.columnVisibility, reactTableProps.enableHiding]);
     const updatedInitialColumnOrder = useMemo(() => {
         const resultFromInitialState = initialState?.columnOrder ? [...initialState.columnOrder] : [];
-        columnDefaults.order.forEach(columnId => {
-            if (!resultFromInitialState.includes(columnId)) {
-                resultFromInitialState.push(columnId);
+        JSON.parse(stableColumns).forEach((column) => {
+            if (column.id && !resultFromInitialState.includes(column.id)) {
+                resultFromInitialState.push(column.id);
             }
         });
         return resultFromInitialState;
-    }, [columnDefaults, initialState?.columnOrder]);
+    }, [stableColumns, initialState?.columnOrder]);
     const stableUpdatedInitialColumnPinning = useMemo(() => {
         const pinningState = { left: [], right: [] };
         JSON.parse(stableColumns).forEach((column) => {
@@ -1883,37 +1938,21 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
     // defined — it originates from `baseState` — so the callbacks read it directly.
     const stateRef = useRef(state);
     stateRef.current = state;
-    // Advances the ref at once so several updaters from one event (Reset) build on each other.
-    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 what differs from the column defaults (see the hook's JSDoc); storing a default
-    // would freeze it under the user's layout.
+    // 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.
     const persistTableState = useCallback((nextState) => {
         if (!onTableStateChange) {
             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 nextColumnSizing = nextState.columnSizing;
+        if (!nextColumnSizing) {
+            onTableStateChange(nextState);
+            return;
         }
-        onTableStateChange(reported);
-    }, [onTableStateChange, columnDefaults, defaultColumnSizingById, stableUpdatedInitialColumnPinning]);
-    const isResizingColumnRef = useRef(false);
-    const sizingReportPendingRef = useRef(false);
+        const columnSizingToPersist = Object.fromEntries(objectEntries(nextColumnSizing).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
+        onTableStateChange({ ...nextState, columnSizing: columnSizingToPersist });
+    }, [onTableStateChange, defaultColumnSizingById]);
     const table = useReactTable({
         manualSorting: true,
         enableSortingRemoval: true,
@@ -1922,34 +1961,44 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
         getCoreRowModel: getCoreRowModel(),
         ...reactTableProps,
         onColumnVisibilityChange: value => {
-            persistTableState({ columnVisibility: applyUpdate("columnVisibility", value) });
+            const current = stateRef.current.columnVisibility;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, columnVisibility: next }));
+            persistTableState({ columnVisibility: next });
             reactTableProps.onColumnVisibilityChange?.(value);
         },
         onColumnSizingChange: value => {
-            const next = applyUpdate("columnSizing", value);
-            // A drag fires this on every pointer move; report it once, when the drag ends (effect below).
-            if (isResizingColumnRef.current) {
-                sizingReportPendingRef.current = true;
-            }
-            else {
-                persistTableState({ columnSizing: next });
-            }
+            const current = stateRef.current.columnSizing;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, columnSizing: next }));
+            persistTableState({ columnSizing: next });
             reactTableProps.onColumnSizingChange?.(value);
         },
         onColumnOrderChange: value => {
-            persistTableState({ columnOrder: applyUpdate("columnOrder", value) });
+            const current = stateRef.current.columnOrder;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, columnOrder: next }));
+            persistTableState({ columnOrder: next });
             reactTableProps.onColumnOrderChange?.(value);
         },
         onSortingChange: value => {
-            persistTableState({ sorting: applyUpdate("sorting", value) });
+            const current = stateRef.current.sorting;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, sorting: next }));
+            persistTableState({ sorting: next });
             reactTableProps.onSortingChange?.(value);
         },
         onColumnPinningChange: value => {
-            persistTableState({ columnPinning: applyUpdate("columnPinning", value) });
+            const current = stateRef.current.columnPinning;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, columnPinning: next }));
+            persistTableState({ columnPinning: next });
             reactTableProps.onColumnPinningChange?.(value);
         },
         onExpandedChange: value => {
-            const next = applyUpdate("expanded", value);
+            const current = stateRef.current.expanded;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, expanded: next }));
             if (reactTableProps.state?.expanded === undefined) {
                 persistTableState({ expanded: next });
             }
@@ -1958,15 +2007,6 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
         columns,
         state,
     });
-    const isResizingColumn = table.getState().columnSizingInfo.isResizingColumn !== false;
-    isResizingColumnRef.current = isResizingColumn;
-    // TanStack applies the final size before it clears the flag, so `stateRef` already holds it.
-    useEffect(() => {
-        if (!isResizingColumn && sizingReportPendingRef.current) {
-            sizingReportPendingRef.current = false;
-            persistTableState({ columnSizing: stateRef.current.columnSizing });
-        }
-    }, [isResizingColumn, persistTableState]);
     return useMemo(() => {
         return { table };
     }, [table]);