basalt-ui 1.26.0 → 1.28.0

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

@@ -30,8 +30,9 @@
  * 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'
+import { createStoreCore } from '../state/fields'
+import type { FieldWrite, StoreEntry } from '../state/fields'
+import type { AnyField, FieldHandle, FieldSetOptions, SearchValues, StoredValues } from '../state'
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -67,7 +68,10 @@ export type SearchStore<S extends Record<string, AnyField>> = {
   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. */
+  /**
+   * Returns every field to its fallback: one navigate, one storage write. The mirror is UNSET
+   * rather than written — see `FieldHandle.clear()` for why writing the fallback pins a thunk.
+   */
   useReset: () => () => void
 }
 
@@ -129,6 +133,48 @@ function warnWriteHasNowhereToGo(input: { key: string; name: string; param: stri
   )
 }
 
+/**
+ * Dev-only, once per param: a `patch` named a search param ANOTHER field of the same store owns.
+ * The navigate would put it in the URL while the store's own write path never touched the mirror,
+ * so the next paramless visit and every `linkSearch` link resolve the OLD value — the URL and the
+ * mirror disagree from that click on, and nothing looks broken until a reader shares a link.
+ *
+ * Thrown in dev rather than warned: the call is a mistake with a one-line fix (write the other
+ * field through its own setter), and the damage is silent. Production keeps the write — a thrown
+ * error there would take a page down over a stale param — and logs it once.
+ */
+function patchOwnsFieldMessage(input: {
+  key: string
+  name: string
+  owner: string
+  param: string
+}): string {
+  const { key, name, owner, param } = input
+  return (
+    `basalt-ui: createSearchStore('${key}'): set('${name}', …, { patch }) carries \`${param}\`, ` +
+    `which this store's field '${owner}' owns — the URL would take it while the localStorage ` +
+    'mirror kept the old value, so the next paramless visit and every `linkSearch` link disagree ' +
+    `with the page the write happened on. Write it through \`field.${owner}.use()[1]\` instead; ` +
+    'a `patch` is for keys the store does NOT own.'
+  )
+}
+
+/**
+ * Dev-only, once per field: a patched write from a route that does not validate the field. The
+ * write persists (A1), but the patch has no navigate to merge into and is dropped — the one case
+ * where half of a two-part write silently disappears.
+ */
+function warnPatchDropped(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}' with a \`patch\` from a route ` +
+      `that does not validate \`${param}\` — the field's value persisted (A1), but the patch was ` +
+      'DROPPED: there is no navigate to merge it into. Render the control on the route wired to ' +
+      '`validateSearch`, or apply that sibling param on the route that owns 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
@@ -140,6 +186,25 @@ export type InternalSearchStore<S extends Record<string, AnyField>> = SearchStor
   markReaderWired: () => void
 }
 
+/**
+ * A thunk fallback belongs to the LOCAL and MEMORY lanes only. On the URL lane `validateSearch`
+ * would evaluate it on every navigation and write the result into the URL, so a deep link would
+ * carry a value nobody picked and two visits a second apart would disagree. Thrown at definition
+ * rather than warned at read time: the field set is static, so there is no run in which this is
+ * anything but a mistake.
+ */
+function assertNoLazyUrlFallback(key: string, fields: Record<string, AnyField>): void {
+  for (const [name, f] of Object.entries(fields)) {
+    if (typeof f.fallback !== 'function' || !f.lane.url) continue
+    throw new Error(
+      `basalt-ui: createSearchStore('${key}'): field '${name}' has a thunk fallback on the URL ` +
+        'lane — `validateSearch` would evaluate it on every navigation and pin the result into the ' +
+        'URL. Pass a value instead, or move the field off the URL lane (`{ url: false }`, or ' +
+        '`createLocalStore`), where a lazy fallback is resolved per read.',
+    )
+  }
+}
+
 /** 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 {
@@ -154,6 +219,7 @@ function isMemoryLane(entry: StoreEntry): boolean {
 export function buildSearchStore<const S extends Record<string, AnyField>>(
   o: CreateSearchStoreOptions<S> & { legacyValueField?: string },
 ): InternalSearchStore<S> {
+  assertNoLazyUrlFallback(o.key, o.fields)
   const core = createStoreCore(o)
 
   // `validateSearch` reads storage on every navigation, which says nothing about whether the
@@ -167,6 +233,39 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
     readerWired = true
   }
   const nowhereWarned = new Set<string>()
+  const patchDroppedWarned = new Set<string>()
+  const patchOwnerLogged = new Set<string>()
+
+  /** Every URL param this store owns, mapped to the field that owns it — what a `patch` may not name. */
+  const paramOwners = new Map<string, string>()
+  for (const entry of core.urlEntries) {
+    for (const param of entry.codec.params) paramOwners.set(param, entry.name)
+  }
+  const persistedNames = new Set(
+    core.entries.filter((entry) => entry.codec.lane.persist).map((entry) => entry.name),
+  )
+
+  /**
+   * The URL lane's `clear()` needs a `navigate`, which only exists inside a render. Each render of
+   * `urlUse` therefore leaves the navigate its mount would use here, keyed by field — so `clear()`
+   * from an event handler on that mount navigates exactly as its setter would, and a field no mount
+   * has read falls back to clearing the mirror alone.
+   */
+  const urlClear = new Map<string, () => void>()
+
+  const assertPatchNotOwned = (entry: StoreEntry, patch: Record<string, unknown>): void => {
+    for (const param of Object.keys(patch)) {
+      const owner = paramOwners.get(param)
+      // The field's OWN params are harmless: its `toSearch` is spread after the patch and wins.
+      if (owner === undefined || entry.codec.params.includes(param)) continue
+      const message = patchOwnsFieldMessage({ key: o.key, name: entry.name, owner, param })
+      if (process.env['NODE_ENV'] !== 'production') throw new Error(message)
+      if (patchOwnerLogged.has(param)) continue
+      patchOwnerLogged.add(param)
+      // oxlint-disable-next-line no-console -- production keeps the write; the log is the record
+      console.error(message)
+    }
+  }
 
   const flatten = (
     search: Record<string, unknown> | null,
@@ -215,7 +314,7 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
     return core.readStoredFlat() as Partial<StoredValues<S>>
   }
 
-  const urlUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
+  const urlUse = (entry: StoreEntry) => (): readonly [unknown, FieldWrite] => {
     const search = useCurrentSearch()
     const navigate = useNavigate()
     const [record, setRecord] = core.usePersistedRecord()
@@ -224,14 +323,45 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
     // 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)
+    urlClear.set(entry.name, () => {
+      if (!validated) return
+      navigate({
+        to: '.',
+        search: (prev: Record<string, unknown>) => ({
+          ...prev,
+          ...entry.codec.toSearch(entry.codec.fallback),
+        }),
+        replace: true,
+        resetScroll: false,
+      })
+    })
 
     return [
       value,
-      (next: unknown) => {
+      (next: unknown, opts?: FieldSetOptions) => {
+        const patch = opts?.patch
+        if (patch !== undefined && Object.keys(patch).length > 0) {
+          assertPatchNotOwned(entry, patch)
+          if (
+            !validated &&
+            !patchDroppedWarned.has(entry.name) &&
+            process.env['NODE_ENV'] !== 'production'
+          ) {
+            patchDroppedWarned.add(entry.name)
+            warnPatchDropped({ key: o.key, name: entry.name, param: entry.codec.primary })
+          }
+        }
         if (validated) {
           navigate({
             to: '.',
-            search: (prev: Record<string, unknown>) => ({ ...prev, ...entry.codec.toSearch(next) }),
+            // `patch` FIRST, the field's own params last: a patch is for keys the store does not
+            // own (clearing a sibling `detailDate` with `undefined`), so it must never be able to
+            // overwrite the value this very call is setting.
+            search: (prev: Record<string, unknown>) => ({
+              ...prev,
+              ...opts?.patch,
+              ...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
@@ -252,7 +382,9 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
     ] as const
   }
 
-  const localUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
+  // No `patch` here or in the memory lane: neither navigates, so there is no search object to merge
+  // into and nothing to silently half-apply.
+  const localUse = (entry: StoreEntry) => (): readonly [unknown, FieldWrite] => {
     const [record, setRecord] = core.usePersistedRecord()
     markReaderWired()
     return [
@@ -265,6 +397,19 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
   // memory-only. The third used to be the one combination that dropped its write.
   const memoryEntries = core.entries.filter(isMemoryLane)
 
+  /**
+   * Unsetting one field, per lane: drop the mirror key (never write the fallback — a thunk fallback
+   * resolved into localStorage is a value nobody chose), drop the memory value, and on the URL lane
+   * navigate back to the fallback params through the last render of `use()`.
+   */
+  const clearFor = (entry: StoreEntry) => (): void => {
+    if (entry.codec.lane.persist) core.clearField(entry.name)
+    else if (!entry.codec.lane.url) core.clearMemory(entry.name)
+    if (!entry.codec.lane.url) return
+    const clearUrl = urlClear.get(entry.name)
+    if (clearUrl !== undefined) clearUrl()
+  }
+
   const field = {} as { [K in keyof S]: FieldHandle<S[K]> }
   for (const entry of core.entries) {
     const use = entry.codec.lane.url
@@ -272,7 +417,11 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
       : 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]>
+    field[entry.name as keyof S] = core.handle(
+      entry,
+      use,
+      clearFor(entry),
+    ) as unknown as FieldHandle<S[keyof S]>
   }
 
   const useValues = (): SearchValues<S> => {
@@ -325,11 +474,21 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
       }
       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
+      // Reset means UNSET, not "write the fallback": `codec.fallback` is the RESOLVED value, so a
+      // thunk (`() => todayIso()`) would be pinned into the mirror by the very act of resetting and
+      // read back tomorrow as a choice nobody made. Deleting the key lets `resolve` fall through to
+      // the live fallback — which is what `resetMemory` above has always done for the memory lane.
+      const record = core.readRecord()
+      const next: Record<string, unknown> = {}
+      let dropped = false
+      for (const [name, value] of Object.entries(record)) {
+        if (persistedNames.has(name)) {
+          dropped = true
+          continue
+        }
+        next[name] = value
       }
-      setRecord(next)
+      if (dropped) setRecord(next)
     }
   }
 

package/src/router-tanstack/use-nav.ts

@@ -113,26 +113,31 @@ export function useNav<
       // chain: the widened `AnyNavLink['search']` is `unknown`, which `LinkComponentProps` rejects.
       // The consumer gets zero casts, which is the point.
       //
-      // `activeOptions: { exact: true }` is what makes `resolveState` above the ONLY authority on
-      // active, and it is not a preference — a `Link` computes its own `isActive` (default
-      // `activeOptions.exact: false`, i.e. prefix) and spreads `{ 'data-status': 'active',
-      // 'aria-current': 'page' }` LAST, after `activeProps` and after every caller prop
-      // (`@tanstack/react-router/dist/esm/link.js` — `...isActive && STATIC_ACTIVE_PROPS` is the
-      // final entry of the returned object). So `aria-current` cannot be overridden from outside;
-      // the only lever is `isActive` itself. Left at its default, the router re-derived the exact
-      // fuzzy match this resolver exists to replace, and at `/dashboard/sessions` BOTH the parent
-      // and the child anchor carried `aria-current="page"` even with basalt's own model marking one
-      // of them an ancestor — verified in Chrome, and the reason the first attempt at this fix
-      // measured as no fix at all.
+      // `activeOptions: { exact: true, includeSearch: true }` is what makes `resolveState` above
+      // the ONLY authority on active, and it is not a preference — a `Link` computes its own
+      // `isActive` (default `activeOptions.exact: false`, i.e. prefix) and spreads
+      // `{ 'data-status': 'active', 'aria-current': 'page' }` LAST, after `activeProps` and after
+      // every caller prop (`@tanstack/react-router/dist/esm/link.js` — `...isActive &&
+      // STATIC_ACTIVE_PROPS` is the final entry of the returned object). So `aria-current` cannot
+      // be overridden from outside; the only lever is `isActive` itself. Left at its default, the
+      // router re-derived the exact fuzzy match this resolver exists to replace, and at
+      // `/dashboard/sessions` BOTH the parent and the child anchor carried `aria-current="page"`
+      // even with basalt's own model marking one of them an ancestor — verified in Chrome, and the
+      // reason the first attempt at this fix measured as no fix at all. `includeSearch` already
+      // defaults to `true` upstream; naming it here is belt-and-braces so a future default change
+      // cannot silently reopen the gap.
       //
       // Exact here does NOT narrow basalt's own law. `resolveState` still matches fuzzily and still
       // lights an item whose exact route is never visited; that item is simply named by the
       // `aria-current` `app-sidebar.tsx` stamps itself, which survives because the router's spread
-      // is conditional on ITS `isActive` being true.
+      // is conditional on ITS `isActive` being true. The CSS side no longer treats `aria-current`
+      // as a style hook either (`theme/nav-link.module.css`, `shell/app-sidebar.module.css`), so
+      // `use-nav`'s single `data-active` winner is the one visual authority even if the router's
+      // own `isActive` ever disagreed.
       const Anchor: NavAnchor = (props) =>
         createElement(Link as ElementType, {
           ...item.link,
-          activeOptions: { exact: true },
+          activeOptions: { exact: true, includeSearch: true },
           ...props,
         })
 

package/src/section/index.ts

@@ -1 +1 @@
-export { Section, type SectionProps } from './section'
+export { Section, type SectionProps, type SectionSlot } from './section'

package/src/section/section.module.css

@@ -22,6 +22,17 @@
   gap: var(--vx-space-stack-md, 0.75rem);
 }
 
+/*
+ * `group` tier (an aside/inspector Section): zero gap between children. `PanelRow`s already own
+ * their own vertical rhythm — `--vx-space-row-inset-y` (6px) plus the `.row + .row` hairline — so
+ * stacking the 12px `stack-md` gap ON TOP made a one-line row's pitch 55px with the hairline sitting
+ * 33/22 off-centre in it. At gap 0 the pitch is 43px and the rule is centred (Trellis ≈29, Quiver
+ * ≈33, the sidebar's own rows 33) — no negative margins, the gap simply isn't there to fight.
+ */
+.root[data-tier='group'] .body {
+  gap: 0;
+}
+
 /*
  * `summary` — the always-visible row under the header. No border, no background (the Section owns
  * neither); it is a plain flow row, so a consumer's `Group` of stats or one line of `Text` lands