basalt-ui 1.26.0 → 1.28.0

package/src/shell/page-bar.test.tsx

@@ -1,316 +0,0 @@
-/**
- * `PageBar`'s two invariants that only a rendered tree can prove (`docs/CONTROLS-SPEC.md` §2.1):
- * row 1 leaves the page and lands in the app-shell header, row 2 does NOT — it stays in the page
- * flow, sticks under the header, and publishes its measured height. Both are decided by context
- * (is there a `BasaltShell` above me?), so a unit test of the component alone can't see either.
- *
- * The `--basalt-page-bar-h` publish is the one piece needing a real ResizeObserver callback. The
- * harness shim (`tests/setup/dom.ts`) is a deliberate no-op, so this file installs a controllable
- * fake for the duration of the suite and fires the callback by hand against a stubbed rect —
- * happy-dom evaluates no layout, so a genuine observer would only ever report 0 (which the
- * `height > 0` guard correctly refuses to publish).
- */
-import { MantineProvider } from '@mantine/core'
-import { render, screen } from '@testing-library/react'
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { useEffect } from 'react'
-import type { ReactNode } from 'react'
-import { BasaltShell, PageBar } from './index'
-import type { SidebarSection } from './index'
-
-const BRAND = { name: 'Argo' }
-const ONE_SECTION: SidebarSection[] = [
-  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
-]
-
-const HEIGHT_VAR = '--basalt-page-bar-h'
-
-type Observed = { node: Element; trigger: () => void }
-
-let observed: Observed[] = []
-let nativeResizeObserver: typeof ResizeObserver
-
-/** A ResizeObserver whose callback the test fires — see this file's doc for why the shim can't. */
-function installFakeResizeObserver(): void {
-  observed = []
-  class FakeResizeObserver {
-    constructor(private readonly callback: ResizeObserverCallback) {}
-    observe(node: Element): void {
-      observed.push({
-        node,
-        trigger: () => this.callback([], this as unknown as ResizeObserver),
-      })
-    }
-    unobserve(): void {}
-    disconnect(): void {}
-  }
-  window.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver
-}
-
-/** Every element measures `height` — the layout happy-dom never evaluates, for the whole tree. */
-function stubEveryRect(height: number): void {
-  Element.prototype.getBoundingClientRect = function rect() {
-    return { height, width: 0, top: 0, left: 0, right: 0, bottom: height, x: 0, y: 0 } as DOMRect
-  }
-}
-
-function stubHeight(node: HTMLElement, height: number): void {
-  Object.defineProperty(node, 'getBoundingClientRect', {
-    configurable: true,
-    value: () => ({ height, width: 0, top: 0, left: 0, right: 0, bottom: height, x: 0, y: 0 }),
-  })
-}
-
-beforeEach(() => {
-  nativeResizeObserver = window.ResizeObserver
-  installFakeResizeObserver()
-})
-
-afterEach(() => {
-  window.ResizeObserver = nativeResizeObserver
-  document.documentElement.style.removeProperty(HEIGHT_VAR)
-})
-
-const shellRow = () => document.querySelector<HTMLElement>('[data-basalt-page-bar="shell"]')
-
-describe('PageBar inside a BasaltShell', () => {
-  const renderInShell = () =>
-    render(
-      <MantineProvider>
-        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
-          <PageBar
-            actions={{
-              primary: { key: 'row1', kind: 'custom', node: <span data-testid="row1" /> },
-            }}
-            tabs={<span data-testid="row2" />}
-          />
-        </BasaltShell>
-      </MantineProvider>,
-    )
-
-  test('row 1 portals into the app-shell header — every copy of it', () => {
-    renderInShell()
-    const header = document.querySelector('.mantine-AppShell-header')
-    expect(header).not.toBeNull()
-    const copies = screen.getAllByTestId('row1')
-    expect(copies.length).toBeGreaterThan(0)
-    for (const copy of copies) expect(header?.contains(copy)).toBe(true)
-  })
-
-  test('row 2 stays in the page flow — NOT in the header', () => {
-    renderInShell()
-    const header = document.querySelector('.mantine-AppShell-header')
-    const row2 = screen.getByTestId('row2')
-    expect(header?.contains(row2)).toBe(false)
-    expect(shellRow()?.contains(row2)).toBe(true)
-  })
-
-  test('a ResizeObserver reading publishes --basalt-page-bar-h on documentElement', () => {
-    renderInShell()
-    const row = shellRow()
-    expect(row).not.toBeNull()
-    stubHeight(row as HTMLElement, 44)
-    const entry = observed.find((o) => o.node === row)
-    expect(entry).toBeDefined()
-    entry?.trigger()
-    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('44px')
-  })
-
-  test('a zero reading is refused — the guard is what kept a consumer sticky offset from collapsing', () => {
-    renderInShell()
-    const row = shellRow()
-    stubHeight(row as HTMLElement, 0)
-    observed.find((o) => o.node === row)?.trigger()
-    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
-  })
-
-  test('unmounting removes the property, so the next route does not inherit this height', () => {
-    const { unmount } = renderInShell()
-    const row = shellRow()
-    stubHeight(row as HTMLElement, 44)
-    observed.find((o) => o.node === row)?.trigger()
-    unmount()
-    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
-  })
-
-  test('title is ignored inside a shell — the breadcrumb names the page (law C8)', () => {
-    render(
-      <MantineProvider>
-        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
-          <PageBar title="Ignored" tabs={<span data-testid="row2" />} />
-        </BasaltShell>
-      </MantineProvider>,
-    )
-    expect(screen.queryByText('Ignored')).toBeNull()
-  })
-})
-
-/**
- * A consumer's own test DOM has no `ResizeObserver` unless it installs a shim — happy-dom and jsdom
- * both lack it. An unguarded `new ResizeObserver` in the effect turned that into a hard throw from
- * every page test that mounted a bar, which is a framework bug, not a consumer one.
- */
-describe('PageBar with no ResizeObserver at all', () => {
-  test('a shell-less bar still mounts, and publishes nothing rather than throwing', () => {
-    // @ts-expect-error deliberately removing a DOM global the guard exists to survive
-    window.ResizeObserver = undefined
-    expect(() =>
-      render(
-        <MantineProvider>
-          <PageBar title="linewatch" tabs={<span data-testid="row2" />} />
-        </MantineProvider>,
-      ),
-    ).not.toThrow()
-    expect(screen.getByRole('heading', { level: 1 }).textContent).toBe('linewatch')
-    // happy-dom evaluates no layout, so the one-shot measure reads 0 and the guard refuses it.
-    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
-  })
-
-  test('a filters row mounts too, and unmounting still cleans up', () => {
-    // Only the SHELL-LESS form is exercised: `BasaltShell` mounts a Mantine `AppShell` whose own
-    // internals construct a `ResizeObserver`, so that half can never run without one — which is
-    // also why the guard matters for the shell-less consumer (linewatch) specifically.
-    // @ts-expect-error see above
-    window.ResizeObserver = undefined
-    const { unmount } = render(
-      <MantineProvider>
-        <PageBar title="linewatch" filters={<span data-testid="filters" />} />
-      </MantineProvider>,
-    )
-    expect(screen.getByTestId('filters')).toBeDefined()
-    expect(() => unmount()).not.toThrow()
-    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
-  })
-})
-
-describe('PageBar without a shell', () => {
-  test('renders the title as the page heading and sticks both rows at the top', () => {
-    render(
-      <MantineProvider>
-        <PageBar title="linewatch" tabs={<span data-testid="row2" />} />
-      </MantineProvider>,
-    )
-    const heading = screen.getByRole('heading', { level: 1 })
-    expect(heading.textContent).toBe('linewatch')
-    const bar = document.querySelector<HTMLElement>('[data-basalt-page-bar="standalone"]')
-    expect(bar).not.toBeNull()
-    expect(bar?.contains(heading)).toBe(true)
-    expect(bar?.contains(screen.getByTestId('row2'))).toBe(true)
-  })
-
-  test('renders nothing at all when every slot is empty (law C14)', () => {
-    render(
-      <MantineProvider>
-        <PageBar />
-      </MantineProvider>,
-    )
-    expect(document.querySelector('[data-basalt-page-bar]')).toBeNull()
-  })
-})
-
-/**
- * The sticky offsets and law C7's no-horizontal-scroll rule live entirely in CSS, and a CSS module
- * resolves to `''` under `bun test` (no bundler in the loop) — so they are asserted against the
- * shipped CSS TEXT, the same pattern `prose.module.css.test.ts` and `styles.floor.test.ts` use.
- */
-describe('page-bar.module.css', () => {
-  const css = readFileSync(
-    resolve(dirname(fileURLToPath(import.meta.url)), 'page-bar.module.css'),
-    'utf8',
-  )
-  /** Declarations only — the block comments above them discuss `::before` and `overflow` by name. */
-  const decls = css.replace(/\/\*[\s\S]*?\*\//g, '')
-
-  test('row 2 inside a shell sticks at the AppShell header-height VAR, never a measured number', () => {
-    const rule = decls.match(/\.row2Sticky\s*\{([^}]+)\}/)
-    expect(rule).not.toBeNull()
-    expect(rule?.[1]).toContain('position: sticky')
-    expect(rule?.[1]).toContain('top: var(--app-shell-header-height, 0px)')
-  })
-
-  test('the shell-less bar sticks at the top of the document', () => {
-    const rule = decls.match(/\.bar\s*\{([^}]+)\}/)
-    expect(rule?.[1]).toContain('position: sticky')
-    expect(rule?.[1]).toContain('top: 0')
-  })
-
-  test('no row ever scrolls sideways or wraps (law C7)', () => {
-    expect(decls).not.toContain('overflow-x')
-    expect(decls).not.toMatch(/overflow(-y)?:\s*(auto|scroll)/)
-    expect(decls.match(/flex-wrap: nowrap/g)?.length).toBeGreaterThanOrEqual(5)
-  })
-
-  test('the mobile hit area rides ::after — Mantine owns Button::before for its loading overlay', () => {
-    expect(decls).toContain('::after')
-    expect(decls).not.toContain('::before')
-    expect(decls).toContain('min-height: var(--vx-space-touch-control-height)')
-  })
-
-  test('the hit area un-clips its own host — Mantine roots are overflow: hidden', () => {
-    // Without this the overlay is clipped back to the 30px box and law C15's 36px target does not
-    // exist at all, which no token assertion can catch.
-    expect(decls).toMatch(/:not\(\[data-loading\]\)[\s\S]{0,80}overflow: visible/)
-  })
-})
-
-/**
- * The height has to exist at the FIRST paint, not one frame later: `Section`'s scroll anchor reads
- * `var(--basalt-page-bar-h, 0px)`, so a cold load of `/page#anchor` that scrolls before the property
- * lands leaves the anchored heading under the sticky bar.
- *
- * The probe is what makes the timing observable. Passive effects run child-first, so a probe INSIDE
- * the bar reads the property before the bar's own passive effect would have written it — it can only
- * see `44px` if the publish happened in the layout phase.
- */
-describe('the height var is published before first paint', () => {
-  const nativeRect = Element.prototype.getBoundingClientRect
-
-  afterEach(() => {
-    Element.prototype.getBoundingClientRect = nativeRect
-  })
-
-  test('a passive effect inside the bar already sees --basalt-page-bar-h', () => {
-    const seen: { current: string | null } = { current: null }
-    function Probe(): ReactNode {
-      useEffect(() => {
-        seen.current = document.documentElement.style.getPropertyValue(HEIGHT_VAR)
-      }, [])
-      return <span data-testid="row2" />
-    }
-
-    stubEveryRect(44)
-    render(
-      <MantineProvider>
-        <PageBar title="linewatch" tabs={<Probe />} />
-      </MantineProvider>,
-    )
-
-    expect(seen.current).toBe('44px')
-  })
-})
-
-describe('className reaches the bar root in both forms', () => {
-  test('shell-less: it joins the standalone root, keeping the module class', () => {
-    render(
-      <MantineProvider>
-        <PageBar title="linewatch" tabs={<span data-testid="row2" />} className="lw-bleed" />
-      </MantineProvider>,
-    )
-    const bar = document.querySelector<HTMLElement>('[data-basalt-page-bar="standalone"]')
-    expect(bar?.classList.contains('lw-bleed')).toBe(true)
-  })
-
-  test('in a shell: it joins row 2s sticky wrapper, not the portalled row 1', () => {
-    render(
-      <MantineProvider>
-        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
-          <PageBar tabs={<span data-testid="row2" />} className="argo-bleed" />
-        </BasaltShell>
-      </MantineProvider>,
-    )
-    expect(shellRow()?.classList.contains('argo-bleed')).toBe(true)
-  })
-})

package/src/state/fields.test.tsx

@@ -1,258 +0,0 @@
-/**
- * `createLocalStore` — the router-free lane of the store family.
- *
- * Rendered with NO `RouterProvider` on purpose: the local lane must not touch
- * `@tanstack/react-router`, because that is the whole difference between it and `createSearchStore`
- * (argo's five in-chart `useState` selects, linewatch's compact toggle). A router hook would throw
- * here, so these tests are the proof, not a claim.
- */
-import { beforeEach, describe, expect, test } from 'bun:test'
-import { act, renderHook } from '@testing-library/react'
-import { createLocalStore, field } from './fields'
-
-function storedRecord(key: string): Record<string, unknown> | null {
-  const raw = localStorage.getItem(`basalt:${key}`)
-  if (raw === null) return null
-  return (JSON.parse(raw) as { value: Record<string, unknown> }).value
-}
-
-function persist(key: string, record: Record<string, unknown>): void {
-  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: 1, value: record }))
-}
-
-beforeEach(() => {
-  localStorage.clear()
-})
-
-describe('createLocalStore', () => {
-  test('use() reads the mirror, falls back, and writes with no router in sight', () => {
-    const store = createLocalStore({
-      key: 'l-metric',
-      fields: { metric: field.enum(['load', 'volume'], 'load') },
-    })
-
-    const { result } = renderHook(() => store.field.metric.use())
-    expect(result.current[0]).toBe('load')
-
-    act(() => {
-      result.current[1]('volume')
-    })
-    expect(result.current[0]).toBe('volume')
-    expect(storedRecord('l-metric')).toEqual({ metric: 'volume' })
-  })
-
-  test('a pre-existing mirror is read on first render', () => {
-    const store = createLocalStore({
-      key: 'l-restore',
-      fields: { view: field.enum(['chart', 'table'], 'chart') },
-    })
-    persist('l-restore', { view: 'table' })
-
-    const { result } = renderHook(() => store.field.view.use())
-    expect(result.current[0]).toBe('table')
-  })
-
-  test('an invalid mirror entry decodes to the fallback rather than through it', () => {
-    const store = createLocalStore({
-      key: 'l-invalid',
-      fields: { view: field.enum(['chart', 'table'], 'chart') },
-    })
-    persist('l-invalid', { view: 'spreadsheet' })
-
-    const { result } = renderHook(() => store.field.view.use())
-    expect(result.current[0]).toBe('chart')
-  })
-
-  test('every field kind round-trips through the mirror', () => {
-    const store = createLocalStore({
-      key: 'l-kinds',
-      fields: {
-        tags: field.multi(['api', 'design', 'guide']),
-        range: field.range({ presets: ['7d', '30d'], fallback: '30d', custom: true }),
-        rows: field.number({ fallback: 10, min: 1, max: 50, int: true }),
-        compact: field.boolean(false),
-        q: field.string(),
-      },
-    })
-
-    const tags = renderHook(() => store.field.tags.use())
-    act(() => {
-      tags.result.current[1](['guide', 'api'])
-    })
-    // Canonical order is enforced on the way back out, not on the way in.
-    expect(store.readStored()['tags']).toEqual(['api', 'guide'])
-
-    const range = renderHook(() => store.field.range.use())
-    act(() => {
-      range.result.current[1]({ preset: 'custom', from: '2026-01-01', to: '2026-02-01' })
-    })
-    expect(range.result.current[0]).toEqual({
-      preset: 'custom',
-      from: '2026-01-01',
-      to: '2026-02-01',
-    })
-
-    const rows = renderHook(() => store.field.rows.use())
-    act(() => {
-      rows.result.current[1](25)
-    })
-    expect(rows.result.current[0]).toBe(25)
-
-    const compact = renderHook(() => store.field.compact.use())
-    act(() => {
-      compact.result.current[1](true)
-    })
-    expect(compact.result.current[0]).toBe(true)
-
-    const q = renderHook(() => store.field.q.use())
-    act(() => {
-      q.result.current[1]('sled')
-    })
-    expect(q.result.current[0]).toBe('sled')
-
-    // One localStorage entry per store, holding every field.
-    expect(storedRecord('l-kinds')).toEqual({
-      tags: ['guide', 'api'],
-      range: { preset: 'custom', from: '2026-01-01', to: '2026-02-01' },
-      rows: 25,
-      compact: true,
-      q: 'sled',
-    })
-  })
-
-  test('two fields written in the same tick do not clobber each other', () => {
-    const store = createLocalStore({
-      key: 'l-concurrent',
-      fields: {
-        view: field.enum(['chart', 'table'], 'chart'),
-        compact: field.boolean(false),
-      },
-    })
-
-    const view = renderHook(() => store.field.view.use())
-    const compact = renderHook(() => store.field.compact.use())
-
-    act(() => {
-      view.result.current[1]('table')
-      compact.result.current[1](true)
-    })
-
-    expect(storedRecord('l-concurrent')).toEqual({ view: 'table', compact: true })
-  })
-
-  test('readStored is flat and omits a field that has never been written', () => {
-    const store = createLocalStore({
-      key: 'l-read',
-      fields: {
-        view: field.enum(['chart', 'table'], 'chart'),
-        compact: field.boolean(false),
-      },
-    })
-    persist('l-read', { view: 'table' })
-
-    expect(store.readStored()).toEqual({ view: 'table' })
-  })
-
-  test('handles carry the same contract a search store hands a control', () => {
-    const store = createLocalStore({
-      key: 'l-handle',
-      fields: { view: field.enum(['chart', 'table'], 'chart') },
-    }).field.view
-
-    expect(store.kind).toBe('enum')
-    expect(store.fallback).toBe('chart')
-    expect(store.isDefault('chart')).toBe(true)
-    expect(store.options).toEqual([
-      { value: 'chart', label: 'chart' },
-      { value: 'table', label: 'table' },
-    ])
-  })
-})
-
-/**
- * `persist: false` in a local store has no URL to fall back on, so it is the IN-MEMORY lane rather
- * than a field frozen on its fallback: shared across mounts for the session, gone on reload.
- */
-describe('createLocalStore — the in-memory lane', () => {
-  test('a persist: false field survives a remount and never touches localStorage', () => {
-    const store = createLocalStore({
-      key: 'l-memory',
-      fields: { zoomed: field.boolean(false, { persist: false }) },
-    })
-
-    const first = renderHook(() => store.field.zoomed.use())
-    expect(first.result.current[0]).toBe(false)
-    act(() => {
-      first.result.current[1](true)
-    })
-    expect(first.result.current[0]).toBe(true)
-    first.unmount()
-
-    const second = renderHook(() => store.field.zoomed.use())
-    expect(second.result.current[0]).toBe(true)
-    expect(localStorage.getItem('basalt:l-memory')).toBeNull()
-    expect(localStorage.length).toBe(0)
-  })
-
-  test('two live mounts of the same field see one value', () => {
-    const store = createLocalStore({
-      key: 'l-memory-shared',
-      fields: { metric: field.enum(['load', 'volume'], 'load', { persist: false }) },
-    })
-
-    const a = renderHook(() => store.field.metric.use())
-    const b = renderHook(() => store.field.metric.use())
-
-    act(() => {
-      a.result.current[1]('volume')
-    })
-
-    expect(b.result.current[0]).toBe('volume')
-  })
-
-  test('a mirrored field beside it still persists — the lane is per field', () => {
-    const store = createLocalStore({
-      key: 'l-memory-mixed',
-      fields: {
-        view: field.enum(['chart', 'table'], 'chart'),
-        zoomed: field.boolean(false, { persist: false }),
-      },
-    })
-
-    const view = renderHook(() => store.field.view.use())
-    const zoomed = renderHook(() => store.field.zoomed.use())
-    act(() => {
-      view.result.current[1]('table')
-      zoomed.result.current[1](true)
-    })
-
-    expect(storedRecord('l-memory-mixed')).toEqual({ view: 'table' })
-    expect(zoomed.result.current[0]).toBe(true)
-  })
-})
-
-describe('createLocalStore — labels()', () => {
-  test('labels reach field.<name>.options, and the call is chainable', () => {
-    const store = createLocalStore({
-      key: 'l-labels',
-      fields: { metric: field.enum(['load', 'volume'], 'load') },
-    }).labels({ metric: { load: 'Training load', volume: 'Total volume' } })
-
-    expect(store.field.metric.options).toEqual([
-      { value: 'load', label: 'Training load' },
-      { value: 'volume', label: 'Total volume' },
-    ])
-  })
-
-  test('an unlabelled value falls back to the value itself', () => {
-    const store = createLocalStore({
-      key: 'l-labels-partial',
-      fields: { metric: field.enum(['load', 'volume'], 'load') },
-    }).labels({ metric: { load: 'Training load' } })
-
-    expect(store.field.metric.options.map((option) => option.label)).toEqual([
-      'Training load',
-      'volume',
-    ])
-  })
-})

package/src/styles.floor.test.ts

@@ -1,36 +0,0 @@
-/**
- * Regression test for the iOS input-zoom FLOOR itself (styles.css).
- *
- * This rule is load-bearing for accessibility (Safari zooms the viewport on focus below 16px and
- * never zooms back out) — it must never be silently softened (dropping `!important`, so an inline
- * `style` attribute defeats it again) or dropped (losing `max()`, turning the floor into a pin that
- * fights a deliberately larger input). Both properties are asserted directly against the shipped
- * CSS text, independent of the `check-theme` guard (which scans CONSUMER source, not this file).
- */
-import { readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'bun:test'
-
-const STYLES_CSS_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'styles.css')
-
-describe('styles.css — iOS input floor', () => {
-  const css = readFileSync(STYLES_CSS_PATH, 'utf8')
-
-  it('declares the floor rule on input, select, textarea', () => {
-    expect(css).toMatch(/input\s*,\s*\n?\s*select\s*,\s*\n?\s*textarea\s*\{/)
-  })
-
-  it('keeps max(16px, …) — a FLOOR, not a pin', () => {
-    expect(css).toContain('max(16px')
-  })
-
-  it('is !important — un-defeatable by an inline style attribute', () => {
-    const ruleMatch = css.match(
-      /input\s*,\s*\n?\s*select\s*,\s*\n?\s*textarea\s*\{\s*\n?\s*font-size:\s*([^;]+);/,
-    )
-    expect(ruleMatch).not.toBeNull()
-    expect(ruleMatch?.[1]).toContain('max(16px')
-    expect(ruleMatch?.[1]).toContain('!important')
-  })
-})