automatica11y 0.3.1 → 0.3.3

package/src/tiers/computed/color.js

@@ -0,0 +1,40 @@
+/**
+ * Color math for the computed tier. Colors are `[r, g, b, a]` with r, g, and b from 0 to 255 and a from 0 to 1.
+ * The page turns every CSS color into this form (see measure-kit.js), so this file never parses CSS.
+ */
+
+/** Relative luminance of an opaque color, as WCAG defines it. */
+export function luminance([r, g, b]) {
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Lay `top` over an opaque `under` color. The result is opaque. */
+export function composite(top, under) {
+  const a = top[3];
+  return [0, 1, 2].map((i) => top[i] * a + under[i] * (1 - a)).concat(1);
+}
+
+/** WCAG contrast ratio between two opaque colors, from 1 to 21. */
+export function contrastRatio(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Contrast of a possibly translucent foreground over an opaque background. */
+export function contrastOver(fg, bg) {
+  return contrastRatio(composite(fg, bg), bg);
+}
+
+/** The ratio text needs: 3 for large text (24px, or 18.66px and bold), and 4.5 for the rest. */
+export function textThreshold(sizePx, weight) {
+  return sizePx >= 24 || (sizePx >= 18.66 && Number(weight) >= 700) ? 3 : 4.5;
+}
+
+/** "4.52:1". The ratio is cut down, never rounded up, so 2.999 never reads as 3. */
+export function formatRatio(ratio) {
+  return `${(Math.floor(ratio * 100) / 100).toFixed(2).replace(/\.?0+$/, "")}:1`;
+}

package/src/tiers/computed/index.js

@@ -0,0 +1,25 @@
+import { installHelpers } from "../interactions/helpers.js";
+import { runCheck } from "../interactions/index.js";
+import { COMPUTED_CHECKS } from "./checks.js";
+import { installMeasure } from "./measure-kit.js";
+
+/**
+ * Run the computed checks for one archetype against its fixture page. Each check gets a fresh page.
+ * A check that can't finish reports `error`, and one that can't reduce the page to colors reports `undetermined`.
+ * Neither counts as a pass.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype
+ */
+export async function runComputed(browser, url, archetype) {
+  if (archetype === "chart") return { status: "not-applicable", reason: "The chart archetype has no trigger to measure." };
+  const results = [];
+  for (const check of COMPUTED_CHECKS) results.push(await runCheck(browser, url, check, { kits: [installHelpers, installMeasure] }));
+  return { status: "ran", checks: results };
+}
+
+/** What a page or Storybook target says about this tier. */
+export const COMPUTED_NOT_APPLICABLE_FOR_PAGES = {
+  status: "not-applicable",
+  reason: "Computed checks need an archetype fixture with a trigger hook. Page and Storybook targets don't have one.",
+};

package/src/tiers/computed/measure-kit.js

@@ -0,0 +1,205 @@
+/**
+ * Runs inside the page before any page script. It sets `window.__a11yMeasure`, which reads resolved styles
+ * (getComputedStyle) and turns them into plain numbers: colors as [r, g, b, a], sizes in pixels.
+ * It never decides pass or fail. The checks in checks.js do that.
+ * This function is serialized and sent to the browser, so it can't use anything from outside itself.
+ */
+export function installMeasure() {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const context = canvas.getContext("2d", { willReadFrequently: true });
+
+  /** Any CSS color to [r, g, b, a] in sRGB, or null. The canvas does the conversion, so modern color spaces work. */
+  const rgba = (css) => {
+    if (!css || !context) return null;
+    context.clearRect(0, 0, 1, 1);
+    context.fillStyle = "#000";
+    context.fillStyle = css;
+    context.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;
+    // The canvas stores premultiplied values, so a translucent color loses a little precision. That's fine for contrast.
+    return a === 0 ? [0, 0, 0, 0] : [r, g, b, a / 255];
+  };
+  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3])).concat(1);
+  const parentOf = (el) => el.assignedSlot || el.parentElement || (el.getRootNode() instanceof ShadowRoot ? el.getRootNode().host : null);
+
+  /**
+   * The opaque color behind an element: its ancestors' backgrounds laid over each other, ending at white.
+   * `includeSelf` adds the element's own background. Gradients, images, and transparency can't be reduced to one color,
+   * so those return a reason instead of a guess.
+   */
+  const backdrop = (el, includeSelf) => {
+    const layers = [];
+    let node = includeSelf ? el : parentOf(el);
+    for (let hops = 0; node && hops < 60; hops += 1) {
+      const style = getComputedStyle(node);
+      if (style.backgroundImage !== "none") return { reason: "a background image or gradient sits behind it" };
+      if (Number(style.opacity) < 1) return { reason: "an element behind it is partly transparent" };
+      if (style.mixBlendMode !== "normal") return { reason: "a blend mode is applied behind it" };
+      const color = rgba(style.backgroundColor);
+      if (color && color[3] > 0) {
+        layers.push(color);
+        if (color[3] === 1) break;
+      }
+      node = parentOf(node);
+    }
+    let result = [255, 255, 255, 1];
+    for (const layer of layers.reverse()) result = over(layer, result);
+    return { color: result };
+  };
+
+  const visibleBox = (el) => {
+    const box = el.getBoundingClientRect();
+    return box.width > 0 && box.height > 0;
+  };
+  const deepActive = () => {
+    let active = document.activeElement;
+    while (active && active.shadowRoot && active.shadowRoot.activeElement) active = active.shadowRoot.activeElement;
+    return active;
+  };
+  const trigger = () => {
+    const find = (root) => {
+      const hit = root.querySelector("[data-a11y-trigger]");
+      if (hit) return hit;
+      for (const el of root.querySelectorAll("*")) if (el.shadowRoot) { const inner = find(el.shadowRoot); if (inner) return inner; }
+      return null;
+    };
+    return find(document);
+  };
+
+  /** Split a computed box-shadow list at its top-level commas. */
+  const splitShadows = (value) => {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+      if (value[i] === "(") depth += 1;
+      else if (value[i] === ")") depth -= 1;
+      else if (value[i] === "," && depth === 0) { out.push(value.slice(start, i).trim()); start = i + 1; }
+    }
+    out.push(value.slice(start).trim());
+    return out.filter(Boolean);
+  };
+  const parseShadow = (text) => {
+    const color = /(rgba?\([^)]*\)|color\([^)]*\)|oklab\([^)]*\)|oklch\([^)]*\)|lab\([^)]*\)|lch\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]{3,8}|\b[a-z]+\b(?=\s|$))/i.exec(text.replace(/\binset\b/, ""));
+    const rest = text.replace(/\binset\b/, "").replace(color ? color[0] : "", "");
+    const [x, y, blur, spread] = (rest.match(/-?[\d.]+px/g) ?? []).map(parseFloat);
+    return { inset: /\binset\b/.test(text), x: x ?? 0, y: y ?? 0, blur: blur ?? 0, spread: spread ?? 0, color: color ? rgba(color[0]) : null };
+  };
+
+  window.__a11yMeasure = {
+    rgba,
+    /** The text inside the trigger: each element that directly holds text, with its color, size, and backdrop. */
+    text() {
+      const el = trigger();
+      if (!el) return null;
+      const parts = [];
+      const seen = new Set();
+      const consider = (node, label) => {
+        if (seen.has(node) || !visibleBox(node)) return;
+        seen.add(node);
+        const style = getComputedStyle(node);
+        if (style.visibility === "hidden") return;
+        const behind = backdrop(node, true);
+        const color = rgba(style.color);
+        parts.push({
+          text: label.replace(/\s+/g, " ").trim().slice(0, 40),
+          color,
+          size: parseFloat(style.fontSize),
+          weight: style.fontWeight,
+          backdrop: behind.color ?? null,
+          undetermined: behind.reason ?? (color ? null : "its color couldn't be read"),
+        });
+      };
+      const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+      for (let node = walker.nextNode(); node && parts.length < 12; node = walker.nextNode()) {
+        if (node.nodeValue && node.nodeValue.trim() && node.parentElement) consider(node.parentElement, node.nodeValue);
+      }
+      if (el.matches("input, textarea, select") && "value" in el && String(el.value).trim()) consider(el, String(el.value));
+      return parts;
+    },
+    /** What the control looks like from outside: label, input, or icon, and the colors that mark its edge. */
+    boundary() {
+      const el = trigger();
+      if (!el) return null;
+      const style = getComputedStyle(el);
+      const outside = backdrop(el, false);
+      const inside = backdrop(el, true);
+      const parts = [];
+      if (outside.color && inside.color) {
+        parts.push({ kind: "fill", color: inside.color });
+        for (const side of ["Top", "Right", "Bottom", "Left"]) {
+          const border = parseFloat(style[`border${side}Width`]) > 0 && style[`border${side}Style`] !== "none" ? rgba(style[`border${side}Color`]) : null;
+          if (border && border[3] > 0) parts.push({ kind: `${side.toLowerCase()} border`, color: over(border, inside.color), width: parseFloat(style[`border${side}Width`]) });
+        }
+      }
+      const graphics = [];
+      for (const shape of el.querySelectorAll("svg path, svg circle, svg ellipse, svg rect, svg line, svg polyline, svg polygon")) {
+        const s = getComputedStyle(shape);
+        for (const [kind, value] of [["fill", s.fill], ["stroke", s.stroke]]) {
+          const color = value && value !== "none" ? rgba(value) : null;
+          if (color && color[3] > 0 && visibleBox(shape) && inside.color) graphics.push({ kind, color: over(color, inside.color) });
+        }
+      }
+      return {
+        outside: outside.color ?? null,
+        undetermined: outside.reason ?? inside.reason ?? null,
+        parts,
+        graphics: graphics.slice(0, 12),
+        hasText: (el.innerText ?? el.textContent ?? "").trim().length > 0 || (el.matches("input, textarea, select") && "value" in el && String(el.value).trim().length > 0),
+        inputLike: el.matches("input:not([type=button]):not([type=submit]):not([type=reset]):not([type=checkbox]):not([type=radio]), textarea, select") || ["textbox", "combobox", "searchbox", "listbox"].includes(el.getAttribute("role") ?? ""),
+        box: (() => { const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, width: b.width, height: b.height }; })(),
+      };
+    },
+    /** The styles that draw a focus indicator on the focused element itself, with the colors they sit against. */
+    focusStyles(atRest) {
+      const el = atRest ? trigger() : deepActive();
+      if (!el) return null;
+      const style = getComputedStyle(el);
+      const outside = backdrop(el, false);
+      const inside = backdrop(el, true);
+      const side = ["Top", "Right", "Bottom", "Left"].find((name) => parseFloat(style[`border${name}Width`]) > 0 && style[`border${name}Style`] !== "none");
+      const border = side ? rgba(style[`border${side}Color`]) : null;
+      return {
+        outside: outside.color ?? null,
+        inside: inside.color ?? null,
+        undetermined: outside.reason ?? inside.reason ?? null,
+        outline: style.outlineStyle !== "none" && parseFloat(style.outlineWidth) > 0 ? { width: parseFloat(style.outlineWidth), offset: parseFloat(style.outlineOffset) || 0, color: rgba(style.outlineColor) } : null,
+        shadows: style.boxShadow === "none" ? [] : splitShadows(style.boxShadow).map(parseShadow),
+        border: border ? { width: parseFloat(style[`border${side}Width`]), color: border } : null,
+        box: (() => { const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, width: b.width, height: b.height }; })(),
+      };
+    },
+    /**
+     * Compare two screenshots (as data URLs) pixel by pixel. For each pixel that changed, find the contrast between
+     * its two colors. Used when a focus indicator isn't a plain outline or ring, such as a ripple or a background change.
+     */
+    async compareShots(before, after) {
+      const load = async (url) => {
+        const bitmap = await createImageBitmap(await (await fetch(url)).blob());
+        const c = document.createElement("canvas");
+        c.width = bitmap.width;
+        c.height = bitmap.height;
+        const ctx = c.getContext("2d", { willReadFrequently: true });
+        ctx.drawImage(bitmap, 0, 0);
+        return ctx.getImageData(0, 0, c.width, c.height);
+      };
+      const [a, b] = [await load(before), await load(after)];
+      const lin = (v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+      const lum = (d, i) => 0.2126 * lin(d[i]) + 0.7152 * lin(d[i + 1]) + 0.0722 * lin(d[i + 2]);
+      let changed = 0;
+      let strong = 0;
+      let max = 1;
+      for (let i = 0; i < a.data.length; i += 4) {
+        if (a.data[i] === b.data[i] && a.data[i + 1] === b.data[i + 1] && a.data[i + 2] === b.data[i + 2]) continue;
+        changed += 1;
+        const [hi, lo] = [lum(a.data, i), lum(b.data, i)].sort((x, y) => y - x);
+        const ratio = (hi + 0.05) / (lo + 0.05);
+        if (ratio > max) max = ratio;
+        if (ratio >= 3) strong += 1;
+      }
+      return { changed, strong, max, width: a.width, height: a.height };
+    },
+  };
+}

package/src/tiers/interactions/archetypes.js

@@ -5,6 +5,8 @@
  * Checks only use the two hooks (`data-a11y-trigger`, `data-a11y-root`) and ARIA roles.
  */
 
+import { focusIndicatorChanges } from "./focus-indicator.js";
+
 const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
 const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
 const na = (detail) => ({ result: "not-applicable", detail });
@@ -28,15 +30,15 @@ const COMMON = [
     criteria: ["2.4.7"],
     async run(ctx) {
       if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so its focus indicator wasn't checked.");
-      const focused = await ctx.page.evaluate(() => window.__a11y.focusStyle());
+      const focused = await ctx.page.evaluate(() => window.__a11y.focusSnapshot());
       await ctx.page.evaluate(() => window.__a11y.remember());
       const clip = ctx.clipAround(focused.box);
       const shotFocused = await ctx.page.screenshot({ clip });
       await ctx.page.evaluate(() => /** @type {any} */ (window).__a11yLast?.blur());
       await ctx.settle();
-      const unfocused = await ctx.page.evaluate(() => window.__a11y.lastStyle());
-      const changed = Object.keys(focused.style).filter((key) => focused.style[key] !== unfocused?.[key]);
-      if (changed.length) return pass(`Computed style changed on focus: ${changed.join(", ")}.`, { method: "computed-style" });
+      const unfocused = await ctx.page.evaluate(() => window.__a11y.lastSnapshot());
+      const changed = focusIndicatorChanges(focused.parts, unfocused?.parts);
+      if (changed.length) return pass(`Computed style changed on focus: ${changed.join("; ")}.`, { method: "computed-style" });
       const shotBlurred = await ctx.page.screenshot({ clip });
       if (!shotFocused.equals(shotBlurred)) return pass("The pixels around the trigger changed on focus, though no style property did.", { method: "screenshot" });
       return fail("Nothing visible changed when the trigger got keyboard focus. Checked computed styles first, then a screenshot comparison.", { method: "screenshot" });

package/src/tiers/interactions/focus-indicator.js

@@ -0,0 +1,39 @@
+/**
+ * Compare the resolved styles of a control with and without keyboard focus, and say which changes can show a focus indicator.
+ * A change counts only if a person could see it: an outline with a width and a color, a box shadow, a border, a color change,
+ * a text decoration, or an element that appeared inside. An outline offset alone doesn't count, because it moves nothing visible.
+ * @param {Record<string, Record<string, any>>} focused Parts of the focused control, keyed by where they are.
+ * @param {Record<string, Record<string, any>> | undefined} unfocused The same parts without focus.
+ * @returns {string[]} Each change, such as `the element: outline`.
+ */
+export function focusIndicatorChanges(focused, unfocused) {
+  const changes = [];
+  for (const [where, now] of Object.entries(focused)) {
+    const before = unfocused?.[where];
+    if (!before) {
+      if (now.rendered) changes.push(`${where}: appeared on focus`);
+      continue;
+    }
+    // A ring that stays in the page but only shows on focus, such as a ripple, goes from not rendered to rendered.
+    if (now.rendered && !before.rendered) {
+      changes.push(`${where}: appeared on focus`);
+      continue;
+    }
+    const found = [];
+    const drawnOutline = (s) => s.outlineStyle !== "none" && parseFloat(s.outlineWidth) > 0 && !transparent(s.outlineColor);
+    if (drawnOutline(now) && (!drawnOutline(before) || now.outlineWidth !== before.outlineWidth || now.outlineColor !== before.outlineColor || now.outlineStyle !== before.outlineStyle)) found.push("outline");
+    if (now.boxShadow !== before.boxShadow) found.push("box-shadow");
+    const drawnBorder = (s) => s.borderTopStyle !== "none" && parseFloat(s.borderTopWidth) > 0;
+    if (drawnBorder(now) && (now.borderTopColor !== before.borderTopColor || now.borderTopWidth !== before.borderTopWidth || !drawnBorder(before))) found.push("border");
+    if (now.backgroundColor !== before.backgroundColor) found.push("background color");
+    if (now.color !== before.color) found.push("text color");
+    if (now.textDecorationLine !== before.textDecorationLine) found.push("text decoration");
+    if (!now.rendered && !before.rendered) continue;
+    for (const what of found) changes.push(`${where}: ${what}`);
+  }
+  return changes;
+}
+
+function transparent(color) {
+  return color === "transparent" || /^rgba\(.*,\s*0\)$/.test(color) || /\/\s*0\)$/.test(color);
+}

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)];
@@ -116,26 +138,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,11 +66,11 @@ 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] } = {}) {
   /** @type {Awaited<ReturnType<typeof openPage>> | null} */
   let opened = null;
   try {
-    opened = await openPage(browser, url, { beforeGoto: (page) => page.addInitScript(installHelpers), waitUntil: "load" });
+    opened = await openPage(browser, url, { beforeGoto: async (page) => { for (const kit of kits) await page.addInitScript(kit); }, waitUntil: "load" });
     const ctx = makeContext(opened.page);
     await ctx.trigger.waitFor({ state: "attached", timeout: 3000 });
     const outcome = await Promise.race([

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.`;
+}