basalt-ui 1.25.0 → 1.27.0

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   BasaltErrorBoundary
 } from "./provider/index.js";
 import { createBasaltTheme, baseTheme, cssVariablesResolver } from "./theme/index.js";
+import { CTL_THEME, CtlSlot } from "./theme/index.js";
 import { ThemeToggle } from "./theme-toggle/index.js";
 import { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from "./motion/index.js";
 import {
@@ -17,18 +18,18 @@ import {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  PageHeaderProvider,
-  PageActions,
-  PageActionsOutlet
+  PageBar
 } from "./shell/index.js";
 import {
   assertNever
 } from "./register.js";
 import {
   createPersistedState,
-  useOnlineStatus,
-  readPersistedValue
+  readPersistedValue,
+  createLocalStore
 } from "./state.js";
+import { WidgetHeader } from "./widget-header/index.js";
+import { Section } from "./section/index.js";
 import {
   DeltaBadge,
   StatCard,
@@ -65,9 +66,11 @@ export {
   BasaltErrorBoundary,
   BasaltProvider,
   BasaltShell,
+  CTL_THEME,
   Composer,
   ConnectivityIndicator,
   ConnectivityProvider,
+  CtlSlot,
   DangerZone,
   DeltaBadge,
   EmptyState,
@@ -81,10 +84,9 @@ export {
   MOTION_SPRING,
   MobileNav,
   NavCountBadge,
-  PageActions,
-  PageActionsOutlet,
-  PageHeaderProvider,
+  PageBar,
   QueryState,
+  Section,
   SettingsRow,
   SettingsSection,
   SidebarAccount,
@@ -98,10 +100,12 @@ export {
   ThreadTranscript,
   ThreadWorkspace,
   ToolChip,
+  WidgetHeader,
   assertNever,
   baseTheme,
   createAdapterThreadsStore,
   createBasaltTheme,
+  createLocalStore,
   createPersistedState,
   createThreadsStore,
   cssVariablesResolver,
@@ -111,6 +115,5 @@ export {
   threadPartRenderers,
   threadsStoreAdapterContract,
   useAgentThreadRuns,
-  useConnectivity,
-  useOnlineStatus
+  useConnectivity
 };

package/dist/nav/types.d.ts

@@ -37,6 +37,8 @@ export type SidebarItem = {
     /** Plain href — the no-router fallback, and the breadcrumb parent target. */
     href?: string;
     active?: boolean;
+    /** A parent on the path to the active row. NOT active itself — never carries `aria-current`. */
+    ancestor?: boolean;
     disabled?: boolean;
     onClick?: (e: MouseEvent) => void;
     /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
@@ -64,6 +66,82 @@ export type SidebarSection = {
     /** Mobile behaviour for this section. Omit for the default (items place themselves). */
     mobile?: false | NavSectionMobile;
 };
+/**
+ * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
+ * members are `VX.status` keys by construction. Declared here rather than imported from
+ * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
+ * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
+ * `@mantine/core` installed.
+ */
+export type SidebarBlockTone = 'good' | 'warn' | 'bad';
+/** One row inside a `kind: 'list'` block. Same router seam as `SidebarItem` — `Anchor`, then href. */
+export type SidebarBlockItem = {
+    key: string;
+    label: string;
+    /** Trailing muted text (a timestamp, a count, an owner). */
+    meta?: string;
+    icon?: ReactNode;
+    /** Renders a status dot in place of a missing `icon`; reads `--vx-status-*`, never a hex. */
+    tone?: SidebarBlockTone;
+    Anchor?: NavAnchor;
+    href?: string;
+    onClick?: () => void;
+};
+/**
+ * A list of non-destination rows under a micro-label — "Awaiting action", "Recents", a project
+ * list. `count` is the header badge (and what earns a rail dot); `max` shows the first N with a
+ * "Show more" toggle past it.
+ */
+export type SidebarListBlock = {
+    kind: 'list';
+    key: string;
+    label: string;
+    icon?: ReactNode;
+    count?: number;
+    /** Rows shown before the "Show more" toggle. Omit to show every row. */
+    max?: number;
+    items: SidebarBlockItem[];
+    /** @default 'nav' */
+    placement?: 'nav' | 'bottom';
+    collapsible?: boolean;
+    /** Collapsed-rail projection. @default 'dot' when `count` is set, `'hidden'` otherwise */
+    rail?: 'dot' | 'hidden';
+    /** @default 'more' */
+    mobile?: 'more' | 'hidden';
+};
+/** A "Getting started 1 of 5" progress row. Pinned above the settings footer; never in the nav. */
+export type SidebarProgressBlock = {
+    kind: 'progress';
+    key: string;
+    label: string;
+    value: number;
+    total: number;
+    onClick?: () => void;
+    /** @default 'bottom' — the only placement a progress row has. */
+    placement?: 'bottom';
+    /** Collapsed-rail projection: a ring on the settings row. @default 'ring' */
+    rail?: 'ring' | 'hidden';
+    /** @default 'hidden' */
+    mobile?: 'more' | 'hidden';
+};
+/**
+ * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
+ * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
+ * from mobile for the same reason that prop was.
+ */
+export type SidebarCustomBlock = {
+    kind: 'custom';
+    key: string;
+    node: ReactNode;
+    /** @default 'nav' */
+    placement?: 'nav' | 'bottom';
+};
+/**
+ * A sidebar block — DECLARED DATA, never a `ReactNode` slot (law C13, `docs/CONTROLS-SPEC.md`
+ * §2.3), which is what lets basalt own the collapsed-rail badge and the mobile More-sheet
+ * projection instead of each consumer hand-rolling both.
+ */
+export type SidebarBlock = SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock;
 export type MobileNavSurface = 'link' | 'menu' | 'sheet';
 /** One row inside a `menu`/`sheet` slot, grouped under its source section. */
 export type MobileNavGroup = {
@@ -102,8 +180,6 @@ export type MobileNavConfig = {
     menuMax?: number;
     /** @default 'More' */
     moreLabel?: string;
-    /** Extra content pinned to the bottom of the More surface. */
-    moreExtra?: ReactNode;
     /** Scroll container for active-slot re-tap. @default document.scrollingElement */
     getScrollElement?: () => HTMLElement | null;
 };

package/dist/nav/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/nav/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/nav/types.ts"],"names":[],"mappings":"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"}

package/dist/notifications/bell.d.ts

@@ -6,7 +6,10 @@ export type NotificationBellProps = {
  * Bell icon button with an unread-Inbox indicator. Opens a NotificationCenter popover.
  *
  * @example
- * <BasaltShell globalActions={<NotificationBell />} {...rest} />
+ * <BasaltShell
+ *   globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]}
+ *   {...rest}
+ * />
  */
 export declare function NotificationBell({ label }: NotificationBellProps): import("react").JSX.Element;
 //# sourceMappingURL=bell.d.ts.map

package/dist/notifications/bell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bell.d.ts","sourceRoot":"","sources":["../../src/notifications/bell.tsx"],"names":[],"mappings":"AA0BA,MAAM,MAAM,qBAAqB,GAAG;IAClC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,KAAuB,EAAE,EAAE,qBAAqB,+BAsElF"}
+{"version":3,"file":"bell.d.ts","sourceRoot":"","sources":["../../src/notifications/bell.tsx"],"names":[],"mappings":"AA0BA,MAAM,MAAM,qBAAqB,GAAG;IAClC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,KAAuB,EAAE,EAAE,qBAAqB,+BAsElF"}

package/dist/notifications/index.d.ts

@@ -20,7 +20,7 @@
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
  * // Shell bell (globalActions slot):
- * <BasaltShell globalActions={<NotificationBell />} ... />
+ * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
 export { notify, notifySuccess, notifyError, notifyWarning, notifyInfo, notifyPromise, } from './notify.js';
 export type { NotifyOptions, NotifyPromiseMessages } from './notify.js';

package/dist/router-tanstack/field.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `field.*` — the field vocabulary `createSearchStore` takes, re-exported at the surface a consumer
+ * imports it from (`basalt-ui/router-tanstack`, beside the store factory).
+ *
+ * The builders and their codecs LIVE in `../state` on purpose: a field is declarative data with no
+ * router in it, and `createLocalStore` — the router-free lane, published on `basalt-ui/state` —
+ * has to build the same fields without pulling in `@tanstack/react-router`. One definition, two
+ * surfaces, no second description of the same param.
+ *
+ * Full field reference: the JSDoc on `field` itself, and `docs/CONTROLS-SPEC.md` §4.
+ */
+export { field } from '../state.js';
+export type { AnyField, BooleanField, EnumField, FieldFallback, FieldHandle, FieldLane, FieldOption, FieldSetOptions, FieldValue, MultiField, NumberField, RangeField, RangeParams, RangePresets, RangeWindow, RangeWindows, RangeValue, ResolvedLane, SearchValues, StoredValues, StringField, } from '../state.js';
+//# sourceMappingURL=field.d.ts.map

package/dist/router-tanstack/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,UAAU,CAAA"}

package/dist/router-tanstack/field.js

@@ -0,0 +1,4 @@
+import { field } from "../state.js";
+export {
+  field
+};

package/dist/router-tanstack/index.d.ts

@@ -3,9 +3,13 @@
  * Optional peer: @tanstack/react-router.
  * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
  * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
- * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
- * the search-param stores — no Mantine, no JSX.
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs, plus
+ * `createSearchStore` + the `field.*` vocabulary (and the two deprecated enum-only wrappers it
+ * replaced) — no Mantine, no JSX.
  */
+export { createSearchStore, type CreateSearchStoreOptions, type SearchStore } from './search-store.js';
+export { field } from './field.js';
+export type { AnyField, BooleanField, EnumField, FieldFallback, FieldHandle, FieldLane, FieldOption, FieldSetOptions, FieldValue, MultiField, NumberField, RangeField, RangeParams, RangePresets, RangeValue, RangeWindow, RangeWindows, ResolvedLane, SearchValues, StoredValues, StringField, } from './field.js';
 export { createSearchParamStore, type SearchParamStore, type SearchParamStoreOptions, } from './search-param-store.js';
 export { createMultiSearchParamStore, type MultiSearchParamStore, type MultiSearchParamStoreOptions, } from './multi-search-param-store.js';
 export { defineNav, navGroup, navTarget, flattenNav } from './nav.js';

package/dist/router-tanstack/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClE,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,QAAQ,GACT,MAAM,OAAO,CAAA;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC1D,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,0EAA0E;QAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,oEAAoE;QACpE,IAAI,CAAC,EAAE,SAAS,CAAA;QAChB,wDAAwD;QACxD,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB;CACF;AAID,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG;IACtB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAID,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CASzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACnG,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClE,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,QAAQ,GACT,MAAM,OAAO,CAAA;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC1D,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,0EAA0E;QAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,oEAAoE;QACpE,IAAI,CAAC,EAAE,SAAS,CAAA;QAChB,wDAAwD;QACxD,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB;CACF;AAID,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG;IACtB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAID,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CASzD"}

package/dist/router-tanstack/index.js

@@ -1,3 +1,5 @@
+import { createSearchStore } from "./search-store.js";
+import { field } from "./field.js";
 import {
   createSearchParamStore
 } from "./search-param-store.js";
@@ -26,7 +28,9 @@ function useRouterBreadcrumbs() {
 export {
   createMultiSearchParamStore,
   createSearchParamStore,
+  createSearchStore,
   defineNav,
+  field,
   flattenNav,
   navGroup,
   navTarget,

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