@trackunit/react-components 1.21.15 → 1.21.17

package/index.cjs.js

@@ -20,8 +20,9 @@ var reactVirtual = require('@tanstack/react-virtual');
 var reactHelmetAsync = require('react-helmet-async');
 var reactTabs = require('@radix-ui/react-tabs');
 var fflate = require('fflate');
-var zod = require('zod');
 var superjson = require('superjson');
+var zod = require('zod');
+var dequal = require('dequal');
 
 const cvaIcon = cssClassVarianceUtilities.cvaMerge(["aspect-square", "inline-grid", "relative", "shrink-0"], {
     variants: {
@@ -7829,14 +7830,15 @@ const getSheetPanelStyle = ({ snapHeight, isOpen, closePhase, variant, autoHeigh
         height: autoHeight ? "fit-content" : `var(--sheet-drag-height, ${snapHeight})`,
         maxHeight: maxHeight ?? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)`,
         pointerEvents: "auto",
-        transform: isOpen ? "translateY(0)" : "translateY(100%)",
-        transition: suppressTransition
+        transform: isOpen
+            ? "translateY(0) scale(var(--sheet-stack-scale, 1))"
+            : "translateY(100%) scale(var(--sheet-stack-scale, 1))",
+        transformOrigin: "bottom center",
+        transition: isDragging
             ? "none"
-            : isDragging
-                ? "none"
-                : autoHeight || !isOpen
-                    ? SHEET_TRANSFORM_TRANSITION
-                    : SHEET_OPEN_TRANSITION,
+            : suppressTransition || autoHeight || !isOpen
+                ? SHEET_TRANSFORM_TRANSITION
+                : SHEET_OPEN_TRANSITION,
     };
 };
 
@@ -10316,8 +10318,11 @@ const useCustomEncoding = () => {
             // If it's already a string, use it directly; otherwise stringify the object
             const json = typeof input === "string" ? input : JSON.stringify(input);
             const textInput = new TextEncoder().encode(json);
-            // Use fflate for synchronous gzip compression
-            const compressed = fflate.gzipSync(textInput);
+            // Use fflate for synchronous gzip compression.
+            // mtime: 0 ensures deterministic output — without it the gzip header
+            // includes the current timestamp, making the same input produce a
+            // different encoded string on every call.
+            const compressed = fflate.gzipSync(textInput, { mtime: 0 });
             return b64urlEncode(compressed);
         }
         catch (_) {
@@ -10369,6 +10374,36 @@ const useCustomEncoding = () => {
     return react.useMemo(() => ({ encode, decode }), [encode, decode]);
 };
 
+/**
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const taggedSuperjsonEnvelopeSchema = zod.z.object({
+    __serializer: zod.z.literal("superjson"),
+    json: zod.z.custom(),
+    meta: zod.z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
 /**
  * Runs a sequential migration pipeline on the provided data, applying
  * each migration whose version is in the range (fromVersion, toVersion].
@@ -10474,36 +10509,6 @@ const salvageState = (schema, rawData, defaultState) => {
     }
 };
 
-/**
- * Internal envelope used to tag superjson-serialized data in web storage.
- *
- * `__serializer` is a **reserved internal key** — consumer state objects must
- * not include it as a top-level key. The double-underscore prefix is a
- * deliberate signal that this is a private implementation detail.
- *
- * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
- * detected in the value being written.
- */
-const taggedSuperjsonEnvelopeSchema = zod.z.object({
-    __serializer: zod.z.literal("superjson"),
-    json: zod.z.custom(),
-    meta: zod.z.custom().optional(),
-});
-const storageSerializer = {
-    serialize: (value) => {
-        const serialized = superjson.serialize(value);
-        return JSON.stringify({ __serializer: "superjson", ...serialized });
-    },
-    deserialize: (value) => {
-        const parsed = JSON.parse(value);
-        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
-        if (result.success) {
-            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
-        }
-        return parsed;
-    },
-};
-
 /**
  * Internal envelope that pairs stored data with a schema version number.
  *
@@ -10979,6 +10984,202 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+const MAX_URL_LENGTH = 5000;
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Provides a write function that updates the URL through the application
+ * router (preserving other search params), guards against exceeding
+ * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
+ * back/forward, shared links) via an optional callback.
+ *
+ * @param options - Configuration for the search param sync.
+ * @param options.key - The URL search parameter name.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
+ */
+const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
+    const navigate = reactRouter.useNavigate();
+    const location = reactRouter.useLocation();
+    const search = reactRouter.useSearch({ strict: false, shouldThrow: false });
+    const lastWrittenRef = react.useRef(undefined);
+    const onExternalChangeRef = react.useRef(onExternalChange);
+    react.useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentSearchValue = react.useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        const value = search?.[key];
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        return undefined;
+    }, [enabled, search, key]);
+    react.useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (currentSearchValue === undefined) {
+            return;
+        }
+        if (currentSearchValue === lastWrittenRef.current) {
+            return;
+        }
+        if (lastWrittenRef.current === undefined) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            onExternalChangeRef.current?.();
+        });
+    }, [currentSearchValue, enabled]);
+    const getUrlLengthWithSearchParam = react.useCallback((paramKey, paramValue, params) => {
+        const otherParamsLength = sharedUtils.objectKeys(params)
+            .filter(k => k !== paramKey)
+            .reduce((totalLength, k) => {
+            const kLen = encodeURIComponent(String(k)).length;
+            const v = params[k];
+            const vLen = v !== null && v !== undefined ? encodeURIComponent(String(v)).length : 0;
+            return totalLength + kLen + vLen + (totalLength > 0 ? 2 : 1);
+        }, 0);
+        const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
+        return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
+    }, [location]);
+    const updateSearchParam = react.useCallback((encodedValue) => {
+        if (!enabled) {
+            return;
+        }
+        if (encodedValue !== undefined && encodedValue === lastWrittenRef.current) {
+            return;
+        }
+        lastWrittenRef.current = encodedValue;
+        if (currentSearchValue === encodedValue) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            const shouldReplace = replaceOption ?? !Boolean(currentSearchValue);
+            void navigate({
+                to: ".",
+                search: (prev) => {
+                    if (getUrlLengthWithSearchParam(key, encodedValue || "", prev) <= MAX_URL_LENGTH) {
+                        return { ...prev, [key]: encodedValue };
+                    }
+                    else {
+                        return { ...prev, [key]: undefined };
+                    }
+                },
+                hash: location.hash,
+                replace: shouldReplace,
+            });
+        });
+    }, [enabled, navigate, key, replaceOption, location.hash, getUrlLengthWithSearchParam, currentSearchValue]);
+    return react.useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
+};
+
+/**
+ * Generates a localStorage key, optionally scoped to a specific user.
+ *
+ * When `userId` is provided the key is `"key-userId"`.
+ * When omitted the key is returned as-is (unscoped).
+ *
+ * @param key - Unique persistence identifier.
+ * @param userId - Client-side user id to scope storage per user.
+ * @returns {string} The combined storage key.
+ */
+const useStorageKey = (key, userId) => {
+    return react.useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
+};
+
+/**
+ * Generic persistence hook that loads state from URL search params (with
+ * localStorage fallback) and writes changes to both.
+ *
+ * On mount the hook tries, in order:
+ *  1. Decode the URL search param and pass it through `validate`.
+ *  2. If that yields nothing, read localStorage and pass the parsed JSON through `validate`.
+ *
+ * `persistState` writes the state to localStorage (via `serialize`, default
+ * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
+ * Duplicate writes where the state has not changed (deep equality) are skipped.
+ *
+ * @param options - Configuration for the persisted state.
+ * @param options.key - Unique identifier used for both the URL search param and the localStorage key.
+ * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
+ * @param options.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
+ * @param options.toUrlValue - Transform applied before URL encoding (default: encode state as-is).
+ * @param options.fromUrlValue - Transform applied after URL decoding, before validation (default: identity).
+ * @param options.enabled - When `false` the URL is neither read nor written (default `true`).
+ * @param options.onExternalChange - Fired when the URL param changes externally (e.g. browser back).
+ * @param options.replace - Forwarded to `useSearchParamSync`.
+ * @param options.clientSideUserId - The user ID to use for the localStorage key.
+ */
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, onExternalChange, replace, clientSideUserId, }) => {
+    const { encode, decode } = useCustomEncoding();
+    const { searchValue, updateSearchParam } = useSearchParamSync({
+        key,
+        enabled,
+        onExternalChange,
+        replace,
+    });
+    const storageKey = useStorageKey(key, clientSideUserId);
+    const validateRef = react.useRef(validate);
+    react.useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
+    const toUrlValueRef = react.useRef(toUrlValue);
+    react.useEffect(() => {
+        toUrlValueRef.current = toUrlValue;
+    }, [toUrlValue]);
+    const fromUrlValueRef = react.useRef(fromUrlValue);
+    react.useEffect(() => {
+        fromUrlValueRef.current = fromUrlValue;
+    }, [fromUrlValue]);
+    const serializeRef = react.useRef(serialize);
+    react.useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const [initialState] = react.useState(() => {
+        if (enabled && searchValue) {
+            try {
+                const decoded = decode(searchValue);
+                const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
+                const validated = validate(transformed);
+                if (validated !== undefined) {
+                    return validated;
+                }
+            }
+            catch {
+                // fall through to localStorage
+            }
+        }
+        try {
+            const raw = localStorage.getItem(storageKey);
+            if (raw) {
+                const parsed = storageSerializer.deserialize(raw);
+                return validate(parsed);
+            }
+        }
+        catch {
+            // no valid stored state
+        }
+        return undefined;
+    });
+    const lastPersistedRef = react.useRef(initialState);
+    const persistState = react.useCallback((state) => {
+        if (dequal.dequal(lastPersistedRef.current, state)) {
+            return;
+        }
+        lastPersistedRef.current = state;
+        const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
+        localStorage.setItem(storageKey, serialized);
+        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
+        updateSearchParam(encode(urlValue));
+    }, [storageKey, encode, updateSearchParam]);
+    return react.useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
+};
+
 const OVERSCAN = 10;
 const DEFAULT_ROW_HEIGHT = 50;
 /**
@@ -12154,6 +12355,7 @@ exports.KPICardSkeleton = KPICardSkeleton;
 exports.KPISkeleton = KPISkeleton;
 exports.List = List;
 exports.ListItem = ListItem;
+exports.MAX_URL_LENGTH = MAX_URL_LENGTH;
 exports.MenuDivider = MenuDivider;
 exports.MenuItem = MenuItem;
 exports.MenuList = MenuList;
@@ -12255,6 +12457,7 @@ exports.iconColorNames = iconColorNames;
 exports.iconPalette = iconPalette;
 exports.noPagination = noPagination;
 exports.preferenceCardGrid = preferenceCardGrid;
+exports.storageSerializer = storageSerializer;
 exports.useBidirectionalScroll = useBidirectionalScroll;
 exports.useClickOutside = useClickOutside;
 exports.useContainerBreakpoints = useContainerBreakpoints;
@@ -12282,6 +12485,7 @@ exports.useMergeRefs = useMergeRefs;
 exports.useModifierKey = useModifierKey;
 exports.useOverflowBorder = useOverflowBorder;
 exports.useOverflowItems = useOverflowItems;
+exports.usePersistedState = usePersistedState;
 exports.usePopoverContext = usePopoverContext;
 exports.usePrevious = usePrevious;
 exports.usePrompt = usePrompt;
@@ -12290,11 +12494,13 @@ exports.useRelayPagination = useRelayPagination;
 exports.useResize = useResize;
 exports.useScrollBlock = useScrollBlock;
 exports.useScrollDetection = useScrollDetection;
+exports.useSearchParamSync = useSearchParamSync;
 exports.useSelfUpdatingRef = useSelfUpdatingRef;
 exports.useSessionStorage = useSessionStorage;
 exports.useSessionStorageReducer = useSessionStorageReducer;
 exports.useSheet = useSheet;
 exports.useSheetSnap = useSheetSnap;
+exports.useStorageKey = useStorageKey;
 exports.useTextSearch = useTextSearch;
 exports.useTimeout = useTimeout;
 exports.useViewportBreakpoints = useViewportBreakpoints;

package/index.esm.js

@@ -10,7 +10,7 @@ import IconSpriteSolid from '@trackunit/ui-icons/icons-sprite-solid.svg';
 import { snakeCase, titleCase } from 'string-ts';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { Slot, Slottable } from '@radix-ui/react-slot';
-import { Link, useBlocker, useSearch, useNavigate } from '@tanstack/react-router';
+import { Link, useBlocker, useNavigate, useLocation, useSearch } from '@tanstack/react-router';
 import { isEqual, omit } from 'es-toolkit';
 import { useFloating, offset, flip, shift, size, autoUpdate, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } from '@floating-ui/react';
 import { twMerge } from 'tailwind-merge';
@@ -18,8 +18,9 @@ import { useVirtualizer } from '@tanstack/react-virtual';
 import { HelmetProvider, Helmet } from 'react-helmet-async';
 import { Trigger, Content as Content$1, List as List$1, Root } from '@radix-ui/react-tabs';
 import { gzipSync, gunzipSync } from 'fflate';
-import { z } from 'zod';
 import superjson from 'superjson';
+import { z } from 'zod';
+import { dequal } from 'dequal';
 
 const cvaIcon = cvaMerge(["aspect-square", "inline-grid", "relative", "shrink-0"], {
     variants: {
@@ -7827,14 +7828,15 @@ const getSheetPanelStyle = ({ snapHeight, isOpen, closePhase, variant, autoHeigh
         height: autoHeight ? "fit-content" : `var(--sheet-drag-height, ${snapHeight})`,
         maxHeight: maxHeight ?? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)`,
         pointerEvents: "auto",
-        transform: isOpen ? "translateY(0)" : "translateY(100%)",
-        transition: suppressTransition
+        transform: isOpen
+            ? "translateY(0) scale(var(--sheet-stack-scale, 1))"
+            : "translateY(100%) scale(var(--sheet-stack-scale, 1))",
+        transformOrigin: "bottom center",
+        transition: isDragging
             ? "none"
-            : isDragging
-                ? "none"
-                : autoHeight || !isOpen
-                    ? SHEET_TRANSFORM_TRANSITION
-                    : SHEET_OPEN_TRANSITION,
+            : suppressTransition || autoHeight || !isOpen
+                ? SHEET_TRANSFORM_TRANSITION
+                : SHEET_OPEN_TRANSITION,
     };
 };
 
@@ -10314,8 +10316,11 @@ const useCustomEncoding = () => {
             // If it's already a string, use it directly; otherwise stringify the object
             const json = typeof input === "string" ? input : JSON.stringify(input);
             const textInput = new TextEncoder().encode(json);
-            // Use fflate for synchronous gzip compression
-            const compressed = gzipSync(textInput);
+            // Use fflate for synchronous gzip compression.
+            // mtime: 0 ensures deterministic output — without it the gzip header
+            // includes the current timestamp, making the same input produce a
+            // different encoded string on every call.
+            const compressed = gzipSync(textInput, { mtime: 0 });
             return b64urlEncode(compressed);
         }
         catch (_) {
@@ -10367,6 +10372,36 @@ const useCustomEncoding = () => {
     return useMemo(() => ({ encode, decode }), [encode, decode]);
 };
 
+/**
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const taggedSuperjsonEnvelopeSchema = z.object({
+    __serializer: z.literal("superjson"),
+    json: z.custom(),
+    meta: z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
 /**
  * Runs a sequential migration pipeline on the provided data, applying
  * each migration whose version is in the range (fromVersion, toVersion].
@@ -10472,36 +10507,6 @@ const salvageState = (schema, rawData, defaultState) => {
     }
 };
 
-/**
- * Internal envelope used to tag superjson-serialized data in web storage.
- *
- * `__serializer` is a **reserved internal key** — consumer state objects must
- * not include it as a top-level key. The double-underscore prefix is a
- * deliberate signal that this is a private implementation detail.
- *
- * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
- * detected in the value being written.
- */
-const taggedSuperjsonEnvelopeSchema = z.object({
-    __serializer: z.literal("superjson"),
-    json: z.custom(),
-    meta: z.custom().optional(),
-});
-const storageSerializer = {
-    serialize: (value) => {
-        const serialized = superjson.serialize(value);
-        return JSON.stringify({ __serializer: "superjson", ...serialized });
-    },
-    deserialize: (value) => {
-        const parsed = JSON.parse(value);
-        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
-        if (result.success) {
-            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
-        }
-        return parsed;
-    },
-};
-
 /**
  * Internal envelope that pairs stored data with a schema version number.
  *
@@ -10977,6 +10982,202 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+const MAX_URL_LENGTH = 5000;
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Provides a write function that updates the URL through the application
+ * router (preserving other search params), guards against exceeding
+ * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
+ * back/forward, shared links) via an optional callback.
+ *
+ * @param options - Configuration for the search param sync.
+ * @param options.key - The URL search parameter name.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
+ */
+const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const search = useSearch({ strict: false, shouldThrow: false });
+    const lastWrittenRef = useRef(undefined);
+    const onExternalChangeRef = useRef(onExternalChange);
+    useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentSearchValue = useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        const value = search?.[key];
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        return undefined;
+    }, [enabled, search, key]);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (currentSearchValue === undefined) {
+            return;
+        }
+        if (currentSearchValue === lastWrittenRef.current) {
+            return;
+        }
+        if (lastWrittenRef.current === undefined) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            onExternalChangeRef.current?.();
+        });
+    }, [currentSearchValue, enabled]);
+    const getUrlLengthWithSearchParam = useCallback((paramKey, paramValue, params) => {
+        const otherParamsLength = objectKeys(params)
+            .filter(k => k !== paramKey)
+            .reduce((totalLength, k) => {
+            const kLen = encodeURIComponent(String(k)).length;
+            const v = params[k];
+            const vLen = v !== null && v !== undefined ? encodeURIComponent(String(v)).length : 0;
+            return totalLength + kLen + vLen + (totalLength > 0 ? 2 : 1);
+        }, 0);
+        const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
+        return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
+    }, [location]);
+    const updateSearchParam = useCallback((encodedValue) => {
+        if (!enabled) {
+            return;
+        }
+        if (encodedValue !== undefined && encodedValue === lastWrittenRef.current) {
+            return;
+        }
+        lastWrittenRef.current = encodedValue;
+        if (currentSearchValue === encodedValue) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            const shouldReplace = replaceOption ?? !Boolean(currentSearchValue);
+            void navigate({
+                to: ".",
+                search: (prev) => {
+                    if (getUrlLengthWithSearchParam(key, encodedValue || "", prev) <= MAX_URL_LENGTH) {
+                        return { ...prev, [key]: encodedValue };
+                    }
+                    else {
+                        return { ...prev, [key]: undefined };
+                    }
+                },
+                hash: location.hash,
+                replace: shouldReplace,
+            });
+        });
+    }, [enabled, navigate, key, replaceOption, location.hash, getUrlLengthWithSearchParam, currentSearchValue]);
+    return useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
+};
+
+/**
+ * Generates a localStorage key, optionally scoped to a specific user.
+ *
+ * When `userId` is provided the key is `"key-userId"`.
+ * When omitted the key is returned as-is (unscoped).
+ *
+ * @param key - Unique persistence identifier.
+ * @param userId - Client-side user id to scope storage per user.
+ * @returns {string} The combined storage key.
+ */
+const useStorageKey = (key, userId) => {
+    return useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
+};
+
+/**
+ * Generic persistence hook that loads state from URL search params (with
+ * localStorage fallback) and writes changes to both.
+ *
+ * On mount the hook tries, in order:
+ *  1. Decode the URL search param and pass it through `validate`.
+ *  2. If that yields nothing, read localStorage and pass the parsed JSON through `validate`.
+ *
+ * `persistState` writes the state to localStorage (via `serialize`, default
+ * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
+ * Duplicate writes where the state has not changed (deep equality) are skipped.
+ *
+ * @param options - Configuration for the persisted state.
+ * @param options.key - Unique identifier used for both the URL search param and the localStorage key.
+ * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
+ * @param options.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
+ * @param options.toUrlValue - Transform applied before URL encoding (default: encode state as-is).
+ * @param options.fromUrlValue - Transform applied after URL decoding, before validation (default: identity).
+ * @param options.enabled - When `false` the URL is neither read nor written (default `true`).
+ * @param options.onExternalChange - Fired when the URL param changes externally (e.g. browser back).
+ * @param options.replace - Forwarded to `useSearchParamSync`.
+ * @param options.clientSideUserId - The user ID to use for the localStorage key.
+ */
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, onExternalChange, replace, clientSideUserId, }) => {
+    const { encode, decode } = useCustomEncoding();
+    const { searchValue, updateSearchParam } = useSearchParamSync({
+        key,
+        enabled,
+        onExternalChange,
+        replace,
+    });
+    const storageKey = useStorageKey(key, clientSideUserId);
+    const validateRef = useRef(validate);
+    useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
+    const toUrlValueRef = useRef(toUrlValue);
+    useEffect(() => {
+        toUrlValueRef.current = toUrlValue;
+    }, [toUrlValue]);
+    const fromUrlValueRef = useRef(fromUrlValue);
+    useEffect(() => {
+        fromUrlValueRef.current = fromUrlValue;
+    }, [fromUrlValue]);
+    const serializeRef = useRef(serialize);
+    useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const [initialState] = useState(() => {
+        if (enabled && searchValue) {
+            try {
+                const decoded = decode(searchValue);
+                const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
+                const validated = validate(transformed);
+                if (validated !== undefined) {
+                    return validated;
+                }
+            }
+            catch {
+                // fall through to localStorage
+            }
+        }
+        try {
+            const raw = localStorage.getItem(storageKey);
+            if (raw) {
+                const parsed = storageSerializer.deserialize(raw);
+                return validate(parsed);
+            }
+        }
+        catch {
+            // no valid stored state
+        }
+        return undefined;
+    });
+    const lastPersistedRef = useRef(initialState);
+    const persistState = useCallback((state) => {
+        if (dequal(lastPersistedRef.current, state)) {
+            return;
+        }
+        lastPersistedRef.current = state;
+        const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
+        localStorage.setItem(storageKey, serialized);
+        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
+        updateSearchParam(encode(urlValue));
+    }, [storageKey, encode, updateSearchParam]);
+    return useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
+};
+
 const OVERSCAN = 10;
 const DEFAULT_ROW_HEIGHT = 50;
 /**
@@ -12121,4 +12322,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MAX_URL_LENGTH, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, storageSerializer, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.21.15",
+  "version": "1.21.17",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -19,9 +19,10 @@
     "@trackunit/ui-icons": "1.11.93",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
+    "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "superjson": "^2.2.6",
-    "zod": "^3.23.8"
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/persistence/usePersistedState.d.ts

@@ -0,0 +1,40 @@
+type UsePersistedStateOptions<TState> = {
+    readonly key: string;
+    readonly validate: (raw: unknown) => TState | undefined;
+    readonly serialize?: (state: TState) => string;
+    readonly toUrlValue?: (state: TState) => string | object | Array<object>;
+    readonly fromUrlValue?: (decoded: unknown) => unknown;
+    readonly enabled?: boolean;
+    readonly onExternalChange?: () => void;
+    readonly replace?: boolean;
+    readonly clientSideUserId?: string;
+};
+type UsePersistedStateReturn<TState> = {
+    readonly initialState: TState | undefined;
+    readonly persistState: (state: TState) => void;
+};
+/**
+ * Generic persistence hook that loads state from URL search params (with
+ * localStorage fallback) and writes changes to both.
+ *
+ * On mount the hook tries, in order:
+ *  1. Decode the URL search param and pass it through `validate`.
+ *  2. If that yields nothing, read localStorage and pass the parsed JSON through `validate`.
+ *
+ * `persistState` writes the state to localStorage (via `serialize`, default
+ * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
+ * Duplicate writes where the state has not changed (deep equality) are skipped.
+ *
+ * @param options - Configuration for the persisted state.
+ * @param options.key - Unique identifier used for both the URL search param and the localStorage key.
+ * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
+ * @param options.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
+ * @param options.toUrlValue - Transform applied before URL encoding (default: encode state as-is).
+ * @param options.fromUrlValue - Transform applied after URL decoding, before validation (default: identity).
+ * @param options.enabled - When `false` the URL is neither read nor written (default `true`).
+ * @param options.onExternalChange - Fired when the URL param changes externally (e.g. browser back).
+ * @param options.replace - Forwarded to `useSearchParamSync`.
+ * @param options.clientSideUserId - The user ID to use for the localStorage key.
+ */
+export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, onExternalChange, replace, clientSideUserId, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+export {};

package/src/hooks/persistence/useSearchParamSync.d.ts

@@ -0,0 +1,27 @@
+export declare const MAX_URL_LENGTH = 5000;
+type UseSearchParamSyncOptions = {
+    readonly key: string;
+    readonly enabled?: boolean;
+    readonly onExternalChange?: () => void;
+    readonly replace?: boolean;
+};
+type UseSearchParamSyncReturn = {
+    readonly searchValue: string | undefined;
+    readonly updateSearchParam: (encodedValue: string | undefined) => void;
+};
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Provides a write function that updates the URL through the application
+ * router (preserving other search params), guards against exceeding
+ * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
+ * back/forward, shared links) via an optional callback.
+ *
+ * @param options - Configuration for the search param sync.
+ * @param options.key - The URL search parameter name.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
+ */
+export declare const useSearchParamSync: ({ key, enabled, onExternalChange, replace: replaceOption, }: UseSearchParamSyncOptions) => UseSearchParamSyncReturn;
+export {};

package/src/hooks/persistence/useStorageKey.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generates a localStorage key, optionally scoped to a specific user.
+ *
+ * When `userId` is provided the key is `"key-userId"`.
+ * When omitted the key is returned as-is (unscoped).
+ *
+ * @param key - Unique persistence identifier.
+ * @param userId - Client-side user id to scope storage per user.
+ * @returns {string} The combined storage key.
+ */
+export declare const useStorageKey: (key: string, userId?: string) => string;

package/src/index.d.ts

@@ -110,12 +110,16 @@ export * from "./components/ValueBar/ValueBarTypes";
 export * from "./components/ZStack/ZStack";
 export * from "./components/ZStack/ZStack.variants";
 export * from "./hooks/encoding/useCustomEncoding";
+export * from "./hooks/localStorage/storageSerializer";
 export * from "./hooks/localStorage/types";
 export * from "./hooks/localStorage/useLocalStorage";
 export * from "./hooks/localStorage/useLocalStorageReducer";
 export * from "./hooks/localStorage/useSessionStorage";
 export * from "./hooks/localStorage/useSessionStorageReducer";
 export * from "./hooks/noPagination";
+export * from "./hooks/persistence/usePersistedState";
+export * from "./hooks/persistence/useSearchParamSync";
+export * from "./hooks/persistence/useStorageKey";
 export * from "./hooks/useBidirectionalScroll";
 export * from "./hooks/useClickOutside";
 export * from "./hooks/useContainerBreakpoints";