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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/deal-clock:mason/47-every-page-works-with-a-keyboard-and-a-s → main 2 commits fork 1 thread · 1 unresolved

  • Merged. mason/47-every-page-works-with-a-keyboard-and-a-s was merged into main as 2473546.

Review

Sign in to review this change.
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.
182182 who owes what, the reminder drafts and editing them, the record of what was
183183 sent, the reasons for messages you chose not to send, the calendar file, and adding parties, dates and deals.
184184 - **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.
185186 - **Simulated:** sending. Send records that a reminder went out and keeps the
186187 words that were approved; no email or text message leaves the app.
187188 - **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(/&nbsp;/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: {
7373 ${plain || input.live === false ? "" : `<script type="module" src="${asset("live.js")}"></script><script type="module" src="${asset("sheets.js")}"></script>`}
7474 <body${bodyClass === undefined ? "" : ` class="${escape(bodyClass)}"`}>
7575 <div class="page">
76 <a class="skip" href="#content">Skip to content</a>
7677 <header class="head">
7778 <a class="brand" href="/">
7879 <span class="brand-mark" aria-hidden="true"></span>
@@ -89,7 +90,8 @@ ${plain || input.live === false ? "" : `<script type="module" src="${asset("live
8990 </nav>`
9091 }
9192 </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>
9395 ${plain ? "" : `<footer class="muted">
9496 <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>
9597 ${ssh === undefined ? "<p>The terminal is off.</p>" : `<p>Terminal: <code>${escape(ssh)}</code></p>`}
static/app.css +22
@@ -76,6 +76,28 @@ code,
7676 outline: 2px solid var(--color-accent);
7777 outline-offset: 2px;
7878 }
79 .skip {
80 position: absolute;
81 left: var(--space-2);
82 top: var(--space-2);
83 transform: translateY(-200%);
84 padding: var(--space-2) var(--space-3);
85 background: var(--color-surface);
86 border: 1px solid var(--color-line);
87 border-radius: var(--radius-md);
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 }
79101 .muted {
80102 color: var(--color-muted);
81103 }
static/live.js +10
@@ -29,6 +29,15 @@ function connect() {
2929 };
3030 }
3131
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
3241 let refreshing = false;
3342 let again = false;
3443 async function refresh(types) {
@@ -55,6 +64,7 @@ async function refresh(types) {
5564 const next = fresh.getElementById(el.id);
5665 if (next) el.replaceWith(next);
5766 }
67 announce("Updated");
5868 } finally {
5969 refreshing = false;
6070 if (again) {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs