basalt-ui 1.26.0 → 1.28.0

package/src/controls/multi-select-filter.tsx

@@ -16,17 +16,30 @@
  *   label="All channels"
  *   options={CHANNELS.map((c) => ({ value: c, label: `${c} · ${counts[c]}` }))}
  * />
+ *
+ * @example
+ * // The aside's facet column (`docs/ASIDE-SPEC.md` §1): counts and their bars are DATA, so they
+ * // arrive as a map rather than baked into the labels the way the runtime catalogue does it.
+ * <MultiSelectFilter field={shipments.field.origin} label="Origin" counts={countsByOrigin} />
  */
 import { Button, Checkbox, Stack } from '@mantine/core'
-import type { ReactNode } from 'react'
+import { useState } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { FieldHandle, MultiField } from '../state'
 import type { FilterOption } from './select-filter'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
-import { SheetField, SheetOptionList, useControlName } from './filter-sheet'
+import { CheckGlyph, useControlName } from './filter-sheet'
+import { PanelRow } from './panel-row'
 
-export type MultiSelectFilterProps<T extends string> = {
+/** How many facet rows a panel shows before the rest fold behind `Show N more`. Six is the point at
+ *  which a facet column stops being a list you scan and starts being one you scroll. */
+const PANEL_FACET_MAX = 6
+
+export type MultiSelectFilterProps<T extends string> = BasaltProps & {
   readonly field: FieldHandle<MultiField<T>>
   readonly label: string
   readonly icon?: ReactNode
@@ -43,49 +56,75 @@ export type MultiSelectFilterProps<T extends string> = {
    * string-field shape to make it required.
    */
   readonly options?: readonly FilterOption[]
+  /**
+   * Per-option counts, rendered on the `panel` surface as a mono number plus a bar proportional to
+   * the LARGEST count in the map — the Foundry facet column (`docs/ASIDE-SPEC.md` §1). A missing
+   * key is a row with no count and no bar, not a zero.
+   *
+   * Ignored on the pill and sheet surfaces, where there is no room for a second data channel: put
+   * the number in the label there (`options`).
+   */
+  readonly counts?: Record<string, number>
+  /**
+   * How many facet rows the `panel` surface shows before the rest fold behind a `Show N more` row.
+   *
+   * @default 6
+   */
+  readonly max?: number
 }
 
-export function MultiSelectFilter<T extends string>({
-  field,
-  label,
-  icon,
-  noun,
-  options: optionsProp,
-}: MultiSelectFilterProps<T>): ReactNode {
+export function MultiSelectFilter<T extends string>(props: MultiSelectFilterProps<T>): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('MultiSelectFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, icon, noun, counts, max, options: optionsProp, className, style } = props
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
   const isDefault = field.isDefault(value)
   useFilterRegistration(!isDefault, () => {
-    setValue(field.fallback)
+    field.clear()
   })
 
   // The prop wins whole, never merged — same rule as `EnumFilter`: a catalogue that dropped a row
   // must be able to drop it, and `All channels` is counted against the rows actually shown.
   const options: readonly FilterOption[] = optionsProp ?? field.options
   const inSheet = surface === 'sheet'
+  const inPanel = surface === 'panel'
   const carriesInformation = value.length > 0 && value.length < options.length
-  const { labelId } = useControlName(label, inSheet)
+  const { labelId } = useControlName(label, inSheet || inPanel)
+
+  // One toggle, shared by both list forms — the rows are rendered from `options`, whose values
+  // belong to the field either way (the prop relabels a closed set, it cannot open it), so the cast
+  // restores what the codec already guarantees.
+  const toggle = (next: string): void => {
+    const has = value.includes(next as T)
+    setValue(has ? value.filter((v) => v !== next) : [...value, next as T])
+  }
 
-  // The SHEET form is a `SheetOptionList` in `multi` mode — 44px rows, a trailing check on each
-  // selected one, hairlines between rows only. Same reasoning as `EnumFilter`: the popover keeps
-  // Mantine's `Checkbox.Group`, the sheet reads as a list of options rather than a stack of boxes.
-  if (inSheet) {
+  // The SHEET form is the PANEL form — the facet column (`docs/CONTROLS-SPEC.md` §3: "sheet = panel
+  // rows inside a Drawer"). It used to render a `SheetOptionList` in `multi` mode (44px rows, a
+  // trailing check, no fold), which meant a set with many options was a sheet as tall as the set;
+  // the facet column folds past `max` behind `Show N more` instead, which is the shape a set of
+  // unknown size actually needs.
+  if (inSheet || inPanel) {
     return (
-      <SheetField label={label} labelId={labelId}>
-        <SheetOptionList
-          mode="multi"
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
+        <FacetList
           labelId={labelId}
-          selected={value}
           options={options}
-          onToggle={(next) => {
-            // The rows are rendered from `options`, whose values belong to the field either way (the
-            // prop relabels a closed set, it cannot open it) — the cast restores what the codec
-            // already guarantees.
-            const has = value.includes(next as T)
-            setValue(has ? value.filter((v) => v !== next) : [...value, next as T])
-          }}
+          selected={value}
+          max={max ?? PANEL_FACET_MAX}
+          onToggle={toggle}
+          {...(counts !== undefined && { counts })}
         />
-      </SheetField>
+      </PanelRow>
     )
   }
 
@@ -119,7 +158,7 @@ export function MultiSelectFilter<T extends string>({
           variant="subtle"
           size="ctl"
           onClick={() => {
-            setValue(field.fallback)
+            field.clear()
           }}
         >
           Clear
@@ -133,8 +172,119 @@ export function MultiSelectFilter<T extends string>({
       label={carriesInformation ? `${value.length} ${noun ?? label.toLowerCase()}` : label}
       active={!isDefault}
       {...(icon !== undefined && { icon })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       <div className={classes.optionList}>{body}</div>
     </FilterPill>
   )
 }
+
+type FacetListProps = {
+  readonly labelId: string
+  readonly options: readonly FilterOption[]
+  readonly selected: readonly string[]
+  readonly counts?: Record<string, number>
+  /** Rows shown before the rest fold behind `Show N more`. */
+  readonly max: number
+  readonly onToggle: (value: string) => void
+}
+
+/**
+ * The facet column's rows. INTERNAL to this control: a list of counted checkboxes not bound to a
+ * `field.multi` is a hand-rolled filter (`basalt/hand-rolled-filter`), so there is no separate
+ * `FacetList` export to reach for — the counts are a prop on the control that already owns the set.
+ *
+ * The bar is scaled against the LARGEST count present, not against a total: a facet column is read
+ * as a comparison between its own rows, and dividing by a total nobody supplied would render every
+ * bar as a sliver on a set with many options.
+ */
+function FacetList({
+  labelId,
+  options,
+  selected,
+  counts,
+  max,
+  onToggle,
+}: FacetListProps): ReactNode {
+  const [expanded, setExpanded] = useState(false)
+  const shown = expanded ? options : options.slice(0, max)
+  const hidden = options.length - shown.length
+  // `0` as the seed, so an empty map (or one whose keys miss every option) yields a peak of 0 rather
+  // than `-Infinity`, and every bar resolves to a width of 0 instead of `NaN%`.
+  const peak = options.reduce((top, option) => Math.max(top, counts?.[option.value] ?? 0), 0)
+
+  return (
+    // A real `<fieldset>` named by the row's own label — the native element carries the grouping
+    // semantics, and the heading is already visible.
+    <fieldset className={classes.facetList} aria-labelledby={labelId}>
+      {shown.map((option) => {
+        const isSelected = selected.includes(option.value)
+        const count = counts?.[option.value]
+        return (
+          <label
+            key={option.value}
+            className={classes.facetOption}
+            {...(isSelected && { 'data-selected': true })}
+            {...(option.disabled === true && { 'data-disabled': true })}
+          >
+            {/* theme-allow raw-form-control — the input is NEVER PAINTED. Visually hidden
+                (`.facetInput`), it exists only to carry the row's semantics; the surface the reader
+                sees and clicks is the `<label>` around it. */}
+            <input
+              className={classes.facetInput}
+              type="checkbox"
+              value={option.value}
+              checked={isSelected}
+              disabled={option.disabled === true}
+              aria-label={option.label}
+              onChange={() => {
+                onToggle(option.value)
+              }}
+            />
+            {count === undefined ? (
+              // No count/bar on this row — without a visible box, an unselected row was plain
+              // text with no affordance that it toggles at all (only a checkmark appeared, and
+              // only once selected). `size="ctl"` reads `--checkbox-size-ctl`
+              // (`theme/index.ts`'s `ctlSizeVars`), the same var every other home's `Checkbox`
+              // resolves through. Decorative — the real toggle semantics live on `.facetInput`.
+              <Checkbox.Indicator
+                className={classes.facetCheckbox}
+                size="ctl"
+                checked={isSelected}
+                aria-hidden
+                {...(option.disabled === true && { disabled: true })}
+              />
+            ) : (
+              peak > 0 && (
+                <span
+                  className={classes.facetBar}
+                  aria-hidden
+                  style={{ '--facet-fill': `${(count / peak) * 100}%` } as CSSProperties}
+                />
+              )
+            )}
+            <span className={classes.facetLabel}>{option.label}</span>
+            {count !== undefined && <span className={classes.facetCount}>{count}</span>}
+            {count !== undefined && isSelected && (
+              <span className={classes.facetCheck} aria-hidden>
+                <CheckGlyph />
+              </span>
+            )}
+          </label>
+        )
+      })}
+      {hidden > 0 && (
+        <button
+          type="button"
+          className={classes.facetMore}
+          onClick={() => {
+            setExpanded(true)
+          }}
+        >
+          {`Show ${hidden} more`}
+        </button>
+      )}
+    </fieldset>
+  )
+}

package/src/controls/number-filter.tsx

@@ -0,0 +1,329 @@
+/**
+ * `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`/`step` come off the HANDLE, never the call site.**
+ * `field.number({ min, max, int, step })` declares them, the codec clamps to them on write, and the
+ * handle republishes all four — so the `NumberInput` bounds its own stepper and `int` refuses
+ * decimals outright. Three of them 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}).
+ *
+ * `step` survives as a prop only because a call site may legitimately want a COARSER grain than the
+ * field's (a 0..600 seconds threshold stepping by 30), and it now DEFAULTS to `field.step` — the
+ * resolved one, so `int: true` still implies 1 with the rule stated once, in `field.number`.
+ *
+ * @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 { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+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 { useControlName } from './filter-sheet'
+import { PanelRow } from './panel-row'
+
+/** 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 = BasaltProps & {
+  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, overriding the field's own. Ignored in the `options` form, which has
+   * no stepper.
+   *
+   * @default `field.step` — the field's declared grain, which is `1` for an `int: true` field that
+   * declared none. Absent on both, the input keeps Mantine's own default of 1.
+   */
+  readonly step?: number
+}
+
+export function NumberFilter(props: NumberFilterProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('NumberFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, icon, options, step, className, style } = props
+  // 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 })}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      />
+    )
+  }
+  // The prop wins over the field's declared grain; `field.step` is the default, so an `int` field
+  // steps by 1 with nothing written here (see `NumberFilterProps.step`).
+  const grain = step ?? field.step
+  return (
+    <NumberStepper
+      field={field}
+      label={label}
+      {...(icon !== undefined && { icon })}
+      {...(grain !== undefined && { step: grain })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    />
+  )
+}
+
+/**
+ * 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/panel `PanelChoice`, 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,
+  className,
+  style,
+}: BasaltProps & {
+  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 })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    />
+  )
+}
+
+/** The stepper form — a pill holding a `ctl` `NumberInput`, or a full-width sheet row. */
+function NumberStepper({
+  field,
+  label,
+  icon,
+  step,
+  className,
+  style,
+}: BasaltProps & {
+  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 inPanel = surface === 'panel'
+  const { labelId, nameProps } = useControlName(label, inSheet || inPanel)
+  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 })}
+      // Already resolved by `NumberFilter` — the prop, else the field's own grain.
+      {...(step !== undefined && { step })}
+      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()
+      }}
+    />
+  )
+
+  // 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 (inPanel || inSheet) {
+    return (
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
+        {input}
+      </PanelRow>
+    )
+  }
+
+  return (
+    <FilterPill
+      label={String(value)}
+      numeric
+      active={!isDefault}
+      {...(icon !== undefined && { icon })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      <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/panel-row.module.css

@@ -0,0 +1,86 @@
+/*
+ * The `panel` surface's row skeleton (`docs/ASIDE-SPEC.md` §1, §3) — the inspector archetype's
+ * geometry, and nothing else.
+ *
+ * **Label ABOVE, never beside (G4).** At an aside's ~300px a label, a control and a readout on one
+ * line leave the control ~90px, which for a 20-step slider is under 12px per step. So the row is two
+ * lines: a head line (label · hint · readout, or label · a `Switch`) and a full-width control line.
+ * The toggle is the one exception, because a switch beside a label costs nothing and a switch on its
+ * own line reads as a second control.
+ *
+ * Rows separate with a `--vx-divider` hairline rather than sitting in cards — Lightroom, not a
+ * dashboard (`docs/ASIDE-SPEC.md` §3). The vertical inset is `--vx-space-row-inset-y` (6), the
+ * INSPECTOR row's, deliberately not `--vx-space-settings-row-inset-y` (10), which belongs to a
+ * settings FORM row and is nearly twice the height in a column that has none to spare.
+ */
+
+.row {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs, 0.25rem);
+  min-width: 0;
+  padding-block: var(--vx-space-row-inset-y);
+}
+
+/* Between rows only — never above the first or below the last, where the aside's own section
+ * chrome already draws the boundary. */
+.row + .row {
+  border-top: 1px solid var(--vx-divider);
+}
+
+/* `disabled` dims the BODY, it does not remove it: an inspector row that is off still states what it
+ * would control, and the control inside keeps its own `disabled` semantics. */
+.row[data-disabled] {
+  opacity: 0.55;
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+  min-width: 0;
+}
+
+.label {
+  font-size: var(--vx-text-xs);
+  font-weight: 550;
+  color: var(--vx-ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * The readout is MONO and right-aligned: it is a number that changes while a thumb is dragged, and a
+ * proportional face would reflow the head line on every frame. `margin-inline-start: auto` is what
+ * pushes it (or, in a toggle row, the `end` control) to the trailing edge without a spacer element.
+ */
+.readout {
+  margin-inline-start: auto;
+  flex: none;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--vx-muted);
+}
+
+.end {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  margin-inline-start: auto;
+}
+
+/* A readout AND an `end` control: the readout already took the auto margin, so the control just
+ * follows it across the gap. */
+.readout + .end {
+  margin-inline-start: 0;
+}
+
+/* Column flex, so a control with no width of its own fills the row rather than shrinking to its
+ * content — the row IS the width, which is why no control in it carries a `w` (law C5). */
+.control {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}