basalt-ui 1.25.0 → 1.27.0

package/dist/state/fields.js

@@ -0,0 +1,405 @@
+import { useSyncExternalStore } from "react";
+import { createPersistedState, readPersistedValue, writePersistedValue } from "./persisted.js";
+function rangeField(o, lane) {
+  const { fallback } = o;
+  return {
+    kind: "range",
+    presets: o.presets,
+    // A thunk fallback stays a thunk — wrapped so the lazy value is read at the same moment every
+    // other lane reads one, not once here at definition.
+    fallback: typeof fallback === "function" ? () => ({ preset: fallback() }) : { preset: fallback },
+    custom: o.custom ?? false,
+    params: o.params ?? {},
+    window: o.window ?? {},
+    lane: resolveLane(lane)
+  };
+}
+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) };
+  },
+  range: rangeField,
+  /** 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"
+  };
+}
+function resolveFallback(raw) {
+  return typeof raw === "function" ? raw() : raw;
+}
+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,
+        get fallback() {
+          return resolveFallback(f.fallback);
+        },
+        windows: f.window,
+        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, { bounds: { min: f.min, max: f.max, int: f.int } });
+    }
+    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,
+    get fallback() {
+      return resolveFallback(f.fallback);
+    },
+    ...extra?.bounds !== void 0 && { bounds: extra.bounds },
+    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();
+    },
+    remove: (name) => {
+      if (!values.delete(name)) return;
+      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 clearField = (name) => {
+    const record = readRecord();
+    if (!Object.hasOwn(record, name)) return;
+    const next = { ...record };
+    delete next[name];
+    writePersistedValue(o.key, version, fromRecord(next));
+  };
+  const writeField = (setRecord, name, value) => {
+    setRecord({ ...readRecord(), [name]: value });
+  };
+  const handle = (entry, use, clear) => {
+    const { codec } = entry;
+    const built = {
+      kind: codec.kind,
+      use,
+      clear,
+      isDefault: (v) => codec.equals(v, codec.fallback)
+    };
+    if (codec.kind === "range") {
+      built["toWindow"] = (v) => {
+        if (v.preset === "custom" && v.from !== void 0 && v.to !== void 0) {
+          return { from: v.from, to: v.to };
+        }
+        const windows = codec.windows;
+        if (windows !== void 0 && Object.hasOwn(windows, v.preset)) {
+          const resolver = windows[v.preset];
+          if (resolver !== void 0) return resolver(/* @__PURE__ */ new Date());
+        }
+        return { window: v.preset };
+      };
+    }
+    if (codec.kind === "number") {
+      const bounds = codec.bounds;
+      built["min"] = bounds?.min;
+      built["max"] = bounds?.max;
+      built["int"] = bounds?.int ?? false;
+    }
+    Object.defineProperty(built, "options", {
+      enumerable: true,
+      get: () => optionsFor(entry)
+    });
+    Object.defineProperty(built, "fallback", {
+      enumerable: true,
+      get: () => codec.fallback
+    });
+    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(),
+    clearField,
+    clearMemory: (name) => memory.remove(name),
+    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 persisted = entry.codec.lane.persist;
+    const use = persisted ? persistedUse(entry) : core.memoryUse(entry);
+    const clear = persisted ? () => core.clearField(entry.name) : () => core.clearMemory(entry.name);
+    field2[entry.name] = core.handle(entry, use, clear);
+  }
+  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,60 @@
+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;
+/**
+ * Write a value under the namespaced key `basalt:<key>` in the same versioned envelope
+ * `createPersistedState` writes, and wake every hook on that key — the write half of
+ * `readPersistedValue`, and plain in the same way: no React required.
+ *
+ * The one call site is a store field's `clear()`, which has to DELETE its key from the store's
+ * record from an event handler, where the hook's setter is not in reach. Not exported from the
+ * `basalt-ui/state` barrel: the two store factories are the API, this is their seam.
+ *
+ * @internal
+ */
+export declare function writePersistedValue(key: string, version: number, value: unknown): void;
+//# 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;AA4FD;;;;;;;;;;;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,CAwEvC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAYhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAItF"}

package/dist/state/persisted.js

@@ -0,0 +1,123 @@
+import { useSyncExternalStore } from "react";
+const noopSubscribe = (_cb) => () => {
+};
+const channels = /* @__PURE__ */ new Map();
+function notify(storageKey) {
+  const channel = channels.get(storageKey);
+  if (channel === void 0) return;
+  for (const listener of channel.listeners) listener();
+}
+function channelFor(storageKey) {
+  const existing = channels.get(storageKey);
+  if (existing !== void 0) return existing;
+  const created = { listeners: /* @__PURE__ */ new Set(), handler: null };
+  channels.set(storageKey, created);
+  return created;
+}
+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 writeEnvelope(storageKey, version, value) {
+  try {
+    const envelope = { v: version, value };
+    window.localStorage.setItem(storageKey, JSON.stringify(envelope));
+  } catch {
+  }
+}
+function writeStorage(opts, next) {
+  writeEnvelope(`basalt:${opts.key}`, opts.version, next);
+}
+function createPersistedState(opts) {
+  const storageKey = `basalt:${opts.key}`;
+  const subscribe = (cb) => {
+    const channel = channelFor(storageKey);
+    channel.listeners.add(cb);
+    if (channel.handler === null) {
+      channel.handler = (e) => {
+        if (e.key === storageKey) notify(storageKey);
+      };
+      window.addEventListener("storage", channel.handler);
+    }
+    return () => {
+      channel.listeners.delete(cb);
+      if (channel.listeners.size === 0 && channel.handler !== null) {
+        window.removeEventListener("storage", channel.handler);
+        channel.handler = 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);
+    notify(storageKey);
+  };
+  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;
+  }
+}
+function writePersistedValue(key, version, value) {
+  const storageKey = `basalt:${key}`;
+  writeEnvelope(storageKey, version, value);
+  notify(storageKey);
+}
+export {
+  createPersistedState,
+  readPersistedValue,
+  writePersistedValue
+};

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

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

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

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

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 RangeWindow, type RangeWindows, type FieldFallback, type FieldSetOptions, 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, type FieldUse, type FieldWrite, resolveFieldCodec, createStoreCore, } from './state/fields.js';
 //# sourceMappingURL=state.d.ts.map