pour-engine 1.12.0 → 1.13.0

package/config/project.config.js

@@ -6,6 +6,6 @@
 export default {
   engine: {
     name: 'pour engine',
-    version: '1.12.0',
+    version: '1.13.0',
   },
 };

package/engine/rules/wcag/1.3.1-listitem-parent.js

@@ -20,7 +20,17 @@ export default {
     // owned elements, so the <li>s in a <ul role="none"> are presentational
     // too. There is no listitem left to be orphaned, and stepping over the
     // <ul> used to blame whatever happened to be above it.
-    const listContainer = (el) => el.matches('ul, ol, menu') || el.getAttribute('role') === 'list';
+    //
+    // Any OTHER explicit role replaces the native list semantics entirely:
+    // a <ul role="navigation"> is a navigation landmark, not a list, so it
+    // cannot own listitems and its <li> children are orphaned exactly as if
+    // the <ul> were a <div>. Matching the tag alone waved those through
+    // (found on ar.wikipedia.org: portal links in <ul role="navigation">).
+    const listContainer = (el) => {
+      const role = el.getAttribute('role');
+      if (el.matches('ul, ol, menu')) return !role || ['list', 'presentation', 'none'].includes(role);
+      return role === 'list';
+    };
     while (parent && !listContainer(parent) && (
       ['presentation', 'none'].includes(parent.getAttribute('role') ?? '')
       || (!parent.hasAttribute('role') && (parent.tagName === 'DIV' || parent.tagName === 'SPAN'))
@@ -28,10 +38,17 @@ export default {
       parent = parent.assignedSlot?.parentElement ?? parent.parentElement ?? parent.getRootNode()?.host;
     }
     if (parent && listContainer(parent)) return { status: 'pass' };
+    const parentLabel = parent
+      ? `<${parent.tagName.toLowerCase()}${parent.getAttribute('role') ? ` role="${parent.getAttribute('role')}"` : ''}>`
+      : 'nothing';
     return {
       status: 'fail',
-      message: `This <li> sits inside <${parent?.tagName.toLowerCase() ?? 'nothing'}> — outside a list, screen readers lose the item's list context entirely.`,
-      fix: 'Wrap it in a <ul> or <ol>, or change it to a <div>/<p> if it isn’t really a list item.',
+      message: `This <li> sits inside ${parentLabel} — ${parent?.matches('ul, ol, menu') && parent.getAttribute('role')
+        ? 'the explicit role replaces the list semantics, so'
+        : 'outside a list,'} screen readers lose the item's list context entirely.`,
+      fix: parent?.matches('ul, ol, menu') && parent.getAttribute('role')
+        ? 'Remove the role from the list (use a wrapping element for the landmark), or give the items roles the container expects.'
+        : 'Wrap it in a <ul> or <ol>, or change it to a <div>/<p> if it isn’t really a list item.',
     };
   },
 };

package/engine/rules/wcag/2.1.1-scrollable-region-focusable.js

@@ -1,17 +1,42 @@
 // WCAG SC 2.1.1 Keyboard (Level A) · SC 2.1.3 Keyboard (No Exception) (Level AAA)
+//
+// Matches EVERY element rather than a tag list: overflow makes a scroll
+// container out of whatever it lands on — nav, header, footer, form, table
+// wrappers, custom elements — and a tag list silently skipped all of them
+// (found on carbondesignsystem.com: a scrollable <nav> the rule never saw).
+// The cost stays flat because the overwhelming majority of elements exit on
+// two integer reads before any style or visibility work happens.
 const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]';
 
-/** Focusable content in the FLAT tree: the node's own descendants, nodes
+/** Reachable with the Tab key — what actually lets a keyboard user move
+ *  focus into the region and scroll it. Focusable-but-not-tabbable content
+ *  (tabindex="-1") does not help: measured in Chrome 151, a scroller whose
+ *  content is all tabindex="-1" is treated by the browser itself as holding
+ *  nothing reachable (it auto-focuses the scroller, same as when empty). */
+function isTabbable(element) {
+  if (element.tabIndex < 0 || element.disabled) return false;
+  if (typeof element.checkVisibility === 'function') {
+    return element.checkVisibility({ visibilityProperty: true });
+  }
+  return true;
+}
+
+/** Tabbable content in the FLAT tree: the node's own descendants, nodes
  *  slotted in from the light DOM, and content of open shadow roots. */
-function hasFocusableContent(node) {
-  if (node.querySelector?.(FOCUSABLE)) return true;
+function hasTabbableContent(node) {
+  for (const el of node.querySelectorAll?.(FOCUSABLE) ?? []) {
+    if (isTabbable(el)) return true;
+  }
   for (const slot of node.querySelectorAll?.('slot') ?? []) {
     for (const assigned of slot.assignedElements?.() ?? []) {
-      if (assigned.matches?.(FOCUSABLE) || assigned.querySelector?.(FOCUSABLE)) return true;
+      if ((assigned.matches?.(FOCUSABLE) && isTabbable(assigned))) return true;
+      for (const el of assigned.querySelectorAll?.(FOCUSABLE) ?? []) {
+        if (isTabbable(el)) return true;
+      }
     }
   }
   for (const el of node.querySelectorAll?.('*') ?? []) {
-    if (el.shadowRoot && hasFocusableContent(el.shadowRoot)) return true;
+    if (el.shadowRoot && hasTabbableContent(el.shadowRoot)) return true;
   }
   return false;
 }
@@ -22,27 +47,60 @@ export default {
   tags: ['wcag2a', 'wcag211', 'wcag213'], // 2.1.3 is 2.1.1's AAA twin — same check satisfies both
   help: 'Scrollable regions must be reachable by keyboard',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html',
-  selector: 'div, section, article, main, aside, ul, ol, dl, pre, output, figure',
-  evaluate(element) {
+  selector: '*',
+  // Visibility is checked inside, AFTER the cheap overflow gate: filtering
+  // every element of the page up front would cost a style read per element;
+  // gating first pays it only on the handful that actually overflow.
+  visibleOnly: false,
+  evaluate(element, { isVisible }) {
+    // Cheap-first: two integer reads reject almost every element with no
+    // style resolution at all. display:none subtrees have no layout, so
+    // both deltas are 0 and they exit here too.
+    const overflowsX = element.scrollWidth > element.clientWidth + 1;
+    const overflowsY = element.scrollHeight > element.clientHeight + 1;
+    if (!overflowsX && !overflowsY) return { status: 'pass' };
+    // The document scroller belongs to the browser: arrow keys scroll the
+    // page without any author-supplied focus stop. Overflow set on <body>
+    // can also propagate to the viewport, which is the same UA-owned
+    // scrollbar wearing different markup.
+    if (element === element.ownerDocument.documentElement || element === element.ownerDocument.body) {
+      return { status: 'pass' };
+    }
+    // A zero-extent box (a collapsed drawer at max-height: 0) presents no
+    // scrollable region — nothing of it is on screen to scroll. Its open
+    // state is a different audit state, judged when it is actually open.
+    if (!element.clientWidth || !element.clientHeight) return { status: 'pass' };
     const style = getComputedStyle(element);
     // Judged PER AXIS: an overflow the user can't scroll on its own axis
     // (overflow-x: hidden marquees whose overflow-y merely computes to
     // auto) is not a scrollable region — content moves by animation, not
     // by user scrolling.
-    const scrollableX = /(auto|scroll)/.test(style.overflowX)
-      && element.scrollWidth > element.clientWidth + 1;
-    const scrollableY = /(auto|scroll)/.test(style.overflowY)
-      && element.scrollHeight > element.clientHeight + 1;
+    const scrollableX = overflowsX && /(auto|scroll)/.test(style.overflowX);
+    const scrollableY = overflowsY && /(auto|scroll)/.test(style.overflowY);
     if (!scrollableX && !scrollableY) return { status: 'pass' };
+    if (!isVisible(element)) return { status: 'pass' };
     if (element.tabIndex >= 0) return { status: 'pass' };
-    // Focusable content inside lets keyboard users scroll by moving focus —
+    // Tabbable content inside lets keyboard users scroll by moving focus —
     // including content slotted in from the light DOM and content inside
     // open shadow roots (carousels built as web components).
-    if (hasFocusableContent(element)) return { status: 'pass' };
+    if (hasTabbableContent(element)) return { status: 'pass' };
+    // An explicit negative tabindex is the author OPTING OUT of the tab
+    // order, and the browser honours it: measured in Chrome 151, a scroller
+    // with tabindex="-1" is skipped by Tab even though the same scroller
+    // without the attribute would be auto-focused. Nothing inside is
+    // tabbable either, so the overflowed content is unreachable by keyboard
+    // in every engine — assertable, not browser-dependent.
+    if (element.hasAttribute('tabindex')) {
+      return {
+        status: 'fail',
+        message: 'This region scrolls, holds nothing tabbable, and its tabindex="-1" removes the region itself from the tab order — keyboard users cannot reach the overflowed content in any browser.',
+        fix: 'Change tabindex="-1" to tabindex="0" (plus role="region" and an aria-label describing it), or make something inside it tabbable.',
+      };
+    }
     // NOT a failure, because the browser may already have solved it.
     //
     // Chromium puts a scroll container in the tab order by itself when the
-    // container holds nothing focusable — and that condition is exactly the
+    // container holds nothing tabbable — and that condition is exactly the
     // one this rule fires on, so in Chrome every element reaching this line
     // IS keyboard reachable. Measured, not assumed: Chrome 151 tabs
     // before → the scroller → after, while `element.tabIndex` still reports
@@ -57,7 +115,7 @@ export default {
     // don't.
     return {
       status: 'incomplete',
-      message: 'This region scrolls and holds nothing focusable, so reaching its overflowed content depends on the browser. Chromium gives such containers keyboard focus automatically; not every engine does. Tab to it in the browsers you support, and add tabindex="0" if it cannot be reached.',
+      message: 'This region scrolls and holds nothing tabbable, so reaching its overflowed content depends on the browser. Chromium gives such containers keyboard focus automatically; not every engine does. Tab to it in the browsers you support, and add tabindex="0" if it cannot be reached.',
       fix: 'If you support browsers that do not focus scroll containers, add tabindex="0" (plus role="region" and an aria-label describing it).',
     };
   },

package/engine/rules/wcag/2.5.8-target-size.js

@@ -199,9 +199,183 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     const encloses = (a, b) =>
       a.left <= b.left && a.right >= b.right && a.top <= b.top && a.bottom >= b.bottom;
 
+    // ── Obscured targets ──────────────────────────────────────────────
+    // The criterion measures the region that ACCEPTS the pointer action.
+    // When another target paints over part of this one, clicks in the
+    // overlap go to the other target, so the accepting region is only the
+    // part left uncovered — a 26px logo link tiled 20px from the next link
+    // offers the pointer 20px, whatever its box says (found on ant.design).
+    // Box-sized-fine targets are therefore re-measured as the largest
+    // uncovered sub-rectangle before they may pass.
+    //
+    // Overlap only counts between targets that MOVE TOGETHER. A footer
+    // link sliding under a fixed header overlaps it at this scroll
+    // position and not the next, and asserting a size failure from scroll
+    // state invents a defect the layout does not have (the same trap the
+    // reachability test below documents). Targets share motion when they
+    // share a fixed/sticky context — both inside the same pinned bar, or
+    // neither pinned at all.
+    const fixedContexts = new Map();
+    const fixedContextOf = (element) => {
+      if (fixedContexts.has(element)) return fixedContexts.get(element);
+      let context = null;
+      for (let node = element; node && node !== element.ownerDocument.documentElement; node = node.parentElement) {
+        const position = getComputedStyle(node).position;
+        if (position === 'fixed' || position === 'sticky') { context = node; break; }
+      }
+      fixedContexts.set(element, context);
+      return context;
+    };
+    const overlapOf = (a, b) => {
+      const left = Math.max(a.left, b.left);
+      const top = Math.max(a.top, b.top);
+      const right = Math.min(a.right, b.right);
+      const bottom = Math.min(a.bottom, b.bottom);
+      // Only MATERIAL overlap obscures. A 1–2px intrusion is the border-
+      // collapse convention (button groups with negative margins) plus
+      // layout rounding — asserting a size failure from a 1px shave off a
+      // 24px control invents a defect no pointer will ever notice (seen
+      // live: a consent button measured 112×23 through a 1px overlap).
+      return right - left > 2 && bottom - top > 2
+        ? { left, top, right, bottom, width: right - left, height: bottom - top } : null;
+    };
+    /** Does target j's paint sit ABOVE target i where they overlap? The
+     *  paint stack at the overlap's midpoint answers it directly; the first
+     *  layer belonging to exactly one of the two decides. Off-viewport
+     *  points cannot be probed, and guessing from document order or
+     *  z-index is not evidence on pages full of stacking contexts
+     *  (transforms, opacity), so an unprovable overlap asserts nothing —
+     *  an audit run with the region scrolled into view proves it then. */
+    const paintsOver = (j, i, overlap) => {
+      const doc = elements[i].ownerDocument;
+      const win = doc.defaultView;
+      const x = overlap.left + overlap.width / 2;
+      const y = overlap.top + overlap.height / 2;
+      if (!win || typeof doc.elementsFromPoint !== 'function'
+        || x < 0 || y < 0 || x >= win.innerWidth || y >= win.innerHeight) return false;
+      for (const layer of doc.elementsFromPoint(x, y)) {
+        const inJ = elements[j] === layer || elements[j].contains(layer);
+        const inI = elements[i] === layer || elements[i].contains(layer);
+        if (inJ && !inI) return true;
+        if (inI && !inJ) return false;
+      }
+      return false; // neither reachable there — a third element's problem, not j's
+    };
+    /** Largest uncovered sub-rectangle after removing the overlap: the best
+     *  of the four slabs beside/above/below it (exact for one obscurer,
+     *  a safe under-approximation applied sequentially for several). */
+    const uncovered = (rect, overlap) => {
+      const slabs = [
+        { left: rect.left, top: rect.top, right: overlap.left, bottom: rect.bottom },
+        { left: overlap.right, top: rect.top, right: rect.right, bottom: rect.bottom },
+        { left: rect.left, top: rect.top, right: rect.right, bottom: overlap.top },
+        { left: rect.left, top: overlap.bottom, right: rect.right, bottom: rect.bottom },
+      ].map((s) => ({ ...s, width: s.right - s.left, height: s.bottom - s.top }))
+        .filter((s) => s.width >= 1 && s.height >= 1);
+      // Note: rect may be a DOMRect, whose properties do not survive object
+      // spread — the zero-rect is built from explicit reads.
+      if (!slabs.length) {
+        return { left: rect.left, top: rect.top, right: rect.left, bottom: rect.top, width: 0, height: 0 };
+      }
+      return slabs.reduce((best, s) => (s.width * s.height > best.width * best.height ? s : best));
+    };
+    // Spatial hash so finding overlap candidates stays near-linear on pages
+    // with tens of thousands of targets: only targets sharing a cell can
+    // intersect, so each target is tested against its cell-mates only.
+    const CELL = 256;
+    let cellIndex = null;
+    const cellsOf = (r) => {
+      const keys = [];
+      for (let cx = Math.floor(r.left / CELL); cx <= Math.floor(r.right / CELL); cx++) {
+        for (let cy = Math.floor(r.top / CELL); cy <= Math.floor(r.bottom / CELL); cy++) {
+          keys.push(`${cx}:${cy}`);
+        }
+      }
+      return keys;
+    };
+    const overlapCandidates = (i) => {
+      if (!cellIndex) {
+        cellIndex = new Map();
+        rects.forEach((r, j) => {
+          if (!laidOut[j]) return;
+          for (const key of cellsOf(r)) {
+            if (!cellIndex.has(key)) cellIndex.set(key, []);
+            cellIndex.get(key).push(j);
+          }
+        });
+      }
+      const seen = new Set();
+      for (const key of cellsOf(rects[i])) {
+        for (const j of cellIndex.get(key) ?? []) if (j !== i) seen.add(j);
+      }
+      return seen;
+    };
+    /** The pointer-accepting rect of a box-sized-fine target, reduced by
+     *  every overlapping target painted above it — or null when nothing
+     *  qualifying overlaps. */
+    const obscuredRect = (i) => {
+      let effective = null;
+      for (const j of overlapCandidates(i)) {
+        if (elements[j].contains(elements[i]) || elements[i].contains(elements[j])) continue; // same control, nested markup
+        if (encloses(rects[j], rects[i]) || encloses(rects[i], rects[j])) continue; // one control drawn twice
+        // Two links to the same place are one control in two boxes (a
+        // card's image link over its title link): clicks in the overlap
+        // land on the same destination, which is the criterion's
+        // "equivalent" case, provable here because the hrefs match.
+        if (typeof elements[i].href === 'string' && elements[i].href === elements[j].href) continue;
+        const overlap = overlapOf(effective ?? rects[i], rects[j]);
+        if (!overlap) continue;
+        if (fixedContextOf(elements[j]) !== fixedContextOf(elements[i])) continue; // scroll-state, not layout
+        if (!paintsOver(j, i, overlap)) continue;
+        effective = uncovered(effective ?? rects[i], overlap);
+      }
+      return effective;
+    };
+
     return elements.map((element, i) => {
       if (!laidOut[i]) return { status: 'pass' }; // not laid out / not a pointer target
-      if (!undersized[i]) return { status: 'pass' };
+      if (!undersized[i]) {
+        // Box is big enough — but the pointer only gets the uncovered part.
+        const effective = obscuredRect(i);
+        if (!effective || (effective.width >= min && effective.height >= min)) return { status: 'pass' };
+        if (isInTextLine(element)) return { status: 'pass' };
+        // A target the pointer never actually hits is a keyboard
+        // affordance, not a pointer target — an in-flow skip link whose
+        // box sits beneath the header's paint (python.org's is hit-tested
+        // to its container at every probe point). Probed per fragment:
+        // if every in-viewport probe misses the element, pointers never
+        // interact with it and its pointer size is nobody's defect.
+        // (Hit-tests paid only here, on candidate failures.)
+        const everHit = (() => {
+          const doc = element.ownerDocument;
+          const win = doc.defaultView;
+          if (!win || typeof doc.elementsFromPoint !== 'function') return true;
+          const fragments = [...element.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+          let tested = false;
+          for (const fragment of (fragments.length ? fragments : [rects[i]])) {
+            const x = fragment.left + fragment.width / 2;
+            const y = fragment.top + fragment.height / 2;
+            if (x < 0 || y < 0 || x >= win.innerWidth || y >= win.innerHeight) continue;
+            tested = true;
+            if (doc.elementsFromPoint(x, y).includes(element)) return true;
+          }
+          return !tested; // nothing probe-able → don't know → don't silence
+        })();
+        if (!everHit) return { status: 'pass' };
+        // The spacing exception cannot apply: the obscuring target is at
+        // distance zero. UA-control cannot either: the browser sized the
+        // box, but the author's layout took part of it away.
+        const rect = rects[i];
+        return {
+          status: 'fail',
+          message: `This target's box is ${Math.round(rect.width)}×${Math.round(rect.height)}px, but another target overlaps it and clicks in the overlap go there — the part that still accepts the pointer is ${Math.round(effective.width)}×${Math.round(effective.height)}px, below the ${min}×${min}px minimum.`,
+          fix: 'Space the targets so they no longer overlap, or enlarge this one until the uncovered part reaches the minimum.',
+          data: {
+            box: { width: Math.round(rect.width), height: Math.round(rect.height) },
+            effective: { width: Math.round(effective.width), height: Math.round(effective.height) },
+          },
+        };
+      }
       if (uaControlled(element)) return { status: 'pass' }; // UA Control exception
       if (isInTextLine(element)) return { status: 'pass' };
       if (spacingException) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Accessibility (WCAG 2.2) audit engine written from the W3C specifications — runs entirely in the browser, no dependencies.",
   "type": "module",
   "main": "engine/index.js",