@trackunit/react-components 1.25.4 → 1.26.0

package/index.esm.js

@@ -11239,6 +11239,400 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+/**
+ * Pure utilities for reading and writing single named entries inside a URL
+ * fragment (the part after `#`).
+ *
+ * # Format contract
+ *
+ * The fragment body (after the leading `#`) is treated as a sequence of
+ * `&`-separated tokens. A token may be:
+ *  - **A named entry** — `<key>=<value>` (the first `=` separates key from
+ *    value; later `=` chars are part of the value).
+ *  - **Foreign content** — anything else (bare scroll anchors like
+ *    `section`, hash routes, third-party data, malformed tokens). Foreign
+ *    tokens are preserved byte-for-byte, in their original positions.
+ *
+ * # Single-key ownership
+ *
+ * Callers operate on **one** named key per invocation. Every token whose
+ * key does not match the supplied key is foreign — the utility never
+ * categorises or rewrites it. This mirrors how `useSearchParamSync`
+ * treats a single named search param.
+ *
+ * # Value-encoding invariant
+ *
+ * Values passed to {@link writeHashKey} must not contain `&`, `=`, or `#`.
+ * The standard producer for this codebase is `useCustomEncoding`, whose
+ * base64url alphabet (`[A-Za-z0-9_-]`) satisfies the invariant by
+ * construction. Keys are restricted by the existing persistence-key
+ * schema (camelCase, ≤15 chars), so they are likewise safe.
+ *
+ * # Anchor-scroll caveat
+ *
+ * Browsers locate scroll targets by matching the entire fragment string
+ * against element IDs. Appending a named entry to a fragment containing
+ * a bare anchor (e.g. `#section` becoming `#section&userTableTp=...`)
+ * therefore breaks anchor scrolling on that page. This is unavoidable
+ * for any hash-backed shared state. Consumers that rely on scroll
+ * anchors should not also persist state to the hash on the same route.
+ */
+const TOKEN_SEPARATOR = "&";
+const KEY_VALUE_SEPARATOR = "=";
+const stripLeadingHash = (hash) => (hash.startsWith("#") ? hash.slice(1) : hash);
+const formatHash = (body) => (body.length === 0 ? "" : `#${body}`);
+/**
+ * Reads the value of a single named entry from a URL fragment.
+ *
+ * @param hash - The fragment string, with or without the leading `#`.
+ * @param key - The entry key to look up.
+ * @returns {string | undefined} The raw value (everything after the first
+ *   `=` in the matching token), or `undefined` when the key is absent. An
+ *   entry whose token has no `=` is treated as foreign content and ignored.
+ */
+const readHashKey = (hash, key) => {
+    const body = stripLeadingHash(hash);
+    if (body.length === 0) {
+        return undefined;
+    }
+    for (const token of body.split(TOKEN_SEPARATOR)) {
+        const eqIndex = token.indexOf(KEY_VALUE_SEPARATOR);
+        if (eqIndex > 0 && token.slice(0, eqIndex) === key) {
+            return token.slice(eqIndex + 1);
+        }
+    }
+    return undefined;
+};
+/**
+ * Returns a new fragment string with the named entry written, replaced,
+ * or removed. Foreign tokens are preserved in their original order; the
+ * named entry retains its position if it already exists, and is appended
+ * to the end when newly inserted. Empty tokens (e.g. produced by
+ * consecutive `&`) are dropped on the way out.
+ *
+ * @param hash - The current fragment string, with or without the leading `#`.
+ * @param key - The entry key to write.
+ * @param value - The value to set, or `undefined` to remove the entry.
+ * @returns {string} The new fragment string, including a leading `#` when
+ *   non-empty, or an empty string when the result has no tokens left.
+ */
+const writeHashKey = (hash, key, value) => {
+    const body = stripLeadingHash(hash);
+    const tokens = body.length === 0 ? [] : body.split(TOKEN_SEPARATOR);
+    const next = [];
+    let replaced = false;
+    for (const token of tokens) {
+        if (token.length === 0) {
+            continue;
+        }
+        const eqIndex = token.indexOf(KEY_VALUE_SEPARATOR);
+        if (eqIndex > 0 && token.slice(0, eqIndex) === key) {
+            if (value !== undefined && !replaced) {
+                next.push(`${key}${KEY_VALUE_SEPARATOR}${value}`);
+                replaced = true;
+            }
+            // Else: drop the token (either removing the key or dropping a
+            // duplicate occurrence after we already wrote the replacement).
+            continue;
+        }
+        next.push(token);
+    }
+    if (value !== undefined && !replaced) {
+        next.push(`${key}${KEY_VALUE_SEPARATOR}${value}`);
+    }
+    return formatHash(next.join(TOKEN_SEPARATOR));
+};
+
+/**
+ * Default maximum length of the resulting URL fragment after adding one
+ * persisted entry. Writes are skipped (localStorage continues to hold the
+ * full state) when adding the entry would push the fragment past this cap.
+ *
+ * The fragment is never sent to the server, so it is not subject to the
+ * AWS WAF managed-rule `SizeRestrictions_QUERYSTRING` cap that applies to
+ * search params (5000 bytes). 64 KB stays well below typical browser URL
+ * limits (Chromium ≳ 100 KB, Firefox ≳ 64 KB on the address bar) while
+ * still leaving generous headroom for any realistic table state.
+ */
+const MAX_HASH_LENGTH = 64 * 1024;
+/**
+ * Syncs an encoded string value with a single named entry inside the URL
+ * fragment (`location.hash`) via Tanstack Router.
+ *
+ * Behaviour mirrors `useSearchParamSync`, with two differences:
+ *  - Reads from and writes to `location.hash` instead of `location.search`.
+ *  - Writes are guarded against {@link MAX_HASH_LENGTH} rather than the
+ *    AWS-WAF-driven search-param cap.
+ *
+ * The fragment is treated as a sequence of `&`-separated tokens via the
+ * pure utilities in `./hashFragment`. Foreign tokens (bare anchors, other
+ * named entries) are preserved byte-for-byte on every write.
+ *
+ * @param options - Configuration for the hash entry sync.
+ * @param options.key - The named entry inside the fragment.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the entry changes externally
+ *   (e.g. browser back/forward, pasted link, foreign router push).
+ * @param options.replace - `true` to always use `replaceState` instead of pushState.
+ */
+const useHashParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const router = useRouter();
+    const lastWrittenRef = useRef(undefined);
+    const pendingWriteRef = useRef(null);
+    const onExternalChangeRef = useRef(onExternalChange);
+    useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentHashValue = useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        return readHashKey(location.hash, key);
+    }, [enabled, location.hash, key]);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (currentHashValue === undefined) {
+            return;
+        }
+        if (currentHashValue === lastWrittenRef.current) {
+            return;
+        }
+        if (lastWrittenRef.current === undefined) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            onExternalChangeRef.current?.();
+        });
+    }, [currentHashValue, enabled]);
+    // Writes are dispatched via a "pending write" queue rather than calling
+    // `navigate` directly from inside the rAF callback. Tanstack Router's
+    // `router.state.status === "pending"` is common during the first paint
+    // of a route (loaders, suspense), and an earlier implementation that
+    // simply returned in that case lost the write outright — the
+    // URL-restoration path in `usePersistedState` is one-shot (guarded by a
+    // ref), so when a localStorage-→-hash write coincided with a pending
+    // router the canonical hash never got populated and users saw an
+    // intermittent "hash not set on initial visit" bug.
+    //
+    // The queue + retry pattern below makes writes reliable:
+    //  - `updateHashParam` stores the latest attempted write in
+    //    `pendingWriteRef` and schedules an rAF flush.
+    //  - `flushPendingWrite` only navigates when the router is idle; while
+    //    pending it leaves the write queued so it can fire later.
+    //  - A dedicated effect watches `router.state.status` and re-attempts
+    //    the flush whenever the router settles, draining the queue.
+    const flushPendingWrite = useCallback(() => {
+        const pending = pendingWriteRef.current;
+        if (pending === null) {
+            return;
+        }
+        if (router.state.status === "pending") {
+            // Keep the write queued; the status-watcher effect below will retry
+            // when the router transitions back to idle.
+            return;
+        }
+        pendingWriteRef.current = null;
+        const { encodedValue, options } = pending;
+        const nextHash = writeHashKey(location.hash, key, encodedValue);
+        if (nextHash.length > MAX_HASH_LENGTH) {
+            // Drop the write so the fragment never grows past the cap. The
+            // localStorage write performed by `usePersistedState` still holds
+            // the full state, so the layout survives a reload on the same
+            // browser; only the shareable URL is degraded.
+            return;
+        }
+        const shouldReplace = options?.replace ?? replaceOption ?? !Boolean(currentHashValue);
+        // Tanstack Router's `navigate({ hash })` expects the fragment body
+        // *without* the leading `#` — the router adds the delimiter itself
+        // when serialising the URL. Forwarding the `#`-prefixed value from
+        // `writeHashKey` produces a doubled `##` in the address bar
+        // (visually broken, even though browsers still parse the fragment
+        // correctly because URL fragments start at the *first* `#`).
+        const navigateHash = nextHash.startsWith("#") ? nextHash.slice(1) : nextHash;
+        void navigate({
+            to: ".",
+            // Returning the same `prev` reference leaves the search params
+            // unchanged. We must still pass `search` so router types are happy.
+            search: (prev) => prev,
+            hash: navigateHash,
+            replace: shouldReplace,
+        });
+    }, [router.state.status, location.hash, key, currentHashValue, navigate, replaceOption]);
+    useEffect(() => {
+        if (router.state.status === "pending") {
+            return;
+        }
+        if (pendingWriteRef.current === null) {
+            return;
+        }
+        flushPendingWrite();
+    }, [router.state.status, flushPendingWrite]);
+    // Drop any queued write when the consumer unmounts. The queue + retry
+    // pattern above keeps writes pending across a `router.state.status ===
+    // "pending"` phase, which means a write scheduled just before a route
+    // change could otherwise drain onto the *next* route once it settles.
+    // Cancelling here preserves the original "writes are scoped to the
+    // owning route" contract that the pre-queue implementation got for
+    // free by dropping the write outright.
+    useEffect(() => () => {
+        pendingWriteRef.current = null;
+    }, []);
+    const updateHashParam = useCallback((encodedValue, options) => {
+        if (!enabled) {
+            return;
+        }
+        // Dedupe against either the last *committed* write or the value
+        // currently queued for the next rAF. Both represent the caller's
+        // intent so we don't schedule redundant rAF callbacks for identical
+        // requests.
+        const inFlightOrLastWritten = pendingWriteRef.current?.encodedValue ?? lastWrittenRef.current;
+        if (encodedValue !== undefined && encodedValue === inFlightOrLastWritten) {
+            return;
+        }
+        // Prime `lastWrittenRef` here (not inside `flushPendingWrite`) so
+        // the external-change detector treats this value as the caller's
+        // authoritative state even when the flush is a no-op (URL already
+        // matches) or stays queued during a pending router phase. Without
+        // priming, the next "external" change would look identical to the
+        // initial render (`lastWrittenRef === undefined`) and the callback
+        // would be skipped.
+        lastWrittenRef.current = encodedValue;
+        if (currentHashValue === encodedValue) {
+            return;
+        }
+        pendingWriteRef.current = { encodedValue, options };
+        requestAnimationFrame(() => {
+            flushPendingWrite();
+        });
+    }, [enabled, currentHashValue, flushPendingWrite]);
+    return useMemo(() => ({ searchValue: currentHashValue, updateSearchParam: updateHashParam }), [currentHashValue, updateHashParam]);
+};
+
+/**
+ * One-shot migration: if the URL still carries a legacy `?<key>=...`
+ * search param from before this hook moved table-style state to the
+ * fragment, decode it, hand it to the caller via `onMigrated`, then strip
+ * the search param via a `replace` navigation so back/forward history
+ * isn't polluted.
+ *
+ * Invariants:
+ *  - The strip navigation fires at most once per mount (guarded by
+ *    `hasStrippedRef`) so we don't loop on the navigation we ourselves
+ *    triggered.
+ *  - `onMigrated` is also fired at most once per mount (guarded by
+ *    `hasMigratedRef`), but its gating is independent of the strip:
+ *    if `hashAlreadyHasValue` flips `true → false` after the strip
+ *    (e.g. an external actor clears the canonical hash mid-mount), the
+ *    next render still gets a chance to migrate the legacy value into
+ *    the hash. Conflating the two flags would have permanently lost
+ *    the legacy state in that race.
+ *  - Never throws — a decode/validate failure silently drops the value
+ *    and still strips the search param. The legacy key is owned by this
+ *    codebase's persistence convention (camelCase + `Tp` suffix), so
+ *    stripping unparseable values cannot destroy third-party data.
+ *  - When `hashAlreadyHasValue` is `true` the hash wins: the search
+ *    param is stripped but `onMigrated` is not fired.
+ *  - The `location.hash` is preserved verbatim across the strip
+ *    navigation so any concurrent hash content (including a freshly
+ *    written value) survives the cleanup.
+ */
+const useMigrateLegacySearchParam = ({ key, enabled, decode, fromUrlValue, validate, hashAlreadyHasValue, onMigrated, }) => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const search = useSearch({ strict: false, shouldThrow: false });
+    // The three flags are tracked independently because they describe
+    // distinct side effects with distinct lifetimes:
+    //
+    //  - `hasStrippedRef` guards the cleanup navigation against looping
+    //    on the navigation we ourselves triggered.
+    //  - `hasMigratedRef` guards `onMigrated` against being called twice
+    //    with the same legacy value.
+    //  - `cachedRawValueRef` snapshots the legacy raw string the first
+    //    time we observe it. The strip navigation below removes the
+    //    value from `search` on the next render, so without a cache we
+    //    can never migrate it later. This matters in one specific edge
+    //    case: `hashAlreadyHasValue` is `true` on the first render (so
+    //    we skip `onMigrated` and just strip), then later flips to
+    //    `false` because another actor cleared the canonical hash. With
+    //    the cache the next render can still surface the legacy value.
+    //
+    // The previous implementation conflated all of this into a single
+    // `hasRunRef`, which permanently lost the legacy state in that race.
+    const hasStrippedRef = useRef(false);
+    const hasMigratedRef = useRef(false);
+    const cachedRawValueRef = useRef(undefined);
+    const decodeRef = useRef(decode);
+    const fromUrlValueRef = useRef(fromUrlValue);
+    const validateRef = useRef(validate);
+    const onMigratedRef = useRef(onMigrated);
+    useEffect(() => {
+        decodeRef.current = decode;
+        fromUrlValueRef.current = fromUrlValue;
+        validateRef.current = validate;
+        onMigratedRef.current = onMigrated;
+    }, [decode, fromUrlValue, validate, onMigrated]);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (hasStrippedRef.current && hasMigratedRef.current) {
+            return;
+        }
+        // Snapshot the raw value the first time we see it. After the strip
+        // navigation below, `search?.[key]` is undefined, but a later
+        // render that flips `hashAlreadyHasValue` back to `false` still
+        // needs the original value to migrate.
+        if (cachedRawValueRef.current === undefined) {
+            const rawValue = search?.[key];
+            if (typeof rawValue === "string" || typeof rawValue === "number" || typeof rawValue === "boolean") {
+                cachedRawValueRef.current = String(rawValue);
+            }
+        }
+        const rawString = cachedRawValueRef.current;
+        if (rawString === undefined) {
+            // Nothing legacy to migrate yet. Don't flip either flag — the
+            // param may appear on a later render (e.g. router still hydrating).
+            return;
+        }
+        if (!hasMigratedRef.current && !hashAlreadyHasValue) {
+            let migratedState;
+            try {
+                const decoded = decodeRef.current(rawString);
+                const transformed = fromUrlValueRef.current ? fromUrlValueRef.current(decoded) : decoded;
+                migratedState = validateRef.current(transformed);
+            }
+            catch {
+                migratedState = undefined;
+            }
+            // Invalid legacy data is silently dropped: the search param is
+            // still stripped below, so the URL stays clean. Surfacing a
+            // console warning here would require disabling a lint rule, and
+            // the data loss is bounded — localStorage holds the working state
+            // for the current session, and the user's next interaction
+            // repopulates the hash. We still flip the flag in the invalid
+            // case so we don't burn cycles re-decoding the same bad string
+            // on every render.
+            hasMigratedRef.current = true;
+            if (migratedState !== undefined) {
+                onMigratedRef.current(migratedState);
+            }
+        }
+        if (!hasStrippedRef.current) {
+            hasStrippedRef.current = true;
+            void navigate({
+                to: ".",
+                search: (prev) => ({ ...prev, [key]: undefined }),
+                hash: location.hash,
+                replace: true,
+            });
+        }
+    }, [enabled, key, hashAlreadyHasValue, search, navigate, location.hash]);
+};
+
 /**
  * Default maximum full URL length after adding one persisted search param
  * before the URL write is skipped (localStorage still persists the full state).
@@ -11267,6 +11661,7 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
     const router = useRouter();
     const search = useSearch({ strict: false, shouldThrow: false });
     const lastWrittenRef = useRef(undefined);
+    const pendingWriteRef = useRef(null);
     const onExternalChangeRef = useRef(onExternalChange);
     useEffect(() => {
         onExternalChangeRef.current = onExternalChange;
@@ -11310,46 +11705,96 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
         const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
         return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
     }, [location]);
+    // Writes are dispatched via a "pending write" queue rather than calling
+    // `navigate` directly from inside the rAF callback. See the matching
+    // comment block in `useHashParamSync` for the full rationale — in short,
+    // navigating while `router.state.status === "pending"` was previously
+    // dropped silently, which lost the URL-restoration write performed by
+    // `usePersistedState` on routes that mount during a loader-driven
+    // pending phase.
+    const flushPendingWrite = useCallback(() => {
+        const pending = pendingWriteRef.current;
+        if (pending === null) {
+            return;
+        }
+        if (router.state.status === "pending") {
+            // Keep the write queued; the status-watcher effect below retries on
+            // the next idle transition.
+            return;
+        }
+        pendingWriteRef.current = null;
+        const { encodedValue, options } = pending;
+        const shouldReplace = options?.replace ?? 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,
+        });
+    }, [
+        router.state.status,
+        location.hash,
+        key,
+        currentSearchValue,
+        navigate,
+        replaceOption,
+        getUrlLengthWithSearchParam,
+    ]);
+    useEffect(() => {
+        if (router.state.status === "pending") {
+            return;
+        }
+        if (pendingWriteRef.current === null) {
+            return;
+        }
+        flushPendingWrite();
+    }, [router.state.status, flushPendingWrite]);
+    // Drop any queued write when the consumer unmounts. The queue + retry
+    // pattern above keeps writes pending across a `router.state.status ===
+    // "pending"` phase, which means a write scheduled just before a route
+    // change could otherwise drain onto the *next* route once it settles
+    // (e.g. a debounced filter write leaking into the destination route).
+    // Cancelling here preserves the original "writes are scoped to the
+    // owning route" contract that the pre-queue implementation got for
+    // free by dropping the write outright.
+    useEffect(() => () => {
+        pendingWriteRef.current = null;
+    }, []);
     const updateSearchParam = useCallback((encodedValue, options) => {
         if (!enabled) {
             return;
         }
-        if (encodedValue !== undefined && encodedValue === lastWrittenRef.current) {
+        // Dedupe against either the last committed write or the value
+        // currently queued for the next rAF — both represent the caller's
+        // intent so we don't schedule redundant rAF callbacks for identical
+        // requests.
+        const inFlightOrLastWritten = pendingWriteRef.current?.encodedValue ?? lastWrittenRef.current;
+        if (encodedValue !== undefined && encodedValue === inFlightOrLastWritten) {
             return;
         }
+        // Prime `lastWrittenRef` here (not inside `flushPendingWrite`) so
+        // the external-change detector treats this value as the caller's
+        // authoritative state even when the flush is a no-op (URL already
+        // matches) or stays queued during a pending router phase. Without
+        // priming, the next "external" change would look identical to the
+        // initial render (`lastWrittenRef === undefined`) and the callback
+        // would be skipped.
         lastWrittenRef.current = encodedValue;
         if (currentSearchValue === encodedValue) {
             return;
         }
+        pendingWriteRef.current = { encodedValue, options };
         requestAnimationFrame(() => {
-            if (router.state.status === "pending") {
-                return;
-            }
-            const shouldReplace = options?.replace ?? 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,
-            });
+            flushPendingWrite();
         });
-    }, [
-        enabled,
-        navigate,
-        key,
-        replaceOption,
-        location.hash,
-        getUrlLengthWithSearchParam,
-        currentSearchValue,
-        router.state.status,
-    ]);
+    }, [enabled, currentSearchValue, flushPendingWrite]);
     return useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
 };
 
@@ -11368,11 +11813,17 @@ const useStorageKey = (key, userId) => {
 };
 
 /**
- * Generic persistence hook that loads state from URL search params (with
- * localStorage fallback) and writes changes to both.
+ * Generic persistence hook that loads state from a URL slot (search param
+ * or hash fragment, depending on `urlLocation`) with localStorage fallback,
+ * and writes changes to both.
  *
  * On mount the hook resolves the initial state as follows:
- *  - If a URL search param exists, decode it and pass through `validate`.
+ *  - If the canonical URL slot (search OR hash, per `urlLocation`) holds a
+ *    value, decode it and pass through `validate`.
+ *  - In `urlLocation: "hash"` mode, if the canonical hash slot is empty
+ *    but a **legacy** `?<key>=...` search param is present, decode and
+ *    validate that as a one-shot fallback. A migration effect then strips
+ *    the legacy search param via a `replace` navigation.
  *  - 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.
@@ -11380,32 +11831,61 @@ const useStorageKey = (key, userId) => {
  *    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).
- * Duplicate writes where the state has not changed (deep equality) are skipped.
+ * `storageSerializer.serialize`) and syncs to the canonical URL slot (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.key - Unique identifier used for both the URL slot 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.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.onExternalChange - Fired when the URL value changes externally (e.g. browser back).
+ * @param options.replace - Forwarded to the underlying URL sync hook.
  * @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`.
+ * @param options.urlLocation - Which URL slot backs the value (`"search"` or `"hash"`). Default `"search"`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", }) => {
     const { encode, decode } = useCustomEncoding();
-    const { searchValue, updateSearchParam } = useSearchParamSync({
+    const searchActive = enabled && urlLocation === "search";
+    const hashActive = enabled && urlLocation === "hash";
+    // Both URL-sync hooks are mounted unconditionally to satisfy the Rules of
+    // Hooks; the inactive one is gated off via `enabled: false` and is a
+    // no-op at runtime.
+    const searchSync = useSearchParamSync({
+        key,
+        enabled: searchActive,
+        onExternalChange,
+        replace,
+    });
+    const hashSync = useHashParamSync({
         key,
-        enabled,
+        enabled: hashActive,
         onExternalChange,
         replace,
     });
+    const { searchValue, updateSearchParam } = hashActive ? hashSync : searchSync;
+    // In hash mode, also read the raw search params so a legacy `?<key>=...`
+    // value can hydrate the initial state once, before the migration effect
+    // strips it. In search mode this stays `undefined` so the legacy fallback
+    // is inert.
+    const rawSearch = useSearch({ strict: false, shouldThrow: false });
+    const legacySearchValue = useMemo(() => {
+        if (!hashActive) {
+            return undefined;
+        }
+        const raw = rawSearch?.[key];
+        if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+            return String(raw);
+        }
+        return undefined;
+    }, [hashActive, rawSearch, key]);
     const storageKey = useStorageKey(key, clientSideUserId);
     const toUrlValueRef = useRef(toUrlValue);
     useEffect(() => {
@@ -11427,22 +11907,44 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     useEffect(() => {
         searchValueRef.current = searchValue;
     }, [searchValue]);
-    const readPersistedState = useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
-        let urlState;
-        if (enabled && valueFromUrl) {
+    const legacySearchValueRef = useRef(legacySearchValue);
+    useEffect(() => {
+        legacySearchValueRef.current = legacySearchValue;
+    }, [legacySearchValue]);
+    const readPersistedState = useCallback(({ valueFromUrl, legacyValueFromUrl, validateState, transformFromUrlValue, }) => {
+        const tryDecode = (raw) => {
             try {
-                const decoded = decode(valueFromUrl);
+                const decoded = decode(raw);
                 const transformed = transformFromUrlValue ? transformFromUrlValue(decoded) : decoded;
-                urlState = validateState(transformed);
+                return validateState(transformed);
             }
             catch {
-                // fall through to localStorage
+                return undefined;
+            }
+        };
+        let urlState;
+        let canonicalUrlValid = false;
+        let usedLegacyUrl = false;
+        if (enabled && valueFromUrl) {
+            urlState = tryDecode(valueFromUrl);
+            if (urlState !== undefined) {
+                canonicalUrlValid = true;
+            }
+        }
+        if (urlState === undefined && enabled && legacyValueFromUrl) {
+            urlState = tryDecode(legacyValueFromUrl);
+            if (urlState !== undefined) {
+                usedLegacyUrl = true;
             }
         }
         // 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 };
+            return {
+                initialState: urlState,
+                canonicalUrlHasValidState: canonicalUrlValid,
+                needsUrlRestore: usedLegacyUrl,
+            };
         }
         let storageState;
         if (localStorageEnabled) {
@@ -11460,22 +11962,39 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         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 };
+            return {
+                initialState: { ...storageState, ...urlState },
+                canonicalUrlHasValidState: canonicalUrlValid,
+                needsUrlRestore: usedLegacyUrl,
+            };
         }
         if (urlState !== undefined) {
-            return { initialState: urlState, loadedFromStorage: false };
+            return {
+                initialState: urlState,
+                canonicalUrlHasValidState: canonicalUrlValid,
+                needsUrlRestore: usedLegacyUrl,
+            };
         }
         if (storageState !== undefined) {
-            return { initialState: storageState, loadedFromStorage: true };
+            return {
+                initialState: storageState,
+                canonicalUrlHasValidState: false,
+                needsUrlRestore: true,
+            };
         }
-        return { initialState: undefined, loadedFromStorage: false };
+        return {
+            initialState: undefined,
+            canonicalUrlHasValidState: false,
+            needsUrlRestore: false,
+        };
     }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
     const [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => readPersistedState({
         valueFromUrl: searchValue,
+        legacyValueFromUrl: legacySearchValue,
         validateState: validate,
         transformFromUrlValue: fromUrlValue,
     }));
-    const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${storageKey}`;
+    const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${urlLocation}:${storageKey}`;
     const persistedStateReadKeyRef = useRef(persistedStateReadKey);
     useEffect(() => {
         if (persistedStateReadKeyRef.current === persistedStateReadKey) {
@@ -11484,11 +12003,39 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         persistedStateReadKeyRef.current = persistedStateReadKey;
         setPersistedStateSnapshot(readPersistedState({
             valueFromUrl: searchValueRef.current,
+            legacyValueFromUrl: legacySearchValueRef.current,
             validateState: validateRef.current,
             transformFromUrlValue: fromUrlValueRef.current,
         }));
     }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, loadedFromStorage } = persistedStateSnapshot;
+    const { initialState, canonicalUrlHasValidState, needsUrlRestore } = persistedStateSnapshot;
+    // Late-hydration recovery: TanStack Router's `useSearch` can return an
+    // empty object on the very first render of a route that's still in a
+    // loader-driven pending phase. The `useState` initializer above runs
+    // exactly once, so a legacy `?<key>=...` value that only becomes
+    // visible on a later render would otherwise be missed entirely —
+    // `initialState` would resolve to `undefined`, and the migration
+    // effect would strip the legacy param without ever piping it through
+    // `onMigrated`. We re-read here when:
+    //   - the snapshot has nothing usable yet (`initialState === undefined`
+    //     AND the canonical URL slot has no valid value), and
+    //   - a legacy value has just appeared.
+    // Once `initialState` is populated, this effect's guard short-circuits
+    // and the rest of the lifecycle (restore + migration) takes over.
+    useEffect(() => {
+        if (initialState !== undefined || canonicalUrlHasValidState) {
+            return;
+        }
+        if (legacySearchValue === undefined) {
+            return;
+        }
+        setPersistedStateSnapshot(readPersistedState({
+            valueFromUrl: searchValueRef.current,
+            legacyValueFromUrl: legacySearchValue,
+            validateState: validateRef.current,
+            transformFromUrlValue: fromUrlValueRef.current,
+        }));
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, readPersistedState]);
     const lastPersistedRef = useRef(initialState);
     useEffect(() => {
         lastPersistedRef.current = initialState;
@@ -11496,19 +12043,54 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     const hasRestoredUrlRef = useRef(false);
     useEffect(() => {
         hasRestoredUrlRef.current = false;
-    }, [enabled, localStorageEnabled, storageKey]);
+    }, [enabled, localStorageEnabled, storageKey, urlLocation]);
     useEffect(() => {
         if (hasRestoredUrlRef.current) {
             return;
         }
-        if (!enabled || !loadedFromStorage || initialState === undefined || searchValue !== undefined) {
+        // Gate on `canonicalUrlHasValidState`, not on the raw `searchValue`:
+        // an undecodable string sitting in the canonical slot must NOT block
+        // the restore, otherwise a valid legacy/search/storage fallback ends
+        // up silently dropped (the bad string survives the migration's strip
+        // and is the only state left on the next reload).
+        if (!enabled || !needsUrlRestore || initialState === undefined || canonicalUrlHasValidState) {
             return;
         }
         hasRestoredUrlRef.current = true;
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
         const encoded = encode(urlValue);
         updateSearchParam(encoded, { replace: true });
-    }, [enabled, loadedFromStorage, initialState, searchValue, updateSearchParam, encode]);
+    }, [enabled, needsUrlRestore, initialState, canonicalUrlHasValidState, updateSearchParam, encode]);
+    // Strip the legacy search param so reloads come from the canonical hash
+    // slot and the URL stays tidy. The hook is a no-op outside hash mode.
+    // `hashAlreadyHasValue` is `true` only when the canonical hash slot
+    // already holds *valid* state — a raw but undecodable string must not
+    // suppress `onMigrated`, otherwise a valid legacy value would be lost
+    // on the next reload (see `canonicalUrlHasValidState` for the same
+    // reasoning in the restore effect above).
+    useMigrateLegacySearchParam({
+        key,
+        enabled: hashActive,
+        decode,
+        fromUrlValue,
+        validate,
+        hashAlreadyHasValue: canonicalUrlHasValidState,
+        onMigrated: useCallback((migrated) => {
+            if (dequal(lastPersistedRef.current, migrated)) {
+                return;
+            }
+            lastPersistedRef.current = migrated;
+            if (localStorageEnabled) {
+                const serialized = serializeRef.current
+                    ? serializeRef.current(migrated)
+                    : storageSerializer.serialize(migrated);
+                localStorage.setItem(storageKey, serialized);
+            }
+            const urlValue = toUrlValueRef.current ? toUrlValueRef.current(migrated) : migrated;
+            const encoded = encode(urlValue);
+            updateSearchParam(encoded, { replace: true });
+        }, [encode, localStorageEnabled, storageKey, updateSearchParam]),
+    });
     const persistState = useCallback((state) => {
         if (dequal(lastPersistedRef.current, state)) {
             return;
@@ -12681,4 +13263,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
  */
 setupLibraryTranslations();
 
-export { Alert, Badge, Breadcrumb, 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 };
+export { Alert, Badge, Breadcrumb, 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_HASH_LENGTH, 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, useHashParamSync, 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 };