basalt-ui 1.26.0 → 1.28.0

package/src/controls/sync-button.test.tsx

@@ -1,183 +0,0 @@
-/**
- * `SyncButton` — the age formatting and the syncing state (law C12, `docs/CONTROLS-SPEC.md` §3).
- *
- * The age is the part that had four hand-rolled copies across consumers, each with its own
- * rounding; `formatAge` is asserted directly so the boundaries are pinned, not inferred from one
- * rendered string.
- */
-import { MantineProvider } from '@mantine/core'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { renderToStaticMarkup } from 'react-dom/server'
-import { describe, expect, test } from 'bun:test'
-import { AGE_REFRESH_MS, SyncButton, formatAge } from './sync-button'
-
-function renderSync(props: Partial<Parameters<typeof SyncButton>[0]> = {}) {
-  return render(
-    <MantineProvider>
-      <SyncButton syncing={false} scope="page" onSync={() => {}} {...props} />
-    </MantineProvider>,
-  )
-}
-
-describe('formatAge', () => {
-  test('anything under a minute is `just now`, so a fresh sync stops flickering', () => {
-    expect(formatAge(0)).toBe('just now')
-    expect(formatAge(59_000)).toBe('just now')
-  })
-
-  test('minutes, then hours, then days', () => {
-    expect(formatAge(60_000)).toBe('1m ago')
-    expect(formatAge(2 * 60_000)).toBe('2m ago')
-    expect(formatAge(59 * 60_000)).toBe('59m ago')
-    expect(formatAge(60 * 60_000)).toBe('1h ago')
-    expect(formatAge(23 * 60 * 60_000)).toBe('23h ago')
-    expect(formatAge(24 * 60 * 60_000)).toBe('1d ago')
-  })
-
-  test('the refresh interval is coarser than the smallest unit it renders', () => {
-    expect(AGE_REFRESH_MS).toBeLessThanOrEqual(60_000)
-  })
-})
-
-describe('SyncButton', () => {
-  test('renders the age beside the label on desktop', () => {
-    renderSync({ lastCompletedAt: Date.now() - 2 * 60_000 })
-    expect(screen.getByRole('button').textContent).toContain('Sync')
-    expect(screen.getByRole('button').textContent).toContain('2m ago')
-  })
-
-  test('a Date and an epoch number are the same input', () => {
-    renderSync({ lastCompletedAt: new Date(Date.now() - 3 * 60_000) })
-    expect(screen.getByRole('button').textContent).toContain('3m ago')
-  })
-
-  test('no age at all when nothing has completed yet', () => {
-    renderSync({ lastCompletedAt: null })
-    expect(screen.getByRole('button').textContent).toBe('Sync')
-  })
-
-  test('syncing announces itself and refuses a second click — WITHOUT losing focus', () => {
-    let presses = 0
-    renderSync({
-      syncing: true,
-      onSync: () => {
-        presses += 1
-      },
-    })
-    const button = screen.getByRole('button')
-
-    expect(button.getAttribute('aria-busy')).toBe('true')
-    expect(button.getAttribute('aria-disabled')).toBe('true')
-    // The NATIVE attribute is what drops focus to <body> mid-press, so it must stay off: a keyboard
-    // user who presses Sync has to still be standing on the button when the sync lands.
-    expect(button.hasAttribute('disabled')).toBe(false)
-    expect(button.hasAttribute('data-disabled')).toBe(true)
-
-    button.focus()
-    fireEvent.click(button)
-    expect(presses).toBe(0)
-    expect(document.activeElement).toBe(button)
-  })
-
-  test('an idle press does call onSync — the refusal above is not just a dead handler', () => {
-    let presses = 0
-    renderSync({
-      onSync: () => {
-        presses += 1
-      },
-    })
-    fireEvent.click(screen.getByRole('button'))
-    expect(presses).toBe(1)
-  })
-
-  test('the age is absent on the server, so hydration cannot mismatch it', () => {
-    // `Date.now()` during render is the whole bug: the server renders one age and a client hydrating
-    // a minute later renders another. Both must render NO age; the effect fills it in after mount.
-    const html = renderToStaticMarkup(
-      <MantineProvider>
-        <SyncButton
-          syncing={false}
-          scope="page"
-          onSync={() => {}}
-          lastCompletedAt={Date.now() - 5 * 60_000}
-        />
-      </MantineProvider>,
-    )
-    expect(html).not.toContain('5m ago')
-    expect(html).toContain('Sync')
-  })
-
-  test('an error puts the control in the danger tone', () => {
-    renderSync({ error: 'Upstream 503' })
-    expect(screen.getByRole('button').getAttribute('data-variant')).toBe('default')
-    expect(document.querySelector('[data-basalt-sync-scope="page"]')).not.toBeNull()
-  })
-
-  test('the error message is in the accessible name, not only in a hover tooltip', () => {
-    // A tooltip announces only while open, and Mantine's opens on hover ALONE by default — so
-    // without this the red colour is the entire signal for a keyboard or screen-reader user.
-    renderSync({ error: 'Rate limited' })
-    expect(screen.getByRole('button', { name: 'Sync — Rate limited' })).toBeDefined()
-  })
-
-  test('scope reaches the DOM so a call site is readable without reading the props', () => {
-    renderSync({ scope: 'global' })
-    expect(document.querySelector('[data-basalt-sync-scope="global"]')).not.toBeNull()
-  })
-})
-
-/**
- * The shape per scope. `scope` used to be documentation only; it now picks the form, because the
- * shell header has no room for a labelled button beside the breadcrumb, `PageBar` row 1 and every
- * other global action — and a page bar does (spec §3, law C12).
- */
-describe('the shape follows the scope', () => {
-  test('global renders an ActionIcon with no label text at any width', () => {
-    renderSync({ scope: 'global', label: 'Sync all' })
-    const button = screen.getByRole('button')
-    // Mantine's own class names are static strings (unlike a CSS-module hash), so which PRIMITIVE
-    // rendered is assertable — and it is the whole difference between the two forms.
-    expect(button.classList.contains('mantine-ActionIcon-root')).toBe(true)
-    // Icon-only on EVERY viewport, so there is no text to hide with a media query in the first
-    // place: the label reaches the user as the accessible name only.
-    expect(button.textContent).toBe('')
-    expect(screen.getByRole('button', { name: 'Sync all' })).toBeDefined()
-  })
-
-  test('a global button carries no rendered age either — the tooltip is its only home', () => {
-    renderSync({ scope: 'global', lastCompletedAt: Date.now() - 4 * 60_000 })
-    expect(screen.getByRole('button').textContent).toBe('')
-  })
-
-  test('page renders the labelled Button, and is named even once the label is hidden below sm', () => {
-    renderSync({ scope: 'page' })
-    const button = screen.getByRole('button')
-    expect(button.classList.contains('mantine-Button-root')).toBe(true)
-    expect(button.textContent).toBe('Sync')
-    // jsdom evaluates no media query, so the `display: none` below `sm` is not observable here —
-    // what IS observable is the half that makes it safe: `display: none` text leaves the
-    // accessibility tree, so the name has to come from `aria-label`, not from the children.
-    expect(button.getAttribute('aria-label')).toBe('Sync')
-  })
-
-  test('both scopes fold an error into the accessible name, not only into the tone', () => {
-    renderSync({ scope: 'global', error: 'Upstream 503' })
-    expect(screen.getByRole('button', { name: 'Sync — Upstream 503' })).toBeDefined()
-  })
-
-  test('a global button refuses a second click while syncing, exactly as the page form does', () => {
-    let presses = 0
-    renderSync({
-      scope: 'global',
-      syncing: true,
-      onSync: () => {
-        presses += 1
-      },
-    })
-    const button = screen.getByRole('button')
-    expect(button.getAttribute('aria-disabled')).toBe('true')
-    expect(button.hasAttribute('disabled')).toBe(false)
-    fireEvent.click(button)
-    expect(presses).toBe(0)
-  })
-})

package/src/dashboard/query-state.test.tsx

@@ -1,152 +0,0 @@
-/**
- * `QueryState` exists because shipping only `EmptyState` produced a correctness bug in a real
- * consumer: a 500 rendered "No images", a dropped connection rendered "Share not found — it may
- * have been deleted". Every assertion here is aimed at that failure mode rather than at chrome.
- *
- *  1. A FAILED query never renders the empty copy. This is the bug, stated as a test.
- *  2. A failed query WITH cached data keeps the page and adds a banner — a background refetch
- *     failing must not blank a screen that already works.
- *  3. `fetchStatus: 'idle'` with no data is EMPTY, not loading (the `enabled: false` case);
- *     `'fetching'` with no data is loading.
- *  4. A result missing a branch flag THROWS. `QueryStateLike` is a structural subset on purpose,
- *     so the compiler stops policing it — and every field it can lose fails silently in the
- *     direction of a false claim about the data.
- */
-import { MantineProvider } from '@mantine/core'
-import { render, screen } from '@testing-library/react'
-import { describe, expect, test } from 'bun:test'
-import type { ReactNode } from 'react'
-import { QueryState } from './query-state'
-import type { QueryStateLike } from './query-state'
-
-type Row = { id: number }
-
-function result(over: Partial<QueryStateLike<Row[]>>): QueryStateLike<Row[]> {
-  return {
-    data: undefined,
-    isError: false,
-    error: null,
-    fetchStatus: 'idle',
-    refetch: () => undefined,
-    ...over,
-  }
-}
-
-const EMPTY = { title: 'No images match', description: 'Widen the capture dates.' }
-
-function renderState(query: QueryStateLike<Row[]>, extra?: ReactNode): HTMLElement {
-  const { container } = render(
-    <MantineProvider>
-      <QueryState query={query} empty={EMPTY} errorTitle="Could not load images">
-        {(rows) => <div data-testid="body">{rows.length} rows</div>}
-      </QueryState>
-      {extra}
-    </MantineProvider>,
-  )
-  return container
-}
-
-describe('the branch a 500 must not take', () => {
-  test('an errored query renders the server message, never the empty copy', () => {
-    renderState(
-      result({ isError: true, error: { status: 500, value: { message: 'index is rebuilding' } } }),
-    )
-    expect(screen.getByText('index is rebuilding')).toBeTruthy()
-    expect(screen.queryByText('No images match')).toBeNull()
-    expect(screen.getByRole('button', { name: 'Retry' })).toBeTruthy()
-  })
-
-  test('an opaque 500 envelope falls back to the errorTitle copy plus the status', () => {
-    render(
-      <MantineProvider>
-        <QueryState
-          query={result({ isError: true, error: { status: 500, value: {} } })}
-          errorTitle="Could not load images"
-          errorFallback="The library did not answer."
-        >
-          {() => null}
-        </QueryState>
-      </MantineProvider>,
-    )
-    expect(screen.getByText('The library did not answer. (HTTP 500)')).toBeTruthy()
-  })
-
-  test('retry calls refetch', () => {
-    let calls = 0
-    renderState(result({ isError: true, error: new Error('down'), refetch: () => ++calls }))
-    ;(screen.getByRole('button', { name: 'Retry' }) as HTMLButtonElement).click()
-    expect(calls).toBe(1)
-  })
-})
-
-describe('cached data survives a failed refresh', () => {
-  test('error WITH data renders the body plus a banner, not the error page', () => {
-    renderState(result({ data: [{ id: 1 }], isError: true, error: new Error('refresh failed') }))
-    expect(screen.getByTestId('body').textContent).toBe('1 rows')
-    expect(screen.getByText('Showing cached data')).toBeTruthy()
-  })
-})
-
-describe('empty vs loading', () => {
-  test('no data + idle is EMPTY (the enabled:false case)', () => {
-    renderState(result({ fetchStatus: 'idle' }))
-    expect(screen.getByText('No images match')).toBeTruthy()
-  })
-
-  test('no data + fetching is LOADING', () => {
-    renderState(result({ fetchStatus: 'fetching' }))
-    expect(screen.queryByText('No images match')).toBeNull()
-    expect(screen.getByLabelText('Loading')).toBeTruthy()
-  })
-
-  test('an empty array is empty; a populated one renders children', () => {
-    renderState(result({ data: [] }))
-    expect(screen.getByText('No images match')).toBeTruthy()
-  })
-
-  test('isEmpty overrides the default test', () => {
-    render(
-      <MantineProvider>
-        <QueryState query={result({ data: [] })} empty={EMPTY} isEmpty={() => false}>
-          {(rows) => <div data-testid="body">{rows.length} rows</div>}
-        </QueryState>
-      </MantineProvider>,
-    )
-    expect(screen.getByTestId('body').textContent).toBe('0 rows')
-  })
-
-  test('omitting `empty` renders nothing rather than inventing copy', () => {
-    render(
-      <MantineProvider>
-        <QueryState query={result({ data: [] })}>{() => <div>rows</div>}</QueryState>
-      </MantineProvider>,
-    )
-    expect(screen.queryByText('rows')).toBeNull()
-  })
-})
-
-describe('a malformed result throws instead of asserting absence', () => {
-  const cases: [string, unknown][] = [
-    ['missing isError', { data: undefined, error: null, fetchStatus: 'idle', refetch: () => 0 }],
-    [
-      'misspelled fetchStatus',
-      { data: undefined, isError: false, error: null, fetchStatus: 'pending', refetch: () => 0 },
-    ],
-    ['missing refetch', { data: undefined, isError: false, error: null, fetchStatus: 'idle' }],
-    ['not an object at all', ['a', 'b']],
-  ]
-
-  for (const [name, bad] of cases) {
-    test(name, () => {
-      expect(() =>
-        render(
-          <MantineProvider>
-            <QueryState query={bad as QueryStateLike<Row[]>} empty={EMPTY}>
-              {() => null}
-            </QueryState>
-          </MantineProvider>,
-        ),
-      ).toThrow(/QueryState: `query`/)
-    })
-  }
-})

package/src/dashboard/settings-section.test.tsx

@@ -1,56 +0,0 @@
-/**
- * SettingsSection / DangerZone — the WidgetHeader composition (docs/CONTROLS-SPEC.md §2.2):
- * `description` renamed to `subtitle`, both now render an h2 (`tier="section"`) via `WidgetHeader`,
- * and `actions` reaches the header's actions slot.
- */
-import { MantineProvider } from '@mantine/core'
-import { render, screen } from '@testing-library/react'
-import { describe, expect, test } from 'bun:test'
-import type { ReactElement } from 'react'
-import { DangerZone, SettingsSection } from './settings-section'
-
-function renderWith(node: ReactElement) {
-  return render(<MantineProvider>{node}</MantineProvider>)
-}
-
-describe('SettingsSection composes WidgetHeader at the section tier', () => {
-  test('renders an h2 carrying the title', () => {
-    renderWith(
-      <SettingsSection title="Profile">
-        <div>rows</div>
-      </SettingsSection>,
-    )
-    expect(screen.getByRole('heading', { level: 2, name: 'Profile' })).toBeDefined()
-  })
-
-  test('subtitle (renamed from description) renders below the title', () => {
-    renderWith(
-      <SettingsSection title="Profile" subtitle="Your public identity.">
-        <div>rows</div>
-      </SettingsSection>,
-    )
-    expect(screen.getByText('Your public identity.')).toBeDefined()
-  })
-
-  test('actions reach the header actions slot', () => {
-    renderWith(
-      <SettingsSection title="Profile" actions={<button type="button">Export</button>}>
-        <div>rows</div>
-      </SettingsSection>,
-    )
-    expect(screen.getByRole('button', { name: 'Export' })).toBeDefined()
-  })
-})
-
-describe('DangerZone keeps its eyebrow alongside the WidgetHeader', () => {
-  test('renders the eyebrow and an h2 title', () => {
-    renderWith(
-      <DangerZone title="Delete workspace" subtitle="This action cannot be undone.">
-        <div>rows</div>
-      </DangerZone>,
-    )
-    expect(screen.getByText('Danger Zone')).toBeDefined()
-    expect(screen.getByRole('heading', { level: 2, name: 'Delete workspace' })).toBeDefined()
-    expect(screen.getByText('This action cannot be undone.')).toBeDefined()
-  })
-})

package/src/dashboard/stat-card.test.tsx

@@ -1,154 +0,0 @@
-/**
- * `StatCard`'s threshold rail — the one behavior in this component that carries information rather
- * than layout, and the one where a regression is silent: a wrong rail colour still renders a
- * perfectly good-looking card.
- *
- * Two invariants, both asserted against real rendered markup:
- *
- *  1. EVERY tone states its verdict in TEXT. The rail is `aria-hidden` decoration; colour alone must
- *     never be the only carrier of a threshold (WCAG 1.4.1), so a `VisuallyHidden` string ships with
- *     it — for `good` no less than for `bad`.
- *  2. OMISSION IS NOT `good`. `tone` undefined means "fine, OR nothing measured", and those two are
- *     the same untinted card on purpose. A card with no reading must not be able to render green by
- *     leaving the prop off, so the absence case asserts no rail and no verdict text at all — which a
- *     future `tone = tone ?? 'good'` style default would immediately fail.
- *
- * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
- * `theme/use-basalt-spacing.test.tsx`'s doc) — `renderToStaticMarkup` inside a real `MantineProvider`
- * is used deliberately here instead, since the rail is an inline style on server-rendered markup.
- * Converting to the DOM harness would only be worth it if a future assertion here needed live DOM
- * behavior (e.g. computed styles, focus/hover interaction) rather than the static markup string.
- */
-import { MantineProvider } from '@mantine/core'
-import { describe, expect, test } from 'bun:test'
-import { renderToStaticMarkup } from 'react-dom/server'
-import { StatCard } from './stat-card'
-import type { StatCardTone } from './stat-card'
-
-function render(tone?: StatCardTone) {
-  return renderToStaticMarkup(
-    <MantineProvider>
-      {/* exactOptionalPropertyTypes forbids an explicit tone={undefined} — spread only when set */}
-      <StatCard
-        title="Downtime · last 24h"
-        value="0 min"
-        {...(tone !== undefined ? { tone } : {})}
-      />
-    </MantineProvider>,
-  )
-}
-
-const TONES: { tone: StatCardTone; token: string; verdict: string }[] = [
-  { tone: 'good', token: 'var(--vx-status-good)', verdict: 'Within the good threshold' },
-  { tone: 'warn', token: 'var(--vx-status-warn)', verdict: 'Past the warning threshold' },
-  { tone: 'bad', token: 'var(--vx-status-bad)', verdict: 'Past the severe threshold' },
-]
-
-describe('every tone draws its rail from the per-scheme status token', () => {
-  for (const { tone, token } of TONES) {
-    test(tone, () => {
-      const markup = render(tone)
-      // A hex here would be one scheme's colour frozen into both — the rail has to re-resolve with
-      // the palette, including under a consumer's `derive` retune.
-      expect(markup).toContain(`background:${token}`)
-      expect(markup).toContain(`data-tone="${tone}"`)
-    })
-  }
-})
-
-describe('every tone also states its verdict in text', () => {
-  for (const { tone, verdict } of TONES) {
-    test(tone, () => {
-      expect(render(tone)).toContain(verdict)
-    })
-  }
-})
-
-describe('omitting tone is not "good" — it is untinted, and says nothing', () => {
-  const markup = render()
-
-  test('no rail is drawn', () => {
-    expect(markup).not.toContain('var(--vx-status-')
-  })
-
-  test('the card carries no data-tone at all', () => {
-    // Part of the same contract, and the half a consumer can style against: `[data-tone]` must not
-    // match an unmarked card. A default of any kind — including a placeholder like `tone ?? 'none'`
-    // that draws no rail — would put the attribute back and break that selector silently.
-    expect(markup).not.toContain('data-tone')
-  })
-
-  test('no verdict is announced', () => {
-    for (const { verdict } of TONES) expect(markup).not.toContain(verdict)
-  })
-
-  test('the value still renders — the card is normal, just unmarked', () => {
-    expect(markup).toContain('0 min')
-  })
-})
-
-describe('the header composes WidgetHeader at the widget tier', () => {
-  test('renders an h3 carrying the title', () => {
-    const markup = renderToStaticMarkup(
-      <MantineProvider>
-        <StatCard title="Active Users" value="12,483" />
-      </MantineProvider>,
-    )
-    expect(markup).toContain('<h3')
-    expect(markup).toContain('Active Users')
-  })
-})
-
-describe('info and subtitle reach the composed WidgetHeader', () => {
-  function renderHeader(props: { info?: string; subtitle?: string }) {
-    return renderToStaticMarkup(
-      <MantineProvider>
-        <StatCard title="Training load" value="412" {...props} />
-      </MantineProvider>,
-    )
-  }
-
-  test('the subtitle renders as its own line under the hero row', () => {
-    expect(renderHeader({ subtitle: 'TSS · 7-day rolling' })).toContain('TSS · 7-day rolling')
-  })
-
-  test('the info text ships with the glyph, and never inside the heading', () => {
-    const markup = renderHeader({ info: 'Sum of per-session TSS over 7 days.' })
-    // `WidgetHeader` renders the bubble only while open, so the closed markup carries the named
-    // trigger — what matters here is that the card FORWARDED the prop and that the text stayed OUT
-    // of the `<h3>`, which is what an `info` rendered inside the heading would silently do.
-    expect(markup).toContain('aria-label="More information"')
-    const heading = /<h3[^>]*>(.*?)<\/h3>/.exec(markup)?.[1] ?? ''
-    expect(heading).toContain('Training load')
-    expect(heading).not.toContain('Sum of')
-  })
-
-  test('neither prop renders anything when omitted — no glyph, no empty line', () => {
-    expect(renderHeader({})).not.toContain('More information')
-  })
-})
-
-describe('sparklinePlacement', () => {
-  function renderWithSparkline(placement?: 'bleed' | 'right') {
-    return renderToStaticMarkup(
-      <MantineProvider>
-        <StatCard
-          title="Active Users"
-          value="12,483"
-          sparkline={<span data-testid="spark">spark</span>}
-          {...(placement !== undefined ? { sparklinePlacement: placement } : {})}
-        />
-      </MantineProvider>,
-    )
-  }
-
-  test('defaults to bleed — the full-width row bled to the card edges', () => {
-    const markup = renderWithSparkline()
-    expect(markup).toContain('data-placement="bleed"')
-  })
-
-  test('right sits the sparkline beside the hero-value row', () => {
-    const markup = renderWithSparkline('right')
-    expect(markup).toContain('data-placement="right"')
-  })
-})