basalt-ui 1.24.0 → 1.26.0

package/src/controls/actions.type-guard.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Compile-time proof that law C6's "exactly one primary" is a TYPE fact, not a runtime check.
+ *
+ * `ActionGroupProps.primary` is singular, so a second one is unwritable: an array is rejected, and
+ * a duplicate object key is a tsc error in its own right. This mirrors the
+ * `apps/playground/src/*.type-guard.ts` convention (one `@ts-expect-error` per bad line, proven by
+ * `tsc --noEmit`) but lives beside the type, exactly as `agent-chat/virtualize.type-guard.test.ts`
+ * does — and for the same packaging reason: a bare `*.type-guard.ts` under `src/` would be picked
+ * up by tsup's build glob and ship an unused fixture, while `*.test.ts` is excluded from it.
+ */
+import { describe, expect, test } from 'bun:test'
+import type { ActionGroupProps, BarAction, GlobalAction } from './actions'
+
+function accept(props: ActionGroupProps): ActionGroupProps {
+  return props
+}
+
+function acceptAction(action: BarAction): BarAction {
+  return action
+}
+
+function acceptGlobal(action: GlobalAction): GlobalAction {
+  return action
+}
+
+// ── Valid — must type-check with no error ─────────────────────────────────────
+
+accept({})
+accept({ primary: { key: 'a', label: 'A' } })
+accept({ primary: { key: 'a', label: 'A' }, secondary: [{ key: 'b', label: 'B' }] })
+accept({ secondary: [{ key: 'm', kind: 'menu', label: 'Export as', items: [] }] })
+accept({ primary: { key: 'c', kind: 'custom', node: null } })
+acceptAction({ key: 'a', label: 'A', mobile: 'hidden', danger: true })
+acceptGlobal({ key: 'g', node: null, mobile: 'bar' })
+
+// ── Invalid — each MUST be a tsc error, one directive per bad line ────────────
+
+const TWO: BarAction[] = [
+  { key: 'a', label: 'A' },
+  { key: 'b', label: 'B' },
+]
+// @ts-expect-error a SECOND primary is unwritable: `primary` is one action, never a list
+accept({ primary: TWO })
+// @ts-expect-error `secondary` is the list; a single action is not one
+accept({ secondary: { key: 'b', label: 'B' } })
+// @ts-expect-error a `kind: 'menu'` group has no mobile placement — it always folds
+acceptAction({ key: 'm', kind: 'menu', label: 'M', items: [], mobile: 'bar' })
+// @ts-expect-error a `kind: 'custom'` action carries a node, never a label
+acceptAction({ key: 'c', kind: 'custom', node: null, label: 'C' })
+// @ts-expect-error `label` is required on a button-shaped action
+acceptAction({ key: 'a' })
+// @ts-expect-error 'sheet' is not a mobile placement
+acceptAction({ key: 'a', label: 'A', mobile: 'sheet' })
+// @ts-expect-error a GlobalAction is data, not a bare node
+acceptGlobal({ node: null })
+
+describe('ActionGroupProps (type-guard)', () => {
+  test('is a compile-time-only fixture — see the @ts-expect-error directives above', () => {
+    // No runtime behavior to assert: the proof is that this file type-checks at all. A single
+    // trivial assertion keeps this a normal bun:test file rather than an empty-suite oddity.
+    expect(true).toBe(true)
+  })
+})

package/src/controls/compare-filter.tsx

@@ -0,0 +1,64 @@
+/**
+ * `CompareFilter` — the period-comparison enum every dashboard grows
+ * (`docs/CONTROLS-SPEC.md` §3). A `SelectFilter` narrowed to the three values basalt names, so the
+ * label, the option order and the fallback are the same on every page instead of three per app.
+ *
+ * @example
+ * // compare: field.enum(['none', 'previous', 'year'], 'none')
+ * <CompareFilter field={analytics.field.compare} />
+ */
+import type { ReactNode } from 'react'
+import type { EnumField, FieldHandle } from '../state'
+import { EnumFilter } from './enum-filter'
+import { SwapGlyph } from './glyphs'
+
+/** The three comparison bases — declare the field as `field.enum(COMPARE_VALUES, 'none')`. */
+export type CompareValue = 'none' | 'previous' | 'year'
+
+/** The declared value order, so a consumer's `field.enum` and this control cannot disagree. */
+export const COMPARE_VALUES: readonly CompareValue[] = ['none', 'previous', 'year']
+
+/**
+ * The three option labels basalt names — the other half of "the same on every page instead of three
+ * per app", which this control promised and did not deliver.
+ *
+ * `field.enum` labels an option with the raw VALUE until a consumer calls `store.labels()`, so a
+ * `CompareFilter` over an unlabelled field printed `none` / `previous` / `year` in its popover and,
+ * now that the pill reads the value (see `EnumFilter`'s doc), in the bar too. Every app then wrote
+ * the same three strings into its own `labels()` call, which is three chances to disagree about what
+ * `year` means.
+ *
+ * These are DEFAULTS, not overrides: a field whose label differs from its value has been labelled
+ * deliberately, and that label wins. Detecting it as `label !== value` is exactly the signal
+ * `optionsFor` leaves behind (`state/fields.ts` — `label: map?.[value] ?? value`), so nothing new
+ * has to be threaded through the store to ask the question.
+ */
+export const COMPARE_LABELS: Readonly<Record<CompareValue, string>> = {
+  none: 'No comparison',
+  previous: 'Previous period',
+  year: 'Same period last year',
+}
+
+export type CompareFilterProps = {
+  readonly field: FieldHandle<EnumField<CompareValue>>
+  /** @default 'Compare' */
+  readonly label?: string
+  /** Leading pill icon. Defaults to an arrows-swap glyph — like `RangeFilter`'s calendar, the mark
+   *  is part of what makes the pill legible as a period comparison. */
+  readonly icon?: ReactNode
+}
+
+export function CompareFilter({ field, label = 'Compare', icon }: CompareFilterProps): ReactNode {
+  // Read through the handle's own options so a consumer's `labels()` and its option ORDER both
+  // survive; only an UNLABELLED row (label === value) takes basalt's default string.
+  const options = field.options.map((option) =>
+    option.label === option.value && isCompareValue(option.value)
+      ? { value: option.value, label: COMPARE_LABELS[option.value] }
+      : option,
+  )
+  return <EnumFilter field={field} label={label} icon={icon ?? <SwapGlyph />} options={options} />
+}
+
+function isCompareValue(value: string): value is CompareValue {
+  return (COMPARE_VALUES as readonly string[]).includes(value)
+}

package/src/controls/control-group.test.tsx

@@ -0,0 +1,229 @@
+/**
+ * `ControlGroup` — the joined-control primitive (`docs/CONTROLS-SPEC.md` §3), and `ActionGroup`'s
+ * derived use of it.
+ *
+ * The gap it closes: every consumer that wanted a `‹ Today ›` stepper hand-built one — a `Group
+ * gap={0}` plus per-child `radius` and `style={{ marginLeft: -1 }}`, restated on each page, each
+ * getting the focus-ring z-index wrong in its own way. `basalt/shadow-basalt-export` now names the
+ * three words that fork tends to arrive under (`ButtonGroup`, `ButtonRow`, `JoinedButtons`).
+ *
+ * The GEOMETRY is CSS, and CSS-module hashes are unavailable under `bun test`, so it is asserted
+ * from the module text (the idiom `filter-set.test.tsx` and `theme/layout-rhythm-css.test.ts` use).
+ * The PARTITION — which adjacent actions get joined — is real logic and is rendered.
+ */
+import { ActionIcon, Button, MantineProvider } from '@mantine/core'
+import { render } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ReactNode } from 'react'
+import { ActionGroup } from './actions'
+import type { BarAction } from './actions'
+import { ControlGroup } from './control-group'
+
+const CSS = readFileSync(join(import.meta.dir, 'controls.module.css'), 'utf8')
+const JOINED = CSS.slice(CSS.indexOf('/* ── ControlGroup'))
+
+function mount(node: ReactNode) {
+  return render(<MantineProvider>{node}</MantineProvider>)
+}
+
+const desktop = () => document.querySelector('.mantine-visible-from-sm')
+const mobile = () => document.querySelector('.mantine-hidden-from-sm')
+
+/** The joined boxes inside one variant of the row. */
+function groups(root: Element | null): Element[] {
+  return [...(root?.querySelectorAll('[data-gap]') ?? [])]
+}
+
+function Glyph(): ReactNode {
+  return <svg viewBox="0 0 24 24" />
+}
+
+describe('the joined box', () => {
+  test('renders one element carrying the gap mode, defaulting to "none"', () => {
+    const { container } = mount(
+      <ControlGroup>
+        <Button variant="default">Today</Button>
+      </ControlGroup>,
+    )
+    expect(container.querySelector('[data-gap]')?.getAttribute('data-gap')).toBe('none')
+  })
+
+  test('gap="tight" is the un-joined mode, for a set that must stay separately pressable', () => {
+    const { container } = mount(
+      <ControlGroup gap="tight">
+        <Button variant="default">A</Button>
+        <Button variant="default">B</Button>
+      </ControlGroup>,
+    )
+    expect(container.querySelector('[data-gap]')?.getAttribute('data-gap')).toBe('tight')
+    expect(JOINED).toContain("[data-gap='tight'] {\n  gap: var(--vx-space-control-gap")
+  })
+
+  test('joined children collapse their two adjacent borders into one', () => {
+    // 2px down the middle reads as a gap someone forgot to close, not as a divider.
+    expect(JOINED).toContain("[data-gap='none'] > * + * {\n  margin-inline-start: -1px;")
+  })
+
+  test('the radius lives on the outer ends only — that is what makes three boxes one box', () => {
+    expect(JOINED).toContain("[data-gap='none'] > *:not(:first-child):not(:last-child) {")
+    expect(JOINED).toContain('border-radius: 0;')
+    expect(JOINED).toContain("[data-gap='none'] > *:first-child:not(:only-child) {")
+    expect(JOINED).toContain("[data-gap='none'] > *:last-child:not(:only-child) {")
+  })
+
+  test('a one-child group keeps its normal shape — :only-child is excluded on both ends', () => {
+    // A conditional render that dropped two of three children must not lose half its corners.
+    expect(JOINED).toContain(':first-child:not(:only-child)')
+    expect(JOINED).toContain(':last-child:not(:only-child)')
+  })
+
+  test('the internal hairline is drawn here, because the default border is transparent', () => {
+    // `cssVariablesResolver` points `--mantine-color-default-border` at transparent on purpose
+    // (DESIGN-SPEC §8). The 12%-ink value is `.pill`'s, so a joined pill row and a joined button row
+    // read as one family.
+    expect(JOINED).toContain("[data-gap='none'] > [data-variant='default'] {")
+    expect(JOINED).toContain('color-mix(in srgb, var(--vx-ink) 12%, transparent)')
+  })
+
+  test('a filled child keeps its fill edge — the border rule is scoped to the default variant', () => {
+    expect(JOINED).not.toMatch(/\[data-gap='none'\] > \* \{\s*border-color/)
+  })
+
+  test('hover/focus/active raise the child so its shared edge paints whole', () => {
+    expect(JOINED).toContain("[data-gap='none'] > *:focus-visible,")
+    expect(JOINED).toContain('z-index: 1;')
+    expect(JOINED).toContain('position: relative;')
+  })
+
+  test('the group never wraps — a joined set that broke mid-box is worse than an overflow', () => {
+    const rule = JOINED.slice(
+      JOINED.indexOf('.group {'),
+      JOINED.indexOf('}', JOINED.indexOf('.group {')),
+    )
+    expect(rule).toContain('flex-wrap: nowrap')
+    expect(rule).toContain('flex: none')
+  })
+
+  test('it adds no role and no label — a joined LOOK is not a semantic group', () => {
+    const { container } = mount(
+      <ControlGroup>
+        <ActionIcon variant="default" aria-label="Previous">
+          <Glyph />
+        </ActionIcon>
+        <Button variant="default">Today</Button>
+      </ControlGroup>,
+    )
+    const box = container.querySelector('[data-gap]')
+    expect(box?.hasAttribute('role')).toBe(false)
+    expect(box?.hasAttribute('aria-label')).toBe(false)
+  })
+})
+
+describe('ActionGroup joins what belongs together, and nothing else', () => {
+  const stepper: BarAction[] = [
+    { key: 'prev', label: 'Previous period', icon: <Glyph />, group: true },
+    { key: 'today', label: 'Today', group: true },
+    { key: 'next', label: 'Next period', icon: <Glyph />, group: true },
+  ]
+
+  test('a run of group:true secondaries becomes ONE joined box on desktop', () => {
+    mount(<ActionGroup secondary={stepper} />)
+    const joined = groups(desktop())
+    expect(joined.length).toBe(1)
+    expect(joined[0]?.querySelectorAll('button').length).toBe(3)
+  })
+
+  test('a joined member with an icon renders icon-only, its label demoted to the a11y name', () => {
+    // `‹ Today ›` is ONE control whose middle segment names it; the arrows' content is their
+    // direction. Labelled, the same three actions measured 304px against 118px in Chrome.
+    mount(<ActionGroup secondary={stepper} />)
+    const row = desktop()
+    const prev = row?.querySelector('[aria-label="Previous period"]')
+    expect(prev).not.toBeNull()
+    expect(prev?.textContent).toBe('')
+    // The one member with no icon keeps its label — the rule reads what the caller supplied.
+    expect(row?.textContent).toBe('Today')
+  })
+
+  test('a joined set with NO icons keeps every label — the icon-only rule is not a width policy', () => {
+    mount(
+      <ActionGroup
+        secondary={[
+          { key: 'abs', label: 'Absolute', group: true },
+          { key: 'rate', label: 'Rate', group: true },
+        ]}
+      />,
+    )
+    expect(groups(desktop()).length).toBe(1)
+    expect(desktop()?.textContent).toBe('AbsoluteRate')
+  })
+
+  test('independent secondaries are NOT joined — the default row is unchanged', () => {
+    mount(
+      <ActionGroup
+        secondary={[
+          { key: 'export', label: 'Export CSV' },
+          { key: 'accounts', label: 'Accounts', icon: <Glyph /> },
+        ]}
+      />,
+    )
+    expect(groups(desktop()).length).toBe(0)
+  })
+
+  test('a non-group action between two group ones splits the run in two', () => {
+    // Two runs of one is the same row it was before — the group flag is per-member on purpose, so a
+    // set that forgets one member degrades to the old row instead of joining the wrong things.
+    mount(
+      <ActionGroup
+        secondary={[
+          { key: 'prev', label: 'Prev', group: true },
+          { key: 'loose', label: 'Loose' },
+          { key: 'next', label: 'Next', group: true },
+        ]}
+      />,
+    )
+    expect(groups(desktop()).length).toBe(0)
+  })
+
+  test('adjacent ICON-ONLY entries join on the MOBILE bar without any flag', () => {
+    // Below `sm` an icon-bearing action renders as an `ActionIcon` and nothing else, so two in a row
+    // are two 30px squares with a gap — three boxes' worth of border for two actions, exactly where
+    // width is scarcest.
+    mount(
+      <ActionGroup
+        secondary={[
+          { key: 'a', label: 'Filter', icon: <Glyph />, mobile: 'bar' },
+          { key: 'b', label: 'Sort', icon: <Glyph />, mobile: 'bar' },
+        ]}
+      />,
+    )
+    expect(groups(mobile()).length).toBe(1)
+    // …and NOT on desktop, where the same two actions are labelled buttons that are not related.
+    expect(groups(desktop()).length).toBe(0)
+  })
+
+  test('the mobile PRIMARY is never joined to a sibling — a fill edge against a border edge', () => {
+    mount(
+      <ActionGroup
+        primary={{ key: 'save', label: 'Save', icon: <Glyph /> }}
+        secondary={[{ key: 'a', label: 'Filter', icon: <Glyph />, mobile: 'bar' }]}
+      />,
+    )
+    expect(groups(mobile()).length).toBe(0)
+  })
+
+  test('a kind:"custom" entry breaks the run — basalt does not draw that node', () => {
+    mount(
+      <ActionGroup
+        secondary={[
+          { key: 'prev', label: 'Prev', group: true },
+          { key: 'chip', kind: 'custom', node: <span>live</span> },
+          { key: 'next', label: 'Next', group: true },
+        ]}
+      />,
+    )
+    expect(groups(desktop()).length).toBe(0)
+  })
+})

package/src/controls/control-group.tsx

@@ -0,0 +1,63 @@
+/**
+ * `ControlGroup` — adjacent controls that act on ONE thing, joined into one box
+ * (`docs/CONTROLS-SPEC.md` §3). Blueprint's `ControlGroup` and Mantine's own `Button.Group` are the
+ * same primitive; neither works here, because basalt's tier holds `FilterPill`s, `Button`s,
+ * `ActionIcon`s and `TextInput`s in the same row and Mantine's `Button.Group` joins Buttons only
+ * (it declares its own `section-*` size vars, which the `ctl` tier does not define — see
+ * `theme/ctl-tier-coverage.test.ts`'s note on why `*Group` directories are excluded from the scan).
+ *
+ * **What it is for.** A `‹ Today ›` date stepper, a `− 1 +` quantity, an `Absolute | Rate` pair — a
+ * set of controls a reader should read as ONE control with several affordances. The joined box is the
+ * statement: these three act on the same value, and the two dividers inside it are the only place a
+ * hairline is a divider rather than a border (`docs/DESIGN-SPEC.md` §8 — depth is a shadow). A row of
+ * INDEPENDENT actions is not this; that is `ActionGroup`, and joining it would claim a relationship
+ * that is not there.
+ *
+ * **Presentational by design — no `role`, no `aria-label`.** A joined LOOK is not a semantic group:
+ * each child is already a button or an input with its own accessible name, and wrapping them in a
+ * `role="group"` adds a level to the a11y tree that announces nothing a reader needs. Where the set
+ * genuinely IS one control with one name — a range picker, a tab set — basalt already ships that
+ * control (`RangeFilter`, `ViewTabs`) with the right semantics, and reaching for `ControlGroup`
+ * instead is `basalt/hand-rolled-filter`.
+ *
+ * @example
+ * // The one shape this exists for: three affordances, one value.
+ * <ControlGroup>
+ *   <ActionIcon variant="default" aria-label="Previous period" onClick={back}><IconLeft /></ActionIcon>
+ *   <Button variant="default" onClick={today}>Today</Button>
+ *   <ActionIcon variant="default" aria-label="Next period" onClick={next}><IconRight /></ActionIcon>
+ * </ControlGroup>
+ */
+import { Box } from '@mantine/core'
+import type { ReactNode } from 'react'
+import classes from './controls.module.css'
+
+export type ControlGroupProps = {
+  readonly children: ReactNode
+  /**
+   * `none` (the default) JOINS the children: no gap, one shared hairline between each pair, and the
+   * corner radius only on the outer ends, so the set reads as one box.
+   *
+   * `tight` keeps the tier's own control gap and only guarantees the alignment and the no-wrap. It
+   * is for a set that belongs together but must stay separately pressable — three destructive
+   * actions, or a pair where one child is `filled` and joining it would put a fill edge against a
+   * border edge.
+   *
+   * @default 'none'
+   */
+  readonly gap?: 'none' | 'tight'
+  readonly className?: string
+}
+
+export function ControlGroup({ children, gap = 'none', className }: ControlGroupProps): ReactNode {
+  return (
+    // A Mantine `Box`, not a raw `<div>` — `basalt/raw-html-layout` flags layout styling on a bare
+    // HTML tag, the same reason `CtlSlot` uses one.
+    <Box
+      className={className === undefined ? classes.group : `${classes.group} ${className}`}
+      data-gap={gap}
+    >
+      {children}
+    </Box>
+  )
+}