basalt-ui 1.25.0 → 1.26.0

package/src/controls/enum-filter.tsx

@@ -0,0 +1,159 @@
+/**
+ * The shared body behind `SelectFilter` and `CompareFilter` — one closed-enum filter over
+ * `field.enum` (`docs/CONTROLS-SPEC.md` §3). INTERNAL: the two exported wrappers differ only in
+ * their default label and in how narrowly they type `field`, so there is one implementation and no
+ * third public spelling of it.
+ *
+ * Both surfaces render the SAME `Radio.Group`, differing only in row height: a radio list states
+ * "one of these" without a second interaction (a nested Select inside a popover would), and it is
+ * the sheet form the spec prescribes — so it is the popover form too rather than inventing a second
+ * idiom for the same choice.
+ *
+ * **The pill label is ALWAYS the selected option's label, including at the field's default value.**
+ * It used to fall back to the FILTER's name while `isDefault(value)` held, and that is the bug this
+ * comment exists to keep fixed: a bar reading `Compare` over a field holding `'previous'` states
+ * something false — the popover said `Previous period` was selected and the pill said the filter had
+ * not been touched. A pill is a readout, so the value is the only thing it may print. `label` is the
+ * popover/sheet heading and the accessible name, nothing else; the ACTIVE state (touched vs at its
+ * default) is carried by the accent border, which is a second channel and does not need the text.
+ *
+ * `?? label` survives as a last resort for a value that is in the field but not in the rendered
+ * `options` — a runtime catalogue that has dropped a row while the URL still points at it. That is a
+ * data gap, not a default, and printing the filter's name is the least-wrong thing to do with it.
+ *
+ * `field` is typed as `ChoiceHandle` rather than a `FieldHandle<EnumField>`, and `options` may
+ * override the field's own rows — the two halves of `SelectFilter`'s runtime-catalogue shape (see
+ * its doc). Both public wrappers still type `field` exactly, so a wrong field kind is still a type
+ * error at the call site; the widening lives here, where nothing consumer-facing points at it.
+ */
+import { Button, Radio, Stack } from '@mantine/core'
+import type { ReactNode } from 'react'
+import type { FieldOption } from '../state'
+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 type { FilterOption } from './select-filter'
+
+/**
+ * The slice of a `FieldHandle` this body actually binds to, generic over the VALUE rather than over
+ * the field kind. `FieldHandle<EnumField<T>>` satisfies it at `T` and `FieldHandle<StringField>` at
+ * `string`, which is what lets `SelectFilter` take either without this file knowing about kinds —
+ * and it stays a structural subset, so it can never widen into a second, hand-constructible handle.
+ */
+export type ChoiceHandle<T extends string> = {
+  readonly fallback: T
+  readonly options: readonly FieldOption[]
+  use(): readonly [T, (next: T) => void]
+  isDefault(v: T): boolean
+}
+
+export type EnumFilterProps<T extends string> = {
+  readonly field: ChoiceHandle<T>
+  readonly label: string
+  readonly icon?: ReactNode
+  /** Adds a `Clear` action that writes the field back to its fallback. */
+  readonly clearable?: boolean
+  /**
+   * Overrides `field.options` at render — a runtime catalogue whose labels carry live data, or the
+   * only row source a `StringField` has. `| undefined` explicitly: an internal component is spread
+   * into, and `exactOptionalPropertyTypes` rejects a possibly-undefined member on a bare optional.
+   */
+  readonly options?: readonly FilterOption[] | undefined
+}
+
+export function EnumFilter<T extends string>({
+  field,
+  label,
+  icon,
+  clearable,
+  options: optionsProp,
+}: EnumFilterProps<T>): ReactNode {
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const isDefault = field.isDefault(value)
+  useFilterRegistration(!isDefault, () => {
+    setValue(field.fallback)
+  })
+
+  // The prop wins whole, never merged: a catalogue that has dropped a value must be able to drop
+  // its row, which a merge with `field.options` would silently put back.
+  const options: readonly FilterOption[] = optionsProp ?? field.options
+  const selected = options.find((option) => option.value === value)
+  const inSheet = surface === 'sheet'
+  const { labelId } = useControlName(label, inSheet)
+
+  // The SHEET form is a `SheetOptionList` (44px rows, trailing check, hairline between rows), not
+  // the popover's `Radio.Group` — see `SheetOptionList`'s doc for why the leading radio dot had to
+  // go. Both still write through the same setter, so there is one behaviour and two surfaces.
+  if (inSheet) {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        <SheetOptionList
+          mode="single"
+          labelId={labelId}
+          selected={[value]}
+          options={options}
+          onToggle={(next) => {
+            // Rendered from `options` — the field's declared values, or the runtime catalogue
+            // standing in for them; the cast restores what the codec already guarantees.
+            setValue(next as T)
+          }}
+        />
+      </SheetField>
+    )
+  }
+
+  const body = (
+    // Mantine's OWN `label` prop, not an `aria-label`: `Radio.Group` overwrites both `aria-label`
+    // and `aria-labelledby` with its own `aria-labelledby` pointing at the `Input.Wrapper` label it
+    // renders — which, with no `label` passed, points at an element that does not exist. So the only
+    // way to name this group is to give it the label. It doubles as the heading in both surfaces:
+    // the group needs the FILTER's name ('Currency'), which the pill cannot supply because the pill
+    // reads the VALUE ('EUR') once set.
+    <Radio.Group
+      label={label}
+      classNames={{ label: classes.groupLabel }}
+      value={value}
+      onChange={(next) => {
+        // `next` is a DOM string, and the radios are rendered from `options` — the field's own
+        // declared values, or the runtime catalogue standing in for them. Over a closed enum the
+        // cast restores what the codec already guarantees; over a `StringField` there is nothing to
+        // guarantee and nothing to widen, since every string is a legal value there.
+        setValue(next as T)
+      }}
+    >
+      <Stack gap={2}>
+        {options.map((option) => (
+          <Radio
+            key={option.value}
+            value={option.value}
+            label={option.label}
+            {...(option.disabled === true && { disabled: true })}
+          />
+        ))}
+      </Stack>
+      {clearable === true && !isDefault && (
+        <Button
+          variant="subtle"
+          size="ctl"
+          onClick={() => {
+            setValue(field.fallback)
+          }}
+        >
+          Clear
+        </Button>
+      )}
+    </Radio.Group>
+  )
+
+  return (
+    <FilterPill
+      label={selected?.label ?? label}
+      active={!isDefault}
+      {...(icon !== undefined && { icon })}
+    >
+      <div className={classes.optionList}>{body}</div>
+    </FilterPill>
+  )
+}

package/src/controls/filter-context.tsx

@@ -0,0 +1,153 @@
+/**
+ * The two contexts `FilterSet` publishes and every control in this folder consumes
+ * (`docs/CONTROLS-SPEC.md` §3). Its own module so `filter-set.tsx` and `filter-sheet.tsx` can both
+ * read it without importing each other.
+ *
+ * **Surface** — `useFilterSurface()` is how a control decides its FORM, not a media query: `'pill'`
+ * inside the bar row (and inside the desktop `+N` fold), `'sheet'` inside the mobile `Filters (n)`
+ * Drawer. A control renders exactly one form per mount; the desktop/mobile swap WITHIN the pill
+ * form is CSS (`visibleFrom`/`hiddenFrom`), never JS (C9).
+ *
+ * **Registry** — `useFilterRegistration()` is what makes `Filters (n)` and `Reset all` derived
+ * rather than hand-passed: each filter reports `{ isActive, reset }` for itself, so `FilterSet`
+ * needs no list of its children's fields. Registration is deliberately scoped to ONE surface: the
+ * bar row keeps every child mounted on every viewport (hidden slots are `display: none`, never
+ * unmounted — see `controls.module.css`), so the row alone is a complete and stable census. The
+ * fold dropdown and the sheet mount a SECOND copy of the same children and therefore provide a
+ * `null` registry, which is what keeps one filter from counting twice.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import type { ReactNode } from 'react'
+
+/** Which form a control renders. Provided by `FilterSet`; `'pill'` when there is no `FilterSet`. */
+export type FilterSurface = 'pill' | 'sheet'
+
+const FilterSurfaceContext = createContext<FilterSurface>('pill')
+
+/**
+ * The form this control should render — the ONE thing a control branches on.
+ *
+ * @example
+ * const surface = useFilterSurface()
+ * if (surface === 'sheet') return <SheetField label={label}>…</SheetField>
+ */
+export function useFilterSurface(): FilterSurface {
+  return useContext(FilterSurfaceContext)
+}
+
+/** What one filter reports about itself, keyed internally by a `useId()` per mount. */
+export type FilterRegistration = {
+  /** `!field.isDefault(value)` — the only input to `Filters (n)` and the pill's accent border. */
+  readonly isActive: boolean
+  /** Writes the field back to its fallback. Called by `Reset all`. */
+  readonly reset: () => void
+}
+
+type FilterRegistry = {
+  register(key: string, registration: FilterRegistration): void
+  unregister(key: string): void
+}
+
+const FilterRegistryContext = createContext<FilterRegistry | null>(null)
+
+export type FilterSetScopeProps = {
+  readonly surface: FilterSurface
+  /** `null` on a second copy of the same children (the fold dropdown, the sheet). */
+  readonly registry: FilterRegistry | null
+  readonly children: ReactNode
+}
+
+/** Provides both contexts at once — every place FilterSet mounts children goes through this. */
+export function FilterSetScope({ surface, registry, children }: FilterSetScopeProps): ReactNode {
+  return (
+    <FilterSurfaceContext.Provider value={surface}>
+      <FilterRegistryContext.Provider value={registry}>{children}</FilterRegistryContext.Provider>
+    </FilterSurfaceContext.Provider>
+  )
+}
+
+/**
+ * Report this filter's active/reset state to the enclosing `FilterSet`. Call it unconditionally —
+ * it no-ops outside a registering scope (a bare filter with no `FilterSet`, the fold dropdown, the
+ * sheet), which is what keeps it hook-safe in every control.
+ *
+ * @example
+ * const [value, setValue] = field.use()
+ * useFilterRegistration(!field.isDefault(value), () => setValue(field.fallback))
+ */
+export function useFilterRegistration(isActive: boolean, reset: () => void): void {
+  const registry = useContext(FilterRegistryContext)
+  const key = useId()
+  // A ref, so a `reset` closure that is fresh every render does not re-run the effect (and so
+  // `Reset all` always calls the LATEST setter, not the one captured at registration).
+  const resetRef = useRef(reset)
+  resetRef.current = reset
+  const stableReset = useCallback(() => {
+    resetRef.current()
+  }, [])
+
+  useEffect(() => {
+    if (registry === null) return
+    registry.register(key, { isActive, reset: stableReset })
+    return () => {
+      registry.unregister(key)
+    }
+  }, [registry, key, isActive, stableReset])
+}
+
+export type FilterCensus = {
+  readonly registry: FilterRegistry
+  /** How many registered filters are non-default — `Filters (n)`. */
+  readonly activeCount: number
+  /** Resets every registered filter. */
+  readonly resetAll: () => void
+}
+
+/**
+ * The registry side, for `FilterSet` itself. The map is a ref (registration happens in children's
+ * effects, which must not re-render the parent mid-commit) and the COUNT is state, so only a real
+ * change in the count re-renders the bar.
+ */
+export function useFilterCensus(): FilterCensus {
+  const entries = useRef(new Map<string, FilterRegistration>())
+  const [activeCount, setActiveCount] = useState(0)
+
+  // The functional form, so React's own bail-out drops a write of the count already held — a
+  // register/unregister pair that leaves the count unchanged must not re-render the bar.
+  const sync = useCallback(() => {
+    let next = 0
+    for (const entry of entries.current.values()) {
+      if (entry.isActive) next += 1
+    }
+    setActiveCount((current) => (current === next ? current : next))
+  }, [])
+
+  const registry = useMemo<FilterRegistry>(
+    () => ({
+      register(key, registration) {
+        entries.current.set(key, registration)
+        sync()
+      },
+      unregister(key) {
+        entries.current.delete(key)
+        sync()
+      },
+    }),
+    [sync],
+  )
+
+  const resetAll = useCallback(() => {
+    for (const entry of entries.current.values()) entry.reset()
+  }, [])
+
+  return { registry, activeCount, resetAll }
+}

package/src/controls/filter-pill.tsx

@@ -0,0 +1,120 @@
+/**
+ * `FilterPill` — the one chip every filter in the bar row renders (`docs/CONTROLS-SPEC.md` §3):
+ * bordered, 30px, leading icon · label · trailing `⇅`. INTERNAL: it is not on the `./controls`
+ * barrel, because a consumer reaching for it directly is hand-rolling a filter
+ * (`basalt/hand-rolled-filter`) — the pill is what `RangeFilter`/`SelectFilter`/… ARE, not a
+ * building block to assemble one from.
+ *
+ * The 30px box is `variant="default" size="ctl"` and nothing else — the tier comes from the theme's
+ * `--button-height-ctl` var set (`docs/CONTROLS-SPEC.md` §5), so the pill is the same height whether
+ * or not the home wrapped its slot in `CtlSlot`, and it tracks the density knob for free.
+ *
+ * Two modes, one component: with `children` the pill is a `Popover` target (every enum-ish filter);
+ * with only `onClick` it is a plain button that acts on press (`ToggleFilter`, the `+N` fold's
+ * sibling, the `Filters (n)` sheet opener).
+ */
+import { Button, Popover } from '@mantine/core'
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import { IconSlot } from '../theme/icon-slot'
+import classes from './controls.module.css'
+import { UpDownGlyph } from './glyphs'
+
+export type FilterPillProps = {
+  readonly label: string
+  readonly icon?: ReactNode
+  /** Non-default → accent-tinted border. Derived from `field.isDefault(value)`, never hand-set. */
+  readonly active?: boolean
+  /** Mono label, for a numeric preset set (`7d` / `30d`) — the same law `[data-numeric]` applies
+   *  to a numeric SegmentedControl label (`theme/segmented-control.module.css`). */
+  readonly numeric?: boolean
+  /** Popover body. Omit for a press-to-act pill. */
+  readonly children?: ReactNode
+  readonly onClick?: () => void
+  /** Accessible name when the visible label is a bare count (`+2`). */
+  readonly ariaLabel?: string
+  /**
+   * `aria-pressed` for the press-to-act mode (`ToggleFilter`) — without it the on/off state is
+   * carried by a border colour and nothing else. Deliberately NOT set on a popover-target pill,
+   * where `aria-expanded` (which Mantine's `Popover.Target` supplies) is the correct state.
+   */
+  readonly pressed?: boolean
+  readonly className?: string
+  /** Set by `FilterSet` on its own fold/sheet pills; a filter never passes either of these. */
+  readonly hideGlyph?: boolean
+  /** `data-shown` — the CSS hook that reveals the `+N` fold pill once folding is needed. */
+  readonly shown?: boolean
+}
+
+export function FilterPill({
+  label,
+  icon,
+  active,
+  numeric,
+  children,
+  onClick,
+  ariaLabel,
+  pressed,
+  className,
+  hideGlyph,
+  shown,
+}: FilterPillProps): ReactNode {
+  // Mantine's `Popover` does not open on target click — it is a controlled surface, unlike `Menu`.
+  // This is the only `useState` in the folder, and it holds an OVERLAY's open flag, not a filter's
+  // value (C3 is about the value; a popover that survives a reload would be a bug, not a feature).
+  const [opened, setOpened] = useState(false)
+
+  const target = (
+    <Button
+      variant="default"
+      size="ctl"
+      className={className === undefined ? classes.pill : `${classes.pill} ${className}`}
+      classNames={{ label: classes.pillLabel }}
+      {...(active === true && { 'data-active': true })}
+      {...(numeric === true && { 'data-numeric': true })}
+      {...(ariaLabel !== undefined && { 'aria-label': ariaLabel })}
+      {...(pressed !== undefined && children === undefined && { 'aria-pressed': pressed })}
+      {...(shown === true && { 'data-shown': true })}
+      {...(icon !== undefined && {
+        // `IconSlot` owns the 16px box and the optical centring; `.pillIcon` adds only the pill's
+        // muted-then-ink colour law. A consumer's glyph can no longer set this row's height.
+        leftSection: <IconSlot className={classes.pillIcon}>{icon}</IconSlot>,
+      })}
+      {...(hideGlyph !== true && {
+        rightSection: (
+          <IconSlot className={classes.glyph}>
+            <UpDownGlyph />
+          </IconSlot>
+        ),
+      })}
+      onClick={
+        onClick ??
+        (() => {
+          setOpened((current) => !current)
+        })
+      }
+    >
+      {label}
+    </Button>
+  )
+
+  if (children === undefined) return target
+
+  return (
+    <Popover
+      opened={opened}
+      onChange={setOpened}
+      onDismiss={() => {
+        setOpened(false)
+      }}
+      position="bottom-start"
+      withinPortal
+      shadow="md"
+      radius="sm"
+      trapFocus
+    >
+      <Popover.Target>{target}</Popover.Target>
+      <Popover.Dropdown className={classes.dropdown}>{children}</Popover.Dropdown>
+    </Popover>
+  )
+}