a11y-loop 0.1.0

package/src/lib/checks/focus-visible.js

@@ -0,0 +1,296 @@
+/**
+ * Focus visibility (SC 2.4.7) and focus-indicator contrast (SC 1.4.11).
+ *
+ * Method: read the computed style of every focusable element in its resting
+ * state, focus it, read the computed style again, and diff. A focus indicator
+ * exists only if something visibly CHANGED — an element that looks identical
+ * focused and unfocused has no indicator, whatever its stylesheet claims.
+ *
+ * The ring's own contrast against the colour behind it is SC 1.4.11 territory
+ * that essentially nothing automates. Where the adjacent background cannot be
+ * determined (background images, gradients) the finding is needs-review rather
+ * than a guess.
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+import { checkContrast, parseColor, ColorParseError } from '../contrast-math.js';
+import { resetFocusToDocumentStart, clearFocusSentinel } from './keyboard.js';
+
+/** Computed properties compared between resting and focused state. */
+export const WATCHED_PROPERTIES = [
+  'outlineStyle',
+  'outlineWidth',
+  'outlineColor',
+  'outlineOffset',
+  'boxShadow',
+  'borderTopWidth',
+  'borderTopColor',
+  'borderBottomWidth',
+  'borderBottomColor',
+  'backgroundColor',
+  'color',
+  'textDecorationLine',
+  'textDecorationColor',
+];
+
+/** Minimum contrast for a focus indicator, as a non-text visual object. */
+export const RING_CONTRAST_MIN = 3;
+
+const isTransparent = (value) =>
+  typeof value === 'string' &&
+  (value === 'transparent' || /rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0\s*\)/.test(value));
+
+const hasWidth = (value) => Number.parseFloat(value) > 0;
+
+/**
+ * Which watched properties changed on focus, described in plain terms.
+ *
+ * @param {Record<string,string>} base    computed style at rest
+ * @param {Record<string,string>} focused computed style while focused
+ * @returns {{visible:boolean, indicators:string[], changed:string[]}}
+ */
+export function describeFocusChange(base = {}, focused = {}) {
+  const changed = WATCHED_PROPERTIES.filter((prop) => base[prop] !== focused[prop]);
+  const indicators = [];
+
+  const outlineAppeared =
+    focused.outlineStyle !== 'none' &&
+    hasWidth(focused.outlineWidth) &&
+    !isTransparent(focused.outlineColor) &&
+    (base.outlineStyle === 'none' ||
+      !hasWidth(base.outlineWidth) ||
+      isTransparent(base.outlineColor) ||
+      base.outlineColor !== focused.outlineColor ||
+      base.outlineWidth !== focused.outlineWidth);
+  if (outlineAppeared) indicators.push('outline');
+
+  if (
+    focused.boxShadow &&
+    focused.boxShadow !== 'none' &&
+    base.boxShadow !== focused.boxShadow
+  ) {
+    indicators.push('box-shadow');
+  }
+  if (
+    base.borderTopWidth !== focused.borderTopWidth ||
+    base.borderTopColor !== focused.borderTopColor ||
+    base.borderBottomWidth !== focused.borderBottomWidth ||
+    base.borderBottomColor !== focused.borderBottomColor
+  ) {
+    indicators.push('border');
+  }
+  if (base.backgroundColor !== focused.backgroundColor) indicators.push('background-color');
+  if (base.color !== focused.color) indicators.push('text colour');
+  if (
+    base.textDecorationLine !== focused.textDecorationLine ||
+    base.textDecorationColor !== focused.textDecorationColor
+  ) {
+    indicators.push('text-decoration');
+  }
+
+  return { visible: indicators.length > 0, indicators, changed };
+}
+
+/**
+ * The colour of the focus indicator itself, if one can be identified.
+ * @returns {string|null}
+ */
+export function indicatorColor(focused = {}, indicators = []) {
+  if (indicators.includes('outline') && !isTransparent(focused.outlineColor)) {
+    return focused.outlineColor;
+  }
+  if (indicators.includes('box-shadow')) {
+    const match = /(rgba?\([^)]*\))/.exec(focused.boxShadow ?? '');
+    if (match && !isTransparent(match[1])) return match[1];
+  }
+  if (indicators.includes('border') && !isTransparent(focused.borderTopColor)) {
+    return focused.borderTopColor;
+  }
+  return null;
+}
+
+/**
+ * Contrast of a focus ring against what sits behind it.
+ *
+ * @returns {{determinable:boolean, ratio?:number, ratioDisplay?:string, passes?:boolean}}
+ */
+export function ringContrast(ringColor, adjacentBackground) {
+  if (!ringColor || !adjacentBackground) return { determinable: false };
+  try {
+    parseColor(ringColor);
+    parseColor(adjacentBackground);
+  } catch (error) {
+    if (error instanceof ColorParseError) return { determinable: false };
+    throw error;
+  }
+  const result = checkContrast(ringColor, adjacentBackground, { ui: true });
+  return {
+    determinable: true,
+    ratio: result.ratio,
+    ratioDisplay: result.ratioDisplay,
+    passes: result.passes.AA,
+  };
+}
+
+/**
+ * @param {Array} samples from `surveyFocusVisibility`
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function focusVisibilityFindings(samples, ctx) {
+  const findings = [];
+  const { passes = [], state = null } = ctx ?? {};
+
+  for (const sample of samples) {
+    const change = describeFocusChange(sample.base, sample.focused);
+
+    if (!change.visible) {
+      findings.push(
+        makeFinding({
+          ruleId: 'focus-not-visible',
+          source: 'a11y-loop',
+          severity: SEVERITY.VIOLATION,
+          impact: 'serious',
+          sc: '2.4.7',
+          selector: sample.selector,
+          html: sample.html,
+          message:
+            'Nothing about this element changes visually when it receives keyboard focus ' +
+            '(no outline, box-shadow, border, background or text change). Keyboard users ' +
+            'cannot tell where they are.',
+          passes,
+          state,
+        }),
+      );
+      continue;
+    }
+
+    const ring = indicatorColor(sample.focused, change.indicators);
+    const contrast = ringContrast(ring, sample.adjacentBackground);
+
+    if (!contrast.determinable) {
+      findings.push(
+        makeFinding({
+          ruleId: 'focus-indicator-contrast',
+          source: 'a11y-loop',
+          severity: SEVERITY.NEEDS_REVIEW,
+          impact: 'moderate',
+          sc: '1.4.11',
+          selector: sample.selector,
+          html: sample.html,
+          message:
+            `Focus indicator present (${change.indicators.join(', ')}), but its contrast ` +
+            'could not be computed — the colour behind it is an image, a gradient, or not ' +
+            'resolvable. Confirm the indicator is clearly visible against its surroundings.',
+          passes,
+          state,
+          data: { indicators: change.indicators, indicatorColor: ring },
+        }),
+      );
+      continue;
+    }
+
+    if (!contrast.passes) {
+      findings.push(
+        makeFinding({
+          ruleId: 'focus-indicator-contrast',
+          source: 'a11y-loop',
+          severity: SEVERITY.NEEDS_REVIEW,
+          impact: 'moderate',
+          sc: '1.4.11',
+          selector: sample.selector,
+          html: sample.html,
+          message:
+            `The focus indicator (${change.indicators.join(', ')}, ${ring}) has a contrast ` +
+            `ratio of ${contrast.ratioDisplay}:1 against the adjacent background ` +
+            `${sample.adjacentBackground}, below the ${RING_CONTRAST_MIN}:1 minimum for ` +
+            'non-text visual information.',
+          passes,
+          state,
+          data: {
+            indicators: change.indicators,
+            indicatorColor: ring,
+            adjacentBackground: sample.adjacentBackground,
+            ratio: contrast.ratio,
+          },
+        }),
+      );
+    }
+  }
+
+  return findings;
+}
+
+/** How many Tab presses the focus walk will make. */
+export const MAX_FOCUS_STEPS = 40;
+
+/**
+ * Record resting and focused computed styles for each focusable element.
+ *
+ * Focus is driven with the Tab KEY rather than `element.focus()`, because
+ * `:focus-visible` is exactly the selector that distinguishes the two: Chromium
+ * applies it on keyboard focus and withholds it on programmatic focus for most
+ * element types. Calling `.focus()` would report missing focus rings on elements
+ * that style `:focus-visible` correctly.
+ *
+ * The cost is a second Tab walk (the keyboard check does its own). Both walks are
+ * read-only, so they cannot contaminate each other.
+ *
+ * @param {import('playwright').Page} page
+ */
+export async function surveyFocusVisibility(page) {
+  const resting = await page.evaluate((watched) => {
+    const helpers = window.__a11yLoop;
+    const nodes = window.tabbable ? window.tabbable.tabbable(helpers.tabbableRoot()) : [];
+    if (document.activeElement && document.activeElement.blur) document.activeElement.blur();
+    const read = (el) => {
+      const style = getComputedStyle(el);
+      const out = {};
+      for (const prop of watched) out[prop] = style[prop];
+      return out;
+    };
+    const map = {};
+    for (const el of nodes) {
+      if (!helpers.isVisible(el)) continue;
+      map[helpers.cssPath(el)] = {
+        html: helpers.shortHtml(el),
+        style: read(el),
+        adjacentBackground: helpers.backdropColor(el.parentElement ?? el),
+      };
+    }
+    return map;
+  }, WATCHED_PROPERTIES);
+
+  await resetFocusToDocumentStart(page);
+
+  const samples = [];
+  const seen = new Set();
+  for (let i = 0; i < MAX_FOCUS_STEPS; i++) {
+    await page.keyboard.press('Tab');
+    const stop = await page.evaluate((watched) => {
+      const el = document.activeElement;
+      if (!el || el === document.body || el === document.documentElement) return null;
+      if (el.hasAttribute?.('data-a11y-loop-sentinel')) return null;
+      const style = getComputedStyle(el);
+      const focused = {};
+      for (const prop of watched) focused[prop] = style[prop];
+      return { selector: window.__a11yLoop.cssPath(el), focused };
+    }, WATCHED_PROPERTIES);
+
+    if (!stop) break;
+    if (seen.has(stop.selector)) break; // wrapped around
+    seen.add(stop.selector);
+
+    const base = resting[stop.selector];
+    if (!base) continue; // tabbable did not predict it; the keyboard check reports that
+    samples.push({
+      selector: stop.selector,
+      html: base.html,
+      base: base.style,
+      focused: stop.focused,
+      adjacentBackground: base.adjacentBackground,
+    });
+  }
+
+  await clearFocusSentinel(page);
+  return samples;
+}

package/src/lib/checks/keyboard.js

@@ -0,0 +1,235 @@
+/**
+ * Keyboard reachability and tab order (SC 2.1.1, 2.4.3).
+ *
+ * Two things axe cannot see, because it never presses a key:
+ *  1. Positive `tabindex` values — always a defect. They pull elements out of
+ *     document order into a separate, brittle tab sequence.
+ *  2. The observed tab walk versus the set `tabbable()` says should be
+ *     reachable. A mismatch means either something interactive is unreachable
+ *     (a real failure) or the order diverges from DOM order (a judgment call
+ *     for a human, so: needs review).
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+
+/** How many Tab presses to walk before giving up. */
+export const MAX_TAB_STEPS = 60;
+
+/**
+ * @param {Array<{selector:string, html:string, tabindex:string}>} elements
+ * @returns {Array<{selector:string, html:string, tabindex:number}>}
+ */
+export function findPositiveTabindex(elements) {
+  return elements
+    .map((el) => ({ ...el, tabindex: Number.parseInt(el.tabindex, 10) }))
+    .filter((el) => Number.isFinite(el.tabindex) && el.tabindex > 0);
+}
+
+/**
+ * Compare what `tabbable()` says is reachable with what actually received focus.
+ *
+ * @param {{expected:string[], observed:string[]}} walk selectors, in order
+ * @returns {{unreachable:string[], unexpected:string[], divergesAt:number|null}}
+ */
+export function diffTabOrder({ expected = [], observed = [] } = {}) {
+  const observedSet = new Set(observed);
+  const expectedSet = new Set(expected);
+
+  const unreachable = expected.filter((sel) => !observedSet.has(sel));
+  const unexpected = observed.filter((sel) => !expectedSet.has(sel));
+
+  // Compare the order of the elements the two lists agree on.
+  const commonExpected = expected.filter((sel) => observedSet.has(sel));
+  const commonObserved = observed.filter((sel) => expectedSet.has(sel));
+  let divergesAt = null;
+  for (let i = 0; i < Math.min(commonExpected.length, commonObserved.length); i++) {
+    if (commonExpected[i] !== commonObserved[i]) {
+      divergesAt = i;
+      break;
+    }
+  }
+
+  return { unreachable, unexpected, divergesAt };
+}
+
+/**
+ * Build findings from a completed keyboard survey.
+ *
+ * @param {object} survey
+ * @param {Array} survey.positiveTabindex
+ * @param {string[]} survey.expected
+ * @param {string[]} survey.observed
+ * @param {Array<{selector:string,html:string}>} [survey.expectedDetails]
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function keyboardFindings(survey, ctx) {
+  const findings = [];
+  const { passes = [], state = null } = ctx ?? {};
+
+  const positiveTabindex = findPositiveTabindex(survey.positiveTabindex ?? []);
+  const positiveTabindexSelectors = new Set(positiveTabindex.map((el) => el.selector));
+
+  for (const el of positiveTabindex) {
+    findings.push(
+      makeFinding({
+        ruleId: 'positive-tabindex',
+        source: 'a11y-loop',
+        severity: SEVERITY.VIOLATION,
+        impact: 'serious',
+        sc: '2.4.3',
+        selector: el.selector,
+        html: el.html,
+        message:
+          `tabindex="${el.tabindex}" forces this element out of document order into a ` +
+          'separate tab sequence. Use tabindex="0" (or no tabindex) and order the DOM instead.',
+        passes,
+        state,
+        data: { tabindex: el.tabindex },
+      }),
+    );
+  }
+
+  const diff = diffTabOrder(survey);
+  const detailFor = (selector) =>
+    (survey.expectedDetails ?? []).find((d) => d.selector === selector)?.html ?? '';
+
+  // A positive-tabindex element sorts into an earlier phase of the browser's
+  // focus order than anything a forward-only walk anchored at document start
+  // can reach — the walk can never observe it, however reachable it really is,
+  // because there is no tabindex value that sorts before a positive one. That
+  // makes it look "unreachable" when the real defect (and the only one worth
+  // reporting) is already captured, more precisely, by positive-tabindex above.
+  // Reporting both would double-count the same element under two rule ids and
+  // mislabel a "reachable too early" problem as "unreachable".
+  for (const selector of diff.unreachable.filter((sel) => !positiveTabindexSelectors.has(sel))) {
+    findings.push(
+      makeFinding({
+        ruleId: 'keyboard-unreachable',
+        source: 'a11y-loop',
+        severity: SEVERITY.VIOLATION,
+        impact: 'critical',
+        sc: '2.1.1',
+        selector,
+        html: detailFor(selector),
+        message:
+          'This element should be reachable by keyboard but never received focus during a ' +
+          `Tab walk of ${MAX_TAB_STEPS} steps. Check for aria-hidden, display:none on focus, ` +
+          'a focus trap earlier in the page, or tabindex="-1".',
+        passes,
+        state,
+      }),
+    );
+  }
+
+  if (diff.divergesAt !== null) {
+    findings.push(
+      makeFinding({
+        ruleId: 'focus-order-diverges',
+        source: 'a11y-loop',
+        severity: SEVERITY.NEEDS_REVIEW,
+        impact: 'moderate',
+        sc: '2.4.3',
+        selector: survey.observed?.[diff.divergesAt] ?? 'html',
+        html: '',
+        message:
+          'The observed tab order diverges from DOM order at position ' +
+          `${diff.divergesAt + 1}. That is not automatically a failure — whether the order is ` +
+          'logical is a human judgment. Confirm the sequence still makes sense.',
+        passes,
+        state,
+        data: { expected: survey.expected, observed: survey.observed },
+      }),
+    );
+  }
+
+  return findings;
+}
+
+/**
+ * Put the sequential focus navigation starting point at the top of the
+ * currently reachable region.
+ *
+ * `blur()` alone is not enough: Chromium remembers the blurred element as the
+ * starting point, so the next Tab continues from there and the elements BEFORE it
+ * are never visited — which looks exactly like an unreachable control. This
+ * matters whenever a state setup function has clicked something, which is most of
+ * the time. A focused sentinel at the start of the body fixes the origin.
+ *
+ * "Top of the document" is not always `document.body`: if a native `<dialog>`
+ * is open, everything outside it is inert, so a sentinel inserted into `body`
+ * could never be focused at all. The sentinel goes into whichever element
+ * `tabbableRoot()` says is actually reachable right now.
+ *
+ * @param {import('playwright').Page} page
+ */
+export async function resetFocusToDocumentStart(page) {
+  await page.evaluate(() => {
+    document.querySelector('[data-a11y-loop-sentinel]')?.remove();
+    const sentinel = document.createElement('span');
+    sentinel.tabIndex = 0;
+    sentinel.setAttribute('data-a11y-loop-sentinel', '');
+    sentinel.style.cssText =
+      'position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;';
+    const root = window.__a11yLoop ? window.__a11yLoop.tabbableRoot() : document.body;
+    root.insertBefore(sentinel, root.firstChild);
+    sentinel.focus();
+  });
+}
+
+/** Remove the sentinel so it can never appear in a report or a later pass. */
+export async function clearFocusSentinel(page) {
+  await page.evaluate(() => document.querySelector('[data-a11y-loop-sentinel]')?.remove());
+}
+
+/**
+ * Run the keyboard survey in a live page.
+ * @param {import('playwright').Page} page
+ */
+export async function surveyKeyboard(page) {
+  const expectedDetails = await page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    const nodes = window.tabbable ? window.tabbable.tabbable(helpers.tabbableRoot()) : [];
+    return nodes.map((el) => ({
+      selector: helpers.cssPath(el),
+      html: helpers.shortHtml(el),
+    }));
+  });
+
+  const positiveTabindex = await page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    return Array.from(document.querySelectorAll('[tabindex]'))
+      .filter((el) => helpers.isVisible(el))
+      .map((el) => ({
+        selector: helpers.cssPath(el),
+        html: helpers.shortHtml(el),
+        tabindex: el.getAttribute('tabindex'),
+      }));
+  });
+
+  await resetFocusToDocumentStart(page);
+
+  const observed = [];
+  const seen = new Set();
+  for (let i = 0; i < MAX_TAB_STEPS; i++) {
+    await page.keyboard.press('Tab');
+    const current = await page.evaluate(() => {
+      const el = document.activeElement;
+      if (!el || el === document.body || el === document.documentElement) return null;
+      if (el.hasAttribute?.('data-a11y-loop-sentinel')) return null;
+      return window.__a11yLoop.cssPath(el);
+    });
+    if (current === null) break;
+    if (seen.has(current)) break; // wrapped around
+    seen.add(current);
+    observed.push(current);
+  }
+
+  await clearFocusSentinel(page);
+
+  return {
+    expected: expectedDetails.map((d) => d.selector),
+    expectedDetails,
+    observed,
+    positiveTabindex,
+  };
+}

package/src/lib/checks/link-text.js

@@ -0,0 +1,83 @@
+/**
+ * Ambiguous link text (SC 2.4.4 Link Purpose (In Context), Level A).
+ *
+ * Cheap heuristic, deliberately narrow. "Read more" IS allowed by SC 2.4.4 when
+ * the surrounding context makes the destination clear, and only a human can say
+ * whether it does — so every finding here is needs-review, never a violation.
+ * The phrase list is kept short on purpose: a broad list produces noise, and
+ * noise is what makes agents ignore reports.
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+
+/** Exact accessible names treated as uninformative on their own. */
+export const AMBIGUOUS_PHRASES = ['click here', 'read more', 'learn more', 'here', 'more'];
+
+/**
+ * Normalise an accessible name for comparison: lowercase, strip surrounding
+ * punctuation and trailing chevrons/arrows, collapse whitespace.
+ */
+export function normalizeLinkText(text) {
+  if (typeof text !== 'string') return '';
+  return text
+    .toLowerCase()
+    .replace(/[→⇒›»>]+/g, ' ')
+    .replace(/[.!?:,;…]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** @returns {boolean} */
+export function isAmbiguousLinkText(text) {
+  return AMBIGUOUS_PHRASES.includes(normalizeLinkText(text));
+}
+
+/**
+ * @param {Array<{selector:string, html:string, name:string, context?:string}>} links
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function linkTextFindings(links = [], ctx) {
+  const { passes = [], state = null } = ctx ?? {};
+  return links
+    .filter((link) => isAmbiguousLinkText(link.name))
+    .map((link) =>
+      makeFinding({
+        ruleId: 'ambiguous-link-text',
+        source: 'a11y-loop',
+        severity: SEVERITY.NEEDS_REVIEW,
+        impact: 'moderate',
+        sc: '2.4.4',
+        selector: link.selector,
+        html: link.html,
+        message:
+          `Link text is "${link.name.trim()}", which does not describe the destination. ` +
+          'SC 2.4.4 allows this when the surrounding context supplies the purpose, and only a ' +
+          'human can judge that — so confirm the context, or name the destination in the link ' +
+          '(e.g. "Read more about the speaker line-up").',
+        passes,
+        state,
+        data: { name: link.name.trim(), context: link.context ?? null },
+      }),
+    );
+}
+
+/**
+ * Collect visible links and their accessible names.
+ * @param {import('playwright').Page} page
+ */
+export async function surveyLinks(page) {
+  return page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    return Array.from(document.querySelectorAll('a[href], [role="link"]'))
+      .filter((el) => helpers.isVisible(el))
+      .map((el) => ({
+        selector: helpers.cssPath(el),
+        html: helpers.shortHtml(el),
+        name: helpers.accessibleName(el),
+        context: (el.closest('li, p, td, h1, h2, h3, h4, section')?.textContent ?? '')
+          .replace(/\s+/g, ' ')
+          .trim()
+          .slice(0, 120),
+      }));
+  });
+}