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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "3.8.2-alpha-0ef4e15e7c1.0",
+  "version": "3.8.2-alpha-775ca1816d6.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,16 +14,16 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.18.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/css-class-variance-utilities": "2.3.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/shared-utils": "1.19.5-alpha-0ef4e15e7c1.0",
-    "@trackunit/ui-icons": "1.17.5-alpha-0ef4e15e7c1.0",
+    "@trackunit/ui-design-tokens": "1.18.5-alpha-775ca1816d6.0",
+    "@trackunit/css-class-variance-utilities": "2.3.5-alpha-775ca1816d6.0",
+    "@trackunit/shared-utils": "1.19.5-alpha-775ca1816d6.0",
+    "@trackunit/ui-icons": "1.17.5-alpha-775ca1816d6.0",
     "es-toolkit": "^1.52.0",
     "@tanstack/react-virtual": "^3.14.13",
     "dequal": "^2.0.3",
     "fflate": "^0.8.3",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.8.5-alpha-0ef4e15e7c1.0"
+    "@trackunit/i18n-library-translation": "2.8.5-alpha-775ca1816d6.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -1,24 +1,19 @@
+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 may be silently
- *   truncated before they hit the browser bar.
+ *   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. When this mode is selected,
- *   `usePersistedState` also performs a one-shot migration from any
- *   legacy `?<key>=...` value so previously shared links don't lose state.
+ *   driven only by browser URL limits.
  */
-export type UrlPersistenceLocation = "search" | "hash";
+export type UrlPersistenceLocation = UrlParamLocation;
 type UsePersistedStateOptions<TState> = {
     readonly key: string;
     readonly validate: (raw: unknown) => TState | undefined;
-    readonly serialize?: (state: TState) => string;
     readonly toUrlValue?: (state: TState) => string | object | Array<object>;
     readonly fromUrlValue?: (decoded: unknown) => unknown;
-    readonly enabled?: boolean;
     readonly localStorageEnabled?: boolean;
-    readonly onExternalChange?: () => void;
     readonly replace?: boolean;
     readonly clientSideUserId?: string;
     /**
@@ -30,8 +25,7 @@ type UsePersistedStateOptions<TState> = {
      * (e.g. per-user layout details that shouldn't be shareable) so the
      * omitted fields still survive reloads via localStorage.
      *
-     * Default is `false`, preserving the original behavior where URL state
-     * fully replaces localStorage state on read.
+     * Default is `false`: URL state fully replaces localStorage state on read.
      */
     readonly mergeWithStorageOnRead?: boolean;
     /**
@@ -56,15 +50,16 @@ type UsePersistedStateOptions<TState> = {
 };
 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;
-    readonly clearState: () => void;
     /**
-     * Writes the hydrated state to localStorage when it came from the URL and
-     * differs from what this identity has stored. Returns `false` when the
-     * snapshot is still for a previous read (identity not resolved yet), so
-     * the caller can retry. A no-op success returns `true`.
+     * 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 commitHydratedState: () => boolean;
+    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
@@ -72,47 +67,39 @@ type UsePersistedStateReturn<TState> = {
  * and writes changes to both.
  *
  * On mount the hook resolves the initial state as follows:
- *  - If the canonical URL slot (search OR hash, per `urlLocation`) holds a
- *    value, decode it and pass through `validate`.
- *  - In `urlLocation: "hash"` mode, if the canonical hash slot has no valid
- *    value but a **legacy** `?<key>=...` search param is present, decode and
- *    validate that as a one-shot fallback. The value is copied into the hash
- *    and the search param is stripped via a `replace` navigation.
- *  - A value that comes only from localStorage is not written to the URL.
- *    Copying it on load 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 user changes the state.
+ *  - 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.
  *
- * `persistState` writes the state to localStorage (via `serialize`, default
- * `storageSerializer.serialize`) and syncs to the canonical URL slot (via
- * `toUrlValue` + encoding). Duplicate writes where the state has not
- * changed (deep equality) are skipped.
+ * 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.
  *
- * `commitHydratedState` writes the hydrated value to localStorage only,
- * when it came from the URL and differs from what this identity has stored.
- * It does not update the URL. It returns `false` while the snapshot is
- * still for a previous read, so the caller can retry after identity
- * resolution. The caller decides which identity is allowed to commit.
+ * `persistState` writes to localStorage (`storageSerializer`) and to the URL
+ * (via `toUrlValue` + encoding).
+ * Each slot skips a value deep-equal to its last write. The URL side starts
+ * from the hydrated state, so echoing `initialState` writes no URL entry. 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.
  *
- * `clearState` removes the entry from localStorage and from the URL slot,
- * rather than writing an empty value. Use it when the state a consumer
- * derives has become empty, so no leftover entry is stored for a value the
- * user has reset. It is idempotent — clearing an absent entry is a no-op.
+ * 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.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
  * @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.enabled - When `false` the URL is neither read nor written (default `true`).
  * @param options.localStorageEnabled - When `false` localStorage is neither read nor written (default `true`).
- * @param options.onExternalChange - Fired when the URL value changes externally (e.g. browser back).
  * @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
@@ -122,5 +109,5 @@ type UsePersistedStateReturn<TState> = {
  * @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, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, urlLocation, stampUrlWithIdentity, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+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,30 +1,12 @@
-/**
- * Default 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 url host + path + query + hash string
- */
-export declare const MAX_URL_LENGTH = 5000;
-type UseSearchParamSyncOptions = {
-    readonly key: string;
-    readonly enabled?: boolean;
-    readonly onExternalChange?: () => void;
-    readonly replace?: boolean;
-};
-type UseSearchParamSyncReturn = {
-    readonly searchValue: string | undefined;
-    readonly updateSearchParam: (encodedValue: string | undefined, options?: {
-        readonly replace?: boolean;
-    }) => void;
-};
+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.
  *
- * Provides a write function that updates the URL through the application
- * router (preserving other search params), guards against exceeding
- * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
- * back/forward, shared links) via an optional callback.
+ * 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.
@@ -32,5 +14,4 @@ type UseSearchParamSyncReturn = {
  * @param options.onExternalChange - Called when the param changes externally.
  * @param options.replace - `true` to always use `replaceState`.
  */
-export declare const useSearchParamSync: ({ key, enabled, onExternalChange, replace: replaceOption, }: UseSearchParamSyncOptions) => UseSearchParamSyncReturn;
-export {};
+export declare const useSearchParamSync: (options: UseSearchParamSyncOptions) => UseUrlParamSyncReturn;

package/src/hooks/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/index.d.ts

@@ -126,7 +126,6 @@ export * from "./hooks/localStorage/useLocalStorageReducer";
 export * from "./hooks/localStorage/useSessionStorage";
 export * from "./hooks/localStorage/useSessionStorageReducer";
 export * from "./hooks/noPagination";
-export * from "./hooks/persistence/useHashParamSync";
 export * from "./hooks/persistence/usePersistedState";
 export * from "./hooks/persistence/useSearchParamSync";
 export * from "./hooks/persistence/useStorageKey";

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 {};