automatica11y 0.3.2 → 0.4.0

package/src/tiers/interactions/helpers.js

@@ -12,6 +12,28 @@ export function installHelpers() {
     return uids.get(el);
   };
 
+  const FOCUS_PROPS = ["outlineStyle", "outlineWidth", "outlineColor", "boxShadow", "borderTopStyle", "borderTopColor", "borderTopWidth", "backgroundColor", "color", "textDecorationLine"];
+  const snapshotOf = (el) => {
+    if (!el) return null;
+    const read = (node, pseudo) => {
+      const s = getComputedStyle(node, pseudo);
+      if (pseudo && (s.content === "none" || s.content === "normal")) return null;
+      const box = node.getBoundingClientRect();
+      return { ...Object.fromEntries(FOCUS_PROPS.map((key) => [key, s[key]])), rendered: s.display !== "none" && s.visibility !== "hidden" && Number(s.opacity) > 0 && box.width > 0 && box.height > 0 };
+    };
+    const parts = {};
+    const add = (key, node, pseudo) => {
+      const part = read(node, pseudo);
+      if (part) parts[key] = part;
+    };
+    add("the element", el);
+    add("its ::before", el, "::before");
+    add("its ::after", el, "::after");
+    [...el.querySelectorAll("*")].slice(0, 30).forEach((child, index) => add(`inner element ${index + 1} (${child.tagName.toLowerCase()})`, child));
+    const box = el.getBoundingClientRect();
+    return { parts, box: { x: box.x, y: box.y, width: box.width, height: box.height } };
+  };
+
   /** All matches in the document and in every open shadow root. */
   const queryAllDeep = (selector, root = /** @type {Document | ShadowRoot} */ (document)) => {
     const found = [...root.querySelectorAll(selector)];
@@ -41,6 +63,21 @@ export function installHelpers() {
   const byId = (el, id) => (el.getRootNode().getElementById ? el.getRootNode().getElementById(id) : document.getElementById(id));
   const text = (el) => (el?.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 80);
 
+  /** The text a person sees in an element, following slots to the text assigned to them. */
+  const flatText = (el) => {
+    if (!el) return "";
+    let out = "";
+    const walk = (node) => {
+      if (node.nodeType === 3) out += node.nodeValue;
+      else if (node.nodeType === 1 && node.localName === "slot") {
+        const assigned = node.assignedNodes({ flatten: true });
+        (assigned.length ? assigned : [...node.childNodes]).forEach(walk);
+      } else if (node.nodeType === 1) node.childNodes.forEach(walk);
+    };
+    walk(el);
+    return out.trim().replace(/\s+/g, " ").slice(0, 80);
+  };
+
   /** The element ARIA says is active: the focused element, or the descendant it points to. */
   const activeTarget = () => {
     const active = deepActive();
@@ -49,6 +86,20 @@ export function installHelpers() {
     return (pointed && byId(active, pointed)) || active;
   };
 
+  const LIVE_ROLES = { alert: "assertive", status: "polite", log: "polite", marquee: "off", timer: "off" };
+  /** How a live region announces: its aria-live value if it has a valid one, otherwise what its role implies. */
+  const politeness = (el) => {
+    const set = (el.getAttribute("aria-live") ?? "").trim().toLowerCase();
+    if (["off", "polite", "assertive"].includes(set)) return set;
+    return LIVE_ROLES[el.getAttribute("role") ?? ""] ?? "off";
+  };
+  const isLiveElement = (el) => Object.hasOwn(LIVE_ROLES, el.getAttribute("role") ?? "") || el.hasAttribute("aria-live");
+  /** The closest element, from `el` upward, that is a live region or has an aria-live attribute. */
+  const liveRegionOf = (el) => {
+    for (let node = el; node; node = node.assignedSlot || node.parentElement || node.getRootNode?.().host) if (node.nodeType === 1 && isLiveElement(node)) return node;
+    return null;
+  };
+
   window.__a11yClicks = 0;
   document.addEventListener("click", () => (window.__a11yClicks += 1), true);
 
@@ -94,6 +145,33 @@ export function installHelpers() {
         visible: visible(el),
       }));
     },
+    /** The message (data-a11y-root) and the live region it sits in, as they are right now. */
+    live() {
+      const root = queryDeep("[data-a11y-root]");
+      let region = root ? liveRegionOf(root) : null;
+      // A web component can keep the role on a wrapper inside its shadow root, around a slot that shows the message.
+      if (!region && root?.shadowRoot) region = [...root.shadowRoot.querySelectorAll("[role], [aria-live]")].find((el) => isLiveElement(el) && el.querySelector("slot")) ?? null;
+      const chain = [];
+      for (let node = root; node && chain.length < 200; node = node.assignedSlot || node.parentElement || node.getRootNode?.().host) chain.push(uid(node));
+      return {
+        /** The message and everything above it, so a later check can tell whether the region's element was already in the page. */
+        ancestorUids: chain,
+        present: Boolean(root),
+        visible: visible(root),
+        text: flatText(root),
+        named: Boolean(root && (root.getAttribute("aria-label") || root.getAttribute("aria-labelledby"))),
+        region: region ? { uid: uid(region), role: region.getAttribute("role"), ariaLive: region.getAttribute("aria-live"), politeness: politeness(region), isMessage: region === root } : null,
+        regionUids: queryAllDeep("[role], [aria-live]").filter(isLiveElement).map(uid),
+      };
+    },
+    /** Move focus to the first control inside the message, such as a dismiss button. Returns what it found. */
+    focusDismiss() {
+      const root = queryDeep("[data-a11y-root]");
+      const control = root ? [...root.querySelectorAll('button, a[href], input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])')].find(visible) : null;
+      if (!control) return { found: false };
+      control.focus();
+      return { found: true, tag: control.localName, label: text(control) || control.getAttribute("aria-label") || "" };
+    },
     /** The name a control gets from its label, in the order browsers use. */
     nameSources() {
       const control = queryDeep("[data-a11y-trigger]");
@@ -116,26 +194,19 @@ export function installHelpers() {
       const live = [...root.querySelectorAll('[role="alert"], [aria-live="assertive"], [aria-live="polite"], [role="status"]')].map(text).filter(Boolean);
       return { invalid: control.getAttribute("aria-invalid") === "true" || control.matches(":invalid"), ariaInvalid: control.getAttribute("aria-invalid") === "true", linked, live };
     },
-    /** Computed style properties that can show a focus indicator. */
-    focusStyle() {
-      const el = deepActive();
-      if (!el) return null;
-      const s = getComputedStyle(el);
-      const pick = ["outlineStyle", "outlineWidth", "outlineColor", "outlineOffset", "boxShadow", "borderTopColor", "borderTopWidth", "backgroundColor", "color", "textDecorationLine"];
-      const style = Object.fromEntries(pick.map((key) => [key, s[key]]));
-      const box = el.getBoundingClientRect();
-      return { style, box: { x: box.x, y: box.y, width: box.width, height: box.height } };
+    /**
+     * The resolved styles that can show a focus indicator, for the focused element, its ::before and ::after,
+     * and the elements inside it (a library may draw its ring on a child, such as a ripple).
+     */
+    focusSnapshot() {
+      return snapshotOf(deepActive());
     },
-    /** Remember the focused element, so its style can be read after it loses focus. */
+    /** Remember the focused element, so its snapshot can be taken after it loses focus. */
     remember() {
       window.__a11yLast = deepActive();
     },
-    lastStyle() {
-      const el = window.__a11yLast;
-      if (!el) return null;
-      const s = getComputedStyle(el);
-      const pick = ["outlineStyle", "outlineWidth", "outlineColor", "outlineOffset", "boxShadow", "borderTopColor", "borderTopWidth", "backgroundColor", "color", "textDecorationLine"];
-      return Object.fromEntries(pick.map((key) => [key, s[key]]));
+    lastSnapshot() {
+      return snapshotOf(window.__a11yLast);
     },
     inputValue() {
       const el = queryDeep("[data-a11y-trigger]");

package/src/tiers/interactions/index.js

@@ -7,7 +7,7 @@ const CHECK_TIMEOUT_MS = 25_000;
 const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
 
 /** Everything a check can do, bound to one fresh page. */
-function makeContext(page) {
+export function makeContext(page) {
   const ctx = {
     page,
     trigger: page.locator("[data-a11y-trigger]").first(),
@@ -66,13 +66,25 @@ function makeContext(page) {
 }
 
 /** Run one check on a fresh page, so no check inherits another's state. */
-export async function runCheck(browser, url, check, { timeoutMs = CHECK_TIMEOUT_MS } = {}) {
+export async function runCheck(browser, url, check, { timeoutMs = CHECK_TIMEOUT_MS, kits = [installHelpers], needsTrigger = true, waitUntil = /** @type {"load" | "networkidle"} */ ("load") } = {}) {
   /** @type {Awaited<ReturnType<typeof openPage>> | null} */
   let opened = null;
+  /** @type {Array<Awaited<ReturnType<typeof openPage>>>} */
+  const variants = [];
+  const beforeGoto = async (page) => { for (const kit of kits) await page.addInitScript(kit); };
   try {
-    opened = await openPage(browser, url, { beforeGoto: (page) => page.addInitScript(installHelpers), waitUntil: "load" });
+    opened = await openPage(browser, url, { beforeGoto, waitUntil });
     const ctx = makeContext(opened.page);
-    await ctx.trigger.waitFor({ state: "attached", timeout: 3000 });
+    /**
+     * Open the same page again with other browser settings (reduced motion, dark mode, a narrow window), and get a context for it.
+     * It closes with the check.
+     */
+    ctx.variant = async (options) => {
+      const other = await openPage(browser, url, { ...options, beforeGoto, waitUntil });
+      variants.push(other);
+      return makeContext(other.page);
+    };
+    if (needsTrigger) await ctx.trigger.waitFor({ state: "attached", timeout: 3000 });
     const outcome = await Promise.race([
       check.run(ctx),
       new Promise((_, reject) => setTimeout(() => reject(new Error(`The check took longer than ${timeoutMs / 1000} seconds.`)), timeoutMs)),
@@ -82,6 +94,7 @@ export async function runCheck(browser, url, check, { timeoutMs = CHECK_TIMEOUT_
     return { name: check.name, criteria: check.criteria, result: "error", detail: `The check couldn't finish: ${(error instanceof Error ? error.message : String(error)).split("\n")[0]}` };
   } finally {
     await opened?.close();
+    for (const other of variants) await other.close();
   }
 }
 

package/src/tiers/rules/axe.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { criterionFromDigits } from "../../wcag/index.js";
 
 const require = createRequire(import.meta.url);
 let axeSource = null;
@@ -27,10 +28,10 @@ export function axeTags(wcag, level) {
   return tags;
 }
 
-/** `wcag143` becomes `1.4.3`. Returns null for tags that aren't success criteria. */
+/** `wcag143` becomes `1.4.3`, using the W3C's list of criteria. Returns null for tags that aren't success criteria. */
 function criterionFromTag(tag) {
-  const match = /^wcag(\d)(\d)(\d{1,2})$/.exec(tag);
-  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+  const match = /^wcag(\d{3,4})$/.exec(tag);
+  return match ? (criterionFromDigits(match[1])?.num ?? null) : null;
 }
 
 /** An axe target can be nested for iframes and shadow roots. Flatten it to one readable selector. */

package/src/wcag/index.js

@@ -0,0 +1,83 @@
+/**
+ * WCAG success criteria, read from the W3C's own published JSON (src/data/wcag-2.2.json, unmodified).
+ * Criterion numbers, names, levels, and versions all come from that file. Nothing here is typed in by hand.
+ * The links are built from each criterion's `id` and are ours, not the W3C's data.
+ *
+ * Source: Web Content Accessibility Guidelines (WCAG) 2.2, https://www.w3.org/TR/WCAG22/
+ * Terms of use: https://github.com/w3c/wcag/blob/main/11ty/json/README.md
+ */
+import { readFileSync } from "node:fs";
+
+const DATA = new URL("../data/wcag-2.2.json", import.meta.url);
+const SOURCE = new URL("../data/wcag-2.2.source.json", import.meta.url);
+
+/** @typedef {{ num: string, id: string, handle: string, level: "A" | "AA" | "AAA", versions: string[], url: string, understandingUrl: string }} Criterion */
+
+/** @type {Map<string, Criterion> | null} */
+let index = null;
+
+function load() {
+  if (index) return index;
+  const data = JSON.parse(readFileSync(DATA, "utf8"));
+  index = new Map();
+  for (const principle of data.principles) {
+    for (const guideline of principle.guidelines) {
+      for (const sc of guideline.successcriteria) {
+        index.set(sc.num, {
+          num: sc.num,
+          id: sc.id,
+          handle: sc.handle,
+          level: sc.level,
+          versions: sc.versions,
+          url: `https://www.w3.org/TR/WCAG22/#${sc.id}`,
+          understandingUrl: `https://www.w3.org/WAI/WCAG22/Understanding/${sc.id}`,
+        });
+      }
+    }
+  }
+  return index;
+}
+
+/** The criterion with this number, such as `1.4.3`, or null when WCAG 2.2 has no such criterion. */
+export function criterion(num) {
+  return load().get(num) ?? null;
+}
+
+/** The criterion for a number written without dots, the way axe-core tags it: `1410` is 1.4.10. Null when none matches. */
+export function criterionFromDigits(digits) {
+  for (const c of load().values()) if (c.num.replaceAll(".", "") === digits) return c;
+  return null;
+}
+
+/** Every criterion, in the W3C's order. */
+export function allCriteria() {
+  return [...load().values()];
+}
+
+/** True when the criterion is part of this WCAG version (`2.0`, `2.1`, or `2.2`). */
+export function inVersion(num, version) {
+  return criterion(num)?.versions.includes(version) ?? false;
+}
+
+/** "1.4.3 Contrast (Minimum)", or just the number when the W3C data doesn't know it. */
+export function criterionName(num) {
+  const c = criterion(num);
+  return c ? `${c.num} ${c.handle}` : num;
+}
+
+/** "WCAG 2.4.13 Focus Appearance (level AAA)" for use in a sentence. */
+export function criterionRef(num) {
+  const c = criterion(num);
+  return c ? `WCAG ${c.num} ${c.handle} (level ${c.level})` : `WCAG ${num}`;
+}
+
+/** Where the data came from and when it was downloaded, for the report's attribution line. */
+export function wcagSource() {
+  return JSON.parse(readFileSync(SOURCE, "utf8"));
+}
+
+/** The sentence a report prints wherever it shows criterion names. */
+export function wcagAttribution() {
+  const { retrieved } = wcagSource();
+  return `Criterion names and levels come from the W3C's [WCAG 2.2 JSON](https://www.w3.org/WAI/WCAG22/wcag.json), retrieved ${retrieved}. Source: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), W3C. Links to each criterion are added by automatica11y.`;
+}

package/src/harness/npm-react.js

@@ -1,39 +0,0 @@
-/** React flavor: the entry files and button and link templates that go into a bundle. */
-
-/** Mounts a fixture's default export. */
-export const entry = (fixturePath, _pkg) => `import { createElement } from "react";
-import { createRoot } from "react-dom/client";
-import Fixture from ${JSON.stringify(fixturePath)};
-const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
-createRoot(document.getElementById("root")).render(createElement(Fixture, { libA11y }));
-`;
-
-/** Loads the whole package, lists its exports, and records compound parts such as Dialog.Trigger. */
-export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
-const out = [];
-for (const name of Object.keys(lib)) {
-  const value = lib[name];
-  const type = typeof value;
-  if (value === null || (type !== "function" && type !== "object")) continue;
-  const parts = Object.keys(value).filter((key) => /^[A-Z]/.test(key)).slice(0, 30);
-  out.push({ name, type, parts });
-}
-window.__a11yExports = out;
-`;
-
-/**
- * A fixture for the simple archetypes, from the export name alone.
- * Compound components (dialog, tabs, menu) can't be guessed, so they need a fixture someone writes.
- */
-export function template(archetype, pkg, exportName) {
-  const body = {
-    button: `<Component data-a11y-trigger data-a11y-root type="button">Save</Component>`,
-    link: `<Component data-a11y-trigger data-a11y-root href="#top">Read more</Component>`,
-  }[archetype];
-  if (!body) return null;
-  return `import { ${exportName} as Component } from ${JSON.stringify(pkg)};
-export default function Fixture() {
-  return ${body};
-}
-`;
-}

package/src/harness/npm-wc.js

@@ -1,30 +0,0 @@
-/** Web component flavor: framework-free entries and templates. */
-
-/** Loads the package so its custom elements get defined, then calls the fixture's default export, `mount(container)`. */
-export const entry = (fixturePath, pkg) => `import ${JSON.stringify(pkg)};
-import mount from ${JSON.stringify(fixturePath)};
-const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
-await mount(document.getElementById("root"), { libA11y });
-`;
-
-/** Loads the whole package. The page's init script records every custom element the package defines. */
-export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
-window.__a11yExports = Object.keys(lib).map((name) => ({ name, type: typeof lib[name], parts: [] }));
-`;
-
-/** A fixture for the simple archetypes, from the tag name alone. */
-export function template(archetype, tag) {
-  const attrs = {
-    button: `el.textContent = "Save";`,
-    link: `el.setAttribute("href", "#top");\n  el.textContent = "Read more";`,
-  }[archetype];
-  if (!attrs) return null;
-  return `export default function mount(container) {
-  const el = document.createElement(${JSON.stringify(tag)});
-  el.setAttribute("data-a11y-trigger", "");
-  el.setAttribute("data-a11y-root", "");
-  ${attrs}
-  container.append(el);
-}
-`;
-}