automatica11y 0.3.3 → 0.4.0

package/src/tiers/conditions/kit.js

@@ -0,0 +1,133 @@
+/**
+ * Runs inside the page before any page script. It sets `window.__a11yConditions`, which reads what the page does under
+ * a user's settings and environment: running animations, content that spills past the window, and content a text spacing
+ * override clips. It reports plain facts. The checks in checks.js decide pass or fail.
+ * This function is serialized and sent to the browser, so it can't use anything from outside itself.
+ */
+export function installConditions() {
+  /** A short, readable name for an element: `button#save`, `div.alert`, or `span`. */
+  const describe = (el) => {
+    if (!el || el.nodeType !== 1) return "(document)";
+    const tag = el.localName;
+    if (el.id) return `${tag}#${el.id}`;
+    const first = typeof el.className === "string" ? el.className.trim().split(/\s+/).find(Boolean) : "";
+    return first ? `${tag}.${first}` : tag;
+  };
+
+  /** Keyframe properties that move or resize something. Opacity and color changes aren't motion. */
+  const MOVING = /^(transform|translate|rotate|scale|top|left|right|bottom|inset\w*|margin\w*|offset(Path|Distance|Rotate)|backgroundPosition\w*|height|maxHeight|minHeight|width|maxWidth|minWidth|clipPath|clip)$/;
+  const IGNORED_KEYS = new Set(["offset", "easing", "composite", "computedOffset"]);
+
+  const allElements = () => [...document.body.querySelectorAll("*")];
+
+  /** The scroll container an element sits in, if one hides its overflow sideways (so it doesn't push the page wider). */
+  const scrollsSideways = (el) => {
+    for (let node = el.parentElement; node && node !== document.documentElement; node = node.parentElement) {
+      const x = getComputedStyle(node).overflowX;
+      if (x === "auto" || x === "scroll" || x === "hidden" || x === "clip") return true;
+    }
+    return false;
+  };
+
+  window.__a11yConditions = {
+    describe,
+    /** Every animation and transition running right now. */
+    animations() {
+      return document.getAnimations().map((/** @type {any} */ animation) => {
+        const effect = /** @type {any} */ (animation.effect);
+        const timing = effect?.getComputedTiming?.() ?? {};
+        const keyframes = effect?.getKeyframes?.() ?? [];
+        const props = [...new Set(keyframes.flatMap((frame) => Object.keys(frame)).filter((key) => !IGNORED_KEYS.has(key)))];
+        const target = effect?.target ?? null;
+        const iterations = timing.iterations === Infinity ? "infinite" : timing.iterations;
+        return {
+          kind: animation.constructor.name,
+          name: animation.animationName ?? animation.transitionProperty ?? "",
+          target: describe(target),
+          duration: typeof timing.duration === "number" ? timing.duration : null,
+          iterations,
+          props,
+          moving: props.some((prop) => MOVING.test(prop)),
+        };
+      });
+    },
+    /** How far the page reaches past the window's right edge, and which elements do it. */
+    overflow(rootSelector) {
+      const width = document.documentElement.clientWidth;
+      const offenders = [];
+      for (const el of allElements()) {
+        const box = el.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0) continue;
+        const style = getComputedStyle(el);
+        if (style.visibility === "hidden" || style.display === "none") continue;
+        if (box.right > width + 1 && !scrollsSideways(el)) offenders.push({ element: describe(el), right: Math.round(box.right), width: Math.round(box.width), left: Math.round(box.left) });
+      }
+      const root = rootSelector ? document.querySelector(rootSelector) : null;
+      const rootBox = root && root.getClientRects().length ? root.getBoundingClientRect() : null;
+      return {
+        viewportWidth: width,
+        scrollWidth: document.documentElement.scrollWidth,
+        offenders: offenders.slice(0, 8),
+        offenderCount: offenders.length,
+        root: rootBox ? { element: describe(root), left: Math.round(rootBox.left), right: Math.round(rootBox.right) } : null,
+      };
+    },
+    /** For every element, whether its box cuts off its own content, so two snapshots can show what a change clips. */
+    clipping() {
+      return allElements().map((el) => {
+        const style = getComputedStyle(el);
+        const hidesX = ["hidden", "clip"].includes(style.overflowX);
+        const hidesY = ["hidden", "clip"].includes(style.overflowY);
+        const box = el.getBoundingClientRect();
+        return {
+          /** A one-pixel box that hides its overflow is a screen reader only copy. Nobody sees its text, so nothing is cut off. */
+          visuallyHidden: box.width <= 1 && box.height <= 1,
+          element: describe(el),
+          hidesX,
+          hidesY,
+          overX: el.scrollWidth - el.clientWidth,
+          overY: el.scrollHeight - el.clientHeight,
+          text: (el.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 30),
+        };
+      });
+    },
+    /** Apply the text spacing the success criterion names, with !important so authored styles can't hold it back. */
+    applySpacing() {
+      const style = document.createElement("style");
+      style.setAttribute("data-a11y-spacing", "");
+      style.textContent = "* { line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; } p { margin-bottom: 2em !important; }";
+      document.head.append(style);
+    },
+    /**
+     * Surfaces that carry text over a see-through background or a blur: a background color that isn't fully opaque,
+     * or a backdrop filter. Empty overlays are left out, because they hold no text for the effect to get in the way of.
+     */
+    translucentSurfaces() {
+      const toRgba = window.__a11yMeasure?.rgba;
+      const found = [];
+      for (const el of allElements()) {
+        const box = el.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0) continue;
+        const style = getComputedStyle(el);
+        if (style.visibility === "hidden" || style.display === "none") continue;
+        const own = [...el.childNodes].some((n) => n.nodeType === 3 && n.nodeValue.trim()) || el.matches("input, textarea, select, button");
+        const holdsText = own || (el.textContent ?? "").trim().length > 0;
+        if (!holdsText) continue;
+        const color = toRgba ? toRgba(style.backgroundColor) : null;
+        const seeThrough = Boolean(color) && color[3] > 0 && color[3] < 1;
+        const blur = style.backdropFilter && style.backdropFilter !== "none" ? style.backdropFilter : "";
+        if (seeThrough || blur) found.push({ element: describe(el), background: seeThrough ? `${Math.round(color[3] * 100)}% opaque` : "", backdropFilter: blur });
+      }
+      return found;
+    },
+    /** Elements that opt out of forced colors, and so keep their own colors. */
+    forcedColorOptOuts() {
+      return allElements().filter((el) => getComputedStyle(el).forcedColorAdjust === "none").slice(0, 20).map(describe);
+    },
+    /** A cheap fingerprint of how the page looks in the current color scheme. */
+    appearance() {
+      const html = getComputedStyle(document.documentElement);
+      return { colorScheme: html.colorScheme, background: getComputedStyle(document.body).backgroundColor, color: getComputedStyle(document.body).color };
+    },
+  };
+}

package/src/tiers/interactions/archetypes.js

@@ -87,9 +87,120 @@ async function openMenu(ctx) {
   return null;
 }
 
+// ---- live-region: a message that appears or changes without moving focus ----
+
+/** Press Enter on the trigger and wait for the message. Returns what the page looked like before, and after. */
+async function showMessage(ctx) {
+  await ctx.focus();
+  const before = await ctx.page.evaluate(() => window.__a11y.live());
+  await ctx.press("Enter");
+  const deadline = Date.now() + 2500;
+  let after = await ctx.page.evaluate(() => window.__a11y.live());
+  while (Date.now() < deadline && !(after.present && after.visible && (after.text || after.named))) {
+    await ctx.settle(80);
+    after = await ctx.page.evaluate(() => window.__a11y.live());
+  }
+  return { before, after, appeared: after.present && after.visible };
+}
+
+const NO_MESSAGE = "The message didn't appear when Enter was pressed on the trigger.";
+
+const LIVE_REGION_CHECKS = [
+  {
+    name: "message-in-live-region",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return fail(NO_MESSAGE);
+      if (!after.region) return fail("The message isn't inside an element with role alert, status, or log, or with an aria-live attribute, so a screen reader isn't told when it appears.");
+      if (after.region.politeness === "off") return fail(`The message sits in a region that doesn't announce (${after.region.role ? `role ${after.region.role}` : "aria-live"}${after.region.ariaLive ? `, aria-live="${after.region.ariaLive}"` : ""}), so a screen reader isn't told when it appears.`);
+      return pass(`The message is in a live region (${after.region.role ? `role ${after.region.role}, ` : ""}${after.region.politeness}).`);
+    },
+  },
+  {
+    name: "message-has-text",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its text wasn't checked.`);
+      return after.text || after.named ? pass(`The message says "${after.text || "(named by aria-label)"}".`) : fail("The message has no text and no accessible name, so there's nothing to announce.");
+    },
+  },
+  {
+    name: "region-exists-before-message",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { before, after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its region wasn't checked.`);
+      if (!after.region || after.region.politeness === "off") return na("The message isn't in a live region, so the region's timing doesn't apply.");
+      if (before.regionUids.includes(after.region.uid)) return pass("The live region was already in the page before the message, so assistive technology was watching it.");
+      if (after.region.role === "alert") return pass("The live region was added together with its message. role=\"alert\" is announced when it's inserted, so this works.");
+      return before.ancestorUids.includes(after.region.uid)
+        ? fail("The element was in the page before the message, but it only became a live region when the message arrived. Screen readers often miss that. Put role or aria-live in the page's HTML, and change only what's inside the region.")
+        : fail("The live region was added to the page together with its message. Screen readers often miss that. Keep the region in the page and change what's inside it.");
+    },
+  },
+  {
+    name: "live-politeness-fits-role",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its politeness wasn't checked.`);
+      const r = after.region;
+      if (!r) return na("The message isn't in a live region, so there's no politeness to check.");
+      if (r.role === "alert" && r.ariaLive && r.ariaLive.toLowerCase() !== "assertive") return fail(`role="alert" is assertive, but aria-live="${r.ariaLive}" on the same element overrides it.`);
+      if (r.role === "status" && (r.ariaLive ?? "").toLowerCase() === "off") return fail('role="status" is polite, but aria-live="off" on the same element turns announcing off.');
+      return pass(`The region announces ${r.politeness}${r.role ? `, as role ${r.role} implies` : ""}.`);
+    },
+  },
+  {
+    name: "focus-stays-on-trigger",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Focus wasn't checked.`);
+      await ctx.settle(200);
+      const s = await ctx.snap();
+      return s.activeIsTrigger ? pass("Focus stayed on the trigger when the message appeared.") : fail(`Focus moved to ${where(s)} when the message appeared. A status message is announced without taking focus.`);
+    },
+  },
+  {
+    name: "dismiss-works-by-keyboard",
+    criteria: ["2.1.1"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its controls weren't checked.`);
+      const found = await ctx.page.evaluate(() => window.__a11y.focusDismiss());
+      if (!found.found) return na("The message has no control inside it, so there's nothing to dismiss.");
+      await ctx.settle();
+      await ctx.press("Enter");
+      const gone = await ctx.waitFor((s) => !s.rootExists || !s.rootVisible, 1500);
+      return gone ? pass(`Enter on the ${found.tag}${found.label ? ` "${found.label}"` : ""} removed the message.`) : fail(`Enter on the ${found.tag}${found.label ? ` "${found.label}"` : ""} didn't remove the message.`);
+    },
+  },
+  {
+    name: "focus-kept-after-removal",
+    criteria: ["2.4.3"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Focus after removal wasn't checked.`);
+      const found = await ctx.page.evaluate(() => window.__a11y.focusDismiss());
+      if (!found.found) return na("The message has no control inside it, so nothing removes it from the keyboard.");
+      await ctx.settle();
+      await ctx.press("Enter");
+      if (!(await ctx.waitFor((s) => !s.rootExists || !s.rootVisible, 1500))) return na("Enter didn't remove the message, so where focus goes wasn't checked.");
+      await ctx.settle(200);
+      const s = await ctx.snap();
+      return s.bodyActive ? fail("Focus fell back to the page when the message was removed. Move it to the trigger or another control.") : pass(`Focus moved to ${where(s)} when the message was removed.`);
+    },
+  },
+];
+
 // ---- The tables ----
 
 export const ARCHETYPE_CHECKS = {
+  "live-region": LIVE_REGION_CHECKS,
+
   button: [
     { name: "enter-activates", criteria: ["2.1.1"], run: activates("Enter", "Enter") },
     { name: "space-activates", criteria: ["2.1.1"], run: activates("Space", "Space") },

package/src/tiers/interactions/helpers.js

@@ -63,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();
@@ -71,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);
 
@@ -116,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]");

package/src/tiers/interactions/index.js

@@ -66,13 +66,25 @@ export 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, kits = [installHelpers] } = {}) {
+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: async (page) => { for (const kit of kits) await page.addInitScript(kit); }, 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/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);
-}
-`;
-}