basalt-ui 1.27.0 → 1.28.0

package/src/theme/spacing.test.ts

@@ -1,495 +0,0 @@
-/**
- * The spacing gate — the level-0 acceptance baseline for `SPACE`/`SPACE_SCALE`/`SPACE_STEP`/
- * `SPACE_FIXED` (`tokens/palette.ts`).
- *
- * READ THIS BEFORE UPDATING A NUMBER HERE. This file locks the CURRENT shipped identity, not the
- * pre-tokenization one. It was born as the byte-identity gate for a tokenization-only refactor (the
- * token tables replacing the Mantine `spacing` size-scale, ~4 components' hardcoded
- * `styles`/`defaultProps` literals, and the `--vx-space-*` CSS vars), and it is still the ONLY thing
- * standing between a base-table typo and a silent app-wide layout shift. What it can NOT do is tell
- * you whether a diff to it was intended — updating this file is exactly how a deliberate retune
- * lands, and also exactly how a regression would hide. So: a change here must be a visual decision
- * taken on purpose, in the same commit as the base-table edit, with the reason in the commit body.
- * Never "fix the test" to make a red suite green.
- *
- * Deliberate departures from the original pre-tokenization numbers so far:
- *
- * - `SPACE_SCALE` (the app-wide Mantine `xs`..`xl` rhythm) went 10/12/16/18/24 → 11/13/18/20/26, and
- *   13 `sidebar*` gap/inset one-offs tightened ~15% — the component-roominess retune. The two moves
- *   are deliberately opposite: roomier cards and generic layout, a tighter sidebar. `SPACE.rowInsetX`/
- *   `rowInsetY`, the 4px stack rhythm, and the sidebar SIZES (`sidebarAvatarSize`,
- *   `sidebarSearchTriggerHeight`, the two Menu widths) were held back on purpose — see that commit.
- * - `SPACE_STEP.stickyHeaderClearance` moved from 84 (the original literal) through an
- * intermediate single derived value of 108, then a responsive PAIR (Decision 3), to its FINAL shape:
- * ONE value, 60, DERIVED as `appShellHeaderHeight + anchors.stackMd`. Deriving it fixed the original
- * 84's drift from the header it was supposed to clear; the `stickyHeaderClearanceMobile` half of the
- * pair was deleted in 1.26.0 along with the two-row mobile header it existed for — the AppShell
- * header is one 48px row at every viewport now (law C14, `docs/CONTROLS-SPEC.md` §2.1), so
- * `appShellHeaderMobileHeight` and `appHeaderMobileActionsHeight` went with it. See `deriveSpacing`'s
- * doc in `tokens/palette.ts` for the full rationale. Every value NOT named above is still
- * byte-identical to the pre-tokenization number it replaced.
- */
-import { DEFAULT_THEME, mergeMantineTheme } from '@mantine/core'
-import type { MantineTheme } from '@mantine/core'
-import { describe, expect, test } from 'bun:test'
-import { buildPaletteCss, pxRem } from '../tokens'
-import { SPACE, SPACE_FIXED, SPACE_SCALE, SPACE_STEP } from '../tokens/palette'
-import { baseTheme } from './index'
-
-const theme: MantineTheme = mergeMantineTheme(DEFAULT_THEME, baseTheme)
-
-describe('SPACE anchors match the shipped identity', () => {
-  test('rowInsetX is 10, rowInsetY is 6', () => {
-    expect(SPACE.rowInsetX).toBe(10)
-    expect(SPACE.rowInsetY).toBe(6)
-  })
-
-  test('the 4px vertical rhythm is unchanged', () => {
-    expect(SPACE.stackXs).toBe(4)
-    expect(SPACE.stackSm).toBe(8)
-    expect(SPACE.stackMd).toBe(12)
-    expect(SPACE.stackLg).toBe(16)
-    expect(SPACE.stackXl).toBe(24)
-  })
-
-  test('inputHeight and controlHeight are both 42 (the shared control-height anchor)', () => {
-    expect(SPACE.inputHeight).toBe(42)
-    expect(SPACE.controlHeight).toBe(42)
-  })
-
-  test('the controls tier anchors are 20/24/30/36 (docs/CONTROLS-SPEC.md §5)', () => {
-    expect(SPACE.controlHeightTag).toBe(20)
-    expect(SPACE.controlHeightWidget).toBe(24)
-    expect(SPACE.controlHeightCtl).toBe(30)
-    expect(SPACE.touchControlHeight).toBe(36)
-  })
-})
-
-describe('SPACE_SCALE matches the shipped identity — independent of SPACE even where it coincides', () => {
-  test('xs/sm/md/lg/xl are 11/13/18/20/26', () => {
-    expect(SPACE_SCALE.xs).toBe(11)
-    expect(SPACE_SCALE.sm).toBe(13)
-    expect(SPACE_SCALE.md).toBe(18)
-    expect(SPACE_SCALE.lg).toBe(20)
-    expect(SPACE_SCALE.xl).toBe(26)
-  })
-})
-
-describe('SPACE_STEP one-offs match the shipped identity', () => {
-  test('timelineBullet is 22', () => {
-    expect(SPACE_STEP.timelineBullet).toBe(22)
-  })
-})
-
-describe('SPACE_FIXED structurals match the shipped identity', () => {
-  test('hairline is 1', () => {
-    expect(SPACE_FIXED.hairline).toBe(1)
-  })
-
-  test('readingProgressHeight is 2 (not emitted as a var — see the assertion below)', () => {
-    expect(SPACE_FIXED.readingProgressHeight).toBe(2)
-  })
-
-  test('segmentedTrackInset is 2 (not emitted as a var — see the assertion below)', () => {
-    expect(SPACE_FIXED.segmentedTrackInset).toBe(2)
-  })
-})
-
-describe('the Mantine spacing size-scale reaches theme.spacing as the expected rem strings', () => {
-  // The px->rem conversion and the retuned bases, end to end (`pxRem`'s 16px root: 11px = 0.6875rem).
-  // These WERE the pre-tokenization literals until the component-roominess retune — see the file doc.
-  test('xs/sm/md/lg/xl resolve to the exact expected rem strings', () => {
-    expect(baseTheme.spacing).toEqual({
-      xs: '0.6875rem',
-      sm: '0.8125rem',
-      md: '1.125rem',
-      lg: '1.25rem',
-      xl: '1.625rem',
-    })
-  })
-})
-
-describe('every re-pointed component styles/defaultProps spacing value matches its shipped number', () => {
-  test('NavLink root padding = 6px 10px', () => {
-    expect(baseTheme.components?.['NavLink']?.styles?.['root']?.['padding']).toBe(
-      'var(--vx-space-row-inset-y) var(--vx-space-row-inset-x)',
-    )
-  })
-
-  test('Menu item padding = 6px 10px', () => {
-    expect(baseTheme.components?.['Menu']?.styles?.['item']?.['padding']).toBe(
-      'var(--vx-space-row-inset-y) var(--vx-space-row-inset-x)',
-    )
-  })
-
-  test('SegmentedControl root padding = 2 (a density-exempt SPACE_FIXED literal, not a var)', () => {
-    // `styles` is function-form (size='ctl' gates a label override — see `theme/index.ts`), not a
-    // flat object, so it has to be called rather than indexed directly.
-    const stylesFn = baseTheme.components?.['SegmentedControl']?.styles as
-      | ((
-          theme: unknown,
-          props: { size?: string },
-          ctx: unknown,
-        ) => Record<string, Record<string, unknown>>)
-      | undefined
-    const resolved = stylesFn?.({}, {}, {})
-    expect(resolved?.['root']?.['padding']).toBe('2px')
-  })
-
-  test('Timeline defaultProps stays bulletSize: 22, lineWidth: 1', () => {
-    const tl = baseTheme.components?.['Timeline']
-    expect(tl?.defaultProps?.['bulletSize']).toBe(22)
-    expect(tl?.defaultProps?.['lineWidth']).toBe(1)
-  })
-
-  test('Progress defaultProps stays size: 6', () => {
-    expect(baseTheme.components?.['Progress']?.defaultProps?.['size']).toBe(6)
-  })
-
-  test('NavLink root/label lineHeight reads the density-tracking var', () => {
-    const nl = baseTheme.components?.['NavLink']
-    expect(nl?.styles?.['root']?.['lineHeight']).toBe('var(--vx-space-row-line-height)')
-    expect(nl?.styles?.['label']?.['lineHeight']).toBe('var(--vx-space-row-line-height)')
-  })
-
-  test('Input --input-height reconstructs BOTH the rem half and the --mantine-scale half', () => {
-    // Mantine's own `--input-height-md` is `calc(2.625rem * var(--mantine-scale))` — rem-relative
-    // to the root font size AND scale-aware. The override must reconstruct both, not flatten either
-    // into a bare px value (see the `Input.extend` `vars` doc comment for why).
-    const vars = baseTheme.components?.['Input']?.vars
-    // Test-only stub props/ctx — the callback only reads `size`.
-    const mdResult = vars?.(theme, { size: 'md' } as never, {} as never)
-    expect(mdResult?.wrapper?.['--input-height']).toBe(
-      'calc(var(--vx-space-input-height) * var(--mantine-scale))',
-    )
-  })
-
-  test('Input --input-height leaves a non-md size on Mantine own static height', () => {
-    const vars = baseTheme.components?.['Input']?.vars
-    const xsResult = vars?.(theme, { size: 'xs' } as never, {} as never)
-    expect(xsResult?.wrapper?.['--input-height']).toBeUndefined()
-  })
-
-  test('Button --button-height reconstructs BOTH the rem half and the --mantine-scale half', () => {
-    // Same reconstruction as Input above — Mantine's own `--button-height-md` is also
-    // `calc(2.625rem * var(--mantine-scale))`. Single-sourced from the SAME `controlHeight` anchor
-    // `--vx-space-input-height` reads (see `Button.extend`'s doc comment).
-    const vars = baseTheme.components?.['Button']?.vars
-    const mdResult = vars?.(theme, { size: 'md' } as never, {} as never)
-    expect(mdResult?.root?.['--button-height']).toBe(
-      'calc(var(--vx-space-control-height) * var(--mantine-scale))',
-    )
-  })
-
-  test('Button --button-height leaves a non-md size on Mantine own static height', () => {
-    const vars = baseTheme.components?.['Button']?.vars
-    const smResult = vars?.(theme, { size: 'sm' } as never, {} as never)
-    expect(smResult?.root?.['--button-height']).toBeUndefined()
-  })
-
-  test('ActionIcon --ai-size reconstructs BOTH the rem half and the --mantine-scale half', () => {
-    const vars = baseTheme.components?.['ActionIcon']?.vars
-    const mdResult = vars?.(theme, { size: 'md' } as never, {} as never)
-    expect(mdResult?.root?.['--ai-size']).toBe(
-      'calc(var(--vx-space-control-height) * var(--mantine-scale))',
-    )
-  })
-
-  test('ActionIcon --ai-size leaves a non-md size on Mantine own static height', () => {
-    const vars = baseTheme.components?.['ActionIcon']?.vars
-    const smResult = vars?.(theme, { size: 'sm' } as never, {} as never)
-    expect(smResult?.root?.['--ai-size']).toBeUndefined()
-  })
-})
-
-describe('--vx-space-* is emitted from the SAME constants', () => {
-  const css = buildPaletteCss()
-
-  test('emits every SPACE anchor, unchanged', () => {
-    expect(css).toContain('--vx-space-row-inset-x: 10px;')
-    expect(css).toContain('--vx-space-row-inset-y: 6px;')
-    expect(css).toContain('--vx-space-stack-xs: 4px;')
-    expect(css).toContain('--vx-space-stack-sm: 8px;')
-    expect(css).toContain('--vx-space-stack-md: 12px;')
-    expect(css).toContain('--vx-space-stack-lg: 16px;')
-    expect(css).toContain('--vx-space-stack-xl: 24px;')
-  })
-
-  test('does NOT emit SPACE_FIXED as a var', () => {
-    expect(css).not.toContain('--vx-space-hairline')
-    expect(css).not.toContain('--vx-space-reading-progress-height')
-    expect(css).not.toContain('--vx-space-segmented-track-inset')
-  })
-
-  test('does NOT emit the dead numbers-only vars (JS-consumed, zero var() reads)', () => {
-    // `SPACE_SCALE` (the generic Mantine spacing scale) already reaches production through
-    // `theme.spacing` -> `--mantine-spacing-*`, not a `--vx-space-scale-*` var nobody read — and
-    // `timelineBullet`/`chart*`/`progressBarSize` are JS-number-only (`Timeline`'s
-    // `defaultProps.bulletSize`, `VX.legendGap`/`VX.margin`/`VX.dotR`, `Progress`'s
-    // `defaultProps.size`). See `spaceDecls`'s doc in `tokens/index.ts`.
-    expect(css).not.toContain('--vx-space-scale-xs')
-    expect(css).not.toContain('--vx-space-scale-sm')
-    expect(css).not.toContain('--vx-space-scale-md')
-    expect(css).not.toContain('--vx-space-scale-lg')
-    expect(css).not.toContain('--vx-space-scale-xl')
-    expect(css).not.toContain('--vx-space-timeline-bullet')
-    expect(css).not.toContain('--vx-space-chart-legend-gap')
-    expect(css).not.toContain('--vx-space-chart-margin-top')
-    expect(css).not.toContain('--vx-space-chart-margin-right')
-    expect(css).not.toContain('--vx-space-chart-margin-bottom')
-    expect(css).not.toContain('--vx-space-chart-margin-left')
-    expect(css).not.toContain('--vx-space-chart-dot-r')
-    expect(css).not.toContain('--vx-space-progress-bar-size')
-  })
-
-  test('emits the density pass additions: row line-height, input height, control height', () => {
-    expect(css).toContain('--vx-space-row-line-height: 1.35;')
-    // REM, not px — Mantine's own `--input-height-md`/`--button-height-md` are both
-    // `calc(2.625rem * var(--mantine-scale))` (identical in `styles.css` and the `styles.layer.css`
-    // variant consumers load), so flattening this into a flat px value would desync those heights
-    // from the root font size AND `--mantine-scale`. See `tokens/index.ts`'s `spaceDecls` and
-    // `theme/index.ts`'s `Input.extend`/`Button.extend`/`ActionIcon.extend` `vars` for the halves
-    // of the fix.
-    expect(css).toContain('--vx-space-input-height: 2.625rem;')
-    expect(css).not.toContain('--vx-space-input-height: 42px;')
-    expect(css).toContain('--vx-space-control-height: 2.625rem;')
-    expect(css).not.toContain('--vx-space-control-height: 42px;')
-  })
-
-  test('emits the controls-tier heights in REM, and the control gap in px (docs/CONTROLS-SPEC.md §5)', () => {
-    expect(css).toContain('--vx-space-control-height-tag: 1.25rem;')
-    expect(css).toContain('--vx-space-control-height-widget: 1.5rem;')
-    expect(css).toContain('--vx-space-control-height-ctl: 1.875rem;')
-    expect(css).toContain('--vx-space-touch-control-height: 2.25rem;')
-    expect(css).toContain('--vx-space-page-bar-row-height: 2.5rem;')
-    expect(css).toContain('--vx-space-section-header-height: 2.25rem;')
-    expect(css).toContain('--vx-space-widget-header-height: 1.75rem;')
-    expect(css).toContain('--vx-space-sidebar-block-row-height: 2rem;')
-    expect(css).toContain('--vx-space-control-gap: 6px;')
-    expect(css).toContain('--vx-space-sheet-row-height: 2.75rem;')
-  })
-})
-
-/**
- * The CSS-module spacing sweep (`docs/STATUS.md`) — every new `SPACE_STEP` one-off it introduced,
- * locked to its shipped literal AND, for the ones with a real `var()` consumer, to the exact
- * `--vx-space-*` declaration `buildPaletteCss()` emits for it. Table-driven (one row per constant)
- * instead of one `test()` per constant — this table is the single place a future retune of one of
- * these has to touch. `cssVar: null` marks a JS-number-only constant (no `var()` consumer anywhere —
- * `Timeline`'s `defaultProps.bulletSize`, `VX.legendGap`/`VX.margin`/`VX.dotR`, `Progress`'s
- * `defaultProps.size`) that deliberately has NO `--vx-space-*` declaration (see `spaceDecls`'s doc
- * in `tokens/index.ts`).
- */
-const SPACE_STEP_SWEEP: ReadonlyArray<
-  readonly [
-    key: keyof typeof SPACE_STEP,
-    value: number,
-    cssVar: string | null,
-    /** Defaults to `'px'`. The controls-tier row/sheet heights emit REM (`pxRem`), same
-     *  reconstruction as `space-input-height`/`space-control-height` — see `spaceDecls`'s doc in
-     *  `tokens/index.ts`. */
-    unit?: 'px' | 'rem',
-  ]
-> = [
-  // DERIVED, not an independent literal — see `deriveSpacing`'s doc (`tokens/palette.ts`, third
-  // bullet) for why 60 (not 84) is the level-0 value: the ONE key deliberately exempt from the
-  // "every SPACE_STEP number is locked at level 0" invariant this file otherwise enforces (locked
-  // here, not skipped, precisely so a future regression back to 84 shows up as a failing assertion
-  // rather than a silent revert).
-  ['stickyHeaderClearance', 60, 'space-sticky-header-clearance'],
-  ['navIconGap', 10, 'space-nav-icon-gap'],
-  ['sidebarRegionGap', 10, 'space-sidebar-region-gap'],
-  ['proseQuoteInsetY', 2, 'space-prose-quote-inset-y'],
-  ['proseQuoteIndent', 12, 'space-prose-quote-indent'],
-  ['proseInlineCodeInsetY', 1.5, 'space-prose-inline-code-inset-y'],
-  ['proseInlineCodeInsetX', 5, 'space-prose-inline-code-inset-x'],
-  ['proseCodeBlockInsetY', 10, 'space-prose-code-block-inset-y'],
-  ['proseCodeBlockInsetX', 12, 'space-prose-code-block-inset-x'],
-  ['proseHeadingAnchorGap', 6, 'space-prose-heading-anchor-gap'],
-  ['proseTableCellInsetY', 5, 'space-prose-table-cell-inset-y'],
-  ['proseTableCellInsetX', 8, 'space-prose-table-cell-inset-x'],
-  ['proseChatListGapBottom', 10, 'space-prose-chat-list-gap-bottom'],
-  ['proseChatListIndent', 20, 'space-prose-chat-list-indent'],
-  ['proseChatListItemGap', 3, 'space-prose-chat-list-item-gap'],
-  ['proseChatNestedListGap', 2, 'space-prose-chat-nested-list-gap'],
-  ['proseChatHeadingGapTop', 14, 'space-prose-chat-heading-gap-top'],
-  ['proseChatHeadingGapBottom', 6, 'space-prose-chat-heading-gap-bottom'],
-  ['proseArticleParagraphGap', 14, 'space-prose-article-paragraph-gap'],
-  ['proseArticleListGapTop', 6, 'space-prose-article-list-gap-top'],
-  ['proseArticleListGapBottom', 14, 'space-prose-article-list-gap-bottom'],
-  ['proseArticleListIndent', 22, 'space-prose-article-list-indent'],
-  ['proseArticleH1GapTop', 6, 'space-prose-article-h1-gap-top'],
-  ['proseArticleH1GapBottom', 14, 'space-prose-article-h1-gap-bottom'],
-  ['proseArticleHeadingGapTop', 30, 'space-prose-article-heading-gap-top'],
-  ['proseArticleHeadingGapBottom', 10, 'space-prose-article-heading-gap-bottom'],
-  ['proseArticleH2RuleGap', 6, 'space-prose-article-h2-rule-gap'],
-  ['proseArticleBlockGap', 18, 'space-prose-article-block-gap'],
-  ['articleColumnGap', 56, 'space-article-column-gap'],
-  ['articleTocRailWidth', 220, 'space-article-toc-rail-width'],
-  ['articleHeaderGap', 10, 'space-article-header-gap'],
-  ['articleHeaderPaddingBottom', 20, 'space-article-header-padding-bottom'],
-  ['articleHeaderMarginBottom', 28, 'space-article-header-margin-bottom'],
-  ['articleMetaRowGap', 6, 'space-article-meta-row-gap'],
-  ['articleFooterGap', 12, 'space-article-footer-gap'],
-  ['articleFooterMarginTop', 40, 'space-article-footer-margin-top'],
-  ['articleFooterPaddingTop', 20, 'space-article-footer-padding-top'],
-  ['articleNavTargetGap', 6, 'space-article-nav-target-gap'],
-  ['codeBlockHeaderGap', 8, 'space-code-block-header-gap'],
-  ['codeBlockHeaderInsetY', 6, 'space-code-block-header-inset-y'],
-  ['codeBlockHeaderInsetRight', 10, 'space-code-block-header-inset-right'],
-  ['codeBlockContentInsetX', 14, 'space-code-block-content-inset-x'],
-  ['codeBlockHeaderRightGap', 6, 'space-code-block-header-right-gap'],
-  ['codeBlockBodyInsetY', 10, 'space-code-block-body-inset-y'],
-  ['codeBlockFloatingCopyOffset', 6, 'space-code-block-floating-copy-offset'],
-  ['calloutInsetY', 10, 'space-callout-inset-y'],
-  ['calloutInsetX', 14, 'space-callout-inset-x'],
-  ['calloutTitleRowGap', 8, 'space-callout-title-row-gap'],
-  ['tocRootGap', 6, 'space-toc-root-gap'],
-  ['tocLinkInsetY', 4, 'space-toc-link-inset-y'],
-  ['tocLinkIndent', 12, 'space-toc-link-indent'],
-  ['tocSubIndent', 24, 'space-toc-sub-indent'],
-  ['articleCardTagsGap', 4, 'space-article-card-tags-gap'],
-  ['articleCardTagInsetY', 1, 'space-article-card-tag-inset-y'],
-  ['articleCardTagInsetX', 6, 'space-article-card-tag-inset-x'],
-  ['articleCardMetaGapTop', 2, 'space-article-card-meta-gap-top'],
-  ['guideBodyGapBottom', 8, 'space-guide-body-gap-bottom'],
-  ['guideFooterGapTop', 20, 'space-guide-footer-gap-top'],
-  ['guideFooterInsetTop', 16, 'space-guide-footer-inset-top'],
-  ['sidebarSearchGap', 7, 'space-sidebar-search-gap'],
-  ['sidebarSearchTriggerHeight', 32, 'space-sidebar-search-trigger-height'],
-  ['settingsRowInsetY', 10, 'space-settings-row-inset-y'],
-  ['settingsRowGap', 16, 'space-settings-row-gap'],
-  ['mermaidContainerInset', 16, 'space-mermaid-container-inset'],
-  ['sidebarBrandInsetTop', 2, 'space-sidebar-brand-inset-top'],
-  ['sidebarBrandInsetX', 7, 'space-sidebar-brand-inset-x'],
-  ['sidebarSectionGap', 12, 'space-sidebar-section-gap'],
-  ['sidebarAccountInsetTop', 9, 'space-sidebar-account-inset-top'],
-  ['sidebarAccountInsetX', 7, 'space-sidebar-account-inset-x'],
-  ['sidebarAccountInsetBottom', 2, 'space-sidebar-account-inset-bottom'],
-  ['sidebarAvatarSize', 28, 'space-sidebar-avatar-size'],
-  ['sidebarSectionLabelGap', 2, 'space-sidebar-section-label-gap'],
-  ['sidebarChildListGapTop', 2, 'space-sidebar-child-list-gap-top'],
-  ['sidebarChildListGapBottom', 3, 'space-sidebar-child-list-gap-bottom'],
-  ['sidebarChildListIndent', 15, 'space-sidebar-child-list-indent'],
-  ['sidebarChildRowInsetY', 4, 'space-sidebar-child-row-inset-y'],
-  ['sidebarChildRowIndent', 12, 'space-sidebar-child-row-indent'],
-  // JS-number-only (`app-sidebar-account.tsx`/`app-sidebar.tsx` read both via `useBasaltSpacing()` —
-  // Mantine's `<Menu width={…}>` also takes a number, not a `var()` string).
-  ['sidebarAccountMenuWidth', 220, null],
-  ['sidebarSettingsMenuWidth', 200, null],
-  // JS-number-only (`shell/index.tsx` reads all three via `useBasaltSpacing()` — Mantine's AppShell
-  // `header`/`navbar` props take numbers, not `var()` strings) — see `spaceDecls`'s doc in
-  // `tokens/index.ts` for why a `--vx-space-app-shell-*` declaration would have zero consumers.
-  ['appShellHeaderHeight', 48, null],
-  ['appShellNavbarWidth', 256, null],
-  ['appShellNavbarRailWidth', 48, null],
-  ['mobileNavTabGap', 3, 'space-mobile-nav-tab-gap'],
-  // JS-number-only, and for the same two reasons the six above are: `shell/index.tsx` hands
-  // `mobileNavBarHeight` to AppShell's `footer.height` (a number, not a `var()` string), and
-  // `app-mobile-nav.tsx` hands `mobileNavMenuWidth` to `<Menu width={…}>`.
-  ['mobileNavBarHeight', 56, null],
-  ['mobileNavIconSize', 24, 'space-mobile-nav-icon-size'],
-  ['mobileNavTabInsetY', 2, 'space-mobile-nav-tab-inset-y'],
-  ['mobileNavTabInsetX', 12, 'space-mobile-nav-tab-inset-x'],
-  ['mobileNavRowHeight', 44, 'space-mobile-nav-row-height'],
-  ['mobileNavMenuWidth', 232, null],
-  ['agentRailInsetX', 10, 'space-agent-rail-inset-x'],
-  ['agentPartGapTop', 6, 'space-agent-part-gap-top'],
-  ['agentCodeInset', 8, 'space-agent-code-inset'],
-  ['agentErrorInsetY', 8, 'space-agent-error-inset-y'],
-  ['agentErrorInsetX', 10, 'space-agent-error-inset-x'],
-  ['agentScrollButtonGapTop', 8, 'space-agent-scroll-button-gap-top'],
-  ['agentMessageInsetY', 10, 'space-agent-message-inset-y'],
-  ['agentMessageInsetX', 12, 'space-agent-message-inset-x'],
-  ['agentTranscriptInset', 16, 'space-agent-transcript-inset'],
-  ['badgeInsetY', 2, 'space-badge-inset-y'],
-  ['badgeInsetX', 7, 'space-badge-inset-x'],
-  ['statCardGap', 8, 'space-stat-card-gap'],
-  ['virtualRowInsetY', 8, 'space-virtual-row-inset-y'],
-  ['virtualRowInsetX', 12, 'space-virtual-row-inset-x'],
-  ['chartLegendGap', 22, null],
-  ['chartMarginTop', 12, null],
-  ['chartMarginRight', 16, null],
-  ['chartMarginRightAxis', 40, null],
-  ['chartMarginBottom', 30, null],
-  ['chartMarginLeft', 44, null],
-  ['chartDotR', 5, null],
-  ['progressBarSize', 6, null],
-  ['timelineBullet', 22, null],
-  // Controls tier row/gap heights (`docs/CONTROLS-SPEC.md` §5) — emitted in REM for the heights
-  // (`pageBarRowHeight`/`sectionHeaderHeight`/`widgetHeaderHeight`/`sidebarBlockRowHeight`/
-  // `sheetRowHeight`, same `pxRem` reconstruction as `space-input-height`), px for the gap.
-  ['pageBarRowHeight', 40, 'space-page-bar-row-height', 'rem'],
-  ['sectionHeaderHeight', 36, 'space-section-header-height', 'rem'],
-  ['widgetHeaderHeight', 28, 'space-widget-header-height', 'rem'],
-  ['sidebarBlockRowHeight', 32, 'space-sidebar-block-row-height', 'rem'],
-  ['controlGap', 6, 'space-control-gap'],
-  ['sheetRowHeight', 44, 'space-sheet-row-height', 'rem'],
-  // Applied as JS numbers in `Table.extend`'s `styles.th`/`styles.td` `height`, so — like
-  // `progressBarSize` — neither has a `--vx-space-*` declaration to assert.
-  ['tableHeaderHeight', 36, null],
-  ['tableRowHeight', 40, null],
-]
-
-describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identity', () => {
-  test('every constant matches its shipped literal', () => {
-    for (const [key, value] of SPACE_STEP_SWEEP) {
-      expect(SPACE_STEP[key]).toBe(value)
-    }
-  })
-
-  test('every constant with a cssVar is emitted as its own --vx-space-* declaration, unchanged', () => {
-    const css = buildPaletteCss()
-    for (const [, value, cssVar, unit = 'px'] of SPACE_STEP_SWEEP) {
-      if (cssVar === null) continue
-      const expected = unit === 'rem' ? pxRem(value) : `${value}px`
-      expect(css).toContain(`--vx-${cssVar}: ${expected};`)
-    }
-  })
-
-  test('every cssVar: null constant is NOT emitted as a --vx-space-* declaration', () => {
-    const css = buildPaletteCss()
-    const jsOnlyKeys = SPACE_STEP_SWEEP.filter(([, , cssVar]) => cssVar === null).map(
-      ([key]) => key,
-    )
-    expect(jsOnlyKeys).toEqual([
-      'sidebarAccountMenuWidth',
-      'sidebarSettingsMenuWidth',
-      'appShellHeaderHeight',
-      'appShellNavbarWidth',
-      'appShellNavbarRailWidth',
-      'mobileNavBarHeight',
-      'mobileNavMenuWidth',
-      'chartLegendGap',
-      'chartMarginTop',
-      'chartMarginRight',
-      'chartMarginRightAxis',
-      'chartMarginBottom',
-      'chartMarginLeft',
-      'chartDotR',
-      'progressBarSize',
-      'timelineBullet',
-      'tableHeaderHeight',
-      'tableRowHeight',
-    ])
-    expect(css).not.toContain('--vx-space-sidebar-account-menu-width')
-    expect(css).not.toContain('--vx-space-sidebar-settings-menu-width')
-    expect(css).not.toContain('--vx-space-app-shell-header-height')
-    expect(css).not.toContain('--vx-space-app-shell-navbar-width')
-    expect(css).not.toContain('--vx-space-app-shell-navbar-rail-width')
-    expect(css).not.toContain('--vx-space-mobile-nav-bar-height')
-    expect(css).not.toContain('--vx-space-mobile-nav-menu-width')
-    expect(css).not.toContain('--vx-space-chart-legend-gap')
-    expect(css).not.toContain('--vx-space-progress-bar-size')
-    expect(css).not.toContain('--vx-space-timeline-bullet')
-    expect(css).not.toContain('--vx-space-table-header-height')
-    expect(css).not.toContain('--vx-space-table-row-height')
-  })
-
-  test('the sweep table covers every SPACE_STEP key', () => {
-    const tableKeys = new Set(SPACE_STEP_SWEEP.map(([key]) => key))
-    for (const key of Object.keys(SPACE_STEP)) {
-      expect(tableKeys.has(key as keyof typeof SPACE_STEP)).toBe(true)
-    }
-  })
-})

package/src/theme/use-basalt-spacing.test.tsx

@@ -1,55 +0,0 @@
-/**
- * `useBasaltSpacing` — the only path by which a non-default density level reaches `BasaltShell`'s
- * AppShell header/navbar/rail dimensions and `AppSidebar`/`SidebarAccount`'s `<Menu width>` (see the
- * hook's own doc). Nothing previously asserted it actually reads `theme.other.basaltDensity` off the
- * running Mantine theme — that wiring could silently break (e.g. a typo'd key, or a dropped fallback)
- * with every other density test still green, since those all exercise `deriveSpacing`/
- * `createBasaltTheme` directly, never this hook.
- *
- * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
- * `tokens/build-fonts-css.test.ts`'s doc for that same note elsewhere) — this suite still uses
- * `react-dom/server`'s `renderToStaticMarkup` deliberately: it's enough to invoke a hook inside a
- * REAL `MantineProvider` tree without a DOM, so these assertions exercise the actual
- * `useMantineTheme()` read, not a re-implementation of it. Converting to the DOM harness would only
- * be worth it if a future assertion here needed the hook to react to a live DOM event (e.g. a
- * `ResizeObserver`-driven remeasure) rather than a single render-time read.
- */
-import { MantineProvider } from '@mantine/core'
-import type { MantineProviderProps } from '@mantine/core'
-import { describe, expect, test } from 'bun:test'
-import { renderToStaticMarkup } from 'react-dom/server'
-import { DEFAULT_SPACE_VALUES, deriveSpacing } from '../tokens/palette'
-import { useBasaltSpacing } from './use-basalt-spacing'
-
-function readBasaltSpacing(theme?: MantineProviderProps['theme']) {
-  let captured: ReturnType<typeof useBasaltSpacing> | undefined
-  function Probe() {
-    captured = useBasaltSpacing()
-    return null
-  }
-  renderToStaticMarkup(
-    // exactOptionalPropertyTypes forbids an explicit theme={undefined} — spread only when set
-    <MantineProvider {...(theme !== undefined ? { theme } : {})}>
-      <Probe />
-    </MantineProvider>,
-  )
-  return captured
-}
-
-describe('useBasaltSpacing', () => {
-  test('falls back to DEFAULT_SPACE_VALUES when theme.other.basaltDensity is unset', () => {
-    // Fails if the hook drops its `?? DEFAULT_SPACE_VALUES` fallback (e.g. returns `undefined` at
-    // the shipped default density instead).
-    expect(readBasaltSpacing()).toEqual(DEFAULT_SPACE_VALUES)
-  })
-
-  test('reads the resolved values off theme.other.basaltDensity when present', () => {
-    const retuned = deriveSpacing(-2)
-    // Fails if the hook stops reading `theme.other.basaltDensity` (e.g. always returns
-    // `DEFAULT_SPACE_VALUES` regardless of the running theme).
-    expect(readBasaltSpacing({ other: { basaltDensity: retuned } })).toEqual(retuned)
-    expect(readBasaltSpacing({ other: { basaltDensity: retuned } })).not.toEqual(
-      DEFAULT_SPACE_VALUES,
-    )
-  })
-})

package/src/theme-lab/derive-controls.test.ts

@@ -1,94 +0,0 @@
-/**
- * `DeriveControls`'s persisted-state migrations. v2→v3 bumped `STORAGE_VERSION` to `3` when
- * `density` was added alongside `radius` + the six color knobs; v3→v4 bumped it again when
- * `deriveSpacing`'s accepted range narrowed from `[-5, 5]` to `[-3, 3]` (see `derive-controls.tsx`'s
- * module doc comment for both). No `migrate` is passed to `createPersistedState`, so a version
- * mismatch falls through to `opts.initial` (`../state`'s `parseStorage`) rather than carrying
- * `parsed.value` forward — `parsePersistedDeriveState` is the schema validator that rejection
- * ultimately routes through.
- *
- * Tested at the validator seam directly (not through `createPersistedState`'s localStorage
- * round-trip): no DOM render harness is configured in this package (see
- * `../provider/build-fonts-css.test.ts`), and this repo's test environment has no `localStorage`
- * either (see `../router-tanstack/multi-search-param-store.test.ts`).
- */
-import { describe, expect, test } from 'bun:test'
-import { DEFAULT_DERIVE_CONFIG } from '../tokens/derive'
-import { DEFAULT_STATE, parsePersistedDeriveState } from './derive-controls'
-
-/** A v1-shaped persisted value — the six color knobs + `applied`, no `radius`/`density` key at all. */
-const V1_SHAPED_VALUE = {
-  accent: DEFAULT_DERIVE_CONFIG.accent,
-  neutral: DEFAULT_DERIVE_CONFIG.neutral,
-  lightLevel: DEFAULT_DERIVE_CONFIG.lightLevel,
-  darkLevel: DEFAULT_DERIVE_CONFIG.darkLevel,
-  vibrancy: DEFAULT_DERIVE_CONFIG.vibrancy,
-  accentBrightness: DEFAULT_DERIVE_CONFIG.accentBrightness,
-  applied: false,
-}
-
-/** A v2-shaped persisted value — the six color knobs + `radius` + `applied`, no `density` key. */
-const V2_SHAPED_VALUE = { ...V1_SHAPED_VALUE, radius: 0 }
-
-describe('a v1-shaped persisted value (no radius/density key) is rejected', () => {
-  test('parsePersistedDeriveState returns null, not a value with radius/density: undefined', () => {
-    const parsed = parsePersistedDeriveState(V1_SHAPED_VALUE)
-    expect(parsed).toBeNull()
-  })
-})
-
-describe('a v2-shaped persisted value (radius present, no density key) is rejected', () => {
-  test('parsePersistedDeriveState returns null, not a value with density: undefined', () => {
-    const parsed = parsePersistedDeriveState(V2_SHAPED_VALUE)
-    expect(parsed).toBeNull()
-  })
-
-  test('DEFAULT_STATE (what a rejection falls back to via parseStorage) has a real density', () => {
-    // No `migrate` is passed to `createPersistedState`, so a version mismatch (v1/v2 vs the current
-    // v3) sets the pre-validation value to `opts.initial` — DEFAULT_STATE — which this validator
-    // must then accept, landing a real `radius: 0` / `density: 0`, never `undefined`.
-    expect(parsePersistedDeriveState(DEFAULT_STATE)).toEqual(DEFAULT_STATE)
-    expect(DEFAULT_STATE.radius).toBe(0)
-    expect(DEFAULT_STATE.density).toBe(0)
-  })
-})
-
-describe('a v3-shaped persisted value (radius + density present) round-trips', () => {
-  test('parsePersistedDeriveState accepts it and preserves both levels', () => {
-    const v3Value = { ...V2_SHAPED_VALUE, radius: 3, density: -2 }
-    expect(parsePersistedDeriveState(v3Value)).toEqual(v3Value)
-  })
-
-  test('an out-of-range density level is rejected', () => {
-    const badValue = { ...V2_SHAPED_VALUE, density: 99 }
-    expect(parsePersistedDeriveState(badValue)).toBeNull()
-  })
-
-  test('a non-integer density level is rejected', () => {
-    const badValue = { ...V2_SHAPED_VALUE, density: 1.5 }
-    expect(parsePersistedDeriveState(badValue)).toBeNull()
-  })
-})
-
-describe('a pre-v4 envelope holding a density outside the narrowed [-3, 3] range is rejected', () => {
-  // The exact live-crash path the v3->v4 bump exists to prevent: a v3 envelope from an earlier
-  // session could hold `density: 4` or `density: -5`, both valid under the OLD `isLevel` (-5..5)
-  // check that guarded `density` pre-v4. Falling through to `DEFAULT_STATE` here, instead of
-  // reaching `deriveSpacing` at render, is what the version bump buys.
-  test('density: 4 (in-range for radius, out of range for density) is rejected', () => {
-    const badValue = { ...V2_SHAPED_VALUE, density: 4 }
-    expect(parsePersistedDeriveState(badValue)).toBeNull()
-  })
-
-  test('density: -5 (the old lower bound) is rejected', () => {
-    const badValue = { ...V2_SHAPED_VALUE, density: -5 }
-    expect(parsePersistedDeriveState(badValue)).toBeNull()
-  })
-
-  test('radius: -5/5 stays accepted — only density narrowed', () => {
-    const lowRadius = { ...V2_SHAPED_VALUE, radius: -5, density: -3 }
-    const highRadius = { ...V2_SHAPED_VALUE, radius: 5, density: 3 }
-    expect(parsePersistedDeriveState(lowRadius)).toEqual(lowRadius)
-    expect(parsePersistedDeriveState(highRadius)).toEqual(highRadius)
-  })
-})