@trackunit/react-router-components 0.0.0-stage → 1.0.3

package/index.cjs.js

@@ -0,0 +1,1102 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var i18nLibraryTranslation = require('@trackunit/i18n-library-translation');
+var reactComponents = require('@trackunit/react-components');
+var cssClassVarianceUtilities = require('@trackunit/css-class-variance-utilities');
+var sharedUtils = require('@trackunit/shared-utils');
+var react = require('react');
+var reactRouter = require('@tanstack/react-router');
+var dequal = require('dequal');
+var zod = require('zod');
+var reactDrawer = require('@trackunit/react-drawer');
+
+var defaultTranslations = {
+	"breadcrumb.backButton": "Back",
+	"breadcrumb.expandButton": "expand"
+};
+
+/** The translation namespace for this library */
+const namespace = "react.react-router-components";
+/**
+ * The TranslationResource for this Library.
+ * Holds lazy loaded imports for all languages supported by the library.
+ *
+ * This is used to register the translations for this library before initializing i18next.
+ */
+const translations = {
+    ns: namespace,
+    default: defaultTranslations,
+    languages: {
+        de: () => Promise.resolve().then(function () { return require('./translation.cjs.js'); }),
+        da: () => Promise.resolve().then(function () { return require('./translation2.cjs.js'); }),
+        cs: () => Promise.resolve().then(function () { return require('./translation3.cjs.js'); }),
+        nl: () => Promise.resolve().then(function () { return require('./translation4.cjs.js'); }),
+        fr: () => Promise.resolve().then(function () { return require('./translation5.cjs.js'); }),
+        fi: () => Promise.resolve().then(function () { return require('./translation6.cjs.js'); }),
+        hu: () => Promise.resolve().then(function () { return require('./translation7.cjs.js'); }),
+        it: () => Promise.resolve().then(function () { return require('./translation8.cjs.js'); }),
+        nb: () => Promise.resolve().then(function () { return require('./translation9.cjs.js'); }),
+        pl: () => Promise.resolve().then(function () { return require('./translation10.cjs.js'); }),
+        pt: () => Promise.resolve().then(function () { return require('./translation11.cjs.js'); }),
+        ru: () => Promise.resolve().then(function () { return require('./translation12.cjs.js'); }),
+        ro: () => Promise.resolve().then(function () { return require('./translation13.cjs.js'); }),
+        es: () => Promise.resolve().then(function () { return require('./translation14.cjs.js'); }),
+        sv: () => Promise.resolve().then(function () { return require('./translation15.cjs.js'); }),
+        ja: () => Promise.resolve().then(function () { return require('./translation16.cjs.js'); }),
+        th: () => Promise.resolve().then(function () { return require('./translation17.cjs.js'); }),
+    },
+};
+/**
+ *  Local useTranslation for this specific library
+ */
+const useTranslation = () => i18nLibraryTranslation.useNamespaceTranslation(namespace);
+/**
+ * Registers the translations for this library
+ */
+const setupLibraryTranslations = () => {
+    i18nLibraryTranslation.registerTranslations(translations);
+};
+
+const cvaBreadcrumb = cssClassVarianceUtilities.cva({ base: ["my-4", "flex", "place-items-center"] });
+const cvaBreadcrumbItem = cssClassVarianceUtilities.cva({ base: ["flex", "items-center"] });
+const cvaBreadcrumbForLargeScreen = cssClassVarianceUtilities.cva({ base: ["flex", "flex-nowrap", "items-center"] });
+const cvaBreadcrumbForMediumScreen = cssClassVarianceUtilities.cva({
+    base: ["flex", "items-center"],
+    variants: {
+        expanded: {
+            true: "flex-wrap",
+            false: "flex-nowrap",
+        },
+    },
+    defaultVariants: { expanded: false },
+});
+
+/**
+ * BreadcrumbItem is a helper component that renders the individual breadcrumb item.
+ */
+const BreadcrumbItem = ({ item, "data-testid": dataTestId, className, style, }) => {
+    const id = sharedUtils.uuidv4();
+    return (jsxRuntime.jsx("div", { className: cvaBreadcrumbItem({ className }), "data-testid": dataTestId, id: `${item.props.label}-${id}`, style: style, children: item }));
+};
+
+/**
+ * BreadcrumbForLargeScreen is a helper component that renders the breadcrumb items for large screens.
+ */
+const BreadcrumbForLargeScreen = ({ "data-testid": dataTestId, breadcrumbItems, className, style, }) => {
+    return (jsxRuntime.jsx("div", { className: cvaBreadcrumbForLargeScreen({ className }), "data-testid": dataTestId, style: style, children: breadcrumbItems.map((item, index) => (jsxRuntime.jsx(BreadcrumbItem, { "data-testid": `BreadcrumbItem-${dataTestId}`, item: item }, `breadcrumbItem-${index}`))) }));
+};
+
+/**
+ * BreadcrumbForMediumScreen is a helper component that renders the breadcrumb items for medium screens.
+ */
+const BreadcrumbForMediumScreen = ({ "data-testid": dataTestId, breadcrumbItems, className, style, }) => {
+    const [t] = useTranslation();
+    const [expanded, setExpanded] = react.useState(false);
+    const getReducedArray = react.useCallback(() => {
+        let reducedArrayElements = [];
+        const collapsibleButton = (jsxRuntime.jsxs("div", { className: cvaBreadcrumbItem(), children: [jsxRuntime.jsx(reactComponents.IconButton, { "data-testid": `collapsibleButton-${dataTestId}`, icon: jsxRuntime.jsx(reactComponents.Icon, { name: "EllipsisHorizontal" }), onClick: () => setExpanded(true), size: "small", title: t("breadcrumb.expandButton"), variant: "ghost-neutral" }), jsxRuntime.jsx(reactComponents.Icon, { className: "text-neutral-300", name: "Slash", size: "small" })] }));
+        const firstBreadcrumbItem = breadcrumbItems[0];
+        if (firstBreadcrumbItem && breadcrumbItems.length > 3) {
+            const lastTwoBreadcrumbItem = breadcrumbItems.slice(-2);
+            reducedArrayElements = [firstBreadcrumbItem, collapsibleButton, ...lastTwoBreadcrumbItem];
+        }
+        return reducedArrayElements;
+    }, [breadcrumbItems, dataTestId, t]);
+    const reducedArray = getReducedArray();
+    return (jsxRuntime.jsx("div", { className: cvaBreadcrumbForMediumScreen({ className, expanded }), "data-testid": dataTestId, style: style, children: (!expanded && reducedArray.length !== 0 ? reducedArray : breadcrumbItems).map(item => (jsxRuntime.jsx(BreadcrumbItem, { "data-testid": `breadcrumbItem-${dataTestId}`, item: item }, `${item.props.label}-${sharedUtils.uuidv4()}`))) }));
+};
+
+/**
+ * BreadcrumbForSmallScreen is a helper component that renders the breadcrumb items for small screens.
+ */
+const BreadcrumbForSmallScreen = ({ "data-testid": dataTestId, breadcrumbItems, className, style, }) => {
+    const lastBreadcrumbItem = breadcrumbItems.slice(-1);
+    return (jsxRuntime.jsx("div", { className: className, "data-testid": dataTestId, style: style, children: lastBreadcrumbItem.map((item, index) => (jsxRuntime.jsx(BreadcrumbItem, { "data-testid": `breadcrumbItem-${dataTestId}`, item: item }, `breadcrumbItem-${index}`))) }));
+};
+
+/**
+ * BreadcrumbContainer is a helper component that renders the breadcrumb items based on the screen size.
+ *
+ * @param {BreadcrumbContainerProps} props - The props for the BreadcrumbContainer component
+ */
+const BreadcrumbContainer = ({ className, "data-testid": dataTestId, breadcrumbItems, style, ref, }) => {
+    const { isLg: isLargeScreen, isMd: isMediumScreen, isXs: isSmallScreen } = reactComponents.useViewportBreakpoints();
+    const sharedContainerProps = { className, "data-testid": dataTestId, ref, style };
+    if (isLargeScreen) {
+        return (jsxRuntime.jsx("div", { ...sharedContainerProps, children: jsxRuntime.jsx(BreadcrumbForLargeScreen, { breadcrumbItems: breadcrumbItems, "data-testid": `largeScreen-${dataTestId}` }) }));
+    }
+    if (isMediumScreen) {
+        return (jsxRuntime.jsx("div", { ...sharedContainerProps, children: jsxRuntime.jsx(BreadcrumbForMediumScreen, { breadcrumbItems: breadcrumbItems, "data-testid": `mediumScreen-${dataTestId}` }) }));
+    }
+    if (isSmallScreen) {
+        return (jsxRuntime.jsx("div", { ...sharedContainerProps, children: jsxRuntime.jsx(BreadcrumbForSmallScreen, { breadcrumbItems: breadcrumbItems, "data-testid": `smallScreen-${dataTestId}` }) }));
+    }
+    return (jsxRuntime.jsx("div", { ...sharedContainerProps, children: jsxRuntime.jsx(BreadcrumbForLargeScreen, { breadcrumbItems: breadcrumbItems, "data-testid": `largeScreen-${dataTestId}` }) }));
+};
+
+/**
+ * useBreadcrumbItemsToRender is a custom hook that takes an array of BreadcrumbItemProps and returns an array of React.ReactElement
+ */
+const useBreadcrumbItemsToRender = (breadcrumbItems) => {
+    return react.useMemo(() => breadcrumbItems.map((item, index, array) => {
+        const isLast = index === array.length - 1;
+        if (!isLast) {
+            return (jsxRuntime.jsxs("div", { className: "flex items-center", children: [jsxRuntime.jsx(reactComponents.Button, { asChild: true, size: "small", variant: "ghost-neutral", children: jsxRuntime.jsx(reactRouter.Link, { to: item.to, children: item.label }) }), jsxRuntime.jsx(reactComponents.Icon, { className: "text-neutral-300", name: "Slash", size: "small" })] }, index));
+        }
+        return (jsxRuntime.jsx(reactComponents.Text, { className: "text-nowrap pl-2 font-medium", size: "small", children: item.label }, index));
+    }), [breadcrumbItems]);
+};
+
+/**
+ * The breadcrumb component shows a user's location in a website or application. Breadcrumbs are particularly useful when a large amount of content is organized in a hierarchical manner. They streamline navigation, minimize the steps required to revisit previous pages, and offer contextual insights to the users.
+ *
+ * All items except the last are rendered as clickable links. The last item is rendered as plain text representing the current page.
+ * The component automatically adapts to the screen size: on large screens all items are visible, on medium screens middle items collapse behind an ellipsis button, and on small screens only the current page is shown.
+ *
+ * ### When to use
+ * Use breadcrumbs when deep navigation is available, on apps or pages where users might dive into content and could benefit from a quick way to return to higher levels. Breadcrumbs display the current screen as the final item in the list to make it clear where the user is.
+ *
+ * ### When not to use
+ * Do not use on the first hierarchal level, such as a home page or a main page, as there is no previous step the user can get to.
+ * Avoid using breadcrumbs to indicate forthcoming steps. For processes with sequential steps, use a wizard flow instead.
+ *
+ * @example Basic breadcrumb navigation
+ * ```tsx
+ * import { Breadcrumb } from "@trackunit/react-router-components";
+ * import { useNavigate } from "@tanstack/react-router";
+ *
+ * const AssetDetailBreadcrumb = () => {
+ *   const navigate = useNavigate();
+ *
+ *   return (
+ *     <Breadcrumb
+ *       breadcrumbItems={[
+ *         { label: "Fleet", to: "/fleet" },
+ *         { label: "Assets", to: "/fleet/assets" },
+ *         { label: "Excavator 001", to: "/fleet/assets/123" },
+ *       ]}
+ *       onClickBack={() => navigate({ to: "/fleet/assets" })}
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {BreadcrumbProps} props - The props for the Breadcrumb component
+ * @returns {ReactElement} Breadcrumb component
+ */
+const Breadcrumb = ({ className, "data-testid": dataTestId, breadcrumbItems, onClickBack, style, ref, }) => {
+    const [t] = useTranslation();
+    const breadCrumbItemsToJSX = useBreadcrumbItemsToRender(breadcrumbItems);
+    return (jsxRuntime.jsxs("div", { className: cvaBreadcrumb({ className }), "data-testid": dataTestId, ref: ref, style: style, children: [jsxRuntime.jsx(reactComponents.IconButton, { "data-testid": `backButton-${dataTestId}`, icon: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowLeft", size: "small" }), onClick: onClickBack, size: "small", title: t("breadcrumb.backButton"), variant: "ghost-neutral" }), jsxRuntime.jsx("div", { children: jsxRuntime.jsx(BreadcrumbContainer, { breadcrumbItems: breadCrumbItemsToJSX, "data-testid": dataTestId }) })] }));
+};
+
+const searchRecordSchema = zod.z.record(zod.z.string(), zod.z.unknown());
+const primitiveSearchValueSchema = zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()]);
+/**
+ * Reads one search param from a TanStack `useSearch({ strict: false })` result.
+ *
+ * The registered route tree often has an empty or closed search schema, so a
+ * string key cannot index that type. Parsing to a string record keeps the
+ * lookup valid for every app router.
+ */
+const readPrimitiveSearchParam = (search, key) => {
+    const parsedSearch = searchRecordSchema.safeParse(search);
+    if (!parsedSearch.success) {
+        return undefined;
+    }
+    const parsedValue = primitiveSearchValueSchema.safeParse(parsedSearch.data[key]);
+    if (!parsedValue.success) {
+        return undefined;
+    }
+    return String(parsedValue.data);
+};
+
+/**
+ * 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
+ * host + path + query + hash string.
+ */
+const MAX_URL_LENGTH = 5000;
+/**
+ * Maximum length of the URL fragment after adding one persisted entry.
+ * Oversized new entries are skipped; oversized replacements remove the stale
+ * entry so localStorage remains authoritative.
+ *
+ * The fragment is never sent to the server, so the WAF cap above does not
+ * apply. 64 KB stays well below typical browser URL limits (Chromium ≳ 100 KB,
+ * Firefox ≳ 64 KB on the address bar) while leaving generous headroom for any
+ * realistic table state.
+ */
+const MAX_HASH_LENGTH = 64 * 1024;
+/**
+ * Syncs an encoded string value with a single named entry in the URL — either
+ * a search param or an entry inside the hash fragment — via Tanstack Router.
+ *
+ * Writes go through the application router so other search params and
+ * foreign fragment content are preserved. Each slot has a size guard
+ * ({@link MAX_URL_LENGTH} for search, {@link MAX_HASH_LENGTH} for hash); an
+ * oversized value is dropped from the URL and localStorage stays
+ * authoritative. External changes to the entry (browser back/forward, a
+ * pasted link, a foreign router push) fire `onExternalChange`.
+ *
+ * Writes are dispatched via a pending-write queue rather than calling
+ * `navigate` directly. Tanstack Router's `router.state.status === "pending"`
+ * is common during the first paint of a route (loaders, suspense), and an
+ * implementation that simply returned in that case lost the write outright.
+ * `updateSearchParam` stores the latest attempted write and schedules an rAF
+ * flush; the flush only navigates when the router is idle, and an effect
+ * retries whenever the router settles. A queued write is dropped on unmount so
+ * it cannot drain onto the next route.
+ *
+ * @param options - Configuration for the URL entry sync.
+ * @param options.key - The search param name or fragment entry name.
+ * @param options.location - `"search"` or `"hash"`.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the entry changes externally.
+ * @param options.replace - `true` to always use `replaceState`; `false` to always push.
+ *   Default: replace when the entry is being added, push when it already has a value.
+ */
+const useUrlParamSync = ({ key, location: urlLocation, enabled = true, onExternalChange, replace: replaceOption, }) => {
+    const navigate = reactRouter.useNavigate();
+    const location = reactRouter.useLocation();
+    const router = reactRouter.useRouter();
+    const search = reactRouter.useSearch({ strict: false, shouldThrow: false });
+    const isHash = urlLocation === "hash";
+    const lastWrittenRef = react.useRef(undefined);
+    const pendingWriteRef = react.useRef(null);
+    const onExternalChangeRef = react.useRef(onExternalChange);
+    react.useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentValue = react.useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        return isHash ? sharedUtils.readHashKey(location.hash, key) : readPrimitiveSearchParam(search, key);
+    }, [enabled, isHash, location.hash, search, key]);
+    react.useEffect(() => {
+        if (!enabled || currentValue === undefined) {
+            return;
+        }
+        if (currentValue === lastWrittenRef.current || lastWrittenRef.current === undefined) {
+            return;
+        }
+        // A caller may have primed `lastWrittenRef` via `updateSearchParam` while
+        // the URL still carries the previous value (queued rAF / router pending).
+        // Treating that stale URL as an external change would reload state from
+        // persistence before the write lands.
+        if (pendingWriteRef.current !== null) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            onExternalChangeRef.current?.();
+        });
+    }, [currentValue, enabled]);
+    // Read through refs so the write path does not change identity on every
+    // navigation; it only needs the location and current value at the moment it
+    // flushes, which may be an animation frame after it was queued.
+    const locationRef = react.useRef(location);
+    const currentValueRef = react.useRef(currentValue);
+    react.useEffect(() => {
+        locationRef.current = location;
+        currentValueRef.current = currentValue;
+    }, [location, currentValue]);
+    const getUrlLengthWithSearchParam = react.useCallback((paramValue, params) => {
+        const { href, searchStr, hash } = locationRef.current;
+        const otherParamsLength = sharedUtils.objectKeys(params)
+            .filter(k => k !== key)
+            .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 = href.length - (searchStr.length || 0) + (hash.length || 0);
+        return urlBase + otherParamsLength + 1 + key.length + 1 + paramValue.length;
+    }, [key]);
+    const flushPendingWrite = react.useCallback(() => {
+        const pending = pendingWriteRef.current;
+        if (pending === null) {
+            return;
+        }
+        if (router.state.status === "pending") {
+            // Keep the write queued; the status-watcher effect retries once idle.
+            return;
+        }
+        pendingWriteRef.current = null;
+        const { encodedValue } = pending;
+        const { hash } = locationRef.current;
+        const valueInUrl = currentValueRef.current;
+        const shouldReplace = replaceOption ?? !Boolean(valueInUrl);
+        if (!isHash) {
+            void navigate({
+                to: ".",
+                search: (prev) => getUrlLengthWithSearchParam(encodedValue ?? "", prev) <= MAX_URL_LENGTH
+                    ? { ...prev, [key]: encodedValue }
+                    : { ...prev, [key]: undefined },
+                hash,
+                replace: shouldReplace,
+            });
+            return;
+        }
+        let nextHash = sharedUtils.writeHashKey(hash, key, encodedValue);
+        let removedOversizedValue = false;
+        if (nextHash.length > MAX_HASH_LENGTH) {
+            if (valueInUrl === undefined) {
+                return;
+            }
+            nextHash = sharedUtils.writeHashKey(hash, key, undefined);
+            removedOversizedValue = true;
+        }
+        void navigate({
+            to: ".",
+            // Returning the same `prev` reference leaves the search params
+            // unchanged; `search` must still be passed for the router types.
+            search: (prev) => prev,
+            // The router adds the `#` itself; forwarding it would double it.
+            hash: nextHash.startsWith("#") ? nextHash.slice(1) : nextHash,
+            replace: removedOversizedValue ? true : shouldReplace,
+        });
+    }, [router.state.status, replaceOption, isHash, navigate, getUrlLengthWithSearchParam, key]);
+    react.useEffect(() => {
+        if (router.state.status === "pending" || pendingWriteRef.current === null) {
+            return;
+        }
+        flushPendingWrite();
+    }, [router.state.status, flushPendingWrite]);
+    react.useEffect(() => () => {
+        pendingWriteRef.current = null;
+    }, []);
+    const updateSearchParam = react.useCallback((encodedValue) => {
+        if (!enabled) {
+            return;
+        }
+        // Dedupe against the last committed write or the value already queued;
+        // both represent the caller's intent.
+        const inFlightOrLastWritten = pendingWriteRef.current?.encodedValue ?? lastWrittenRef.current;
+        if (encodedValue !== undefined && encodedValue === inFlightOrLastWritten) {
+            return;
+        }
+        // Prime here (not in the flush) so the external-change detector treats
+        // this value as the caller's state even when the flush is a no-op or
+        // stays queued during a pending router phase.
+        lastWrittenRef.current = encodedValue;
+        if (currentValueRef.current === encodedValue) {
+            return;
+        }
+        pendingWriteRef.current = { encodedValue };
+        requestAnimationFrame(() => {
+            flushPendingWrite();
+        });
+    }, [enabled, flushPendingWrite]);
+    return react.useMemo(() => ({ searchValue: currentValue, updateSearchParam }), [currentValue, updateSearchParam]);
+};
+
+/**
+ * Raw localStorage access, kept in one place so this file's exemption from the
+ * no-direct-storage-access rule is centralised rather than repeated at each call site.
+ *
+ * TODO: migrate to the useLocalStorage hook — this file was exempted when the
+ * no-direct-storage-access rule was introduced.
+ */
+/* eslint-disable no-restricted-globals */
+const rawLocalStorage = {
+    read: (key) => localStorage.getItem(key),
+    write: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+};
+/**
+ * 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 the URL slot holds a value, 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.
+ *
+ * A value that comes only from localStorage is never written to the URL on
+ * load. Copying it left a layout in history, bookmarks, and login redirects,
+ * which then replayed an older layout over the saved one (GLU-2396). The URL
+ * is written when the consumer persists a change.
+ *
+ * `persistState` writes to localStorage (`storageSerializer`) and to the URL
+ * (via `toUrlValue` + encoding).
+ * Each slot skips a value equal to its last write. The URL side compares what
+ * would land in the URL (the `toUrlValue` projection and the identity stamp),
+ * starting from the projection of the hydrated state and the stamp the URL
+ * carries: echoing `initialState`, or changing only a field the projection
+ * strips, writes no URL entry, while an equal state persisted after the
+ * identity resolves rewrites the URL with its stamp. The storage side starts
+ * from what localStorage held, so a consumer that persists `initialState`
+ * after opening a link saves that link's state for the account that opened
+ * it, and a reload of the account's own link writes nothing.
+ * `persistToStorage` and `persistToUrl` are the same two halves exposed
+ * separately for consumers that schedule them differently; passing `undefined`
+ * removes the entry rather than writing an empty value.
+ *
+ * The snapshot is re-read when the storage key or the storage/merge options
+ * change, in the same render, so a write in that commit already sees the
+ * state for the new key.
+ *
+ * @param options - Configuration for the persisted state.
+ * @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.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.localStorageEnabled - When `false` localStorage is neither read nor written (default `true`).
+ * @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"`.
+ * @param options.stampUrlWithIdentity - Stamp URL writes with the current identity so the login
+ *   redirect can drop entries left by another account on this browser. Default `false`.
+ */
+const usePersistedState = ({ key, validate, toUrlValue, fromUrlValue, localStorageEnabled = true, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", stampUrlWithIdentity = false, }) => {
+    const { encode, decode } = reactComponents.useCustomEncoding();
+    // Fingerprint of the identity this hook writes URL values for. `undefined`
+    // while the identity is unresolved (or when stamping is off): writes are
+    // then unstamped.
+    const currentUrlOwner = react.useMemo(() => (stampUrlWithIdentity && clientSideUserId !== undefined ? sharedUtils.identityFingerprint(clientSideUserId) : undefined), [stampUrlWithIdentity, clientSideUserId]);
+    const { searchValue: urlValue, updateSearchParam: updateUrlValue } = useUrlParamSync({
+        key,
+        location: urlLocation,
+        replace,
+    });
+    const storageKey = reactComponents.useStorageKey(key, clientSideUserId);
+    // `toUrlValue` is read through a ref so the write callbacks stay stable
+    // when a consumer passes an inline function.
+    const toUrlValueRef = react.useRef(toUrlValue);
+    react.useEffect(() => {
+        toUrlValueRef.current = toUrlValue;
+    }, [toUrlValue]);
+    const readStoredState = react.useCallback((validateState) => {
+        if (!localStorageEnabled) {
+            return undefined;
+        }
+        try {
+            const raw = rawLocalStorage.read(storageKey);
+            if (!raw) {
+                return undefined;
+            }
+            return validateState(sharedUtils.storageSerializer.deserialize(raw));
+        }
+        catch {
+            return undefined;
+        }
+    }, [localStorageEnabled, storageKey]);
+    const readPersistedState = react.useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
+        let urlState;
+        let urlStamp;
+        if (valueFromUrl) {
+            try {
+                // The ownership stamp decides nothing on read (the login redirect
+                // does that, see `useStripForeignIdentityHash`); it is kept only to
+                // seed the URL dedupe with what the URL is currently stamped with.
+                const { value, owner } = sharedUtils.unwrapUrlOwner(decode(valueFromUrl));
+                urlState = validateState(transformFromUrlValue ? transformFromUrlValue(value) : value);
+                urlStamp = urlState === undefined ? undefined : { owner };
+            }
+            catch {
+                urlState = undefined;
+            }
+        }
+        // Storage is read even when the URL wins outright: it seeds the storage
+        // dedupe, so persisting the hydrated state writes only when the URL
+        // changed something.
+        const stored = readStoredState(validateState);
+        let hydrated;
+        if (urlState === undefined) {
+            hydrated = stored;
+        }
+        else if (mergeWithStorageOnRead && stored !== undefined) {
+            // URL fields take precedence; storage fills in whatever the URL
+            // omits (e.g. fields stripped by `toUrlValue`).
+            hydrated = { ...stored, ...urlState };
+        }
+        else {
+            hydrated = urlState;
+        }
+        return { initialState: hydrated, storedState: stored, urlValue: urlStamp };
+    }, [decode, mergeWithStorageOnRead, readStoredState]);
+    // The shareable projection of `state`: what a URL write carries before
+    // encoding. The URL dedupe compares this, not the whole state, so a change
+    // confined to a field `toUrlValue` strips is not a URL change.
+    const projectForUrl = react.useCallback((state) => (toUrlValueRef.current ? toUrlValueRef.current(state) : state), []);
+    // Every URL write goes through here so the ownership stamp is applied uniformly.
+    const encodeUrlWrite = react.useCallback(({ projected, owner }) => encode(owner === undefined ? projected : sharedUtils.wrapUrlOwner(projected, owner)), [encode]);
+    // `readPersistedState` changes identity exactly when an input that changes
+    // what a read returns does (storage key, storage/merge options), so the
+    // snapshot is re-read then and only then — synchronously, in the render
+    // where the input changed, by deriving state from the changed input. A URL
+    // change after mount or an inline `validate` deliberately does not
+    // re-hydrate `initialState`: `useUrlParamSync` owns URL changes.
+    const readSnapshot = () => ({
+        readWith: readPersistedState,
+        ...readPersistedState({ valueFromUrl: urlValue, validateState: validate, transformFromUrlValue: fromUrlValue }),
+    });
+    const [snapshot, setSnapshot] = react.useState(readSnapshot);
+    if (snapshot.readWith !== readPersistedState) {
+        setSnapshot(readSnapshot());
+    }
+    const { initialState, storedState } = snapshot;
+    // Last value written to each slot, for deduping. Two refs, not one, because
+    // a consumer may schedule the two writes differently (storage at once, URL
+    // debounced). Both are re-seeded whenever the snapshot is re-read so the
+    // first write to a newly scoped key is never skipped.
+    //
+    // The storage side starts as what storage held, so persisting the hydrated
+    // state after opening a link writes only when the URL changed something.
+    //
+    // The URL side holds what a write would put in the URL: the shareable
+    // projection plus the owner stamp. It starts as the projection of the
+    // hydrated value, so a consumer that echoes `initialState` on mount, or
+    // changes only a field the projection strips, writes nothing: a layout read
+    // from storage must not grow a URL entry (GLU-2396). Its owner starts as the
+    // stamp the URL carries (or the current owner when the URL is empty), so an
+    // equal state persisted after the identity resolves still rewrites the URL
+    // with its stamp.
+    const urlOwnerSeed = snapshot.urlValue ? snapshot.urlValue.owner : currentUrlOwner;
+    const seedUrlWrite = react.useCallback((project) => initialState === undefined ? undefined : { projected: project(initialState), owner: urlOwnerSeed }, [initialState, urlOwnerSeed]);
+    const lastStoredRef = react.useRef(storedState);
+    // The first seed is computed during render, so it projects with the
+    // `toUrlValue` prop rather than reading `toUrlValueRef` (refs are not read
+    // in render); the projection is cheap, and later seeds come from the effect.
+    const lastUrlRef = react.useRef(seedUrlWrite(state => (toUrlValue ? toUrlValue(state) : state)));
+    react.useEffect(() => {
+        lastStoredRef.current = storedState;
+        lastUrlRef.current = seedUrlWrite(projectForUrl);
+    }, [seedUrlWrite, projectForUrl, storedState]);
+    const persistToStorage = react.useCallback((state) => {
+        if (!localStorageEnabled) {
+            return;
+        }
+        if (state === undefined) {
+            lastStoredRef.current = undefined;
+            rawLocalStorage.remove(storageKey);
+            return;
+        }
+        if (dequal.dequal(lastStoredRef.current, state)) {
+            return;
+        }
+        try {
+            rawLocalStorage.write(storageKey, sharedUtils.storageSerializer.serialize(state));
+            lastStoredRef.current = state;
+        }
+        catch {
+            // Quota or a disabled store: the next write retries; the URL is unaffected.
+        }
+    }, [localStorageEnabled, storageKey]);
+    const persistToUrl = react.useCallback((state) => {
+        if (state === undefined) {
+            lastUrlRef.current = undefined;
+            updateUrlValue(undefined);
+            return;
+        }
+        const write = { projected: projectForUrl(state), owner: currentUrlOwner };
+        const last = lastUrlRef.current;
+        // Same projection: write only to add or change a stamp. An unresolved
+        // identity never rewrites a stamped URL just to strip the stamp; it is
+        // re-stamped once the identity resolves.
+        if (last !== undefined &&
+            dequal.dequal(last.projected, write.projected) &&
+            (last.owner === write.owner || write.owner === undefined)) {
+            return;
+        }
+        lastUrlRef.current = write;
+        updateUrlValue(encodeUrlWrite(write));
+    }, [currentUrlOwner, encodeUrlWrite, projectForUrl, updateUrlValue]);
+    const persistState = react.useCallback((state) => {
+        persistToStorage(state);
+        persistToUrl(state);
+    }, [persistToStorage, persistToUrl]);
+    return react.useMemo(() => ({ initialState, persistState, persistToStorage, persistToUrl }), [initialState, persistState, persistToStorage, persistToUrl]);
+};
+
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Thin wrapper over {@link useUrlParamSync} with `location: "search"`; see it
+ * for the write queue, the size guard (`MAX_URL_LENGTH`), and external-change
+ * detection.
+ *
+ * @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 = (options) => useUrlParamSync({ ...options, location: "search" });
+
+/**
+ * A text link to a route inside the app, rendered through the router's `Link`.
+ * Use `ExternalLink` from `@trackunit/react-components` for links that leave the app.
+ *
+ * @param {RouteLinkProps} props The props for the RouteLink component.
+ * @returns {ReactElement} RouteLink component
+ */
+const RouteLink = ({ to, text, title, onClick, className, "data-testid": dataTestId, }) => {
+    return (jsxRuntime.jsx(reactRouter.Link, { className: cvaStyledLink({ className }), "data-testid": dataTestId, onClick: onClick, title: title, to: to, children: text }));
+};
+const cvaStyledLink = cssClassVarianceUtilities.cva({ base: ["text-primary-600", "hover:text-primary-700"] });
+
+const DEFAULT_PARAM_NAME = "c";
+const DEFAULT_DEBOUNCE_MS = 300;
+/**
+ * Reads a cursor from the URL search params on mount and provides a debounced
+ * updater for writing it back. Uses `replace: true` to avoid polluting browser
+ * history with every scroll position change.
+ *
+ * Wire `initialCursor` into `usePaginationQuery` and `updateCursor` into
+ * `useBidirectionalScroll`'s `onTopItemChange` callback (mapping index to cursor).
+ *
+ * A pending write is dropped whenever a path-changing navigation starts or the
+ * location has moved on: the write targets `to: "."`, so landing it after the
+ * user opened a row would replace their destination with the list they came
+ * from.
+ */
+const useCursorUrlSync = ({ paramName = DEFAULT_PARAM_NAME, debounceMs = DEFAULT_DEBOUNCE_MS, } = {}) => {
+    const router = reactRouter.useRouter();
+    const navigate = reactRouter.useNavigate();
+    // Read the cursor off the router rather than `useSearch`, which would
+    // subscribe the table to its own writes and re-render every row mid-scroll.
+    const [initialCursor] = react.useState(() => {
+        const entry = Object.entries(router.latestLocation.search).find(([key]) => key === paramName);
+        return typeof entry?.[1] === "string" ? entry[1] : undefined;
+    });
+    const timerRef = react.useRef(undefined);
+    const cancelPendingUpdate = react.useCallback(() => {
+        if (timerRef.current !== undefined) {
+            clearTimeout(timerRef.current);
+            timerRef.current = undefined;
+        }
+    }, []);
+    const paramNameRef = react.useRef(paramName);
+    react.useEffect(() => {
+        paramNameRef.current = paramName;
+    }, [paramName]);
+    const updateCursor = react.useCallback((cursor) => {
+        cancelPendingUpdate();
+        const scheduledAtPathname = router.latestLocation.pathname;
+        timerRef.current = setTimeout(() => {
+            timerRef.current = undefined;
+            if (router.latestLocation.pathname !== scheduledAtPathname) {
+                return;
+            }
+            void navigate({
+                to: ".",
+                search: (prev) => ({
+                    ...prev,
+                    [paramNameRef.current]: cursor,
+                }),
+                // Without this the router drops the fragment, and with it the table layout.
+                hash: true,
+                replace: true,
+            });
+        }, debounceMs);
+    }, [cancelPendingUpdate, debounceMs, navigate, router]);
+    // Only path-changing navigations invalidate a pending write. Same-pathname
+    // navigations (filter bar, table persistence, map viewBox) share this URL and
+    // their writes must not cancel ours. Cancelling here rather than relying on
+    // the pathname check alone also covers navigating away and back within the
+    // debounce window, which would otherwise land a stale cursor on a fresh list.
+    react.useEffect(() => router.subscribe("onBeforeNavigate", event => {
+        if (event.pathChanged) {
+            cancelPendingUpdate();
+        }
+    }), [cancelPendingUpdate, router]);
+    react.useEffect(() => {
+        return cancelPendingUpdate;
+    }, [cancelPendingUpdate]);
+    return react.useMemo(() => ({ initialCursor, updateCursor }), [initialCursor, updateCursor]);
+};
+
+const readOwnValue = (record, key) => {
+    if (record === null || record === undefined) {
+        return undefined;
+    }
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+        return undefined;
+    }
+    return Reflect.get(record, key);
+};
+// The only place a router value becomes `TId`, and the narrowing is unchecked: the `from` route's
+// `params.parse` / `validateSearch` owns the id's shape, and `TId` has no runtime form the hook
+// could check against. This only drops values that cannot be an id at all. TanStack's default
+// search parser JSON-parses values, so `?rowId=42` arrives as the number 42; integers beyond
+// Number.MAX_SAFE_INTEGER have already lost digits, so they are no selection.
+const trustRouteValidatedId = (value) => {
+    const isRouteValidatedId = (candidate) => (typeof candidate === "string" && candidate.length > 0) ||
+        (typeof candidate === "number" && Number.isSafeInteger(candidate));
+    return isRouteValidatedId(value) ? value : undefined;
+};
+const findFromMatch = (matches, fromIds) => matches.find(match => fromIds.includes(match.routeId));
+const readSelection = (match, param, paramKind) => readOwnValue(paramKind === "path" ? match?.params : match?.search, param);
+/** The route `routeId` names and its ancestors, root first. */
+const routeChain = (routesById, routeId) => {
+    const routes = [];
+    for (let route = routesById[routeId]; route !== undefined; route = route.parentRoute) {
+        routes.unshift(route);
+    }
+    return routes;
+};
+// The blocker's locations and `getMatchedRoutes` give raw path params, while route matches carry
+// them after every matched route's `params.parse`, root first. Applying the same parses keeps the
+// ids compared and written equal to the ones read from `router.state.matches`.
+const parsePathParams = (routes, rawParams) => {
+    const params = { ...rawParams };
+    routes.forEach(route => {
+        const parse = route.options.params?.parse ?? route.options.parseParams;
+        if (parse === undefined) {
+            return;
+        }
+        try {
+            Object.assign(params, parse(params));
+        }
+        catch {
+            // Like the router, a failed parse leaves the params as they were.
+        }
+    });
+    return params;
+};
+const applySearchValidator = (validator, input) => {
+    if (validator === undefined) {
+        return {};
+    }
+    if ("~standard" in validator) {
+        const result = validator["~standard"].validate(input);
+        if (result instanceof Promise || result.issues !== undefined) {
+            throw new Error("useRouterDrawer: search validation failed");
+        }
+        return result.value;
+    }
+    if ("parse" in validator) {
+        return validator.parse(input);
+    }
+    return validator(input);
+};
+// The blocker's locations and `router.latestLocation` give the raw parsed search, while route
+// matches carry it after every matched route's `validateSearch`, root first, each over the search
+// validated so far. Applying the same validators keeps search ids equal to the rendered ones.
+// This mirrors `validateSearch` and `matchRoutes` in `@tanstack/router-core` 1.114; re-check it on
+// upgrade. Unlike the router, it records no `searchError` and ignores a non-object result.
+const validateSearch = (routes, rawSearch) => routes.reduce((search, route) => {
+    try {
+        const validated = applySearchValidator(route.options.validateSearch, { ...search });
+        return typeof validated === "object" && validated !== null ? { ...search, ...validated } : search;
+    }
+    catch {
+        // Like the router, a failed validation leaves the search as it was.
+        return search;
+    }
+}, { ...rawSearch });
+/** `routes` up to and including the first one in `fromIds`, or `undefined` if none is. */
+const routesThroughFrom = (routes, fromIds) => {
+    const fromIndex = routes.findIndex(route => fromIds.includes(route.id));
+    return fromIndex === -1 ? undefined : routes.slice(0, fromIndex + 1);
+};
+// After this drawer's guard allows a move, `setId` navigates with a fresh token in the history
+// state, and the blocker lets exactly the navigation carrying it through (once). The navigation
+// itself is the identity: a token kept in the router would also bless the next leave when another
+// blocker vetoes the allowed move, since a vetoed navigation never settles to clear it.
+const ALLOWED_MOVE_STATE_KEY = "useRouterDrawerAllowedMove";
+let allowedMoveCount = 0;
+const createMoveToken = () => {
+    allowedMoveCount += 1;
+    return `${Date.now().toString(36)}-${allowedMoveCount}`;
+};
+const withMoveToken = (moveToken) => moveToken === undefined
+    ? {}
+    : { state: previous => Object.assign({}, previous, { [ALLOWED_MOVE_STATE_KEY]: moveToken }) };
+const useRouterSelection = ({ from, param, paramKind = "search", onBeforeClose, }) => {
+    const router = reactRouter.useRouter();
+    const fromIds = typeof from === "string" ? [from] : from;
+    const unknownRouteId = fromIds.find(routeId => readOwnValue(router.routesById, routeId) === undefined);
+    if (unknownRouteId !== undefined) {
+        throw new Error(`useRouterDrawer: "from" route id "${unknownRouteId}" is not registered in the router.`);
+    }
+    const value = reactRouter.useRouterState({
+        select: state => readSelection(findFromMatch(state.matches, fromIds), param, paramKind),
+    });
+    const navigate = reactRouter.useNavigate();
+    const id = trustRouteValidatedId(value);
+    const navigateRef = react.useRef(navigate);
+    const routerRef = react.useRef(router);
+    const fromIdsRef = react.useRef(fromIds);
+    const onBeforeCloseRef = react.useRef(onBeforeClose);
+    const guardPendingRef = react.useRef(false);
+    const allowedMoveRef = react.useRef(undefined);
+    react.useLayoutEffect(() => {
+        navigateRef.current = navigate;
+        routerRef.current = router;
+        fromIdsRef.current = fromIds;
+        onBeforeCloseRef.current = onBeforeClose;
+    });
+    // Returns whether the guard allowed leaving the selection.
+    const askGuard = react.useCallback(async (guard) => {
+        guardPendingRef.current = true;
+        try {
+            return (await guard()) === true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            guardPendingRef.current = false;
+        }
+    }, []);
+    const blockerFn = react.useCallback(async ({ currentLocation, nextLocation }) => {
+        const allowedMove = allowedMoveRef.current;
+        if (allowedMove !== undefined && readOwnValue(nextLocation.state, ALLOWED_MOVE_STATE_KEY) === allowedMove) {
+            // Consumed here, as soon as this blocker accepts the move, not when its navigation settles:
+            // another blocker can still veto it, and then nothing settles.
+            allowedMoveRef.current = undefined;
+            return false;
+        }
+        const guard = onBeforeCloseRef.current;
+        if (guard === undefined) {
+            return false;
+        }
+        // Same id alone is not "same selection": a route that reuses `param`'s name for something
+        // else must not be mistaken for the selection's own route, so its owner must match too. The
+        // owner is the matched `from` route, so child routes under it keep the selection.
+        const selectionAt = (historyLocation) => {
+            const parsedLocation = routerRef.current.parseLocation(undefined, historyLocation);
+            const { foundRoute, routeParams } = routerRef.current.getMatchedRoutes(parsedLocation);
+            if (foundRoute === undefined) {
+                return undefined;
+            }
+            const location = {
+                routeId: foundRoute.id,
+                params: routeParams,
+                search: parsedLocation.search,
+            };
+            const routes = routeChain(routerRef.current.looseRoutesById, location.routeId);
+            const throughFrom = routesThroughFrom(routes, fromIdsRef.current);
+            const fromRoute = throughFrom?.at(-1);
+            if (throughFrom === undefined || fromRoute === undefined) {
+                return undefined;
+            }
+            const locationId = trustRouteValidatedId(paramKind === "path"
+                ? readOwnValue(parsePathParams(routes, location.params), param)
+                : readOwnValue(validateSearch(throughFrom, location.search), param));
+            if (locationId === undefined) {
+                return undefined;
+            }
+            return { id: locationId, ownerRouteId: fromRoute.id };
+        };
+        const currentSelection = selectionAt(currentLocation);
+        if (currentSelection === undefined) {
+            return false;
+        }
+        const nextSelection = selectionAt(nextLocation);
+        const sameSelection = nextSelection !== undefined &&
+            Object.is(currentSelection.id, nextSelection.id) &&
+            currentSelection.ownerRouteId === nextSelection.ownerRouteId;
+        if (sameSelection) {
+            return false;
+        }
+        // The pending short-circuit only applies once a navigation is known to leave the selection:
+        // checked above so an unrelated or same-selection event (e.g. a same-URL popstate) passes
+        // through instead of being blocked, which on the pop path would send the user forward.
+        if (guardPendingRef.current) {
+            return true;
+        }
+        return !(await askGuard(guard));
+    }, [askGuard, param, paramKind]);
+    const isGuarding = onBeforeClose !== undefined && id !== undefined;
+    react.useEffect(() => {
+        if (!isGuarding) {
+            return undefined;
+        }
+        return router.history.block({ blockerFn, enableBeforeUnload: false });
+    }, [isGuarding, blockerFn, router]);
+    // Resolved from `router.latestLocation` on every call: `router.state.matches` lags a navigation
+    // that has not loaded yet, and a guard can settle long after `setId` was called. Every write
+    // passes `hash: true`, since TanStack drops the hash from a navigation that does not ask for it.
+    const planWrite = react.useCallback((nextId) => {
+        const latestRouter = routerRef.current;
+        const { latestLocation } = latestRouter;
+        const { matchedRoutes, routeParams } = latestRouter.getMatchedRoutes(latestLocation);
+        const throughFrom = routesThroughFrom(matchedRoutes, fromIdsRef.current);
+        const fromRoute = throughFrom?.at(-1);
+        if (paramKind === "search") {
+            const currentSearchId = trustRouteValidatedId(throughFrom === undefined
+                ? undefined
+                : readOwnValue(validateSearch(throughFrom, latestLocation.search), param));
+            if (Object.is(nextId, currentSearchId)) {
+                return undefined;
+            }
+            return {
+                currentId: currentSearchId,
+                commit: moveToken => navigateRef.current({
+                    to: ".",
+                    search: (prev) => ({ ...prev, [param]: nextId }),
+                    hash: true,
+                    replace: true,
+                    ...withMoveToken(moveToken),
+                }),
+            };
+        }
+        const params = parsePathParams(matchedRoutes, routeParams);
+        const currentId = trustRouteValidatedId(fromRoute === undefined ? undefined : readOwnValue(params, param));
+        if (Object.is(nextId, currentId)) {
+            return undefined;
+        }
+        // Targets are absolute: navigate's `from` is looked up in the lagging `router.state.matches`
+        // and throws when the latest location's from match is not there yet.
+        const fromPath = fromRoute?.fullPath;
+        if (fromPath !== undefined) {
+            return {
+                currentId,
+                commit: moveToken => navigateRef.current({
+                    to: nextId === undefined ? `${fromPath}/..` : fromPath,
+                    params: { ...params, [param]: nextId },
+                    search: true,
+                    hash: true,
+                    replace: true,
+                    ...withMoveToken(moveToken),
+                }),
+            };
+        }
+        if (nextId === undefined) {
+            return undefined;
+        }
+        const [onlyFromId, ...otherFromIds] = fromIdsRef.current;
+        const onlyFromPath = onlyFromId === undefined ? undefined : latestRouter.routesById[onlyFromId]?.fullPath;
+        if (onlyFromPath === undefined || otherFromIds.length > 0) {
+            throw new Error(`useRouterDrawer: opening "${param}" from closed needs a single "from" route id to navigate to; got ${JSON.stringify(fromIdsRef.current)}.`);
+        }
+        return {
+            currentId,
+            commit: moveToken => navigateRef.current({
+                to: onlyFromPath,
+                params: { ...params, [param]: nextId },
+                search: true,
+                hash: true,
+                replace: true,
+                ...withMoveToken(moveToken),
+            }),
+        };
+    }, [param, paramKind]);
+    const setId = react.useCallback((nextId) => {
+        const write = planWrite(nextId);
+        if (write === undefined) {
+            return;
+        }
+        if (guardPendingRef.current) {
+            return;
+        }
+        const guard = onBeforeCloseRef.current;
+        const fromId = write.currentId;
+        if (guard === undefined || fromId === undefined) {
+            void write.commit();
+            return;
+        }
+        // The guard runs here rather than in the blocker: a navigation handed to the blocker is built
+        // before the guard settles, so allowing it would undo URL changes made while it was pending.
+        // On allow the write is planned again from the latest location. Only this drawer's blocker
+        // lets that one navigation through, so other blockers still run and the guard is not asked twice.
+        void askGuard(guard).then(allowed => {
+            if (!allowed) {
+                return;
+            }
+            let allowedWrite;
+            try {
+                allowedWrite = planWrite(nextId);
+            }
+            catch {
+                // `planWrite` only throws when nothing is selected any more, which makes this attempt stale.
+                return;
+            }
+            // The selection moved while the guard was pending, so this attempt no longer applies.
+            if (allowedWrite === undefined || !Object.is(allowedWrite.currentId, fromId)) {
+                return;
+            }
+            const moveToken = createMoveToken();
+            allowedMoveRef.current = moveToken;
+            void allowedWrite.commit(moveToken);
+        });
+    }, [askGuard, planWrite]);
+    return { id, isOpen: id !== undefined, setId };
+};
+/**
+ * Ties a `Drawer`'s selection to a URL param. Wraps `useDrawer` and `useHold` so callers spread the
+ * result onto `Drawer` and never call either themselves.
+ *
+ * `id` is held through the close animation, so a query called as `useX(id, { skip: !id })` keeps
+ * serving the closing id's data while the drawer slides out, and is skipped once it has exited.
+ *
+ * When one component owns the URL state and a child renders `Drawer`, call this hook in the parent
+ * and pass the result down as props. The child spreads them onto `Drawer` and does not call `useDrawer`.
+ *
+ * Call the hook from a component that stays rendered while the `from` route is matched, such as the
+ * list or layout route that is an ancestor of `from`; otherwise the drawer is never shown.
+ *
+ * There is no `decode` option. `TId` is declared by the caller and not checked by the hook: the id
+ * is taken as the `from` route's `validateSearch` or `params.parse` produced it, so `TId` must match
+ * that output. Validate there, to produce numbers or reject bad values. A missing or empty param is
+ * treated as no selection, including a `params.parse` that falls back to `""` for invalid input.
+ *
+ * Every write (open, switch, close) replaces the current history entry, so Back never steps through
+ * drawer selections. Other search params and parent path params are kept. In path mode, switching
+ * ids navigates to the `from` route, dropping any deeper child segments, and closing navigates one
+ * path segment up from it.
+ *
+ * `onClose`, `onOpenChange` and `onBeforeClose` from `useDrawer` are not exposed: `onClose` is always
+ * `setId(undefined)`, and `onBeforeClose` runs through the router blocker, where forwarding it to
+ * `useDrawer` as well would guard twice. `onOpen` fires when the selection goes from none to an id, not on mount.
+ *
+ * @example
+ * ```tsx
+ * // Rendered by the `/templates` list route; `/templates/$templateId` parses the id.
+ * const { id, setId, ...drawer } = useRouterDrawer({
+ *   from: "/templates/$templateId",
+ *   param: "templateId",
+ *   paramKind: "path",
+ *   position: "right",
+ *   onBeforeClose: async () => confirmDiscard(),
+ * });
+ * const { data, loading } = useTemplate(id, { skip: !id });
+ * return <Drawer {...drawer}>...</Drawer>;
+ * ```
+ */
+const useRouterDrawer = ({ from, param, paramKind, onBeforeClose, variant, trapFocus, position, dismiss, onOpen, }) => {
+    const { id: selectedId, isOpen, setId } = useRouterSelection({ from, param, paramKind, onBeforeClose });
+    const drawer = reactDrawer.useDrawer({ isOpen, onClose: () => setId(undefined), variant, trapFocus, position, dismiss });
+    const id = reactComponents.useHold(selectedId, drawer.isExiting);
+    reactComponents.useWatch({
+        value: isOpen,
+        onChange: nowOpen => {
+            if (nowOpen) {
+                onOpen?.();
+            }
+        },
+    });
+    return react.useMemo(() => ({ ...drawer, id, setId }), [drawer, id, setId]);
+};
+
+/*
+ * ----------------------------
+ * | SETUP TRANSLATIONS START |
+ * ----------------------------
+ * This import and function call is needed to register translations for this library.
+ * Do not remove this if this library has translations.
+ */
+setupLibraryTranslations();
+
+exports.Breadcrumb = Breadcrumb;
+exports.MAX_URL_LENGTH = MAX_URL_LENGTH;
+exports.RouteLink = RouteLink;
+exports.useCursorUrlSync = useCursorUrlSync;
+exports.usePersistedState = usePersistedState;
+exports.useRouterDrawer = useRouterDrawer;
+exports.useSearchParamSync = useSearchParamSync;