basalt-ui 1.27.0 → 1.29.0

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), () => {
     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

@@ -1,6 +1,77 @@
 /**
- * `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.
+ * DeltaBadge — the KPI trend chip (docs/DESIGN-SPEC.md §5): mono 11.5px weight 600, status-color
+ * text on a status-13% tint, control radius, 2px/7px padding, optional ▲/▼ glyph at 9px.
+ * `polarity` decides the TONE the sign maps to — `'up-good'` (default) reads a rise as success and
+ * a fall as danger; `'up-bad'` inverts that for a metric where a rise is the worse reading (a
+ * cycle-top index, latency, error rate); `'neutral'` renders every sign in a faint, non-verdict
+ * tint. Zero is always faint with no glyph, under every polarity. The label never carries a
+ * leading "+"; pass `format` to control the magnitude string (defaults to a one-decimal percentage
+ * of the absolute value). The ▲/▼ glyph is DIRECTION, not verdict, and stays polarity-independent —
+ * governed only by `withGlyph` and the sign.
+ *
+ * Mantine-free (plain `<span>` + this folder's CSS module, docs/CONTROLS-SPEC.md §2.2) so
+ * `WidgetHeader` can compose it from inside `charts/` without tripping `basalt/token-layer-
+ * boundary` or `check-dist-layering.mjs`.
+ *
+ * @example
+ * import { DeltaBadge } from 'basalt-ui'
+ *
+ * <DeltaBadge value={12.4} />                          // ▲ 12.4%, success tint
+ * <DeltaBadge value={-3.1} />                           // ▼ 3.1%, danger tint
+ * <DeltaBadge value={0} />                              // 0.0%, neutral faint tint, no glyph
+ * <DeltaBadge value={182} format={(v) => `${Math.abs(v)}ms`} withGlyph={false} />
+ * <DeltaBadge value={35.9} polarity="up-bad" />         // ▲ 35.9%, danger tint — a rise is bad here
  */
-export { DeltaBadge, type DeltaBadgeProps } from '../widget-header/delta-badge'
+import { alpha, VX } from '../tokens'
+import classes from './widget-header.module.css'
+
+export type DeltaPolarity = 'up-good' | 'up-bad' | 'neutral'
+
+export type DeltaBadgeProps = {
+  /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
+  value: number
+  /** Which sign reads as the good verdict. `'up-good'` (default) is today's behaviour — positive
+   * success, negative danger. `'up-bad'` inverts it for a metric where a rise is the worse reading.
+   * `'neutral'` renders every sign in the faint tint — a change with no verdict attached. Zero is
+   * always faint regardless. */
+  polarity?: DeltaPolarity
+  /** Formats the value into the label text. Defaults to `${Math.abs(value).toFixed(1)}%`. */
+  format?: (value: number) => string
+  /** Render the ▲/▼ direction glyph. Defaults to `true`; a zero value never shows a glyph. */
+  withGlyph?: boolean
+  /** Optional comparison timeframe rendered directly after the value in a dimmer shade of the same
+   * tone (e.g. `MoM`, `WoW`, `YTD`) — states what the delta is measured against without a hover. */
+  period?: string | undefined
+}
+
+const defaultFormat = (value: number): string => `${Math.abs(value).toFixed(1)}%`
+
+function resolveTone(value: number, polarity: DeltaPolarity): string {
+  if (value === 0 || polarity === 'neutral') return VX.faint
+  const rose = value > 0
+  const good = polarity === 'up-good' ? rose : !rose
+  return good ? VX.status.good : VX.status.bad
+}
+
+export function DeltaBadge({
+  value,
+  polarity = 'up-good',
+  format = defaultFormat,
+  withGlyph = true,
+  period,
+}: DeltaBadgeProps) {
+  const tone = resolveTone(value, polarity)
+  const glyph = value > 0 ? '▲' : value < 0 ? '▼' : undefined
+  const showGlyph = withGlyph && glyph !== undefined
+
+  return (
+    <span
+      className={classes.deltaBadge}
+      style={{ backgroundColor: alpha(tone, 0.13), color: tone }}
+    >
+      {showGlyph && <span className={classes.deltaGlyph}>{glyph}</span>}
+      {format(value)}
+      {period !== undefined && <span className={classes.deltaPeriod}>{period}</span>}
+    </span>
+  )
+}