basalt-ui 1.24.0 → 1.26.0

package/src/theme/ctl-theme.test.tsx

@@ -0,0 +1,275 @@
+/**
+ * `CtlSlot`/`CTL_THEME` — proves the `size="ctl"` default reaches a bare `<Button>` dropped into
+ * the slot with NO prop at the call site, and that the tier stays scoped to the slot (a sibling
+ * `<Button>` outside `<CtlSlot>` never resolves the `-ctl` var).
+ *
+ * `data-size`/the inline `style` custom-property string are Mantine's own render output — verified
+ * directly against a real render (`@testing-library/react`, `tests/setup/dom.ts`'s jsdom harness),
+ * not asserted from memory. jsdom does not compute the CSS cascade, so this can only prove the
+ * INLINE var REFERENCE Mantine's `varsResolver` emits (`--button-height: var(--button-height-ctl)`)
+ * — not the resolved pixel value, which is `cssVariablesResolver`'s and `spaceDecls`'s job
+ * (covered by `spacing.test.ts`/`density.test.ts`).
+ *
+ * Outside `<CtlSlot>`, `<Button>` resolves to Mantine's own native default, NOT basalt's `md` —
+ * verified against `theme/index.ts`'s `Button.extend`: unlike Input/TextInput/NumberInput/
+ * PasswordInput/Select/Textarea, basalt sets no `defaultProps.size` for Button/ActionIcon at all,
+ * so an un-sized Button carries no `data-size` attribute and no `--button-height` inline var
+ * (Mantine's own CSS stylesheet default takes over). The test below asserts the accurate,
+ * verified claim — the tier does not leak past the slot — rather than a `size="md"` claim Button
+ * was never given.
+ */
+import { ActionIcon, Button, Checkbox, MantineProvider, Radio, Switch } from '@mantine/core'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { FilterPill } from '../controls/filter-pill'
+import { StatCard } from '../dashboard/stat-card'
+import { baseTheme } from './index'
+import { CTL_THEME, CtlSlot } from './ctl-theme'
+
+describe('CtlSlot', () => {
+  test('a bare Button inside CtlSlot resolves the ctl tier with no size prop', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <Button>Save</Button>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    const button = container.querySelector('button')
+    expect(button?.getAttribute('data-size')).toBe('ctl')
+    expect(button?.style.getPropertyValue('--button-height')).toBe('var(--button-height-ctl)')
+    expect(button?.style.getPropertyValue('--button-padding-x')).toBe('var(--button-padding-x-ctl)')
+  })
+
+  test('the wrapper carries the data-basalt-tier marker and stays out of flow', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <Button>Save</Button>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    const wrapper = container.querySelector('[data-basalt-tier]')
+    expect(wrapper?.getAttribute('data-basalt-tier')).toBe('ctl')
+    expect((wrapper as HTMLElement | null)?.style.display).toBe('contents')
+  })
+
+  test('a Button outside CtlSlot never resolves the ctl tier', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <Button>Save</Button>
+      </MantineProvider>,
+    )
+    const button = container.querySelector('button')
+    expect(button?.getAttribute('data-size')).not.toBe('ctl')
+    expect(button?.style.getPropertyValue('--button-height')).not.toBe('var(--button-height-ctl)')
+  })
+
+  test('CTL_THEME sets defaultProps.size "ctl" for every documented component', () => {
+    const names = [
+      'Button',
+      'ActionIcon',
+      'Input',
+      'TextInput',
+      'Select',
+      'MultiSelect',
+      'SegmentedControl',
+      'NativeSelect',
+      'Radio',
+      'RadioGroup',
+      'Checkbox',
+      'CheckboxGroup',
+      'Switch',
+      'SwitchGroup',
+    ] as const
+    for (const name of names) {
+      expect(CTL_THEME.components?.[name]?.defaultProps?.['size']).toBe('ctl')
+    }
+  })
+})
+
+/**
+ * Radio/Checkbox/Switch at the tier, and the portal question that had to be settled before the
+ * defaults could be trusted: a filter's popover body and the mobile sheet are rendered
+ * `withinPortal`, so they are NOT DOM descendants of the `<CtlSlot>` wrapper — but a React portal
+ * preserves the React tree, and `MantineThemeProvider` is React context. So the tier DOES reach them,
+ * and no second `CtlSlot` inside `Popover.Dropdown`/`Drawer` is needed. These tests are what makes
+ * that a checked fact rather than a reasoned one.
+ */
+describe('the toggle family at the ctl tier', () => {
+  test('a bare Radio inside CtlSlot resolves the ctl indicator box', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <Radio value="a" label="Previous period" />
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    const root = container.querySelector('.mantine-Radio-root')
+    expect(root?.getAttribute('style')).toContain('--radio-size: var(--radio-size-ctl)')
+    expect(root?.getAttribute('style')).toContain('--radio-icon-size: var(--radio-icon-size-ctl)')
+  })
+
+  test('a bare Checkbox inside CtlSlot resolves the ctl indicator box', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <Checkbox value="a" label="Web" />
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    expect(container.querySelector('.mantine-Checkbox-root')?.getAttribute('style')).toContain(
+      '--checkbox-size: var(--checkbox-size-ctl)',
+    )
+  })
+
+  test('a bare Switch inside CtlSlot resolves all five of its ctl vars', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <Switch label="Errors only" />
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    const style = container.querySelector('.mantine-Switch-root')?.getAttribute('style') ?? ''
+    for (const prefix of [
+      'switch-height',
+      'switch-width',
+      'switch-thumb-size',
+      'switch-label-font-size',
+      'switch-track-label-padding',
+    ]) {
+      expect(style).toContain(`--${prefix}: var(--${prefix}-ctl)`)
+    }
+  })
+
+  test('a Radio outside CtlSlot keeps Mantine’s own default — the tier does not leak', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <Radio value="a" label="Previous period" />
+      </MantineProvider>,
+    )
+    expect(
+      container.querySelector('.mantine-Radio-root')?.getAttribute('style') ?? '',
+    ).not.toContain('var(--radio-size-ctl)')
+  })
+
+  test('a PORTALED popover body inherits the tier — React context crosses a portal', async () => {
+    render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <FilterPill label="No comparison">
+            <Radio.Group value="previous">
+              <Radio value="previous" label="Previous period" />
+            </Radio.Group>
+          </FilterPill>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'No comparison' }))
+    })
+    // The dropdown is a portal at document.body — deliberately queried off `document`, not the
+    // render container, because being outside the container is the whole point of the test.
+    const root = document.querySelector('.mantine-Popover-dropdown .mantine-Radio-root')
+    expect(root).not.toBeNull()
+    expect(root?.getAttribute('style')).toContain('--radio-size: var(--radio-size-ctl)')
+  })
+})
+
+/**
+ * `tier="widget"` — the 24px ActionIcon step a `WidgetHeader tier="widget"` header row can hold.
+ *
+ * The bug: `StatCard` wrapped its `actions` slot in a plain `<CtlSlot>`, so a bare `ActionIcon`
+ * resolved to the 30px `ctl` tier inside a 28px header row (`--vx-space-widget-header-height`) and
+ * grew it to 30. Measured in Chrome on the playground's dashboard at 390px, two KPI cards in the
+ * same grid row: the one WITH a kebab put its hero value at y=164, the one without at y=162 — the
+ * whole card, and every number in it, 2px out of line because of a slot's tier.
+ */
+describe('CtlSlot tier="widget"', () => {
+  test('a bare ActionIcon resolves the 24px icon step, not the 30px ctl one', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot tier="widget">
+          <ActionIcon variant="subtle" aria-label="Card actions">
+            <span />
+          </ActionIcon>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    const button = container.querySelector('button')
+    expect(button?.getAttribute('data-size')).toBe('icon')
+    // `--ai-size-icon` reads `--vx-space-control-height-widget` (24px) in `ctlSizeVars()`, so the
+    // tier tracks the density knob like every other control height.
+    expect(button?.style.getPropertyValue('--ai-size')).toBe('var(--ai-size-icon)')
+  })
+
+  test('the marker is the TIER name, the same one ChartCard writes by hand', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot tier="widget">
+          <span />
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    expect(container.querySelector('[data-basalt-tier]')?.getAttribute('data-basalt-tier')).toBe(
+      'widget',
+    )
+  })
+
+  test('the default is still `ctl` — no call site had to change', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot>
+          <ActionIcon variant="subtle" aria-label="Sync">
+            <span />
+          </ActionIcon>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    expect(container.querySelector('button')?.getAttribute('data-size')).toBe('ctl')
+    expect(container.querySelector('[data-basalt-tier]')?.getAttribute('data-basalt-tier')).toBe(
+      'ctl',
+    )
+  })
+
+  test('the widget tier is ActionIcon-only — a Button in it keeps whatever it had', () => {
+    // Only `--ai-size-icon` exists at this step (`theme/index.ts`'s `ctlSizeVars`). Defaulting a
+    // Button to `size="icon"` would resolve `--button-height: var(--button-height-icon)` to nothing
+    // and paint a zero-height button — the exact `-xs`-var failure `ctlSizeVars`' doc records.
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <CtlSlot tier="widget">
+          <Button>Save</Button>
+        </CtlSlot>
+      </MantineProvider>,
+    )
+    expect(container.querySelector('button')?.getAttribute('data-size')).not.toBe('icon')
+  })
+})
+
+/**
+ * `StatCard`'s own slot — the regression guard on the call site, not just on the mechanism. A
+ * `<CtlSlot>` here (the default tier) is what shipped, and nothing else in the suite would have
+ * caught it.
+ */
+describe('StatCard mounts its actions slot at the widget tier', () => {
+  test('a raw ActionIcon in `actions` lands on the 24px step', () => {
+    const { container } = render(
+      <MantineProvider theme={baseTheme}>
+        <StatCard
+          title="Total sales"
+          value="$1294.9k"
+          actions={
+            <ActionIcon variant="subtle" aria-label="Card actions">
+              <span />
+            </ActionIcon>
+          }
+        />
+      </MantineProvider>,
+    )
+    const slot = container.querySelector('[data-basalt-tier]')
+    expect(slot?.getAttribute('data-basalt-tier')).toBe('widget')
+    expect(container.querySelector('button')?.getAttribute('data-size')).toBe('icon')
+  })
+})

package/src/theme/ctl-theme.tsx

@@ -0,0 +1,138 @@
+/**
+ * The `size="ctl"` slot theme (`docs/CONTROLS-SPEC.md` §5) — every home (`PageBar`, `Section`,
+ * table toolbar, sidebar blocks, wave 3/4) wraps its **slot**, never its body, in `<CtlSlot>` so a
+ * raw `Button`/`ActionIcon`/`Input`/… dropped into that slot renders at the `ctl` tier with NO prop
+ * at the call site — a `size="xs"` typed there is C5 (`basalt/control-size-literal`).
+ *
+ * `CTL_THEME.components[*].defaultProps.size = 'ctl'` only sets the DEFAULT — an explicit
+ * `size="md"` (or anything else) at the call site still wins, same override precedence as every
+ * other Mantine `defaultProps`. Mantine's own `mergeMantineTheme` DEEP-merges `components` (not a
+ * shallow replace), so nesting `<CtlSlot>` under `BasaltProvider` never drops the base theme's
+ * `Button.extend`/`ActionIcon.extend`/… `vars`/`classNames` (the shadow/depth idiom,
+ * `docs/DESIGN-SPEC.md` §5) — only `defaultProps.size` is added on top.
+ *
+ * `Menu` is deliberately absent — verified against the installed `@mantine/core` 9.3.0 source
+ * (`Menu.d.ts`, `MenuItem.d.ts`): neither accepts a `size` prop at all, so "Menu/Menu.Item where
+ * applicable" (the spec's own hedge) resolves to "not applicable" here.
+ *
+ * **Radio / Checkbox / Switch and their `.Group`s, and the one consequence worth stating.** These
+ * three default to Mantine's `sm` — a 20px indicator beside the tier's 13.5px option label — which
+ * is what every filter popover and the mobile sheet rendered. They are here rather than fixed in a
+ * CSS module because their geometry is a Mantine SIZE (five vars for a Switch alone), so the tier
+ * reaches them the same way it reaches Button and Input: through `-ctl` vars in
+ * `cssVariablesResolver`. The `.Group`s are listed too, so the group's `Input.Wrapper` label lands
+ * on the tier's font step as well.
+ *
+ * The consequence: Mantine resolves a Radio's size as `props.size ? props.size : ctx.size`
+ * (`Radio.mjs`), and a theme `defaultProps.size` is indistinguishable from an explicit prop to that
+ * check — so inside a `<CtlSlot>` a `<Radio.Group size="lg">` no longer sizes its children, they stay
+ * `ctl`. That is the correct trade in a home's SLOT (the whole contract there is "everything is the
+ * tier"), and it is stated here because it is the kind of thing that otherwise gets rediscovered as
+ * a bug. A consumer wanting a `lg` radio group puts it in a BODY, which no `CtlSlot` wraps.
+ */
+import {
+  ActionIcon,
+  Box,
+  Button,
+  Checkbox,
+  Input,
+  MantineThemeProvider,
+  MultiSelect,
+  NativeSelect,
+  Radio,
+  SegmentedControl,
+  Select,
+  Switch,
+  TextInput,
+} from '@mantine/core'
+import type { MantineSize, MantineThemeOverride } from '@mantine/core'
+import type { ReactNode } from 'react'
+
+/** The `MantineThemeOverride` a `<CtlSlot>` provides — see this module's doc for the merge/
+ * precedence contract. Exported so a consumer composing its own slot (a bespoke home not covered
+ * by `PageBar`/`Section`/the sidebar blocks) can reach the SAME tier without re-declaring it. */
+export const CTL_THEME: MantineThemeOverride = {
+  components: {
+    Button: Button.extend({ defaultProps: { size: 'ctl' } }),
+    ActionIcon: ActionIcon.extend({ defaultProps: { size: 'ctl' } }),
+    Input: Input.extend({ defaultProps: { size: 'ctl' } }),
+    TextInput: TextInput.extend({ defaultProps: { size: 'ctl' } }),
+    Select: Select.extend({ defaultProps: { size: 'ctl' } }),
+    MultiSelect: MultiSelect.extend({ defaultProps: { size: 'ctl' } }),
+    SegmentedControl: SegmentedControl.extend({ defaultProps: { size: 'ctl' } }),
+    NativeSelect: NativeSelect.extend({ defaultProps: { size: 'ctl' } }),
+    // The theme keys are the component names Mantine's own `useProps` looks up — `RadioGroup`, not
+    // `Radio.Group` (`RadioGroup.mjs`: `useProps("RadioGroup", …)`).
+    Radio: Radio.extend({ defaultProps: { size: 'ctl' } }),
+    // Mantine types `RadioGroup.size` as a CLOSED `MantineSize`, while `Radio`, `Checkbox`,
+    // `Checkbox.Group`, `Switch` and `Switch.Group` all type theirs OPEN
+    // (`MantineSize | (string & {})`) — verified in the installed 9.3.0 `.d.ts` files, so this is an
+    // upstream inconsistency, not a statement that `RadioGroup` cannot take a custom tier. At
+    // runtime `getSize` interpolates the string identically for all six. The cast restores what
+    // every sibling type already allows; it widens nothing.
+    RadioGroup: Radio.Group.extend({ defaultProps: { size: 'ctl' as MantineSize } }),
+    Checkbox: Checkbox.extend({ defaultProps: { size: 'ctl' } }),
+    CheckboxGroup: Checkbox.Group.extend({ defaultProps: { size: 'ctl' } }),
+    Switch: Switch.extend({ defaultProps: { size: 'ctl' } }),
+    SwitchGroup: Switch.Group.extend({ defaultProps: { size: 'ctl' } }),
+  },
+}
+
+/**
+ * The `tier="widget"` slot theme — ActionIcon-ONLY, at the 24px `size="icon"` step
+ * (`--ai-size-icon` → `--vx-space-control-height-widget`, `docs/CONTROLS-SPEC.md` §5).
+ *
+ * It exists because a `WidgetHeader tier="widget"` header row is 28px
+ * (`--vx-space-widget-header-height`) and a 30px `ctl` control does not fit inside it. `StatCard`
+ * wrapped its `actions` slot in a plain `<CtlSlot>`, so a card WITH a kebab measured a 30px title
+ * row and a card WITHOUT one measured 28 — two KPI cards side by side in the same grid row were
+ * 2px out of alignment, and every number under them with it. Measured on the playground's dashboard
+ * at 390px: `Total sales` at 164 against `Orders` at 162.
+ *
+ * The tier is a HEIGHT statement, so a slot can only fix it by owning the size — which is exactly
+ * what {@link controlHeightWidget}'s own doc already said this step was for ("the `size="icon"`
+ * ActionIcon height — `WidgetHeader tier="widget"` actions"). It is ActionIcon-only because the
+ * tier has one var (`--ai-size-icon`): a 24px Button or Input has no vars declared and would
+ * silently resolve to its initial value, which is why widening this set is a
+ * `theme/index.ts`-first change, never a line added here.
+ */
+const WIDGET_THEME: MantineThemeOverride = {
+  components: {
+    ActionIcon: ActionIcon.extend({ defaultProps: { size: 'icon' } }),
+  },
+}
+
+export type CtlSlotProps = {
+  children: ReactNode
+  /**
+   * Which tier the slot imposes. `ctl` (the default) is the 30px control tier every home's control
+   * row uses. `widget` is the 24px ActionIcon step a `WidgetHeader tier="widget"` header row can
+   * hold — see {@link WIDGET_THEME} for the misalignment that makes it a separate tier rather than
+   * a caller's `size` prop.
+   *
+   * The values are the TIER names, matching the `data-basalt-tier` attribute the slot emits and the
+   * one `ChartCard` already writes by hand (it lives inside the Mantine-free `charts/` boundary and
+   * so cannot mount this component). `widget` maps to Mantine's `size="icon"`; the two vocabularies
+   * differ and that is upstream's, not basalt's.
+   *
+   * @default 'ctl'
+   */
+  tier?: 'ctl' | 'widget'
+}
+
+/**
+ * Wrap a home's SLOT (never its body) to render every Mantine control inside it at the `ctl` tier.
+ * The marker is a Mantine `Box` (not a raw `<div>` — `basalt/raw-html-layout` flags inline
+ * layout/surface styling on a bare HTML tag), `display: contents` keeps it out of the slot's own
+ * flex/grid layout while leaving the `data-basalt-tier="ctl"` attribute queryable/testable
+ * (`docs/CONTROLS-SPEC.md` §5) without the wrapper participating in flow.
+ */
+export function CtlSlot({ children, tier = 'ctl' }: CtlSlotProps): ReactNode {
+  return (
+    <MantineThemeProvider inherit theme={tier === 'widget' ? WIDGET_THEME : CTL_THEME}>
+      <Box data-basalt-tier={tier} style={{ display: 'contents' }}>
+        {children}
+      </Box>
+    </MantineThemeProvider>
+  )
+}

package/src/theme/ctl-tier-coverage.test.ts

@@ -0,0 +1,170 @@
+/**
+ * The ctl-tier coverage gate (`docs/CONTROLS-SPEC.md` §5) — greps every `getSize(size, '<prefix>')`
+ * / `getFontSize(size)` call in the INSTALLED `@mantine/core` source for the TWELVE components the
+ * tier covers (Button, ActionIcon, Input, SegmentedControl, Combobox, Select, MultiSelect,
+ * TextInput, Menu — the nine the spec names — plus Radio, Checkbox and Switch) and asserts
+ * `cssVariablesResolver`'s `variables` block declares a `-ctl` var for every distinct prefix found —
+ * so a missing var (the `--button-padding-x-ctl` the spec's own text calls out as "every draft
+ * omitted") fails the build instead of silently rendering at 0px/undefined.
+ *
+ * Radio/Checkbox/Switch joined the scan when they joined `CTL_THEME`: they had defaulted to
+ * Mantine's `sm`, a 20px indicator beside the tier's 13.5px option label, in every filter popover and
+ * in the mobile sheet. Adding them to `defaultProps` without declaring their vars would have been
+ * strictly worse than leaving them alone — an undeclared `--radio-size-ctl` resolves to the
+ * property's INITIAL value, which is how a Select once shipped with no chevron (see
+ * `theme/index.ts`'s `ctlSizeVars` doc). This scan is what makes the two halves inseparable.
+ *
+ * Reads the REAL installed package (not a hand-typed list of prefixes) so a future `@mantine/core`
+ * minor that adds a new `getSize`/`getFontSize` call to one of these nine components fails this
+ * test until the matching `-ctl` var is declared — the same "verify against source, not memory"
+ * discipline `ctl-theme.tsx`'s own doc comment describes.
+ *
+ * `getFontSize(size)` is `getSize(size, 'mantine-font-size')` (`core/utils/get-size/get-size.mjs`),
+ * so every `-fz`/`-font-size` call site (Button's `--button-fz`, Input's `--input-fz`,
+ * SegmentedControl's `--sc-font-size`, Combobox's `--combobox-option-fz`) collapses onto the ONE
+ * `mantine-font-size` prefix — verified by proving the prove-it-would-fail step below actually red-
+ * lines when `--mantine-font-size-ctl` is removed, not merely when a component-named font var is
+ * missing (no such var is ever read).
+ *
+ * `*Group`/`*GroupSection` subdirectories (`Button.Group`, `ActionIcon.Group`) are excluded — they
+ * are separate, undocumented-for-`ctl` components (`section-height`/`section-padding-x`/
+ * `section-fz`), out of scope for `docs/CONTROLS-SPEC.md` §5's nine-component list.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { DEFAULT_THEME, mergeMantineTheme } from '@mantine/core'
+import type { MantineTheme } from '@mantine/core'
+import { describe, expect, test } from 'bun:test'
+import { CTL_THEME, baseTheme, cssVariablesResolver } from './index'
+
+const theme: MantineTheme = mergeMantineTheme(DEFAULT_THEME, baseTheme)
+
+const MANTINE_CORE_ESM_COMPONENTS = join(
+  dirname(require.resolve('@mantine/core/package.json')),
+  'esm/components',
+)
+
+/** Every component `CTL_THEME` sets a `ctl` default on, plus `Input`/`Combobox`/`Menu` which the
+ *  others resolve through. Keep this list and `CTL_THEME.components` in step — the last test in this
+ *  file asserts exactly that, so they cannot drift apart silently. */
+const CTL_TIER_COMPONENTS = [
+  'Button',
+  'ActionIcon',
+  'Input',
+  'SegmentedControl',
+  'Combobox',
+  'Select',
+  'MultiSelect',
+  'TextInput',
+  'Menu',
+  'Radio',
+  'Checkbox',
+  'Switch',
+  // In `CTL_THEME` since the tier shipped, and never scanned until the drift test below was added —
+  // which is the whole argument for that test. It renders a native `<select>` through
+  // `Input`/`InputBase`, so it contributes no prefix of its own; being scanned is what proves that
+  // rather than assuming it.
+  'NativeSelect',
+] as const
+
+/** Every `.mjs` file (not `.mjs.map`) under a component directory, recursing into subcomponents but
+ * skipping `*Group`/`*GroupSection` (see this file's doc). */
+function collectMjsFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  const out: string[] = []
+  for (const entry of readdirSync(dir)) {
+    if (/Group/.test(entry)) continue
+    const full = join(dir, entry)
+    const stat = statSync(full)
+    if (stat.isDirectory()) out.push(...collectMjsFiles(full))
+    else if (entry.endsWith('.mjs')) out.push(full)
+  }
+  return out
+}
+
+/** Every distinct `getSize`/`getFontSize` prefix the nine components actually read, extracted from
+ * the installed source — `getFontSize(...)` always collapses to `mantine-font-size` (see this
+ * file's doc). */
+function collectSizePrefixes(): Set<string> {
+  const prefixes = new Set<string>()
+  for (const component of CTL_TIER_COMPONENTS) {
+    for (const file of collectMjsFiles(join(MANTINE_CORE_ESM_COMPONENTS, component))) {
+      const src = readFileSync(file, 'utf8')
+      for (const m of src.matchAll(/get(?:Size|Spacing)\(\s*[\w.?]+\s*,\s*["']([\w-]+)["']/g)) {
+        prefixes.add(m[1]!)
+      }
+      if (/getFontSize\(/.test(src)) prefixes.add('mantine-font-size')
+    }
+  }
+  return prefixes
+}
+
+describe('ctl-tier var coverage', () => {
+  const prefixes = collectSizePrefixes()
+
+  test('the scan finds the prefixes this spec is grounded in (sanity check on the scan itself)', () => {
+    expect(prefixes.has('button-height')).toBe(true)
+    expect(prefixes.has('button-padding-x')).toBe(true)
+    expect(prefixes.has('ai-size')).toBe(true)
+    expect(prefixes.has('input-height')).toBe(true)
+    expect(prefixes.has('sc-padding')).toBe(true)
+    expect(prefixes.has('combobox-option-padding')).toBe(true)
+    expect(prefixes.has('combobox-chevron-size')).toBe(true)
+    expect(prefixes.has('mantine-font-size')).toBe(true)
+  })
+
+  test('the scan reaches Radio/Checkbox/Switch — the three the popovers and the sheet render', () => {
+    expect(prefixes.has('radio-size')).toBe(true)
+    expect(prefixes.has('radio-icon-size')).toBe(true)
+    expect(prefixes.has('checkbox-size')).toBe(true)
+    expect(prefixes.has('switch-height')).toBe(true)
+    expect(prefixes.has('switch-width')).toBe(true)
+    expect(prefixes.has('switch-thumb-size')).toBe(true)
+    expect(prefixes.has('switch-label-font-size')).toBe(true)
+    expect(prefixes.has('switch-track-label-padding')).toBe(true)
+  })
+
+  test('there is NO --checkbox-icon-size to declare — Checkbox derives its tick in CSS', () => {
+    // Worth pinning: the obvious symmetry with `radio-icon-size` does not exist in 9.3.0, and
+    // declaring a var no `getSize` call reads would be dead weight that reads like coverage.
+    expect(prefixes.has('checkbox-icon-size')).toBe(false)
+  })
+
+  test('every scanned prefix has a declared -ctl var', () => {
+    const declared = cssVariablesResolver(theme).variables
+    const missing = [...prefixes].filter((prefix) => !(`--${prefix}-ctl` in declared))
+    expect(missing).toEqual([])
+  })
+
+  test('ActionIcon additionally gets an -icon var (size="icon", WidgetHeader tier="widget")', () => {
+    const declared = cssVariablesResolver(theme).variables
+    expect(declared['--ai-size-icon']).toBeDefined()
+  })
+
+  test('--mantine-line-height-ctl is declared (read by every -ctl Input/Button label via the line-height cascade)', () => {
+    const declared = cssVariablesResolver(theme).variables
+    expect(declared['--mantine-line-height-ctl']).toBeDefined()
+  })
+
+  test('every component CTL_THEME defaults to `ctl` is in the scanned set', () => {
+    // The two halves of the tier — `defaultProps.size = 'ctl'` and the `-ctl` vars — must move
+    // together, and this is what makes adding a component to one without the other fail. `*Group`
+    // keys resolve to their base component's prefixes (a Group reads `Input.Wrapper`'s vars, and the
+    // scan already covers `Input`), so they are stripped before the comparison.
+    const scanned = new Set<string>(CTL_TIER_COMPONENTS)
+    const themed = Object.keys(CTL_THEME.components ?? {}).map((name) =>
+      name.endsWith('Group') ? name.slice(0, -'Group'.length) : name,
+    )
+    expect(themed.filter((name) => !scanned.has(name))).toEqual([])
+  })
+
+  // Proves the gate actually bites — the exact regression the spec calls out
+  // ("--button-padding-x-ctl every draft omitted").
+  test('regression proof: a var missing from cssVariablesResolver would fail the coverage assertion above', () => {
+    const declared = cssVariablesResolver(theme).variables
+    const withoutOne = { ...declared }
+    delete withoutOne['--button-padding-x-ctl']
+    const missing = [...prefixes].filter((prefix) => !(`--${prefix}-ctl` in withoutOne))
+    expect(missing).toEqual(['button-padding-x'])
+  })
+})