@trackunit/react-components 2.6.5 → 2.7.0

package/index.cjs.js

@@ -22,8 +22,6 @@ var utils = require('@floating-ui/react/utils');
 var reactHelmetAsync = require('react-helmet-async');
 var reactTabs = require('@radix-ui/react-tabs');
 var fflate = require('fflate');
-var superjson = require('superjson');
-var zod = require('zod');
 var dequal = require('dequal');
 
 var defaultTranslations = {
@@ -2363,7 +2361,7 @@ const Tag = ({ className, "data-testid": dataTestId, children, size = "medium",
             color,
             layout,
             border: color === "white" ? "default" : "none",
-        }), "data-testid": dataTestId, onMouseEnter: onMouseEnter, ref: ref, style: style, children: [icon !== null && icon !== undefined && size === "medium" ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "icon", children: icon })) : null, jsxRuntime.jsx("span", { className: cvaTagText({ truncate: shouldTruncate }), ref: textRef, children: children }), Boolean(onClickClose) && isSupportedDismissColor && size === "medium" && !disabled ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "dismiss", onClick: onClickClose, children: jsxRuntime.jsx(Tooltip, { disabled: disabled, label: removeTagLabel, placement: "bottom", children: jsxRuntime.jsx(Icon, { className: cvaTagIcon(), "data-testid": dataTestId + "Icon", name: "XCircle", size: "small", style: { WebkitTransition: "-webkit-transform 0.150s" }, type: "solid" }) }) })) : null] }));
+        }), "data-testid": dataTestId, onMouseEnter: onMouseEnter, ref: ref, style: style, children: [icon !== null && icon !== undefined && size === "medium" ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "icon", children: icon })) : null, jsxRuntime.jsx("span", { className: cvaTagText({ truncate: shouldTruncate }), ref: textRef, children: children }), Boolean(onClickClose) && isSupportedDismissColor && size === "medium" && !disabled ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "dismiss", onClick: onClickClose, children: jsxRuntime.jsx(Tooltip, { disabled: disabled, label: removeTagLabel, placement: "bottom", children: jsxRuntime.jsx(Icon, { className: cvaTagIcon(), "data-testid": `${dataTestId}Icon`, name: "XCircle", size: "small", style: { WebkitTransition: "-webkit-transform 0.150s" }, type: "solid" }) }) })) : null] }));
 };
 
 // Mirrors the slug logic in @trackunit/storybook-docs-components SectionName so anchors line up
@@ -4768,7 +4766,7 @@ function stylesToCss(styles, parentSelector, indent = "") {
             }
             else if (key.startsWith("@")) {
                 // At-rule (like @container): wrap in the at-rule
-                const nestedCss = stylesToCss(value, parentSelector, indent + "  ");
+                const nestedCss = stylesToCss(value, parentSelector, `${indent}  `);
                 lines.push(`${indent}${key} {\n${nestedCss}\n${indent}}`);
             }
         }
@@ -11865,334 +11863,6 @@ const useCustomEncoding = () => {
     return react.useMemo(() => ({ encode, decode }), [encode, decode]);
 };
 
-/**
- * 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.
- *
- * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
- * detected in the value being written.
- */
-const taggedSuperjsonEnvelopeSchema = zod.z.object({
-    __serializer: zod.z.literal("superjson"),
-    json: zod.z.custom(),
-    meta: zod.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;
-    },
-};
-
-/**
- * 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).
- */
-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);
-};
-
-/**
- * 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.
- *
- * 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.
- */
-function buildSalvagingSchema(schema, defaultValue) {
-    if (schema instanceof zod.z.ZodOptional) {
-        return buildSalvagingSchema(schema.unwrap(), defaultValue).optional();
-    }
-    if (schema instanceof zod.z.ZodNullable) {
-        return buildSalvagingSchema(schema.unwrap(), defaultValue).nullable();
-    }
-    if (schema instanceof zod.z.ZodDefault) {
-        return buildSalvagingSchema(schema._def.innerType, defaultValue);
-    }
-    if (!(schema instanceof zod.z.ZodObject)) {
-        return schema;
-    }
-    const defaultRecordResult = zod.z.record(zod.z.string(), zod.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 zod.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 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 {
-        return null;
-    }
-};
-
-/**
- * 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 = zod.z
-    .object({
-    __version: zod.z.number(),
-    __data: zod.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 && !esToolkit.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;
-    }
-    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;
-    }
-};
-
-/**
- * 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 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 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;
-};
-
-/**
- * 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.
- *
- * @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 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.
@@ -12220,7 +11890,7 @@ const useStorageSyncEffect = ({ storage, key, state, defaultState, schema, versi
             return;
         }
         const { schema: currentSchema, defaultState: currentDefault, onValidationFailed: currentOnFailed, onValidationSuccessful: currentOnSuccess, version: currentVersion, } = optionsRef.current;
-        validateState({
+        sharedUtils.validateState({
             state,
             schema: currentSchema,
             defaultState: currentDefault,
@@ -12231,7 +11901,7 @@ const useStorageSyncEffect = ({ storage, key, state, defaultState, schema, versi
                 currentOnFailed?.(error);
             },
             onValidationSuccessful: data => {
-                writeToStorage(storage, key, data, currentVersion);
+                sharedUtils.writeToStorage(storage, key, data, currentVersion);
                 currentOnSuccess?.(data);
             },
         });
@@ -12248,20 +11918,32 @@ const useStorageSyncEffect = ({ storage, key, state, defaultState, schema, versi
  * @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.legacyRawString - Narrow, opt-in recovery for keys known to hold a plain-text
+ *   value that was never JSON-encoded. See `WebStorageOptions.legacyRawString`.
  * @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 useWebStorage = (storage, { key, defaultState, schema, migration, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }) => {
+const useWebStorage = (storage, { key, defaultState, schema, migration, legacyRawString, onValidationFailed, onValidationSuccessful, onValidationSalvaged, }) => {
     if (!key) {
         throw new Error("useWebStorage: key must be a non-empty string");
     }
-    const [state, setState] = react.useState(() => readFromStorage({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged }));
+    const [state, setState] = react.useState(() => sharedUtils.readFromStorage({
+        storage,
+        key,
+        defaultState,
+        schema,
+        migration,
+        legacyRawString,
+        onValidationFailed,
+        onValidationSalvaged,
+    }));
     const prevKeyRef = react.useRef(key);
     const defaultStateRef = react.useRef(defaultState);
     const schemaRef = react.useRef(schema);
     const migrationRef = react.useRef(migration);
+    const legacyRawStringRef = react.useRef(legacyRawString);
     const onValidationFailedRef = react.useRef(onValidationFailed);
     const onValidationSalvagedRef = react.useRef(onValidationSalvaged);
     react.useEffect(() => {
@@ -12273,6 +11955,9 @@ const useWebStorage = (storage, { key, defaultState, schema, migration, onValida
     react.useEffect(() => {
         migrationRef.current = migration;
     }, [migration]);
+    react.useEffect(() => {
+        legacyRawStringRef.current = legacyRawString;
+    }, [legacyRawString]);
     react.useEffect(() => {
         onValidationFailedRef.current = onValidationFailed;
     }, [onValidationFailed]);
@@ -12284,12 +11969,13 @@ const useWebStorage = (storage, { key, defaultState, schema, migration, onValida
         if (key !== prevKeyRef.current) {
             prevKeyRef.current = key;
             keyChangedRef.current = true;
-            setState(readFromStorage({
+            setState(sharedUtils.readFromStorage({
                 storage,
                 key,
                 defaultState: defaultStateRef.current,
                 schema: schemaRef.current,
                 migration: migrationRef.current,
+                legacyRawString: legacyRawStringRef.current,
                 onValidationFailed: onValidationFailedRef.current,
                 onValidationSalvaged: onValidationSalvagedRef.current,
             }));
@@ -12383,7 +12069,7 @@ const useWebStorageReducer = (storage, { key, defaultState, schema, migration, r
                 return internal;
         }
     };
-    const [state, internalDispatch] = react.useReducer(internalReducer, undefined, () => readFromStorage({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged }));
+    const [state, internalDispatch] = react.useReducer(internalReducer, undefined, () => sharedUtils.readFromStorage({ storage, key, defaultState, schema, migration, onValidationFailed, onValidationSalvaged }));
     const userDispatch = react.useCallback((action) => internalDispatch({ kind: "user", action }), []);
     const prevKeyRef = react.useRef(key);
     const defaultStateRef = react.useRef(defaultState);
@@ -12413,7 +12099,7 @@ const useWebStorageReducer = (storage, { key, defaultState, schema, migration, r
             keyChangedRef.current = true;
             internalDispatch({
                 kind: "reinit",
-                state: readFromStorage({
+                state: sharedUtils.readFromStorage({
                     storage,
                     key,
                     defaultState: defaultStateRef.current,
@@ -13224,7 +12910,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             try {
                 const raw = rawLocalStorage.read(storageKey);
                 if (raw) {
-                    const parsed = storageSerializer.deserialize(raw);
+                    const parsed = sharedUtils.storageSerializer.deserialize(raw);
                     storageState = validateState(parsed);
                 }
             }
@@ -13356,7 +13042,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             if (localStorageEnabled) {
                 const serialized = serializeRef.current
                     ? serializeRef.current(migrated)
-                    : storageSerializer.serialize(migrated);
+                    : sharedUtils.storageSerializer.serialize(migrated);
                 rawLocalStorage.write(storageKey, serialized);
             }
             const urlValue = toUrlValueRef.current ? toUrlValueRef.current(migrated) : migrated;
@@ -13370,7 +13056,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         }
         lastPersistedRef.current = state;
         if (localStorageEnabled) {
-            const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
+            const serialized = serializeRef.current ? serializeRef.current(state) : sharedUtils.storageSerializer.serialize(state);
             rawLocalStorage.write(storageKey, serialized);
         }
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
@@ -14586,6 +14272,10 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
  */
 setupLibraryTranslations();
 
+Object.defineProperty(exports, "storageSerializer", {
+  enumerable: true,
+  get: function () { return sharedUtils.storageSerializer; }
+});
 exports.Alert = Alert;
 exports.Badge = Badge;
 exports.Breadcrumb = Breadcrumb;
@@ -14721,7 +14411,6 @@ exports.iconColorNames = iconColorNames;
 exports.iconPalette = iconPalette;
 exports.noPagination = noPagination;
 exports.preferenceCardGrid = preferenceCardGrid;
-exports.storageSerializer = storageSerializer;
 exports.useBidirectionalScroll = useBidirectionalScroll;
 exports.useClickOutside = useClickOutside;
 exports.useContainerBreakpoints = useContainerBreakpoints;