@trackunit/react-components 1.25.4 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.25.4",
+  "version": "1.26.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",

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

@@ -0,0 +1,62 @@
+/**
+ * Pure utilities for reading and writing single named entries inside a URL
+ * fragment (the part after `#`).
+ *
+ * # Format contract
+ *
+ * The fragment body (after the leading `#`) is treated as a sequence of
+ * `&`-separated tokens. A token may be:
+ *  - **A named entry** — `<key>=<value>` (the first `=` separates key from
+ *    value; later `=` chars are part of the value).
+ *  - **Foreign content** — anything else (bare scroll anchors like
+ *    `section`, hash routes, third-party data, malformed tokens). Foreign
+ *    tokens are preserved byte-for-byte, in their original positions.
+ *
+ * # Single-key ownership
+ *
+ * Callers operate on **one** named key per invocation. Every token whose
+ * key does not match the supplied key is foreign — the utility never
+ * categorises or rewrites it. This mirrors how `useSearchParamSync`
+ * treats a single named search param.
+ *
+ * # Value-encoding invariant
+ *
+ * Values passed to {@link writeHashKey} must not contain `&`, `=`, or `#`.
+ * The standard producer for this codebase is `useCustomEncoding`, whose
+ * base64url alphabet (`[A-Za-z0-9_-]`) satisfies the invariant by
+ * construction. Keys are restricted by the existing persistence-key
+ * schema (camelCase, ≤15 chars), so they are likewise safe.
+ *
+ * # Anchor-scroll caveat
+ *
+ * Browsers locate scroll targets by matching the entire fragment string
+ * against element IDs. Appending a named entry to a fragment containing
+ * a bare anchor (e.g. `#section` becoming `#section&userTableTp=...`)
+ * therefore breaks anchor scrolling on that page. This is unavoidable
+ * for any hash-backed shared state. Consumers that rely on scroll
+ * anchors should not also persist state to the hash on the same route.
+ */
+/**
+ * Reads the value of a single named entry from a URL fragment.
+ *
+ * @param hash - The fragment string, with or without the leading `#`.
+ * @param key - The entry key to look up.
+ * @returns {string | undefined} The raw value (everything after the first
+ *   `=` in the matching token), or `undefined` when the key is absent. An
+ *   entry whose token has no `=` is treated as foreign content and ignored.
+ */
+export declare const readHashKey: (hash: string, key: string) => string | undefined;
+/**
+ * Returns a new fragment string with the named entry written, replaced,
+ * or removed. Foreign tokens are preserved in their original order; the
+ * named entry retains its position if it already exists, and is appended
+ * to the end when newly inserted. Empty tokens (e.g. produced by
+ * consecutive `&`) are dropped on the way out.
+ *
+ * @param hash - The current fragment string, with or without the leading `#`.
+ * @param key - The entry key to write.
+ * @param value - The value to set, or `undefined` to remove the entry.
+ * @returns {string} The new fragment string, including a leading `#` when
+ *   non-empty, or an empty string when the result has no tokens left.
+ */
+export declare const writeHashKey: (hash: string, key: string, value: string | undefined) => string;

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

@@ -0,0 +1,55 @@
+/**
+ * Default maximum length of the resulting URL fragment after adding one
+ * persisted entry. Writes are skipped (localStorage continues to hold the
+ * full state) when adding the entry would push the fragment past this cap.
+ *
+ * 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`.
+ *  - Writes are guarded against {@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

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

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

@@ -1,3 +1,15 @@
+/**
+ * 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.
+ * - `"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.
+ */
+export type UrlPersistenceLocation = "search" | "hash";
 type UsePersistedStateOptions<TState> = {
     readonly key: string;
     readonly validate: (raw: unknown) => TState | undefined;
@@ -22,17 +34,28 @@ type UsePersistedStateOptions<TState> = {
      * 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;
 };
 type UsePersistedStateReturn<TState> = {
     readonly initialState: TState | undefined;
     readonly persistState: (state: TState) => void;
 };
 /**
- * Generic persistence hook that loads state from URL search params (with
- * localStorage fallback) and writes changes to both.
+ * 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 a URL search param exists, decode it and pass through `validate`.
+ *  - 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 is empty
+ *    but a **legacy** `?<key>=...` search param is present, decode and
+ *    validate that as a one-shot fallback. A migration effect then strips
+ *    the legacy search param via a `replace` navigation.
  *  - 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.
@@ -40,23 +63,25 @@ type UsePersistedStateReturn<TState> = {
  *    localStorage so fields stripped by `toUrlValue` survive via storage.
  *
  * `persistState` writes the state to localStorage (via `serialize`, default
- * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
- * Duplicate writes where the state has not changed (deep equality) are skipped.
+ * `storageSerializer.serialize`) and syncs to the canonical URL slot (via
+ * `toUrlValue` + encoding). Duplicate writes where the state has not
+ * changed (deep equality) are skipped.
  *
  * @param options - Configuration for the persisted state.
- * @param options.key - Unique identifier used for both the URL search param and the localStorage key.
+ * @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 param changes externally (e.g. browser back).
- * @param options.replace - Forwarded to `useSearchParamSync`.
+ * @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
  *   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"`.
  */
-export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, urlLocation, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
 export {};

package/src/index.d.ts

@@ -117,6 +117,7 @@ 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";