basalt-ui 1.24.0 → 1.26.0

package/dist/router-tanstack/multi-search-param-store.d.ts

@@ -1,52 +1,3 @@
-/**
- * createMultiSearchParamStore — the multi-select sibling of `createSearchParamStore`, for search
- * params backed by an ANY-OF set (e.g. a tag filter) instead of a single value (e.g. a tab).
- *
- * Same three-concern factory shape as `createSearchParamStore`:
- * 1. `validateSearch` — pass directly to `createFileRoute({ validateSearch })`.
- *    Falls back to localStorage when the URL param is absent or invalid, then to `fallback`.
- * 2. `useStore` — React hook: `const [values, persist] = store.useStore()`.
- *    Call `persist(next)` alongside `navigate` so the selection survives navigation.
- * 3. `readStored` — plain function for non-React contexts (tests, guards).
- * 4. `linkSearch` — the click-time `search:` thunk for a nav link, ready-made.
- *
- * Headless — no Mantine, no JSX. Same tier as `createSearchParamStore`.
- *
- * ## Encoding — array-native, not CSV
- *
- * TanStack Router's default search serialization is `stringifySearchWith(JSON.stringify,
- * JSON.parse)`, and its `stringifyValue` branches on `typeof val === 'object' && val !== null` —
- * an array is an object, so `{ tags: ['a', 'b'] }` serializes to `?tags=%5B%22a%22%2C%22b%22%5D`
- * and `parseSearchWith(JSON.parse)` reverses it losslessly. This store deals entirely in arrays
- * (what `validateSearch` returns is exactly what the router stringifies), so a CSV encoding is not
- * reachable from here — there is no string-building step to intercept. A consumer who wants
- * prettier URLs (e.g. `?tags=a,b`) configures router-global `parseSearch`/`stringifySearch` (see
- * TanStack Router's documented custom-search-param-serialization recipe); this store keeps working
- * untouched either way, because it hands the router an array, not an encoding.
- *
- * ## Decoding — defensive and canonical
- *
- * Any value pulled from the URL or localStorage is normalized in this order:
- * 1. Accept only `Array.isArray` input — anything else decodes to empty.
- * 2. Keep only entries present in `opts.values` (drops tampered values and values dropped from the
- *    vocabulary since the URL/localStorage entry was written).
- * 3. Dedupe.
- * 4. Re-sort into `opts.values` DECLARATION order.
- *
- * Canonical ordering means `['api', 'design']` and `['design', 'api']` normalize to the SAME
- * array — one URL for one logical selection, so history entries and any loader cache keyed on the
- * search stay stable regardless of the order a user toggled filters in.
- *
- * @example
- * export const articleTags = createMultiSearchParamStore({
- *   key: 'article-tags', param: 'tags',
- *   values: ['api', 'design', 'guide'] as const,
- * })
- *
- * export const Route = createFileRoute('/content')({
- *   validateSearch: articleTags.validateSearch,
- * })
- */
 export type MultiSearchParamStoreOptions<T extends string, P extends string = string> = {
     /** localStorage key (namespaced `basalt:<key>` automatically). */
     key: string;
@@ -69,7 +20,7 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
     };
     /**
      * React hook: `const [current, persist] = store.useStore()`.
-     * Call `persist(next)` in your filter's `onChange` alongside `navigate()`.
+     * localStorage only — it does NOT read or write the URL.
      */
     useStore: () => readonly [readonly T[], (next: readonly T[]) => void];
     /** Plain read — for use outside React (tests, guards, fallback reads). */
@@ -80,12 +31,13 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
      * for why a module-scope literal silently defeats the store.
      *
      * No dev warning rides on this one, unlike the single-value store: an empty array in the URL is
-     * indistinguishable from an absent param here (`validateSearch` falls back to storage for both),
-     * so a link declaring `{ tags: [] }` restores correctly and there is no broken state to detect.
+     * indistinguishable from an absent param here, so a link declaring `{ tags: [] }` restores
+     * correctly and there is no broken state to detect.
      */
     linkSearch: () => {
         [K in P]: readonly T[];
     };
 };
+/** @deprecated Use `createSearchStore` + `field.multi`. Removed in 1.29.0. */
 export declare function createMultiSearchParamStore<const T extends string, const P extends string>(opts: MultiSearchParamStoreOptions<T, P>): MultiSearchParamStore<T, P>;
 //# sourceMappingURL=multi-search-param-store.d.ts.map

package/dist/router-tanstack/multi-search-param-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multi-search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/multi-search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAMH,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAA;IACR,0FAA0F;IAC1F,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,SAAS,CAAC,EAAE,CAAA;IACvB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC/E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;IAC/E;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,CAAA;IACrE,0EAA0E;IAC1E,UAAU,EAAE,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,CAAA;IACrC;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;CAC7C,CAAA;AAID,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACxF,IAAI,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAwC7B"}
+{"version":3,"file":"multi-search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/multi-search-param-store.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAA;IACR,0FAA0F;IAC1F,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,SAAS,CAAC,EAAE,CAAA;IACvB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC/E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;IAC/E;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,CAAA;IACrE,0EAA0E;IAC1E,UAAU,EAAE,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,CAAA;IACrC;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;CAC7C,CAAA;AAID,8EAA8E;AAC9E,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACxF,IAAI,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CA4B7B"}

package/dist/router-tanstack/multi-search-param-store.js

@@ -1,37 +1,29 @@
-import { createPersistedState, readPersistedValue } from "../state.js";
+import { createPersistedState, field } from "../state.js";
+import { buildSearchStore } from "./search-store.js";
 function createMultiSearchParamStore(opts) {
   const version = opts.version ?? 1;
   const fallback = opts.fallback ?? [];
-  const allowed = new Set(opts.values);
-  const normalize = (raw) => {
-    if (!Array.isArray(raw)) return [];
-    const present = /* @__PURE__ */ new Set();
-    for (const entry of raw) {
-      if (typeof entry === "string" && allowed.has(entry)) present.add(entry);
-    }
-    return opts.values.filter((value) => present.has(value));
-  };
-  const readStored = () => {
-    const raw = readPersistedValue(opts.key, version);
-    if (!Array.isArray(raw)) return null;
-    return normalize(raw);
-  };
-  const linkSearch = () => {
-    return { [opts.param]: readStored() ?? fallback };
-  };
-  const validateSearch = (search) => {
-    const fromUrl = normalize(search[opts.param]);
-    if (fromUrl.length > 0) {
-      return { [opts.param]: fromUrl };
-    }
-    return { [opts.param]: readStored() ?? fallback };
-  };
-  const useStore = createPersistedState({
+  const store = buildSearchStore({
+    key: opts.key,
+    version,
+    fields: { [opts.param]: field.multi(opts.values, fallback) },
+    legacyValueField: opts.param
+  });
+  const persisted = createPersistedState({
     key: opts.key,
     version,
     initial: fallback
   });
-  return { validateSearch, useStore, readStored, linkSearch };
+  const useStore = () => {
+    store.markReaderWired();
+    return persisted();
+  };
+  return {
+    validateSearch: (search) => store.validateSearch(search),
+    useStore,
+    readStored: () => store.readStored()[opts.param] ?? null,
+    linkSearch: () => store.linkSearch()
+  };
 }
 export {
   createMultiSearchParamStore

package/dist/router-tanstack/search-param-store.d.ts

@@ -1,89 +1,3 @@
-/**
- * createSearchParamStore — bridge between TanStack Router URL search params and
- * basalt-ui's localStorage persistence.
- *
- * Combines three concerns into one factory:
- * 1. `validateSearch` — pass directly to `createFileRoute({ validateSearch })`.
- *    Falls back to localStorage when the URL param is absent or invalid.
- * 2. `useStore` — React hook: `const [value, persist] = store.useStore()`.
- *    Call `persist(next)` alongside `navigate` so the selection survives
- *    navigation away from and back to the route.
- * 3. `readStored` — plain function for non-React contexts (tests, guards).
- * 4. `linkSearch` — the click-time `search:` thunk a nav link needs, ready-made.
- *
- * ## The half that is easy to skip
- *
- * `validateSearch` restores the value when you navigate TO the route with no param. It cannot do
- * anything about a nav link that declares the param itself — and a link written as
- * `search: { range: '30d' }` at module scope pins the fallback on every click, which silently
- * defeats the whole store. The reference consumer shipped exactly that: three features adopted the
- * persistence, the reader had ZERO call sites, and "remember my window" had never once worked.
- *
- * `linkSearch` exists so that failure is unreachable from the API rather than only warned about in
- * this comment — the mistake is made while typing `search:`, so the remedy has to be something
- * autocomplete offers at that keystroke. The JSDoc was already here when it happened.
- *
- * Headless — no Mantine, no JSX. Same tier as `useBasaltNav` and
- * `useRouterBreadcrumbs`.
- *
- * ## Full integration recipe (5 steps)
- *
- * **1. Define** — one call per search param, e.g. in a shared lib/ module:
- *
- *     export const dashboardRange = createSearchParamStore({
- *       key: 'dashboard-range',  param: 'range',
- *       values: ['1d', '7d', '30d'] as const,  fallback: '30d',
- *     })
- *
- * **2. Route** — plug validateSearch into the parent layout route:
- *
- *     export const Route = createFileRoute('/dashboard')({
- *       validateSearch: dashboardRange.validateSearch,
- *       component: DashboardLayout,  // renders <DateFilter/> + <Outlet/>
- *     })
- *
- * **3. Filter** — a component in the shell header (PageActions portal):
- *
- *     function DateFilter() {
- *       const { range } = useSearch({ from: '/dashboard' })
- *       const [, persist] = dashboardRange.useStore()
- *       return <SegmentedControl value={range}
- *         onChange={(v) => { persist(v); navigate({ to: '.',
- *           search: (prev) => ({ ...prev, range: v }) }) }} />
- *     }
- *
- * **4. Page** — accepts the param as a **prop**, NOT from useSearch:
- *
- *     // CRITICAL: never call useSearch({ from: '/dashboard' }) in a page
- *     // component that renders on a sibling route (e.g. /activity).
- *     // Sibling routes aren't children — the `from` fails.
- *     function DashboardPage({ range = '30d' }: { range?: DateRange }) {
- *       const data = useMemo(() => generateData(range), [range])
- *       return <Charts data={data} range={range} />
- *     }
- *
- * **5. Nav links** — carry the param across sub-pages, set per destination in
- * the nav definition so only the dashboard sub-tree inherits it and every
- * other link stays clean. Pass `linkSearch` BY REFERENCE — it is the click-time thunk:
- *
- *     navGroup({ id: 'dash', label: 'Dashboard' }, [
- *       { id: 'dash-overview', label: 'Overview', icon: <IconHome />,
- *         link: linkOptions({ to: '/dashboard', search: dashboardRange.linkSearch }) },
- *       { id: 'dash-activity', label: 'Activity', icon: <IconPulse />,
- *         link: linkOptions({ to: '/dashboard/activity', search: dashboardRange.linkSearch }) },
- *     ])
- *
- * `linkSearch` IS that thunk (`() => ({ [param]: readStored() ?? fallback })`) — hand-rolling it
- * over `readStored` still works and is what you need when the link also carries other params.
- *
- * NOT `search: true`. That flag means "keep the current search" and TanStack
- * only offers it where the target's search is OPTIONAL — a route wired to a
- * store's `validateSearch` always returns the param, so the router requires a
- * value and `search: true` is a type error. The thunk is also the better
- * behaviour: `<Link>` re-evaluates it at click time, so arriving from OUTSIDE
- * the sub-tree restores the last selection instead of landing on the factory
- * default, and a definition evaluated once at module scope never goes stale.
- */
 export type SearchParamStoreOptions<T extends string, P extends string = string> = {
     /** localStorage key (namespaced `basalt:<key>` automatically). */
     key: string;
@@ -106,7 +20,8 @@ export type SearchParamStore<T extends string, P extends string = string> = {
     };
     /**
      * React hook: `const [current, persist] = store.useStore()`.
-     * Call `persist(next)` in your filter's `onChange` alongside `navigate()`.
+     * localStorage only — it does NOT read or write the URL. `createSearchStore`'s
+     * `field.<name>.use()` is the replacement that does both.
      */
     useStore: () => readonly [T, (next: T) => void];
     /** Plain read — for use outside React (tests, guards, fallback reads). */
@@ -122,5 +37,6 @@ export type SearchParamStore<T extends string, P extends string = string> = {
         [K in P]: T;
     };
 };
+/** @deprecated Use `createSearchStore` + `field.enum`. Removed in 1.29.0. */
 export declare function createSearchParamStore<const T extends string, const P extends string>(opts: SearchParamStoreOptions<T, P>): SearchParamStore<T, P>;
 //# sourceMappingURL=search-param-store.d.ts.map

package/dist/router-tanstack/search-param-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAMH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;CAClC,CAAA;AAgCD,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAyDxB"}
+{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;;OAIG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;CAClC,CAAA;AAID,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAwBxB"}

package/dist/router-tanstack/search-param-store.js

@@ -1,53 +1,24 @@
-import { createPersistedState, readPersistedValue } from "../state.js";
-function warnLinkPinsFallback(input) {
-  const { key, param, urlValue, storedValue } = input;
-  console.warn(
-    `[basalt-ui] createSearchParamStore('${key}'): the URL pinned \`${param}=${urlValue}\` (the fallback) while '${storedValue}' was persisted, and nothing has read this store back. A nav link is almost certainly declaring \`search: { ${param}: '${urlValue}' }\` at module scope, which overrides the stored value on every click \u2014 pass the store's own reader instead: \`search: <store>.linkSearch\`. (dev only)`
-  );
-}
+import { createPersistedState, field } from "../state.js";
+import { buildSearchStore } from "./search-store.js";
 function createSearchParamStore(opts) {
   const version = opts.version ?? 1;
-  let readerWired = false;
-  let warned = false;
-  const read = () => {
-    const raw = readPersistedValue(opts.key, version);
-    if (typeof raw !== "string") return null;
-    if (opts.values.includes(raw)) return raw;
-    return null;
-  };
-  const readStored = () => {
-    readerWired = true;
-    return read();
-  };
-  const linkSearch = () => {
-    readerWired = true;
-    return { [opts.param]: read() ?? opts.fallback };
-  };
-  const validateSearch = (search) => {
-    const raw = search[opts.param];
-    if (typeof raw === "string" && opts.values.includes(raw)) {
-      if (!warned && !readerWired && raw === opts.fallback && process.env["NODE_ENV"] !== "production") {
-        const stored = read();
-        if (stored !== null && stored !== raw) {
-          warned = true;
-          warnLinkPinsFallback({
-            key: opts.key,
-            param: opts.param,
-            urlValue: raw,
-            storedValue: stored
-          });
-        }
-      }
-      return { [opts.param]: raw };
-    }
-    return { [opts.param]: read() ?? opts.fallback };
-  };
-  const useStore = createPersistedState({
+  const store = buildSearchStore({
     key: opts.key,
     version,
-    initial: opts.fallback
+    fields: { [opts.param]: field.enum(opts.values, opts.fallback) },
+    legacyValueField: opts.param
   });
-  return { validateSearch, useStore, readStored, linkSearch };
+  const persisted = createPersistedState({ key: opts.key, version, initial: opts.fallback });
+  const useStore = () => {
+    store.markReaderWired();
+    return persisted();
+  };
+  return {
+    validateSearch: (search) => store.validateSearch(search),
+    useStore,
+    readStored: () => store.readStored()[opts.param] ?? null,
+    linkSearch: () => store.linkSearch()
+  };
 }
 export {
   createSearchParamStore

package/dist/router-tanstack/search-store.d.ts

@@ -0,0 +1,81 @@
+import type { AnyField, FieldHandle, SearchValues, StoredValues } from '../state.js';
+export type CreateSearchStoreOptions<S extends Record<string, AnyField>> = {
+    /** localStorage key (namespaced `basalt:<key>` automatically). One entry per store. */
+    key: string;
+    /** The fields, built with `field.*`. The key of each is its default URL param name. */
+    fields: S;
+    /** Envelope version — bump when the field set changes to discard stale localStorage. */
+    version?: number;
+};
+export type SearchStore<S extends Record<string, AnyField>> = {
+    /**
+     * Pass directly to `createFileRoute({ validateSearch })`. Returns every URL-lane param, resolved
+     * URL ⊳ localStorage ⊳ fallback — a route wired to it therefore always has the params, which is
+     * what makes `use()`'s "does this route own the field" check trivial and exact.
+     */
+    validateSearch: (raw: Record<string, unknown>) => SearchValues<S>;
+    /**
+     * The click-time `search:` value for a nav link. Pass it BY REFERENCE
+     * (`search: store.linkSearch`) inside `defineNav` — never a literal object, which pins the
+     * fallback on every click and is why one consumer's reader had zero call sites (C10, A2).
+     */
+    linkSearch: () => SearchValues<S>;
+    /** Plain read for non-React contexts (a redirect, a loader, a guard, a test). */
+    readStored: () => Partial<StoredValues<S>>;
+    /** The per-field handles every basalt control takes instead of `value`/`onChange` (C2). */
+    field: {
+        [K in keyof S]: FieldHandle<S[K]>;
+    };
+    /** Option labels for enum / multi / range fields. Chainable — call it once, at definition. */
+    labels: (map: Partial<{
+        [K in keyof S]: Record<string, string>;
+    }>) => SearchStore<S>;
+    /** Every URL-lane param, resolved — the object a page hands to its query. */
+    useValues: () => SearchValues<S>;
+    /** How many fields differ from their fallback — the `n` in a `Filters (n)` pill. */
+    useActiveCount: () => number;
+    /** Resets every field to its fallback: one navigate, one storage write. */
+    useReset: () => () => void;
+};
+/**
+ * The public store plus the one member only the deprecated wrappers need: `markReaderWired`, so a
+ * consumer whose only reader is the wrapper's own `useStore()` still counts as wired and never sees
+ * the pinned-link warning it never used to see.
+ *
+ * @internal — absent from `SearchStore`, so it is invisible on `createSearchStore`'s return type.
+ */
+export type InternalSearchStore<S extends Record<string, AnyField>> = SearchStore<S> & {
+    markReaderWired: () => void;
+};
+/**
+ * The store, plus the one knob the deprecated wrappers need: `legacyValueField` keeps the
+ * enum-only stores' single-value storage layout so an already-persisted selection still resolves.
+ * Not exported from the barrel — `createSearchStore` is the public door.
+ */
+export declare function buildSearchStore<const S extends Record<string, AnyField>>(o: CreateSearchStoreOptions<S> & {
+    legacyValueField?: string;
+}): InternalSearchStore<S>;
+/**
+ * One store per page (or per feature), over typed fields. `key` is the localStorage key; each
+ * field's map key is its default URL param name.
+ *
+ * @example
+ * export const analytics = createSearchStore({
+ *   key: 'analytics',
+ *   fields: {
+ *     range: field.range({ presets: ['7d', '30d', '90d'], fallback: '30d', custom: true }),
+ *     compare: field.enum(['none', 'previous'], 'none'),
+ *     channels: field.multi(CHANNELS, []),
+ *   },
+ * }).labels({ range: { '7d': 'Last 7 days', '30d': 'Last 30 days', '90d': 'Last 90 days' } })
+ *
+ * export const Route = createFileRoute('/analytics')({
+ *   validateSearch: analytics.validateSearch,
+ *   loaderDeps: ({ search }) => search,
+ * })
+ *
+ * // in the page: <RangeFilter field={analytics.field.range} />
+ * // in the nav:  linkOptions({ to: '/analytics', search: analytics.linkSearch })
+ */
+export declare function createSearchStore<const S extends Record<string, AnyField>>(o: CreateSearchStoreOptions<S>): SearchStore<S>;
+//# sourceMappingURL=search-store.d.ts.map

package/dist/router-tanstack/search-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-store.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAc,YAAY,EAAE,MAAM,UAAU,CAAA;AAI7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;IACzE,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,MAAM,EAAE,CAAC,CAAA;IACT,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;IAC5D;;;;OAIG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAA;IACjE;;;;OAIG;IACH,UAAU,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAA;IACjC,iFAAiF;IACjF,UAAU,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1C,2FAA2F;IAC3F,KAAK,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAA;IAC5C,8FAA8F;IAC9F,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;KAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;IACpF,6EAA6E;IAC7E,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAA;IAChC,oFAAoF;IACpF,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,MAAM,IAAI,CAAA;CAC3B,CAAA;AA4DD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IACrF,eAAe,EAAE,MAAM,IAAI,CAAA;CAC5B,CAAA;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACvE,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,mBAAmB,CAAC,CAAC,CAAC,CAoMxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACxE,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAC7B,WAAW,CAAC,CAAC,CAAC,CAEhB"}

package/dist/router-tanstack/search-store.js

@@ -0,0 +1,187 @@
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { createStoreCore } from "../state.js";
+function warnLinkPinsFallback(input) {
+  const { key, param, urlValue, storedValue } = input;
+  console.warn(
+    `[basalt-ui] createSearchStore('${key}'): the URL pinned \`${param}=${urlValue}\` (the fallback) while '${storedValue}' was persisted, and nothing has read this store back. A nav link is almost certainly declaring \`search: { ${param}: '${urlValue}' }\` at module scope, which overrides the stored value on every click \u2014 pass the store's own reader instead: \`search: <store>.linkSearch\`. (dev only)`
+  );
+}
+function useCurrentSearch() {
+  const search = useSearch({ strict: false });
+  return typeof search === "object" && search !== null ? search : {};
+}
+function describeValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function warnWriteHasNowhereToGo(input) {
+  const { key, name, param } = input;
+  console.warn(
+    `[basalt-ui] createSearchStore('${key}'): wrote field '${name}' from a route that does not validate \`${param}\`, and the field is \`persist: false\` \u2014 so the write was dropped. Either render this control on the route wired to \`validateSearch\`, or give the field the localStorage lane (drop \`persist: false\`) so a write from elsewhere survives until the owning route reads it. (dev only)`
+  );
+}
+function isMemoryLane(entry) {
+  return !entry.codec.lane.url && !entry.codec.lane.persist;
+}
+function buildSearchStore(o) {
+  const core = createStoreCore(o);
+  let readerWired = false;
+  let warned = false;
+  const markReaderWired = () => {
+    readerWired = true;
+  };
+  const nowhereWarned = /* @__PURE__ */ new Set();
+  const flatten = (search, record) => {
+    const out = {};
+    for (const entry of core.urlEntries) {
+      Object.assign(out, entry.codec.toSearch(core.resolve(entry, search, record)));
+    }
+    return out;
+  };
+  const maybeWarn = (raw, record) => {
+    if (warned || readerWired || process.env["NODE_ENV"] === "production") return;
+    for (const entry of core.urlEntries) {
+      const fromUrl = entry.codec.fromSearch(raw);
+      if (fromUrl === null || !entry.codec.equals(fromUrl, entry.codec.fallback)) continue;
+      const stored = entry.codec.decode(record[entry.name]);
+      if (stored === null || entry.codec.equals(stored, fromUrl)) continue;
+      warned = true;
+      warnLinkPinsFallback({
+        key: o.key,
+        param: entry.codec.primary,
+        urlValue: describeValue(entry.codec.toSearch(fromUrl)[entry.codec.primary]),
+        storedValue: describeValue(entry.codec.toSearch(stored)[entry.codec.primary])
+      });
+      return;
+    }
+  };
+  const validateSearch = (raw) => {
+    const record = core.readRecord();
+    maybeWarn(raw, record);
+    return flatten(raw, record);
+  };
+  const linkSearch = () => {
+    readerWired = true;
+    return flatten(null, core.readRecord());
+  };
+  const readStored = () => {
+    readerWired = true;
+    return core.readStoredFlat();
+  };
+  const urlUse = (entry) => () => {
+    const search = useCurrentSearch();
+    const navigate = useNavigate();
+    const [record, setRecord] = core.usePersistedRecord();
+    markReaderWired();
+    const value = core.resolve(entry, search, record);
+    const validated = Object.hasOwn(search, entry.codec.primary);
+    return [
+      value,
+      (next) => {
+        if (validated) {
+          navigate({
+            to: ".",
+            search: (prev) => ({ ...prev, ...entry.codec.toSearch(next) }),
+            replace: entry.codec.lane.history === "replace",
+            // A filter lives halfway down a page as often as it lives in the bar, and the router's
+            // default scroll restoration treats this same-route search write as a navigation — so
+            // without this a select two screens down jumps the reader back to the top on every
+            // change. Never a prop: there is no filter write that WANTS the page to scroll.
+            resetScroll: false
+          });
+        }
+        if (entry.codec.lane.persist) {
+          core.writeField(setRecord, entry.name, next);
+          return;
+        }
+        if (validated || nowhereWarned.has(entry.name)) return;
+        if (process.env["NODE_ENV"] === "production") return;
+        nowhereWarned.add(entry.name);
+        warnWriteHasNowhereToGo({ key: o.key, name: entry.name, param: entry.codec.primary });
+      }
+    ];
+  };
+  const localUse = (entry) => () => {
+    const [record, setRecord] = core.usePersistedRecord();
+    markReaderWired();
+    return [
+      core.resolve(entry, null, record),
+      (next) => core.writeField(setRecord, entry.name, next)
+    ];
+  };
+  const memoryEntries = core.entries.filter(isMemoryLane);
+  const field = {};
+  for (const entry of core.entries) {
+    const use = entry.codec.lane.url ? urlUse(entry) : entry.codec.lane.persist ? localUse(entry) : core.memoryUse(entry);
+    field[entry.name] = core.handle(entry, use);
+  }
+  const useValues = () => {
+    const search = useCurrentSearch();
+    const [record] = core.usePersistedRecord();
+    markReaderWired();
+    return flatten(search, record);
+  };
+  const useActiveCount = () => {
+    const search = useCurrentSearch();
+    const [record] = core.usePersistedRecord();
+    core.useMemoryVersion();
+    let count = 0;
+    for (const entry of core.entries) {
+      const value = isMemoryLane(entry) ? core.readMemoryValue(entry) : core.resolve(entry, entry.codec.lane.url ? search : null, record);
+      if (!entry.codec.equals(value, entry.codec.fallback)) count += 1;
+    }
+    return count;
+  };
+  const useReset = () => {
+    const search = useCurrentSearch();
+    const navigate = useNavigate();
+    const [, setRecord] = core.usePersistedRecord();
+    return () => {
+      const validatedEntries = core.urlEntries.filter(
+        (entry) => Object.hasOwn(search, entry.codec.primary)
+      );
+      if (validatedEntries.length > 0) {
+        const patch = {};
+        for (const entry of validatedEntries) {
+          Object.assign(patch, entry.codec.toSearch(entry.codec.fallback));
+        }
+        navigate({
+          to: ".",
+          search: (prev) => ({ ...prev, ...patch }),
+          replace: true,
+          // Same reason as a single field's write above — a `Reset all` pressed from the mobile
+          // sheet must not also scroll the page it was pressed on.
+          resetScroll: false
+        });
+      }
+      if (memoryEntries.length > 0) core.resetMemory();
+      if (!core.anyPersisted) return;
+      const next = { ...core.readRecord() };
+      for (const entry of core.entries) {
+        if (entry.codec.lane.persist) next[entry.name] = entry.codec.fallback;
+      }
+      setRecord(next);
+    };
+  };
+  const store = {
+    validateSearch,
+    linkSearch,
+    readStored,
+    field,
+    labels: (map) => {
+      core.setLabels(map);
+      return store;
+    },
+    useValues,
+    useActiveCount,
+    useReset,
+    markReaderWired
+  };
+  return store;
+}
+function createSearchStore(o) {
+  return buildSearchStore(o);
+}
+export {
+  buildSearchStore,
+  createSearchStore
+};

package/dist/router-tanstack/search-store.router.test.d.ts

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

package/dist/router-tanstack/search-store.router.test.d.ts.map

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

package/dist/router-tanstack/search-store.test.d.ts

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

package/dist/router-tanstack/search-store.test.d.ts.map

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

package/dist/router-tanstack/use-nav.d.ts

@@ -10,8 +10,6 @@ export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
     badges?: Partial<Record<NavItemId<G>, number | ReactNode>>;
     /** Override active detection entirely. */
     isActive?: (item: AnyNavItem) => boolean;
-    /** Passed straight through into the returned `mobileNav`. */
-    moreExtra?: ReactNode;
     getScrollElement?: () => HTMLElement | null;
 };
 /** Spread straight onto `<BasaltShell {...nav} />` — both keys are `BasaltShellProps` keys. */

package/dist/router-tanstack/use-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-nav.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,IAAI;IAChE;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAA;IACxC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAA;AAEnF;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,EAC1C,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAqG9D"}
+{"version":3,"file":"use-nav.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAE3F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,IAAI;IAChE;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAA;IACxC,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAA;AAEnF;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,EAC1C,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAgK9D"}