basalt-ui 1.26.0 → 1.27.0

package/src/index.ts

@@ -99,9 +99,11 @@ export {
   type AnyField,
   type BooleanField,
   type EnumField,
+  type FieldFallback,
   type FieldHandle,
   type FieldLane,
   type FieldOption,
+  type FieldSetOptions,
   type FieldValue,
   type MultiField,
   type NumberField,
@@ -109,6 +111,8 @@ export {
   type RangeParams,
   type RangePresets,
   type RangeValue,
+  type RangeWindow,
+  type RangeWindows,
   type ResolvedLane,
   type SearchValues,
   type StoredValues,
@@ -126,6 +130,7 @@ export {
   DeltaBadge,
   type DeltaBadgeProps,
   StatCard,
+  type StatCardBreakdownRow,
   type StatCardProps,
   type StatCardTone,
   EmptyState,

package/src/router-tanstack/field.ts

@@ -14,15 +14,19 @@ export type {
   AnyField,
   BooleanField,
   EnumField,
+  FieldFallback,
   FieldHandle,
   FieldLane,
   FieldOption,
+  FieldSetOptions,
   FieldValue,
   MultiField,
   NumberField,
   RangeField,
   RangeParams,
   RangePresets,
+  RangeWindow,
+  RangeWindows,
   RangeValue,
   ResolvedLane,
   SearchValues,

package/src/router-tanstack/index.ts

@@ -14,9 +14,11 @@ export type {
   AnyField,
   BooleanField,
   EnumField,
+  FieldFallback,
   FieldHandle,
   FieldLane,
   FieldOption,
+  FieldSetOptions,
   FieldValue,
   MultiField,
   NumberField,
@@ -24,6 +26,8 @@ export type {
   RangeParams,
   RangePresets,
   RangeValue,
+  RangeWindow,
+  RangeWindows,
   ResolvedLane,
   SearchValues,
   StoredValues,

package/src/router-tanstack/search-store.router.test.tsx

@@ -17,11 +17,11 @@ import {
   createRoute,
   createRouter,
 } from '@tanstack/react-router'
-import type { AnyField, FieldHandle } from '../state'
+import type { AnyField, FieldHandle, FieldSetOptions } from '../state'
 import { field } from './field'
 import { createSearchStore } from './search-store'
 
-type Probe = { value: unknown; set: (next: unknown) => void }
+type Probe = { value: unknown; set: (next: unknown, opts?: FieldSetOptions) => void }
 type Sink = { current: Probe | null }
 
 function sink(): Sink {
@@ -32,7 +32,7 @@ function sink(): Sink {
 function fieldProbe<F extends AnyField>(handle: FieldHandle<F>, into: Sink) {
   return function FieldProbe(): ReactNode {
     const [value, set] = handle.use()
-    into.current = { value, set: set as (next: unknown) => void }
+    into.current = { value, set: set as Probe['set'] }
     return null
   }
 }
@@ -419,7 +419,7 @@ describe('store hooks', () => {
     expect(count).toBe(2)
   })
 
-  test('useReset returns every field to its fallback in ONE navigate call', async () => {
+  test('useReset returns every field to its fallback in ONE navigate call, UNSETTING the mirror', async () => {
     const store = createSearchStore({
       key: 'r-reset',
       fields: {
@@ -451,14 +451,79 @@ describe('store hooks', () => {
     })
     expect(currentSearch(router)['compare']).toBe('none')
     expect(currentSearch(router)['from']).toBeUndefined()
-    expect(storedRecord('r-reset')).toEqual({
-      range: { preset: '30d' },
-      compare: 'none',
-      compact: false,
-    })
+    // Reset means UNSET: the persisted keys are DELETED, not overwritten with the resolved
+    // fallback — writing it would pin a thunk fallback into the mirror (see the lazy-fallback test
+    // below) and leave the field counted as active tomorrow.
+    expect(storedRecord('r-reset')).toEqual({})
     navigate.mockRestore()
   })
 
+  test('useReset UNSETS a thunk fallback rather than pinning it into the mirror', async () => {
+    let today = '2026-08-27'
+    const store = createSearchStore({
+      key: 'r-lazy-reset',
+      fields: {
+        range: field.enum(['1d', '7d'], '7d'),
+        since: field.string({ fallback: () => today }, { url: false }),
+      },
+    })
+    persist('r-lazy-reset', { since: '2026-01-01' })
+    const probe = sink()
+    let reset: (() => void) | null = null
+    let count = -1
+
+    await mountApp({
+      validateSearch: store.validateSearch,
+      entry: '/dashboard',
+      Dashboard: () => {
+        reset = store.useReset()
+        count = store.useActiveCount()
+        return fieldProbe(store.field.since, probe)()
+      },
+    })
+    expect(probe.current?.value).toBe('2026-01-01')
+
+    await act(async () => {
+      reset?.()
+    })
+
+    expect(probe.current?.value).toBe('2026-08-27')
+    expect(storedRecord('r-lazy-reset')).toEqual({})
+    expect(count).toBe(0)
+
+    // The next day the same field reads TODAY, not the day the reset was pressed — which is the
+    // whole point of a thunk fallback, and what writing the resolved value took away.
+    today = '2026-08-28'
+    expect(store.field.since.fallback).toBe('2026-08-28')
+    expect(store.readStored()['since']).toBeUndefined()
+  })
+
+  test('field.clear() returns the URL param to the fallback and drops the mirror key', async () => {
+    const store = createSearchStore({
+      key: 'r-clear-url',
+      fields: { range: field.enum(['1d', '7d', '30d'], '7d') },
+    })
+    persist('r-clear-url', { range: '30d' })
+    const probe = sink()
+
+    const router = await mountApp({
+      validateSearch: store.validateSearch,
+      entry: '/dashboard?range=30d',
+      Dashboard: fieldProbe(store.field.range, probe),
+    })
+    expect(probe.current?.value).toBe('30d')
+
+    await act(async () => {
+      store.field.range.clear()
+    })
+
+    await waitFor(() => {
+      expect(currentSearch(router)['range']).toBe('7d')
+    })
+    expect(storedRecord('r-clear-url')).toEqual({})
+    expect(probe.current?.value).toBe('7d')
+  })
+
   test('useReset from a FOREIGN route persists only — it never navigates (A1)', async () => {
     const store = createSearchStore({
       key: 'r-reset-foreign',
@@ -636,8 +701,31 @@ describe('the memory-only lane — url: false, persist: false', () => {
     })
     expect(probe.current?.value).toBe('a')
     expect(count).toBe(0)
-    // `useReset` wrote the MIRROR for the persisted field beside it; the memory field is not in it.
-    expect(storedRecord('r-memory')).toEqual({ range: '7d' })
+    // Nothing was ever persisted, so the reset had no key to drop and wrote no envelope — the
+    // mirror only ever holds values a control produced.
+    expect(storedRecord('r-memory')).toBeNull()
+  })
+
+  test('field.clear() drops the memory value, and only that one', async () => {
+    const store = memoryStore()
+    const probe = sink()
+
+    await mountApp({
+      validateSearch: store.validateSearch,
+      entry: '/dashboard',
+      Dashboard: fieldProbe(store.field.scratch, probe),
+    })
+
+    await act(async () => {
+      probe.current?.set('c')
+    })
+    expect(probe.current?.value).toBe('c')
+
+    await act(async () => {
+      store.field.scratch.clear()
+    })
+    expect(probe.current?.value).toBe('a')
+    expect(storedRecord('r-memory')).toBeNull()
   })
 
   test('two mounts of the same field see one value', async () => {
@@ -659,3 +747,136 @@ describe('the memory-only lane — url: false, persist: false', () => {
     expect(b.current?.value).toBe('b')
   })
 })
+
+/**
+ * `set(next, { patch })` — the sibling params a page owns and the store does not. Clearing one used
+ * to need a second `navigate` beside the setter, which either raced the field's own write or left
+ * two history entries where the reader made one change.
+ */
+describe('use() — a patched write', () => {
+  const store = createSearchStore({
+    key: 'r-patch',
+    fields: { tab: field.enum(['overview', 'detail'], 'overview') },
+  })
+
+  /** The store's params PLUS one the page owns — the shape a real route composes. */
+  const validateSearch = (raw: Record<string, unknown>): Record<string, unknown> => ({
+    ...store.validateSearch(raw),
+    detailDate: typeof raw['detailDate'] === 'string' ? raw['detailDate'] : undefined,
+  })
+
+  test('clears a sibling param the store does not own, in the same navigate', async () => {
+    const probe = sink()
+    const router = await mountApp({
+      validateSearch,
+      entry: '/dashboard?tab=detail&detailDate=2026-03-01',
+      Dashboard: fieldProbe(store.field.tab, probe),
+    })
+    expect(currentSearch(router)['detailDate']).toBe('2026-03-01')
+
+    await act(async () => {
+      probe.current?.set('overview', { patch: { detailDate: undefined } })
+    })
+
+    await waitFor(() => {
+      expect(currentSearch(router)['tab']).toBe('overview')
+    })
+    expect(currentSearch(router)['detailDate']).toBeUndefined()
+    expect(probe.current?.value).toBe('overview')
+    // The field's own lane is untouched by the patch — the write still mirrors.
+    expect(storedRecord('r-patch')).toEqual({ tab: 'overview' })
+  })
+
+  test('a patch cannot overwrite the value being set', async () => {
+    const probe = sink()
+    const router = await mountApp({
+      validateSearch,
+      entry: '/dashboard?tab=overview',
+      Dashboard: fieldProbe(store.field.tab, probe),
+    })
+
+    await act(async () => {
+      probe.current?.set('detail', { patch: { tab: 'overview', detailDate: '2026-04-01' } })
+    })
+
+    await waitFor(() => {
+      expect(currentSearch(router)['tab']).toBe('detail')
+    })
+    expect(currentSearch(router)['detailDate']).toBe('2026-04-01')
+  })
+
+  test('a patch naming a param ANOTHER field owns is refused, not silently desynced', async () => {
+    const twoFields = createSearchStore({
+      key: 'r-patch-owned',
+      fields: {
+        tab: field.enum(['overview', 'detail'], 'overview'),
+        range: field.enum(['7d', '30d'], '30d'),
+      },
+    })
+    const probe = sink()
+    const router = await mountApp({
+      validateSearch: twoFields.validateSearch,
+      entry: '/dashboard',
+      Dashboard: fieldProbe(twoFields.field.tab, probe),
+    })
+
+    // The URL would take `range=7d` while the mirror kept `30d`, so the next paramless visit and
+    // every `linkSearch` link would disagree with the page the write happened on.
+    expect(() => {
+      probe.current?.set('detail', { patch: { range: '7d' } })
+    }).toThrow(/field 'range' owns/)
+    expect(currentSearch(router)['tab']).toBe('overview')
+    expect(currentSearch(router)['range']).toBe('30d')
+  })
+
+  test('a patched write from a FOREIGN route drops the patch, and warns once', async () => {
+    const store = createSearchStore({
+      key: 'r-patch-foreign',
+      fields: { tab: field.enum(['overview', 'detail'], 'overview') },
+    })
+    const probe = sink()
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+
+    const router = await mountApp({
+      validateSearch: store.validateSearch,
+      entry: '/other?detailDate=2026-03-01',
+      Other: fieldProbe(store.field.tab, probe),
+    })
+
+    await act(async () => {
+      probe.current?.set('detail', { patch: { detailDate: undefined } })
+    })
+
+    // The write persisted (A1); the patch had no navigate to merge into and is gone.
+    expect(storedRecord('r-patch-foreign')).toEqual({ tab: 'detail' })
+    expect(currentSearch(router)['detailDate']).toBe('2026-03-01')
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      probe.current?.set('overview', { patch: { detailDate: undefined } })
+    })
+    expect(warn).toHaveBeenCalledTimes(1)
+    warn.mockRestore()
+  })
+
+  test('a field with no URL lane has no navigate to patch, and does not make one', async () => {
+    const local = createSearchStore({
+      key: 'r-patch-local',
+      fields: { compact: field.boolean(false, { url: false }) },
+    })
+    const probe = sink()
+    const router = await mountApp({
+      validateSearch,
+      entry: '/dashboard?tab=overview',
+      Dashboard: fieldProbe(local.field.compact, probe),
+    })
+
+    await act(async () => {
+      probe.current?.set(true, { patch: { detailDate: '2026-05-01' } })
+    })
+
+    expect(probe.current?.value).toBe(true)
+    expect(currentSearch(router)['detailDate']).toBeUndefined()
+    expect(storedRecord('r-patch-local')).toEqual({ compact: true })
+  })
+})

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

@@ -396,6 +396,78 @@ describe('the handle, outside React', () => {
     expect(store.field.range.toWindow({ preset: 'custom' })).toEqual({ window: 'custom' })
   })
 
+  test('a preset declared with a `window` resolver projects to `{ from, to }`', () => {
+    // The derived presets three consumers hand-rolled beside the store (`3m`, `ytd`): one preset in
+    // the URL, two dates at the API boundary, no `presetToParams` in the page.
+    const seen: Date[] = []
+    const store = createSearchStore({
+      key: 'k-window-resolver',
+      fields: {
+        range: field.range({
+          presets: ['7d', '3m', 'ytd'],
+          fallback: '7d',
+          custom: true,
+          window: {
+            '3m': (now) => {
+              seen.push(now)
+              return { from: iso(addMonths(now, -3)), to: iso(now) }
+            },
+            ytd: (now) => ({ from: `${now.getUTCFullYear()}-01-01`, to: iso(now) }),
+          },
+        }),
+      },
+    })
+
+    const now = new Date()
+    expect(store.field.range.toWindow({ preset: '3m' })).toEqual({
+      from: iso(addMonths(now, -3)),
+      to: iso(now),
+    })
+    expect(store.field.range.toWindow({ preset: 'ytd' })).toEqual({
+      from: `${now.getUTCFullYear()}-01-01`,
+      to: iso(now),
+    })
+    // Resolved at CALL time, with the current date — never captured at definition.
+    expect(seen[0] instanceof Date).toBe(true)
+
+    // A preset WITHOUT a resolver is untouched, in the same field.
+    expect(store.field.range.toWindow({ preset: '7d' })).toEqual({ window: '7d' })
+    // And a custom window still wins over any resolver.
+    expect(
+      store.field.range.toWindow({ preset: 'custom', from: '2026-03-01', to: '2026-03-14' }),
+    ).toEqual({ from: '2026-03-01', to: '2026-03-14' })
+  })
+
+  test('a resolver changes nothing about the URL — the preset is still what is stored', () => {
+    const store = createSearchStore({
+      key: 'k-window-url',
+      fields: {
+        range: field.range({
+          presets: ['7d', '3m'],
+          fallback: '7d',
+          window: { '3m': () => ({ from: '2026-01-01', to: '2026-04-01' }) },
+        }),
+      },
+    })
+    expect(store.validateSearch({ range: '3m' })).toEqual({
+      range: '3m',
+      from: undefined,
+      to: undefined,
+    })
+    expect(store.field.range.toWindow({ preset: '3m' })).toEqual({
+      from: '2026-01-01',
+      to: '2026-04-01',
+    })
+  })
+
+  test('a preset named like an Object.prototype member is not a resolver', () => {
+    const store = createSearchStore({
+      key: 'k-window-proto',
+      fields: { range: field.range({ presets: ['toString', '7d'], fallback: '7d' }) },
+    })
+    expect(store.field.range.toWindow({ preset: 'toString' })).toEqual({ window: 'toString' })
+  })
+
   test('toWindow exists on a range handle and on no other kind', () => {
     const store = createSearchStore({
       key: 'k-towindow-absent',
@@ -416,3 +488,91 @@ describe('types', () => {
     expect(store.field.tab.kind).toBe('enum')
   })
 })
+
+/** UTC `YYYY-MM-DD` — the shape `toWindow` deals in, with no timezone in the answer. */
+function iso(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+function addMonths(d: Date, months: number): Date {
+  const next = new Date(d)
+  next.setUTCMonth(next.getUTCMonth() + months)
+  return next
+}
+
+describe('a lazy fallback and the lanes', () => {
+  test('a thunk fallback on the URL lane throws at DEFINITION, naming the two ways out', () => {
+    expect(() =>
+      createSearchStore({
+        key: 'k-lazy-url',
+        fields: { since: field.string({ fallback: () => '2026-01-01' }) },
+      }),
+    ).toThrow(/thunk fallback on the URL lane/)
+  })
+
+  test('off the URL lane it resolves per read, in a search store too', () => {
+    let today = '2026-01-01'
+    const store = createSearchStore({
+      key: 'k-lazy-local',
+      fields: {
+        since: field.string({ fallback: () => today }, { url: false }),
+        scratch: field.string({ fallback: () => today }, { url: false, persist: false }),
+      },
+    })
+    expect(store.field.since.fallback).toBe('2026-01-01')
+    today = '2026-02-01'
+    expect(store.field.since.fallback).toBe('2026-02-01')
+    expect(store.field.scratch.fallback).toBe('2026-02-01')
+  })
+})
+
+describe('field.range — the `custom` flag is inferred, never widened', () => {
+  test('an omitted `custom` keeps `custom` out of the value type AND out of the options', () => {
+    const store = createSearchStore({
+      key: 'k-custom-inference',
+      fields: { range: field.range({ presets: ['7d', '30d'], fallback: '30d' }) },
+    })
+    type Search = ReturnType<typeof store.validateSearch>
+
+    const preset: Search['range'] = '7d'
+    // @ts-expect-error 'custom' is NOT a value of a range that never declared `custom: true` —
+    // this is the whole bug: written inline in `fields`, `C` used to widen to `boolean` against
+    // `AnyField`, and every value type gained a preset the field rejects at runtime.
+    const widened: Search['range'] = 'custom'
+
+    expect(preset).toBe('7d')
+    // `String(...)` because `widened`'s DECLARED type no longer admits the value it holds — the
+    // `@ts-expect-error` above is the assertion, this only keeps the binding used.
+    expect(String(widened)).toBe('custom')
+    expect(store.field.range.options.map((option) => option.value)).toEqual(['7d', '30d'])
+    // The runtime agrees with the type: a `custom` preset does not decode.
+    expect(store.validateSearch({ range: 'custom', from: '2026-01-01', to: '2026-02-01' })).toEqual(
+      { range: '30d', from: undefined, to: undefined },
+    )
+  })
+
+  test('`custom: true` still admits it, in the type and in the options', () => {
+    const store = createSearchStore({
+      key: 'k-custom-true',
+      fields: { range: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }) },
+    })
+    type Search = ReturnType<typeof store.validateSearch>
+    const custom: Search['range'] = 'custom'
+
+    expect(custom).toBe('custom')
+    expect(store.field.range.options.map((option) => option.value)).toEqual(['7d', '30d', 'custom'])
+  })
+
+  test('a `custom` flag held in a widened boolean still builds — it just stays widened', () => {
+    const allowCustom: boolean = true
+    const store = createSearchStore({
+      key: 'k-custom-widened',
+      fields: { range: field.range({ presets: ['7d'], fallback: '7d', custom: allowCustom }) },
+    })
+    type Search = ReturnType<typeof store.validateSearch>
+    const custom: Search['range'] = 'custom'
+
+    expect(custom).toBe('custom')
+    expect(store.field.range.options.map((option) => option.value)).toEqual(['7d', 'custom'])
+  })
+})