feat: accessible output HTML for friendlyExplain

Restructure of `result.html` output with WCAG 2.1 AA in mind

Author: grega

README.md

@@ -1,8 +1,5 @@
 # Python Friendly Error Messages
 
-Todo:
-- Accessibility of output HTML
-
 A small library that explains Python error messages in a friendlier way, inspired by [p5.js's Friendly Error System](https://p5js.org/contribute/friendly_error_system/).
 
 It can be used in browser-based editors (like RPF's [Code Editor web component](https://github.com/RaspberryPiFoundation/editor-ui)) or any environment that executes Python code through Pyodide or Skulpt.
@@ -69,6 +66,23 @@ const result = friendlyExplain({
 
 See the [demo](docs/README.md) for a full set of examples.
 
+## Accessibility
+
+`result.html` is built to be accessible by default (with WCAG 2.1 AA in mind):
+
+- The whole explanation is one labelled group — `<div class="pfem" role="group" lang="…" aria-labelledby="…">`, named by its title, with `lang` taken from the copydeck so screen readers pronounce localised copy correctly (`3.1.2 Language of Parts`). `role="group"` (not a landmark) keeps things uncluttered when several explanations render on one page
+- The title is deliberately not a heading. Heading level depends on the surrounding page outline, which a library can't know, so the title supplies the group's accessible name instead. If you want it in your heading outline, render your own heading from `result.title` and use `result.html` (or the structured fields) for the body
+- Code is marked up as code; inline tokens use `<code>` and blocks use `<pre><code>`
+- The suggested fix has a visible "Suggested fix" label; the original traceback stays in a native `<details>`/`<summary>`
+- Element ids are randomised per call so `aria-labelledby` remains unambiguous when multiple explanations coexist on a page
+
+### Your responsibilities
+
+A couple of WCAG 2.1AA requirements can only be met by the host app:
+
+- Announce it: the explanation appears in response to running code. For a screen reader to announce it without stealing focus, insert it into a pre-existing live region (`aria-live="polite"` / `role="status"`) that is already in the DOM, or move focus to it
+- Contrast & colour: all styling is yours, ensure text contrast, and don't rely on colours (`.pfem__var`, `.pfem__file`, …) alone to convey meaning
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.

copydecks/en/copydeck.json

@@ -28,7 +28,8 @@
     "thisFile": "this file",
     "originalError": "Original error",
     "error": "Error",
-    "copydeckNotLoaded": "Copydeck not loaded"
+    "copydeckNotLoaded": "Copydeck not loaded",
+    "suggestedFix": "Suggested fix"
   },
   "errors": {
     "NameError": {

src/engine.ts

@@ -14,6 +14,9 @@ const getUiString = (key: keyof NonNullable<CopyDeck["ui"]>, fallback: string):
   return state.copy?.ui?.[key] || fallback;
 };
 
+// Short non-cryptographic id, unique enough to keep aria-labelledby references distinct when several explanations are rendered on the same page
+const uniqueId = () => `pfem-${Math.random().toString(36).slice(2, 8)}`;
+
 export const registerAdapter = (name: string, fn: (raw: string, code?: string) => Trace | null) =>
   (state.adapters[name] = fn);
 
@@ -31,11 +34,9 @@ const coerceTrace = (input: string | Error | Trace, code?: string, runtime?: str
 
   const raw = typeof input === "string" ? input : String((input as Error).stack || (input as Error).message || input);
   const parsed = adapter(raw, code);
-  // The error could not be parsed into a structured trace, so there is no friendly
-  // explanation to offer. Return null and let the caller fall back to the raw error.
+  // The error could not be parsed into a structured trace, so there is no friendly explanation to offer. Return null and let the caller fall back to the raw error
   if (!parsed) return null;
-  // The runtime-agnostic adapter leaves `runtime: "unknown"`; this adds the concrete
-  // runtime we dispatched on so the trace carries the correct label
+  // The runtime-agnostic adapter leaves `runtime: "unknown"`; this adds the concrete runtime we dispatched on so the trace carries the correct label
   parsed.runtime = runtime as Runtime;
   return parsed;
 };
@@ -74,15 +75,15 @@ const pickVariant = (trace: Trace, code: string | undefined, sections?: Section[
   };
 
   const linePart = trace.line ? `<span class="pfem__line">${escapeHtml(lineStr)} ${escapeHtml(String(trace.line))}</span>` : null;
-  const filePart = trace.file ? `<span class="pfem__file">${escapeHtml(trace.file)}</span>` : null;
+  const filePart = trace.file ? `<code class="pfem__file">${escapeHtml(trace.file)}</code>` : null;
   const htmlLoc =
     linePart && filePart ? `${linePart} ${escapeHtml(inStr)} ${filePart}` :
     linePart ?? filePart ?? escapeHtml(thisFileStr);
 
   const htmlTransforms: Record<string, (v: string) => string> = {
-    name:     (v) => `<span class="pfem__var">${escapeHtml(v)}</span>`,
+    name:     (v) => `<code class="pfem__var">${escapeHtml(v)}</code>`,
     loc:      (_) => htmlLoc,
-    codeLine: (v) => `<span class="pfem__code">${escapeHtml(v)}</span>`,
+    codeLine: (v) => `<code class="pfem__code">${escapeHtml(v)}</code>`,
   };
 
   for (let i = 0; i < entry.variants.length; i++) {
@@ -115,17 +116,23 @@ const pickVariant = (trace: Trace, code: string | undefined, sections?: Section[
     }
 
     const has = (s: Section) => !sections || sections.includes(s);
-    const html = [
-      has("title")   ? `<div class="pfem__title">${titleHtml}</div>` : "",
-      has("summary") ? `<div class="pfem__summary">${summaryHtml}</div>` : "",
-      has("why")     && whyHtml ? `<div class="pfem__why">${whyHtml}</div>` : "",
+    const id = uniqueId();
+    const lang = deck?.meta.language ?? "en";
+    const inner = [
+      has("title")   ? `<p class="pfem__title" id="${id}-title">${titleHtml}</p>` : "",
+      has("summary") ? `<p class="pfem__summary">${summaryHtml}</p>` : "",
+      has("why")     && whyHtml ? `<p class="pfem__why">${whyHtml}</p>` : "",
       has("steps")   && stepsHtml?.length ? `<ul class="pfem__steps">${stepsHtml.map((s) => `<li>${s}</li>`).join("")}</ul>` : "",
-      has("patch")   && patch ? `<pre class="pfem__patch">${escapeHtml(patch)}</pre>` : "",
-      has("details") ? `<details class="pfem__details"><summary>${escapeHtml(getUiString("originalError", "Original error"))}</summary><pre>${escapeHtml(
+      has("patch")   && patch ? `<div class="pfem__patch"><p class="pfem__patch-label">${escapeHtml(getUiString("suggestedFix", "Suggested fix"))}</p><pre class="pfem__patch-code"><code>${escapeHtml(patch)}</code></pre></div>` : "",
+      has("details") ? `<details class="pfem__details"><summary>${escapeHtml(getUiString("originalError", "Original error"))}</summary><pre><code>${escapeHtml(
         (trace.type || getUiString("error", "Error")) + ": " + trace.message
-      )}</pre></details>` : "",
+      )}</code></pre></details>` : "",
     ].filter(Boolean).join("\n");
 
+    // Wrap in a single labelled group so a screen reader perceives one explanation as a named unit
+    const labelledBy = has("title") ? ` aria-labelledby="${id}-title"` : "";
+    const html = `<div class="pfem" role="group" lang="${escapeHtml(lang)}"${labelledBy}>\n${inner}\n</div>`;
+
     return {
       variantId: `${kind}/variants/${i}`,
       title,
@@ -145,17 +152,15 @@ export const friendlyExplain = (opts: ExplainOptions): ExplainResult | null => {
   const code = opts.code;
 
   const trace = coerceTrace(opts.error, code, opts.runtime);
-  // The error could not be parsed — no friendly explanation; caller uses the raw error.
+  // The error could not be parsed — no friendly explanation; caller uses the raw error
   if (!trace) return null;
 
   // Caller-provided file/line take precedence over whatever was parsed from the trace
-  // Useful when the traceback's innermost frame references an internal file (eg.
-  // Pyodide's "<exec>") instead of the user's filename, or when the line needs correcting.
+  // Useful when the traceback's innermost frame references an internal file (eg. Pyodide's "<exec>") instead of the user's filename, or when the line needs correcting
   if (opts.file !== undefined) trace.file = opts.file;
   if (opts.line !== undefined) trace.line = opts.line;
 
-  // (Re)derive the code context from the effective line: when the caller overrides the
-  // line, or when a pre-parsed trace arrived without a codeLine.
+  // (Re)derive the code context from the effective line: when the caller overrides the line, or when a pre-parsed trace arrived without a codeLine
   if (code && trace.line && (opts.line !== undefined || !trace.codeLine)) {
     const lines = code.split(/\r?\n/);
     trace.codeLine = lines[trace.line - 1]?.trim();
@@ -164,8 +169,7 @@ export const friendlyExplain = (opts: ExplainOptions): ExplainResult | null => {
   }
 
   const chosen = pickVariant(trace, code, opts.sections);
-  // No copydeck entry/variant matched this error. Return null so the caller can fall
-  // back to showing the raw Python/Pyodide error as-is, rather than synthetic copy.
+  // No copydeck entry/variant matched this error. Return null so the caller can fall back to showing the raw Python/Pyodide error as-is
   if (!chosen) return null;
 
   return { trace, ...chosen };

src/types.ts

@@ -71,6 +71,7 @@ export type CopyDeck = {
     originalError?: string;
     error?: string;
     copydeckNotLoaded?: string;
+    suggestedFix?: string;
   };
 };
 

tests/engine.test.ts

@@ -141,23 +141,41 @@ NameError: name 'kittens' is not defined`;
     res.steps?.forEach((s) => expect(s).not.toMatch(/<[^>]+>/));
   });
 
-  it("html output wraps {{name}} in pfem__var span", () => {
+  it("html output wraps {{name}} in a pfem__var <code> element", () => {
     const code = `print("Hello")\nprint(kittens)\n`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 2, in <module>
 NameError: name 'kittens' is not defined`;
     const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
-    expect(res.html).toContain('<span class="pfem__var">kittens</span>');
+    expect(res!.html).toContain('<code class="pfem__var">kittens</code>');
   });
 
-  it("html output wraps {{loc}} line and file in separate spans", () => {
+  it("html output wraps {{loc}} line (span) and file (code)", () => {
     const code = `print("Hello")\nprint(kittens)\n`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 2, in <module>
 NameError: name 'kittens' is not defined`;
     const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
-    expect(res.html).toContain('<span class="pfem__line">');
-    expect(res.html).toContain('<span class="pfem__file">main.py</span>');
+    expect(res!.html).toContain('<span class="pfem__line">');
+    expect(res!.html).toContain('<code class="pfem__file">main.py</code>');
+  });
+
+  it("wraps output in a labelled group with a unique id and lang", () => {
+    const code = `print("Hello")\nprint(kittens)\n`;
+    const raw = `Traceback (most recent call last):
+  File "main.py", line 2, in <module>
+NameError: name 'kittens' is not defined`;
+    const a = friendlyExplain({ error: raw, code, runtime: "skulpt" })!;
+    const b = friendlyExplain({ error: raw, code, runtime: "skulpt" })!;
+
+    // group wrapper with lang and an aria-labelledby pointing at the title's id
+    expect(a.html).toMatch(/^<div class="pfem" role="group" lang="en" aria-labelledby="pfem-[a-z0-9]+-title">/);
+    const titleId = a.html!.match(/aria-labelledby="(pfem-[a-z0-9]+-title)"/)![1];
+    expect(a.html).toContain(`<p class="pfem__title" id="${titleId}">`);
+
+    // ids differ between calls so multiple explanations on a page don't collide
+    const idOf = (h: string) => h.match(/aria-labelledby="(pfem-[a-z0-9]+-title)"/)![1];
+    expect(idOf(a.html!)).not.toBe(idOf(b.html!));
   });
 
   it("sections option limits html output to specified sections", () => {