basalt-ui 1.24.0 → 1.26.0

package/src/controls/props-contract.test.tsx

@@ -0,0 +1,106 @@
+/**
+ * C2 and C5 as COMPILER assertions. The claim "a basalt filter has no `value`/`onChange`/`size`" is
+ * only worth making if writing one fails the build, so each `@ts-expect-error` below is the actual
+ * enforcement: `bunx tsc --noEmit` fails if any of them stops being an error, which is what happens
+ * the moment someone widens a prop type back open.
+ *
+ * `tsc` covers `src/**` including test files, so this file is checked by the ordinary typecheck —
+ * there is nothing extra to run and nothing to remember.
+ */
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { createLocalStore, field } from '../state'
+import { CompareFilter } from './compare-filter'
+import { MultiSelectFilter } from './multi-select-filter'
+import { RangeFilter } from './range-filter'
+import { SearchFilter } from './search-filter'
+import { SelectFilter } from './select-filter'
+import { ToggleFilter } from './toggle-filter'
+import { ViewTabs } from './view-tabs'
+
+const local = createLocalStore({
+  key: 'props-contract',
+  fields: {
+    currency: field.enum(['USD', 'EUR'], 'USD'),
+    compare: field.enum(['none', 'previous', 'year'] as const, 'none'),
+    channels: field.multi(['web', 'email'], []),
+    range: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }),
+    errorsOnly: field.boolean(false),
+    q: field.string(),
+  },
+})
+
+/** A runtime catalogue — the shape both `options` props take (`FilterOption[]`). */
+const PROJECTS = [
+  { value: 'argo', label: 'Argo' },
+  { value: 'linewatch', label: 'Linewatch', disabled: true },
+]
+const CHANNELS = [{ value: 'web', label: 'web · 1.2k' }]
+
+/** Never rendered — the file's product is the type errors below, not a DOM assertion. */
+function Rejected(): ReactNode {
+  return (
+    <>
+      {/* @ts-expect-error C2 — a filter has no `value`; the field owns it. */}
+      <SelectFilter field={local.field.currency} label="Currency" value="EUR" />
+      {/* @ts-expect-error C2 — nor an `onChange`; the write goes through the field. */}
+      <SelectFilter field={local.field.currency} label="Currency" onChange={() => {}} />
+      {/* @ts-expect-error C5 — the home sets the tier; a control carries no `size`. */}
+      <SelectFilter field={local.field.currency} label="Currency" size="xs" />
+      {/* @ts-expect-error C5 — nor a responsive override; the swap is the control's own. */}
+      <ViewTabs field={local.field.currency} visibleFrom="sm" />
+      {/* @ts-expect-error C2 — a tab is store state too. */}
+      <ViewTabs field={local.field.currency} value="USD" />
+      {/* @ts-expect-error a boolean field is not an enum field. */}
+      <ToggleFilter field={local.field.currency} label="Errors only" />
+      {/* @ts-expect-error a multi field is not an enum field. */}
+      <SelectFilter field={local.field.channels} label="Channels" />
+      {/* @ts-expect-error an enum field is not a range field. */}
+      <RangeFilter field={local.field.currency} />
+      {/* @ts-expect-error a string field is not a boolean field. */}
+      <ToggleFilter field={local.field.q} label="Errors only" />
+      {/* @ts-expect-error CompareFilter's enum is the three basalt names, not any enum. */}
+      <CompareFilter field={local.field.currency} />
+      {/* @ts-expect-error `label` is required on SelectFilter — the pill needs a name at rest. */}
+      <SelectFilter field={local.field.currency} />
+      {/* A string field declares no values, so `options` is the only possible row source — without
+          it the popover would render empty. Two overloads rather than one union prop type precisely
+          so the message names `options`; see `SelectFilter`'s own doc. */}
+      {/* @ts-expect-error a string field needs `options` — nothing else can supply the rows. */}
+      <SelectFilter field={local.field.q} label="Project" />
+      {/* @ts-expect-error `options` does not widen a MULTI field into a single-select either. */}
+      <SelectFilter field={local.field.channels} label="Channels" options={PROJECTS} />
+    </>
+  )
+}
+
+/** The same call sites, spelled correctly — so a type error above cannot be a false positive. */
+function Accepted(): ReactNode {
+  return (
+    <>
+      <SelectFilter field={local.field.currency} label="Currency" clearable />
+      {/* A runtime catalogue over a closed enum — `options` is optional there. */}
+      <SelectFilter
+        field={local.field.currency}
+        label="Currency"
+        options={[{ value: 'USD', label: 'USD · 1.00' }]}
+      />
+      {/* A string field WITH options — the id set an enum cannot close over. */}
+      <SelectFilter field={local.field.q} label="Project" options={PROJECTS} />
+      <MultiSelectFilter field={local.field.channels} label="All channels" options={CHANNELS} />
+      <CompareFilter field={local.field.compare} />
+      <MultiSelectFilter field={local.field.channels} label="All channels" noun="channels" />
+      <RangeFilter field={local.field.range} />
+      <ToggleFilter field={local.field.errorsOnly} label="Errors only" />
+      <SearchFilter field={local.field.q} placeholder="Search" />
+      <ViewTabs field={local.field.currency} />
+    </>
+  )
+}
+
+describe('props contract', () => {
+  test('both fixtures exist — tsc, not bun, is the assertion (see this file header)', () => {
+    expect(typeof Rejected).toBe('function')
+    expect(typeof Accepted).toBe('function')
+  })
+})

package/src/controls/range-filter.tsx

@@ -0,0 +1,184 @@
+/**
+ * `RangeFilter` — the time-window filter (`docs/CONTROLS-SPEC.md` §3). One pill over a
+ * `field.range`, which owns THREE URL params (preset + `from` + `to`), so a consumer's existing deep
+ * links and loaders keep their shape and `field.toWindow()` replaces every hand-rolled
+ * `presetToParams`.
+ *
+ * In the POPOVER the presets render as a `SegmentedControl` — vertical past four options, where a
+ * horizontal track would either overflow the popover or shrink each label below reading size.
+ * Numeric preset labels (`7d` / `30d`) get `data-numeric`, which is the mono treatment
+ * `theme/segmented-control.module.css` owns; that attribute is what retired the per-consumer
+ * `theme-allow` + inline `fontFamily` hack (C7).
+ *
+ * In the SHEET they render as a `SheetOptionList`, and the custom picker sits behind a
+ * `Custom range…` disclosure row. A vertical `SegmentedControl` stretched across a bottom drawer
+ * read as a broken control rather than a choice (see `SheetOptionList`'s doc), and an unconditional
+ * calendar pushed every OTHER filter in the sheet below the fold — the sheet holds all of them, and
+ * `RangeFilter` is one.
+ *
+ * The custom picker is INJECTED, never imported: `basalt-ui/controls-dates` holds the
+ * `@mantine/dates` implementation, and this module must resolve for a consumer who has no
+ * `@mantine/dates` at all (`docs/CONTROLS-SPEC.md` §3 — `basaltViteConfig`'s `optimizeDeps.include`
+ * for `@mantine/*` would break on an absent peer).
+ *
+ * @example
+ * import { DateRangePicker } from 'basalt-ui/controls-dates'
+ * // range: field.range({ presets: ['7d', '30d', '90d', 'ytd'], fallback: '30d', custom: true })
+ * <RangeFilter field={analytics.field.range} customPicker={DateRangePicker} />
+ */
+import { SegmentedControl, Stack } from '@mantine/core'
+import { useState } from 'react'
+import type { ComponentType, ReactNode } from 'react'
+import type { FieldHandle, RangeField, RangeValue } from '../state'
+import classes from './controls.module.css'
+import { useFilterRegistration, useFilterSurface } from './filter-context'
+import { FilterPill } from './filter-pill'
+import { CalendarGlyph } from './glyphs'
+import { SheetDisclosure, SheetField, SheetOptionList, useControlName } from './filter-sheet'
+
+/** Past four presets the track goes vertical. */
+const VERTICAL_FROM = 5
+/** `7d`, `30d`, `24h`, `90` — a label the mono numeric treatment is for. */
+const NUMERIC_LABEL = /^\d/
+
+/**
+ * The contract a custom-range picker satisfies — `basalt-ui/controls-dates`' `DateRangePicker`, or a
+ * consumer's own. Dates are ISO (`YYYY-MM-DD`), the same shape `field.range` stores and
+ * `toWindow()` emits, so the picker never learns the store's encoding.
+ */
+export type RangeCustomPickerProps = {
+  readonly value: { readonly from?: string | undefined; readonly to?: string | undefined }
+  readonly onChange: (next: { from: string; to: string }) => void
+}
+
+export type RangeFilterProps<P extends string> = {
+  readonly field: FieldHandle<RangeField<P>>
+  /** Leading pill icon. Defaults to a calendar glyph — a range filter reads as a date control, so
+   *  the glyph is part of the control's identity, not a per-call-site decision. */
+  readonly icon?: ReactNode
+  /** Rendered when the field declares `custom: true`. Omitted → presets only. */
+  readonly customPicker?: ComponentType<RangeCustomPickerProps>
+  /** Sheet-form heading. The pill's own label is the VALUE, which is what a bar reads. @default 'Range' */
+  readonly label?: string
+}
+
+export function RangeFilter<P extends string>({
+  field,
+  icon,
+  customPicker,
+  label = 'Range',
+}: RangeFilterProps<P>): ReactNode {
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const isDefault = field.isDefault(value)
+  useFilterRegistration(!isDefault, () => {
+    setValue(field.fallback)
+  })
+
+  const options = field.options
+  const presets = options.filter((option) => option.value !== 'custom')
+  const allowsCustom = options.length !== presets.length
+  const numeric = presets.length > 0 && presets.every((option) => NUMERIC_LABEL.test(option.label))
+  const inSheet = surface === 'sheet'
+  const Picker = customPicker
+  // The track is a `radiogroup`; without this it announces unnamed, and the pill it hangs off reads
+  // the VALUE (`30d`), not the filter.
+  const { labelId, nameProps } = useControlName(label, inSheet)
+  // Expanded when the field ALREADY holds a custom window — a reader who deep-linked one must see
+  // it without hunting for the row that holds it. Local, because it is an overlay's open flag and
+  // not a filter value (the same line `FilterPill`'s `opened` state draws).
+  const [customOpen, setCustomOpen] = useState(value.preset === 'custom')
+  const showPicker = allowsCustom && Picker !== undefined
+
+  if (inSheet) {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        <SheetOptionList
+          mode="single"
+          labelId={labelId}
+          selected={[value.preset]}
+          options={presets.map((option) => ({ value: option.value, label: option.label }))}
+          onToggle={(next) => {
+            setCustomOpen(false)
+            // Rendered from `field.options`, so `next` is always a declared preset — the cast
+            // restores what the codec already guarantees.
+            setValue({ preset: next } as RangeValue<P | 'custom'>)
+          }}
+        />
+        {showPicker && (
+          <SheetDisclosure
+            label="Custom range…"
+            expanded={customOpen}
+            onToggle={() => {
+              setCustomOpen((open) => !open)
+            }}
+          >
+            <Picker
+              value={{ from: value.from, to: value.to }}
+              onChange={({ from, to }) => {
+                setValue({ preset: 'custom', from, to } as RangeValue<P | 'custom'>)
+              }}
+            />
+          </SheetDisclosure>
+        )}
+      </SheetField>
+    )
+  }
+
+  const body = (
+    <Stack gap="xs">
+      <SegmentedControl
+        {...nameProps}
+        size="ctl"
+        orientation={presets.length >= VERTICAL_FROM ? 'vertical' : 'horizontal'}
+        value={value.preset}
+        data={presets.map((option) => ({ value: option.value, label: option.label }))}
+        {...(numeric && { 'data-numeric': true })}
+        onChange={(next) => {
+          // The segments are rendered from `field.options`, so `next` is always a declared preset —
+          // the cast restores what the codec already guarantees.
+          setValue({ preset: next } as RangeValue<P | 'custom'>)
+        }}
+      />
+      {showPicker && (
+        <Picker
+          value={{ from: value.from, to: value.to }}
+          onChange={({ from, to }) => {
+            setValue({ preset: 'custom', from, to } as RangeValue<P | 'custom'>)
+          }}
+        />
+      )}
+    </Stack>
+  )
+
+  return (
+    <FilterPill
+      label={rangeLabel(value, options)}
+      active={!isDefault}
+      numeric={numeric && value.preset !== 'custom'}
+      icon={icon ?? <CalendarGlyph />}
+    >
+      <div className={classes.optionList}>{body}</div>
+    </FilterPill>
+  )
+}
+
+const DAY_FORMAT = new Intl.DateTimeFormat('en-US', {
+  month: 'short',
+  day: 'numeric',
+  // ISO date strings parse as UTC midnight; formatting them in the runtime's zone would render the
+  // previous day west of Greenwich — and differently on server than on client (a hydration
+  // mismatch), the same hazard `formatArticleDate` avoids.
+  timeZone: 'UTC',
+})
+
+/** `Last 30 days`, or `Mar 1 – Mar 14` for a custom window. */
+function rangeLabel(
+  value: RangeValue<string>,
+  options: readonly { value: string; label: string }[],
+): string {
+  if (value.preset === 'custom' && value.from !== undefined && value.to !== undefined) {
+    return `${DAY_FORMAT.format(new Date(value.from))} – ${DAY_FORMAT.format(new Date(value.to))}`
+  }
+  return options.find((option) => option.value === value.preset)?.label ?? value.preset
+}

package/src/controls/search-filter.tsx

@@ -0,0 +1,123 @@
+/**
+ * `SearchFilter` — free text over a `field.string` (`docs/CONTROLS-SPEC.md` §3). The one filter that
+ * is not a pill: a text box states its own value, so wrapping it in a chip + popover would cost a
+ * press per keystroke session for nothing.
+ *
+ * Keystrokes are DEBOUNCED (200ms) before they reach the field. `field.string()` already writes with
+ * `history: 'replace'`, so an un-debounced input would still not stack history entries — what the
+ * debounce buys is one navigation per phrase instead of one per character, which is the difference
+ * between a typed query and a re-rendered route tree eight times over.
+ *
+ * @example
+ * // q: field.string({ max: 120 })
+ * <SearchFilter field={table.field.q} placeholder="Search pages" />
+ */
+import { TextInput } from '@mantine/core'
+import { useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { FieldHandle, StringField } from '../state'
+import { useFilterRegistration, useFilterSurface } from './filter-context'
+import { SheetField, useControlName } from './filter-sheet'
+
+/** One navigation per typed phrase, not per keystroke. */
+const DEBOUNCE_MS = 200
+
+export type SearchFilterProps = {
+  readonly field: FieldHandle<StringField>
+  readonly placeholder?: string
+  /** Sheet-form heading. @default 'Search' */
+  readonly label?: string
+}
+
+export function SearchFilter({
+  field,
+  placeholder,
+  label = 'Search',
+}: SearchFilterProps): ReactNode {
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const draft = useDebouncedField(value, setValue)
+  useFilterRegistration(!field.isDefault(value), () => {
+    setValue(field.fallback)
+  })
+
+  // `placeholder` is optional and, even when set, stops being the name the moment the user types —
+  // so the name comes from `label`, or from the sheet heading when there is one.
+  const { labelId, nameProps } = useControlName(label, surface === 'sheet')
+
+  const input = (
+    <TextInput
+      {...nameProps}
+      size="ctl"
+      value={draft.value}
+      leftSection={<SearchIcon />}
+      {...(placeholder !== undefined && { placeholder })}
+      onChange={(event) => {
+        draft.set(event.currentTarget.value)
+      }}
+    />
+  )
+
+  if (surface === 'sheet') {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        {input}
+      </SheetField>
+    )
+  }
+  return input
+}
+
+/**
+ * A local draft that lands on the field `DEBOUNCE_MS` after the last keystroke, and that follows the
+ * field when it changes from OUTSIDE the input (`Reset all`, a back navigation, a deep link).
+ * `seen` is what separates the two directions: 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.
+ */
+function useDebouncedField(
+  value: string,
+  setValue: (next: string) => void,
+): { value: string; set: (next: string) => void } {
+  const [draft, setDraft] = useState(value)
+  const seen = useRef(value)
+  const commit = useRef(setValue)
+  commit.current = setValue
+
+  useEffect(() => {
+    if (seen.current === value) return
+    seen.current = value
+    setDraft(value)
+  }, [value])
+
+  useEffect(() => {
+    if (draft === value) return
+    const timer = setTimeout(() => {
+      seen.current = draft
+      commit.current(draft)
+    }, DEBOUNCE_MS)
+    return () => {
+      clearTimeout(timer)
+    }
+  }, [draft, value])
+
+  return { value: draft, set: setDraft }
+}
+
+function SearchIcon(): ReactNode {
+  return (
+    <svg
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <circle cx="11" cy="11" r="7" />
+      <path d="M21 21l-4.35 -4.35" />
+    </svg>
+  )
+}

package/src/controls/select-filter.tsx

@@ -0,0 +1,89 @@
+/**
+ * `SelectFilter` — one choice, one pill (`docs/CONTROLS-SPEC.md` §3). Takes `field`, never
+ * `value`/`onChange`/`size` (C2/C5): the handle owns the URL write, the localStorage mirror and the
+ * option labels (`store.labels()`), so the call site is the field plus its human name.
+ *
+ * `options` is the escape hatch for a catalogue that only exists at runtime — the label carries live
+ * data (`EUR · 1.08`), or the id set is fetched rather than declared. It OVERRIDES `field.options`
+ * at render, and it is what makes the second `field` shape legal: a `StringField` handle plus
+ * `options` covers an id set no enum could close over (a project picker, a device list), while a
+ * `StringField` handle WITHOUT `options` stays a type error — nothing would supply the rows, so the
+ * filter would render an empty popover.
+ *
+ * @example
+ * <SelectFilter field={analytics.field.currency} label="Currency" clearable />
+ *
+ * @example
+ * // A runtime catalogue over a closed enum — same field, live labels.
+ * <SelectFilter
+ *   field={analytics.field.currency}
+ *   label="Currency"
+ *   options={rates.map((r) => ({ value: r.code, label: `${r.code} · ${r.rate}` }))}
+ * />
+ *
+ * @example
+ * // An id set the enum cannot close over — a string field, options mandatory.
+ * <SelectFilter
+ *   field={dashboard.field.projectId}
+ *   label="Project"
+ *   options={projects.map((p) => ({ value: p.id, label: p.name, disabled: p.archived }))}
+ * />
+ */
+import type { ReactNode } from 'react'
+import type { EnumField, FieldHandle, StringField } from '../state'
+import { EnumFilter } from './enum-filter'
+
+/**
+ * One row of a runtime catalogue. Wider than the store's own `FieldOption` by exactly one member:
+ * `disabled` renders the row and refuses the selection, which a declared enum expresses by leaving
+ * the value out and a live catalogue cannot (an archived project still labels the rows already
+ * pointing at it).
+ */
+export type FilterOption = {
+  readonly value: string
+  readonly label: string
+  readonly disabled?: boolean
+}
+
+type SelectFilterCommon = {
+  readonly label: string
+  readonly icon?: ReactNode
+  /** Adds a `Clear` action that writes the field back to its fallback. */
+  readonly clearable?: boolean
+}
+
+/** A closed enum field: `options` relabels rows the field already declares, so it is optional. */
+export type SelectFilterEnumProps<T extends string> = SelectFilterCommon & {
+  readonly field: FieldHandle<EnumField<T>>
+  /** Overrides `field.options` at render — a runtime catalogue, labels included. */
+  readonly options?: readonly FilterOption[]
+}
+
+/** A string field: it declares no values, so `options` is the only row source and is required. */
+export type SelectFilterStringProps = SelectFilterCommon & {
+  readonly field: FieldHandle<StringField>
+  /** Required here — see this type's doc. */
+  readonly options: readonly FilterOption[]
+}
+
+export type SelectFilterProps<T extends string> = SelectFilterEnumProps<T> | SelectFilterStringProps
+
+/**
+ * TWO OVERLOADS, not one conditional prop type, and the reason is the error text. A union prop type
+ * reports only the constituent it likes best — for a `StringField` handle passed without `options`
+ * that is the enum branch, so the message reads `Type '"string"' is not assignable to type '"enum"'`
+ * and never mentions the prop that would fix it. The overload form reports both halves, ending in
+ * `Property 'options' is missing`, which is the actual instruction.
+ */
+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 {
+  const { field, ...rest } = props
+
+  // Two arms, one body — and they are not the same code to the compiler. `field.kind` is a NESTED
+  // discriminant, which narrows `field` but never `props`, so each arm is what fixes the shared
+  // body's value type: `string` for the string field, `T` for the enum. Written out rather than
+  // cast, so widening either branch fails here instead of at a consumer's call site.
+  if (field.kind === 'string') return <EnumFilter {...rest} field={field} />
+  return <EnumFilter {...rest} field={field} />
+}

package/src/controls/sync-button.module.css

@@ -0,0 +1,63 @@
+/*
+ * `SyncButton` chrome — the rotating glyph and the desktop-only age suffix.
+ */
+
+.spin {
+  animation: basalt-sync-spin 900ms linear infinite;
+}
+
+@keyframes basalt-sync-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/*
+ * Reduced motion drops the rotation, never the icon: the `aria-busy`/`aria-disabled` pair is what
+ * actually announces "syncing", so removing the spin costs no information.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .spin {
+    animation: none;
+  }
+}
+
+/*
+ * The age rides beside the label on desktop and disappears below `sm`, where the tooltip carries
+ * it instead — one mount, a CSS-only swap (law C9).
+ */
+.age {
+  margin-inline-start: var(--vx-space-control-gap);
+  color: var(--vx-muted);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+}
+
+/*
+ * `scope: 'page'` below `sm`: the label and the age go, the glyph stays, and the button collapses
+ * to the square icon form (spec §3, "icon-only, age in tooltip"). Hidden, not unmounted — a second
+ * mount under `hiddenFrom` is exactly the responsive twin law C9 forbids, which is also why the
+ * accessible name lives on `aria-label` rather than in this text.
+ *
+ * Three declarations, because Mantine's Button spends its width in three places: `--button-padding-x`
+ * (the inline padding, which `[data-with-left-section]` divides by 1.5), the left section's own
+ * `margin-inline-end` (a fixed `--mantine-spacing-xs`, not a variable, so it takes a rule), and the
+ * width itself, pinned to the `ctl` height so the box is square. This module is unlayered, so it
+ * outranks `@layer mantine` regardless of specificity.
+ */
+@media (max-width: 47.99375em) {
+  .label,
+  .age {
+    display: none;
+  }
+
+  .pageButton {
+    --button-padding-x: 0;
+
+    width: calc(var(--vx-space-control-height-ctl, 1.875rem) * var(--mantine-scale, 1));
+  }
+
+  .pageButton :global(.mantine-Button-section[data-position='left']) {
+    margin-inline-end: 0;
+  }
+}

package/src/controls/sync-button.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 spin: string
+  readonly age: string
+  readonly label: string
+  readonly pageButton: string
+}
+export default classes