@trackunit/react-components 3.12.3-alpha-4632fb37afe.0 → 4.0.0

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

@@ -1,117 +0,0 @@
-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/hooks/persistence/useSearchParamSync.d.ts

@@ -1,17 +0,0 @@
-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/hooks/persistence/useUrlParamSync.d.ts

@@ -1,71 +0,0 @@
-/**
- * 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/hooks/useCursorUrlSync.d.ts

@@ -1,23 +0,0 @@
-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 {};