basalt-ui 1.25.0 → 1.27.0

package/src/router-tanstack/multi-search-param-store.test.ts

@@ -1,8 +1,26 @@
-import { describe, expect, test } from 'bun:test'
+/**
+ * The deprecated multi wrapper's contract, unchanged across the rewrite onto
+ * `createSearchStore` — plus the storage path two of these tests used to claim was unreachable.
+ *
+ * `bun test` runs under happy-dom (root `bunfig.toml` preload), so `localStorage` has always been
+ * REAL here: "no localStorage in this environment" was false, and it meant the fallback-to-storage
+ * half of `validateSearch` — the entire reason the store exists — was asserted only in the
+ * single-value store's tests (D12).
+ */
+import { beforeEach, describe, expect, test } from 'bun:test'
 import { createMultiSearchParamStore } from './multi-search-param-store'
 
 const VALUES = ['api', 'design', 'guide'] as const
 
+/** Writes the wrapper's single-value envelope — the layout it has used since 1.0.0. */
+function persist(key: string, value: readonly string[], version = 1): void {
+  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: version, value }))
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
 describe('createMultiSearchParamStore', () => {
   describe('validateSearch', () => {
     test('URL value wins when it decodes to a non-empty array', () => {
@@ -30,10 +48,17 @@ describe('createMultiSearchParamStore', () => {
       expect(a.tags).toEqual(['api', 'design'])
     })
 
-    test('a non-array URL value falls through to the fallback (no localStorage in this env)', () => {
+    test('a non-array URL value falls through to storage, then to the fallback', () => {
       const store = createMultiSearchParamStore({ key: 'tags-e', param: 'tags', values: VALUES })
       expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: [] })
       expect(store.validateSearch({})).toEqual({ tags: [] })
+
+      persist('tags-e', ['guide', 'api'])
+      // Storage is read, and normalized on the way out like any other source.
+      expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: ['api', 'guide'] })
+      expect(store.validateSearch({})).toEqual({ tags: ['api', 'guide'] })
+      // A valid URL array still wins over it.
+      expect(store.validateSearch({ tags: ['design'] })).toEqual({ tags: ['design'] })
     })
 
     test('an empty URL array falls through to the fallback', () => {
@@ -48,9 +73,52 @@ describe('createMultiSearchParamStore', () => {
   })
 
   describe('readStored', () => {
-    test('returns null when nothing is persisted (no localStorage in this test environment)', () => {
+    test('returns null when nothing is persisted', () => {
       const store = createMultiSearchParamStore({ key: 'tags-g', param: 'tags', values: VALUES })
       expect(store.readStored()).toBeNull()
     })
+
+    test('returns the normalized stored selection, and null for a stale envelope version', () => {
+      const store = createMultiSearchParamStore({ key: 'tags-h', param: 'tags', values: VALUES })
+      persist('tags-h', ['guide', 'nope', 'api'])
+      expect(store.readStored()).toEqual(['api', 'guide'])
+
+      const versioned = createMultiSearchParamStore({
+        key: 'tags-i',
+        param: 'tags',
+        values: VALUES,
+        version: 1,
+      })
+      persist('tags-i', ['api'], 2)
+      expect(versioned.readStored()).toBeNull()
+    })
+
+    test('a stored EMPTY selection reads back as empty — a cleared filter stays cleared', () => {
+      // `{ v: 1, value: [] }` is exactly what `useStore()`'s setter writes when a user clears every
+      // filter. The empty-array-means-absent rule is a URL rule; applying it to storage too would
+      // resurrect the fallback on upgrade, which is not what "byte-compatible" means.
+      const store = createMultiSearchParamStore({
+        key: 'tags-empty',
+        param: 'tags',
+        values: VALUES,
+        fallback: ['guide'],
+      })
+      persist('tags-empty', [])
+
+      expect(store.readStored()).toEqual([])
+      expect(store.validateSearch({})).toEqual({ tags: [] })
+      expect(store.linkSearch()).toEqual({ tags: [] })
+      // …while an empty URL array still falls through to storage, as it always has.
+      persist('tags-empty', ['api'])
+      expect(store.validateSearch({ tags: [] })).toEqual({ tags: ['api'] })
+    })
+
+    test('linkSearch carries the stored selection at CALL time', () => {
+      const store = createMultiSearchParamStore({ key: 'tags-j', param: 'tags', values: VALUES })
+      expect(store.linkSearch()).toEqual({ tags: [] })
+
+      persist('tags-j', ['design'])
+      expect(store.linkSearch()).toEqual({ tags: ['design'] })
+    })
   })
 })

package/src/router-tanstack/multi-search-param-store.ts

@@ -1,54 +1,34 @@
 /**
- * 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).
+ * @deprecated `createMultiSearchParamStore` is a thin wrapper over `createSearchStore`
+ * and is removed in 1.29.0. Replace it with `field.multi`:
  *
- * 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.
+ *     const store = createSearchStore({
+ *       key: 'article-tags',
+ *       fields: { tags: field.multi(['api', 'design', 'guide'], []) },
+ *     })
  *
- * Headless — no Mantine, no JSX. Same tier as `createSearchParamStore`.
+ * Two differences to know when you migrate:
  *
- * ## Encoding — array-native, not CSV
+ * - **An empty URL array is a VALUE in the new store**, not "absent". This wrapper keeps the old
+ *   rule (`?tags=[]` falls through to localStorage, then to `fallback`) so an existing consumer's
+ *   links behave identically; `field.multi` treats a cleared selection as a cleared selection.
+ * - `useStore` is localStorage-only. `store.field.tags.use()` reads the URL first (A8).
  *
- * 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.
+ * Encoding is unchanged and array-native: TanStack Router's default
+ * `stringifySearchWith(JSON.stringify, JSON.parse)` round-trips `{ tags: ['a', 'b'] }` losslessly,
+ * so there is no CSV step to intercept — a consumer wanting `?tags=a,b` configures router-global
+ * `parseSearch`/`stringifySearch` and this store keeps working untouched, because it hands the
+ * router an array rather than an encoding.
  *
- * ## Decoding — defensive and canonical
+ * Decoding is unchanged too: array-only input, allowlist-filtered, deduped, then re-sorted into
+ * `values` DECLARATION order — so `['api', 'design']` and `['design', 'api']` normalize to the same
+ * array, and one logical selection has one URL.
  *
- * 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,
- * })
+ * The four returned members (`validateSearch`, `useStore`, `readStored`, `linkSearch`), their
+ * signatures and the single-value localStorage envelope are preserved byte-for-byte.
  */
-
-import { createPersistedState, readPersistedValue } from '../state'
+import { createPersistedState, field } from '../state'
+import { buildSearchStore } from './search-store'
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -73,7 +53,7 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
   validateSearch: (search: Record<string, unknown>) => { [K in P]: readonly T[] }
   /**
    * 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). */
@@ -84,54 +64,43 @@ 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[] }
 }
 
 // ── Implementation ─────────────────────────────────────────────────────────
 
+/** @deprecated Use `createSearchStore` + `field.multi`. Removed in 1.29.0. */
 export function createMultiSearchParamStore<const T extends string, const P extends string>(
   opts: MultiSearchParamStoreOptions<T, P>,
 ): MultiSearchParamStore<T, P> {
   const version = opts.version ?? 1
   const fallback = opts.fallback ?? []
-  const allowed = new Set<string>(opts.values)
-
-  /** Array-only, allowlist-filtered, deduped, canonically re-sorted into `opts.values` order. */
-  const normalize = (raw: unknown): readonly T[] => {
-    if (!Array.isArray(raw)) return []
-    const present = new Set<T>()
-    for (const entry of raw) {
-      if (typeof entry === 'string' && allowed.has(entry)) present.add(entry as T)
-    }
-    return opts.values.filter((value) => present.has(value))
-  }
-
-  const readStored = (): readonly T[] | null => {
-    const raw = readPersistedValue(opts.key, version)
-    if (!Array.isArray(raw)) return null
-    return normalize(raw)
-  }
-
-  const linkSearch = (): { [K in P]: readonly T[] } => {
-    return { [opts.param]: readStored() ?? fallback } as { [K in P]: readonly T[] }
-  }
-
-  const validateSearch = (search: Record<string, unknown>): { [K in P]: readonly T[] } => {
-    const fromUrl = normalize(search[opts.param])
-    if (fromUrl.length > 0) {
-      return { [opts.param]: fromUrl } as { [K in P]: readonly T[] }
-    }
-    return { [opts.param]: readStored() ?? fallback } as { [K in P]: readonly T[] }
-  }
+  const store = buildSearchStore({
+    key: opts.key,
+    version,
+    fields: { [opts.param]: field.multi(opts.values, fallback) },
+    legacyValueField: opts.param,
+  })
 
-  const useStore = createPersistedState<readonly T[]>({
+  const persisted = createPersistedState<readonly T[]>({
     key: opts.key,
     version,
     initial: fallback,
   })
+  // A reader, like the single-value wrapper's — see the note there.
+  const useStore = (): readonly [readonly T[], (next: readonly T[]) => void] => {
+    store.markReaderWired()
+    return persisted()
+  }
 
-  return { validateSearch, useStore, readStored, linkSearch }
+  return {
+    validateSearch: (search) => store.validateSearch(search) as { [K in P]: readonly T[] },
+    useStore,
+    readStored: () =>
+      (store.readStored() as Record<string, readonly T[] | undefined>)[opts.param] ?? null,
+    linkSearch: () => store.linkSearch() as { [K in P]: readonly T[] },
+  }
 }

package/src/router-tanstack/search-param-store.ts

@@ -1,91 +1,33 @@
 /**
- * createSearchParamStore — bridge between TanStack Router URL search params and
- * basalt-ui's localStorage persistence.
+ * @deprecated `createSearchParamStore` is a thin wrapper over `createSearchStore` and is
+ * removed in 1.29.0. It can express exactly one closed string enum on one param; the store it
+ * delegates to expresses six field kinds, per-field lanes, and a range's three params.
  *
- * 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.
+ * Migration is mechanical:
  *
- * ## 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',
+ *     // before
+ *     const range = createSearchParamStore({
+ *       key: 'dashboard-range', param: 'range', values: ['1d', '7d', '30d'] as const, fallback: '30d',
  *     })
+ *     const [, persist] = range.useStore()          // localStorage only — never the URL
  *
- * **2. Route** — plug validateSearch into the parent layout route:
- *
- *     export const Route = createFileRoute('/dashboard')({
- *       validateSearch: dashboardRange.validateSearch,
- *       component: DashboardLayout,  // renders <DateFilter/> + <Outlet/>
+ *     // after
+ *     const dash = createSearchStore({
+ *       key: 'dashboard-range',
+ *       fields: { range: field.enum(['1d', '7d', '30d'], '30d') },
  *     })
+ *     const [value, set] = dash.field.range.use()    // reads the URL, writes both lanes
  *
- * **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:
+ * The two are NOT equivalent in the one way that matters: `useStore` reads localStorage, so a deep
+ * link `?range=7d` rendered `30d` (A8). `field.range.use()` reads the URL first. See
+ * `docs/CONTROLS-SPEC.md` §4 and `MIGRATING.md`.
  *
- *     // 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.
+ * What the wrapper preserves byte-for-byte, because `basalt-ui-obsidian` consumes it two hops
+ * downstream: the four returned members (`validateSearch`, `useStore`, `readStored`, `linkSearch`),
+ * their signatures, and the single-value localStorage envelope an existing browser already holds.
  */
-
-import { createPersistedState, readPersistedValue } from '../state'
+import { createPersistedState, field } from '../state'
+import { buildSearchStore } from './search-store'
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -110,7 +52,8 @@ export type SearchParamStore<T extends string, P extends string = string> = {
   validateSearch: (search: Record<string, unknown>) => { [K in P]: T }
   /**
    * 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). */
@@ -125,93 +68,33 @@ export type SearchParamStore<T extends string, P extends string = string> = {
   linkSearch: () => { [K in P]: T }
 }
 
-/**
- * Dev-only, once per store: the URL is pinning `fallback` while something else is persisted, and
- * neither reader has ever been called. That combination has exactly one realistic cause — a nav
- * link declaring the param as a literal — and it is invisible otherwise, because every individual
- * piece looks correct and the feature merely never remembers anything.
- *
- * Deliberately NOT a timer over "was this store ever read": that fires in every test that builds a
- * store, and it cannot say what to do about it. This fires only in the broken state, and names the
- * fix.
- */
-function warnLinkPinsFallback(input: {
-  key: string
-  param: string
-  urlValue: string
-  storedValue: string
-}): void {
-  const { key, param, urlValue, storedValue } = input
-  // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
-  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 — pass the store's own reader instead: " +
-      '`search: <store>.linkSearch`. (dev only)',
-  )
-}
-
 // ── Implementation ─────────────────────────────────────────────────────────
 
+/** @deprecated Use `createSearchStore` + `field.enum`. Removed in 1.29.0. */
 export function createSearchParamStore<const T extends string, const P extends string>(
   opts: SearchParamStoreOptions<T, P>,
 ): SearchParamStore<T, P> {
   const version = opts.version ?? 1
-
-  // `validateSearch` reads the store internally on every navigation, which says nothing about
-  // whether the CONSUMER wired a reader — only the two public readers below set this.
-  let readerWired = false
-  let warned = false
-
-  const read = (): T | null => {
-    const raw = readPersistedValue(opts.key, version)
-    if (typeof raw !== 'string') return null
-    if ((opts.values as readonly string[]).includes(raw)) return raw as T
-    return null
-  }
-
-  const readStored = (): T | null => {
-    readerWired = true
-    return read()
-  }
-
-  const linkSearch = (): { [K in P]: T } => {
-    readerWired = true
-    return { [opts.param]: (read() ?? opts.fallback) as T } as { [K in P]: T }
-  }
-
-  const validateSearch = (search: Record<string, unknown>): { [K in P]: T } => {
-    const raw = search[opts.param]
-    if (typeof raw === 'string' && (opts.values as readonly string[]).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 as T } as { [K in P]: T }
-    }
-    return { [opts.param]: (read() ?? opts.fallback) as T } as { [K in P]: T }
-  }
-
-  const useStore = createPersistedState<T>({
+  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<T>({ key: opts.key, version, initial: opts.fallback })
+  // `useStore` is a reader too. Without this, a consumer whose ONLY reader is `useStore()` — the
+  // documented wiring for this factory — would start seeing the pinned-link warning it never saw
+  // before, purely because the wrapper now delegates.
+  const useStore = (): readonly [T, (next: T) => void] => {
+    store.markReaderWired()
+    return persisted()
+  }
+
+  return {
+    validateSearch: (search) => store.validateSearch(search) as { [K in P]: T },
+    useStore,
+    readStored: () => (store.readStored() as Record<string, T | undefined>)[opts.param] ?? null,
+    linkSearch: () => store.linkSearch() as { [K in P]: T },
+  }
 }