basalt-ui 1.27.0 → 1.29.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,15 +56,30 @@ 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)
@@ -63,29 +91,40 @@ export function MultiSelectFilter<T extends string>({
   // 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>
     )
   }
 
@@ -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

@@ -21,14 +21,18 @@
  * `SearchFilter` debounces for the same reason; a number has an explicit commit point (leaving the
  * field, pressing Enter) and a phrase does not, so this one commits rather than waits.
  *
- * **`min`/`max`/`int` come off the HANDLE, never the call site.** `field.number({ min, max, int })`
- * declares them, the codec clamps to them on write, and the handle republishes all three — so the
- * `NumberInput` bounds its own stepper and `int` refuses decimals outright. They are not props here
- * on purpose: they belong to the field, which is the thing that validates the URL, and a second copy
- * at the call site is a second answer to the same question that stops matching the moment the field
- * moves. The clamp is still the backstop for a value that arrives from outside the input (a
- * hand-typed URL, a stale deep link), and the draft follows the field down when it fires (see
- * {@link useCommittedNumber}).
+ * **`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.
@@ -51,13 +55,16 @@
 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 { SheetField, useControlName } from './filter-sheet'
+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. */
@@ -66,7 +73,7 @@ export type NumberFilterOption = {
   readonly label: string
 }
 
-export type NumberFilterProps = {
+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). */
@@ -75,15 +82,22 @@ export type NumberFilterProps = {
   /** Present → the radio-list form. Absent → the stepper form. */
   readonly options?: readonly NumberFilterOption[]
   /**
-   * The stepper's increment. Ignored in the `options` form, which has no stepper.
+   * The stepper's increment, overriding the field's own. Ignored in the `options` form, which has
+   * no stepper.
    *
-   * @default 1 — and for an `int: true` field that is also the only sane grain, so it is what the
-   * field's own declaration produces without this prop.
+   * @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({ field, label, icon, options, step }: NumberFilterProps): ReactNode {
+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.
@@ -94,15 +108,22 @@ export function NumberFilter({ field, label, icon, options, step }: NumberFilter
         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 })}
-      {...(step !== undefined && { step })}
+      {...(grain !== undefined && { step: grain })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     />
   )
 }
@@ -110,7 +131,7 @@ export function NumberFilter({ field, label, icon, options, step }: NumberFilter
 /**
  * The `options` form. It renders no radio list of its own — it ADAPTS the number handle into
  * `EnumFilter`'s `ChoiceHandle<string>` and hands it over, so the popover's `Radio.Group`, the
- * sheet's `SheetOptionList`, the registration and the pill readout are the ones already tested for
+ * 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'`),
@@ -126,7 +147,9 @@ function NumberChoice({
   label,
   icon,
   options,
-}: {
+  className,
+  style,
+}: BasaltProps & {
   readonly field: FieldHandle<NumberField>
   readonly label: string
   readonly icon?: ReactNode
@@ -160,6 +183,8 @@ function NumberChoice({
       numeric
       options={rows}
       {...(icon !== undefined && { icon })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     />
   )
 }
@@ -170,7 +195,9 @@ function NumberStepper({
   label,
   icon,
   step,
-}: {
+  className,
+  style,
+}: BasaltProps & {
   readonly field: FieldHandle<NumberField>
   readonly label: string
   readonly icon?: ReactNode
@@ -183,7 +210,8 @@ function NumberStepper({
   useFilterRegistration(!isDefault, () => {
     field.clear()
   })
-  const { labelId, nameProps } = useControlName(label, inSheet)
+  const inPanel = surface === 'panel'
+  const { labelId, nameProps } = useControlName(label, inSheet || inPanel)
   const draft = useCommittedNumber(value, setValue, { min: field.min, max: field.max })
 
   const input = (
@@ -198,7 +226,8 @@ function NumberStepper({
       // `int: true` is refused by the codec, not rounded, so the input must refuse it too — a `.5`
       // typed into an integer field would otherwise decode to `null` and resurrect the fallback.
       {...(field.int && { allowDecimal: false })}
-      {...(step !== undefined ? { step } : field.int && { step: 1 })}
+      // Already resolved by `NumberFilter` — the prop, else the field's own grain.
+      {...(step !== undefined && { step })}
       value={draft.value}
       onChange={draft.set}
       onBlur={draft.commit}
@@ -212,11 +241,18 @@ function NumberStepper({
     />
   )
 
-  if (inSheet) {
+  // 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 (
-      <SheetField label={label} labelId={labelId}>
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
         {input}
-      </SheetField>
+      </PanelRow>
     )
   }
 
@@ -226,6 +262,8 @@ function NumberStepper({
       numeric
       active={!isDefault}
       {...(icon !== undefined && { icon })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       <div className={classes.optionList}>{input}</div>
     </FilterPill>

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;
+}

package/src/controls/panel-row.module.css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly row: string
+  readonly head: string
+  readonly label: string
+  readonly readout: string
+  readonly end: string
+  readonly control: string
+}
+export default classes