@trackunit/react-components 1.18.15 → 1.18.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.18.15",
+  "version": "1.18.16",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,14 +14,15 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.11.69",
-    "@trackunit/css-class-variance-utilities": "1.11.71",
-    "@trackunit/shared-utils": "1.13.71",
-    "@trackunit/ui-icons": "1.11.68",
+    "@trackunit/ui-design-tokens": "1.11.70",
+    "@trackunit/css-class-variance-utilities": "1.11.72",
+    "@trackunit/shared-utils": "1.13.72",
+    "@trackunit/ui-icons": "1.11.69",
     "@tanstack/react-router": "1.114.29",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
     "fflate": "^0.8.2",
+    "superjson": "^2.2.6",
     "zod": "^3.23.8"
   },
   "module": "./index.esm.js",

package/src/hooks/localStorage/readFromStorage.d.ts

@@ -0,0 +1,39 @@
+import type { z } from "zod";
+import type { MigrationConfig, WebStorageCallbacks } from "./types";
+/**
+ * Reads and deserializes a value from web storage, validating it against the provided schema.
+ * Falls back to defaultState if the key is missing or data is corrupt.
+ *
+ * On partial validation failure for ZodObject schemas, salvages valid fields rather than
+ * resetting the entire state to `defaultState`. See `salvageState` for salvage mechanics.
+ * If the salvaged result is deeply equal to `defaultState` (i.e. every field was invalid),
+ * the salvage is considered a total loss and `onValidationFailed` is called instead of
+ * `onValidationSalvaged`.
+ *
+ * Deserialization failures (unparseable/corrupt raw data) are routed through
+ * `onValidationFailed` so consumers are always notified when stored data is unusable.
+ *
+ * When `migration` is provided, detects versioned envelopes, runs the
+ * migration pipeline, and validates the migrated result. Non-versioned consumers are
+ * unaffected — the migration path is fully opt-in.
+ *
+ * @template TState - The type of the stored state.
+ * @param params - Storage, key, default state, Zod schema, optional migration config, and optional callbacks.
+ * @param params.storage - The web Storage instance.
+ * @param params.key - The storage key.
+ * @param params.defaultState - Fallback value when no stored data exists or data is corrupt.
+ * @param params.schema - Zod schema to validate the deserialized data.
+ * @param params.migration - Optional migration configuration (version, steps, fromKey).
+ * @param params.onValidationFailed - Called when validation fails and no salvage is possible, or when
+ *   deserialization of the raw storage value fails entirely.
+ * @param params.onValidationSalvaged - Called when validation fails but at least one stored field
+ *   was recovered (salvaged result differs from defaultState).
+ * @returns {TState} The validated or salvaged state, or defaultState.
+ */
+export declare const readFromStorage: <TState>({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged, }: {
+    readonly storage: Storage;
+    readonly key: string;
+    readonly defaultState: TState;
+    readonly schema: z.ZodType<TState>;
+    readonly migration?: MigrationConfig;
+} & Pick<WebStorageCallbacks<TState>, "onValidationFailed" | "onValidationSalvaged">) => TState;

package/src/hooks/localStorage/runMigrations.d.ts

@@ -0,0 +1,13 @@
+import type { StorageMigration } from "./types";
+/**
+ * Runs a sequential migration pipeline on the provided data, applying
+ * each migration whose version is in the range (fromVersion, toVersion].
+ *
+ * Throws if the filtered migrations have non-contiguous versions (gaps).
+ */
+export declare const runMigrations: ({ data, fromVersion, toVersion, migrations, }: {
+    readonly data: unknown;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly migrations: ReadonlyArray<StorageMigration>;
+}) => unknown;

package/src/hooks/localStorage/salvageState.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * Attempts to salvage partial state from raw data when full schema validation has failed.
+ *
+ * For ZodObject schemas, rebuilds the schema with per-field `.catch(defaultState[key])` fallbacks
+ * and reparses. Valid field values from the stored data are kept; invalid fields fall back to their
+ * corresponding values in `defaultState`. Works recursively for nested ZodObject fields.
+ *
+ * Non-object schemas (discriminated unions, unions with `.refine()`, etc.) cannot be partially
+ * salvaged and return `null`.
+ *
+ * Consumer-defined `.catch()` wrappers take precedence over the injected salvage catches, since
+ * Zod processes catches inside-out.
+ *
+ * Note: when every field is invalid, the salvaged result will be deeply equal to `defaultState`.
+ * Callers should compare the result against `defaultState` to distinguish a genuine partial
+ * salvage from a total loss where no stored data survived.
+ *
+ * @template TState - The type of the stored state.
+ * @param schema - Zod schema for validation.
+ * @param rawData - The raw deserialized value that failed validation.
+ * @param defaultState - The authoritative fallback value; used as per-field catch defaults.
+ * @returns {TState | null} The salvaged state, or `null` if salvaging is not possible or also fails.
+ */
+export declare const salvageState: <TState>(schema: z.ZodType<TState>, rawData: unknown, defaultState: TState) => TState | null;

package/src/hooks/localStorage/storageSerializer.d.ts

@@ -0,0 +1,4 @@
+export declare const storageSerializer: {
+    readonly serialize: (value: unknown) => string;
+    readonly deserialize: (value: string) => unknown;
+};

package/src/hooks/localStorage/storageVersionEnvelope.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/**
+ * Internal envelope that pairs stored data with a schema version number.
+ *
+ * `__version` and `__data` are **reserved internal keys** — consumer state
+ * objects must not include them as top-level keys. The double-underscore
+ * prefix is a deliberate signal that these are private implementation details.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+export declare const storageVersionEnvelopeSchema: z.ZodEffects<z.ZodObject<{
+    __version: z.ZodNumber;
+    __data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    __version: number;
+    __data?: unknown;
+}, {
+    __version: number;
+    __data?: unknown;
+}>, {
+    __version: number;
+    __data: unknown;
+}, {
+    __version: number;
+    __data?: unknown;
+}>;
+export type StorageVersionEnvelope = z.infer<typeof storageVersionEnvelopeSchema>;
+/** Wraps data and version into a versioned storage envelope. */
+export declare const createStorageVersionEnvelope: (data: unknown, version: number) => StorageVersionEnvelope;

package/src/hooks/localStorage/types.d.ts

@@ -1,27 +1,31 @@
-import { z } from "zod";
-export interface LocalStorageParams<TState> {
+import type { z } from "zod";
+export type StorageMigration = {
+    readonly version: number;
+    readonly migrate: (data: unknown) => unknown;
+};
+export type MigrationConfig = {
+    readonly version: number;
+    readonly steps?: ReadonlyArray<StorageMigration>;
+    readonly fromKey?: string;
+};
+export type WebStorageOptions<TState> = {
+    /** Must be a stable, non-empty string. Passing an empty string throws during render. Changing from non-empty to empty across renders is unsupported and will throw. */
+    readonly key: string;
+    readonly defaultState: NoInfer<TState>;
+    readonly schema: z.ZodType<TState>;
+    readonly migration?: MigrationConfig;
+};
+export type WebStorageCallbacks<TState> = {
+    readonly onValidationFailed?: (error: unknown) => void;
+    readonly onValidationSuccessful?: (data: TState) => void;
     /**
-     * The key used to store the value in local storage.
-     */
-    key: string;
-    /**
-     * The default state value.
-     */
-    defaultState: TState;
-    /**
-     * Optional schema for validating the state.
-     */
-    schema?: z.Schema<TState>;
-}
-export interface LocalStorageCallbacks<TState> {
-    /**
-     * Optional callback function called when validation fails.
+     * Called when schema validation fails but partial state was recovered.
+     * Valid fields from the stored value are kept; invalid fields fall back to their
+     * corresponding values in `defaultState`. Only fires during reads (initialization
+     * and key changes) — never during the write-sync path.
      *
-     * @param error - The validation error object.
-     */
-    onValidationFailed?: (error: unknown) => void;
-    /**
-     * Optional callback function called when validation succeeds.
+     * @param error - The ZodError describing which fields failed validation.
+     * @param salvaged - The recovered state combining valid stored fields and defaultState fallbacks.
      */
-    onValidationSuccessful?: (data: TState) => void;
-}
+    readonly onValidationSalvaged?: (error: z.ZodError, salvaged: TState) => void;
+};

package/src/hooks/localStorage/useLocalStorage.d.ts

@@ -1,10 +1,16 @@
-import { Dispatch, SetStateAction } from "react";
-import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+import type { Dispatch, SetStateAction } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
 /**
- * Works like a normal useState, but saves to local storage and has optional schema validation.
+ * Works like useState, but persists to localStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
  *
- * @template TState - The type of the value stored in local storage.
- * @param {Omit<LocalStorageParams<TState>, "state"> & LocalStorageCallbacks} options - The options for useLocalStorage.
- * @returns {[TState, Dispatch<SetStateAction<TState>>, () => void]} - A tuple containing the current value, a function to update the value, and a function to remove the value from local storage.
+ * @template TState - The type of the stored state.
+ * @param options - Key, defaultState, schema, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, setState, reset].
  */
-export declare const useLocalStorage: <TState>({ key, defaultState, schema, onValidationFailed, onValidationSuccessful, }: LocalStorageParams<TState> & LocalStorageCallbacks<TState>) => [TState, Dispatch<SetStateAction<TState>>, () => void];
+export declare const useLocalStorage: <TState>(options: WebStorageOptions<TState> & WebStorageCallbacks<TState>) => readonly [TState, Dispatch<SetStateAction<TState>>, () => void];

package/src/hooks/localStorage/useLocalStorageReducer.d.ts

@@ -1,13 +1,20 @@
-import { Dispatch } from "react";
-import { LocalStorageCallbacks, LocalStorageParams } from "./types";
+import type { Dispatch } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
 /**
- * Works like a normal useReducer, but saves to local storage and has optional schema validation.
+ * Works like useReducer, but persists to localStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
  *
- * @template TState - The type of the state.
- * @template TAction - The type of the action.
- * @param {LocalStorageParams<TState> & LocalStorageCallbacks} params - The parameters for the useLocalStorageReducer function.
- * @returns {[TState, Dispatch<TAction>]} - A tuple containing the state and the dispatch function.
+ * @template TState - The type of the stored state.
+ * @template TAction - The type of the reducer action.
+ * @param options - Key, defaultState, schema, reducer, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.reducer - The reducer function.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, dispatch].
  */
-export declare const useLocalStorageReducer: <TState, TAction>({ key, defaultState, reducer, schema, onValidationFailed, onValidationSuccessful, }: {
-    reducer: (state: TState, action: TAction) => TState;
-} & LocalStorageParams<TState> & LocalStorageCallbacks<TState>) => [TState, Dispatch<TAction>];
+export declare const useLocalStorageReducer: <TState, TAction>(options: WebStorageOptions<TState> & WebStorageCallbacks<TState> & {
+    readonly reducer: (state: TState, action: TAction) => TState;
+}) => readonly [TState, Dispatch<TAction>];

package/src/hooks/localStorage/useSessionStorage.d.ts

@@ -0,0 +1,16 @@
+import type { Dispatch, SetStateAction } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
+/**
+ * Works like useState, but persists to sessionStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ *
+ * @template TState - The type of the stored state.
+ * @param options - Key, defaultState, schema, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, setState, reset].
+ */
+export declare const useSessionStorage: <TState>(options: WebStorageOptions<TState> & WebStorageCallbacks<TState>) => readonly [TState, Dispatch<SetStateAction<TState>>, () => void];

package/src/hooks/localStorage/useSessionStorageReducer.d.ts

@@ -0,0 +1,20 @@
+import type { Dispatch } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
+/**
+ * Works like useReducer, but persists to sessionStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ *
+ * @template TState - The type of the stored state.
+ * @template TAction - The type of the reducer action.
+ * @param options - Key, defaultState, schema, reducer, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.reducer - The reducer function.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, dispatch].
+ */
+export declare const useSessionStorageReducer: <TState, TAction>(options: WebStorageOptions<TState> & WebStorageCallbacks<TState> & {
+    readonly reducer: (state: TState, action: TAction) => TState;
+}) => readonly [TState, Dispatch<TAction>];

package/src/hooks/localStorage/useStorageSyncEffect.d.ts

@@ -0,0 +1,35 @@
+import { type MutableRefObject } from "react";
+import type { z } from "zod";
+import type { WebStorageCallbacks } from "./types";
+type UseStorageSyncEffectOptions<TState> = {
+    readonly storage: Storage;
+    readonly key: string;
+    readonly state: TState;
+    readonly defaultState: TState;
+    readonly schema: z.ZodType<TState>;
+    readonly version?: number;
+    /**
+     * When provided, the effect skips the write if this ref is `true`
+     * (and resets it to `false` afterward). Used by key-change handlers
+     * to prevent writing stale state to a newly switched key.
+     */
+    readonly skipWriteRef?: MutableRefObject<boolean>;
+} & WebStorageCallbacks<TState>;
+/**
+ * Effect that synchronizes React state to web storage on every state change,
+ * validating through the schema before writing.
+ *
+ * @template TState - The type of the state.
+ * @param params - Storage, key, state, schema, and optional callbacks.
+ * @param params.storage - The web Storage instance.
+ * @param params.key - The storage key.
+ * @param params.state - The current state value.
+ * @param params.defaultState - The fallback value on validation failure.
+ * @param params.schema - Zod schema for validation.
+ * @param params.version - Optional schema version passed to writeToStorage.
+ * @param params.onValidationFailed - Optional error callback.
+ * @param params.onValidationSuccessful - Optional success callback.
+ * @param params.skipWriteRef - Optional ref flag to skip one write cycle (key-change guard).
+ */
+export declare const useStorageSyncEffect: <TState>({ storage, key, state, defaultState, schema, version, onValidationFailed, onValidationSuccessful, skipWriteRef, }: UseStorageSyncEffectOptions<TState>) => void;
+export {};

package/src/hooks/localStorage/useWebStorage.d.ts

@@ -0,0 +1,18 @@
+import { type Dispatch, type SetStateAction } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
+/**
+ * Internal storage-agnostic hook that backs useLocalStorage and useSessionStorage.
+ *
+ * @template TState - The type of the stored state.
+ * @param storage - The web Storage instance.
+ * @param options - Key, defaultState, schema, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.migration - Optional migration configuration (version, steps, fromKey).
+ * @param options.onValidationFailed - Called when validation fails and no salvage is possible.
+ * @param options.onValidationSuccessful - Called when validation succeeds during the write-sync.
+ * @param options.onValidationSalvaged - Called when validation fails but partial state was recovered.
+ * @returns {Array} A tuple of [state, setState, reset].
+ */
+export declare const useWebStorage: <TState>(storage: Storage, { key, defaultState, schema, migration, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }: WebStorageOptions<TState> & WebStorageCallbacks<TState>) => readonly [TState, Dispatch<SetStateAction<TState>>, () => void];

package/src/hooks/localStorage/useWebStorageReducer.d.ts

@@ -0,0 +1,22 @@
+import { type Dispatch } from "react";
+import type { WebStorageCallbacks, WebStorageOptions } from "./types";
+/**
+ * Internal storage-agnostic reducer hook that backs useLocalStorageReducer and useSessionStorageReducer.
+ *
+ * @template TState - The type of the stored state.
+ * @template TAction - The type of the reducer action.
+ * @param storage - The web Storage instance.
+ * @param options - Key, defaultState, schema, reducer, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.migration - Optional migration configuration (version, steps, fromKey).
+ * @param options.reducer - The reducer function.
+ * @param options.onValidationFailed - Called when validation fails and no salvage is possible.
+ * @param options.onValidationSuccessful - Called when validation succeeds during the write-sync.
+ * @param options.onValidationSalvaged - Called when validation fails but partial state was recovered.
+ * @returns {Array} A tuple of [state, dispatch].
+ */
+export declare const useWebStorageReducer: <TState, TAction>(storage: Storage, { key, defaultState, schema, migration, reducer, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }: WebStorageOptions<TState> & WebStorageCallbacks<TState> & {
+    readonly reducer: (state: TState, action: TAction) => TState;
+}) => readonly [TState, Dispatch<TAction>];

package/src/hooks/localStorage/validateState.d.ts

@@ -1,13 +1,22 @@
-import { LocalStorageCallbacks, LocalStorageParams } from "./types";
-type ValidateStateOptions<TState> = Required<Pick<LocalStorageParams<TState>, "schema">> & {
-    state: TState;
-    defaultState: TState;
-} & LocalStorageCallbacks<TState>;
+import type { z } from "zod";
+import type { WebStorageCallbacks } from "./types";
+type ValidateStateOptions<TState> = {
+    readonly state: unknown;
+    readonly defaultState: TState;
+    readonly schema: z.ZodType<TState>;
+} & WebStorageCallbacks<TState>;
 /**
- * Validates the state object using a Zod schema.
+ * Validates the state using a Zod schema. Returns the parsed state on success,
+ * or defaultState on failure (with error logging and optional callbacks).
  *
  * @template TState - The type of the state.
- * @param {ValidateStateOptions<TState>} params - The parameters for the validateState function.
+ * @param params - The state, schema, defaultState, and optional callbacks.
+ * @param params.state - The raw state to validate.
+ * @param params.schema - The Zod schema for validation.
+ * @param params.defaultState - The fallback value on failure.
+ * @param params.onValidationFailed - Optional error callback.
+ * @param params.onValidationSuccessful - Optional success callback.
+ * @returns {TState} The validated state or defaultState.
  */
-export declare const validateState: <TState>(params: ValidateStateOptions<TState>) => TState;
+export declare const validateState: <TState>({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }: ValidateStateOptions<TState>) => TState;
 export {};

package/src/hooks/localStorage/writeToStorage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serializes and writes a value to web storage.
+ * When a version is provided, wraps the data in a versioned envelope
+ * before serializing so the migration pipeline can detect it on read.
+ *
+ * @param storage - The Storage instance (localStorage / sessionStorage).
+ * @param key - The storage key.
+ * @param value - The value to serialize and store.
+ * @param version - Optional schema version to stamp onto the stored payload.
+ */
+export declare const writeToStorage: (storage: Storage, key: string, value: unknown, version?: number) => void;

package/src/index.d.ts

@@ -105,8 +105,11 @@ export * from "./components/ValueBar/ValueBarTypes";
 export * from "./components/ZStack/ZStack";
 export * from "./components/ZStack/ZStack.variants";
 export * from "./hooks/encoding/useCustomEncoding";
+export * from "./hooks/localStorage/types";
 export * from "./hooks/localStorage/useLocalStorage";
 export * from "./hooks/localStorage/useLocalStorageReducer";
+export * from "./hooks/localStorage/useSessionStorage";
+export * from "./hooks/localStorage/useSessionStorageReducer";
 export * from "./hooks/noPagination";
 export * from "./hooks/useBidirectionalScroll";
 export * from "./hooks/useClickOutside";

package/src/hooks/localStorage/initLocalStorageState.d.ts

@@ -1,9 +0,0 @@
-import { LocalStorageParams } from "./types";
-/**
- * Initializes the state from local storage, parsing and validating it if a Zod schema is provided.
- *
- * @template TState - The type of the state stored in local storage.
- * @param {Omit<LocalStorageParams<TState>, "state">} params - The parameters for initializing the local storage state.
- * @returns {TState} - The initialized state.
- */
-export declare const initLocalStorageState: <TState>({ key, defaultState, schema, }: Omit<LocalStorageParams<TState>, "state">) => TState;

package/src/hooks/localStorage/setLocalStorage.d.ts

@@ -1,11 +0,0 @@
-/**
- * Sets a value in the local storage with the specified key.
- * Thin wrapper around localStorage.setItem() that is slightly more type safe
- * Stringifies value automatically.
- * Useful if you for some reason can't use the useLocalStorage hook for React lifecycle reasons
- *
- * @template TValue - The type of value to be stored.
- * @param {string} key - The key under which to store the value.
- * @param {TValue} value - The value to store in the local storage.
- */
-export declare const setLocalStorage: <TValue>(key: string, value: TValue) => void;

package/src/hooks/localStorage/useLocalStorageEffect.d.ts

@@ -1,12 +0,0 @@
-import { LocalStorageCallbacks, LocalStorageParams } from "./types";
-/**
- * Custom hook for synchronizing a state variable with local storage,
- * with optional schema validation and callbacks.
- *
- * @template TState - The type of the state variable.
- * @param {LocalStorageParams<TState> & LocalStorageCallbacks & { state: TState }} params - The parameters for the useLocalStorageEffect hook.
- * @returns {void}
- */
-export declare const useLocalStorageEffect: <TState>({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful, }: LocalStorageParams<TState> & LocalStorageCallbacks<TState> & {
-    state: TState;
-}) => void;