basalt-ui 1.25.0 → 1.27.0

package/src/controls/number-filter.tsx

@@ -0,0 +1,291 @@
+/**
+ * `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` 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}).
+ *
+ * @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 { 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'
+
+/** 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 = {
+  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. 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.
+   */
+  readonly step?: number
+}
+
+export function NumberFilter({ field, label, icon, options, step }: NumberFilterProps): ReactNode {
+  // 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 })}
+      />
+    )
+  }
+  return (
+    <NumberStepper
+      field={field}
+      label={label}
+      {...(icon !== undefined && { icon })}
+      {...(step !== undefined && { step })}
+    />
+  )
+}
+
+/**
+ * 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
+ * `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,
+}: {
+  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 })}
+    />
+  )
+}
+
+/** The stepper form — a pill holding a `ctl` `NumberInput`, or a full-width sheet row. */
+function NumberStepper({
+  field,
+  label,
+  icon,
+  step,
+}: {
+  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 { labelId, nameProps } = useControlName(label, inSheet)
+  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 })}
+      {...(step !== undefined ? { step } : field.int && { step: 1 })}
+      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()
+      }}
+    />
+  )
+
+  if (inSheet) {
+    return (
+      <SheetField label={label} labelId={labelId}>
+        {input}
+      </SheetField>
+    )
+  }
+
+  return (
+    <FilterPill
+      label={String(value)}
+      numeric
+      active={!isDefault}
+      {...(icon !== undefined && { icon })}
+    >
+      <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/peer-boundary.test.ts

@@ -0,0 +1,85 @@
+/**
+ * The packaging invariant `./controls` and `./controls-dates` exist to express
+ * (`docs/CONTROLS-SPEC.md` §3): `@mantine/dates` is an OPTIONAL peer, so `basalt-ui/controls` must
+ * resolve for a consumer who has never installed it.
+ *
+ * Source-level, and deliberately so: `scripts/pack-test.sh` proves the same thing from the PACKED
+ * tarball with the peer genuinely absent, which is the stronger claim — but it runs in CI, on a
+ * built artifact, minutes later. This file fails in the unit loop, on the line that broke it, which
+ * is what makes the invariant cheap enough to hold. Both, not either.
+ *
+ * The second half is the direction of the dependency: `./controls-dates` may reach INTO `./controls`
+ * (for the `RangeCustomPickerProps` contract, type-only), never the reverse — a runtime import back
+ * would put `@mantine/dates` in `./controls`' graph through the side door, which is exactly the
+ * failure a lazy `import()` would also cause and the reason `RangeFilter` takes the picker as a prop.
+ */
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = join(import.meta.dir, '..')
+
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g
+const LINE_COMMENT = /\/\/.*$/gm
+
+/** Every static or dynamic reference to `spec` that survives to runtime. Type-only forms excluded. */
+function runtimeReferences(source: string, spec: string): boolean {
+  const code = source.replace(BLOCK_COMMENT, '').replace(LINE_COMMENT, '')
+  const quoted = `['"]${spec.replace(/[/*]/g, (c) => `\\${c}`)}['"]`
+  const staticForm = new RegExp(
+    `^(?:import|export)\\s+(?!type\\b)[^\\n]*from\\s+${quoted}|^import\\s+(?!type\\b)${quoted}`,
+    'm',
+  )
+  const dynamicForm = new RegExp(`import\\s*\\(\\s*${quoted}`)
+  return staticForm.test(code) || dynamicForm.test(code)
+}
+
+function filesUnder(dir: string): string[] {
+  const glob = new Bun.Glob('**/*.{ts,tsx}')
+  return [...glob.scanSync({ cwd: join(SRC, dir) })].map((rel) => join(SRC, dir, rel))
+}
+
+describe('./controls never reaches @mantine/dates', () => {
+  const files = filesUnder('controls')
+
+  test('the walk found files to scan', () => {
+    expect(files.length).toBeGreaterThan(5)
+  })
+
+  test('no file under src/controls imports @mantine/dates, statically or lazily', () => {
+    const violations = files
+      .filter((file) => runtimeReferences(readFileSync(file, 'utf8'), '@mantine/dates'))
+      .map((file) => file.slice(SRC.length + 1))
+    expect(violations).toEqual([])
+  })
+})
+
+describe('the dependency points one way', () => {
+  test('no file under src/controls imports src/controls-dates', () => {
+    const violations = filesUnder('controls')
+      .filter((file) => /from\s+['"]\.\.\/controls-dates/.test(readFileSync(file, 'utf8')))
+      .map((file) => file.slice(SRC.length + 1))
+    expect(violations).toEqual([])
+  })
+
+  test('src/controls-dates reaches ../controls for TYPES only — a runtime edge would leak the peer', () => {
+    const violations = filesUnder('controls-dates')
+      .filter((file) => {
+        const source = readFileSync(file, 'utf8')
+        return /from\s+['"]\.\.\/controls/.test(
+          source
+            .replace(/export\s+type\s+\{[^}]*\}\s+from\s+['"][^'"]*['"]/g, '')
+            .replace(/import\s+type\s+\{[^}]*\}\s+from\s+['"][^'"]*['"]/g, ''),
+        )
+      })
+      .map((file) => file.slice(SRC.length + 1))
+    expect(violations).toEqual([])
+  })
+
+  test('@mantine/dates is reached from exactly one place — src/controls-dates', () => {
+    const importers = filesUnder('controls-dates')
+      .filter((file) => runtimeReferences(readFileSync(file, 'utf8'), '@mantine/dates'))
+      .map((file) => file.slice(SRC.length + 1))
+    expect(importers).toEqual(['controls-dates/date-range-picker.tsx'])
+  })
+})

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

@@ -0,0 +1,137 @@
+/**
+ * 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 { NumberFilter } from './number-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(),
+    nights: field.number({ fallback: 2, min: 1, max: 14, int: true }),
+  },
+})
+
+/** 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} />
+      {/* @ts-expect-error C2 — a number filter is store-bound too; there is no `value`. */}
+      <NumberFilter field={local.field.nights} label="Nights" value={3} />
+      {/* @ts-expect-error C5 — the home sets the tier. `step` is the stepper's increment, not a size. */}
+      <NumberFilter field={local.field.nights} label="Nights" size="xs" />
+      {/* @ts-expect-error an enum field is not a number field — the whole point of the control. */}
+      <NumberFilter field={local.field.currency} label="Nights" />
+      {/* @ts-expect-error `label` is required — the popover and the sheet both need a heading. */}
+      <NumberFilter field={local.field.nights} />
+      {/* NumberFilter's options are NUMBERS. A string here is the exact shape argo reached for when
+          it widened `nights` into an enum, and it has to be a type error rather than a silent
+          `Number('7')` at the boundary. */}
+      <NumberFilter
+        field={local.field.nights}
+        label="Nights"
+        // @ts-expect-error a numeric preset set takes `value: number`, never a numeral string.
+        options={[{ value: '7', label: 'A week' }]}
+      />
+      {/* @ts-expect-error `min`/`max` belong to the FIELD, which is what validates the URL. */}
+      <NumberFilter field={local.field.nights} label="Nights" min={1} />
+    </>
+  )
+}
+
+/** 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} />
+      {/* Both forms, spelled correctly: the preset set, and the open stepper. */}
+      <NumberFilter
+        field={local.field.nights}
+        label="Nights"
+        options={[
+          { value: 1, label: '1 night' },
+          { value: 7, label: 'A week' },
+        ]}
+      />
+      <NumberFilter field={local.field.nights} label="Nights" step={2} />
+    </>
+  )
+}
+
+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')
+  })
+})