basalt-ui 1.27.0 → 1.28.0

package/src/controls/panel-row.tsx

@@ -0,0 +1,392 @@
+/**
+ * `PanelRow` — the inspector/facet ROW every control renders on the `panel` surface, and on the
+ * mobile `sheet` surface too (`docs/ASIDE-SPEC.md` §1 "Inspector", §3; `docs/CONTROLS-SPEC.md` §3:
+ * "sheet = panel rows inside a Drawer") — a labelled block around one control, and a HOME: it wraps
+ * its slots in `CtlSlot`, so a control inside carries no `size` of its own (law C5).
+ *
+ * **Label above, never beside (G4).** At an aside's ~300px, label · control · readout on one line
+ * leaves the control about 90px — under 12px per step for a 20-step slider, which is why the CBBI
+ * page hand-rolled two-line rows before this existed. The ONE exception is `end`: a control that
+ * rides the label line because it is atomic and needs no width (a `Switch`).
+ *
+ * The skeleton is plain elements plus one CSS module — no Mantine `Group`/`Stack`. A row is drawn
+ * dozens of times in one column, and the hairline/inset law it carries (`.row + .row`) is a
+ * SIBLING relationship, which a `Stack`'s gap cannot express.
+ *
+ * @example
+ * <PanelRow label="Pi Cycle Top" hint="The 111DMA / 350DMA×2 crossover." readout="0.62">
+ *   <SliderControl field={weights.field.piCycle} label="Pi Cycle Top" />
+ * </PanelRow>
+ *
+ * @example
+ * // A toggle: one line, the control on the label line, no control line at all.
+ * <PanelRow label="Reweighted" end={<Switch checked={on} onChange={…} />} />
+ */
+import { SegmentedControl, Select } from '@mantine/core'
+import { useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { CtlSlot } from '../theme'
+import { InfoGlyph } from '../widget-header/widget-header'
+import classes from './panel-row.module.css'
+
+/**
+ * Past three options a panel row's choice is a `Select`, not a track. Same arithmetic as
+ * `ViewTabs`' phone form, against the aside's ~300px rather than a phone's: a four-segment track at
+ * that width gives each label ~60px, which truncates every word longer than "Previous".
+ *
+ * **The count, not the whole law.** Three options at three WORDS' worth of label is not the same
+ * claim as three options at three SENTENCES' worth — "Same period last year" clipped mid-word
+ * inside its equal third even at a set of exactly three. `PANEL_TRACK_MAX` is the cheap first gate;
+ * `useTrackFits` (below) is the actual width check that decides whether the track renders at all.
+ */
+export const PANEL_TRACK_MAX = 3
+
+export type PanelRowProps = BasaltProps & {
+  /** The row's name. Rendered above the control, `xs`/550 — never inside it. */
+  readonly label: string
+  /** Info glyph + tooltip beside the label — the same affordance `WidgetHeader.info` draws. */
+  readonly hint?: string
+  /**
+   * The current value, mono and right-aligned on the label line. A slider's readout, a range's
+   * resolved window — anything the control itself does not print.
+   */
+  readonly readout?: ReactNode
+  /**
+   * A control that rides the LABEL line instead of taking one of its own — a `Switch`, and by
+   * design almost nothing else. Anything with a width belongs in `children`.
+   */
+  readonly end?: ReactNode
+  /** Dims the row. The control inside keeps its own `disabled` — this is the visual half. */
+  readonly disabled?: boolean
+  /**
+   * Stamped on the label so the control can point `aria-labelledby` at it. The CONTROL owns the id
+   * (it renders this row), so an id published downward could never reach it — see
+   * `useControlName`'s doc.
+   */
+  readonly labelId?: string
+  /**
+   * When set, renders the label as a `<label htmlFor={htmlFor}>` instead of a bare `<span>`, so
+   * clicking the label text also activates the control — the affordance Mantine's own labelled
+   * inputs give for free. Pass the `end` control's id (a `Switch`, typically).
+   */
+  readonly htmlFor?: string
+  /** The full-width control line. Omitted for a row whose control rides `end`. */
+  readonly children?: ReactNode
+}
+
+export function PanelRow({
+  label,
+  hint,
+  readout,
+  end,
+  disabled,
+  labelId,
+  htmlFor,
+  children,
+  className,
+  style,
+}: PanelRowProps): ReactNode {
+  return (
+    <div
+      className={cx(classes.row, className)}
+      {...(disabled === true && { 'data-disabled': true })}
+      {...(style !== undefined && { style })}
+    >
+      {/* ONE slot for the whole row, not one per line: `CtlSlot`'s marker is `display: contents`,
+          so both lines stay flex children of `.row` and the tier reaches `end` and `children`
+          through a single provider. */}
+      <CtlSlot>
+        <div className={classes.head}>
+          {htmlFor !== undefined ? (
+            <label
+              htmlFor={htmlFor}
+              className={classes.label}
+              {...(labelId !== undefined && { id: labelId })}
+            >
+              {label}
+            </label>
+          ) : (
+            <span className={classes.label} {...(labelId !== undefined && { id: labelId })}>
+              {label}
+            </span>
+          )}
+          {hint !== undefined && <InfoGlyph text={hint} />}
+          {readout !== undefined && <span className={classes.readout}>{readout}</span>}
+          {end !== undefined && <span className={classes.end}>{end}</span>}
+        </div>
+        {children !== undefined && <div className={classes.control}>{children}</div>}
+      </CtlSlot>
+    </div>
+  )
+}
+
+/** One option as both surfaces render it — `disabled` is the `SegmentedControl` half. */
+export type PanelChoiceOption = {
+  readonly value: string
+  readonly label: string
+  readonly disabled?: boolean
+}
+
+export type PanelChoiceProps = {
+  /** The control's accessible name, as `useControlName` resolved it for this surface. */
+  readonly nameProps: { 'aria-labelledby': string } | { 'aria-label': string }
+  readonly value: string
+  readonly options: readonly PanelChoiceOption[]
+  /** Numeric labels (`7d` / `30d`) get the mono treatment `segmented-control.module.css` owns. */
+  readonly numeric?: boolean
+  readonly onChange: (next: string) => void
+}
+
+/**
+ * The nearest ANCESTOR that actually occupies layout space — skipping every `display: contents`
+ * box on the way up. Every home in this package wraps its slot in `CtlSlot` (`theme/ctl-theme.tsx`)
+ * to reach the `ctl` tier, and `CtlSlot`'s own marker is a `display: contents` `Box` (deliberately —
+ * it must stay out of the slot's own flex/grid layout). A `display: contents` element generates NO
+ * box of its own, so its `clientWidth` is always `0` — reading `root.parentElement.clientWidth`
+ * directly would report "zero room" for every control mounted straight into a slot (`ViewTabs`'
+ * desktop form, `PageBar`'s `actions`), which is not the constraint being measured at all.
+ */
+function layoutParent(el: HTMLElement): HTMLElement | null {
+  let parent = el.parentElement
+  while (parent !== null && getComputedStyle(parent).display === 'contents') {
+    parent = parent.parentElement
+  }
+  return parent
+}
+
+/**
+ * A `SegmentedControl`'s own semantic class for a rendered option's label (`__staticSelector`,
+ * present on every Mantine styles-api part regardless of the CSS-module hash) — stable across a
+ * version bump the way a generated `_label_1pq5d_5` class is not.
+ */
+const TRACK_LABEL_SELECTOR = '.mantine-SegmentedControl-label'
+
+/**
+ * The authoritative check, meaningful only while the track is actually mounted — TWO signals, not
+ * one, because they catch two DIFFERENT ways a track fails to fit and neither subsumes the other:
+ *
+ * 1. **Root vs parent** (`root.offsetWidth > parent.clientWidth`) — the track's OWN root refuses to
+ *    shrink below `min-width: max-content` (`theme/index.ts`'s `SegmentedControl.extend`), so a
+ *    too-narrow ANCESTOR (a header's `actions` slot squeezing a non-`fullWidth` two-option track)
+ *    shows up as the root overflowing its container.
+ * 2. **Per-label overflow** (`label.scrollWidth > label.clientWidth`) — the ctl-tier `fullWidth`
+ *    label carries `width: 100%` (`theme/index.ts`, so it fills its equal `.control` share for
+ *    ellipsis to work at all — `PanelChoice`'s doc). A `width: 100%` CHILD cannot contribute an
+ *    intrinsic size to its ancestor's max-content computation (percentages are undefined until the
+ *    container's own size is known, so the browser treats it as contributing ~nothing) — which is
+ *    why `min-width: max-content` on the root measurably FAILS to grow past its available space at
+ *    the phone tier: "Week"/"Absolute" clipped inside their equal column ("Wee", "Absolut") while
+ *    `root.offsetWidth` still read as fitting its parent. Signal 1 cannot see this at all; only
+ *    reading each rendered label directly can.
+ *
+ * Both signals require REAL layout, so `unknown` (parent not yet settled) takes priority over
+ * either — see `useTrackFits`'s own doc for why a `0` reading is not evidence of overflow.
+ */
+function measureMounted(root: HTMLElement, parent: HTMLElement): 'fits' | 'overflow' | 'unknown' {
+  if (parent.clientWidth === 0) return 'unknown'
+  if (root.offsetWidth > parent.clientWidth) return 'overflow'
+  const labels = root.querySelectorAll<HTMLElement>(TRACK_LABEL_SELECTOR)
+  for (const label of labels) {
+    if (label.scrollWidth > label.clientWidth) return 'overflow'
+  }
+  return 'fits'
+}
+
+/**
+ * Fit-checks a full-width track: {@link PANEL_TRACK_MAX} (and `ViewTabs`' own `PHONE_TRACK_MAX`) is
+ * the cheap COUNT gate, not the whole law — three short labels and three long ones are not the same
+ * claim at a ~300px column or a phone sheet ("Same period last year" clipped mid-word inside its
+ * equal third even though the set was exactly three; "Week"/"Absolute" clipped inside their equal
+ * column at the phone tier even though the ROOT read as fitting its parent — see
+ * {@link measureMounted}'s doc for why that needs a second signal). This hook is the width gate
+ * underneath the count cap, shared so `PanelChoice` and `ViewTabs`' phone form cannot drift the way
+ * their two hand-rolled ternaries already had once (`PanelChoice`'s own doc).
+ *
+ * **A LIVE toggle, not a one-way latch — it reverts.** The moment the track overflows, `PanelChoice`
+ * swaps it for a `Select`, which un-mounts the only element `measureMounted` could otherwise read.
+ * Two refs survive that swap on purpose: `trackWidthRef` remembers the track's own last-measured
+ * width (refreshed live whenever it IS mounted, used only as a cheap pre-filter — see below — never
+ * as the final answer), and `parentRef` holds the layout parent found once, at the FIRST mount — the
+ * same DOM node hosts either form (`PanelChoice`/`ViewTabs` return one or the other as their sole
+ * element, never a wrapper that differs between them), so it is never itself removed by the swap.
+ * The `ResizeObserver` therefore never watches a node this hook is about to lose: it observes the
+ * PARENT for the whole hook's lifetime and the TRACK only while it exists.
+ *
+ * While `Select` is showing, an observer tick with room to spare (`parent.clientWidth` at or past
+ * the remembered `trackWidthRef`) SPECULATIVELY re-mounts the track rather than trying to predict
+ * the exact threshold from a cached number — the two-signal check above cannot be run without a
+ * live root, and a WRONG guess here is not user-visible: the second effect below re-verifies with
+ * `measureMounted` the instant the fresh root exists, inside the SAME `useLayoutEffect` pass, and
+ * reverts synchronously before paint if the speculation was wrong. Nothing here can loop — a
+ * `ResizeObserver` only fires again on a GENUINE subsequent size change, not because React
+ * re-rendered.
+ *
+ * A SECOND, dependency-free `useLayoutEffect` is what performs that verification (and, on the
+ * ordinary growth-first-detected-while-mounted path, is also what re-arms the observer on the
+ * track's own root once it exists) — the FIRST effect only runs once per `[countFits, dataKey]`,
+ * but the track itself mounts and unmounts every time `fits` changes, and a `ResizeObserver` has to
+ * be told about each new node explicitly; this second effect runs after every render and is a
+ * no-op unless `rootRef.current` is a node it is not already watching.
+ *
+ * The check is THREE-VALUED, not two — `unknown` alongside `fits`/`overflow` — because a
+ * `clientWidth` of `0` is not evidence of overflow, it is evidence the ancestor chain has not been
+ * LAID OUT yet: the aside animates its width in from 0 while `PageAside` claims the region
+ * (`docs/ASIDE-SPEC.md` §0), and every ancestor up to the aside panel itself reads `0` for one or
+ * more layout passes while that transition is in flight. `unknown` updates nothing — it is simply
+ * not yet an answer, and the observer keeps watching for the ancestor chain to settle.
+ *
+ * `useLayoutEffect` runs BEFORE the browser paints, so a CONFIDENT overflow reading is never
+ * actually shown as a track first: the synchronous `setState` for it lands before paint, not after.
+ *
+ * `dataKey` is a caller-built string identifying the CURRENT option set (not read inside the effect
+ * body, just what forces it to re-run — a fresh mount, a fresh `parentRef`/`trackWidthRef` — when
+ * the rendered labels change) — primitive on purpose, so it is an honest `useLayoutEffect`
+ * dependency rather than a fresh array reference on every render.
+ */
+export function useTrackFits(
+  countFits: boolean,
+  dataKey: string,
+): { rootRef: RefObject<HTMLDivElement | null>; fits: boolean } {
+  const rootRef = useRef<HTMLDivElement>(null)
+  const [rootFits, setRootFits] = useState(true)
+  const observerRef = useRef<ResizeObserver | null>(null)
+  const parentRef = useRef<HTMLElement | null>(null)
+  const trackWidthRef = useRef(0)
+  const observedRootRef = useRef<HTMLElement | null>(null)
+
+  useLayoutEffect(() => {
+    if (!countFits) return
+    const root = rootRef.current
+    if (root === null) return
+    const parent = layoutParent(root)
+    if (parent === null) return
+    parentRef.current = parent
+    trackWidthRef.current = root.offsetWidth
+
+    const resolve = (): void => {
+      const p = parentRef.current
+      if (p === null) return
+      const liveRoot = rootRef.current
+
+      if (liveRoot !== null) {
+        const result = measureMounted(liveRoot, p)
+        trackWidthRef.current = liveRoot.offsetWidth
+        if (result === 'unknown') return
+        const fits = result === 'fits'
+        setRootFits((current) => (current === fits ? current : fits))
+        return
+      }
+
+      // `Select` is mounted — speculate rather than measure (see this hook's own doc). No-op
+      // while shrinking or unmeasured: only an actual increase past the last known track width is
+      // worth a remount attempt.
+      if (p.clientWidth === 0 || trackWidthRef.current === 0) return
+      if (p.clientWidth >= trackWidthRef.current) setRootFits(true)
+    }
+
+    if (typeof ResizeObserver === 'undefined') {
+      // No recovery path exists without an observer, so a same-tick confident read is the only
+      // chance this environment gets.
+      resolve()
+      return
+    }
+
+    const observer = new ResizeObserver(resolve)
+    observerRef.current = observer
+    observer.observe(parent)
+    observer.observe(root)
+    observedRootRef.current = root
+
+    // Resolve once, synchronously, so a track that is ALREADY confidently measurable (its
+    // ancestors settled before this component even mounted — the common case) decides before
+    // paint instead of waiting for the observer's first async tick.
+    resolve()
+
+    return () => {
+      observer.disconnect()
+      observerRef.current = null
+      observedRootRef.current = null
+    }
+  }, [countFits, dataKey])
+
+  // Re-arms the SAME observer on a fresh track root whenever one (re)mounts, AND is what actually
+  // VERIFIES a speculative remount (see this hook's own doc) — a wrong guess reverts here,
+  // synchronously, before this render ever paints. A no-op on every render where the track is
+  // absent (`Select` showing) or already the node being watched — deliberately NO dependency
+  // array, since a `ResizeObserver` has to be told about each fresh root explicitly and a fresh
+  // root can appear on any render. Cannot loop: every `setRootFits` call below is a functional
+  // update gated on the value actually CHANGING, so a render this effect does not alter never
+  // re-triggers it.
+  // oxlint-disable-next-line react-hooks/exhaustive-deps -- deliberately runs every render, see above
+  useLayoutEffect(() => {
+    const observer = observerRef.current
+    const root = rootRef.current
+    const parent = parentRef.current
+    if (observer === null || root === null || observedRootRef.current === root) return
+    if (observedRootRef.current !== null) observer.unobserve(observedRootRef.current)
+    observer.observe(root)
+    observedRootRef.current = root
+    trackWidthRef.current = root.offsetWidth
+
+    if (parent === null) return
+    const result = measureMounted(root, parent)
+    if (result === 'unknown') return
+    const fits = result === 'fits'
+    setRootFits((current) => (current === fits ? current : fits))
+  })
+
+  return { rootRef, fits: countFits && rootFits }
+}
+
+/**
+ * The single-choice control a panel row draws: a full-width track while the set fits both
+ * {@link PANEL_TRACK_MAX} and the width check {@link useTrackFits} runs, a `Select` past either.
+ *
+ * Internal, and one component rather than the same ternary in each control: `EnumFilter` and
+ * `ViewTabs` both wrote it out and had already drifted — `ViewTabs`' copy lost `data-numeric`, so a
+ * numeric tab set rendered proportional in the aside and mono everywhere else. The split point is
+ * the geometry of a ~300px column, which is a property of the ROW, not of any one filter, so it
+ * belongs beside the row that imposes it.
+ */
+export function PanelChoice({
+  nameProps,
+  value,
+  options,
+  numeric,
+  onChange,
+}: PanelChoiceProps): ReactNode {
+  const data = options.map((option) => ({
+    value: option.value,
+    label: option.label,
+    disabled: option.disabled === true,
+  }))
+  const countFits = options.length <= PANEL_TRACK_MAX
+  const { rootRef, fits } = useTrackFits(countFits, data.map((d) => d.value).join('|'))
+
+  if (fits) {
+    return (
+      <SegmentedControl
+        ref={rootRef}
+        {...nameProps}
+        fullWidth
+        value={value}
+        data={data}
+        {...(numeric === true && { 'data-numeric': true })}
+        onChange={onChange}
+      />
+    )
+  }
+  return (
+    <Select
+      {...nameProps}
+      value={value}
+      allowDeselect={false}
+      data={data}
+      onChange={(next) => {
+        if (next !== null) onChange(next)
+      }}
+    />
+  )
+}

package/src/controls/range-filter.tsx

@@ -10,11 +10,12 @@
  * `theme/segmented-control.module.css` owns; that attribute is what retired the per-consumer
  * `theme-allow` + inline `fontFamily` hack (C7).
  *
- * In the SHEET they render as a `SheetOptionList`, and the custom picker sits behind a
- * `Custom range…` disclosure row. A vertical `SegmentedControl` stretched across a bottom drawer
- * read as a broken control rather than a choice (see `SheetOptionList`'s doc), and an unconditional
- * calendar pushed every OTHER filter in the sheet below the fold — the sheet holds all of them, and
- * `RangeFilter` is one.
+ * In the PANEL and the SHEET (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a Drawer")
+ * they render as one `Select` — label above, the presets plus a `Custom range…` ROW inside the same
+ * list, which reveals the SAME injected picker underneath. A track cannot hold five date presets at
+ * ~300px (or across a bottom drawer, where a vertical `SegmentedControl` read as a broken control
+ * rather than a choice), and a second control beside the choice would cost the column — or an
+ * unconditional calendar pushed below every OTHER filter in the sheet — a row it does not have.
  *
  * The custom picker is INJECTED, never imported: `basalt-ui/controls-dates` holds the
  * `@mantine/dates` implementation, and this module must resolve for a consumer who has no
@@ -26,27 +27,28 @@
  * // range: field.range({ presets: ['7d', '30d', '90d', 'ytd'], fallback: '30d', custom: true })
  * <RangeFilter field={analytics.field.range} customPicker={DateRangePicker} />
  */
-import { SegmentedControl, Stack } from '@mantine/core'
-import { useState } from 'react'
+import { SegmentedControl, Select, Stack } from '@mantine/core'
+import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import { isDev } from '../utils/is-dev'
 import type { FieldHandle, RangeField, RangeValue } from '../state'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
 import { CalendarGlyph } from './glyphs'
-import { SheetDisclosure, SheetField, SheetOptionList, useControlName } from './filter-sheet'
+import { useControlName } from './filter-sheet'
+import { PanelRow } from './panel-row'
 
 /** Past four presets the track goes vertical. */
 const VERTICAL_FROM = 5
+/** The panel `Select`'s last row — the same wording the sheet's disclosure uses, and the same
+ *  `'custom'` preset value the field already declares, so no synthetic option value exists. */
+const CUSTOM_ROW_LABEL = 'Custom range…'
 /** `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>()
 
@@ -80,7 +82,7 @@ export type RangeCustomPickerProps = {
 }
 
 /** Everything about the props that does not depend on the field's `custom` flag. */
-type RangeFilterBase<P extends string, C extends boolean> = {
+type RangeFilterBase<P extends string, C extends boolean> = BasaltProps & {
   /**
    * 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
@@ -110,11 +112,18 @@ export type RangeFilterProps<P extends string, C extends boolean = boolean> = Ra
 export function RangeFilter<P extends string, C extends boolean = boolean>(
   props: RangeFilterProps<P, C>,
 ): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('RangeFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
   const {
     field,
     icon,
     customPicker,
     label = 'Range',
+    className,
+    style,
     // 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> & {
@@ -132,49 +141,75 @@ export function RangeFilter<P extends string, C extends boolean = boolean>(
   const allowsCustom = options.length !== presets.length
   const numeric = presets.length > 0 && presets.every((option) => NUMERIC_LABEL.test(option.label))
   const inSheet = surface === 'sheet'
+  const inPanel = surface === 'panel'
   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)
+  const { labelId, nameProps } = useControlName(label, inSheet || inPanel)
   // Expanded when the field ALREADY holds a custom window — a reader who deep-linked one must see
   // it without hunting for the row that holds it. Local, because it is an overlay's open flag and
   // not a filter value (the same line `FilterPill`'s `opened` state draws).
   const [customOpen, setCustomOpen] = useState(value.preset === 'custom')
+  // …and RE-SYNCED whenever the preset moves under it. Seeded once, the flag survived a write this
+  // control did not make: a `Reset all` or a `field.clear()` from a `FilterSet` put the field back
+  // on `30d` while the panel's Select still read `Custom range…` with the picker open beneath it.
+  // Tracked against the LAST SEEN preset (`search-filter.tsx`'s `useDebouncedField` idiom) rather
+  // than against `value.preset` alone, because the just-clicked `Custom range…` transient is
+  // exactly the state where the flag is true and the preset has not moved yet.
+  const seenPreset = useRef(value.preset)
+  useEffect(() => {
+    if (seenPreset.current === value.preset) return
+    seenPreset.current = value.preset
+    setCustomOpen(value.preset === 'custom')
+  }, [value.preset])
   const showPicker = allowsCustom && Picker !== undefined
 
-  if (inSheet) {
+  // The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+  // Drawer") — one `Select` holding the presets plus a `Custom range…` row, which reveals the same
+  // injected picker underneath. It used to be a `SheetOptionList` with the picker behind a separate
+  // `SheetDisclosure` row; the `Select` already folds both into one control, so the disclosure had
+  // no job left.
+  if (inPanel || inSheet) {
     return (
-      <SheetField label={label} labelId={labelId}>
-        <SheetOptionList
-          mode="single"
-          labelId={labelId}
-          selected={[value.preset]}
-          options={presets.map((option) => ({ value: option.value, label: option.label }))}
-          onToggle={(next) => {
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
+        <Select
+          {...nameProps}
+          allowDeselect={false}
+          // `customOpen` is what the row reads while the picker is open but no window has been
+          // picked yet — selecting `Custom range…` reveals the calendar, it does not write a
+          // half-built `{ preset: 'custom' }` the codec would have to guess at.
+          value={customOpen ? 'custom' : value.preset}
+          data={[
+            ...presets.map((option) => ({ value: option.value, label: option.label })),
+            ...(showPicker ? [{ value: 'custom', label: CUSTOM_ROW_LABEL }] : []),
+          ]}
+          onChange={(next) => {
+            if (next === null) return
+            if (next === 'custom') {
+              setCustomOpen(true)
+              return
+            }
             setCustomOpen(false)
             // Rendered from `field.options`, so `next` is always a declared preset — the cast
             // restores what the codec already guarantees.
             setValue({ preset: next } as RangeValue<P | 'custom'>)
           }}
         />
-        {showPicker && (
-          <SheetDisclosure
-            label="Custom range…"
-            expanded={customOpen}
-            onToggle={() => {
-              setCustomOpen((open) => !open)
+        {showPicker && customOpen && (
+          <Picker
+            value={{ from: value.from, to: value.to }}
+            onChange={({ from, to }) => {
+              setValue({ preset: 'custom', from, to } as RangeValue<P | 'custom'>)
             }}
-          >
-            <Picker
-              value={{ from: value.from, to: value.to }}
-              onChange={({ from, to }) => {
-                setValue({ preset: 'custom', from, to } as RangeValue<P | 'custom'>)
-              }}
-            />
-          </SheetDisclosure>
+          />
         )}
-      </SheetField>
+      </PanelRow>
     )
   }
 
@@ -210,6 +245,8 @@ export function RangeFilter<P extends string, C extends boolean = boolean>(
       active={!isDefault}
       numeric={numeric && value.preset !== 'custom'}
       icon={icon ?? <CalendarGlyph />}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       <div className={classes.optionList}>{body}</div>
     </FilterPill>

package/src/controls/search-filter.tsx

@@ -15,25 +15,30 @@
 import { TextInput } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { FieldHandle, StringField } from '../state'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
-import { SheetField, useControlName } from './filter-sheet'
+import { useControlName } from './filter-sheet'
+import { PanelRow } from './panel-row'
 
 /** One navigation per typed phrase, not per keystroke. */
 const DEBOUNCE_MS = 200
 
-export type SearchFilterProps = {
+export type SearchFilterProps = BasaltProps & {
   readonly field: FieldHandle<StringField>
   readonly placeholder?: string
   /** Sheet-form heading. @default 'Search' */
   readonly label?: string
 }
 
-export function SearchFilter({
-  field,
-  placeholder,
-  label = 'Search',
-}: SearchFilterProps): ReactNode {
+export function SearchFilter(props: SearchFilterProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('SearchFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, placeholder, label = 'Search', className, style } = props
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
   const draft = useDebouncedField(value, setValue)
@@ -42,8 +47,12 @@ export function SearchFilter({
   })
 
   // `placeholder` is optional and, even when set, stops being the name the moment the user types —
-  // so the name comes from `label`, or from the sheet heading when there is one.
-  const { labelId, nameProps } = useControlName(label, surface === 'sheet')
+  // so the name comes from `label`, or from the visible heading when the surface draws one.
+  const named = surface === 'sheet' || surface === 'panel'
+  const { labelId, nameProps } = useControlName(label, named)
+  // The pill form has no wrapping home — the `TextInput` itself is the root, so it takes the class
+  // directly. The panel/sheet forms wrap it in a home that becomes the root instead.
+  const isPill = surface !== 'panel' && surface !== 'sheet'
 
   const input = (
     <TextInput
@@ -55,14 +64,23 @@ export function SearchFilter({
       onChange={(event) => {
         draft.set(event.currentTarget.value)
       }}
+      {...(isPill && className !== undefined && { className })}
+      {...(isPill && style !== undefined && { style })}
     />
   )
 
-  if (surface === 'sheet') {
+  // The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+  // Drawer") — the same `PanelRow` label-above-control row on both surfaces.
+  if (surface === 'panel' || surface === 'sheet') {
     return (
-      <SheetField label={label} labelId={labelId}>
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
         {input}
-      </SheetField>
+      </PanelRow>
     )
   }
   return input