@trackunit/react-components 3.8.2-alpha-775ca1816d6.0 → 3.8.2

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;