@trackunit/react-components 3.8.2 → 3.8.3-alpha-e1e6a0f33ce.0

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

@@ -1,55 +0,0 @@
-/**
- * Default maximum length of the resulting 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 it is not subject to the
- * AWS WAF managed-rule `SizeRestrictions_QUERYSTRING` cap that applies to
- * search params (5000 bytes). 64 KB stays well below typical browser URL
- * limits (Chromium ≳ 100 KB, Firefox ≳ 64 KB on the address bar) while
- * still leaving generous headroom for any realistic table state.
- */
-export declare const MAX_HASH_LENGTH: number;
-type UseHashParamSyncOptions = {
-    readonly key: string;
-    readonly enabled?: boolean;
-    readonly onExternalChange?: () => void;
-    readonly replace?: boolean;
-};
-type UseHashParamSyncReturn = {
-    /**
-     * Mirrors the field name on `useSearchParamSync` so this hook is a
-     * drop-in replacement when only the URL location changes (search ↔ hash).
-     * Despite the name, this value is read from `location.hash`.
-     */
-    readonly searchValue: string | undefined;
-    /**
-     * Mirrors the function name on `useSearchParamSync`. Writes to
-     * `location.hash`, preserving any foreign fragment content untouched.
-     */
-    readonly updateSearchParam: (encodedValue: string | undefined, options?: {
-        readonly replace?: boolean;
-    }) => void;
-};
-/**
- * Syncs an encoded string value with a single named entry inside the URL
- * fragment (`location.hash`) via Tanstack Router.
- *
- * Behaviour mirrors `useSearchParamSync`, with two differences:
- *  - Reads from and writes to `location.hash` instead of `location.search`.
- *  - Oversized replacements remove stale values using
- *    {@link MAX_HASH_LENGTH}, rather than the AWS-WAF-driven search-param cap.
- *
- * The fragment is treated as a sequence of `&`-separated tokens via the
- * pure utilities in `./hashFragment`. Foreign tokens (bare anchors, other
- * named entries) are preserved byte-for-byte on every write.
- *
- * @param options - Configuration for the hash entry sync.
- * @param options.key - The named entry inside the fragment.
- * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
- * @param options.onExternalChange - Called when the entry changes externally
- *   (e.g. browser back/forward, pasted link, foreign router push).
- * @param options.replace - `true` to always use `replaceState` instead of pushState.
- */
-export declare const useHashParamSync: ({ key, enabled, onExternalChange, replace: replaceOption, }: UseHashParamSyncOptions) => UseHashParamSyncReturn;
-export {};

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

@@ -1,62 +0,0 @@
-type UseMigrateLegacySearchParamOptions<TState> = {
-    readonly key: string;
-    readonly enabled: boolean;
-    /**
-     * Pure decoder for the raw search-param string. Should not throw — return
-     * `undefined` when the input can't be decoded.
-     */
-    readonly decode: (rawSearchValue: string) => unknown;
-    /**
-     * Optional transform applied to the decoded payload before validation
-     * (mirrors `usePersistedState`'s `fromUrlValue`).
-     */
-    readonly fromUrlValue?: (decoded: unknown) => unknown;
-    /**
-     * Schema validator. Return the parsed state on success, `undefined`
-     * otherwise.
-     */
-    readonly validate: (raw: unknown) => TState | undefined;
-    /**
-     * When `true`, the hash already carries a valid value for this key. The
-     * hook still strips the legacy search param (so the URL is clean) but
-     * does NOT fire `onMigrated` — the hash is canonical and we must not
-     * stomp on it.
-     */
-    readonly hashAlreadyHasValue: boolean;
-    /**
-     * Called at most once when a valid legacy search-param value is found
-     * and the hash is currently empty. Pipe through your normal
-     * `persistState` so the value ends up in both the hash and localStorage.
-     */
-    readonly onMigrated: (state: TState) => void;
-};
-/**
- * One-shot migration: if the URL still carries a legacy `?<key>=...`
- * search param from before this hook moved table-style state to the
- * fragment, decode it, hand it to the caller via `onMigrated`, then strip
- * the search param via a `replace` navigation so back/forward history
- * isn't polluted.
- *
- * Invariants:
- *  - The strip navigation fires at most once per mount (guarded by
- *    `hasStrippedRef`) so we don't loop on the navigation we ourselves
- *    triggered.
- *  - `onMigrated` is also fired at most once per mount (guarded by
- *    `hasMigratedRef`), but its gating is independent of the strip:
- *    if `hashAlreadyHasValue` flips `true → false` after the strip
- *    (e.g. an external actor clears the canonical hash mid-mount), the
- *    next render still gets a chance to migrate the legacy value into
- *    the hash. Conflating the two flags would have permanently lost
- *    the legacy state in that race.
- *  - Never throws — a decode/validate failure silently drops the value
- *    and still strips the search param. The legacy key is owned by this
- *    codebase's persistence convention (camelCase + `Tp` suffix), so
- *    stripping unparseable values cannot destroy third-party data.
- *  - When `hashAlreadyHasValue` is `true` the hash wins: the search
- *    param is stripped but `onMigrated` is not fired.
- *  - The `location.hash` is preserved verbatim across the strip
- *    navigation so any concurrent hash content (including a freshly
- *    written value) survives the cleanup.
- */
-export declare const useMigrateLegacySearchParam: <TState>({ key, enabled, decode, fromUrlValue, validate, hashAlreadyHasValue, onMigrated, }: UseMigrateLegacySearchParamOptions<TState>) => void;
-export {};