basalt-ui 1.26.0 → 1.27.0

package/src/controls/number-filter.tsx

@@ -0,0 +1,291 @@
+/**
+ * `NumberFilter` — one number, one pill (`docs/CONTROLS-SPEC.md` §3), over a `field.number`. Takes
+ * `field`, never `value`/`onChange`/`size` (C2/C5), like every other control on this subpath.
+ *
+ * **Two forms, and `options` is the whole switch.** With `options` the filter is a pill plus a radio
+ * list — the same body `SelectFilter` renders, reached through `EnumFilter`'s `ChoiceHandle`, so a
+ * numeric preset set (`1` / `2` / `7` nights) is one idiom with the enum filters rather than a
+ * second spelling of the same choice. Without `options` it is a pill whose popover holds a `ctl`
+ * `NumberInput` with its steppers, and the sheet form is that input in a full-width row.
+ *
+ * **A threshold is a NUMBER, not a string enum, and that is why this control exists.** Both
+ * consumers that needed one wrote around its absence in opposite directions: linewatch kept a raw
+ * `SegmentedControl` over `minDuration` (a `control-outside-home` warn, law C1), and argo widened
+ * `nights` into a string enum — which puts `'3'` in the URL, makes every comparison a parse, and
+ * closes a set that was never closed. `field.number` already carries the codec, the clamp and both
+ * lanes; the only thing missing was the control.
+ *
+ * **The stepper applies on blur or Enter, never per keystroke.** A number is typed digit by digit,
+ * so a live write navigates on `4`, `42`, `420` and lands three values in the loader for one
+ * intended threshold — and the middle two are real values the store would clamp and persist.
+ * `SearchFilter` debounces for the same reason; a number has an explicit commit point (leaving the
+ * field, pressing Enter) and a phrase does not, so this one commits rather than waits.
+ *
+ * **`min`/`max`/`int` come off the HANDLE, never the call site.** `field.number({ min, max, int })`
+ * declares them, the codec clamps to them on write, and the handle republishes all three — so the
+ * `NumberInput` bounds its own stepper and `int` refuses decimals outright. They are not props here
+ * on purpose: they belong to the field, which is the thing that validates the URL, and a second copy
+ * at the call site is a second answer to the same question that stops matching the moment the field
+ * moves. The clamp is still the backstop for a value that arrives from outside the input (a
+ * hand-typed URL, a stale deep link), and the draft follows the field down when it fires (see
+ * {@link useCommittedNumber}).
+ *
+ * @example
+ * // A preset set — a pill plus a radio list, exactly like SelectFilter.
+ * // nights: field.number({ fallback: 2, min: 1, max: 14, int: true })
+ * <NumberFilter
+ *   field={booking.field.nights}
+ *   label="Nights"
+ *   options={[
+ *     { value: 1, label: '1 night' },
+ *     { value: 2, label: '2 nights' },
+ *     { value: 7, label: 'A week' },
+ *   ]}
+ * />
+ *
+ * @example
+ * // An open threshold — a pill holding a stepper, applied on blur or Enter.
+ * // minDuration: field.number({ fallback: 0, min: 0, max: 600 })
+ * <NumberFilter field={lines.field.minDuration} label="Min duration" step={30} />
+ */
+import { NumberInput } from '@mantine/core'
+import { useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { FieldHandle, NumberField } from '../state'
+import classes from './controls.module.css'
+import { EnumFilter } from './enum-filter'
+import type { ChoiceHandle } from './enum-filter'
+import { useFilterRegistration, useFilterSurface } from './filter-context'
+import { FilterPill } from './filter-pill'
+import { SheetField, useControlName } from './filter-sheet'
+
+/** One row of a numeric preset set. Narrower than `FilterOption` — a preset is never `disabled`:
+ *  the set is declared at the call site, so a row that should not be offered is left out. */
+export type NumberFilterOption = {
+  readonly value: number
+  readonly label: string
+}
+
+export type NumberFilterProps = {
+  readonly field: FieldHandle<NumberField>
+  /** The popover/sheet heading and the accessible name — never the pill text, which reads the
+   *  VALUE (see `EnumFilter`'s doc for why a pill may only print what is selected). */
+  readonly label: string
+  readonly icon?: ReactNode
+  /** Present → the radio-list form. Absent → the stepper form. */
+  readonly options?: readonly NumberFilterOption[]
+  /**
+   * The stepper's increment. Ignored in the `options` form, which has no stepper.
+   *
+   * @default 1 — and for an `int: true` field that is also the only sane grain, so it is what the
+   * field's own declaration produces without this prop.
+   */
+  readonly step?: number
+}
+
+export function NumberFilter({ field, label, icon, options, step }: NumberFilterProps): ReactNode {
+  // Two BRANCHES, two components, and never a conditional hook: the radio form's state lives in
+  // `EnumFilter` and the stepper's in `NumberStepper`, so which one mounts is decided once by a prop
+  // that does not change across a mount's life.
+  if (options !== undefined) {
+    return (
+      <NumberChoice
+        field={field}
+        label={label}
+        options={options}
+        {...(icon !== undefined && { icon })}
+      />
+    )
+  }
+  return (
+    <NumberStepper
+      field={field}
+      label={label}
+      {...(icon !== undefined && { icon })}
+      {...(step !== undefined && { step })}
+    />
+  )
+}
+
+/**
+ * The `options` form. It renders no radio list of its own — it ADAPTS the number handle into
+ * `EnumFilter`'s `ChoiceHandle<string>` and hands it over, so the popover's `Radio.Group`, the
+ * sheet's `SheetOptionList`, the registration and the pill readout are the ones already tested for
+ * `SelectFilter`/`CompareFilter` rather than a numeric copy of all four.
+ *
+ * The adapter is a projection, not a store: the URL still holds a NUMBER (`nights=3`, not `'3'`),
+ * because every write goes back through `setValue(Number(next))` into the same field codec.
+ *
+ * `field.use()` is called HERE, at a component's top level, and the adapter's own `use()` just
+ * returns what it read. The other way round — a `use()` that calls the real hook when `EnumFilter`
+ * invokes it — works at runtime (the call site is stable) but makes a plain object method a hook,
+ * which is a thing neither `react/rules-of-hooks` nor a reader should have to reason about.
+ */
+function NumberChoice({
+  field,
+  label,
+  icon,
+  options,
+}: {
+  readonly field: FieldHandle<NumberField>
+  readonly label: string
+  readonly icon?: ReactNode
+  readonly options: readonly NumberFilterOption[]
+}): ReactNode {
+  const [value, setValue] = field.use()
+  const rows = options.map((option) => ({ value: String(option.value), label: option.label }))
+  const choice: ChoiceHandle<string> = {
+    fallback: String(field.fallback),
+    options: rows,
+    use: () =>
+      [
+        String(value),
+        (next: string) => {
+          setValue(Number(next))
+        },
+      ] as const,
+    isDefault: (v) => field.isDefault(Number(v)),
+    clear: () => {
+      field.clear()
+    },
+  }
+
+  // `options` passed explicitly as well as through the handle: `EnumFilter` reads the PROP first
+  // (the runtime-catalogue override), and passing the same rows both ways keeps the two agreeing
+  // whichever branch of that lookup a future edit takes.
+  return (
+    <EnumFilter
+      field={choice}
+      label={label}
+      numeric
+      options={rows}
+      {...(icon !== undefined && { icon })}
+    />
+  )
+}
+
+/** The stepper form — a pill holding a `ctl` `NumberInput`, or a full-width sheet row. */
+function NumberStepper({
+  field,
+  label,
+  icon,
+  step,
+}: {
+  readonly field: FieldHandle<NumberField>
+  readonly label: string
+  readonly icon?: ReactNode
+  readonly step?: number
+}): ReactNode {
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const inSheet = surface === 'sheet'
+  const isDefault = field.isDefault(value)
+  useFilterRegistration(!isDefault, () => {
+    field.clear()
+  })
+  const { labelId, nameProps } = useControlName(label, inSheet)
+  const draft = useCommittedNumber(value, setValue, { min: field.min, max: field.max })
+
+  const input = (
+    <NumberInput
+      {...nameProps}
+      size="ctl"
+      // The FIELD's bounds, straight off the handle — so the stepper stops at the limit and a typed
+      // value cannot exceed it, instead of being silently corrected one commit later. The codec's
+      // clamp stays the backstop for everything that does not come through this box.
+      {...(field.min !== undefined && { min: field.min })}
+      {...(field.max !== undefined && { max: field.max })}
+      // `int: true` is refused by the codec, not rounded, so the input must refuse it too — a `.5`
+      // typed into an integer field would otherwise decode to `null` and resurrect the fallback.
+      {...(field.int && { allowDecimal: false })}
+      {...(step !== undefined ? { step } : field.int && { step: 1 })}
+      value={draft.value}
+      onChange={draft.set}
+      onBlur={draft.commit}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter') return
+        // A filter is not inside a form here, but a consumer's page may be — an Enter that submits
+        // the page instead of committing the threshold is the one failure mode worth pre-empting.
+        event.preventDefault()
+        draft.commit()
+      }}
+    />
+  )
+
+  if (inSheet) {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        {input}
+      </SheetField>
+    )
+  }
+
+  return (
+    <FilterPill
+      label={String(value)}
+      numeric
+      active={!isDefault}
+      {...(icon !== undefined && { icon })}
+    >
+      <div className={classes.optionList}>{input}</div>
+    </FilterPill>
+  )
+}
+
+/**
+ * A local draft that lands on the field only when the user is DONE with it (blur, Enter), and that
+ * follows the field when it changes from outside the input — `Reset all`, a back navigation, a deep
+ * link, and the codec's own clamp.
+ *
+ * The clamp is the interesting direction, and it is why `bounds` is a parameter rather than left to
+ * the codec. `commit` clamps to the field's OWN limits before it compares, so the readout follows
+ * the clamp even when the store does not move: a second out-of-range `9999` against `max: 600` over
+ * a stored `600` writes nothing (the value is already `600`), which means `[value]` never changes and
+ * the effect below never runs — and the input went on displaying `9999` over a URL holding `600`,
+ * exactly the readout this hook exists to prevent. Only the FIRST out-of-range commit was ever
+ * healed.
+ *
+ * `seen` (the number this hook last committed) plus the effect stay as the backstop for a change that
+ * did not come through this box at all — `Reset all`, a deep link, a back navigation — and for a
+ * codec clamp the bounds here cannot predict.
+ */
+function useCommittedNumber(
+  value: number,
+  setValue: (next: number) => void,
+  bounds: { min?: number | undefined; max?: number | undefined },
+): { value: number | string; set: (next: number | string) => void; commit: () => void } {
+  const [draft, setDraft] = useState<number | string>(value)
+  const seen = useRef(value)
+  const commitRef = useRef(setValue)
+  commitRef.current = setValue
+
+  useEffect(() => {
+    if (seen.current === value) return
+    seen.current = value
+    setDraft(value)
+  }, [value])
+
+  return {
+    value: draft,
+    set: setDraft,
+    commit: () => {
+      const parsed = typeof draft === 'number' ? draft : Number.parseFloat(draft)
+      // An empty or half-typed box ('', '-', '1e') is not a value — restore the field's, rather
+      // than committing `NaN` for the codec to fall back on and calling that the user's intent.
+      if (!Number.isFinite(parsed)) {
+        setDraft(value)
+        return
+      }
+      // Clamp to what the codec will actually store, then show THAT — a draft the store is about to
+      // refuse is a lie whether or not the store's value moves. `int` needs no handling: the input
+      // runs `allowDecimal: false` on an integer field, so a decimal never reaches here.
+      let next = parsed
+      if (bounds.min !== undefined && next < bounds.min) next = bounds.min
+      if (bounds.max !== undefined && next > bounds.max) next = bounds.max
+      setDraft(next)
+      if (next === value) return
+      seen.current = next
+      commitRef.current(next)
+    },
+  }
+}

package/src/controls/props-contract.test.tsx

@@ -12,6 +12,7 @@ import type { ReactNode } from 'react'
 import { createLocalStore, field } from '../state'
 import { CompareFilter } from './compare-filter'
 import { MultiSelectFilter } from './multi-select-filter'
+import { NumberFilter } from './number-filter'
 import { RangeFilter } from './range-filter'
 import { SearchFilter } from './search-filter'
 import { SelectFilter } from './select-filter'
@@ -27,6 +28,7 @@ const local = createLocalStore({
     range: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }),
     errorsOnly: field.boolean(false),
     q: field.string(),
+    nights: field.number({ fallback: 2, min: 1, max: 14, int: true }),
   },
 })
 
@@ -70,6 +72,25 @@ function Rejected(): ReactNode {
       <SelectFilter field={local.field.q} label="Project" />
       {/* @ts-expect-error `options` does not widen a MULTI field into a single-select either. */}
       <SelectFilter field={local.field.channels} label="Channels" options={PROJECTS} />
+      {/* @ts-expect-error C2 — a number filter is store-bound too; there is no `value`. */}
+      <NumberFilter field={local.field.nights} label="Nights" value={3} />
+      {/* @ts-expect-error C5 — the home sets the tier. `step` is the stepper's increment, not a size. */}
+      <NumberFilter field={local.field.nights} label="Nights" size="xs" />
+      {/* @ts-expect-error an enum field is not a number field — the whole point of the control. */}
+      <NumberFilter field={local.field.currency} label="Nights" />
+      {/* @ts-expect-error `label` is required — the popover and the sheet both need a heading. */}
+      <NumberFilter field={local.field.nights} />
+      {/* NumberFilter's options are NUMBERS. A string here is the exact shape argo reached for when
+          it widened `nights` into an enum, and it has to be a type error rather than a silent
+          `Number('7')` at the boundary. */}
+      <NumberFilter
+        field={local.field.nights}
+        label="Nights"
+        // @ts-expect-error a numeric preset set takes `value: number`, never a numeral string.
+        options={[{ value: '7', label: 'A week' }]}
+      />
+      {/* @ts-expect-error `min`/`max` belong to the FIELD, which is what validates the URL. */}
+      <NumberFilter field={local.field.nights} label="Nights" min={1} />
     </>
   )
 }
@@ -94,6 +115,16 @@ function Accepted(): ReactNode {
       <ToggleFilter field={local.field.errorsOnly} label="Errors only" />
       <SearchFilter field={local.field.q} placeholder="Search" />
       <ViewTabs field={local.field.currency} />
+      {/* Both forms, spelled correctly: the preset set, and the open stepper. */}
+      <NumberFilter
+        field={local.field.nights}
+        label="Nights"
+        options={[
+          { value: 1, label: '1 night' },
+          { value: 7, label: 'A week' },
+        ]}
+      />
+      <NumberFilter field={local.field.nights} label="Nights" step={2} />
     </>
   )
 }

package/src/controls/range-filter.tsx

@@ -41,6 +41,34 @@ const VERTICAL_FROM = 5
 /** `7d`, `30d`, `24h`, `90` — a label the mono numeric treatment is for. */
 const NUMERIC_LABEL = /^\d/
 
+/** The house dev gate — `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle
+ *  constant-folds this to `false` and drops the warning. Read per call, never hoisted. */
+function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}
+
+/** Once per label — a filter renders on every navigation, and the wiring is fixed at definition. */
+const noPickerWarned = new Set<string>()
+
+/**
+ * Dev-only: the field declares `custom: true` and no picker was injected, so the custom window is
+ * unreachable — the popover shows presets only and the sheet's `Custom range…` row never renders.
+ * A warning rather than a type error: `custom: true` with presets only is a legal (and tested)
+ * configuration, and the picker is INJECTED precisely because `@mantine/dates` may be absent, so
+ * the type cannot tell "deliberately preset-only" from "forgot the import".
+ */
+function warnCustomWithoutPicker(label: string, unreachable: boolean): void {
+  if (!unreachable || !isDev() || noPickerWarned.has(label)) return
+  noPickerWarned.add(label)
+  // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
+  console.warn(
+    `[basalt-ui] RangeFilter('${label}'): the field declares \`custom: true\` but no ` +
+      '`customPicker` was injected, so the custom window cannot be reached. Pass ' +
+      '`customPicker={DateRangePicker}` (`basalt-ui/controls-dates`), or drop `custom: true` from ' +
+      'the field. (dev only)',
+  )
+}
+
 /**
  * The contract a custom-range picker satisfies — `basalt-ui/controls-dates`' `DateRangePicker`, or a
  * consumer's own. Dates are ISO (`YYYY-MM-DD`), the same shape `field.range` stores and
@@ -51,28 +79,52 @@ export type RangeCustomPickerProps = {
   readonly onChange: (next: { from: string; to: string }) => void
 }
 
-export type RangeFilterProps<P extends string> = {
-  readonly field: FieldHandle<RangeField<P>>
+/** Everything about the props that does not depend on the field's `custom` flag. */
+type RangeFilterBase<P extends string, C extends boolean> = {
+  /**
+   * A range handle from either store factory. Generic over the field's `custom` flag so a
+   * `field.range({ ... })` WITHOUT `custom` (whose handle is `RangeField<P, false>`, and whose
+   * values therefore never include `'custom'`) binds with no cast — pinning `C` to its default
+   * `boolean` here made the setter contravariantly incompatible and forced one at every call site.
+   */
+  readonly field: FieldHandle<RangeField<P, C>>
   /** Leading pill icon. Defaults to a calendar glyph — a range filter reads as a date control, so
    *  the glyph is part of the control's identity, not a per-call-site decision. */
   readonly icon?: ReactNode
-  /** Rendered when the field declares `custom: true`. Omitted → presets only. */
-  readonly customPicker?: ComponentType<RangeCustomPickerProps>
   /** Sheet-form heading. The pill's own label is the VALUE, which is what a bar reads. @default 'Range' */
   readonly label?: string
 }
 
-export function RangeFilter<P extends string>({
-  field,
-  icon,
-  customPicker,
-  label = 'Range',
-}: RangeFilterProps<P>): ReactNode {
+export type RangeFilterProps<P extends string, C extends boolean = boolean> = RangeFilterBase<
+  P,
+  C
+> & {
+  /**
+   * Rendered when the field declares `custom: true`. Omitted → presets only, which stays LEGAL
+   * (a range that only ever shows presets is a real configuration) but warns once in dev when the
+   * field allows a custom window: the affordance is then unreachable, and nothing else says so.
+   */
+  readonly customPicker?: ComponentType<RangeCustomPickerProps>
+}
+
+export function RangeFilter<P extends string, C extends boolean = boolean>(
+  props: RangeFilterProps<P, C>,
+): ReactNode {
+  const {
+    field,
+    icon,
+    customPicker,
+    label = 'Range',
+    // One cast, at the one boundary a generic `C` cannot be read through: `C` only ever describes
+    // the FIELD's custom flag, and the body handles both.
+  } = props as unknown as RangeFilterBase<P, boolean> & {
+    readonly customPicker?: ComponentType<RangeCustomPickerProps>
+  }
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
   const isDefault = field.isDefault(value)
   useFilterRegistration(!isDefault, () => {
-    setValue(field.fallback)
+    field.clear()
   })
 
   const options = field.options
@@ -81,6 +133,7 @@ export function RangeFilter<P extends string>({
   const numeric = presets.length > 0 && presets.every((option) => NUMERIC_LABEL.test(option.label))
   const inSheet = surface === 'sheet'
   const Picker = customPicker
+  warnCustomWithoutPicker(label, allowsCustom && Picker === undefined)
   // The track is a `radiogroup`; without this it announces unnamed, and the pill it hangs off reads
   // the VALUE (`30d`), not the filter.
   const { labelId, nameProps } = useControlName(label, inSheet)

package/src/controls/range-filter.type-guard.test.tsx

@@ -0,0 +1,122 @@
+/**
+ * `RangeFilterProps` is generic over the FIELD's `custom` flag — the compile-time half, plus the one
+ * runtime consequence of leaving `customPicker` out.
+ *
+ * Why a file of its own (the `actions.type-guard.test.ts` convention): pinning `C` to its default
+ * `boolean` made `RangeFilter field={...}` reject a `field.range({ … })` that never declared
+ * `custom: true`. The handle's setter is contravariant, so a `RangeValue<P>` setter cannot stand in
+ * for a `RangeValue<P | 'custom'>` one — two consumers cast at the call site instead, which is
+ * exactly the diagnostic the cast was hiding.
+ */
+import { describe, expect, spyOn, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import type { FieldHandle, RangeField } from '../state'
+import { createLocalStore, field } from '../state'
+import { RangeFilter } from './range-filter'
+import type { RangeCustomPickerProps } from './range-filter'
+
+// Two stores, not two range fields in one: every range defaults its `from`/`to` param names, and
+// the store core rejects the collision at definition (see `assertNoParamCollision`).
+const store = createLocalStore({
+  key: 'tg-range',
+  fields: {
+    presetsOnly: field.range({ presets: ['7d', '30d'], fallback: '30d' }),
+    view: field.enum(['chart', 'table'], 'chart'),
+  },
+})
+
+const customStore = createLocalStore({
+  key: 'tg-range-custom',
+  fields: { withCustom: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }) },
+})
+
+function Picker({ onChange }: RangeCustomPickerProps): ReactNode {
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        onChange({ from: '2026-03-01', to: '2026-03-14' })
+      }}
+    >
+      pick march
+    </button>
+  )
+}
+
+/** A control that took a range handle from ITS OWN props — `C` widened, which must still bind. */
+function Wrapper({ handle }: { handle: FieldHandle<RangeField<'7d' | '30d'>> }): ReactNode {
+  return <RangeFilter field={handle} customPicker={Picker} />
+}
+
+// ── Valid — must type-check with no error ─────────────────────────────────────
+
+function Accepted(): ReactNode {
+  return (
+    <>
+      {/* The regression: no `custom`, therefore `RangeField<P, false>` — and no cast. */}
+      <RangeFilter field={store.field.presetsOnly} />
+      <RangeFilter field={store.field.presetsOnly} label="Window" />
+      <RangeFilter field={customStore.field.withCustom} customPicker={Picker} />
+      <Wrapper handle={customStore.field.withCustom} />
+    </>
+  )
+}
+
+// ── Invalid — each MUST be a tsc error, one directive per bad line ────────────
+
+function Rejected(): ReactNode {
+  return (
+    <>
+      {/* @ts-expect-error an enum handle is not a range handle, whatever `C` is */}
+      <RangeFilter field={store.field.view} />
+      {/* @ts-expect-error `value`/`onChange` is not the binding a basalt control takes (C2) */}
+      <RangeFilter value={{ preset: '7d' }} onChange={() => {}} />
+    </>
+  )
+}
+
+/** The first argument of every captured warn call. */
+function lines(warn: { mock: { calls: unknown[][] } }): string[] {
+  return warn.mock.calls.map((call) => String(call[0]))
+}
+
+describe('RangeFilterProps (type-guard)', () => {
+  test('both fixtures exist — tsc, not bun, is the assertion for the cases above', () => {
+    expect(typeof Accepted).toBe('function')
+    expect(typeof Rejected).toBe('function')
+  })
+
+  test('a custom-capable field with no picker warns once in dev — the affordance is unreachable', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      render(
+        <MantineProvider>
+          <RangeFilter field={customStore.field.withCustom} label="Unreachable" />
+        </MantineProvider>,
+      )
+      expect(screen.getByRole('button', { name: '30d' })).toBeDefined()
+      expect(
+        lines(warn).filter((line) => line.includes("RangeFilter('Unreachable')")),
+      ).toHaveLength(1)
+      expect(lines(warn)[0]).toContain('customPicker')
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  test('a preset-only field is silent — presets only is a configuration, not a mistake', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      render(
+        <MantineProvider>
+          <RangeFilter field={store.field.presetsOnly} label="Silent" />
+        </MantineProvider>,
+      )
+      expect(lines(warn).filter((line) => line.includes("RangeFilter('Silent')"))).toHaveLength(0)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+})

package/src/controls/search-filter.tsx

@@ -38,7 +38,7 @@ export function SearchFilter({
   const surface = useFilterSurface()
   const draft = useDebouncedField(value, setValue)
   useFilterRegistration(!field.isDefault(value), () => {
-    setValue(field.fallback)
+    field.clear()
   })
 
   // `placeholder` is optional and, even when set, stops being the name the moment the user types —

package/src/controls/toggle-filter.tsx

@@ -25,7 +25,7 @@ export function ToggleFilter({ field, label, icon }: ToggleFilterProps): ReactNo
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
   useFilterRegistration(!field.isDefault(value), () => {
-    setValue(field.fallback)
+    field.clear()
   })
 
   if (surface === 'sheet') {

package/src/dashboard/index.ts

@@ -1,5 +1,10 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'
-export { StatCard, type StatCardProps, type StatCardTone } from './stat-card'
+export {
+  StatCard,
+  type StatCardBreakdownRow,
+  type StatCardProps,
+  type StatCardTone,
+} from './stat-card'
 export { EmptyState, type EmptyStateProps } from './empty-state'
 export {
   SettingsSection,