basalt-ui 1.25.0 → 1.27.0

package/src/controls/filter-sheet.tsx

@@ -0,0 +1,285 @@
+/**
+ * The mobile `Filters (n)` sheet and the two row primitives every control's sheet form composes
+ * (`docs/CONTROLS-SPEC.md` §2.1/§3). A bottom `Drawer`: every child of the `FilterSet` renders its
+ * full-width sheet form, edits APPLY IMMEDIATELY (there is no Apply button — the URL is the truth
+ * and a filter write is already `history: 'replace'`), and one `Reset all` footer clears every
+ * registered filter.
+ *
+ * 44px rows are the one sheet dimension C15 pins, so they come from
+ * `--vx-space-sheet-row-height` — the density-tracking token, not a literal.
+ *
+ * INTERNAL, like `FilterPill`: `FilterSet` owns when the sheet opens, so a consumer mounting it by
+ * hand would own a second, unregistered filter home (C1).
+ */
+import { Button, Drawer } from '@mantine/core'
+import { useId } from 'react'
+import type { ReactNode } from 'react'
+import classes from './controls.module.css'
+
+export type FilterSheetProps = {
+  readonly opened: boolean
+  readonly onClose: () => void
+  readonly onResetAll: () => void
+  readonly title?: string
+  readonly children: ReactNode
+}
+
+/**
+ * `Reset all` rides the HEADER, beside the title and the close ×, not a footer.
+ *
+ * A bottom drawer's footer is the one region a phone cannot promise is on screen: the sheet grows
+ * with its content, so with six filters open the reset button sat below the fold and the only way to
+ * reach it was to scroll past every row it would have undone. The header is fixed by construction.
+ * It also removes the sheet's last horizontal rule — a footer needs separating from the rows above
+ * it, a header does not (`docs/CONTROLS-SPEC.md` §2.1: hairlines between OPTION rows only).
+ */
+export function FilterSheet({
+  opened,
+  onClose,
+  onResetAll,
+  title = 'Filters',
+  children,
+}: FilterSheetProps): ReactNode {
+  return (
+    <Drawer
+      opened={opened}
+      onClose={onClose}
+      position="bottom"
+      radius="sm"
+      classNames={{ header: classes.sheetHeader, title: classes.sheetTitle }}
+      title={
+        <>
+          <span className={classes.sheetTitleText}>{title}</span>
+          <Button variant="subtle" size="ctl" onClick={onResetAll}>
+            Reset all
+          </Button>
+        </>
+      }
+    >
+      <div className={classes.sheetBody}>{children}</div>
+    </Drawer>
+  )
+}
+
+/** The selected-row mark — 16px, drawn at the row's trailing edge (`docs/CONTROLS-SPEC.md` §2.1). */
+function CheckGlyph(): ReactNode {
+  return (
+    <svg
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.25}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M5 12.5l5 5l9 -11" />
+    </svg>
+  )
+}
+
+/** One row of a {@link SheetOptionList}. */
+export type SheetOption = {
+  readonly value: string
+  readonly label: string
+  readonly disabled?: boolean
+}
+
+export type SheetOptionListProps = {
+  /** `single` renders radio semantics, `multi` checkbox semantics. */
+  readonly mode: 'single' | 'multi'
+  /** The selected value(s) — a one-element array in `single` mode. */
+  readonly selected: readonly string[]
+  readonly options: readonly SheetOption[]
+  readonly onToggle: (value: string) => void
+  /** The `SheetField` heading this list is named by. */
+  readonly labelId: string
+}
+
+/**
+ * The sheet's ONE list form (`docs/CONTROLS-SPEC.md` §2.1): every option is a 44px full-width row,
+ * label left, a check at the trailing edge when selected, a 1px hairline between rows and nowhere
+ * else.
+ *
+ * **It replaced a `SegmentedControl` and a Mantine `Radio` list, for two different reasons.** The
+ * range presets rendered as a `orientation="vertical"` SegmentedControl, which in a full-width sheet
+ * is a stack of left-aligned labels inside a tinted track — it read as a broken control, not as a
+ * choice, and it carried the track's own inset so it aligned with nothing else in the sheet. The
+ * enum/multi filters rendered Mantine `Radio`/`Checkbox` rows, which put a 20px dot or box in the
+ * leading position of every row; at six filters the sheet was a column of controls rather than a
+ * column of options, and the leading marks pushed every label off the sheet's own text column.
+ *
+ * The semantics are a real native `<input>` inside the row's `<label>`, visually hidden — not
+ * `role="radio"` on a div. A hidden native input keeps the arrow-key group behaviour, the
+ * form-association and the announced state for free, and `<label>` wrapping it makes the whole 44px
+ * box the hit target (C15) without a single `onClick` on a non-interactive element.
+ */
+export function SheetOptionList({
+  mode,
+  selected,
+  options,
+  onToggle,
+  labelId,
+}: SheetOptionListProps): ReactNode {
+  // ONE name per rendered list, so a sheet holding two range filters keeps two radio groups.
+  const name = useId()
+  return (
+    // A real `<fieldset>`, not `role="group"` on a div — the native element carries the grouping
+    // semantics and gets its own box reset in the module (`.sheetList`). `aria-labelledby` points at
+    // the `SheetField` heading rather than a `<legend>`: the heading is already visible above the
+    // list, and a legend would render it a second time.
+    <fieldset className={classes.sheetList} aria-labelledby={labelId}>
+      {options.map((option) => {
+        const isSelected = selected.includes(option.value)
+        return (
+          <label
+            key={option.value}
+            className={classes.sheetOption}
+            {...(isSelected && { 'data-selected': true })}
+            {...(option.disabled === true && { 'data-disabled': true })}
+          >
+            {/* theme-allow raw-form-control — the input is NEVER PAINTED. It is visually hidden
+                (`.sheetOptionInput`) and exists only to carry the row's semantics: the checked state,
+                the radio-group arrow keys, the announced name. The surface the reader sees and taps
+                is the `<label>` around it, which the theme's tokens style directly. A Mantine
+                `Radio` here would paint the 20px indicator this row form exists to remove — see
+                `SheetOptionList`'s doc. */}
+            <input
+              className={classes.sheetOptionInput}
+              type={mode === 'single' ? 'radio' : 'checkbox'}
+              name={name}
+              value={option.value}
+              checked={isSelected}
+              disabled={option.disabled === true}
+              aria-label={option.label}
+              onChange={() => {
+                onToggle(option.value)
+              }}
+            />
+            <span className={classes.sheetOptionLabel}>{option.label}</span>
+            {isSelected && (
+              <span className={classes.sheetOptionCheck} aria-hidden>
+                <CheckGlyph />
+              </span>
+            )}
+          </label>
+        )
+      })}
+    </fieldset>
+  )
+}
+
+export type SheetDisclosureProps = {
+  readonly label: string
+  readonly expanded: boolean
+  readonly onToggle: () => void
+  readonly children: ReactNode
+}
+
+/**
+ * A 44px row that expands its own body inline — the sheet's answer to a control too large to sit in
+ * the list unconditionally (`RangeFilter`'s custom date picker, which is a whole calendar). Same row
+ * geometry as a {@link SheetOptionList} option, so the disclosure reads as the list's last entry
+ * rather than as a different kind of thing.
+ */
+export function SheetDisclosure({
+  label,
+  expanded,
+  onToggle,
+  children,
+}: SheetDisclosureProps): ReactNode {
+  return (
+    <div className={classes.sheetList}>
+      <button
+        type="button"
+        className={classes.sheetOption}
+        aria-expanded={expanded}
+        {...(expanded && { 'data-selected': true })}
+        onClick={onToggle}
+      >
+        <span className={classes.sheetOptionLabel}>{label}</span>
+        {expanded && (
+          <span className={classes.sheetOptionCheck} aria-hidden>
+            <CheckGlyph />
+          </span>
+        )}
+      </button>
+      {expanded && <div className={classes.sheetDisclosureBody}>{children}</div>}
+    </div>
+  )
+}
+
+export type SheetFieldProps = {
+  readonly label: string
+  /** Stamped on the heading so a control can point `aria-labelledby` at it — see `useControlName`. */
+  readonly labelId?: string
+  readonly children: ReactNode
+}
+
+/** A labelled block inside the sheet — the sheet form's outer shell for every control. */
+export function SheetField({ label, labelId, children }: SheetFieldProps): ReactNode {
+  return (
+    <div className={classes.sheetField}>
+      <span className={classes.sheetLabel} {...(labelId !== undefined && { id: labelId })}>
+        {label}
+      </span>
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Names a control that has no VISIBLE Mantine `label`, and does it differently per surface — which
+ * is the whole reason this is one helper instead of an `aria-label` sprinkled per call site.
+ *
+ * In the SHEET the visible `SheetField` heading is right there, so the control points at it
+ * (`aria-labelledby`) and the heading stops being decoration. In the PILL surface there is no
+ * visible name to point at — the pill text is the VALUE (`EUR`, `30d`, `3 channels`) — so the
+ * control carries the filter's own name instead. Either way the announced name is what is being
+ * filtered, not what it currently holds.
+ *
+ * The id is generated by the CONTROL, not by `SheetField`, because the control renders its own
+ * `SheetField`: an id published downward through context could never reach the sibling that needs it.
+ *
+ * @example
+ * const { labelId, nameProps } = useControlName(label, inSheet)
+ * <Radio.Group {...nameProps} …/>
+ * // and, in the sheet branch: <SheetField label={label} labelId={labelId}>…</SheetField>
+ */
+export function useControlName(
+  label: string,
+  inSheet: boolean,
+): {
+  labelId: string
+  nameProps: { 'aria-labelledby': string } | { 'aria-label': string }
+} {
+  const labelId = useId()
+  return {
+    labelId,
+    nameProps: inSheet ? { 'aria-labelledby': labelId } : { 'aria-label': label },
+  }
+}
+
+export type SheetRowProps = {
+  readonly children: ReactNode
+}
+
+/** One 44px full-width row (`--vx-space-sheet-row-height`). */
+export function SheetRow({ children }: SheetRowProps): ReactNode {
+  return <div className={classes.sheetRow}>{children}</div>
+}
+
+/** The class every sheet-form list item shares, for controls that render their own row element. */
+export const sheetRowClass = classes.sheetRow
+
+/**
+ * `classNames` for a Radio/Checkbox/Switch rendered as a sheet row — stretches its `body` and
+ * `<label>` across the full 44px so the whole row is the touch target, not the middle 20px of it.
+ */
+export const sheetRowClassNames = {
+  root: classes.sheetRow,
+  body: classes.sheetRowBody,
+  label: classes.sheetRowLabel,
+} as const

package/src/controls/glyphs.tsx

@@ -0,0 +1,81 @@
+/**
+ * The control tier's own inline glyphs (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * basalt ships NO icon dependency — every `icon` slot in the public API takes a `ReactNode` the
+ * consumer fills. These are the few glyphs the FRAMEWORK draws for itself, where a default icon is
+ * part of the control's identity rather than a caller's decision: a range filter reads as a date
+ * picker because it carries a calendar, a compare filter because it carries the swap arrows, and
+ * the mobile `Filters (n)` pill because it carries a funnel. Same convention the shell already uses
+ * for its own chrome (`shell/sidebar-search.tsx`, `shell/app-sidebar.tsx`): a 24×24 `viewBox`,
+ * `stroke="currentColor"`, sized down by the `size` prop.
+ *
+ * INTERNAL — not on the `./controls` barrel. A consumer wanting a different glyph passes `icon`.
+ */
+import type { ReactNode } from 'react'
+
+/** The tier's icon box: 16px inside a button, 14px for a trailing affordance. */
+const ICON_SIZE = 16
+const AFFORDANCE_SIZE = 14
+
+function Stroke({ size = ICON_SIZE, children }: { size?: number; children: ReactNode }): ReactNode {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.75}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      {children}
+    </svg>
+  )
+}
+
+/** `RangeFilter`'s default leading icon. */
+export function CalendarGlyph(): ReactNode {
+  return (
+    <Stroke>
+      <rect x={3} y={5} width={18} height={16} rx={2.5} />
+      <path d="M3 10h18" />
+      <path d="M8 3v4" />
+      <path d="M16 3v4" />
+    </Stroke>
+  )
+}
+
+/** `CompareFilter`'s default leading icon — the arrows-swap glyph. */
+export function SwapGlyph(): ReactNode {
+  return (
+    <Stroke>
+      <path d="M4 8h13l-3.5 -3.5" />
+      <path d="M20 16h-13l3.5 3.5" />
+    </Stroke>
+  )
+}
+
+/** The mobile `Filters (n)` pill's leading icon. */
+export function FunnelGlyph(): ReactNode {
+  return (
+    <Stroke>
+      <path d="M4 4h16l-6.5 8v7l-3 -1.5v-5.5z" />
+    </Stroke>
+  )
+}
+
+/**
+ * Every pill's trailing affordance — 14px, muted, and an SVG rather than the `⇅` character it
+ * replaced. A text glyph rendered at the label's own font metrics, so it sat off the optical centre
+ * and shifted with the font stack; the path is centred in its own box.
+ */
+export function UpDownGlyph(): ReactNode {
+  return (
+    <Stroke size={AFFORDANCE_SIZE}>
+      <path d="M8 9l4 -4l4 4" />
+      <path d="M8 15l4 4l4 -4" />
+    </Stroke>
+  )
+}

package/src/controls/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `basalt-ui/controls` — the Mantine-coupled control tier (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * Every control here renders at the `ctl` tier from the home that hosts it and owns its own
+ * desktop/mobile swap in CSS (law C9). Actions and sync land in wave 3; the filter/tab family
+ * follows in wave 4.
+ */
+export {
+  ActionGroup,
+  OverflowMenu,
+  DESKTOP_SECONDARY_MAX,
+  MOBILE_GLOBAL_BAR_MAX,
+  barActionMobile,
+  globalActionMobile,
+  type BarAction,
+  type BarActionItem,
+  type BarActionMenu,
+  type BarActionCustom,
+  type ActionGroupProps,
+  type GlobalAction,
+  type OverflowMenuProps,
+} from './actions'
+export { SyncButton, formatAge, AGE_REFRESH_MS, type SyncButtonProps } from './sync-button'
+export { ControlGroup, type ControlGroupProps } from './control-group'
+
+// ── Filters + tabs (wave 4) ───────────────────────────────────────────────────────────────────
+// `FilterPill`, `FilterSheet` and the `EnumFilter` body are deliberately NOT here: reaching for
+// them is hand-rolling a filter (`basalt/hand-rolled-filter`), and `useFilterSurface` is only
+// meaningful to a control living inside a `FilterSet` — i.e. to this folder.
+export { FilterSet, type FilterSetProps } from './filter-set'
+export { RangeFilter, type RangeCustomPickerProps, type RangeFilterProps } from './range-filter'
+export {
+  CompareFilter,
+  COMPARE_VALUES,
+  type CompareFilterProps,
+  type CompareValue,
+} from './compare-filter'
+export {
+  SelectFilter,
+  type FilterOption,
+  type SelectFilterEnumProps,
+  type SelectFilterProps,
+  type SelectFilterStringProps,
+} from './select-filter'
+export { MultiSelectFilter, type MultiSelectFilterProps } from './multi-select-filter'
+export { NumberFilter, type NumberFilterOption, type NumberFilterProps } from './number-filter'
+export { SearchFilter, type SearchFilterProps } from './search-filter'
+export { ToggleFilter, type ToggleFilterProps } from './toggle-filter'
+export { ViewTabs, type ViewTabsOption, type ViewTabsProps } from './view-tabs'

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

@@ -0,0 +1,140 @@
+/**
+ * `MultiSelectFilter` — an any-of set over one closed enum (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * The pill reads the filter's name while the selection carries no information — empty (no
+ * constraint) or every option (the same thing said the long way) — and switches to a count once it
+ * does: `All channels` → `3 channels`. `noun` is the plural read in that count and defaults to the
+ * label lowercased, so `label="Channels"` needs no second prop.
+ *
+ * @example
+ * <MultiSelectFilter field={analytics.field.channels} label="All channels" noun="channels" />
+ *
+ * @example
+ * // A runtime catalogue over the same closed field — live labels, same values.
+ * <MultiSelectFilter
+ *   field={analytics.field.channels}
+ *   label="All channels"
+ *   options={CHANNELS.map((c) => ({ value: c, label: `${c} · ${counts[c]}` }))}
+ * />
+ */
+import { Button, Checkbox, Stack } from '@mantine/core'
+import type { ReactNode } from 'react'
+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'
+
+export type MultiSelectFilterProps<T extends string> = {
+  readonly field: FieldHandle<MultiField<T>>
+  readonly label: string
+  readonly icon?: ReactNode
+  /**
+   * The plural noun in the `3 channels` count.
+   *
+   * @default the label, lowercased
+   */
+  readonly noun?: string
+  /**
+   * Overrides `field.options` at render — a runtime catalogue whose labels carry live data
+   * (`web · 1.2k`). The VALUES still belong to the field: a multi field is a closed set, so this
+   * relabels and reorders rows, it does not open new ones. Unlike `SelectFilter` there is no
+   * string-field shape to make it required.
+   */
+  readonly options?: readonly FilterOption[]
+}
+
+export function MultiSelectFilter<T extends string>({
+  field,
+  label,
+  icon,
+  noun,
+  options: optionsProp,
+}: MultiSelectFilterProps<T>): ReactNode {
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const isDefault = field.isDefault(value)
+  useFilterRegistration(!isDefault, () => {
+    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 carriesInformation = value.length > 0 && value.length < options.length
+  const { labelId } = useControlName(label, inSheet)
+
+  // 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) {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        <SheetOptionList
+          mode="multi"
+          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])
+          }}
+        />
+      </SheetField>
+    )
+  }
+
+  const body = (
+    // Mantine's own `label`, for the same reason `enum-filter.tsx` uses it — `Checkbox.Group`
+    // overwrites any `aria-label`/`aria-labelledby` with its own. Named from `label`, never from the
+    // pill text, which reads `3 channels` and describes the selection rather than the filter.
+    <Checkbox.Group
+      label={label}
+      classNames={{ label: classes.groupLabel }}
+      value={[...value]}
+      onChange={(next) => {
+        // The boxes 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.
+        setValue(next as readonly T[])
+      }}
+    >
+      <Stack gap={2}>
+        {options.map((option) => (
+          <Checkbox
+            key={option.value}
+            value={option.value}
+            label={option.label}
+            {...(option.disabled === true && { disabled: true })}
+          />
+        ))}
+      </Stack>
+      {!isDefault && (
+        <Button
+          variant="subtle"
+          size="ctl"
+          onClick={() => {
+            field.clear()
+          }}
+        >
+          Clear
+        </Button>
+      )}
+    </Checkbox.Group>
+  )
+
+  return (
+    <FilterPill
+      label={carriesInformation ? `${value.length} ${noun ?? label.toLowerCase()}` : label}
+      active={!isDefault}
+      {...(icon !== undefined && { icon })}
+    >
+      <div className={classes.optionList}>{body}</div>
+    </FilterPill>
+  )
+}