basalt-ui 1.25.0 → 1.27.0

package/src/controls/range-filter.tsx

@@ -0,0 +1,237 @@
+/**
+ * `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 house dev gate — `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle
+ *  constant-folds this to `false` and drops the warning. Read per call, never hoisted. */
+function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}
+
+/** Once per label — a filter renders on every navigation, and the wiring is fixed at definition. */
+const noPickerWarned = new Set<string>()
+
+/**
+ * Dev-only: the field declares `custom: true` and no picker was injected, so the custom window is
+ * unreachable — the popover shows presets only and the sheet's `Custom range…` row never renders.
+ * A warning rather than a type error: `custom: true` with presets only is a legal (and tested)
+ * configuration, and the picker is INJECTED precisely because `@mantine/dates` may be absent, so
+ * the type cannot tell "deliberately preset-only" from "forgot the import".
+ */
+function warnCustomWithoutPicker(label: string, unreachable: boolean): void {
+  if (!unreachable || !isDev() || noPickerWarned.has(label)) return
+  noPickerWarned.add(label)
+  // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
+  console.warn(
+    `[basalt-ui] RangeFilter('${label}'): the field declares \`custom: true\` but no ` +
+      '`customPicker` was injected, so the custom window cannot be reached. Pass ' +
+      '`customPicker={DateRangePicker}` (`basalt-ui/controls-dates`), or drop `custom: true` from ' +
+      'the field. (dev only)',
+  )
+}
+
+/**
+ * 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
+}
+
+/** Everything about the props that does not depend on the field's `custom` flag. */
+type RangeFilterBase<P extends string, C extends boolean> = {
+  /**
+   * A range handle from either store factory. Generic over the field's `custom` flag so a
+   * `field.range({ ... })` WITHOUT `custom` (whose handle is `RangeField<P, false>`, and whose
+   * values therefore never include `'custom'`) binds with no cast — pinning `C` to its default
+   * `boolean` here made the setter contravariantly incompatible and forced one at every call site.
+   */
+  readonly field: FieldHandle<RangeField<P, C>>
+  /** 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
+  /** Sheet-form heading. The pill's own label is the VALUE, which is what a bar reads. @default 'Range' */
+  readonly label?: string
+}
+
+export type RangeFilterProps<P extends string, C extends boolean = boolean> = RangeFilterBase<
+  P,
+  C
+> & {
+  /**
+   * Rendered when the field declares `custom: true`. Omitted → presets only, which stays LEGAL
+   * (a range that only ever shows presets is a real configuration) but warns once in dev when the
+   * field allows a custom window: the affordance is then unreachable, and nothing else says so.
+   */
+  readonly customPicker?: ComponentType<RangeCustomPickerProps>
+}
+
+export function RangeFilter<P extends string, C extends boolean = boolean>(
+  props: RangeFilterProps<P, C>,
+): ReactNode {
+  const {
+    field,
+    icon,
+    customPicker,
+    label = 'Range',
+    // One cast, at the one boundary a generic `C` cannot be read through: `C` only ever describes
+    // the FIELD's custom flag, and the body handles both.
+  } = props as unknown as RangeFilterBase<P, boolean> & {
+    readonly customPicker?: ComponentType<RangeCustomPickerProps>
+  }
+  const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const isDefault = field.isDefault(value)
+  useFilterRegistration(!isDefault, () => {
+    field.clear()
+  })
+
+  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
+  warnCustomWithoutPicker(label, allowsCustom && Picker === undefined)
+  // 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/range-filter.type-guard.test.tsx

@@ -0,0 +1,122 @@
+/**
+ * `RangeFilterProps` is generic over the FIELD's `custom` flag — the compile-time half, plus the one
+ * runtime consequence of leaving `customPicker` out.
+ *
+ * Why a file of its own (the `actions.type-guard.test.ts` convention): pinning `C` to its default
+ * `boolean` made `RangeFilter field={...}` reject a `field.range({ … })` that never declared
+ * `custom: true`. The handle's setter is contravariant, so a `RangeValue<P>` setter cannot stand in
+ * for a `RangeValue<P | 'custom'>` one — two consumers cast at the call site instead, which is
+ * exactly the diagnostic the cast was hiding.
+ */
+import { describe, expect, spyOn, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import type { FieldHandle, RangeField } from '../state'
+import { createLocalStore, field } from '../state'
+import { RangeFilter } from './range-filter'
+import type { RangeCustomPickerProps } from './range-filter'
+
+// Two stores, not two range fields in one: every range defaults its `from`/`to` param names, and
+// the store core rejects the collision at definition (see `assertNoParamCollision`).
+const store = createLocalStore({
+  key: 'tg-range',
+  fields: {
+    presetsOnly: field.range({ presets: ['7d', '30d'], fallback: '30d' }),
+    view: field.enum(['chart', 'table'], 'chart'),
+  },
+})
+
+const customStore = createLocalStore({
+  key: 'tg-range-custom',
+  fields: { withCustom: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }) },
+})
+
+function Picker({ onChange }: RangeCustomPickerProps): ReactNode {
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        onChange({ from: '2026-03-01', to: '2026-03-14' })
+      }}
+    >
+      pick march
+    </button>
+  )
+}
+
+/** A control that took a range handle from ITS OWN props — `C` widened, which must still bind. */
+function Wrapper({ handle }: { handle: FieldHandle<RangeField<'7d' | '30d'>> }): ReactNode {
+  return <RangeFilter field={handle} customPicker={Picker} />
+}
+
+// ── Valid — must type-check with no error ─────────────────────────────────────
+
+function Accepted(): ReactNode {
+  return (
+    <>
+      {/* The regression: no `custom`, therefore `RangeField<P, false>` — and no cast. */}
+      <RangeFilter field={store.field.presetsOnly} />
+      <RangeFilter field={store.field.presetsOnly} label="Window" />
+      <RangeFilter field={customStore.field.withCustom} customPicker={Picker} />
+      <Wrapper handle={customStore.field.withCustom} />
+    </>
+  )
+}
+
+// ── Invalid — each MUST be a tsc error, one directive per bad line ────────────
+
+function Rejected(): ReactNode {
+  return (
+    <>
+      {/* @ts-expect-error an enum handle is not a range handle, whatever `C` is */}
+      <RangeFilter field={store.field.view} />
+      {/* @ts-expect-error `value`/`onChange` is not the binding a basalt control takes (C2) */}
+      <RangeFilter value={{ preset: '7d' }} onChange={() => {}} />
+    </>
+  )
+}
+
+/** The first argument of every captured warn call. */
+function lines(warn: { mock: { calls: unknown[][] } }): string[] {
+  return warn.mock.calls.map((call) => String(call[0]))
+}
+
+describe('RangeFilterProps (type-guard)', () => {
+  test('both fixtures exist — tsc, not bun, is the assertion for the cases above', () => {
+    expect(typeof Accepted).toBe('function')
+    expect(typeof Rejected).toBe('function')
+  })
+
+  test('a custom-capable field with no picker warns once in dev — the affordance is unreachable', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      render(
+        <MantineProvider>
+          <RangeFilter field={customStore.field.withCustom} label="Unreachable" />
+        </MantineProvider>,
+      )
+      expect(screen.getByRole('button', { name: '30d' })).toBeDefined()
+      expect(
+        lines(warn).filter((line) => line.includes("RangeFilter('Unreachable')")),
+      ).toHaveLength(1)
+      expect(lines(warn)[0]).toContain('customPicker')
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  test('a preset-only field is silent — presets only is a configuration, not a mistake', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      render(
+        <MantineProvider>
+          <RangeFilter field={store.field.presetsOnly} label="Silent" />
+        </MantineProvider>,
+      )
+      expect(lines(warn).filter((line) => line.includes("RangeFilter('Silent')"))).toHaveLength(0)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+})

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), () => {
+    field.clear()
+  })
+
+  // `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