@trackunit/react-components 1.18.15 → 1.18.16

package/index.esm.js

@@ -18,6 +18,8 @@ import { useVirtualizer } from '@tanstack/react-virtual';
 import { HelmetProvider, Helmet } from 'react-helmet-async';
 import { Trigger, Content, List as List$1, Root } from '@radix-ui/react-tabs';
 import { gzipSync, gunzipSync } from 'fflate';
+import { z } from 'zod';
+import superjson from 'superjson';
 
 const cvaIcon = cvaMerge(["aspect-square", "inline-grid", "relative", "shrink-0"], {
     variants: {
@@ -8238,179 +8240,615 @@ const useCustomEncoding = () => {
 };
 
 /**
- * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
+ * Runs a sequential migration pipeline on the provided data, applying
+ * each migration whose version is in the range (fromVersion, toVersion].
  *
- * @example
- * const [color, setColor] = React.useState(getRandomColor());
-  const previousColor = usePrevious(color);
+ * Throws if the filtered migrations have non-contiguous versions (gaps).
  */
-const usePrevious = (value) => {
-    const ref = useRef(undefined);
-    useEffect(() => {
-        ref.current = value;
-    }, [value]);
-    const wrapper = useMemo(() => ({
-        get previous() {
-            return ref.current;
-        },
-    }), []);
-    return wrapper.previous;
+const runMigrations = ({ data, fromVersion, toVersion, migrations, }) => {
+    if (toVersion <= fromVersion) {
+        return data;
+    }
+    const applicable = migrations
+        .toSorted((a, b) => a.version - b.version)
+        .filter(m => m.version > fromVersion && m.version <= toVersion);
+    if (applicable.length === 0) {
+        return data;
+    }
+    for (let i = 1; i < applicable.length; i++) {
+        const prev = applicable[i - 1];
+        const curr = applicable[i];
+        if (prev && curr && curr.version !== prev.version + 1) {
+            throw new Error(`Migration gap detected: found version ${prev.version} and ${curr.version} but no migration for version ${prev.version + 1}.`);
+        }
+    }
+    return applicable.reduce((acc, migration) => migration.migrate(acc), data);
 };
 
 /**
- * Validates the state object using a Zod schema.
+ * Recursively builds a salvaging schema from a ZodObject by injecting `.catch(defaultValue[key])`
+ * for each field. This means invalid field values fall back to defaultState values rather than
+ * failing the entire parse.
  *
- * @template TState - The type of the state.
- * @param {ValidateStateOptions<TState>} params - The parameters for the validateState function.
+ * Unwraps ZodOptional, ZodNullable, and ZodDefault to reach the inner schema.
+ * ZodCatch is intentionally NOT unwrapped — consumer-defined catches take precedence.
+ * Non-ZodObject schemas (unions, discriminated unions, refinements, etc.) are returned unchanged
+ * so they behave as atomic units.
  */
-const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+function buildSalvagingSchema(schema, defaultValue) {
+    if (schema instanceof z.ZodOptional) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).optional();
+    }
+    if (schema instanceof z.ZodNullable) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).nullable();
+    }
+    if (schema instanceof z.ZodDefault) {
+        return buildSalvagingSchema(schema._def.innerType, defaultValue);
+    }
+    if (!(schema instanceof z.ZodObject)) {
+        return schema;
+    }
+    const defaultRecordResult = z.record(z.string(), z.unknown()).safeParse(defaultValue);
+    if (!defaultRecordResult.success) {
+        return schema;
+    }
+    const defaultRecord = defaultRecordResult.data;
+    const salvagingShape = {};
+    for (const key of Object.keys(schema.shape)) {
+        const fieldSchema = schema.shape[key];
+        if (fieldSchema === undefined)
+            continue;
+        const fieldDefault = defaultRecord[key];
+        salvagingShape[key] = buildSalvagingSchema(fieldSchema, fieldDefault).catch(fieldDefault);
+    }
+    return z.object(salvagingShape);
+}
+/**
+ * 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.
+ */
+const salvageState = (schema, rawData, defaultState) => {
     try {
-        const parsedState = schema.parse(state);
-        onValidationSuccessful?.(parsedState);
-        return parsedState;
+        const salvagingSchema = buildSalvagingSchema(schema, defaultState);
+        const intermediate = salvagingSchema.safeParse(rawData);
+        if (!intermediate.success) {
+            return null;
+        }
+        // Re-validate through the original schema to ensure correctness and get the proper TState type.
+        // By construction this should always succeed: each field value is either the valid stored value
+        // or defaultState[key], both of which satisfy the original schema.
+        const result = schema.safeParse(intermediate.data);
+        return result.success ? result.data : null;
     }
-    catch (error) {
-        // eslint-disable-next-line no-console
-        console.error("Failed to parse and validate the state from local storage.", error);
-        onValidationFailed?.(error);
-        return defaultState;
+    catch {
+        return null;
     }
 };
 
 /**
- * Initializes the state from local storage, parsing and validating it if a Zod schema is provided.
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
  *
- * @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.
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
  */
-const initLocalStorageState = ({ key, defaultState, schema, }) => {
-    const localStorageItem = localStorage.getItem(key);
-    if (!localStorageItem) {
+const taggedSuperjsonEnvelopeSchema = z.object({
+    __serializer: z.literal("superjson"),
+    json: z.custom(),
+    meta: z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
+/**
+ * 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.
+ */
+const storageVersionEnvelopeSchema = z
+    .object({
+    __version: z.number(),
+    __data: z.unknown(),
+})
+    .refine((x) => "__data" in x, {
+    message: "__data is required",
+});
+/** Wraps data and version into a versioned storage envelope. */
+const createStorageVersionEnvelope = (data, version) => ({
+    __version: version,
+    __data: data,
+});
+
+/**
+ * Validates raw data against the schema, attempting partial salvage on failure.
+ *
+ * On success: returns the parsed data.
+ * On failure with a salvageable ZodObject schema where at least one stored field
+ *   survived: returns the salvaged state and calls `onValidationSalvaged`.
+ * On failure where salvage produces a result identical to `defaultState` (i.e. every
+ *   field was invalid and caught to its default): treats this as a total failure and
+ *   calls `onValidationFailed` instead of `onValidationSalvaged`.
+ * On failure with no salvage possible: returns `defaultState` and calls `onValidationFailed`.
+ */
+const validateOrSalvage = ({ rawValue, schema, defaultState, key, onValidationFailed, onValidationSalvaged, }) => {
+    const parseResult = schema.safeParse(rawValue);
+    if (parseResult.success) {
+        return parseResult.data;
+    }
+    const salvaged = salvageState(schema, rawValue, defaultState);
+    if (salvaged !== null && !isEqual(salvaged, defaultState)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Partially invalid data in storage key "${key}" — salvaged valid fields, reset invalid fields to defaults.`, parseResult.error);
+        onValidationSalvaged?.(parseResult.error, salvaged);
+        return salvaged;
+    }
+    // eslint-disable-next-line no-console
+    console.error(`Failed to parse and validate the state from storage key "${key}". Returning default state.`, parseResult.error);
+    onValidationFailed?.(parseResult.error);
+    return defaultState;
+};
+/**
+ * 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.
+ */
+const readFromStorage = ({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged, }) => {
+    const version = migration?.version;
+    const steps = migration?.steps;
+    const fromKey = migration?.fromKey;
+    let raw = storage.getItem(key);
+    if (raw === null && fromKey !== undefined) {
+        raw = storage.getItem(fromKey);
+    }
+    if (raw === null) {
         return defaultState;
     }
-    const localStorageItemJSON = JSON.parse(localStorageItem);
-    if (!schema) {
-        return localStorageItemJSON;
+    try {
+        const deserialized = storageSerializer.deserialize(raw);
+        if (version === undefined) {
+            return validateOrSalvage({
+                rawValue: deserialized,
+                schema,
+                defaultState,
+                key,
+                onValidationFailed,
+                onValidationSalvaged,
+            });
+        }
+        let storedVersion;
+        let data;
+        const envelopeResult = storageVersionEnvelopeSchema.safeParse(deserialized);
+        if (envelopeResult.success) {
+            storedVersion = envelopeResult.data.__version;
+            data = envelopeResult.data.__data;
+        }
+        else {
+            storedVersion = 0;
+            data = deserialized;
+        }
+        if (steps !== undefined && storedVersion < version) {
+            try {
+                data = runMigrations({ data, fromVersion: storedVersion, toVersion: version, migrations: steps });
+            }
+            catch (migrationError) {
+                // eslint-disable-next-line no-console
+                console.error(`Migration failed for storage key "${key}" (v${storedVersion} → v${version}). Returning default state.`, migrationError);
+                return defaultState;
+            }
+        }
+        return validateOrSalvage({ rawValue: data, schema, defaultState, key, onValidationFailed, onValidationSalvaged });
+    }
+    catch (deserializationError) {
+        // eslint-disable-next-line no-console
+        console.error(`Failed to deserialize storage key "${key}". Returning default state.`, deserializationError);
+        onValidationFailed?.(deserializationError);
+        return defaultState;
     }
-    return validateState({ state: localStorageItemJSON, defaultState, schema });
 };
 
 /**
- * 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
+ * Validates the state using a Zod schema. Returns the parsed state on success,
+ * or defaultState on failure (with error logging and optional callbacks).
  *
- * @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.
+ * @template TState - The type of the state.
+ * @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.
  */
-const setLocalStorage = (key, value) => {
-    localStorage.setItem(key, JSON.stringify(value));
+const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+    const result = schema.safeParse(state);
+    if (result.success) {
+        onValidationSuccessful?.(result.data);
+        return result.data;
+    }
+    // eslint-disable-next-line no-console
+    console.error("Failed to parse and validate the state from storage.", result.error);
+    onValidationFailed?.(result.error);
+    return defaultState;
 };
 
 /**
- * Custom hook for synchronizing a state variable with local storage,
- * with optional schema validation and callbacks.
+ * Keys reserved for internal storage envelope metadata.
+ * Consumer state objects must not use these as top-level keys.
+ */
+const RESERVED_STORAGE_KEYS = ["__data", "__version", "__serializer"];
+const warnIfReservedKeys = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return;
+    for (const key of RESERVED_STORAGE_KEYS) {
+        if (key in value) {
+            // eslint-disable-next-line no-console
+            console.warn(`[useWebStorage] "${key}" is a reserved internal storage key and must not be used in state objects. ` +
+                `It will conflict with the storage serialization envelope.`);
+        }
+    }
+};
+/**
+ * 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.
  *
- * @template TState - The type of the state variable.
- * @param {LocalStorageParams<TState> & LocalStorageCallbacks & { state: TState }} params - The parameters for the useLocalStorageEffect hook.
- * @returns {void}
+ * @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.
  */
-const useLocalStorageEffect = ({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
-    const prevState = usePrevious(state);
-    const optionsRef = useRef({ schema, defaultState, onValidationFailed, onValidationSuccessful });
+const writeToStorage = (storage, key, value, version) => {
+    warnIfReservedKeys(value);
+    const payload = version === undefined ? value : createStorageVersionEnvelope(value, version);
+    storage.setItem(key, storageSerializer.serialize(payload));
+};
+
+/**
+ * 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).
+ */
+const useStorageSyncEffect = ({ storage, key, state, defaultState, schema, version, onValidationFailed, onValidationSuccessful, skipWriteRef, }) => {
+    const optionsRef = useRef({ schema, defaultState, onValidationFailed, onValidationSuccessful, version });
     useEffect(() => {
-        optionsRef.current = { schema, defaultState, onValidationFailed, onValidationSuccessful };
-    }, [schema, defaultState, onValidationFailed, onValidationSuccessful]);
+        optionsRef.current = { schema, defaultState, onValidationFailed, onValidationSuccessful, version };
+    }, [schema, defaultState, onValidationFailed, onValidationSuccessful, version]);
     useEffect(() => {
-        if (JSON.stringify(prevState) === JSON.stringify(state)) {
+        if (skipWriteRef?.current) {
+            skipWriteRef.current = false;
             return;
         }
-        const { schema: refSchema, defaultState: refDefaultState, onValidationFailed: refOnValidationFailed, onValidationSuccessful: refOnValidationSuccessful, } = optionsRef.current;
-        if (refSchema) {
-            validateState({
-                state,
-                schema: refSchema,
-                defaultState: refDefaultState,
-                onValidationFailed: error => {
-                    // eslint-disable-next-line no-console
-                    console.error(`State validation failed. Resetting local storage to default state: ${refDefaultState}.`, error);
-                    localStorage.removeItem(key);
-                    refOnValidationFailed?.(error);
-                },
-                onValidationSuccessful: data => {
-                    setLocalStorage(key, data);
-                    refOnValidationSuccessful?.(data);
-                },
-            });
-        }
-        else {
-            const stringifiedState = JSON.stringify(state);
-            localStorage.setItem(key, stringifiedState);
-        }
-    }, [state, key, prevState]);
+        const { schema: currentSchema, defaultState: currentDefault, onValidationFailed: currentOnFailed, onValidationSuccessful: currentOnSuccess, version: currentVersion, } = optionsRef.current;
+        validateState({
+            state,
+            schema: currentSchema,
+            defaultState: currentDefault,
+            onValidationFailed: error => {
+                // eslint-disable-next-line no-console
+                console.error(`State validation failed for key "${key}". Removing from storage.`, error);
+                storage.removeItem(key);
+                currentOnFailed?.(error);
+            },
+            onValidationSuccessful: data => {
+                writeToStorage(storage, key, data, currentVersion);
+                currentOnSuccess?.(data);
+            },
+        });
+    }, [storage, key, state, skipWriteRef]);
 };
 
 /**
- * Works like a normal useState, but saves to local storage and has optional schema validation.
+ * Internal storage-agnostic hook that backs useLocalStorage and useSessionStorage.
  *
- * @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 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].
  */
-const useLocalStorage = ({ key, defaultState, schema, onValidationFailed, onValidationSuccessful, }) => {
+const useWebStorage = (storage, { key, defaultState, schema, migration, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }) => {
     if (!key) {
-        throw new Error("useLocalStorage key must be defined");
+        throw new Error("useWebStorage: key must be a non-empty string");
     }
-    const [state, setState] = useState(() => initLocalStorageState({ key, defaultState, schema }));
-    const prevKey = usePrevious(key);
+    const [state, setState] = useState(() => readFromStorage({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged }));
+    const prevKeyRef = useRef(key);
     const defaultStateRef = useRef(defaultState);
+    const schemaRef = useRef(schema);
+    const migrationRef = useRef(migration);
+    const onValidationFailedRef = useRef(onValidationFailed);
+    const onValidationSalvagedRef = useRef(onValidationSalvaged);
     useEffect(() => {
         defaultStateRef.current = defaultState;
     }, [defaultState]);
-    const schemaRef = useRef(schema);
     useEffect(() => {
         schemaRef.current = schema;
     }, [schema]);
     useEffect(() => {
-        if (key !== prevKey) {
-            setState(initLocalStorageState({ key, defaultState: defaultStateRef.current, schema: schemaRef.current }));
-        }
-    }, [key, prevKey]);
-    const localStorageProps = useMemo(() => ({
+        migrationRef.current = migration;
+    }, [migration]);
+    useEffect(() => {
+        onValidationFailedRef.current = onValidationFailed;
+    }, [onValidationFailed]);
+    useEffect(() => {
+        onValidationSalvagedRef.current = onValidationSalvaged;
+    }, [onValidationSalvaged]);
+    const keyChangedRef = useRef(false);
+    useEffect(() => {
+        if (key !== prevKeyRef.current) {
+            prevKeyRef.current = key;
+            keyChangedRef.current = true;
+            setState(readFromStorage({
+                storage,
+                key,
+                defaultState: defaultStateRef.current,
+                schema: schemaRef.current,
+                migration: migrationRef.current,
+                onValidationFailed: onValidationFailedRef.current,
+                onValidationSalvaged: onValidationSalvagedRef.current,
+            }));
+        }
+    }, [key, storage]);
+    useStorageSyncEffect({
+        storage,
         key,
         state,
         defaultState,
         schema,
+        version: migration?.version,
         onValidationFailed,
         onValidationSuccessful,
-    }), [key, state, defaultState, schema, onValidationFailed, onValidationSuccessful]);
-    useLocalStorageEffect(localStorageProps);
+        skipWriteRef: keyChangedRef,
+    });
+    useEffect(() => {
+        const fromKey = migration?.fromKey;
+        if (fromKey && storage.getItem(key) !== null) {
+            storage.removeItem(fromKey);
+        }
+    }, [migration?.fromKey, storage, key]);
     const reset = useCallback(() => {
         setState(defaultStateRef.current);
     }, []);
-    return useMemo(() => [state, setState, reset], [state, setState, reset]);
+    return useMemo(() => [state, setState, reset], [state, reset]);
 };
 
 /**
- * Works like a normal useReducer, 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 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.
+ * @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].
  */
-const useLocalStorageReducer = ({ key, defaultState, reducer, schema, onValidationFailed, onValidationSuccessful, }) => {
+const useLocalStorage = (options) => useWebStorage(globalThis.localStorage, options);
+
+/**
+ * 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].
+ */
+const useWebStorageReducer = (storage, { key, defaultState, schema, migration, reducer, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }) => {
     if (!key) {
-        throw new Error("useLocalStorage key may not be falsy");
+        throw new Error("useWebStorageReducer: key must be a non-empty string");
     }
-    const [state, dispatch] = useReducer(reducer, defaultState, () => initLocalStorageState({ key, defaultState, schema }));
-    useLocalStorageEffect({ key, state, defaultState, schema, onValidationFailed, onValidationSuccessful });
-    return [state, dispatch];
+    const internalReducer = (prevState, internal) => {
+        switch (internal.kind) {
+            case "reinit":
+                return internal.state;
+            case "user":
+                return reducer(prevState, internal.action);
+            default:
+                return internal;
+        }
+    };
+    const [state, internalDispatch] = useReducer(internalReducer, undefined, () => readFromStorage({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged }));
+    const userDispatch = useCallback((action) => internalDispatch({ kind: "user", action }), []);
+    const prevKeyRef = useRef(key);
+    const defaultStateRef = useRef(defaultState);
+    const schemaRef = useRef(schema);
+    const migrationRef = useRef(migration);
+    const onValidationFailedRef = useRef(onValidationFailed);
+    const onValidationSalvagedRef = useRef(onValidationSalvaged);
+    useEffect(() => {
+        defaultStateRef.current = defaultState;
+    }, [defaultState]);
+    useEffect(() => {
+        schemaRef.current = schema;
+    }, [schema]);
+    useEffect(() => {
+        migrationRef.current = migration;
+    }, [migration]);
+    useEffect(() => {
+        onValidationFailedRef.current = onValidationFailed;
+    }, [onValidationFailed]);
+    useEffect(() => {
+        onValidationSalvagedRef.current = onValidationSalvaged;
+    }, [onValidationSalvaged]);
+    const keyChangedRef = useRef(false);
+    useEffect(() => {
+        if (key !== prevKeyRef.current) {
+            prevKeyRef.current = key;
+            keyChangedRef.current = true;
+            internalDispatch({
+                kind: "reinit",
+                state: readFromStorage({
+                    storage,
+                    key,
+                    defaultState: defaultStateRef.current,
+                    schema: schemaRef.current,
+                    migration: migrationRef.current,
+                    onValidationFailed: onValidationFailedRef.current,
+                    onValidationSalvaged: onValidationSalvagedRef.current,
+                }),
+            });
+        }
+    }, [key, storage]);
+    useStorageSyncEffect({
+        storage,
+        key,
+        state,
+        defaultState,
+        schema,
+        version: migration?.version,
+        onValidationFailed,
+        onValidationSuccessful,
+        skipWriteRef: keyChangedRef,
+    });
+    useEffect(() => {
+        const fromKey = migration?.fromKey;
+        if (fromKey && storage.getItem(key) !== null) {
+            storage.removeItem(fromKey);
+        }
+    }, [migration?.fromKey, storage, key]);
+    return useMemo(() => [state, userDispatch], [state, userDispatch]);
 };
 
+/**
+ * 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 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].
+ */
+const useLocalStorageReducer = (options) => useWebStorageReducer(globalThis.localStorage, options);
+
+/**
+ * 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].
+ */
+const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage, options);
+
+/**
+ * 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].
+ */
+const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
+
 const OVERSCAN = 10;
 const DEFAULT_ROW_HEIGHT = 50;
 /**
@@ -9404,6 +9842,26 @@ const useModifierKey = ({ exclude = [] } = {}) => {
     return isModifierPressed;
 };
 
+/**
+ * The usePrevious hook is a useful tool for tracking the previous value of a variable in a functional component. This can be particularly handy in scenarios where it is necessary to compare the current value with the previous one, such as triggering actions or rendering based on changes.
+ *
+ * @example
+ * const [color, setColor] = React.useState(getRandomColor());
+  const previousColor = usePrevious(color);
+ */
+const usePrevious = (value) => {
+    const ref = useRef(undefined);
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    const wrapper = useMemo(() => ({
+        get previous() {
+            return ref.current;
+        },
+    }), []);
+    return wrapper.previous;
+};
+
 const defaultPageSize = 50;
 /**
  * Custom hook for handling Relay pagination in tables.
@@ -9748,4 +10206,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGeolocation, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGeolocation, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };