basalt-ui 1.25.0 → 1.26.0

package/dist/state/fields.js

@@ -0,0 +1,369 @@
+import { useSyncExternalStore } from "react";
+import { createPersistedState, readPersistedValue } from "./persisted.js";
+const field = {
+  /** A closed string enum — a tab, a compare mode, a single-select filter. */
+  enum(values, fallback, lane) {
+    return { kind: "enum", values, fallback, lane: resolveLane(lane) };
+  },
+  /** An any-of set over the same closed enum. Decoding is deduped and canonically re-sorted. */
+  multi(values, fallback = [], lane) {
+    return { kind: "multi", values, fallback, lane: resolveLane(lane) };
+  },
+  /**
+   * A time window: THREE URL params (preset + `from` + `to`, each renamable through `params`), so a
+   * consumer's existing deep links and loaders keep their shape. `custom: true` additionally
+   * allows the preset `'custom'` with two ISO dates.
+   *
+   * A second `field.range` in the same store — or a second range store composed into the same
+   * route's `validateSearch` — MUST rename `from`/`to` via `params`: every range defaults to the
+   * literal param names `'from'`/`'to'`, and two fields silently sharing them makes the later one's
+   * `toSearch` overwrite the earlier one's dates. `createStoreCore` throws at definition for the
+   * in-store case; the cross-store case is not detectable by either store alone.
+   */
+  range(o, lane) {
+    return {
+      kind: "range",
+      presets: o.presets,
+      fallback: { preset: o.fallback },
+      // The only cast left, and it is narrow: `C` is inferred from this very literal, so the
+      // runtime boolean IS `C` — `?? false` is what the compiler cannot see through.
+      custom: o.custom ?? false,
+      params: o.params ?? {},
+      lane: resolveLane(lane)
+    };
+  },
+  /** A number — pagination, a threshold. Out-of-range input clamps to `min`/`max`. */
+  number(o, lane) {
+    return {
+      kind: "number",
+      fallback: o.fallback,
+      min: o.min,
+      max: o.max,
+      int: o.int === true,
+      lane: resolveLane(lane)
+    };
+  },
+  /** A toggle. Accepts `true`/`false` and the strings `'true'`/`'false'` from a hand-typed URL. */
+  boolean(fallback, lane) {
+    return { kind: "boolean", fallback, lane: resolveLane(lane) };
+  },
+  /** Free text — a search box. Defaults to `history: 'replace'` like every other field. */
+  string(o, lane) {
+    return {
+      kind: "string",
+      fallback: o?.fallback ?? "",
+      max: o?.max,
+      lane: resolveLane(lane)
+    };
+  }
+};
+function resolveLane(lane) {
+  return {
+    url: lane?.url !== false,
+    persist: lane?.persist !== false,
+    history: lane?.history === "push" ? "push" : "replace"
+  };
+}
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T[\d:.]+(?:Z|[+-]\d{2}:\d{2})?)?$/;
+function isIsoDate(raw) {
+  return typeof raw === "string" && ISO_DATE_RE.test(raw) && !Number.isNaN(Date.parse(raw));
+}
+const NUMERIC_RE = /^-?\d+(\.\d+)?$/;
+function decodeBoolean(raw) {
+  if (typeof raw === "boolean") return raw;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return null;
+}
+function sameList(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+  return a.length === b.length && a.every((entry, i) => entry === b[i]);
+}
+function resolveFieldCodec(name, f, opts) {
+  switch (f.kind) {
+    case "enum": {
+      const allowed = new Set(f.values);
+      const decode = (raw) => typeof raw === "string" && allowed.has(raw) ? raw : null;
+      return single(name, f, decode, { optionValues: f.values });
+    }
+    case "multi": {
+      const present = new Set(f.values);
+      const decode = (raw) => {
+        if (!Array.isArray(raw)) return null;
+        const picked = /* @__PURE__ */ new Set();
+        for (const entry of raw) {
+          if (typeof entry === "string" && present.has(entry)) picked.add(entry);
+        }
+        return f.values.filter((value) => picked.has(value));
+      };
+      const decodeUrl = opts?.legacyMultiEmpty === true ? (raw) => {
+        const value = decode(raw);
+        return Array.isArray(value) && value.length === 0 ? null : value;
+      } : decode;
+      return single(name, f, decode, {
+        optionValues: f.values,
+        equals: sameList,
+        decodeUrl
+      });
+    }
+    case "range": {
+      const presetParam = f.params.preset ?? name;
+      const fromParam = f.params.from ?? "from";
+      const toParam = f.params.to ?? "to";
+      const allowed = new Set(f.presets);
+      const decode = (raw) => {
+        if (typeof raw !== "object" || raw === null) return null;
+        const value = raw;
+        if (typeof value.preset !== "string") return null;
+        if (value.preset === "custom") {
+          if (!f.custom || !isIsoDate(value.from) || !isIsoDate(value.to)) return null;
+          return { preset: "custom", from: value.from, to: value.to };
+        }
+        return allowed.has(value.preset) ? { preset: value.preset } : null;
+      };
+      return {
+        kind: "range",
+        lane: f.lane,
+        params: [presetParam, fromParam, toParam],
+        primary: presetParam,
+        fallback: f.fallback,
+        decode,
+        fromSearch: (search) => decode({
+          preset: search[presetParam],
+          from: search[fromParam],
+          to: search[toParam]
+        }),
+        toSearch: (value) => {
+          const range = value;
+          return {
+            [presetParam]: range.preset,
+            [fromParam]: range.from,
+            [toParam]: range.to
+          };
+        },
+        equals: (a, b) => {
+          const x = a;
+          const y = b;
+          if (x === null || y === null) return x === y;
+          return x.preset === y.preset && x.from === y.from && x.to === y.to;
+        },
+        optionValues: f.custom ? [...f.presets, "custom"] : f.presets
+      };
+    }
+    case "number": {
+      const decode = (raw) => {
+        const parsed = typeof raw === "number" ? raw : typeof raw === "string" && NUMERIC_RE.test(raw) ? Number(raw) : NaN;
+        if (!Number.isFinite(parsed)) return null;
+        if (f.int && !Number.isInteger(parsed)) return null;
+        let value = parsed;
+        if (f.min !== void 0 && value < f.min) value = f.min;
+        if (f.max !== void 0 && value > f.max) value = f.max;
+        return value;
+      };
+      return single(name, f, decode);
+    }
+    case "boolean": {
+      return single(name, f, decodeBoolean);
+    }
+    case "string": {
+      const decode = (raw) => {
+        if (typeof raw !== "string") return null;
+        return f.max !== void 0 && raw.length > f.max ? raw.slice(0, f.max) : raw;
+      };
+      return single(name, f, decode);
+    }
+    default: {
+      throw new Error("basalt-ui: createSearchStore received a field of an unknown kind");
+    }
+  }
+}
+function single(name, f, decode, extra) {
+  const decodeUrl = extra?.decodeUrl ?? decode;
+  return {
+    kind: f.kind,
+    lane: f.lane,
+    params: [name],
+    primary: name,
+    fallback: f.fallback,
+    decode,
+    fromSearch: (search) => decodeUrl(search[name]),
+    toSearch: (value) => ({ [name]: value }),
+    equals: extra?.equals ?? ((a, b) => a === b),
+    optionValues: extra?.optionValues ?? []
+  };
+}
+function isRecord(raw) {
+  return typeof raw === "object" && raw !== null && !Array.isArray(raw);
+}
+function assignDefined(into, from) {
+  for (const [key, value] of Object.entries(from)) {
+    if (value !== void 0) into[key] = value;
+  }
+}
+function resolveField(entry, search, record) {
+  const fromUrl = search === null ? null : entry.codec.fromSearch(search);
+  if (fromUrl !== null) return fromUrl;
+  if (entry.codec.lane.persist) {
+    const stored = entry.codec.decode(record[entry.name]);
+    if (stored !== null) return stored;
+  }
+  return entry.codec.fallback;
+}
+function createMemoryLane() {
+  const values = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let version = 0;
+  const bump = () => {
+    version += 1;
+    for (const cb of listeners) cb();
+  };
+  return {
+    subscribe: (cb) => {
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+    getVersion: () => version,
+    // `undefined` is the only "never written" marker the lane needs: no field kind has `undefined`
+    // as a legal value, so it can never collide with a written one.
+    resolve: (entry) => {
+      const stored = values.get(entry.name);
+      return stored === void 0 ? entry.codec.fallback : stored;
+    },
+    write: (name, value) => {
+      values.set(name, value);
+      bump();
+    },
+    clear: () => {
+      if (values.size === 0) return;
+      values.clear();
+      bump();
+    }
+  };
+}
+function assertNoParamCollision(key, entries) {
+  const owner = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const param of entry.codec.params) {
+      const existing = owner.get(param);
+      if (existing !== void 0 && existing !== entry.name) {
+        throw new Error(
+          `basalt-ui: createSearchStore('${key}'): fields '${existing}' and '${entry.name}' both own the URL param '${param}' \u2014 rename one via field.range({ params: { ... } }).`
+        );
+      }
+      owner.set(param, entry.name);
+    }
+  }
+}
+function createStoreCore(o) {
+  const version = o.version ?? 1;
+  const legacy = o.legacyValueField;
+  const entries = Object.entries(o.fields).map(([name, f]) => ({
+    name,
+    codec: resolveFieldCodec(name, f, { legacyMultiEmpty: legacy !== void 0 })
+  }));
+  assertNoParamCollision(o.key, entries);
+  const urlEntries = entries.filter((entry) => entry.codec.lane.url);
+  const anyPersisted = entries.some((entry) => entry.codec.lane.persist);
+  const labels = /* @__PURE__ */ new Map();
+  const usePersistedRaw = createPersistedState({ key: o.key, version, initial: null });
+  const memory = createMemoryLane();
+  const toRecord = (raw) => {
+    if (legacy !== void 0) return raw === null || raw === void 0 ? {} : { [legacy]: raw };
+    return isRecord(raw) ? raw : {};
+  };
+  const fromRecord = (record) => legacy !== void 0 ? record[legacy] ?? null : record;
+  const readRecord = () => toRecord(readPersistedValue(o.key, version));
+  const optionsFor = (entry) => {
+    const map = labels.get(entry.name);
+    return entry.codec.optionValues.map((value) => ({ value, label: map?.[value] ?? value }));
+  };
+  const writeField = (setRecord, name, value) => {
+    setRecord({ ...readRecord(), [name]: value });
+  };
+  const handle = (entry, use) => {
+    const { codec } = entry;
+    const built = {
+      kind: codec.kind,
+      fallback: codec.fallback,
+      use,
+      isDefault: (v) => codec.equals(v, codec.fallback)
+    };
+    if (codec.kind === "range") {
+      built["toWindow"] = (v) => v.preset === "custom" && v.from !== void 0 && v.to !== void 0 ? { from: v.from, to: v.to } : { window: v.preset };
+    }
+    Object.defineProperty(built, "options", {
+      enumerable: true,
+      get: () => optionsFor(entry)
+    });
+    return built;
+  };
+  return {
+    entries,
+    urlEntries,
+    anyPersisted,
+    usePersistedRecord() {
+      const [raw, setRaw] = usePersistedRaw();
+      return [toRecord(raw), (next) => setRaw(fromRecord(next))];
+    },
+    readRecord,
+    memoryUse(entry) {
+      return () => {
+        useSyncExternalStore(memory.subscribe, memory.getVersion, memory.getVersion);
+        return [memory.resolve(entry), (next) => memory.write(entry.name, next)];
+      };
+    },
+    readMemoryValue: (entry) => memory.resolve(entry),
+    useMemoryVersion: () => useSyncExternalStore(memory.subscribe, memory.getVersion, memory.getVersion),
+    resetMemory: () => memory.clear(),
+    setLabels(map) {
+      for (const [name, entry] of Object.entries(map)) {
+        if (entry !== void 0) labels.set(name, entry);
+      }
+    },
+    optionsFor,
+    resolve: resolveField,
+    writeField,
+    readStoredFlat() {
+      const record = readRecord();
+      const out = {};
+      for (const entry of entries) {
+        const stored = entry.codec.decode(record[entry.name]);
+        if (stored !== null) assignDefined(out, entry.codec.toSearch(stored));
+      }
+      return out;
+    },
+    handle
+  };
+}
+function createLocalStore(o) {
+  const core = createStoreCore({ key: o.key, fields: o.fields, version: o.version });
+  const persistedUse = (entry) => () => {
+    const [record, setRecord] = core.usePersistedRecord();
+    return [
+      core.resolve(entry, null, record),
+      (next) => core.writeField(setRecord, entry.name, next)
+    ];
+  };
+  const field2 = {};
+  for (const entry of core.entries) {
+    const use = entry.codec.lane.persist ? persistedUse(entry) : core.memoryUse(entry);
+    field2[entry.name] = core.handle(entry, use);
+  }
+  const store = {
+    field: field2,
+    readStored: () => core.readStoredFlat(),
+    labels: (map) => {
+      core.setLabels(map);
+      return store;
+    }
+  };
+  return store;
+}
+export {
+  createLocalStore,
+  createStoreCore,
+  field,
+  resolveFieldCodec
+};

package/dist/state/fields.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fields.test.d.ts.map

package/dist/state/fields.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.test.d.ts","sourceRoot":"","sources":["../../src/state/fields.test.tsx"],"names":[],"mappings":""}

package/dist/state/persisted.d.ts

@@ -0,0 +1,48 @@
+import type { StandardSchemaV1 } from '../register.js';
+export type PersistedStateOptions<T> = {
+    /** localStorage key (will be namespaced as `basalt:<key>`). */
+    readonly key: string;
+    /** Envelope version — increment when the shape changes. */
+    readonly version: number;
+    /** Value to use when nothing is persisted, after migration fails, or on SSR. */
+    readonly initial: T;
+    /** Migrate a previous-version persisted value forward to the current shape. */
+    readonly migrate?: (persisted: unknown, fromVersion: number) => T;
+    /**
+     * Standard-Schema validate the (post-migrate) value. Invalid result OR a Promise (async schema)
+     * falls back to `initial` — sync storage can't await, so async validators are treated as invalid.
+     */
+    readonly schema?: StandardSchemaV1<unknown, T>;
+};
+/**
+ * Versioned, Standard-Schema-validated localStorage state via useSyncExternalStore (no zustand).
+ * SSR-safe (getServerSnapshot returns `initial`). Cross-tab via the storage event.
+ *
+ * Returns a factory hook — call it once per module, then use the returned hook in components.
+ * Common case is 3 lines.
+ *
+ * @example
+ * export const useFilterDraft = createPersistedState({ key: 'filters', version: 1, initial: DEFAULT, schema: FilterSchema })
+ * // in a component:
+ * const [draft, setDraft] = useFilterDraft()
+ */
+export declare function createPersistedState<T>(opts: PersistedStateOptions<T>): () => readonly [T, (next: T) => void];
+/**
+ * Read a value previously written by `createPersistedState` under the namespaced key
+ * `basalt:<key>`. Parses the versioned envelope shape `{ v, value }`. Returns `null` on
+ * miss, corruption, version mismatch, or SSR — no fallback is applied (call sites supply
+ * their own default).
+ *
+ * Primary use: `validateSearch` in TanStack Router (which runs outside React, so it can't
+ * call `usePersistedState`). Combine with a URL-param check to create a search-param store
+ * backed by localStorage.
+ *
+ * @param key  — un-namespaced key (the same one passed to `createPersistedState`)
+ * @param version — if provided, the envelope version must match; stale envelopes return `null`
+ *
+ * @example
+ * const stored = readPersistedValue('dashboard-range', 1)
+ * // stored is '1d' | '7d' | '30d' | null
+ */
+export declare function readPersistedValue(key: string, version?: number): unknown | null;
+//# sourceMappingURL=persisted.d.ts.map

package/dist/state/persisted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted.d.ts","sourceRoot":"","sources":["../../src/state/persisted.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAOnD,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC,CAAA;IACjE;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;CAC/C,CAAA;AAqDD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CA8EvC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAYhF"}

package/dist/state/persisted.js

@@ -0,0 +1,105 @@
+import { useSyncExternalStore } from "react";
+const noopSubscribe = (_cb) => () => {
+};
+function isEnvelope(raw) {
+  return typeof raw === "object" && raw !== null && "v" in raw && typeof raw["v"] === "number" && "value" in raw;
+}
+function parseStorage(raw, opts) {
+  if (raw === null) return opts.initial;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isEnvelope(parsed)) return opts.initial;
+    let value = parsed.value;
+    if (parsed.v !== opts.version) {
+      value = opts.migrate ? opts.migrate(parsed.value, parsed.v) : opts.initial;
+    }
+    if (opts.schema) {
+      const result = opts.schema["~standard"].validate(value);
+      if (result instanceof Promise) return opts.initial;
+      if (result.issues !== void 0) return opts.initial;
+      return result.value;
+    }
+    return value;
+  } catch {
+    return opts.initial;
+  }
+}
+function writeStorage(opts, next) {
+  const storageKey = `basalt:${opts.key}`;
+  try {
+    const envelope = { v: opts.version, value: next };
+    window.localStorage.setItem(storageKey, JSON.stringify(envelope));
+  } catch {
+  }
+}
+function createPersistedState(opts) {
+  const storageKey = `basalt:${opts.key}`;
+  const listeners = /* @__PURE__ */ new Set();
+  let storageHandler = null;
+  const subscribe = (cb) => {
+    listeners.add(cb);
+    if (storageHandler === null) {
+      storageHandler = (e) => {
+        if (e.key === storageKey) {
+          for (const listener of listeners) listener();
+        }
+      };
+      window.addEventListener("storage", storageHandler);
+    }
+    return () => {
+      listeners.delete(cb);
+      if (listeners.size === 0 && storageHandler !== null) {
+        window.removeEventListener("storage", storageHandler);
+        storageHandler = null;
+      }
+    };
+  };
+  let cachedRaw = null;
+  let cachedValue = opts.initial;
+  let primed = false;
+  const getSnapshot = () => {
+    let raw;
+    try {
+      raw = window.localStorage.getItem(storageKey);
+    } catch {
+      raw = null;
+    }
+    if (primed && raw === cachedRaw) return cachedValue;
+    cachedRaw = raw;
+    cachedValue = parseStorage(raw, opts);
+    primed = true;
+    return cachedValue;
+  };
+  const getServerSnapshot = () => opts.initial;
+  const setState = (next) => {
+    writeStorage(opts, next);
+    for (const cb of listeners) cb();
+  };
+  const isServer = typeof window === "undefined";
+  return function usePersistedState() {
+    const value = useSyncExternalStore(
+      // SSR guard — subscribe must not reference `window` on the server.
+      isServer ? noopSubscribe : subscribe,
+      isServer ? getServerSnapshot : getSnapshot,
+      getServerSnapshot
+    );
+    return [value, setState];
+  };
+}
+function readPersistedValue(key, version) {
+  const storageKey = `basalt:${key}`;
+  try {
+    const raw = localStorage.getItem(storageKey);
+    if (raw === null) return null;
+    const envelope = JSON.parse(raw);
+    if (!isEnvelope(envelope)) return null;
+    if (version !== void 0 && envelope.v !== version) return null;
+    return envelope.value;
+  } catch {
+    return null;
+  }
+}
+export {
+  createPersistedState,
+  readPersistedValue
+};

package/dist/state.d.ts

@@ -1,62 +1,17 @@
-import type { StandardSchemaV1 } from './register.js';
 /**
- * Returns `true` when the browser reports an active network connection, `false` otherwise.
- * Backed by `useSyncExternalStore`: subscribes to window `online`/`offline` events.
- * SSR-safe — `getServerSnapshot` returns `true` (optimistic: assume online on the server).
+ * `basalt-ui/state` — the headless state surface: no Mantine, no router, no JSX.
  *
- * @deprecated Use `useConnectivity()` from `basalt-ui` instead — it aggregates browser,
- *   React Query, SSE, and health-ping signals into a richer `{ status, details }` object.
- *   `useOnlineStatus` remains for simple boolean needs without a provider dependency.
+ * Two halves, one barrel:
  *
- * @example
- * const isOnline = useOnlineStatus()
- * if (!isOnline) return <OfflineBanner />
- */
-export declare function useOnlineStatus(): boolean;
-export type PersistedStateOptions<T> = {
-    /** localStorage key (will be namespaced as `basalt:<key>`). */
-    readonly key: string;
-    /** Envelope version — increment when the shape changes. */
-    readonly version: number;
-    /** Value to use when nothing is persisted, after migration fails, or on SSR. */
-    readonly initial: T;
-    /** Migrate a previous-version persisted value forward to the current shape. */
-    readonly migrate?: (persisted: unknown, fromVersion: number) => T;
-    /**
-     * Standard-Schema validate the (post-migrate) value. Invalid result OR a Promise (async schema)
-     * falls back to `initial` — sync storage can't await, so async validators are treated as invalid.
-     */
-    readonly schema?: StandardSchemaV1<unknown, T>;
-};
-/**
- * Versioned, Standard-Schema-validated localStorage state via useSyncExternalStore (no zustand).
- * SSR-safe (getServerSnapshot returns `initial`). Cross-tab via the storage event.
- *
- * Returns a factory hook — call it once per module, then use the returned hook in components.
- * Common case is 3 lines.
- *
- * @example
- * export const useFilterDraft = createPersistedState({ key: 'filters', version: 1, initial: DEFAULT, schema: FilterSchema })
- * // in a component:
- * const [draft, setDraft] = useFilterDraft()
- */
-export declare function createPersistedState<T>(opts: PersistedStateOptions<T>): () => readonly [T, (next: T) => void];
-/**
- * Read a value previously written by `createPersistedState` under the namespaced key
- * `basalt:<key>`. Parses the versioned envelope shape `{ v, value }`. Returns `null` on
- * miss, corruption, version mismatch, or SSR — no fallback is applied (call sites supply
- * their own default).
- *
- * Primary use: `validateSearch` in TanStack Router (which runs outside React, so it can't
- * call `usePersistedState`). Combine with a URL-param check to create a search-param store
- * backed by localStorage.
- *
- * @param key  — un-namespaced key (the same one passed to `createPersistedState`)
- * @param version — if provided, the envelope version must match; stale envelopes return `null`
+ * - `./state/persisted` — `createPersistedState` / `readPersistedValue`, the versioned localStorage
+ *   primitive every other basalt module persists through.
+ * - `./state/fields` — the store field vocabulary (`field.*`, `FieldHandle`, the lanes) and
+ *   `createLocalStore`, the router-free store. `createSearchStore` (`basalt-ui/router-tanstack`)
+ *   is the router-coupled factory over the same fields.
  *
- * @example
- * const stored = readPersistedValue('dashboard-range', 1)
- * // stored is '1d' | '7d' | '30d' | null
+ * The split is a file boundary, not a surface boundary: this barrel is what `package.json`'s
+ * `./state` export resolves to, and its named exports are pinned by `scripts/export-surface.json`.
  */
-export declare function readPersistedValue(key: string, version?: number): unknown | null;
+export { createPersistedState, type PersistedStateOptions, readPersistedValue, } from './state/persisted.js';
+export { field, createLocalStore, type LocalStore, type FieldLane, type ResolvedLane, type ResolveLane, type RangeValue, type RangeParams, type RangePresets, type EnumField, type MultiField, type RangeField, type NumberField, type BooleanField, type StringField, type AnyField, type FieldValue, type FieldOption, type FieldHandle, type SearchValues, type StoredValues, type FieldCodec, type StoreEntry, type StoreCoreOptions, type StoreCore, resolveFieldCodec, createStoreCore, } from './state/fields.js';
 //# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAwBlD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC,CAAA;IACjE;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;CAC/C,CAAA;AAqDD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CA8EvC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAYhF"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,kBAAkB,GACnB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,KAAK,EACL,gBAAgB,EAChB,KAAK,UAAU,EAEf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EAEjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAA"}