@trackunit/react-table 2.1.57 → 2.1.58

package/index.cjs.js

@@ -7,6 +7,8 @@ var sharedUtils = require('@trackunit/shared-utils');
 var react = require('react');
 var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities');
 var reactRouter = require('@tanstack/react-router');
+var reactCoreHooks = require('@trackunit/react-core-hooks');
+var zod = require('zod');
 var reactFormComponents = require('@trackunit/react-form-components');
 var update = require('immutability-helper');
 var reactDnd = require('react-dnd');
@@ -375,6 +377,279 @@ const ActionSheet = ({ actions, dropdownActions, moreActions = [], selections, r
                 moreActions: moreActions.map(action => actionDataToMenuItem(action, dataTestId)) })] }));
 };
 
+/**
+ * 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 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 = zod.z.object({
+    l: zod.z.array(zod.z.string()).optional(),
+    r: zod.z.array(zod.z.string()).optional(),
+    left: zod.z.array(zod.z.string()).optional(),
+    right: zod.z.array(zod.z.string()).optional(),
+});
+/**
+ * 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 compactForUrl = (state) => {
+    const compact = {};
+    const columnVisibilityEntries = state.columnVisibility ? Object.entries(state.columnVisibility) : undefined;
+    const visibleColumns = columnVisibilityEntries?.filter(([, visible]) => visible).map(([key]) => key) ?? [];
+    const visibleColumnSet = new Set(visibleColumns);
+    if (state.columnVisibility && Object.keys(state.columnVisibility).length > 0) {
+        compact[URL_KEY_MAP.columnVisibility] = visibleColumns;
+    }
+    if (state.columnOrder && state.columnOrder.length > 0) {
+        compact[URL_KEY_MAP.columnOrder] =
+            state.columnVisibility && Object.keys(state.columnVisibility).length > 0
+                ? [
+                    ...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 compactRecordSchema = zod.z.record(zod.z.string(), zod.z.unknown());
+const visibilityArraySchema = zod.z.array(zod.z.string());
+const compactVisibilitySchema = zod.z
+    .object({
+    v: zod.z.array(zod.z.string()).optional(),
+    h: zod.z.array(zod.z.string()).optional(),
+})
+    .strict();
+/**
+ * Expands a compact URL-decoded object back into full TableColumnOptions shape.
+ */
+const expandFromUrl = (decoded) => {
+    const parsed = compactRecordSchema.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;
+    }
+    const visibilityResult = visibilityArraySchema.safeParse(expanded.columnVisibility);
+    if (visibilityResult.success) {
+        expanded.columnVisibility = Object.fromEntries([
+            [sharedUtils.VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, true],
+            ...visibilityResult.data.map(col => [col, true]),
+        ]);
+    }
+    const compactVisibilityResult = compactVisibilitySchema.safeParse(expanded.columnVisibility);
+    if (compactVisibilityResult.success) {
+        expanded.columnVisibility = Object.fromEntries([
+            ...(compactVisibilityResult.data.v ?? []).map(col => [col, true]),
+            ...(compactVisibilityResult.data.h ?? []).map(col => [col, false]),
+        ]);
+    }
+    const pinningResult = compactPinningSchema.safeParse(expanded.columnPinning);
+    if (pinningResult.success) {
+        expanded.columnPinning = {
+            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 = react.useCallback((state) => {
+        return compactForUrl(state);
+    }, []);
+    const fromUrlValue = react.useCallback((decoded) => {
+        return expandFromUrl(decoded);
+    }, []);
+    return react.useMemo(() => ({ toUrlValue, fromUrlValue }), [toUrlValue, fromUrlValue]);
+};
+
+const PERSISTENCE_KEY_MAX_LENGTH = 15;
+const camelCaseRegex = /^[a-z][a-zA-Z0-9]*$/;
+const persistenceKeySchema = zod.z
+    .string()
+    .max(PERSISTENCE_KEY_MAX_LENGTH, {
+    message: `persistenceKey must be at most ${PERSISTENCE_KEY_MAX_LENGTH} characters`,
+})
+    .regex(camelCaseRegex, {
+    message: "persistenceKey must be camelCase (start with lowercase letter, no underscores/hyphens)",
+});
+const expandedStateSchema = zod.z.union([zod.z.literal(true), zod.z.record(zod.z.string(), zod.z.boolean())]);
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+const tableStateSchema = zod.z.object({
+    columnOrder: zod.z.array(zod.z.string()).optional(),
+    sorting: zod.z.array(zod.z.object({ id: zod.z.string(), desc: zod.z.boolean() })).optional(),
+    columnVisibility: zod.z.record(zod.z.string(), zod.z.boolean()).optional(),
+    columnSizing: zod.z.record(zod.z.string(), zod.z.number()).optional(),
+    columnPinning: zod.z
+        .object({
+        left: zod.z.array(zod.z.string()).optional(),
+        right: zod.z.array(zod.z.string()).optional(),
+    })
+        .optional(),
+    expanded: expandedStateSchema.optional(),
+});
+const validateTableState = (raw) => {
+    const result = tableStateSchema.safeParse(raw);
+    return result.success ? result.data : undefined;
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * the URL **hash fragment** and localStorage.
+ *
+ * Storage scope:
+ * - 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 `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. Changes are
+ * debounced (300 ms) and synced to both the hash and localStorage.
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ * @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(", "));
+    }
+    const { clientSideUserId } = reactCoreHooks.useCurrentUser();
+    const localStorageEnabled = clientSideUserId !== undefined;
+    const { toUrlValue, fromUrlValue } = useCompactTableUrl();
+    const { initialState, persistState } = reactComponents.usePersistedState({
+        key: `${persistenceKey}Tp`,
+        validate: validateTableState,
+        toUrlValue,
+        fromUrlValue,
+        replace: false,
+        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.
+        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",
+    });
+    const [pendingState, setPendingState] = react.useState(null);
+    const debouncedPending = reactComponents.useDebounce(pendingState, { delay: 300 });
+    const currentState = react.useMemo(() => {
+        if (!debouncedPending && !initialState) {
+            return undefined;
+        }
+        const columnOrder = debouncedPending?.columnOrder ?? initialState?.columnOrder;
+        const columnSizing = debouncedPending?.columnSizing ?? initialState?.columnSizing;
+        const columnVisibility = debouncedPending?.columnVisibility ?? initialState?.columnVisibility;
+        const sorting = debouncedPending?.sorting ?? initialState?.sorting;
+        const columnPinning = debouncedPending?.columnPinning ?? initialState?.columnPinning;
+        const expanded = debouncedPending?.expanded ?? initialState?.expanded;
+        const state = {};
+        if (columnOrder && columnOrder.length > 0) {
+            state.columnOrder = columnOrder;
+        }
+        if (columnSizing && Object.keys(columnSizing).length > 0) {
+            state.columnSizing = columnSizing;
+        }
+        if (columnVisibility && Object.keys(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" && Object.keys(expanded).length > 0)) {
+            state.expanded = expanded;
+        }
+        return Object.keys(state).length > 0 ? state : undefined;
+    }, [debouncedPending, initialState]);
+    const onTableStateChange = react.useCallback((newTableState) => {
+        if (!newTableState) {
+            return;
+        }
+        setPendingState(newTableState);
+    }, []);
+    react.useEffect(() => {
+        if (!currentState) {
+            return;
+        }
+        persistState(currentState);
+    }, [currentState, persistState]);
+    return react.useMemo(() => ({
+        onTableStateChange,
+        initialState,
+    }), [initialState, onTableStateChange]);
+};
+
 const cvaColumnFilterGrabbable = cssClassVarianceUtilities.cvaMerge(["flex", "items-center", "justify-center"], {
     variants: {
         disabled: {
@@ -1778,4 +2053,5 @@ exports.fromTUSortToTanStack = fromTUSortToTanStack;
 exports.fromTanStackToTUSort = fromTanStackToTUSort;
 exports.useColumnHelper = useColumnHelper;
 exports.useTable = useTable;
+exports.useTablePersistence = useTablePersistence;
 exports.useTableSelection = useTableSelection;

package/index.esm.js

@@ -1,10 +1,12 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation, NamespaceTrans } from '@trackunit/i18n-library-translation';
-import { MenuItem, Icon, Button, Tooltip, useOverflowItems, MoreMenu, MenuList, Spacer, cvaInteractableItem, Text, Popover, PopoverTrigger, IconButton, PopoverContent, useBidirectionalScroll, noPagination, Card, Spinner, EmptyState } from '@trackunit/react-components';
+import { MenuItem, Icon, Button, Tooltip, useOverflowItems, MoreMenu, MenuList, Spacer, usePersistedState, useDebounce, cvaInteractableItem, Text, Popover, PopoverTrigger, IconButton, PopoverContent, useBidirectionalScroll, noPagination, Card, Spinner, EmptyState } from '@trackunit/react-components';
 import { objectValues, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, nonNullable, objectKeys, objectEntries } from '@trackunit/shared-utils';
-import { useMemo, Children, cloneElement, useRef, useState, useCallback, useEffect, createElement } from 'react';
+import { useMemo, Children, cloneElement, useCallback, useState, useEffect, useRef, createElement } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { Link } from '@tanstack/react-router';
+import { useCurrentUser } from '@trackunit/react-core-hooks';
+import { z } from 'zod';
 import { cvaLabel, ToggleSwitch, Search, RadioGroup, RadioItem, Checkbox } from '@trackunit/react-form-components';
 import update from 'immutability-helper';
 import { useDrop, useDrag, DndProvider } from 'react-dnd';
@@ -374,6 +376,279 @@ const ActionSheet = ({ actions, dropdownActions, moreActions = [], selections, r
                 moreActions: moreActions.map(action => actionDataToMenuItem(action, dataTestId)) })] }));
 };
 
+/**
+ * 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 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(),
+});
+/**
+ * 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 compactForUrl = (state) => {
+    const compact = {};
+    const columnVisibilityEntries = state.columnVisibility ? Object.entries(state.columnVisibility) : undefined;
+    const visibleColumns = columnVisibilityEntries?.filter(([, visible]) => visible).map(([key]) => key) ?? [];
+    const visibleColumnSet = new Set(visibleColumns);
+    if (state.columnVisibility && Object.keys(state.columnVisibility).length > 0) {
+        compact[URL_KEY_MAP.columnVisibility] = visibleColumns;
+    }
+    if (state.columnOrder && state.columnOrder.length > 0) {
+        compact[URL_KEY_MAP.columnOrder] =
+            state.columnVisibility && Object.keys(state.columnVisibility).length > 0
+                ? [
+                    ...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 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();
+/**
+ * Expands a compact URL-decoded object back into full TableColumnOptions shape.
+ */
+const expandFromUrl = (decoded) => {
+    const parsed = compactRecordSchema.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;
+    }
+    const visibilityResult = visibilityArraySchema.safeParse(expanded.columnVisibility);
+    if (visibilityResult.success) {
+        expanded.columnVisibility = Object.fromEntries([
+            [VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, true],
+            ...visibilityResult.data.map(col => [col, true]),
+        ]);
+    }
+    const compactVisibilityResult = compactVisibilitySchema.safeParse(expanded.columnVisibility);
+    if (compactVisibilityResult.success) {
+        expanded.columnVisibility = Object.fromEntries([
+            ...(compactVisibilityResult.data.v ?? []).map(col => [col, true]),
+            ...(compactVisibilityResult.data.h ?? []).map(col => [col, false]),
+        ]);
+    }
+    const pinningResult = compactPinningSchema.safeParse(expanded.columnPinning);
+    if (pinningResult.success) {
+        expanded.columnPinning = {
+            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]*$/;
+const persistenceKeySchema = z
+    .string()
+    .max(PERSISTENCE_KEY_MAX_LENGTH, {
+    message: `persistenceKey must be at most ${PERSISTENCE_KEY_MAX_LENGTH} characters`,
+})
+    .regex(camelCaseRegex, {
+    message: "persistenceKey must be camelCase (start with lowercase letter, no underscores/hyphens)",
+});
+const expandedStateSchema = z.union([z.literal(true), z.record(z.string(), z.boolean())]);
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+const tableStateSchema = z.object({
+    columnOrder: z.array(z.string()).optional(),
+    sorting: z.array(z.object({ id: z.string(), desc: z.boolean() })).optional(),
+    columnVisibility: z.record(z.string(), z.boolean()).optional(),
+    columnSizing: z.record(z.string(), z.number()).optional(),
+    columnPinning: z
+        .object({
+        left: z.array(z.string()).optional(),
+        right: z.array(z.string()).optional(),
+    })
+        .optional(),
+    expanded: expandedStateSchema.optional(),
+});
+const validateTableState = (raw) => {
+    const result = tableStateSchema.safeParse(raw);
+    return result.success ? result.data : undefined;
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * the URL **hash fragment** and localStorage.
+ *
+ * Storage scope:
+ * - 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 `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. Changes are
+ * debounced (300 ms) and synced to both the hash and localStorage.
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ * @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(", "));
+    }
+    const { clientSideUserId } = useCurrentUser();
+    const localStorageEnabled = clientSideUserId !== undefined;
+    const { toUrlValue, fromUrlValue } = useCompactTableUrl();
+    const { initialState, persistState } = usePersistedState({
+        key: `${persistenceKey}Tp`,
+        validate: validateTableState,
+        toUrlValue,
+        fromUrlValue,
+        replace: false,
+        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.
+        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",
+    });
+    const [pendingState, setPendingState] = useState(null);
+    const debouncedPending = useDebounce(pendingState, { delay: 300 });
+    const currentState = useMemo(() => {
+        if (!debouncedPending && !initialState) {
+            return undefined;
+        }
+        const columnOrder = debouncedPending?.columnOrder ?? initialState?.columnOrder;
+        const columnSizing = debouncedPending?.columnSizing ?? initialState?.columnSizing;
+        const columnVisibility = debouncedPending?.columnVisibility ?? initialState?.columnVisibility;
+        const sorting = debouncedPending?.sorting ?? initialState?.sorting;
+        const columnPinning = debouncedPending?.columnPinning ?? initialState?.columnPinning;
+        const expanded = debouncedPending?.expanded ?? initialState?.expanded;
+        const state = {};
+        if (columnOrder && columnOrder.length > 0) {
+            state.columnOrder = columnOrder;
+        }
+        if (columnSizing && Object.keys(columnSizing).length > 0) {
+            state.columnSizing = columnSizing;
+        }
+        if (columnVisibility && Object.keys(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" && Object.keys(expanded).length > 0)) {
+            state.expanded = expanded;
+        }
+        return Object.keys(state).length > 0 ? state : undefined;
+    }, [debouncedPending, initialState]);
+    const onTableStateChange = useCallback((newTableState) => {
+        if (!newTableState) {
+            return;
+        }
+        setPendingState(newTableState);
+    }, []);
+    useEffect(() => {
+        if (!currentState) {
+            return;
+        }
+        persistState(currentState);
+    }, [currentState, persistState]);
+    return useMemo(() => ({
+        onTableStateChange,
+        initialState,
+    }), [initialState, onTableStateChange]);
+};
+
 const cvaColumnFilterGrabbable = cvaMerge(["flex", "items-center", "justify-center"], {
     variants: {
         disabled: {
@@ -1763,4 +2038,4 @@ const fromTanStackToTUSort = (input) => {
  */
 setupLibraryTranslations();
 
-export { ActionSheet, ColumnFilter, SelectAllBanner, Sorting, Table, TableEvents, fromTUSortToTanStack, fromTanStackToTUSort, useColumnHelper, useTable, useTableSelection };
+export { ActionSheet, ColumnFilter, SelectAllBanner, Sorting, Table, TableEvents, fromTUSortToTanStack, fromTanStackToTUSort, useColumnHelper, useTable, useTablePersistence, useTableSelection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "2.1.57",
+  "version": "2.1.58",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -11,14 +11,16 @@
     "react-dnd": "16.0.1",
     "react-dnd-html5-backend": "16.0.1",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "2.1.52",
-    "@trackunit/shared-utils": "1.15.52",
+    "@trackunit/react-components": "2.1.53",
+    "@trackunit/react-core-hooks": "1.17.64",
+    "@trackunit/shared-utils": "1.15.53",
     "@trackunit/css-class-variance-utilities": "1.13.52",
     "@trackunit/ui-icons": "1.13.53",
-    "@trackunit/react-table-base-components": "2.1.55",
-    "@trackunit/react-form-components": "2.1.54",
-    "@trackunit/i18n-library-translation": "2.0.52",
-    "@trackunit/iris-app-runtime-core-api": "1.16.57"
+    "@trackunit/react-table-base-components": "2.1.56",
+    "@trackunit/react-form-components": "2.1.55",
+    "@trackunit/i18n-library-translation": "2.0.53",
+    "@trackunit/iris-app-runtime-core-api": "1.16.58",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.114.29",

package/src/hooks/useTablePersistence/useTablePersistence.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+declare const persistenceKeySchema: z.ZodString;
+export type PersistenceKey = z.infer<typeof persistenceKeySchema>;
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+declare const tableStateSchema: z.ZodObject<{
+    columnOrder: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sorting: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        desc: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        desc: boolean;
+    }, {
+        id: string;
+        desc: boolean;
+    }>, "many">>;
+    columnVisibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    columnSizing: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    columnPinning: z.ZodOptional<z.ZodObject<{
+        left: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        right: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        right?: string[] | undefined;
+        left?: string[] | undefined;
+    }, {
+        right?: string[] | undefined;
+        left?: string[] | undefined;
+    }>>;
+    expanded: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<true>, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>;
+}, "strip", z.ZodTypeAny, {
+    columnOrder?: string[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    sorting?: {
+        id: string;
+        desc: boolean;
+    }[] | undefined;
+    columnPinning?: {
+        right?: string[] | undefined;
+        left?: string[] | undefined;
+    } | undefined;
+    columnSizing?: Record<string, number> | undefined;
+    expanded?: true | Record<string, boolean> | undefined;
+}, {
+    columnOrder?: string[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    sorting?: {
+        id: string;
+        desc: boolean;
+    }[] | undefined;
+    columnPinning?: {
+        right?: string[] | undefined;
+        left?: string[] | undefined;
+    } | undefined;
+    columnSizing?: Record<string, number> | undefined;
+    expanded?: true | Record<string, boolean> | undefined;
+}>;
+export type TableColumnOptions = z.infer<typeof tableStateSchema>;
+type UseTablePersistenceResult = {
+    readonly onTableStateChange: (newTableState: Partial<TableColumnOptions> | null) => void;
+    readonly initialState: TableColumnOptions | undefined;
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * the URL **hash fragment** and localStorage.
+ *
+ * Storage scope:
+ * - 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 `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. Changes are
+ * debounced (300 ms) and synced to both the hash and localStorage.
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ * @throws {Error} If persistenceKey is not camelCase or exceeds 15 characters.
+ */
+export declare const useTablePersistence: (persistenceKey: PersistenceKey) => UseTablePersistenceResult;
+export {};

package/src/hooks/useTablePersistence/utils/useCompactTableUrl.d.ts

@@ -0,0 +1,24 @@
+import type { TableColumnOptions } from "../useTablePersistence";
+type CompactTableUrl = Record<string, unknown>;
+type UseCompactTableUrlReturn = {
+    readonly toUrlValue: (state: TableColumnOptions) => CompactTableUrl;
+    readonly fromUrlValue: (decoded: unknown) => unknown;
+};
+/**
+ * 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.
+ */
+export declare const useCompactTableUrl: () => UseCompactTableUrlReturn;
+export {};

package/src/index.d.ts

@@ -1,6 +1,7 @@
 import { ColumnSort } from "@tanstack/react-table";
 export * from "./ActionSheet/Actions";
 export * from "./ActionSheet/ActionSheet";
+export * from "./hooks/useTablePersistence/useTablePersistence";
 export * from "./menus/ColumnFilter";
 export * from "./menus/Sorting";
 export * from "./SelectAllBanner";