@gntik-ai/templates 0.0.0-stage → 0.6.0

package/src/status-403/Page.test.tsx

@@ -0,0 +1,23 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import Status403Page from './Page';
+
+describe('Status403Page', () => {
+  it('renders the forbidden message with landmarks', async () => {
+    render(<Status403Page />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'You don’t have access to Billing' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Go to dashboard' })).toHaveAttribute('href', '/');
+    await expectNoAxeViolations();
+  });
+
+  it('requests access and moves to the requested state', async () => {
+    const onRequestAccess = vi.fn(() => Promise.resolve());
+    render(<Status403Page resource="Audit log" onRequestAccess={onRequestAccess} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Request access' }));
+    expect(onRequestAccess).toHaveBeenCalledOnce();
+    expect(await screen.findByRole('button', { name: 'Access requested' })).toBeDisabled();
+    expect(screen.getByRole('status')).toHaveTextContent('Access request sent');
+  });
+});

package/src/status-403/Page.tsx

@@ -0,0 +1,92 @@
+import { Check, Home, Lock } from '@gntik-ai/icons';
+import { Button, Link, Logo, StatusLayout } from '@gntik-ai/ui';
+import { useState, type ReactNode } from 'react';
+import { forbiddenContent } from './data';
+
+export interface Status403Props {
+  /** What the viewer cannot see. */
+  resource: string;
+  /** Who can grant access. */
+  owner: string;
+  /** Called on "Request access"; may return a promise (the button shows a spinner). */
+  onRequestAccess: () => void | Promise<void>;
+  /** Start in the "requested" state (a pending request exists). */
+  defaultRequested: boolean;
+  homeHref: string;
+  homeLabel: string;
+  /** Account shown in the footer; `null` hides the line. */
+  signedInAs: string | null;
+  switchAccountHref: string;
+  header: ReactNode;
+  fullScreen: boolean;
+}
+
+type RequestState = 'idle' | 'pending' | 'requested';
+
+/** 403 page: StatusLayout with Request access (NoAccessEmpty behaviour) and a way home. */
+export default function Status403Page(props: Partial<Status403Props>) {
+  const {
+    resource = forbiddenContent.resource,
+    owner = forbiddenContent.owner,
+    onRequestAccess,
+    defaultRequested = false,
+    homeHref = forbiddenContent.homeHref,
+    homeLabel = forbiddenContent.homeLabel,
+    signedInAs = forbiddenContent.signedInAs,
+    switchAccountHref = forbiddenContent.switchAccountHref,
+    header = <Logo size={24} wordmark />,
+    fullScreen = true,
+  } = props;
+  const [state, setState] = useState<RequestState>(defaultRequested ? 'requested' : 'idle');
+
+  const request = async () => {
+    setState('pending');
+    try {
+      await onRequestAccess?.();
+      setState('requested');
+    } catch {
+      setState('idle');
+    }
+  };
+
+  const requested = state === 'requested';
+  return (
+    <StatusLayout
+      fullScreen={fullScreen}
+      tone="warning"
+      header={header}
+      icon={Lock}
+      code={forbiddenContent.code}
+      title={`You don’t have access to ${resource}`}
+      description={`Ask ${owner} to grant you a role that includes ${resource.toLowerCase()} permissions.`}
+      primaryAction={
+        <Button
+          variant={requested ? 'secondary' : 'primary'}
+          icon={requested ? Check : undefined}
+          loading={state === 'pending'}
+          disabled={requested}
+          onClick={() => void request()}
+        >
+          {requested ? 'Access requested' : 'Request access'}
+        </Button>
+      }
+      secondaryAction={
+        <Button variant="secondary" icon={Home} render={<a href={homeHref} />} nativeButton={false}>
+          {homeLabel}
+        </Button>
+      }
+      footer={
+        signedInAs ? (
+          <span>
+            Signed in as <span className="font-mono">{signedInAs}</span> ·{' '}
+            <Link href={switchAccountHref}>{forbiddenContent.switchAccountLabel}</Link>
+          </span>
+        ) : undefined
+      }
+    >
+      <p role="status" className="sr-only">
+        {requested ? 'Access request sent' : ''}
+      </p>
+    </StatusLayout>
+  );
+}

package/src/status-403/data.ts

@@ -0,0 +1,13 @@
+import { noAccessSample } from '@gntik-ai/blocks';
+
+/** Neutral fixtures for the 403 page (resource and owner reuse the NoAccessEmpty sample). */
+export const forbiddenContent = {
+  code: '403 · Forbidden',
+  resource: noAccessSample.resource,
+  owner: noAccessSample.owner,
+  homeLabel: 'Go to dashboard',
+  homeHref: '/',
+  signedInAs: 'dana@example.com',
+  switchAccountLabel: 'Switch account',
+  switchAccountHref: '/sign-in',
+};

package/src/status-403/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: '403 Forbidden',
+  family: 'System',
+  priority: 'P1',
+  status: 'beta',
+  description:
+    'Full-page permission state: explains who can grant access, with a Request access action (idle · pending · requested, like NoAccessEmpty) and a way home.',
+  layout: 'StatusLayout',
+  blocks: [],
+};

package/src/status-404/Page.test.tsx

@@ -0,0 +1,23 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import Status404Page from './Page';
+
+describe('Status404Page', () => {
+  it('renders the not-found message with landmarks and a way home', async () => {
+    render(<Status404Page />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'We can’t find that page' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Go to dashboard' })).toHaveAttribute('href', '/');
+    expect(screen.getByRole('link', { name: 'Contact support' })).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+
+  it('calls onBack from Go back', async () => {
+    const onBack = vi.fn();
+    render(<Status404Page onBack={onBack} homeHref="/projects" />);
+    await userEvent.click(screen.getByRole('button', { name: 'Go back' }));
+    expect(onBack).toHaveBeenCalledOnce();
+    expect(screen.getByRole('button', { name: 'Go to dashboard' })).toHaveAttribute('href', '/projects');
+  });
+});

package/src/status-404/Page.tsx

@@ -0,0 +1,60 @@
+import { ArrowLeft, FileQuestion, Home } from '@gntik-ai/icons';
+import { Button, Link, Logo, StatusLayout } from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+import { notFoundContent } from './data';
+
+export interface Status404Props {
+  title: ReactNode;
+  /** Replaces the built-in title; supply exactly one h1 and use its own ref for route focus. */
+  heading?: ReactNode;
+  description: ReactNode;
+  /** Where the primary action leads. */
+  homeHref: string;
+  homeLabel: string;
+  /** Go back handler; defaults to `history.back()`. */
+  onBack: () => void;
+  backLabel: string;
+  supportHref: string;
+  supportLabel: string;
+  /** Minimal top bar; defaults to the Logo with wordmark. */
+  header: ReactNode;
+  fullScreen: boolean;
+}
+
+/** 404 page: StatusLayout with a way home, Go back and a support link in the footer. */
+export default function Status404Page(props: Partial<Status404Props>) {
+  const {
+    title = notFoundContent.title,
+    heading,
+    description = notFoundContent.description,
+    homeHref = notFoundContent.homeHref,
+    homeLabel = notFoundContent.homeLabel,
+    onBack = () => window.history.back(),
+    backLabel = notFoundContent.backLabel,
+    supportHref = notFoundContent.supportHref,
+    supportLabel = notFoundContent.supportLabel,
+    header = <Logo size={24} wordmark />,
+    fullScreen = true,
+  } = props;
+  return (
+    <StatusLayout
+      fullScreen={fullScreen}
+      header={header}
+      icon={FileQuestion}
+      code={notFoundContent.code}
+      {...(heading != null ? { heading } : { title })}
+      description={description}
+      primaryAction={
+        <Button icon={Home} render={<a href={homeHref} />} nativeButton={false}>
+          {homeLabel}
+        </Button>
+      }
+      secondaryAction={
+        <Button variant="secondary" icon={ArrowLeft} onClick={onBack}>
+          {backLabel}
+        </Button>
+      }
+      footer={<Link href={supportHref}>{supportLabel}</Link>}
+    />
+  );
+}

package/src/status-404/PageHeading.test.tsx

@@ -0,0 +1,52 @@
+import { PageHeader } from '@gntik-ai/blocks';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from 'react';
+import { expectNoAxeViolations } from '../test/a11y';
+import Status404Page from './Page';
+
+it('uses PageHeader as the sole h1 while preserving the 404 content, actions and focus contract', async () => {
+  const user = userEvent.setup();
+  const onBack = vi.fn();
+  const titleRef = createRef<HTMLHeadingElement>();
+  render(
+    <Status404Page
+      homeHref="/dashboard"
+      onBack={onBack}
+      heading={
+        <PageHeader
+          as="div"
+          title="Page not found"
+          titleRef={titleRef}
+          breadcrumbs={null}
+          description={null}
+          status=""
+          meta={[]}
+          tabs={null}
+          actions={[]}
+        />
+      }
+    />,
+  );
+  expect(screen.getAllByRole('heading', { level: 1 })).toHaveLength(1);
+  const heading = screen.getByRole('heading', { level: 1, name: 'Page not found' });
+  expect(screen.queryByText('We can’t find that page')).not.toBeInTheDocument();
+  expect(screen.getByText('404 · Not found')).toBeInTheDocument();
+  expect(
+    screen.getByText(
+      'The page may have been moved or deleted, or the link is out of date. Check the address or head back to the dashboard.',
+    ),
+  ).toBeInTheDocument();
+  const primary = screen.getByRole('button', { name: 'Go to dashboard' });
+  expect(primary).toHaveAttribute('href', '/dashboard');
+  expect(screen.getByRole('main').querySelector('a[href], button, [tabindex="0"]')).toBe(primary);
+  expect(screen.getByRole('link', { name: 'Contact support' })).toHaveAttribute('href', '/support');
+  await user.tab();
+  await user.tab();
+  expect(primary).toHaveFocus();
+  titleRef.current?.focus();
+  expect(heading).toHaveFocus();
+  await user.click(screen.getByRole('button', { name: 'Go back' }));
+  expect(onBack).toHaveBeenCalledOnce();
+  await expectNoAxeViolations();
+});

package/src/status-404/data.ts

@@ -0,0 +1,12 @@
+/** Neutral fixtures for the 404 page. */
+export const notFoundContent = {
+  code: '404 · Not found',
+  title: 'We can’t find that page',
+  description:
+    'The page may have been moved or deleted, or the link is out of date. Check the address or head back to the dashboard.',
+  homeLabel: 'Go to dashboard',
+  homeHref: '/',
+  backLabel: 'Go back',
+  supportLabel: 'Contact support',
+  supportHref: '/support',
+};

package/src/status-404/examples/PageHeader.tsx

@@ -0,0 +1,28 @@
+import { PageHeader } from '@gntik-ai/blocks';
+import { useEffect, useRef } from 'react';
+import Status404Page from '../Page';
+
+export default function Status404PageHeader() {
+  const titleRef = useRef<HTMLHeadingElement>(null);
+  useEffect(() => {
+    titleRef.current?.focus();
+  }, []);
+
+  return (
+    <Status404Page
+      heading={
+        <PageHeader
+          as="div"
+          title="Page not found"
+          titleRef={titleRef}
+          breadcrumbs={null}
+          description={null}
+          status=""
+          meta={[]}
+          tabs={null}
+          actions={[]}
+        />
+      }
+    />
+  );
+}

package/src/status-404/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: '404 Not found',
+  family: 'System',
+  priority: 'P1',
+  status: 'beta',
+  description:
+    'Full-page not-found state: code, message, a primary way home, Go back and a support link. The optional heading slot replaces the built-in title so PageHeader supplies the only h1; code stays above it and actions remain unchanged. In the PageHeader example set as="div", breadcrumbs={null}, meta={[]}, tabs={null}, actions={[]}, status="" and description={null}; use StatusLayout’s description once. PageHeader titleRef adds tabIndex=-1 for ref.current.focus() on route load without a Tab stop; leave slot links and actions empty to keep the primary action first in main.',
+  layout: 'StatusLayout',
+  blocks: ['page-header'],
+};

package/src/status-500/Page.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import Status500Page from './Page';
+
+describe('Status500Page', () => {
+  it('renders the error page with the request id and landmarks', async () => {
+    render(<Status500Page />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Something went wrong on our side' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 2, name: 'The request failed' })).toBeInTheDocument();
+    expect(screen.getByText('req_3b91e6c2f04d')).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'System status' })).toHaveAttribute('href', '/status');
+    await expectNoAxeViolations();
+  });
+
+  it('retries through onRetry', async () => {
+    const onRetry = vi.fn(() => Promise.resolve());
+    render(<Status500Page onRetry={onRetry} requestId="req_custom" />);
+    await userEvent.click(screen.getByRole('button', { name: 'Try again' }));
+    expect(onRetry).toHaveBeenCalledOnce();
+    expect(screen.getByText('req_custom')).toBeInTheDocument();
+  });
+});

package/src/status-500/Page.tsx

@@ -0,0 +1,70 @@
+import { ErrorPanel, type FeedbackAction } from '@gntik-ai/blocks';
+import { ServerCrash } from '@gntik-ai/icons';
+import { Link, Logo, StatusLayout } from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+import { serverErrorContent, simulateRetry } from './data';
+
+export interface Status500Props {
+  title: ReactNode;
+  description: ReactNode;
+  /** Status or error code on the ErrorPanel chip. */
+  errorCode: string | number;
+  /** Correlation id for support (copyable). */
+  requestId: string;
+  /** Raw details behind the disclosure. */
+  details: string;
+  /** Retry handler; a returned promise shows the loading state. */
+  onRetry: () => void | Promise<void>;
+  /** Extra action next to Retry; `null` hides it. */
+  supportAction: FeedbackAction | null;
+  homeHref: string;
+  statusHref: string;
+  header: ReactNode;
+  fullScreen: boolean;
+}
+
+/** 500 page: StatusLayout + ErrorPanel with request id, retry and technical details. */
+export default function Status500Page(props: Partial<Status500Props>) {
+  const {
+    title = serverErrorContent.title,
+    description = serverErrorContent.description,
+    errorCode = serverErrorContent.errorCode,
+    requestId = serverErrorContent.requestId,
+    details = serverErrorContent.details,
+    onRetry = simulateRetry,
+    supportAction = { label: 'Contact support', variant: 'ghost' },
+    homeHref = serverErrorContent.homeHref,
+    statusHref = serverErrorContent.statusHref,
+    header = <Logo size={24} wordmark />,
+    fullScreen = true,
+  } = props;
+  return (
+    <StatusLayout
+      fullScreen={fullScreen}
+      tone="destructive"
+      header={header}
+      icon={ServerCrash}
+      code={serverErrorContent.code}
+      title={title}
+      description={description}
+      footer={
+        <>
+          <Link href={homeHref}>{serverErrorContent.homeLabel}</Link>
+          <Link href={statusHref}>{serverErrorContent.statusLabel}</Link>
+        </>
+      }
+    >
+      <ErrorPanel
+        titleAs="h2"
+        className="text-start"
+        title={serverErrorContent.panelTitle}
+        message={serverErrorContent.panelMessage}
+        code={errorCode}
+        requestId={requestId}
+        details={details}
+        onRetry={onRetry}
+        secondaryAction={supportAction}
+      />
+    </StatusLayout>
+  );
+}

package/src/status-500/data.ts

@@ -0,0 +1,20 @@
+/** Neutral fixtures for the 500 page. */
+export const serverErrorContent = {
+  code: '500 · Server error',
+  title: 'Something went wrong on our side',
+  description: 'The page failed to load. Nothing you did caused this, and your data is safe.',
+  panelTitle: 'The request failed',
+  panelMessage:
+    'An unexpected error interrupted the request. Try again; if it keeps happening, share the request ID with support.',
+  errorCode: 500,
+  requestId: 'req_3b91e6c2f04d',
+  details:
+    'GET /v1/projects/web-app/overview\n500 Internal Server Error\nunhandled exception in handler (trace: 7c1e9a42)',
+  homeLabel: 'Go to dashboard',
+  homeHref: '/',
+  statusLabel: 'System status',
+  statusHref: '/status',
+};
+
+/** Simulated retry for the standalone page. */
+export const simulateRetry = () => new Promise<void>((resolve) => setTimeout(resolve, 1200));

package/src/status-500/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: '500 Server error',
+  family: 'System',
+  priority: 'P1',
+  status: 'beta',
+  description:
+    'Full-page server error: StatusLayout message with an ErrorPanel (status code, copyable request id, retry, technical details) and links home and to the status page.',
+  layout: 'StatusLayout',
+  blocks: ['error-panel'],
+};

package/src/status-maintenance/Page.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import StatusMaintenancePage from './Page';
+
+describe('StatusMaintenancePage', () => {
+  it('renders the maintenance message, banner and status link', async () => {
+    render(<StatusMaintenancePage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'We’ll be back shortly' })).toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent('Maintenance in progress.');
+    expect(screen.getByRole('link', { name: 'Subscribe to updates' })).toHaveAttribute('href', '/status/subscribe');
+    expect(screen.getByRole('button', { name: 'View status page' })).toHaveAttribute('href', '/status');
+    await expectNoAxeViolations();
+  });
+
+  it('shows a note when Check again finds the service still down', async () => {
+    const onCheckAgain = vi.fn(() => false);
+    render(<StatusMaintenancePage onCheckAgain={onCheckAgain} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Check again' }));
+    expect(onCheckAgain).toHaveBeenCalledOnce();
+    expect(await screen.findByText('Still in maintenance. Try again in a few minutes.')).toBeInTheDocument();
+  });
+});

package/src/status-maintenance/Page.tsx

@@ -0,0 +1,84 @@
+import { SystemBanner } from '@gntik-ai/blocks';
+import { ExternalLink, RefreshCw, Wrench } from '@gntik-ai/icons';
+import { Button, Logo, StatusLayout } from '@gntik-ai/ui';
+import { useState, type ReactNode } from 'react';
+import { maintenanceContent } from './data';
+
+export interface StatusMaintenanceProps {
+  title: ReactNode;
+  description: ReactNode;
+  /** Bold lead-in and message of the maintenance banner. */
+  bannerTitle: ReactNode;
+  bannerMessage: ReactNode;
+  statusHref: string;
+  subscribeHref: string;
+  /**
+   * "Check again" handler. Resolve `true` when the service is back (the product then navigates);
+   * anything else shows the "still in maintenance" note.
+   */
+  onCheckAgain: () => boolean | void | Promise<boolean | void>;
+  header: ReactNode;
+  fullScreen: boolean;
+}
+
+/** Maintenance page: StatusLayout with Check again, a status page link and a maintenance SystemBanner. */
+export default function StatusMaintenancePage(props: Partial<StatusMaintenanceProps>) {
+  const {
+    title = maintenanceContent.title,
+    description = maintenanceContent.description,
+    bannerTitle = maintenanceContent.bannerTitle,
+    bannerMessage = maintenanceContent.bannerMessage,
+    statusHref = maintenanceContent.statusHref,
+    subscribeHref = maintenanceContent.subscribeHref,
+    onCheckAgain,
+    header = <Logo size={24} wordmark />,
+    fullScreen = true,
+  } = props;
+  const [checking, setChecking] = useState(false);
+  const [note, setNote] = useState('');
+
+  const check = async () => {
+    setChecking(true);
+    setNote('');
+    try {
+      const back = await onCheckAgain?.();
+      if (back !== true) setNote(maintenanceContent.stillDown);
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  return (
+    <StatusLayout
+      fullScreen={fullScreen}
+      tone="warning"
+      header={header}
+      icon={Wrench}
+      code={maintenanceContent.code}
+      title={title}
+      description={description}
+      primaryAction={
+        <Button icon={RefreshCw} loading={checking} onClick={() => void check()}>
+          Check again
+        </Button>
+      }
+      secondaryAction={
+        <Button variant="secondary" trailingIcon={ExternalLink} render={<a href={statusHref} />} nativeButton={false}>
+          {maintenanceContent.statusLabel}
+        </Button>
+      }
+    >
+      <SystemBanner
+        kind="maintenance"
+        dismissible={false}
+        title={bannerTitle}
+        message={bannerMessage}
+        action={{ label: maintenanceContent.subscribeLabel, href: subscribeHref }}
+        className="rounded-lg border text-start"
+      />
+      <p aria-live="polite" className="mt-3 min-h-4 text-[12.5px] text-muted-foreground">
+        {note}
+      </p>
+    </StatusLayout>
+  );
+}

package/src/status-maintenance/data.ts

@@ -0,0 +1,14 @@
+/** Neutral fixtures for the maintenance page. */
+export const maintenanceContent = {
+  code: 'Scheduled maintenance',
+  title: 'We’ll be back shortly',
+  description:
+    'We are upgrading the database. Running services are not affected; the dashboard is read-only until 14:30 UTC.',
+  bannerTitle: 'Maintenance in progress.',
+  bannerMessage: 'Started 13:00 UTC · expected to end 14:30 UTC.',
+  statusLabel: 'View status page',
+  statusHref: '/status',
+  subscribeLabel: 'Subscribe to updates',
+  subscribeHref: '/status/subscribe',
+  stillDown: 'Still in maintenance. Try again in a few minutes.',
+};

package/src/status-maintenance/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Maintenance',
+  family: 'System',
+  priority: 'P1',
+  status: 'beta',
+  description:
+    'Full-page maintenance state: message, Check again and a status page link, with a maintenance SystemBanner carrying the window and a subscribe link.',
+  layout: 'StatusLayout',
+  blocks: ['system-banner'],
+};

package/src/styles.css

@@ -0,0 +1,11 @@
+/* @gntik-ai/templates — everything a product built on the templates needs, in one import:
+     @import "tailwindcss";
+     @import "@gntik-ai/templates/styles.css";
+   Tokens + the Tailwind bridge (via ui), and the sources of every kit package the templates use. */
+@import "@gntik-ai/ui/styles.css";
+@import "@gntik-ai/blocks/styles.css";
+@import "@gntik-ai/charts/styles.css";
+@import "@gntik-ai/chat/styles.css";
+@import "@gntik-ai/flow/styles.css";
+@import "@gntik-ai/editor/styles.css";
+@source "../dist";

package/src/test/a11y.ts

@@ -0,0 +1,18 @@
+import axe from 'axe-core';
+
+/**
+ * Runs axe on a container and returns the violations. Colour contrast is checked in the
+ * browser suite (jsdom has no layout or computed colours), so it is disabled here.
+ */
+export async function axeViolations(container: Element = document.body) {
+  const result = await axe.run(container, {
+    rules: { 'color-contrast': { enabled: false }, region: { enabled: false } },
+  });
+  return result.violations.map((v) => `${v.id}: ${v.help} (${v.nodes.map((n) => n.target.join(' ')).join(', ')})`);
+}
+
+/** Asserts that a container has no axe violations. */
+export async function expectNoAxeViolations(container: Element = document.body) {
+  const violations = await axeViolations(container);
+  if (violations.length) throw new Error('axe violations:\n' + violations.join('\n'));
+}