Public: anyone can read this; the crew can change it.
Every page works with a keyboard and a screen reader, and a test fails when a field loses its label or a page its heading #78
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/47-every-page-works-with-a-keyboard-and-a-s → main 2 commits fork 1 thread · 1 unresolved
5 files
changed +153
−1
README.md +1
| @@ -182,6 +182,7 @@ brief's, with a line in the log. The sample deals always use the brief's. | ||
| 182 | 182 | who owes what, the reminder drafts and editing them, the record of what was |
| 183 | 183 | sent, the reasons for messages you chose not to send, the calendar file, and adding parties, dates and deals. |
| 184 | 184 | - **Real:** the clock, a deal page and the client timeline are tested to answer in under 50 ms with 200 deals. |
| 185 | - **Real:** every page is checked for keyboard and screen-reader use: a skip link, labelled fields, named buttons and links, one heading outline. | |
| 185 | 186 | - **Simulated:** sending. Send records that a reminder went out and keeps the |
| 186 | 187 | words that were approved; no email or text message leaves the app. |
| 187 | 188 | - **Not in this prototype (phase two):** real email or text messages, |
src/a11y.test.ts added +117
| @@ -0,0 +1,117 @@ | ||
| 1 | /** Every page names its controls and its headings, and a keyboard reaches them: read from the rendered HTML. */ | |
| 2 | import { afterAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { forgetRationing } from "./security.ts"; | |
| 7 | import { serve } from "./server.ts"; | |
| 8 | import { sign } from "./who.ts"; | |
| 9 | ||
| 10 | const KEY = "a-key-only-the-forge-holds"; | |
| 11 | const server = serve({ port: 0, dataDir: mkdtempSync(join(tmpdir(), "app-a11y-")), identityKey: KEY }); | |
| 12 | const base = `http://${server.hostname}:${server.port}`; | |
| 13 | afterAll(() => server.stop(true)); | |
| 14 | ||
| 15 | const identity = `u1|alice|user|${Date.now() + 600_000}`; | |
| 16 | const alice = { "x-forge-identity": identity, "x-forge-signature": sign(identity, KEY) }; | |
| 17 | ||
| 18 | const attrs = (tag: string): Record<string, string> => { | |
| 19 | const found: Record<string, string> = {}; | |
| 20 | for (const m of tag.matchAll(/([\w:-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) | |
| 21 | if (m.index !== 0 || !/^<?\w+$/.test(m[0])) found[m[1]!.toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? ""; | |
| 22 | return found; | |
| 23 | }; | |
| 24 | const textOf = (html: string) => html.replace(/<(script|style)[\s\S]*?<\/\1>/g, "").replace(/<[^>]*>/g, "").replace(/ /g, " ").trim(); | |
| 25 | ||
| 26 | /** What is wrong with a page, as sentences; empty when it is fine. */ | |
| 27 | function problems(html: string): string[] { | |
| 28 | const out: string[] = []; | |
| 29 | if (!/<html[^>]*\slang="[a-z]/i.test(html)) out.push("html has no lang"); | |
| 30 | const levels = [...html.matchAll(/<h([1-6])[\s>]/g)].map((m) => Number(m[1])); | |
| 31 | const ones = levels.filter((l) => l === 1).length; | |
| 32 | if (ones !== 1) out.push(`${ones} h1 elements`); | |
| 33 | levels.forEach((l, i) => { | |
| 34 | if (l > (levels[i - 1] ?? 0) + 1 && i > 0) out.push(`heading level skips from h${levels[i - 1]} to h${l}`); | |
| 35 | }); | |
| 36 | ||
| 37 | const labelled = new Set([...html.matchAll(/<label\b([^>]*)>/g)].map((m) => attrs(m[1]!)["for"]).filter(Boolean)); | |
| 38 | const wrapped = [...html.matchAll(/<label\b[^>]*>([\s\S]*?)<\/label>/g)].map((m) => m[1]!); | |
| 39 | for (const m of html.matchAll(/<(input|select|textarea)\b([^>]*)>/g)) { | |
| 40 | const a = attrs(m[2]!); | |
| 41 | if (m[1] === "input" && a["type"]?.toLowerCase() === "hidden") continue; | |
| 42 | const named = | |
| 43 | (a["aria-label"] ?? "").trim() !== "" || | |
| 44 | (a["id"] !== undefined && labelled.has(a["id"])) || | |
| 45 | wrapped.some((inner) => inner.includes(m[0])); | |
| 46 | if (!named) out.push(`unlabelled ${m[1]}: ${m[0].slice(0, 80)}`); | |
| 47 | } | |
| 48 | ||
| 49 | for (const m of html.matchAll(/<(button|a)\b([^>]*)>([\s\S]*?)<\/\1>/g)) { | |
| 50 | const a = attrs(m[2]!); | |
| 51 | if (m[1] === "a" && a["href"] === undefined) continue; | |
| 52 | if ((a["aria-label"] ?? "").trim() === "" && textOf(m[3]!) === "") out.push(`nameless ${m[1]}: ${m[0].slice(0, 80)}`); | |
| 53 | } | |
| 54 | ||
| 55 | for (const m of html.matchAll(/\btabindex\s*=\s*"?(-?\d+)/g)) if (Number(m[1]) > 0) out.push(`tabindex ${m[1]}`); | |
| 56 | ||
| 57 | const seen = new Set<string>(); | |
| 58 | for (const m of html.matchAll(/<[a-z][^>]*?\sid\s*=\s*"?([^"\s>]+)/g)) { | |
| 59 | if (seen.has(m[1]!)) out.push(`duplicate id ${m[1]}`); | |
| 60 | seen.add(m[1]!); | |
| 61 | } | |
| 62 | return out; | |
| 63 | } | |
| 64 | ||
| 65 | const get = async (path: string, headers: Record<string, string> = alice) => (await fetch(`${base}${path}`, { headers })).text(); | |
| 66 | ||
| 67 | async function firstDealId(): Promise<number> { | |
| 68 | const deals = (await (await fetch(`${base}/api/deals`, { headers: alice })).json()) as { id: number }[]; | |
| 69 | return deals[0]!.id; | |
| 70 | } | |
| 71 | ||
| 72 | test("the parser sees what it should", () => { | |
| 73 | expect(problems('<html lang="en"><h1>a</h1><h3>b</h3><input id=x><button></button><a href="/"></a><div id=q></div><i id=q tabindex=2>')).toEqual([ | |
| 74 | "heading level skips from h1 to h3", | |
| 75 | "unlabelled input: <input id=x>", | |
| 76 | "nameless button: <button></button>", | |
| 77 | 'nameless a: <a href="/"></a>', | |
| 78 | "tabindex 2", | |
| 79 | "duplicate id q", | |
| 80 | ]); | |
| 81 | expect(problems('<html lang="en"><h1>a</h1><label for=x>X</label><input id=x><label>Y <select name=y></select></label><input type=hidden name=z><textarea aria-label="T"></textarea>')).toEqual([]); | |
| 82 | }); | |
| 83 | ||
| 84 | test("every page names its controls and headings, and the layout skips to the content", async () => { | |
| 85 | forgetRationing(); | |
| 86 | const id = await firstDealId(); | |
| 87 | const pages: [string, string][] = [ | |
| 88 | ["the clock", await get("/")], | |
| 89 | ["the clock with no match", await get("/?q=zzzznomatch")], | |
| 90 | ["a deal", await get(`/deals/${id}`)], | |
| 91 | ["the client timeline", await get(`/deals/${id}/timeline`)], | |
| 92 | ["new deal", await get("/deals/new")], | |
| 93 | ["people", await get("/people")], | |
| 94 | ["profile", await get("/profile")], | |
| 95 | ["review today's reminders", await get("/reminders/today")], | |
| 96 | ["a refused page", await get("/people", {})], | |
| 97 | ["the welcome page", await get("/", {})], | |
| 98 | ]; | |
| 99 | for (const [name, html] of pages) { | |
| 100 | expect({ name, problems: problems(html) }).toEqual({ name, problems: [] }); | |
| 101 | const skip = html.match(/<body[^>]*>\s*<div[^>]*>\s*<a class="skip" href="#([^"]+)"/); | |
| 102 | expect(skip, `${name} starts with a skip link`).not.toBeNull(); | |
| 103 | expect(html).toMatch(new RegExp(`<main id="${skip![1]}"`)); | |
| 104 | } | |
| 105 | }); | |
| 106 | ||
| 107 | test("live changes are announced from a region that is never swapped out", async () => { | |
| 108 | const html = await get("/"); | |
| 109 | const live = [...html.matchAll(/<[a-z]+\b[^>]*\bdata-live=[^>]*>/g)].map((m) => m[0]); | |
| 110 | expect(live.length).toBeGreaterThan(0); | |
| 111 | // The swapped regions are replaced wholesale, so none of them may be the live region. | |
| 112 | for (const tag of live) expect(tag).not.toContain("aria-live"); | |
| 113 | expect(html).toMatch(/<div id="live-status"[^>]*role="status"[^>]*aria-live="polite"/); | |
| 114 | const script = await Bun.file(join(import.meta.dir, "../static/live.js")).text(); | |
| 115 | expect(script).toContain('getElementById("live-status")'); | |
| 116 | expect(script).not.toMatch(/\.focus\(/); | |
| 117 | }); |
src/pages/layout.ts +3 −1
| @@ -73,6 +73,7 @@ export function layout(input: { | ||
| 73 | 73 | ${plain || input.live === false ? "" : `<script type="module" src="${asset("live.js")}"></script><script type="module" src="${asset("sheets.js")}"></script>`} |
| 74 | 74 | <body${bodyClass === undefined ? "" : ` class="${escape(bodyClass)}"`}> |
| 75 | 75 | <div class="page"> |
| 76 | <a class="skip" href="#content">Skip to content</a> | |
| 76 | 77 | <header class="head"> |
| 77 | 78 | <a class="brand" href="/"> |
| 78 | 79 | <span class="brand-mark" aria-hidden="true"></span> |
| @@ -89,7 +90,8 @@ ${plain || input.live === false ? "" : `<script type="module" src="${asset("live | ||
| 89 | 90 | </nav>` |
| 90 | 91 | } |
| 91 | 92 | </header> |
| 92 | <main>${body}</main> | |
| 93 | ${plain || input.live === false ? "" : '<div id="live-status" class="visually-hidden" role="status" aria-live="polite"></div>'} | |
| 94 | <main id="content">${body}</main> | |
| 93 | 95 | ${plain ? "" : `<footer class="muted"> |
| 94 | 96 | <p>${escape(title)}${commit ? ` <span class="mono">${escape(commit)}</span>` : ""} — Send records your approval and opens your own Mail or Messages with the words. Nothing is sent by the app itself.</p> |
| 95 | 97 | ${ssh === undefined ? "<p>The terminal is off.</p>" : `<p>Terminal: <code>${escape(ssh)}</code></p>`} |
static/app.css +22
| @@ -76,6 +76,28 @@ code, | ||
| 76 | 76 | outline: 2px solid var(); |
| 77 | 77 | outline-offset: 2px; |
| 78 | 78 | } |
| 79 | .skip { | |
| 80 | position: absolute; | |
| 81 | left: var(); | |
| 82 | top: var(); | |
| 83 | transform: translateY(-200%); | |
| 84 | padding: var() var(); | |
| 85 | background: var(); | |
| 86 | border: 1px solid var(); | |
| 87 | border-radius: var(); | |
| 88 | z-index: 10; | |
| 89 | } | |
| 90 | .skip:focus { | |
| 91 | transform: none; | |
| 92 | } | |
| 93 | .visually-hidden { | |
| 94 | position: absolute; | |
| 95 | width: 1px; | |
| 96 | height: 1px; | |
| 97 | overflow: hidden; | |
| 98 | clip-path: inset(50%); | |
| 99 | white-space: nowrap; | |
| 100 | } | |
| 79 | 101 | .muted { |
| 80 | 102 | color: var(); |
| 81 | 103 | } |
static/live.js +10
| @@ -29,6 +29,15 @@ function connect() { | ||
| 29 | 29 | }; |
| 30 | 30 | } |
| 31 | 31 | |
| 32 | // The regions are swapped for new nodes, which a screen reader may not | |
| 33 | // announce; this one element stays, so a change written into it is read out. | |
| 34 | function announce(text) { | |
| 35 | const status = document.getElementById("live-status"); | |
| 36 | if (!status) return; | |
| 37 | status.textContent = ""; | |
| 38 | requestAnimationFrame(() => (status.textContent = text)); | |
| 39 | } | |
| 40 | ||
| 32 | 41 | let refreshing = false; |
| 33 | 42 | let again = false; |
| 34 | 43 | async function refresh(types) { |
| @@ -55,6 +64,7 @@ async function refresh(types) { | ||
| 55 | 64 | const next = fresh.getElementById(el.id); |
| 56 | 65 | if (next) el.replaceWith(next); |
| 57 | 66 | } |
| 67 | announce("Updated"); | |
| 58 | 68 | } finally { |
| 59 | 69 | refreshing = false; |
| 60 | 70 | if (again) { |
new above
offline