basalt-ui 1.25.0 → 1.26.0

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

@@ -0,0 +1,380 @@
+/**
+ * `createSearchStore` — one factory over typed fields, replacing the enum-only
+ * `createSearchParamStore` / `createMultiSearchParamStore` pair.
+ *
+ * The URL is the truth; the localStorage mirror is a fallback UNDER it. Every field resolves the
+ * same way — URL ⊳ localStorage ⊳ fallback (C4) — and declares its lanes once, at definition.
+ *
+ * Ground truth for the placement/persistence law this implements: `docs/CONTROLS-SPEC.md` §4.
+ * What used to be a 100-line recipe in this module's sibling is that spec plus `agent/rules/
+ * basalt-state.md`; the API below is what those paragraphs were waiting for.
+ *
+ * Two behaviours worth knowing before reading the code:
+ *
+ * - **A deep link wins over the mirror.** `?range=7d` reads back `7d` even when localStorage says
+ *   `30d`. The enum-only pair could not do this: its reader hook was the localStorage state, so a
+ *   shared link opened on the wrong window (A8).
+ * - **A field with neither lane is in memory, not nowhere.** `{ url: false, persist: false }` is
+ *   the memory-only lane: session-scoped, shared across every mount of the store, gone on reload —
+ *   the same lane `createLocalStore` gives such a field, through the same store-core helper. It is
+ *   the honest home for a value a reader should not be handed back tomorrow.
+ * - **A write from outside the owning route persists only.** `use()`'s setter navigates only when
+ *   the matched route validates the param — detected by the param key being PRESENT in the current
+ *   search, which a route running this store's `validateSearch` always is (it returns every
+ *   URL-lane param unconditionally) and a foreign route is not. `validateSearch` then picks the
+ *   persisted value up on the next visit (A1). The honest limit of that detection: two DIFFERENT
+ *   stores using the same param name on overlapping routes read as one owner. Presence is what a
+ *   store can see without the router telling it which route declared what, and the alternative — a
+ *   context flag — would need a provider per store, which is the thing this API does not have.
+ *
+ * Headless — no Mantine, no JSX. Same tier as `useBasaltNav` and `useRouterBreadcrumbs`.
+ */
+import { useNavigate, useSearch } from '@tanstack/react-router'
+import { createStoreCore } from '../state'
+import type { AnyField, FieldHandle, SearchValues, StoreEntry, StoredValues } from '../state'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+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
+}
+
+/**
+ * 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] 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 — pass the store's own reader instead: " +
+      '`search: <store>.linkSearch`. (dev only)',
+  )
+}
+
+// ── Implementation ─────────────────────────────────────────────────────────
+
+/** Reads the merged search of every matched route, so a child or sibling needs no `from` (A3). */
+function useCurrentSearch(): Record<string, unknown> {
+  const search = useSearch({ strict: false }) as unknown
+  return typeof search === 'object' && search !== null ? (search as Record<string, unknown>) : {}
+}
+
+function describeValue(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+/**
+ * Dev-only, once per field: a `persist: false` field was written from a route that does not
+ * validate it, so the write had nowhere to go — no URL (the route owns no such param) and no mirror
+ * (the field opted out of one). Silence is the wrong answer here: every other lane combination does
+ * something, so a control that appears to work and changes nothing reads as a basalt bug.
+ */
+function warnWriteHasNowhereToGo(input: { key: string; name: string; param: string }): void {
+  const { key, name, param } = input
+  // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
+  console.warn(
+    `[basalt-ui] createSearchStore('${key}'): wrote field '${name}' from a route that does not ` +
+      `validate \`${param}\`, and the field is \`persist: false\` — 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)',
+  )
+}
+
+/**
+ * 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 memory-only lane: neither the URL nor the mirror, so the value lives in the store's own
+ * session-scoped external store (`StoreCore.memoryUse`) — the lane `createLocalStore` also uses. */
+function isMemoryLane(entry: StoreEntry): boolean {
+  return !entry.codec.lane.url && !entry.codec.lane.persist
+}
+
+/**
+ * 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 function buildSearchStore<const S extends Record<string, AnyField>>(
+  o: CreateSearchStoreOptions<S> & { legacyValueField?: string },
+): InternalSearchStore<S> {
+  const core = createStoreCore(o)
+
+  // `validateSearch` reads storage on every navigation, which says nothing about whether the
+  // CONSUMER wired a reader. Everything a consumer can read THROUGH sets this: `linkSearch`,
+  // `readStored`, and `field.<name>.use()` — the documented reader, and the one a page that never
+  // touches the other two uses exclusively. Missing it there made the pinned-link warning fire on
+  // correctly wired pages.
+  let readerWired = false
+  let warned = false
+  const markReaderWired = (): void => {
+    readerWired = true
+  }
+  const nowhereWarned = new Set<string>()
+
+  const flatten = (
+    search: Record<string, unknown> | null,
+    record: Record<string, unknown>,
+  ): Record<string, unknown> => {
+    const out: Record<string, unknown> = {}
+    for (const entry of core.urlEntries) {
+      Object.assign(out, entry.codec.toSearch(core.resolve(entry, search, record)))
+    }
+    return out
+  }
+
+  const maybeWarn = (raw: Record<string, unknown>, record: Record<string, unknown>): void => {
+    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
+      // Describe both sides as the URL spells them (a range prints `30d`, not its whole value
+      // object) — the message quotes a `search:` literal, so it has to be URL-shaped to be advice.
+      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: Record<string, unknown>): SearchValues<S> => {
+    const record = core.readRecord()
+    maybeWarn(raw, record)
+    return flatten(raw, record) as SearchValues<S>
+  }
+
+  const linkSearch = (): SearchValues<S> => {
+    readerWired = true
+    return flatten(null, core.readRecord()) as SearchValues<S>
+  }
+
+  const readStored = (): Partial<StoredValues<S>> => {
+    readerWired = true
+    return core.readStoredFlat() as Partial<StoredValues<S>>
+  }
+
+  const urlUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
+    const search = useCurrentSearch()
+    const navigate = useNavigate()
+    const [record, setRecord] = core.usePersistedRecord()
+    markReaderWired()
+    const value = core.resolve(entry, search, record)
+    // The matched route validates this field iff its primary param is present (see the module
+    // header). A foreign route gets the persist-only lane.
+    const validated = Object.hasOwn(search, entry.codec.primary)
+
+    return [
+      value,
+      (next: unknown) => {
+        if (validated) {
+          navigate({
+            to: '.',
+            search: (prev: Record<string, unknown>) => ({ ...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 })
+      },
+    ] as const
+  }
+
+  const localUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
+    const [record, setRecord] = core.usePersistedRecord()
+    markReaderWired()
+    return [
+      core.resolve(entry, null, record),
+      (next: unknown) => core.writeField(setRecord, entry.name, next),
+    ] as const
+  }
+
+  // Three lanes, decided once per field at definition: URL (+ optional mirror), mirror-only, and
+  // memory-only. The third used to be the one combination that dropped its write.
+  const memoryEntries = core.entries.filter(isMemoryLane)
+
+  const field = {} as { [K in keyof S]: FieldHandle<S[K]> }
+  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 as keyof S] = core.handle(entry, use) as unknown as FieldHandle<S[keyof S]>
+  }
+
+  const useValues = (): SearchValues<S> => {
+    const search = useCurrentSearch()
+    const [record] = core.usePersistedRecord()
+    markReaderWired()
+    return flatten(search, record) as SearchValues<S>
+  }
+
+  const useActiveCount = (): number => {
+    const search = useCurrentSearch()
+    const [record] = core.usePersistedRecord()
+    // A memory field is as much a filter as any other, so the `Filters (n)` pill has to count it —
+    // which means subscribing to the lane, or the count would go stale the moment one is written.
+    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 = (): (() => void) => {
+    const search = useCurrentSearch()
+    const navigate = useNavigate()
+    const [, setRecord] = core.usePersistedRecord()
+
+    return () => {
+      // Same "does this route own the field" gate as `urlUse` — only reset the params a foreign
+      // route's `validateSearch` actually validates, or the reset navigates there and pollutes it.
+      const validatedEntries = core.urlEntries.filter((entry) =>
+        Object.hasOwn(search, entry.codec.primary),
+      )
+      if (validatedEntries.length > 0) {
+        const patch: Record<string, unknown> = {}
+        for (const entry of validatedEntries) {
+          Object.assign(patch, entry.codec.toSearch(entry.codec.fallback))
+        }
+        navigate({
+          to: '.',
+          search: (prev: Record<string, unknown>) => ({ ...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: InternalSearchStore<S> = {
+    validateSearch,
+    linkSearch,
+    readStored,
+    field,
+    labels: (map) => {
+      core.setLabels(map as Record<string, Record<string, string> | undefined>)
+      return store
+    },
+    useValues,
+    useActiveCount,
+    useReset,
+    markReaderWired,
+  }
+
+  return store
+}
+
+/**
+ * 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 function createSearchStore<const S extends Record<string, AnyField>>(
+  o: CreateSearchStoreOptions<S>,
+): SearchStore<S> {
+  return buildSearchStore(o)
+}

package/src/router-tanstack/use-nav.test.tsx

@@ -0,0 +1,187 @@
+/**
+ * `useNav`'s active-resolution pass, under a REAL TanStack memory router — the half that cannot be
+ * tested headlessly (`matchRoute`/`useRouterState` both need a live router). The fixture below
+ * mirrors every collision shape the playground's own `demo/nav-model.tsx` actually has: a root `/`
+ * item, a `/dashboard` parent with three children, flat siblings, a same-path duplicate
+ * (`reports`/`components`, mirroring the playground's disabled-placeholder shape), and a
+ * search-bearing link (mirroring `dashboardFilters.linkSearch`-style destinations).
+ *
+ * The harness is modeled on `controls/controls.router.test.tsx`'s `mountPage`, narrowed to a
+ * headless probe: `useNav` renders no JSX itself (`./router-tanstack` is a no-JSX barrel), so the
+ * probe component only reads its return value into a sink — no `MantineProvider` needed.
+ */
+import { cleanup, render, waitFor } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router'
+import type { SidebarItem, SidebarSection } from '../nav/types'
+import type { AnyNavItem } from './nav'
+import { defineNav, navGroup } from './nav'
+import { useNav } from './use-nav'
+
+const NAV = defineNav({
+  groups: [
+    navGroup({ id: 'main', label: 'Main' }, [
+      { id: 'home', label: 'Home', link: { to: '/' } },
+      {
+        id: 'dashboard',
+        label: 'Dashboard',
+        // A store-backed destination (law C10's shape) — `search` rides the link like every
+        // other field; `matchOf` below never reads it, so it must not affect matching either.
+        link: { to: '/dashboard', search: { window: '30d' } },
+        children: [
+          { id: 'dashboard-sessions', label: 'Sessions', link: { to: '/dashboard/sessions' } },
+          { id: 'dashboard-traffic', label: 'Traffic', link: { to: '/dashboard/traffic' } },
+          { id: 'dashboard-revenue', label: 'Revenue', link: { to: '/dashboard/revenue' } },
+        ],
+      },
+      { id: 'mobile-nav-pill', label: 'Mobile nav pill', link: { to: '/mobile-nav-pill' } },
+      {
+        id: 'controls-mobile',
+        label: 'Controls (mobile)',
+        link: { to: '/controls-mobile' },
+      },
+      { id: 'components', label: 'Components', link: { to: '/components' } },
+      { id: 'charts-page', label: 'Charts', link: { to: '/charts' } },
+      // The playground's `reports` shape: a disabled placeholder that deliberately borrows an
+      // already-covered route rather than inventing one. Declared AFTER `components`, so the
+      // definition-order tie-break keeps `components` the winner at `/components`.
+      { id: 'reports', label: 'Reports', disabled: true, link: { to: '/components' } },
+    ]),
+  ],
+})
+
+const ROUTE_PATHS = [
+  '/',
+  '/dashboard',
+  '/dashboard/sessions',
+  '/dashboard/traffic',
+  '/dashboard/revenue',
+  '/mobile-nav-pill',
+  '/controls-mobile',
+  '/components',
+  '/charts',
+]
+
+type NavProbeOpts = { isActive?: (item: AnyNavItem) => boolean }
+type NavResult = { sections: SidebarSection[] }
+type Sink = { current: NavResult | null }
+
+/** Depth-first flatten of the rendered `SidebarSection[]` — the same shape every downstream reader
+ * (the sidebar, the mobile bar, the breadcrumb) walks. */
+function flattenItems(sections: SidebarSection[]): SidebarItem[] {
+  const out: SidebarItem[] = []
+  const walk = (items: SidebarItem[]): void => {
+    for (const item of items) {
+      out.push(item)
+      if (item.children) walk(item.children)
+    }
+  }
+  for (const section of sections) walk(section.items)
+  return out
+}
+
+async function mountNav(entry: string, opts?: NavProbeOpts): Promise<Sink> {
+  const sink: Sink = { current: null }
+
+  function NavProbe(): ReactNode {
+    const nav = useNav(NAV, opts)
+    sink.current = { sections: nav.sections }
+    return null
+  }
+
+  const rootRoute = createRootRoute({
+    component: () => (
+      <>
+        <NavProbe />
+        <Outlet />
+      </>
+    ),
+  })
+  const children = ROUTE_PATHS.map((path) =>
+    createRoute({ getParentRoute: () => rootRoute, path, component: () => null }),
+  )
+  const router = createRouter({
+    routeTree: rootRoute.addChildren(children),
+    history: createMemoryHistory({ initialEntries: [entry] }),
+  })
+
+  render(<RouterProvider router={router} />)
+  await waitFor(() => {
+    expect(router.state.status).toBe('idle')
+  })
+  return sink
+}
+
+describe('useNav — exclusivity', () => {
+  test('exactly one row is active at every route in the definition', async () => {
+    for (const path of ROUTE_PATHS) {
+      const sink = await mountNav(path)
+      const items = flattenItems(sink.current!.sections)
+      const activeCount = items.filter((item) => item.active).length
+      expect(activeCount).toBe(1)
+      cleanup()
+    }
+  })
+
+  test('the deepest match wins — a child route does not also light its parent', async () => {
+    const sink = await mountNav('/dashboard/sessions')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    const sessions = items.find((item) => item.key === 'dashboard-sessions')
+    expect(dashboard?.active).toBe(false)
+    expect(sessions?.active).toBe(true)
+  })
+
+  test('the parent of the active row is an ancestor, not active', async () => {
+    const sink = await mountNav('/dashboard/sessions')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    expect(dashboard?.ancestor).toBe(true)
+    expect(dashboard?.active).toBe(false)
+  })
+
+  test('a same-path duplicate destination is neither active nor an ancestor', async () => {
+    const sink = await mountNav('/components')
+    const items = flattenItems(sink.current!.sections)
+    const components = items.find((item) => item.key === 'components')
+    const reports = items.find((item) => item.key === 'reports')
+    expect(components?.active).toBe(true)
+    expect(reports?.active).toBe(false)
+    expect(reports?.ancestor).toBeFalsy()
+  })
+
+  test("'/' stays exact — the root never lights on a nested route", async () => {
+    const sink = await mountNav('/dashboard')
+    const items = flattenItems(sink.current!.sections)
+    const home = items.find((item) => item.key === 'home')
+    expect(home?.active).toBe(false)
+    expect(home?.ancestor).toBeFalsy()
+  })
+
+  test('an item whose exact route is never visited still lights on a descendant route', async () => {
+    // `/dashboard` itself is never the visited entry in this test — only its descendant is —
+    // proving the fix kept `fuzzy: true` as the default rather than flipping every item to exact.
+    const sink = await mountNav('/dashboard/traffic')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    expect(dashboard?.ancestor).toBe(true)
+    expect(dashboard?.active).toBe(false)
+  })
+
+  test('an isActive override cannot light two rows either', async () => {
+    const sink = await mountNav('/', {
+      isActive: (item) => item.id === 'components' || item.id === 'charts-page',
+    })
+    const items = flattenItems(sink.current!.sections)
+    const activeCount = items.filter((item) => item.active).length
+    expect(activeCount).toBe(1)
+  })
+})