@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/highlight-stat/HighlightStat.test.tsx

@@ -0,0 +1,83 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { setMedia } from '../../../test/media'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { HighlightStat } from './HighlightStat'
+
+/** Text a screen reader reaches: content outside aria-hidden subtrees. */
+function readable(el: Element): string {
+  if (el.getAttribute('aria-hidden') === 'true') return ''
+  return [...el.childNodes].map((n) => (n.nodeType === Node.TEXT_NODE ? n.textContent : n instanceof Element ? readable(n) : '')).join(' ')
+}
+
+describe('HighlightStat', () => {
+  it('is a group named by the label; the value is read once', () => {
+    render(<HighlightStat value={94} label="cases" reveal />)
+    const group = screen.getByRole('group', { name: 'cases' })
+    expect(group).toHaveAccessibleDescription('94')
+    expect(readable(group).match(/94/g)).toHaveLength(1)
+  })
+
+  it('shows the final value at once with reveal under reduced motion', () => {
+    setMedia({ reducedMotion: true })
+    const { container } = render(<HighlightStat value={94} label="cases" reveal />)
+    expect(container.querySelector('.ty-reveal-number__run')).toHaveTextContent('94')
+  })
+
+  it('has the source link as its only tab stop', async () => {
+    render(
+      <>
+        <HighlightStat value={1234} label="assertions" source={{ text: 'Edition 2026-09-20', href: '#/editions' }} />
+        <button type="button">after</button>
+      </>,
+    )
+    await userEvent.tab()
+    expect(screen.getByRole('link', { name: 'Edition 2026-09-20' })).toHaveFocus()
+    await userEvent.tab()
+    expect(screen.getByRole('button', { name: 'after' })).toHaveFocus()
+    expect(screen.getByRole('group', { name: 'assertions' })).toHaveAccessibleDescription(/Edition 2026-09-20/)
+  })
+
+  it('draws no card with surface none, a raised card otherwise', () => {
+    const { container } = render(
+      <>
+        <HighlightStat value="12" label="countries" />
+        <HighlightStat value={3} label="editions" surface="raised" />
+      </>,
+    )
+    const [plain, raised] = container.querySelectorAll('.ty-highlight-stat')
+    expect(plain).toHaveAttribute('data-surface', 'none')
+    expect(raised).toHaveAttribute('data-surface', 'raised')
+    const css = cssOf('components/highlight-stat/HighlightStat.css')
+    expect(css).not.toMatch(/\.ty-highlight-stat\s*\{[^}]*(border|box-shadow)/)
+    expect(css).not.toMatch(/--ty-cta|animation|transition|transform/)
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/CanvasText/)
+  })
+
+  it('formats numbers with the locale by default and a custom formatter when given', () => {
+    render(
+      <>
+        <HighlightStat value={1234} label="a" />
+        <HighlightStat value={0.25} label="b" format={(n) => `${n * 100}%`} />
+      </>,
+    )
+    expect(screen.getByText('1,234')).toBeInTheDocument()
+    expect(screen.getByText('25%')).toBeInTheDocument()
+  })
+
+  it('has no axe violations in light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((s) => (
+          <ThemeScope key={s} scheme={s}>
+            <HighlightStat value={94} label={`cases ${s}`} surface="raised" source={{ text: 'Edition', href: '#/e' }} />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/highlight-stat/HighlightStat.tsx

@@ -0,0 +1,66 @@
+import { useId } from 'react'
+import { useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { Link } from '../link/Link'
+import { RevealNumber } from '../reveal-number/RevealNumber'
+
+export interface HighlightStatSource {
+  text: string
+  href?: string
+}
+
+export interface HighlightStatProps {
+  /** The figure; a number may be revealed. */
+  value: number | string
+  /** What the figure counts. */
+  label: string
+  /** Count the value up through RevealNumber (numbers only). */
+  reveal?: boolean
+  /** Formatter for numbers; locale grouping by default. */
+  format?: (n: number) => string
+  /** Where the figure comes from (§3.5: every number is traceable). */
+  source?: HighlightStatSource
+  /** `raised` draws an elevation-2 card; `none` sits on the section. */
+  surface?: 'none' | 'raised'
+  className?: string
+}
+
+/**
+ * One headline figure with its label on a public page
+ * (spec: wave-4/highlight-stat.md). A group named by the label and described
+ * by the value and source; only the source link is focusable.
+ */
+export function HighlightStat(props: HighlightStatProps) {
+  const { locale } = useLocale()
+  const stem = useId().replace(/:/g, '')
+  const ids = { label: `ty-hs-${stem}-l`, value: `ty-hs-${stem}-v`, source: `ty-hs-${stem}-s` }
+  const fmt = props.format ?? ((n: number) => new Intl.NumberFormat(locale).format(n))
+  const numeric = typeof props.value === 'number'
+
+  let figure
+  if (numeric && props.reveal) figure = <RevealNumber to={props.value as number} format={fmt} />
+  else figure = numeric ? fmt(props.value as number) : props.value
+
+  const describedBy = props.source ? `${ids.value} ${ids.source}` : ids.value
+  return (
+    <div
+      role="group"
+      aria-labelledby={ids.label}
+      aria-describedby={describedBy}
+      className={cx('ty-highlight-stat', props.className)}
+      data-surface={props.surface ?? 'none'}
+    >
+      <p id={ids.value} className="ty-highlight-stat__value">
+        {figure}
+      </p>
+      <p id={ids.label} className="ty-highlight-stat__label">
+        {props.label}
+      </p>
+      {props.source && (
+        <p id={ids.source} className="ty-highlight-stat__source">
+          {props.source.href ? <Link href={props.source.href}>{props.source.text}</Link> : props.source.text}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/components/history-list/HistoryList.css

@@ -0,0 +1,116 @@
+/* HistoryList (spec: wave-2/history-list.md; design direction §2.2, §2.7, §2.11, §2.12). */
+@layer tympan.components {
+  .ty-history-list__items {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .ty-history-list__item + .ty-history-list__item {
+    border-block-start: 1px solid var(--ty-line);
+  }
+
+  .ty-history-list__header {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--ty-space-2);
+    box-sizing: border-box;
+    inline-size: 100%;
+    min-block-size: var(--ty-control-target);
+    padding: var(--ty-space-2) var(--ty-space-1);
+    border: 0;
+    border-radius: var(--ty-radius-control);
+    background: none;
+    color: var(--ty-ink-2);
+    font: inherit;
+    text-align: start;
+    outline: none;
+  }
+  button.ty-history-list__header {
+    cursor: pointer;
+  }
+  .ty-history-list__header[data-static] {
+    padding-inline-start: calc(var(--ty-space-1) + 1.15em + var(--ty-space-2));
+  }
+  .ty-history-list__header[data-hovered] {
+    background: var(--ty-surface-sunken);
+  }
+  .ty-history-list__header[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: -2px;
+  }
+
+  .ty-history-list__chevron {
+    margin-block-start: 0.2em;
+    color: var(--ty-ink-3);
+    transition: rotate var(--ty-dur-quick) var(--ty-ease);
+  }
+  .ty-history-list__entry[data-expanded] .ty-history-list__chevron {
+    rotate: 90deg;
+  }
+
+  .ty-history-list__header-text {
+    display: grid;
+    flex: 1;
+    gap: var(--ty-space-1);
+    min-inline-size: 0;
+  }
+  .ty-history-list__line {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ty-space-2);
+  }
+  .ty-history-list__start {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--ty-space-2);
+  }
+  .ty-history-list__summary {
+    overflow: hidden;
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .ty-history-list__details {
+    max-inline-size: calc(var(--ty-measure-prose) * 1ch);
+    padding: 0 var(--ty-space-2) var(--ty-space-3) calc(var(--ty-space-1) + 1.15em + var(--ty-space-2));
+  }
+  .ty-history-list__details[hidden] {
+    display: none;
+  }
+
+  .ty-history-list__ghost {
+    display: grid;
+    gap: var(--ty-space-2);
+    padding: var(--ty-space-3) var(--ty-space-1);
+    border-block-end: 1px solid var(--ty-line);
+  }
+  .ty-history-list__empty {
+    margin: 0;
+    padding: var(--ty-space-3) 0;
+    color: var(--ty-ink-3);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ty-history-list__chevron {
+      transition: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-history-list__item + .ty-history-list__item {
+      border-block-start-color: CanvasText;
+    }
+    .ty-history-list__chevron {
+      color: CanvasText;
+    }
+    .ty-history-list__header[data-focus-visible] {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/components/history-list/HistoryList.test.tsx

@@ -0,0 +1,88 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { HistoryList, type HistoryEntry } from './HistoryList'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+const entries: HistoryEntry[] = [
+  { id: 'a', start: 'Ana · 23 Sep', summary: 'Coded the value', details: 'Detail A' },
+  { id: 'b', start: 'Agent · 22 Sep', end: '2 changes', details: 'Detail B' },
+  { id: 'c', start: 'System · 21 Sep', details: 'Detail C' },
+]
+
+const base = { loadingLabel: 'Loading the history', emptyLabel: 'No history yet' }
+
+describe('HistoryList', () => {
+  it('opens the second entry', async () => {
+    render(<HistoryList items={entries} {...base} />)
+    const second = screen.getByRole('button', { name: /Agent/ })
+    await userEvent.click(second)
+    expect(second).toHaveAttribute('aria-expanded', 'true')
+    expect(screen.getByText('Detail B')).toBeVisible()
+  })
+
+  it('closes the open entry in single mode', async () => {
+    const onExpandedChange = vi.fn()
+    render(<HistoryList items={entries} {...base} defaultExpandedIds={['a']} onExpandedChange={onExpandedChange} />)
+    await userEvent.click(screen.getByRole('button', { name: /Agent/ }))
+    expect(screen.getByRole('button', { name: /Ana/ })).toHaveAttribute('aria-expanded', 'false')
+    expect(onExpandedChange).toHaveBeenLastCalledWith(['b'])
+  })
+
+  it('keeps several entries open in multiple mode', async () => {
+    render(<HistoryList items={entries} {...base} expansion="multiple" />)
+    await userEvent.click(screen.getByRole('button', { name: /Ana/ }))
+    await userEvent.click(screen.getByRole('button', { name: /Agent/ }))
+    expect(screen.getByRole('button', { name: /Ana/ })).toHaveAttribute('aria-expanded', 'true')
+    expect(screen.getByRole('button', { name: /Agent/ })).toHaveAttribute('aria-expanded', 'true')
+  })
+
+  it('renders an entry without details as a static header', () => {
+    render(<HistoryList items={[{ id: 'x', start: 'Frozen edition' }]} {...base} />)
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByText('Frozen edition')).toBeInTheDocument()
+  })
+
+  it('shows a status and no entries while loading', () => {
+    const { container } = render(<HistoryList items={entries} {...base} loading />)
+    expect(screen.getByRole('status')).toHaveTextContent('Loading the history')
+    expect(container.firstElementChild).toHaveAttribute('aria-busy', 'true')
+    expect(screen.queryByText(/Ana/)).toBeNull()
+  })
+
+  it('shows the empty label without items', () => {
+    render(<HistoryList items={[]} {...base} />)
+    expect(screen.getByText('No history yet')).toBeInTheDocument()
+  })
+
+  it('keeps 44 px headers and no transition under reduced motion', () => {
+    const css = cssOf('components/history-list/HistoryList.css')
+    expect(css).toMatch(/__header\s*\{[^}]*min-block-size:\s*var\(--ty-control-target\)/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/transition:\s*none/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <HistoryList items={entries.map((e) => ({ ...e, id: `${scheme}-${e.id}` }))} {...base} defaultExpandedIds={[`${scheme}-a`]} />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('HistoryList in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<HistoryList loadingLabel="تحميل" emptyLabel="لا يوجد سجل" items={[{ id: 'h', start: <span>مراجع</span>, summary: 'تحقق من سنة الإطلاق.', details: <p>تفاصيل</p> }]} />)
+    for (const svg of container.querySelectorAll('.ty-history-list__chevron')) expect(svg).toHaveClass('ty-mirror-rtl')
+    await axeRtl(container)
+  })
+})

package/src/components/history-list/HistoryList.tsx

@@ -0,0 +1,115 @@
+import { ChevronRight } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { Button, Disclosure, DisclosureGroup, DisclosurePanel, type Key } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { Skeleton } from '../skeleton/Skeleton'
+
+export interface HistoryEntry {
+  id: string
+  /** Leading part of the header: ActorChip, then the date (§2.11). */
+  start: ReactNode
+  end?: ReactNode
+  summary?: ReactNode
+  details?: ReactNode
+}
+
+export interface HistoryListProps {
+  items: HistoryEntry[]
+  loading?: boolean
+  loadingLabel: string
+  emptyLabel: string
+  expansion?: 'single' | 'multiple'
+  expandedIds?: string[]
+  defaultExpandedIds?: string[]
+  onExpandedChange?: (ids: string[]) => void
+  /** Number of skeleton rows while loading. */
+  skeletonRows?: number
+  className?: string
+}
+
+function HeaderText({ entry }: { entry: HistoryEntry }) {
+  return (
+    <span className="ty-history-list__header-text">
+      <span className="ty-history-list__line">
+        <span className="ty-history-list__start">{entry.start}</span>
+        {entry.end ? <span className="ty-history-list__end">{entry.end}</span> : null}
+      </span>
+      {entry.summary ? <span className="ty-history-list__summary">{entry.summary}</span> : null}
+    </span>
+  )
+}
+
+/** An entry with details: a disclosure whose header is the trigger. */
+function OpenableEntry({ entry }: { entry: HistoryEntry }) {
+  return (
+    <Disclosure id={entry.id} className="ty-history-list__entry" data-openable="">
+      <Button slot="trigger" className="ty-history-list__header">
+        <ChevronRight className="ty-icon ty-mirror-rtl ty-history-list__chevron" aria-hidden="true" focusable="false" />
+        <HeaderText entry={entry} />
+      </Button>
+      <DisclosurePanel className="ty-history-list__details">{entry.details}</DisclosurePanel>
+    </Disclosure>
+  )
+}
+
+/** An entry without details: a static header, no button, no chevron. */
+function StaticEntry({ entry }: { entry: HistoryEntry }) {
+  return (
+    <div className="ty-history-list__entry">
+      <div className="ty-history-list__header" data-static="">
+        <HeaderText entry={entry} />
+      </div>
+    </div>
+  )
+}
+
+const toIds = (keys: Set<Key>) => [...keys].map(String)
+
+/** Past entries whose headers expand to details (spec: wave-2/history-list.md). */
+export function HistoryList(props: HistoryListProps) {
+  const { items, loading = false, expansion = 'single', skeletonRows = 3 } = props
+
+  if (loading) {
+    return (
+      <div className={cx('ty-history-list', props.className)} aria-busy="true" data-state="loading">
+        <span role="status" className="ty-visually-hidden">
+          {props.loadingLabel}
+        </span>
+        {Array.from({ length: skeletonRows }, (_, i) => (
+          <div className="ty-history-list__ghost" key={i} aria-hidden="true">
+            <Skeleton width="medium" />
+            <Skeleton width="short" />
+          </div>
+        ))}
+      </div>
+    )
+  }
+
+  if (items.length === 0) {
+    return (
+      <p className={cx('ty-history-list', 'ty-history-list__empty', props.className)} data-state="empty">
+        {props.emptyLabel}
+      </p>
+    )
+  }
+
+  const selection =
+    props.expandedIds !== undefined ? { expandedKeys: props.expandedIds } : { defaultExpandedKeys: props.defaultExpandedIds ?? [] }
+
+  return (
+    <DisclosureGroup
+      className={cx('ty-history-list', props.className)}
+      allowsMultipleExpanded={expansion === 'multiple'}
+      onExpandedChange={(keys) => props.onExpandedChange?.(toIds(keys))}
+      {...selection}
+    >
+      <ol className="ty-history-list__items">
+        {items.map((entry) => (
+          <li key={entry.id} className="ty-history-list__item">
+            {entry.details == null ? <StaticEntry entry={entry} /> : <OpenableEntry entry={entry} />}
+          </li>
+        ))}
+      </ol>
+    </DisclosureGroup>
+  )
+}

package/src/components/http-error-page/HttpErrorPage.css

@@ -0,0 +1,70 @@
+/* HttpErrorPage (spec: wave-2/http-error-page.md; design direction §2.2, §2.3, §2.12). Neutral ink only. */
+@layer tympan.components {
+  .ty-http-error {
+    display: grid;
+    place-items: center;
+    min-block-size: 100dvh;
+    padding: var(--ty-space-6) var(--ty-space-4);
+    background: var(--ty-bg);
+    color: var(--ty-ink-2);
+    text-align: center;
+  }
+  .ty-http-error__column {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--ty-space-3);
+    max-inline-size: var(--ty-measure-summary);
+  }
+  .ty-http-error__icon {
+    inline-size: var(--ty-space-5);
+    block-size: var(--ty-space-5);
+    color: var(--ty-ink-3);
+  }
+  .ty-http-error__code {
+    margin: 0;
+    color: var(--ty-ink-3);
+    font-family: var(--ty-font-serif);
+    font-size: var(--ty-font-size-display);
+    line-height: var(--ty-font-line-height-display);
+    font-variant-numeric: tabular-nums;
+  }
+  .ty-http-error__title {
+    margin: 0;
+    color: var(--ty-ink);
+    font-family: var(--ty-font-serif);
+    font-size: var(--ty-font-size-h1);
+    font-weight: var(--ty-font-weight-bold);
+    line-height: var(--ty-font-line-height-h1);
+    outline: none;
+  }
+  .ty-http-error__title:focus-visible {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-http-error__message {
+    margin: 0;
+    font-size: var(--ty-font-size-body-lg);
+    line-height: var(--ty-font-line-height-body-lg);
+  }
+  .ty-http-error__problem {
+    margin: 0;
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+  }
+  .ty-http-error__problem code {
+    font-family: var(--ty-font-mono);
+  }
+  .ty-http-error__actions {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: var(--ty-space-3);
+    margin-block-start: var(--ty-space-3);
+  }
+  @media (forced-colors: active) {
+    .ty-http-error__icon {
+      color: CanvasText;
+    }
+  }
+}

package/src/components/http-error-page/HttpErrorPage.rtl.test.tsx

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { inRtl } from '../../../test/rtl-b'
+import { HttpErrorPage } from './HttpErrorPage'
+
+describe('HttpErrorPage in right-to-left locales', () => {
+  it('renders inside an Arabic right-to-left subtree and passes axe', async () => {
+    const { container } = inRtl(<HttpErrorPage kind="not-found" focusHeading={false} />)
+    expect(container.querySelector('[dir="rtl"]')).not.toBeNull()
+    await expectNoAxeViolations(document.body, ['region'])
+  })
+})

package/src/components/http-error-page/HttpErrorPage.test.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { Button } from '../button/Button'
+import { HttpErrorPage } from './HttpErrorPage'
+
+describe('HttpErrorPage', () => {
+  it('shows the default localised title as the only h1, code read once', () => {
+    const { container } = render(<HttpErrorPage kind="not-found" />)
+    const headings = screen.getAllByRole('heading', { level: 1 })
+    expect(headings).toHaveLength(1)
+    expect(headings[0]).toHaveTextContent('Error 404: Page not found')
+    expect(container.querySelector('.ty-http-error__code')).toHaveAttribute('aria-hidden', 'true')
+    expect(screen.getByRole('main')).toBeInTheDocument()
+  })
+
+  it('replaces the message', () => {
+    render(<HttpErrorPage kind="bad-request" message="The station id is malformed." />)
+    expect(screen.getByText('The station id is malformed.')).toBeInTheDocument()
+  })
+
+  it('shows the problem type as monospace metadata', () => {
+    render(<HttpErrorPage kind="server-error" problemType="https://example.org/problems/upstream" />)
+    expect(screen.getByText('https://example.org/problems/upstream').tagName).toBe('CODE')
+  })
+
+  it('moves focus to the heading on mount', () => {
+    render(<HttpErrorPage kind="server-error" action={<Button>Try again</Button>} />)
+    expect(screen.getByRole('heading', { level: 1 })).toHaveFocus()
+  })
+
+  it('never uses the accent as the error colour', () => {
+    expect(cssOf('components/http-error-page/HttpErrorPage.css')).not.toMatch(/--ty-accent/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        <ThemeScope scheme="light">
+          <HttpErrorPage kind="not-found" focusHeading={false} />
+        </ThemeScope>
+        <ThemeScope scheme="dark">
+          <HttpErrorPage kind="bad-request" focusHeading={false} />
+        </ThemeScope>
+      </>,
+    )
+    await expectNoAxeViolations(container, ['landmark-no-duplicate-main', 'landmark-one-main', 'landmark-main-is-top-level', 'page-has-heading-one', 'landmark-unique'])
+  })
+})

package/src/components/http-error-page/HttpErrorPage.tsx

@@ -0,0 +1,70 @@
+import { FileQuestion, ServerCrash, TriangleAlert } from 'lucide-react'
+import { useEffect, useRef, type ReactNode, type RefObject } from 'react'
+import { cx } from '../../internal/cx'
+import type { HttpErrorKind } from '../../internal/messages/auth-brand'
+import { useMessages } from '../../internal/provider'
+import type { IconComponent } from '../../internal/types'
+
+export type { HttpErrorKind }
+
+export interface HttpErrorPageProps {
+  kind: HttpErrorKind
+  /** Exact code for 5xx variants (502, 503 …); the kind's code otherwise. */
+  code?: number
+  title?: string
+  message?: string
+  action?: ReactNode
+  /** problem+json `type`, shown as monospace metadata. */
+  problemType?: string
+  /** Moves focus to the heading on mount (client-side navigation). */
+  focusHeading?: boolean
+  className?: string
+}
+
+/** Status family per kind: its default code and its glyph. */
+const FAMILY: Record<HttpErrorKind, readonly [number, IconComponent]> = {
+  'bad-request': [400, TriangleAlert],
+  'not-found': [404, FileQuestion],
+  'server-error': [500, ServerCrash],
+}
+
+/** After a client-side navigation, the page title takes focus so the change is announced. */
+function useArrivalFocus(target: RefObject<HTMLElement | null>, enabled: boolean) {
+  useEffect(() => {
+    if (enabled) target.current?.focus()
+  }, [target, enabled])
+}
+
+/** Whole-page 404, 400 and 5xx states (spec: wave-2/http-error-page.md). */
+export function HttpErrorPage(props: HttpErrorPageProps) {
+  const words = useMessages().httpError
+  const titleRef = useRef<HTMLHeadingElement>(null)
+  const [familyCode, Glyph] = FAMILY[props.kind]
+  const status = props.code ?? familyCode
+  const fallback = words[props.kind]
+  useArrivalFocus(titleRef, props.focusHeading ?? true)
+
+  return (
+    <main className={cx('ty-http-error', props.className)} data-kind={props.kind}>
+      <div className="ty-http-error__column">
+        <Glyph className="ty-http-error__icon" aria-hidden="true" focusable="false" />
+        {/* The big number is decoration; the heading says it in words. */}
+        <p aria-hidden="true" className="ty-http-error__code">
+          {status}
+        </p>
+        <h1 ref={titleRef} className="ty-http-error__title" tabIndex={-1}>
+          <span className="ty-visually-hidden">{`${words.codeLabel(status)}: `}</span>
+          {props.title ?? fallback.title}
+        </h1>
+        <p className="ty-http-error__message">{props.message ?? fallback.message}</p>
+        {props.problemType && (
+          <p className="ty-http-error__problem">
+            <span className="ty-visually-hidden">{`${words.problemType}: `}</span>
+            <code>{props.problemType}</code>
+          </p>
+        )}
+        {props.action && <div className="ty-http-error__actions">{props.action}</div>}
+      </div>
+    </main>
+  )
+}