basalt-ui 1.26.0 → 1.28.0

package/src/controls/search-filter.tsx

@@ -15,35 +15,44 @@
 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)
   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 —
-  // 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

package/src/controls/select-filter.tsx

@@ -30,6 +30,8 @@
  * />
  */
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { EnumField, FieldHandle, StringField } from '../state'
 import { EnumFilter } from './enum-filter'
 
@@ -45,7 +47,7 @@ export type FilterOption = {
   readonly disabled?: boolean
 }
 
-type SelectFilterCommon = {
+type SelectFilterCommon = BasaltProps & {
   readonly label: string
   readonly icon?: ReactNode
   /** Adds a `Clear` action that writes the field back to its fallback. */
@@ -78,6 +80,14 @@ export type SelectFilterProps<T extends string> = SelectFilterEnumProps<T> | Sel
 export function SelectFilter<T extends string>(props: SelectFilterEnumProps<T>): ReactNode
 export function SelectFilter(props: SelectFilterStringProps): ReactNode
 export function SelectFilter<T extends string>(props: SelectFilterProps<T>): ReactNode {
+  // F-ERR-1: without this, a `field` that never arrived surfaces as
+  // `undefined is not an object (evaluating 'field.use')` from inside `EnumFilter`, caught by
+  // `BasaltErrorBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
+  // this only ever fires on untyped JS, a `props` object built at runtime, or a store key that
+  // resolved to nothing — all three of which the message now names.
+  assertRequiredProps('SelectFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
   const { field, ...rest } = props
 
   // Two arms, one body — and they are not the same code to the compiler. `field.kind` is a NESTED

package/src/controls/slider-control.tsx

@@ -0,0 +1,159 @@
+/**
+ * `SliderControl` — a `field.number` as an inspector row (`docs/ASIDE-SPEC.md` §1 "Inspector", G7).
+ * Bound like every other control on this subpath: it takes `field`, never `value`/`onChange`/`size`
+ * (C2/C5), and `min`/`max`/`step` come off the HANDLE rather than the call site, so the track's
+ * grain is the field's own declaration and not a second copy of it.
+ *
+ * **It is a ROW on every surface, and that is deliberate.** Unlike the filters it has no pill form:
+ * a chip whose label is a number, opening a popover holding a track, is two presses to change a
+ * value the row states and edits in place. So it renders {@link PanelRow} regardless of
+ * `useFilterSurface()`, and it is not a filter — it registers no `{ isActive, reset }` with a
+ * `FilterSet`, never counts toward `Filters (n)`, and never answers `Reset all`. Its home is an
+ * aside body or a section body, not a bar row.
+ *
+ * **The write lands on drag END, not on every frame.** A slider emits a value per pointer move; on
+ * the URL lane that is one navigation per pixel. The draft is local while dragging and commits
+ * once — the same law `NumberFilter`'s stepper states for keystrokes.
+ *
+ * @example
+ * // piCycle: field.number({ fallback: 1, min: 0, max: 2, step: 0.05 })
+ * <SliderControl
+ *   field={weights.field.piCycle}
+ *   label="Pi Cycle Top"
+ *   hint="The 111DMA / 350DMA×2 crossover."
+ *   format={(v) => `${v.toFixed(2)}×`}
+ * />
+ *
+ * @example
+ * // A COMPOSITION row: the readout states the metric's own reading beside the weight, and the
+ * // switch that governs the row rides the label line — neither is the field's value, so both are
+ * // overrides rather than a `format`.
+ * <SliderControl
+ *   field={weights.field.piCycle}
+ *   label="Pi Cycle Top"
+ *   readout="0.35 · ×1.00"
+ *   end={<Switch checked={on} onChange={toggle} aria-label="Include Pi Cycle Top" />}
+ *   disabled={!on}
+ * />
+ */
+import { Slider } 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, NumberField } from '../state'
+import { PanelRow } from './panel-row'
+
+export type SliderControlProps = BasaltProps & {
+  readonly field: FieldHandle<NumberField>
+  /** The row's label, and the thumb's accessible name. */
+  readonly label: string
+  /** Info glyph + tooltip beside the label — see {@link PanelRow}. */
+  readonly hint?: string
+  /**
+   * The mono readout on the label line. The raw number when omitted, so a unit, a precision or a
+   * ratio is one function rather than a second row.
+   *
+   * @default String(v)
+   */
+  readonly format?: (v: number) => string
+  /**
+   * Replaces the formatted value in the row's readout slot.
+   *
+   * `format` prints the FIELD; this prints whatever the row is actually about. The composition row
+   * that motivated it states a metric's reading beside its weight — `0.35 · ×1.00` — which is one
+   * mono string over two numbers, only one of which this control owns. Prefer `format` whenever the
+   * readout is the field's own value. A FUNCTION form receives the live drag value, so a composed
+   * readout tracks the thumb per frame instead of updating on drag end.
+   */
+  readonly readout?: ReactNode | ((value: number) => ReactNode)
+  /**
+   * A control riding the LABEL line, forwarded to {@link PanelRow.end} — a `Switch` and, by design,
+   * almost nothing else. The composition row's use case is enabling the metric the slider weights:
+   * the toggle governs the row, so it cannot live inside the track it disables.
+   */
+  readonly end?: ReactNode
+  readonly disabled?: boolean
+}
+
+export function SliderControl(props: SliderControlProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('SliderControl', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, hint, format, readout, end, disabled, className, style } = props
+  const [value, setValue] = field.use()
+  const draft = useDraggedNumber(value, setValue)
+
+  return (
+    <PanelRow
+      label={label}
+      readout={
+        typeof readout === 'function'
+          ? readout(draft.value)
+          : (readout ?? (format ?? String)(draft.value))
+      }
+      {...(hint !== undefined && { hint })}
+      {...(end !== undefined && { end })}
+      {...(disabled === true && { disabled: true })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      <Slider
+        // The tier, stated by the control the way every control on this subpath does
+        // (`docs/CONTROLS-SPEC.md` §3) — `Slider` is deliberately absent from `CTL_THEME`, see
+        // `theme/ctl-theme.tsx`'s note, so the row's slot cannot supply it.
+        size="ctl"
+        // The drag tooltip is off: the row already prints the value, in mono, in a fixed place —
+        // a bubble that follows the thumb states the same number twice and jumps while reading.
+        label={null}
+        thumbLabel={label}
+        // The FIELD's declaration, straight off the handle. An undeclared bound leaves Mantine's own
+        // default (0..100) rather than passing `undefined` through as a bound.
+        {...(field.min !== undefined && { min: field.min })}
+        {...(field.max !== undefined && { max: field.max })}
+        {...(field.step !== undefined && { step: field.step })}
+        {...(disabled === true && { disabled: true })}
+        value={draft.value}
+        onChange={draft.set}
+        onChangeEnd={draft.commit}
+      />
+    </PanelRow>
+  )
+}
+
+/**
+ * A local draft that follows the thumb and lands on the field once, on `onChangeEnd` — plus the
+ * usual outside-change backstop (`Reset all`, a deep link, a back navigation, the codec's clamp).
+ *
+ * `seen` is what separates the two directions, exactly as in `SearchFilter`'s debounce and
+ * `NumberFilter`'s commit: it holds the last value this hook itself committed, so an incoming change
+ * it did not cause is the only thing that overwrites the draft mid-drag.
+ */
+function useDraggedNumber(
+  value: number,
+  setValue: (next: number) => void,
+): { value: number; set: (next: number) => void; commit: (next: number) => void } {
+  const [draft, setDraft] = useState(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: (next) => {
+      setDraft(next)
+      if (next === value) return
+      seen.current = next
+      commitRef.current(next)
+    },
+  }
+}

package/src/controls/sync-button.tsx

@@ -23,10 +23,12 @@
 import { ActionIcon, Button, Tooltip } from '@mantine/core'
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import { IconSlot } from '../theme/icon-slot'
 import classes from './sync-button.module.css'
 
-export type SyncButtonProps = {
+export type SyncButtonProps = BasaltProps & {
   syncing: boolean
   /** Last successful completion. `undefined`/`null` renders no age at all. */
   lastCompletedAt?: number | Date | null
@@ -134,6 +136,8 @@ export function SyncButton({
   scope,
   label = 'Sync',
   error,
+  className,
+  style,
 }: SyncButtonProps): ReactNode {
   const age = useRelativeAge(lastCompletedAt)
   // Wherever the label is not painted — every `global` mount, and a `page` mount below `sm` — the
@@ -172,7 +176,12 @@ export function SyncButton({
       withArrow
     >
       {scope === 'global' ? (
-        <ActionIcon variant="default" {...control}>
+        <ActionIcon
+          variant="default"
+          {...control}
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
+        >
           <IconSlot>
             <RefreshGlyph spinning={syncing} />
           </IconSlot>
@@ -180,7 +189,8 @@ export function SyncButton({
       ) : (
         <Button
           variant="default"
-          className={classes.pageButton}
+          className={cx(classes.pageButton, className)}
+          {...(style !== undefined && { style })}
           leftSection={
             <IconSlot>
               <RefreshGlyph spinning={syncing} />

package/src/controls/toggle-filter.tsx

@@ -1,46 +1,64 @@
 /**
  * `ToggleFilter` — a boolean field as one pill (`docs/CONTROLS-SPEC.md` §3). The only filter whose
  * pill has no popover: there is nothing to choose, so the pill IS the control and a press flips it.
- * In the sheet it becomes a `Switch` row, where a 44px row with an explicit on/off affordance reads
- * better than a chip whose state is a border colour.
+ * The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+ * Drawer") — a `PanelRow` whose control rides the label line, the ONE row every panel/sheet surface
+ * draws that way (`docs/ASIDE-SPEC.md` §3): a switch is atomic and needs no width, so the
+ * label-above law every other row follows would only cost it a second line.
  *
  * @example
  * // errorsOnly: field.boolean(false)
  * <ToggleFilter field={filters.field.errorsOnly} label="Errors only" />
  */
 import { Switch } from '@mantine/core'
+import { useId } from 'react'
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { BooleanField, FieldHandle } from '../state'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
-import { sheetRowClassNames } from './filter-sheet'
+import { PanelRow } from './panel-row'
 
-export type ToggleFilterProps = {
+export type ToggleFilterProps = BasaltProps & {
   readonly field: FieldHandle<BooleanField>
   readonly label: string
   readonly icon?: ReactNode
 }
 
-export function ToggleFilter({ field, label, icon }: ToggleFilterProps): ReactNode {
+export function ToggleFilter(props: ToggleFilterProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('ToggleFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, icon, className, style } = props
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
+  const id = useId()
   useFilterRegistration(!field.isDefault(value), () => {
-    setValue(field.fallback)
+    field.clear()
   })
 
-  if (surface === 'sheet') {
-    // The `Switch` IS the row — no wrapping div. `sheetRowClassNames` stretches its own `<label>`
-    // across the full 44px, so the whole row is the touch target rather than the middle 20px of it
-    // (C15). A wrapper div would put the height on a non-interactive box instead.
+  // The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+  // Drawer") — the switch rides the label line on both surfaces, the one row whose control does.
+  if (surface === 'panel' || surface === 'sheet') {
     return (
-      <Switch
-        classNames={sheetRowClassNames}
-        checked={value}
+      <PanelRow
         label={label}
-        labelPosition="left"
-        onChange={(event) => {
-          setValue(event.currentTarget.checked)
-        }}
+        htmlFor={id}
+        end={
+          <Switch
+            id={id}
+            aria-label={label}
+            checked={value}
+            onChange={(event) => {
+              setValue(event.currentTarget.checked)
+            }}
+          />
+        }
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
       />
     )
   }
@@ -55,6 +73,8 @@ export function ToggleFilter({ field, label, icon }: ToggleFilterProps): ReactNo
       onClick={() => {
         setValue(!value)
       }}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     />
   )
 }

package/src/controls/view-tabs.tsx

@@ -6,12 +6,17 @@
  * The responsive swap lives HERE, not at the call site (C9), and it is CSS — `visibleFrom` /
  * `hiddenFrom`, one mount each, never a JS media query (which renders differently on the server than
  * on the first client paint). Below `sm` a set of three or fewer stays a full-width
- * `SegmentedControl`; past that a track cannot hold readable labels on a phone, so it becomes a
+ * `SegmentedControl` — PROVIDED every label actually fits it (`panel-row.tsx`'s `useTrackFits`,
+ * shared with `PanelChoice` so the two width gates cannot drift); past either gate it becomes a
  * `Select`.
  *
  * `only` is how a tab that exists on ONE viewport is declared instead of hand-rolling a second
  * control: `'sm-up'` keeps it off the phone form, `'sm-down'` keeps it off the desktop form.
  *
+ * Inside a `PageAside` it renders as a panel ROW — label above, a full-width track or a `Select`
+ * (`docs/ASIDE-SPEC.md` §3). A view switch in a panel is legal; the page bar's tab slot stays its
+ * default home, and `only` has no meaning there (the panel is one width).
+ *
  * @example
  * <ViewTabs
  *   field={strength.field.tab}
@@ -24,8 +29,14 @@
  */
 import { SegmentedControl, Select } from '@mantine/core'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { EnumField, FieldHandle } from '../state'
 import classes from './controls.module.css'
+import { useFilterSurface } from './filter-context'
+import { useControlName } from './filter-sheet'
+import { PanelChoice, PanelRow, useTrackFits } from './panel-row'
 
 /** Past three options the phone form is a `Select`, not a track. */
 const PHONE_TRACK_MAX = 3
@@ -37,7 +48,7 @@ export type ViewTabsOption<T extends string> = {
   readonly only?: 'sm-up' | 'sm-down'
 }
 
-export type ViewTabsProps<T extends string> = {
+export type ViewTabsProps<T extends string> = BasaltProps & {
   readonly field: FieldHandle<EnumField<T>>
   /** Defaults to `field.options` (every declared value, labelled by `store.labels()`). */
   readonly options?: readonly ViewTabsOption<T>[]
@@ -51,12 +62,17 @@ export type ViewTabsProps<T extends string> = {
   readonly label?: string
 }
 
-export function ViewTabs<T extends string>({
-  field,
-  options,
-  label = 'View',
-}: ViewTabsProps<T>): ReactNode {
+export function ViewTabs<T extends string>(props: ViewTabsProps<T>): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('ViewTabs', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, options, label = 'View', className, style } = props
   const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const inPanel = surface === 'panel'
+  const { labelId, nameProps } = useControlName(label, inPanel)
   const all: readonly ViewTabsOption<T>[] =
     options ?? field.options.map((option) => ({ value: option.value as T, label: option.label }))
 
@@ -68,6 +84,36 @@ export function ViewTabs<T extends string>({
     setValue(next as T)
   }
 
+  const phoneData = phone.map((option) => ({ value: option.value, label: option.label }))
+  const phoneCountFits = phone.length <= PHONE_TRACK_MAX
+  // Called UNCONDITIONALLY, even on the panel branch that never renders the phone form — a hook
+  // may not sit behind the `if (inPanel) return …` below (`react-hooks/rules-of-hooks`), and
+  // `useTrackFits` no-ops cheaply when `countFits` is false or its root never mounts. The same
+  // width gate `PanelChoice` runs (`panel-row.tsx`'s `useTrackFits` doc) — the count cap is the
+  // cheap first gate, a fit check underneath it is what actually decides.
+  const { rootRef: phoneRootRef, fits: phoneFits } = useTrackFits(
+    phoneCountFits,
+    phoneData.map((d) => d.value).join('|'),
+  )
+
+  // The panel form. `only` is dropped on purpose: it exists to declare a tab that belongs to ONE
+  // viewport, and a panel is not a viewport — every declared option is offered.
+  if (inPanel) {
+    return (
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
+        <PanelChoice nameProps={nameProps} value={value} options={all} onChange={commit} />
+      </PanelRow>
+    )
+  }
+
+  // No single root: exactly one of the two forms below is visible at once (CSS `visibleFrom`/
+  // `hiddenFrom`, law C9), so `className`/`style` land on both — whichever one paints is the one a
+  // reader ever sees carrying them.
   return (
     <>
       <SegmentedControl
@@ -77,16 +123,21 @@ export function ViewTabs<T extends string>({
         value={value}
         data={desktop.map((option) => ({ value: option.value, label: option.label }))}
         onChange={commit}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
       />
-      {phone.length <= PHONE_TRACK_MAX ? (
+      {phoneFits ? (
         <SegmentedControl
+          ref={phoneRootRef}
           aria-label={label}
           hiddenFrom="sm"
           size="ctl"
           fullWidth
           value={value}
-          data={phone.map((option) => ({ value: option.value, label: option.label }))}
+          data={phoneData}
           onChange={commit}
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
         />
       ) : (
         <Select
@@ -96,10 +147,11 @@ export function ViewTabs<T extends string>({
           // BOUNDED, not greedy — see `.phoneSelect`'s comment in `controls.module.css`. This is the
           // control owning its own responsive form (law C9), which is also why it is not a `w` prop
           // at the call site (C5, `basalt/control-size-literal`).
-          className={classes.phoneSelect}
+          className={cx(classes.phoneSelect, className)}
+          {...(style !== undefined && { style })}
           value={value}
           allowDeselect={false}
-          data={phone.map((option) => ({ value: option.value, label: option.label }))}
+          data={phoneData}
           onChange={(next) => {
             if (next !== null) commit(next)
           }}

package/src/controls-dates/date-range-picker.tsx

@@ -24,9 +24,16 @@
  */
 import { DatePicker } from '@mantine/dates'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../common/validate'
 import type { RangeCustomPickerProps } from '../controls/range-filter'
 
-export function DateRangePicker({ value, onChange }: RangeCustomPickerProps): ReactNode {
+export function DateRangePicker(props: RangeCustomPickerProps): ReactNode {
+  // F-ERR-1 — without this a missing `value` surfaces as `undefined is not an object
+  // (evaluating 'value.from')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('DateRangePicker', props, ['value'], {
+    value: "pass `{ from, to }` — usually injected by `RangeFilter`'s `customPicker`.",
+  })
+  const { value, onChange } = props
   return (
     <DatePicker
       type="range"

package/src/dashboard/delta-badge.tsx

@@ -2,5 +2,9 @@
  * `DeltaBadge` moved to `src/widget-header/` (docs/CONTROLS-SPEC.md §2.2) so `WidgetHeader` can
  * compose it Mantine-free. Re-exported here unchanged so this deep import path — and `StatCard`'s
  * own `./delta-badge` import — keep working without a wave-3 edit.
+ *
+ * `basalt-ui/widget-header` is canonical — this alias exists only so `basalt-ui/dashboard`-style
+ * deep imports keep resolving; the root barrel (`src/index.ts`) sources `DeltaBadge` from
+ * `../widget-header`, not from here.
  */
-export { DeltaBadge, type DeltaBadgeProps } from '../widget-header/delta-badge'
+export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from '../widget-header/delta-badge'