@trackunit/react-components 1.24.3 → 1.24.5

package/index.cjs.js

@@ -11133,6 +11133,13 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+/**
+ * Default maximum full URL length after adding one persisted search param
+ * before the URL write is skipped (localStorage still persists the full state).
+ *
+ * Sized to stay safely below the AWS WAF managed-rule default
+ * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire url host + path + query + hash string
+ */
 const MAX_URL_LENGTH = 5000;
 /**
  * Syncs an encoded string value with a URL search parameter via Tanstack Router.
@@ -11227,7 +11234,16 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
                 replace: shouldReplace,
             });
         });
-    }, [enabled, navigate, key, replaceOption, location.hash, getUrlLengthWithSearchParam, currentSearchValue, router.state.status]);
+    }, [
+        enabled,
+        navigate,
+        key,
+        replaceOption,
+        location.hash,
+        getUrlLengthWithSearchParam,
+        currentSearchValue,
+        router.state.status,
+    ]);
     return react.useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
 };
 
@@ -11249,9 +11265,13 @@ const useStorageKey = (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`.
+ * On mount the hook resolves the initial state as follows:
+ *  - If a URL search param exists, decode it and pass through `validate`.
+ *  - If localStorage is enabled, read and validate its value.
+ *  - When `mergeWithStorageOnRead` is `false` (default): URL state wins
+ *    entirely when present, otherwise fall back to localStorage.
+ *  - When `mergeWithStorageOnRead` is `true`: shallow-merge URL fields over
+ *    localStorage so fields stripped by `toUrlValue` survive via storage.
  *
  * `persistState` writes the state to localStorage (via `serialize`, default
  * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
@@ -11264,11 +11284,15 @@ const useStorageKey = (key, userId) => {
  * @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.localStorageEnabled - When `false` localStorage 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.
+ * @param options.mergeWithStorageOnRead - Merge URL state on top of localStorage
+ *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
+ *   omits fields so they still survive via localStorage. Default `false`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, onExternalChange, replace, clientSideUserId, }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, }) => {
     const { encode, decode } = useCustomEncoding();
     const { searchValue, updateSearchParam } = useSearchParamSync({
         key,
@@ -11277,51 +11301,96 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         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 serializeRef = react.useRef(serialize);
+    react.useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const validateRef = react.useRef(validate);
+    react.useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
     const fromUrlValueRef = react.useRef(fromUrlValue);
     react.useEffect(() => {
         fromUrlValueRef.current = fromUrlValue;
     }, [fromUrlValue]);
-    const serializeRef = react.useRef(serialize);
+    const searchValueRef = react.useRef(searchValue);
     react.useEffect(() => {
-        serializeRef.current = serialize;
-    }, [serialize]);
-    const [{ initialState, loadedFromStorage }] = react.useState(() => {
-        if (enabled && searchValue) {
+        searchValueRef.current = searchValue;
+    }, [searchValue]);
+    const readPersistedState = react.useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
+        let urlState;
+        if (enabled && valueFromUrl) {
             try {
-                const decoded = decode(searchValue);
-                const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
-                const validated = validate(transformed);
-                if (validated !== undefined) {
-                    return { initialState: validated, loadedFromStorage: false };
-                }
+                const decoded = decode(valueFromUrl);
+                const transformed = transformFromUrlValue ? transformFromUrlValue(decoded) : decoded;
+                urlState = validateState(transformed);
             }
             catch {
                 // fall through to localStorage
             }
         }
-        try {
-            const raw = localStorage.getItem(storageKey);
-            if (raw) {
-                const parsed = storageSerializer.deserialize(raw);
-                const validated = validate(parsed);
-                return { initialState: validated, loadedFromStorage: validated !== undefined };
+        // Without the merge option, URL state wins entirely when present —
+        // this preserves the original "URL > localStorage" priority.
+        if (urlState !== undefined && !mergeWithStorageOnRead) {
+            return { initialState: urlState, loadedFromStorage: false };
+        }
+        let storageState;
+        if (localStorageEnabled) {
+            try {
+                const raw = localStorage.getItem(storageKey);
+                if (raw) {
+                    const parsed = storageSerializer.deserialize(raw);
+                    storageState = validateState(parsed);
+                }
             }
+            catch {
+                // no valid stored state
+            }
+        }
+        if (urlState !== undefined && storageState !== undefined) {
+            // Shallow merge — URL fields take precedence; storage fills in
+            // whatever the URL omits (e.g. fields stripped by `toUrlValue`).
+            return { initialState: { ...storageState, ...urlState }, loadedFromStorage: false };
         }
-        catch {
-            // no valid stored state
+        if (urlState !== undefined) {
+            return { initialState: urlState, loadedFromStorage: false };
+        }
+        if (storageState !== undefined) {
+            return { initialState: storageState, loadedFromStorage: true };
         }
         return { initialState: undefined, loadedFromStorage: false };
-    });
+    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
+    const [persistedStateSnapshot, setPersistedStateSnapshot] = react.useState(() => readPersistedState({
+        valueFromUrl: searchValue,
+        validateState: validate,
+        transformFromUrlValue: fromUrlValue,
+    }));
+    const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${storageKey}`;
+    const persistedStateReadKeyRef = react.useRef(persistedStateReadKey);
+    react.useEffect(() => {
+        if (persistedStateReadKeyRef.current === persistedStateReadKey) {
+            return;
+        }
+        persistedStateReadKeyRef.current = persistedStateReadKey;
+        setPersistedStateSnapshot(readPersistedState({
+            valueFromUrl: searchValueRef.current,
+            validateState: validateRef.current,
+            transformFromUrlValue: fromUrlValueRef.current,
+        }));
+    }, [persistedStateReadKey, readPersistedState]);
+    const { initialState, loadedFromStorage } = persistedStateSnapshot;
     const lastPersistedRef = react.useRef(initialState);
+    react.useEffect(() => {
+        lastPersistedRef.current = initialState;
+    }, [initialState, localStorageEnabled, storageKey]);
     const hasRestoredUrlRef = react.useRef(false);
+    react.useEffect(() => {
+        hasRestoredUrlRef.current = false;
+    }, [enabled, localStorageEnabled, storageKey]);
     react.useEffect(() => {
         if (hasRestoredUrlRef.current) {
             return;
@@ -11331,18 +11400,22 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         }
         hasRestoredUrlRef.current = true;
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
-        updateSearchParam(encode(urlValue), { replace: true });
+        const encoded = encode(urlValue);
+        updateSearchParam(encoded, { replace: true });
     }, [enabled, loadedFromStorage, initialState, searchValue, updateSearchParam, encode]);
     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);
+        if (localStorageEnabled) {
+            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]);
+        const encoded = encode(urlValue);
+        updateSearchParam(encoded);
+    }, [storageKey, encode, localStorageEnabled, updateSearchParam]);
     return react.useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
 };
 

package/index.esm.js

@@ -11131,6 +11131,13 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+/**
+ * Default maximum full URL length after adding one persisted search param
+ * before the URL write is skipped (localStorage still persists the full state).
+ *
+ * Sized to stay safely below the AWS WAF managed-rule default
+ * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire url host + path + query + hash string
+ */
 const MAX_URL_LENGTH = 5000;
 /**
  * Syncs an encoded string value with a URL search parameter via Tanstack Router.
@@ -11225,7 +11232,16 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
                 replace: shouldReplace,
             });
         });
-    }, [enabled, navigate, key, replaceOption, location.hash, getUrlLengthWithSearchParam, currentSearchValue, router.state.status]);
+    }, [
+        enabled,
+        navigate,
+        key,
+        replaceOption,
+        location.hash,
+        getUrlLengthWithSearchParam,
+        currentSearchValue,
+        router.state.status,
+    ]);
     return useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
 };
 
@@ -11247,9 +11263,13 @@ const useStorageKey = (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`.
+ * On mount the hook resolves the initial state as follows:
+ *  - If a URL search param exists, decode it and pass through `validate`.
+ *  - If localStorage is enabled, read and validate its value.
+ *  - When `mergeWithStorageOnRead` is `false` (default): URL state wins
+ *    entirely when present, otherwise fall back to localStorage.
+ *  - When `mergeWithStorageOnRead` is `true`: shallow-merge URL fields over
+ *    localStorage so fields stripped by `toUrlValue` survive via storage.
  *
  * `persistState` writes the state to localStorage (via `serialize`, default
  * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
@@ -11262,11 +11282,15 @@ const useStorageKey = (key, userId) => {
  * @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.localStorageEnabled - When `false` localStorage 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.
+ * @param options.mergeWithStorageOnRead - Merge URL state on top of localStorage
+ *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
+ *   omits fields so they still survive via localStorage. Default `false`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, onExternalChange, replace, clientSideUserId, }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, }) => {
     const { encode, decode } = useCustomEncoding();
     const { searchValue, updateSearchParam } = useSearchParamSync({
         key,
@@ -11275,51 +11299,96 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         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 serializeRef = useRef(serialize);
+    useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const validateRef = useRef(validate);
+    useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
     const fromUrlValueRef = useRef(fromUrlValue);
     useEffect(() => {
         fromUrlValueRef.current = fromUrlValue;
     }, [fromUrlValue]);
-    const serializeRef = useRef(serialize);
+    const searchValueRef = useRef(searchValue);
     useEffect(() => {
-        serializeRef.current = serialize;
-    }, [serialize]);
-    const [{ initialState, loadedFromStorage }] = useState(() => {
-        if (enabled && searchValue) {
+        searchValueRef.current = searchValue;
+    }, [searchValue]);
+    const readPersistedState = useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
+        let urlState;
+        if (enabled && valueFromUrl) {
             try {
-                const decoded = decode(searchValue);
-                const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
-                const validated = validate(transformed);
-                if (validated !== undefined) {
-                    return { initialState: validated, loadedFromStorage: false };
-                }
+                const decoded = decode(valueFromUrl);
+                const transformed = transformFromUrlValue ? transformFromUrlValue(decoded) : decoded;
+                urlState = validateState(transformed);
             }
             catch {
                 // fall through to localStorage
             }
         }
-        try {
-            const raw = localStorage.getItem(storageKey);
-            if (raw) {
-                const parsed = storageSerializer.deserialize(raw);
-                const validated = validate(parsed);
-                return { initialState: validated, loadedFromStorage: validated !== undefined };
+        // Without the merge option, URL state wins entirely when present —
+        // this preserves the original "URL > localStorage" priority.
+        if (urlState !== undefined && !mergeWithStorageOnRead) {
+            return { initialState: urlState, loadedFromStorage: false };
+        }
+        let storageState;
+        if (localStorageEnabled) {
+            try {
+                const raw = localStorage.getItem(storageKey);
+                if (raw) {
+                    const parsed = storageSerializer.deserialize(raw);
+                    storageState = validateState(parsed);
+                }
             }
+            catch {
+                // no valid stored state
+            }
+        }
+        if (urlState !== undefined && storageState !== undefined) {
+            // Shallow merge — URL fields take precedence; storage fills in
+            // whatever the URL omits (e.g. fields stripped by `toUrlValue`).
+            return { initialState: { ...storageState, ...urlState }, loadedFromStorage: false };
         }
-        catch {
-            // no valid stored state
+        if (urlState !== undefined) {
+            return { initialState: urlState, loadedFromStorage: false };
+        }
+        if (storageState !== undefined) {
+            return { initialState: storageState, loadedFromStorage: true };
         }
         return { initialState: undefined, loadedFromStorage: false };
-    });
+    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
+    const [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => readPersistedState({
+        valueFromUrl: searchValue,
+        validateState: validate,
+        transformFromUrlValue: fromUrlValue,
+    }));
+    const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${storageKey}`;
+    const persistedStateReadKeyRef = useRef(persistedStateReadKey);
+    useEffect(() => {
+        if (persistedStateReadKeyRef.current === persistedStateReadKey) {
+            return;
+        }
+        persistedStateReadKeyRef.current = persistedStateReadKey;
+        setPersistedStateSnapshot(readPersistedState({
+            valueFromUrl: searchValueRef.current,
+            validateState: validateRef.current,
+            transformFromUrlValue: fromUrlValueRef.current,
+        }));
+    }, [persistedStateReadKey, readPersistedState]);
+    const { initialState, loadedFromStorage } = persistedStateSnapshot;
     const lastPersistedRef = useRef(initialState);
+    useEffect(() => {
+        lastPersistedRef.current = initialState;
+    }, [initialState, localStorageEnabled, storageKey]);
     const hasRestoredUrlRef = useRef(false);
+    useEffect(() => {
+        hasRestoredUrlRef.current = false;
+    }, [enabled, localStorageEnabled, storageKey]);
     useEffect(() => {
         if (hasRestoredUrlRef.current) {
             return;
@@ -11329,18 +11398,22 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         }
         hasRestoredUrlRef.current = true;
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
-        updateSearchParam(encode(urlValue), { replace: true });
+        const encoded = encode(urlValue);
+        updateSearchParam(encoded, { replace: true });
     }, [enabled, loadedFromStorage, initialState, searchValue, updateSearchParam, encode]);
     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);
+        if (localStorageEnabled) {
+            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]);
+        const encoded = encode(urlValue);
+        updateSearchParam(encoded);
+    }, [storageKey, encode, localStorageEnabled, updateSearchParam]);
     return useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.24.3",
+  "version": "1.24.5",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,10 +14,10 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.13.1",
-    "@trackunit/css-class-variance-utilities": "1.13.1",
-    "@trackunit/shared-utils": "1.15.1",
-    "@trackunit/ui-icons": "1.13.1",
+    "@trackunit/ui-design-tokens": "1.13.2",
+    "@trackunit/css-class-variance-utilities": "1.13.2",
+    "@trackunit/shared-utils": "1.15.2",
+    "@trackunit/ui-icons": "1.13.2",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
     "dequal": "^2.0.3",

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

@@ -5,9 +5,23 @@ type UsePersistedStateOptions<TState> = {
     readonly toUrlValue?: (state: TState) => string | object | Array<object>;
     readonly fromUrlValue?: (decoded: unknown) => unknown;
     readonly enabled?: boolean;
+    readonly localStorageEnabled?: boolean;
     readonly onExternalChange?: () => void;
     readonly replace?: boolean;
     readonly clientSideUserId?: string;
+    /**
+     * When `true` and both URL and localStorage have valid state, the read
+     * returns a shallow merge `{ ...storage, ...url }` where URL fields take
+     * precedence and storage fills in fields the URL omits.
+     *
+     * Use this when `toUrlValue` deliberately omits some fields from the URL
+     * (e.g. per-user layout details that shouldn't be shareable) so the
+     * omitted fields still survive reloads via localStorage.
+     *
+     * Default is `false`, preserving the original behavior where URL state
+     * fully replaces localStorage state on read.
+     */
+    readonly mergeWithStorageOnRead?: boolean;
 };
 type UsePersistedStateReturn<TState> = {
     readonly initialState: TState | undefined;
@@ -17,9 +31,13 @@ type UsePersistedStateReturn<TState> = {
  * 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`.
+ * On mount the hook resolves the initial state as follows:
+ *  - If a URL search param exists, decode it and pass through `validate`.
+ *  - If localStorage is enabled, read and validate its value.
+ *  - When `mergeWithStorageOnRead` is `false` (default): URL state wins
+ *    entirely when present, otherwise fall back to localStorage.
+ *  - When `mergeWithStorageOnRead` is `true`: shallow-merge URL fields over
+ *    localStorage so fields stripped by `toUrlValue` survive via storage.
  *
  * `persistState` writes the state to localStorage (via `serialize`, default
  * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
@@ -32,9 +50,13 @@ type UsePersistedStateReturn<TState> = {
  * @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.localStorageEnabled - When `false` localStorage 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.
+ * @param options.mergeWithStorageOnRead - Merge URL state on top of localStorage
+ *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
+ *   omits fields so they still survive via localStorage. Default `false`.
  */
-export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, onExternalChange, replace, clientSideUserId, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
 export {};

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

@@ -1,3 +1,10 @@
+/**
+ * Default maximum full URL length after adding one persisted search param
+ * before the URL write is skipped (localStorage still persists the full state).
+ *
+ * Sized to stay safely below the AWS WAF managed-rule default
+ * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire url host + path + query + hash string
+ */
 export declare const MAX_URL_LENGTH = 5000;
 type UseSearchParamSyncOptions = {
     readonly key: string;