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

package/migrations/entry.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entry.js.map

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/react/router-components/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/migrations.json

@@ -0,0 +1,3 @@
+{
+  "generators": {}
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@trackunit/react-router-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.3",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "@trackunit/css-class-variance-utilities": "2.6.7",
+    "@trackunit/i18n-library-translation": "2.12.6",
+    "@trackunit/react-components": "4.0.1",
+    "@trackunit/react-drawer": "2.14.9",
+    "@trackunit/shared-utils": "1.22.7",
+    "dequal": "^2.0.3",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.114.29",
+    "react": "^19.0.0"
+  },
+  "migrations": "./migrations.json",
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
 }

package/src/Breadcrumb/Breadcrumb.d.ts

@@ -0,0 +1,39 @@
+import { ReactElement } from "react";
+import { BreadcrumbProps } from "./utils/types";
+/**
+ * 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
+ */
+export declare const Breadcrumb: ({ className, "data-testid": dataTestId, breadcrumbItems, onClickBack, style, ref, }: BreadcrumbProps) => ReactElement;

package/src/Breadcrumb/Breadcrumb.variant.d.ts

@@ -0,0 +1,45 @@
+export declare const cvaBreadcrumb: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaBreadcrumbItem: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaBreadcrumbForLargeScreen: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
+export declare const cvaBreadcrumbForMediumScreen: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        expanded: {
+            true: string;
+            false: string;
+        };
+    };
+    defaultVariants: {
+        expanded: false;
+    };
+}, "defaultVariants"> & {
+    variants: {
+        expanded: {
+            true: string;
+            false: string;
+        };
+    };
+    defaultVariants: Omit<{}, "expanded"> & {
+        expanded: false;
+    };
+}, {
+    expanded: {
+        true: string;
+        false: string;
+    };
+}>;

package/src/Breadcrumb/BreadcrumbContainer.d.ts

@@ -0,0 +1,8 @@
+import { ReactElement } from "react";
+import { BreadcrumbContainerProps } from "./utils/types";
+/**
+ * BreadcrumbContainer is a helper component that renders the breadcrumb items based on the screen size.
+ *
+ * @param {BreadcrumbContainerProps} props - The props for the BreadcrumbContainer component
+ */
+export declare const BreadcrumbContainer: ({ className, "data-testid": dataTestId, breadcrumbItems, style, ref, }: BreadcrumbContainerProps) => ReactElement;

package/src/Breadcrumb/BreadcrumbForLargeScreen.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { BreadcrumbContainerProps } from "./utils/types";
+/**
+ * BreadcrumbForLargeScreen is a helper component that renders the breadcrumb items for large screens.
+ */
+export declare const BreadcrumbForLargeScreen: ({ "data-testid": dataTestId, breadcrumbItems, className, style, }: BreadcrumbContainerProps) => ReactElement;

package/src/Breadcrumb/BreadcrumbForMediumScreen.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { BreadcrumbForMediumScreenProps } from "./utils/types";
+/**
+ * BreadcrumbForMediumScreen is a helper component that renders the breadcrumb items for medium screens.
+ */
+export declare const BreadcrumbForMediumScreen: ({ "data-testid": dataTestId, breadcrumbItems, className, style, }: BreadcrumbForMediumScreenProps) => ReactElement;

package/src/Breadcrumb/BreadcrumbForSmallScreen.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { BreadcrumbContainerProps } from "./utils/types";
+/**
+ * BreadcrumbForSmallScreen is a helper component that renders the breadcrumb items for small screens.
+ */
+export declare const BreadcrumbForSmallScreen: ({ "data-testid": dataTestId, breadcrumbItems, className, style, }: BreadcrumbContainerProps) => ReactElement;

package/src/Breadcrumb/BreadcrumbItem.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { BreadcrumbItemRenderProps } from "./utils/types";
+/**
+ * BreadcrumbItem is a helper component that renders the individual breadcrumb item.
+ */
+export declare const BreadcrumbItem: ({ item, "data-testid": dataTestId, className, style, }: BreadcrumbItemRenderProps) => ReactElement;

package/src/Breadcrumb/utils/types.d.ts

@@ -0,0 +1,26 @@
+import type { CommonProps, Refable, Styleable } from "@trackunit/react-components";
+import { MouseEventHandler, ReactElement } from "react";
+export interface BreadcrumbItemProps {
+    /** The display text for this breadcrumb item. */
+    label: string;
+    /** The route path this breadcrumb item links to. */
+    to: string;
+}
+export interface BreadcrumbProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    /**
+     * The ordered list of breadcrumb items representing the navigation hierarchy.
+     * The last item is rendered as plain text (the current page), all preceding items are rendered as clickable links.
+     */
+    breadcrumbItems: Array<BreadcrumbItemProps>;
+    /**
+     * Click handler for the back arrow button. Typically navigates to the previous breadcrumb item (second-to-last in the list).
+     */
+    onClickBack: MouseEventHandler<HTMLButtonElement>;
+}
+export interface BreadcrumbContainerProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    breadcrumbItems: Array<ReactElement<BreadcrumbItemProps>>;
+}
+export type BreadcrumbForMediumScreenProps = BreadcrumbContainerProps;
+export interface BreadcrumbItemRenderProps extends CommonProps, Styleable {
+    item: ReactElement<BreadcrumbItemProps>;
+}

package/src/Breadcrumb/utils/useBreadcrumbItemsToRender.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { BreadcrumbItemProps } from "./types";
+/**
+ * useBreadcrumbItemsToRender is a custom hook that takes an array of BreadcrumbItemProps and returns an array of React.ReactElement
+ */
+export declare const useBreadcrumbItemsToRender: (breadcrumbItems: Array<BreadcrumbItemProps>) => Array<ReactElement<BreadcrumbItemProps>>;

package/src/RouteLink/RouteLink.d.ts

@@ -0,0 +1,17 @@
+import { CommonProps } from "@trackunit/react-components";
+import { MouseEvent, ReactElement } from "react";
+export interface RouteLinkProps extends CommonProps {
+    to: string;
+    text: string;
+    onClick?: (event: MouseEvent<HTMLAnchorElement, globalThis.MouseEvent>) => void;
+    className?: string;
+    title?: string;
+}
+/**
+ * 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
+ */
+export declare const RouteLink: ({ to, text, title, onClick, className, "data-testid": dataTestId, }: RouteLinkProps) => ReactElement;

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./Breadcrumb/Breadcrumb";
+export * from "./persistence/usePersistedState";
+export * from "./persistence/useSearchParamSync";
+export * from "./RouteLink/RouteLink";
+export * from "./useCursorUrlSync/useCursorUrlSync";
+export * from "./useRouterDrawer/useRouterDrawer";

package/src/persistence/readPrimitiveSearchParam.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare const readPrimitiveSearchParam: (search: unknown, key: string) => string | undefined;

package/src/persistence/usePersistedState.d.ts

@@ -0,0 +1,117 @@
+import { type UrlParamLocation } from "./useUrlParamSync";
+/**
+ * Selects which part of the URL backs the persisted state.
+ *
+ * - `"search"` (default): `?<key>=<encoded>`. Subject to the AWS WAF
+ *   managed-rule cap (~5000 bytes) — large states are dropped from the URL.
+ * - `"hash"`: `#<key>=<encoded>`. Stays on the client, so the cap is
+ *   driven only by browser URL limits.
+ */
+export type UrlPersistenceLocation = UrlParamLocation;
+type UsePersistedStateOptions<TState> = {
+    readonly key: string;
+    readonly validate: (raw: unknown) => TState | undefined;
+    readonly toUrlValue?: (state: TState) => string | object | Array<object>;
+    readonly fromUrlValue?: (decoded: unknown) => unknown;
+    readonly localStorageEnabled?: boolean;
+    readonly replace?: boolean;
+    readonly clientSideUserId?: string;
+    /**
+     * When `true` and both URL and localStorage have valid state, the read
+     * returns a shallow merge `{ ...storage, ...url }` where URL fields take
+     * precedence and storage fills in fields the URL omits.
+     *
+     * Use this when `toUrlValue` deliberately omits some fields from the URL
+     * (e.g. per-user layout details that shouldn't be shareable) so the
+     * omitted fields still survive reloads via localStorage.
+     *
+     * Default is `false`: URL state fully replaces localStorage state on read.
+     */
+    readonly mergeWithStorageOnRead?: boolean;
+    /**
+     * Which slot of the URL backs the persisted value. Default `"search"`.
+     * See {@link UrlPersistenceLocation} for the trade-offs.
+     */
+    readonly urlLocation?: UrlPersistenceLocation;
+    /**
+     * When `true`, every URL write is stamped with a fingerprint of
+     * `clientSideUserId` (`{ o: <fingerprint>, v: <payload> }`). Reads are
+     * unaffected: the URL still wins on load for everyone, so links and
+     * bookmarks render for whoever opens them.
+     *
+     * The stamp exists for the login redirect. The URL is shared by every
+     * account that signs in from the same browser and `redirectToLogin`
+     * carries it through to the next account, which is how one account's
+     * state replaced another's on a shared PC (GLU-2396). At that boundary
+     * `useStripForeignIdentityHash` drops entries stamped by a different
+     * identity that has state stored in this browser. Default `false`.
+     */
+    readonly stampUrlWithIdentity?: boolean;
+};
+type UsePersistedStateReturn<TState> = {
+    readonly initialState: TState | undefined;
+    /** Writes `state` to localStorage and the URL; each slot skips a value equal to its last write. */
+    readonly persistState: (state: TState) => void;
+    /**
+     * Writes `state` to localStorage only; `undefined` removes the entry.
+     * Use together with `persistToUrl` when the two writes should not share a
+     * schedule — e.g. storage immediately, URL debounced.
+     */
+    readonly persistToStorage: (state: TState | undefined) => void;
+    /** Writes `state` to the URL only; `undefined` removes the entry. */
+    readonly persistToUrl: (state: TState | undefined) => void;
+};
+/**
+ * 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`.
+ */
+export declare const usePersistedState: <TState extends object>({ key, validate, toUrlValue, fromUrlValue, localStorageEnabled, replace, clientSideUserId, mergeWithStorageOnRead, urlLocation, stampUrlWithIdentity, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+export {};

package/src/persistence/useSearchParamSync.d.ts

@@ -0,0 +1,17 @@
+import { type UseUrlParamSyncOptions, type UseUrlParamSyncReturn } from "./useUrlParamSync";
+export { MAX_URL_LENGTH } from "./useUrlParamSync";
+type UseSearchParamSyncOptions = Omit<UseUrlParamSyncOptions, "location">;
+/**
+ * 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`.
+ */
+export declare const useSearchParamSync: (options: UseSearchParamSyncOptions) => UseUrlParamSyncReturn;

package/src/persistence/useUrlParamSync.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+export declare 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.
+ */
+export declare const MAX_HASH_LENGTH: number;
+/**
+ * Which part of the URL a persisted value lives in.
+ *
+ * - `"search"`: `?<key>=<encoded>`. Subject to the AWS WAF cap
+ *   ({@link MAX_URL_LENGTH}); large states are dropped from the URL.
+ * - `"hash"`: `#<key>=<encoded>`. Client-only, capped by
+ *   {@link MAX_HASH_LENGTH}.
+ */
+export type UrlParamLocation = "search" | "hash";
+export type UseUrlParamSyncOptions = {
+    readonly key: string;
+    readonly location: UrlParamLocation;
+    readonly enabled?: boolean;
+    readonly onExternalChange?: () => void;
+    readonly replace?: boolean;
+};
+export type UseUrlParamSyncReturn = {
+    /** The raw encoded value currently in the URL slot, or `undefined` when absent or disabled. */
+    readonly searchValue: string | undefined;
+    /** Writes `encodedValue` into the URL slot; `undefined` removes the entry. */
+    readonly updateSearchParam: (encodedValue: string | undefined) => void;
+};
+/**
+ * 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.
+ */
+export declare const useUrlParamSync: ({ key, location: urlLocation, enabled, onExternalChange, replace: replaceOption, }: UseUrlParamSyncOptions) => UseUrlParamSyncReturn;

package/src/translation.d.ts

@@ -0,0 +1,30 @@
+import { NamespaceTransProps, TransForLibs, TranslationResource, useNamespaceTranslation } from "@trackunit/i18n-library-translation";
+import { ReactElement } from "react";
+import defaultTranslations from "./locales/en/translation.json";
+/** A type for all available translation keys in this library */
+export type TranslationKeys = keyof typeof defaultTranslations;
+/** The translation namespace for this library */
+export declare 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.
+ */
+export declare const translations: TranslationResource<TranslationKeys>;
+/**
+ *  Local useTranslation for this specific library
+ */
+export declare const useTranslation: () => ReturnType<typeof useNamespaceTranslation<TranslationKeys>>;
+/**
+ * Type of the t function for the local useTranslation for this specific library
+ */
+export type TranslationFunction = TransForLibs<TranslationKeys>;
+/**
+ * Trans for this specific library.
+ */
+export declare const Trans: (props: NamespaceTransProps<TranslationKeys>) => ReactElement;
+/**
+ * Registers the translations for this library
+ */
+export declare const setupLibraryTranslations: () => void;

package/src/useCursorUrlSync/useCursorUrlSync.d.ts

@@ -0,0 +1,23 @@
+type UseCursorUrlSyncOptions = {
+    readonly paramName?: string;
+    readonly debounceMs?: number;
+};
+type UseCursorUrlSyncResult = {
+    readonly initialCursor: string | undefined;
+    readonly updateCursor: (cursor: string | undefined) => void;
+};
+/**
+ * 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.
+ */
+export declare const useCursorUrlSync: ({ paramName, debounceMs, }?: UseCursorUrlSyncOptions) => UseCursorUrlSyncResult;
+export {};

package/src/useRouterDrawer/useRouterDrawer.d.ts

@@ -0,0 +1,100 @@
+import { type RegisteredRouter, type RouteIds } from "@tanstack/react-router";
+import { type UseDrawerProps, type UseDrawerReturnValue } from "@trackunit/react-drawer";
+/** URL slot that stores a drawer's selected id: a search param or a route path param. */
+export type RouterDrawerParamKind = "search" | "path";
+type RouterDrawerRouteId = RouteIds<RegisteredRouter["routeTree"]>;
+type RouterSelectionOptions = {
+    /**
+     * Id of the route, or routes, that carry the selection. The id is read from whichever of them is
+     * matched; when several are, the outermost match (first in match order) wins. Every id must be
+     * registered in the router; an unknown id throws on render.
+     */
+    from: RouterDrawerRouteId | ReadonlyArray<RouterDrawerRouteId>;
+    /** Name of the URL param that stores the selected id. */
+    param: string;
+    /**
+     * Which URL slot `param` lives in. `"search"` uses a search param. With `"path"`, the param is
+     * read from, and written to, the matched `from` route's path params. Opening from closed
+     * navigates to the `from` route, so it needs a single `from` id. Closing navigates one path
+     * segment up from it, so the `from` route's own path must be exactly `$param` with the list route
+     * one segment above it (e.g. `templates` → `templates/$templateId`).
+     *
+     * @default "search"
+     */
+    paramKind?: RouterDrawerParamKind;
+    /**
+     * Guard for leaving the current selection: switching ids, closing (header X, Escape, outside
+     * click, `setId(undefined)`), browser Back, or navigating anywhere that does not keep the same
+     * selection. Return (or resolve) `true` to allow it; `false`, a throw or a rejected promise keeps
+     * the current URL. Nothing changes until the guard allows it. Opening from closed and navigations
+     * that keep the same selection are not guarded. The same selection means the same id under the
+     * same outermost matched `from` route: moving between child routes of it keeps the selection;
+     * moving to a sibling route of a `from` list does not. The guard is called once per attempt, and while it is pending
+     * every navigation is dropped, not queued. Reloading or closing the tab is not guarded. With
+     * several guarded drawers on one page, each guards its own selection, so leaving the route asks
+     * each guard in turn.
+     *
+     * Browser Forward runs the guard, but denying it does not keep the current entry (GLU-2432).
+     */
+    onBeforeClose?: () => boolean | Promise<boolean>;
+};
+/** Options for {@link useRouterDrawer}. */
+export type UseRouterDrawerOptions = RouterSelectionOptions & Pick<UseDrawerProps, "variant" | "trapFocus" | "position" | "dismiss" | "onOpen">;
+/**
+ * Return value of {@link useRouterDrawer}: the spreadable `useDrawer` surface plus the URL selection.
+ * Open with `setId(id)`; `open()` and `toggle()` cannot select an id, so they do nothing while closed.
+ */
+export type UseRouterDrawerResult<TId extends string | number = string> = UseDrawerReturnValue & {
+    /**
+     * Selected id read from the URL, kept through the close animation: it stays the closing id until
+     * the drawer has fully exited, then becomes `undefined`. Feed query `variables`, `skip` and
+     * rendered content from it. For "is a selection in the URL right now", read `isOpen`.
+     * Not checked against `TId` by the hook: it is whatever the `from` route's validator produced.
+     */
+    readonly id: TId | undefined;
+    /** Stable setter. Writes or clears the URL param, replacing the history entry. Setting the current id is a no-op. */
+    readonly setId: (nextId: TId | undefined) => void;
+};
+/**
+ * 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>;
+ * ```
+ */
+export declare const useRouterDrawer: <TId extends string | number = string>({ from, param, paramKind, onBeforeClose, variant, trapFocus, position, dismiss, onOpen, }: UseRouterDrawerOptions) => UseRouterDrawerResult<TId>;
+export {};

package/translation.cjs.js

@@ -0,0 +1,8 @@
+'use strict';
+
+var translation = {
+	"breadcrumb.backButton": "Back",
+	"breadcrumb.expandButton": "ausklappen"
+};
+
+exports.default = translation;

package/translation.esm.js

@@ -0,0 +1,6 @@
+var translation = {
+	"breadcrumb.backButton": "Back",
+	"breadcrumb.expandButton": "ausklappen"
+};
+
+export { translation as default };

package/translation10.cjs.js

@@ -0,0 +1,8 @@
+'use strict';
+
+var translation = {
+	"breadcrumb.backButton": "Back",
+	"breadcrumb.expandButton": "rozwiń"
+};
+
+exports.default = translation;

package/translation10.esm.js

@@ -0,0 +1,6 @@
+var translation = {
+	"breadcrumb.backButton": "Back",
+	"breadcrumb.expandButton": "rozwiń"
+};
+
+export { translation as default };