commit 2d314401f17cafca00deb9a63ee8ac4adfbf4f1d parent b36377700d2a890fefaba15be1714c4f1b1eaf93 Author: triesap <tyson@radroots.org> Date: Mon, 5 Oct 2026 05:07:48 +0000 design: build accessible presentation primitives (HCP-013) - Add seven finite typed primitives with native HTML and shared link validation. - Associate controls and errors and guard disabled and pending commands. - Verify actual keyboard disclosure and inline confirmation with safe focus return. - Compile isolated source-audited component fixtures while preserving primary output. Diffstat:
11 files changed, 623 insertions(+), 2 deletions(-)
diff --git a/web/src/lib/components/primitives/ActionGroup.svelte b/web/src/lib/components/primitives/ActionGroup.svelte @@ -0,0 +1,8 @@ +<script lang="ts"> + import type { Snippet } from 'svelte'; + let { children }: { children?: Snippet } = $props(); +</script> + +<div class="cluster"> + {#if children}{@render children()}{/if} +</div> diff --git a/web/src/lib/components/primitives/Button.svelte b/web/src/lib/components/primitives/Button.svelte @@ -0,0 +1,54 @@ +<script lang="ts"> + import { navigationHref } from '../../navigation-url'; + type Props = { + label: string; + variant?: 'primary' | 'secondary'; + } & ( + | { + kind?: 'button'; + type?: 'button' | 'submit' | 'reset'; + disabled?: boolean; + onclick?: () => void; + href?: never; + } + | { + kind: 'link'; + href: string; + type?: never; + disabled?: never; + onclick?: never; + } + ); + let { + label, + variant = 'secondary', + kind = 'button', + type = 'button', + disabled = false, + onclick, + href + }: Props = $props(); + function invoke() { + if (!disabled && kind === 'button') onclick?.(); + } +</script> + +{#if kind === 'link' && navigationHref(href)} + <a + href={navigationHref(href)} + class="button" + class:button--primary={variant === 'primary'} + class:button--secondary={variant === 'secondary'}>{label}</a + > +{:else if kind === 'link'} + <span class="button">{label}</span> +{:else} + <button + {type} + {disabled} + onclick={invoke} + class="button" + class:button--primary={variant === 'primary'} + class:button--secondary={variant === 'secondary'}>{label}</button + > +{/if} diff --git a/web/src/lib/components/primitives/ConfirmPanel.svelte b/web/src/lib/components/primitives/ConfirmPanel.svelte @@ -0,0 +1,49 @@ +<script lang="ts"> + import Button from './Button.svelte'; + let { + id, + title, + impact, + confirmLabel, + cancelLabel, + onconfirm, + oncancel, + returnFocus, + pending = false + }: { + id: string; + title: string; + impact: string; + confirmLabel: string; + cancelLabel: string; + onconfirm: () => void; + oncancel: () => void; + returnFocus?: () => void; + pending?: boolean; + } = $props(); + function cancel() { + oncancel(); + returnFocus?.(); + } + function confirm() { + if (!pending) onconfirm(); + } +</script> + +<section + class="notice stack" + aria-labelledby={`${id}-title`} + aria-describedby={`${id}-impact`} +> + <h2 id={`${id}-title`}>{title}</h2> + <p id={`${id}-impact`}>{impact}</p> + <div class="cluster"> + <Button label={cancelLabel} onclick={cancel} /> + <Button + label={confirmLabel} + variant="primary" + disabled={pending} + onclick={confirm} + /> + </div> +</section> diff --git a/web/src/lib/components/primitives/Disclosure.svelte b/web/src/lib/components/primitives/Disclosure.svelte @@ -0,0 +1,9 @@ +<script lang="ts"> + import type { Snippet } from 'svelte'; + let { summary, children }: { summary: string; children?: Snippet } = $props(); +</script> + +<details class="disclosure"> + <summary>{summary}</summary> + {#if children}<div class="stack">{@render children()}</div>{/if} +</details> diff --git a/web/src/lib/components/primitives/EmptyState.svelte b/web/src/lib/components/primitives/EmptyState.svelte @@ -0,0 +1,14 @@ +<script lang="ts"> + import type { Snippet } from 'svelte'; + let { + title, + description, + children + }: { title: string; description: string; children?: Snippet } = $props(); +</script> + +<section class="stack"> + <h2>{title}</h2> + <p>{description}</p> + {#if children}{@render children()}{/if} +</section> diff --git a/web/src/lib/components/primitives/FormField.svelte b/web/src/lib/components/primitives/FormField.svelte @@ -0,0 +1,34 @@ +<script lang="ts"> + import type { Snippet } from 'svelte'; + let { + id, + label, + hint, + error, + control + }: { + id: string; + label: string; + hint?: string; + error?: string; + control: Snippet< + [{ id: string; describedby: string | undefined; invalid: boolean }] + >; + } = $props(); + const describedby = $derived( + [hint ? `${id}-hint` : '', error ? `${id}-error` : ''] + .filter(Boolean) + .join(' ') || undefined + ); +</script> + +<div class="field"> + <label class="label" for={id}>{label}</label> + {#if hint}<p class="text-small text-muted" id={`${id}-hint`}>{hint}</p>{/if} + {#if error}<p class="text-error" id={`${id}-error`}>{error}</p>{/if} + {@render control({ + id, + describedby, + invalid: Boolean(error) + })} +</div> diff --git a/web/src/lib/components/primitives/PageHeading.svelte b/web/src/lib/components/primitives/PageHeading.svelte @@ -0,0 +1,9 @@ +<script lang="ts"> + let { title, description }: { title: string; description?: string } = + $props(); +</script> + +<header class="stack"> + <h1>{title}</h1> + {#if description}<p>{description}</p>{/if} +</header> diff --git a/web/tests/e2e/harness/primitives.svelte b/web/tests/e2e/harness/primitives.svelte @@ -0,0 +1,81 @@ +<script lang="ts"> + import FormField from '../../../src/lib/components/primitives/FormField.svelte'; + import Button from '../../../src/lib/components/primitives/Button.svelte'; + import Disclosure from '../../../src/lib/components/primitives/Disclosure.svelte'; + import PageHeading from '../../../src/lib/components/primitives/PageHeading.svelte'; + import ActionGroup from '../../../src/lib/components/primitives/ActionGroup.svelte'; + import EmptyState from '../../../src/lib/components/primitives/EmptyState.svelte'; + import ConfirmPanel from '../../../src/lib/components/primitives/ConfirmPanel.svelte'; + let commands = $state(0); + let open = $state(false); + let pending = $state(false); + const reference = 'TEST_PUBLIC_REFERENCE_' + '0123456789abcdef'.repeat(32); +</script> + +<div class="page page--reading stack"> + <PageHeading + title="Primitive qualification fixture" + description="Trusted test presentation only" + /> + <FormField + id="terms" + label="Public terms" + hint="Describe the public offer" + error="Enter public terms" + > + {#snippet control({ id, describedby, invalid })} + <input + class="input" + {id} + aria-describedby={describedby} + aria-invalid={invalid} + value={reference} + /> + {/snippet} + </FormField> + <ActionGroup> + <Button + label="Fixture command" + variant="primary" + onclick={() => commands++} + /> + <Button label="Disabled command" disabled onclick={() => commands++} /> + <Button kind="link" href="#fixture-empty" label="Fixture navigation" /> + </ActionGroup> + <p role="status" aria-live="polite">Commands: {commands}</p> + <Disclosure summary="Public fixture details" + ><p class="key">{reference}</p></Disclosure + > + <div id="fixture-empty"> + <EmptyState + title="No fixture results" + description="Try another fixture query" + /> + </div> + <button + type="button" + class="button button--secondary" + id="fixture-review" + onclick={() => (open = true)}>Review discard</button + > + {#if open} + <ConfirmPanel + id="discard" + title="Discard this draft?" + impact="This removes this browser draft. Remote copies remain." + confirmLabel="Discard draft" + cancelLabel="Keep editing" + {pending} + onconfirm={() => { + commands++; + pending = true; + }} + oncancel={() => { + open = false; + pending = false; + }} + returnFocus={() => + globalThis.document.getElementById('fixture-review')?.focus()} + /> + {/if} +</div> diff --git a/web/tests/e2e/primitives.spec.ts b/web/tests/e2e/primitives.spec.ts @@ -0,0 +1,261 @@ +import { expect, test } from '@playwright/test'; +import { createHash } from 'node:crypto'; +import { execFileSync } from 'node:child_process'; +import { + cp, + mkdtemp, + readFile, + readdir, + rm, + writeFile +} from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { createStaticHarness } from '../integration/harness/static.ts'; + +// Isolated qualification clone: actual components compile into disposable output. +// The primary static payload and product route source are never overwritten. +const capsule = fileURLToPath(new URL('../../../', import.meta.url)); +let directory: string; +let server: Awaited<ReturnType<typeof createStaticHarness>>; +test.beforeAll(async () => { + test.setTimeout(120_000); + directory = await mkdtemp(path.join(tmpdir(), 'hcp013-components-')); + try { + const checkout = path.join(directory, 'checkout'); + execFileSync('git', [ + 'clone', + '--quiet', + '--no-hardlinks', + capsule, + checkout + ]); + for (const relative of [ + 'web/src/lib/components/primitives', + 'web/tests/unit/components/primitives.test.ts', + 'web/tests/e2e/primitives.spec.ts', + 'web/tests/e2e/harness/primitives.svelte', + 'web/tests/integration/harness/static.ts' + ]) + await cp(path.join(capsule, relative), path.join(checkout, relative), { + recursive: true + }); + const fixture = await readFile( + path.join(capsule, 'web/tests/e2e/harness/primitives.svelte'), + 'utf8' + ); + await writeFile( + path.join(checkout, 'web/src/routes/+page.svelte'), + fixture.replaceAll('../../../src/lib/', '../lib/') + ); + await cp( + path.join(capsule, 'web/node_modules'), + path.join(checkout, 'web/node_modules'), + { recursive: true, verbatimSymlinks: true } + ); + const sourceAudit = execFileSync( + process.execPath, + ['tools/check-source.mjs'], + { cwd: path.join(checkout, 'web') } + ).toString(); + const identities = []; + for (const name of [ + 'FormField', + 'Button', + 'Disclosure', + 'PageHeading', + 'ActionGroup', + 'EmptyState', + 'ConfirmPanel' + ]) { + const source = await readFile( + path.join( + checkout, + 'web/src/lib/components/primitives', + name + '.svelte' + ) + ); + identities.push({ + name, + sha256: createHash('sha256').update(source).digest('hex') + }); + } + execFileSync(process.execPath, ['tools/build-info.mjs'], { + cwd: path.join(checkout, 'web') + }); + const compiled = execFileSync( + 'corepack', + ['pnpm', 'exec', 'vite', 'build'], + { + cwd: path.join(checkout, 'web'), + stdio: 'pipe', + timeout: 90_000 + } + ); + async function payload( + directory: string, + prefix = '' + ): Promise<{ path: string; sha256: string }[]> { + const files = []; + for (const entry of await readdir(directory, { withFileTypes: true })) { + const relative = prefix + entry.name; + if (entry.isDirectory()) + files.push( + ...(await payload(path.join(directory, entry.name), relative + '/')) + ); + else + files.push({ + path: relative, + sha256: createHash('sha256') + .update(await readFile(path.join(directory, entry.name))) + .digest('hex') + }); + } + return files.sort((left, right) => left.path.localeCompare(right.path)); + } + console.log( + JSON.stringify({ + fixture: 'HCP013_TEST_ONLY_COMPILE', + identities, + sourceAudit, + fixtureSourceSha256: createHash('sha256').update(fixture).digest('hex'), + compiledRouteSha256: createHash('sha256') + .update( + await readFile(path.join(checkout, 'web/src/routes/+page.svelte')) + ) + .digest('hex'), + payload: await payload(path.join(checkout, 'web/build')), + compiled: compiled.toString(), + metadata: JSON.parse( + await readFile( + path.join(checkout, 'web/build/build-info.json'), + 'utf8' + ) + ) as unknown + }) + ); + server = await createStaticHarness({ + buildRoot: path.join(checkout, 'web/build') + }); + } catch (error) { + await rm(directory, { recursive: true, force: true }); + throw error; + } +}); +test.afterAll(async () => { + await server?.close(); + if (directory) await rm(directory, { recursive: true, force: true }); + if (server) + expect(server.state()).toEqual({ listening: false, childProcesses: 0 }); +}); + +for (const width of [320, 1024]) { + test(`actual primitives preserve labels, keyboard and safe return at ${width}px`, async ({ + browser + }) => { + const context = await browser.newContext({ + viewport: { width, height: 900 } + }); + const external: string[] = []; + try { + await context.route('**/*', (route) => { + if (new URL(route.request().url()).origin === server.url) + return route.continue(); + external.push(route.request().url()); + return route.abort(); + }); + const page = await context.newPage(); + await page.goto(server.url); + const input = page.getByLabel('Public terms', { exact: true }); + await expect(input).toHaveAttribute( + 'aria-describedby', + 'terms-hint terms-error' + ); + await expect(input).toHaveAttribute('aria-invalid', 'true'); + await expect(page.locator('#terms-error')).toHaveText( + 'Enter public terms' + ); + const errorBox = await page.locator('#terms-error').boundingBox(); + const inputBox = await input.boundingBox(); + expect(errorBox!.y + errorBox!.height).toBeLessThanOrEqual(inputBox!.y); + await input.focus(); + await page.keyboard.press('Tab'); + await expect( + page.getByRole('button', { name: 'Fixture command', exact: true }) + ).toBeFocused(); + await page.keyboard.press('Enter'); + await expect(page.getByRole('status')).toHaveText('Commands: 1'); + await expect( + page.getByRole('button', { name: 'Disabled command' }) + ).toBeDisabled(); + await page + .getByRole('button', { name: 'Disabled command' }) + .evaluate((element) => (element as HTMLButtonElement).click()); + await expect(page.getByRole('status')).toHaveText('Commands: 1'); + await page + .getByRole('button', { name: 'Disabled command' }) + .evaluate((element) => + element.dispatchEvent(new MouseEvent('click', { bubbles: true })) + ); + await expect(page.getByRole('status')).toHaveText('Commands: 1'); + await page.keyboard.press('Tab'); + await expect( + page.getByRole('link', { name: 'Fixture navigation' }) + ).toBeFocused(); + await page.keyboard.press('Tab'); + await expect(page.locator('summary')).toBeFocused(); + await page.keyboard.press('Enter'); + await expect(page.locator('details')).toHaveAttribute('open', ''); + await page.keyboard.press('Space'); + await expect(page.locator('details')).not.toHaveAttribute('open', ''); + await page.getByRole('button', { name: 'Review discard' }).click(); + await page.keyboard.press('Tab'); + await expect( + page.getByRole('button', { name: 'Keep editing' }) + ).toBeFocused(); + await expect( + page.getByRole('region', { name: 'Discard this draft?' }) + ).toContainText('Remote copies remain.'); + await page.keyboard.press('Enter'); + await expect( + page.getByRole('button', { name: 'Review discard' }) + ).toBeFocused(); + await expect( + page.getByRole('button', { name: 'Keep editing' }) + ).toHaveCount(0); + await page.keyboard.press('Enter'); + await page + .getByRole('button', { name: 'Discard draft', exact: true }) + .click(); + await expect(page.getByRole('status')).toHaveText('Commands: 2'); + await expect( + page.getByRole('button', { name: 'Discard draft', exact: true }) + ).toBeDisabled(); + await page.getByRole('button', { name: 'Keep editing' }).click(); + await expect( + page.getByRole('button', { name: 'Review discard' }) + ).toBeFocused(); + const measured = await page.evaluate(() => ({ + width: innerWidth, + scroll: document.documentElement.scrollWidth, + heights: Array.from( + document.querySelectorAll('input,button,a.button,summary') + ).map((element) => element.getBoundingClientRect().height) + })); + expect(measured.scroll).toBeLessThanOrEqual(measured.width); + for (const height of measured.heights) + expect(height).toBeGreaterThanOrEqual(44); + expect(external).toEqual([]); + console.log( + JSON.stringify({ + fixture: 'HCP013_ACTUAL_PRESENTATION_COMPONENTS_ONLY', + measured + }) + ); + } finally { + await context.close(); + } + expect(context.pages()).toHaveLength(0); + }); +} diff --git a/web/tests/integration/harness/static.ts b/web/tests/integration/harness/static.ts @@ -42,9 +42,12 @@ function acceptsHtml(accept: string) { }); } -export async function createStaticHarness() { +export async function createStaticHarness( + options: { buildRoot?: string } = {} +) { const root = await realpath( - fileURLToPath(new URL('../../../build/', import.meta.url)) + options.buildRoot ?? + fileURLToPath(new URL('../../../build/', import.meta.url)) ); const server = createServer((request, response) => { void (async () => { diff --git a/web/tests/unit/components/primitives.test.ts b/web/tests/unit/components/primitives.test.ts @@ -0,0 +1,99 @@ +import { render } from 'svelte/server'; +import { createRawSnippet } from 'svelte'; +import { describe, expect, it } from 'vitest'; +import FormField from '../../../src/lib/components/primitives/FormField.svelte'; +import Button from '../../../src/lib/components/primitives/Button.svelte'; +import Disclosure from '../../../src/lib/components/primitives/Disclosure.svelte'; +import PageHeading from '../../../src/lib/components/primitives/PageHeading.svelte'; +import ActionGroup from '../../../src/lib/components/primitives/ActionGroup.svelte'; +import EmptyState from '../../../src/lib/components/primitives/EmptyState.svelte'; +import ConfirmPanel from '../../../src/lib/components/primitives/ConfirmPanel.svelte'; + +describe('presentation primitives SSR', () => { + it('associates visible labels, hints and above-control errors', () => { + const output = render(FormField, { + props: { + id: 'terms', + label: 'Terms', + hint: 'Public terms', + error: 'Enter terms', + control: createRawSnippet< + [{ id: string; describedby: string | undefined; invalid: boolean }] + >((get) => ({ + render() { + const control = get(); + return `<input id="${control.id}" aria-describedby="${control.describedby}" aria-invalid="${control.invalid}">`; + } + })) + } + }).body; + expect(output).toContain('for="terms"'); + expect(output).toContain('id="terms-hint"'); + expect(output).toContain('id="terms-error"'); + expect(output.indexOf('Enter terms')).toBeLessThan( + output.indexOf('<input') + ); + expect(output).toContain('aria-describedby="terms-hint terms-error"'); + expect(output).toContain('aria-invalid="true"'); + }); + it('keeps safe button semantics and finite variants', () => { + const output = render(Button, { + props: { label: 'Save', disabled: true } + }).body; + expect(output).toContain('<button'); + expect(output).toContain('type="button"'); + expect(output).toContain('disabled'); + expect(output).not.toContain('<a'); + }); + it('validates actual navigation sinks even for untyped callers', () => { + for (const href of [ + '/search', + 'https://example.org/', + 'mailto:support@example.org' + ]) { + const output = render(Button, { + props: { kind: 'link', label: 'Help', href } + }).body; + expect(output).toContain('<a'); + expect(output).toContain(`href="${href}"`); + } + const output = render(Button, { + props: { kind: 'link', label: 'Invalid target', href: '//example.org' } + }).body; + expect(output).not.toContain('href='); + expect(output).not.toContain('<a'); + }); + it('uses native disclosure and semantic presentation', () => { + expect( + render(Disclosure, { props: { summary: 'Details' } }).body + ).toContain('<summary>Details</summary>'); + expect( + render(PageHeading, { + props: { title: 'Review', description: 'Check public terms' } + }).body + ).toContain('<h1>Review</h1>'); + expect(render(ActionGroup).body).toContain('class="cluster"'); + expect( + render(EmptyState, { + props: { title: 'No results', description: 'Try other terms' } + }).body + ).toContain('No results'); + }); + it('states specific impact and keeps an explicit safe exit', () => { + const output = render(ConfirmPanel, { + props: { + id: 'discard', + title: 'Discard draft?', + impact: 'This removes this browser draft. Remote copies remain.', + confirmLabel: 'Discard draft', + cancelLabel: 'Keep editing', + onconfirm: () => {}, + oncancel: () => {} + } + }).body; + expect(output).toContain('aria-labelledby="discard-title"'); + expect(output).toContain('Remote copies remain.'); + expect(output).toContain('Keep editing'); + expect(output).not.toContain('role="dialog"'); + }); +});