pour-engine 1.27.0 → 1.29.0

package/config/project.config.js

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

package/engine/index.js

@@ -185,7 +185,9 @@ export async function run(context = document, options = {}, onProgress) {
 
     let outcomes;
     if (rule.evaluateAll) {
-      outcomes = rule.evaluateAll(elements, ruleHelpers);
+      // Awaiting a plain array is a no-op, so sync evaluateAll rules are
+      // untouched — async ones (the deferred-reference probe) resolve here.
+      outcomes = await rule.evaluateAll(elements, ruleHelpers);
     } else {
       // Evaluate sequentially with periodic yields so ONE heavy rule on a
       // huge element set can't freeze the page for its whole duration —

package/engine/lib/contrast.js

@@ -130,6 +130,7 @@ let opacityAnimatorsCache = null;
 let mediaRectsCache = null;
 let panelRectsCache = null;
 let pseudoCache = new WeakMap();
+let zeroClipCache = new WeakMap();
 const HAS_IMAGE = Symbol('background-image in chain');
 
 export function resetAuditCaches() {
@@ -139,6 +140,49 @@ export function resetAuditCaches() {
   mediaRectsCache = null;
   panelRectsCache = null;
   pseudoCache = new WeakMap();
+  zeroClipCache = new WeakMap();
+}
+
+/**
+ * True when the element sits inside a subtree erased by a ZERO-AREA clip —
+ * the sr-only recipe (clip: rect(0,0,0,0) / clip-path: inset(50%) on an
+ * absolutely positioned wrapper) applied to an ANCESTOR, which is where it
+ * usually lives: a chart's accessible data table hides the table, and the
+ * judged element is a cell inside it. Only provably zero-area patterns
+ * count: a clip rect with no width or height (any `auto` component keeps
+ * the element judged), or a percentage inset consuming a full axis.
+ * Partial clips never hide. Verdicts cache per ancestor, so a page pays
+ * per container, not per descendant.
+ */
+export function inZeroClipSubtree(element) {
+  for (let a = element; a; a = a.parentElement) {
+    let hidden = zeroClipCache.get(a);
+    if (hidden === undefined) {
+      const s = getComputedStyle(a);
+      hidden = false;
+      if (s.clip !== 'auto' && s.position !== 'static') {
+        const m = /rect\(([^)]+)\)/.exec(s.clip);
+        if (m) {
+          const parts = m[1].split(',').map((v) => v.trim());
+          if (!parts.includes('auto') && parts.length === 4) {
+            const [t, r, b, l] = parts.map(parseFloat);
+            if (r - l <= 0 || b - t <= 0) hidden = true;
+          }
+        }
+      }
+      if (!hidden && s.clipPath && s.clipPath !== 'none') {
+        const m = /inset\(([^)]+)\)/.exec(s.clipPath);
+        if (m && !m[1].includes('px')) {
+          const parts = m[1].trim().split(/\s+/).map(parseFloat);
+          const [t, r = t, b = t, l = r] = parts;
+          if (t + b >= 100 || l + r >= 100) hidden = true;
+        }
+      }
+      zeroClipCache.set(a, hidden);
+    }
+    if (hidden) return true;
+  }
+  return false;
 }
 
 /**

package/engine/rules/wcag/1.4.3-color-contrast.js

@@ -3,7 +3,7 @@ import {
   parseColor, contrastRatio, composite, effectiveBackground, backgroundObscured,
   backgroundImageSource, backgroundImagePaintRect, imagePaintRectInBox, imageLuminanceRange,
   gradientLuminanceRange, rangeVerdict, rangeWithBackdrop, isLargeText, cumulativeOpacity,
-  opacityAnimating, restingOpacity, mediaRects,
+  opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
   showRatio,
@@ -138,13 +138,15 @@ function textVisuallyHidden(element, style, foreground) {
   const indent = parseFloat(style.textIndent) || 0;
   const clipped = /hidden|clip/.test(`${style.overflow} ${style.overflowX} ${style.overflowY}`)
     || style.clipPath !== 'none' || (style.clip !== 'auto' && style.position === 'absolute');
-  // Nothing hints at hiding: skip the getBoundingClientRect layout read —
-  // this runs for every text element on the page, and most are plainly shown.
-  if (!clipped && Math.abs(indent) <= 1000) return false;
+  // Nothing on the element itself hints at hiding: the recipe may still sit
+  // on a WRAPPER (a chart's sr-only data table hides the table; the judged
+  // cell inside computes clip: auto) — the ancestor walk is cached per
+  // container, so this stays affordable on every text element.
+  if (!clipped && Math.abs(indent) <= 1000) return inZeroClipSubtree(element);
   const rect = element.getBoundingClientRect();
   if ((rect.width <= 1 || rect.height <= 1) && clipped) return true;
   if (Math.abs(indent) > rect.width && (clipped || Math.abs(indent) > 1000)) return true;
-  return false;
+  return inZeroClipSubtree(element);
 }
 
 // Turn a luminance-range bracket into a rule outcome (or null = can't tell).

package/engine/rules/wcag/4.1.2-aria-valid-refs.js

@@ -6,6 +6,105 @@ const REF_ATTRIBUTES = [
   'aria-activedescendant', 'aria-owns', 'aria-errormessage', 'aria-details',
 ];
 
+// Deferred-tooltip pattern: libraries (Deque's own docs component included)
+// write aria-describedby="tooltip7" at rest and only CREATE #tooltip7 when
+// the trigger is hovered or focused — which is exactly when a screen reader
+// announces the description, so the pattern works. Only DESCRIPTIVE refs
+// get this benefit of the doubt: a NAME that exists only on hover is broken
+// for rotor navigation even when the deferral works, so aria-labelledby
+// (and the rest) keep failing at rest.
+const PROBEABLE = new Set(['aria-describedby', 'aria-details']);
+// A handful of probes covers any real page; a template bug that dangles
+// fifty refs is broken enough that the un-probed remainder failing as
+// before is the right answer.
+const PROBE_BUDGET = 8;
+const PROBE_WAIT_MS = 250;
+
+/** Fire the events a tooltip library listens for, wait for it to react,
+ *  check whether the ids materialised, then put the page back. */
+async function probeDeferred(element, ids) {
+  const over = ['pointerover', 'mouseover', 'mouseenter'];
+  const out = ['pointerout', 'mouseout', 'mouseleave'];
+  for (const type of over) element.dispatchEvent(new MouseEvent(type, { bubbles: type !== 'mouseenter' }));
+  element.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+  try { element.focus?.({ preventScroll: true }); } catch { /* non-focusable */ }
+  await new Promise((resolve) => setTimeout(resolve, PROBE_WAIT_MS));
+  const root = element.getRootNode();
+  const appeared = ids.every((id) => root.getElementById?.(id));
+  // Restore: the audit must leave the page as it found it, and later rules
+  // must not meet a tooltip that only exists because we hovered.
+  for (const type of out) element.dispatchEvent(new MouseEvent(type, { bubbles: type !== 'mouseleave' }));
+  element.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
+  try { element.blur?.(); } catch { /* ignore */ }
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return appeared;
+}
+
+function inspect(element) {
+  // ARIA id references cannot cross shadow boundaries: they resolve only
+  // within the element's own root (document or shadow tree).
+  const root = element.getRootNode();
+  // Collapsed-disclosure pattern: a trigger with aria-expanded="false"
+  // whose aria-controls panel doesn't exist YET (rendered on expand) is
+  // ubiquitous and harmless while collapsed — name computation doesn't
+  // touch aria-controls, so nothing resolves wrongly today.
+  const collapsed = element.getAttribute('aria-expanded') === 'false';
+  const missing = [];
+  const ambiguous = [];
+  for (const attr of REF_ATTRIBUTES) {
+    for (const id of (element.getAttribute(attr) ?? '').split(/\s+/).filter(Boolean)) {
+      if (!root.getElementById?.(id)) {
+        if (attr === 'aria-controls' && collapsed) continue;
+        missing.push({ attr, id });
+        continue;
+      }
+      const count = root.querySelectorAll(`[id="${CSS.escape(id)}"]`).length;
+      if (count > 1) {
+        ambiguous.push(`${attr}="${id}" — ${count} elements share this id; the reference binds to the FIRST one in the DOM`);
+      }
+    }
+  }
+  return { missing, ambiguous };
+}
+
+function outcome({ missing, ambiguous }, probed, element, accessibleName) {
+  if (missing.length) {
+    // A dangling ref is skipped by the accname computation, so the HARM
+    // depends on what remains. A labelledby that dangles while the element
+    // still names itself (contents, aria-label) is inert clutter — real,
+    // fragile, validator-flagged, but announced correctly today. The same
+    // dangle on an otherwise nameless element is the 4.1.2 failure proper:
+    // names are consumed at REST (element lists, rotor), so the finding
+    // says which of the two this is instead of one blanket accusation.
+    const restingName = (accessibleName?.(element) ?? '').trim();
+    const detail = missing
+      .map(({ attr, id }) => {
+        if (attr === 'aria-labelledby') {
+          return restingName
+            ? `aria-labelledby="${id}" points to nothing — the reference is ignored and this element's name ("${restingName.slice(0, 40)}") currently comes from elsewhere; announced correctly today, but the dead reference is fragile`
+            : `aria-labelledby="${id}" points to nothing and leaves this element without an accessible name`;
+        }
+        return `${attr}="${id}" points to nothing — assistive technology silently ignores it`;
+      })
+      .join('; ');
+    return {
+      status: 'fail',
+      message: `Broken ARIA references: ${detail}.${probed ? ' Probed with focus and hover in case the target is created on demand — it never appeared.' : ''}`,
+      fix: 'Correct or remove the reference, or give the target element that id.',
+    };
+  }
+  if (ambiguous.length) {
+    // Duplicate ids resolve deterministically to the first copy — often
+    // the right one (desktop/mobile double-renders). Real, but a human
+    // must judge whether the first copy is the wrong copy.
+    return {
+      status: 'incomplete',
+      message: `Ambiguous ARIA references: ${ambiguous.join('; ')}. If the first copy in the DOM is the intended target, this works today — but it's fragile.`,
+    };
+  }
+  return { status: 'pass' };
+}
+
 export default {
   id: 'aria-valid-refs',
   // Moderate, not critical: with 4.1.1 Parsing retired in WCAG 2.2 these
@@ -16,46 +115,26 @@ export default {
   help: 'ARIA id references must point to elements that exist',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: REF_ATTRIBUTES.map((attr) => `[${attr}]`).join(', '),
-  evaluate(element) {
-    // ARIA id references cannot cross shadow boundaries: they resolve only
-    // within the element's own root (document or shadow tree).
-    const root = element.getRootNode();
-    // Collapsed-disclosure pattern: a trigger with aria-expanded="false"
-    // whose aria-controls panel doesn't exist YET (rendered on expand) is
-    // ubiquitous and harmless while collapsed — name computation doesn't
-    // touch aria-controls, so nothing resolves wrongly today.
-    const collapsed = element.getAttribute('aria-expanded') === 'false';
-    const missing = [];
-    const ambiguous = [];
-    for (const attr of REF_ATTRIBUTES) {
-      for (const id of (element.getAttribute(attr) ?? '').split(/\s+/).filter(Boolean)) {
-        if (!root.getElementById?.(id)) {
-          if (attr === 'aria-controls' && collapsed) continue;
-          missing.push(`${attr}="${id}" points to nothing — assistive technology silently ignores it`);
+  async evaluateAll(elements, { accessibleName } = {}) {
+    let budget = PROBE_BUDGET;
+    const outcomes = new Array(elements.length);
+    for (let i = 0; i < elements.length; i++) {
+      const element = elements[i];
+      const found = inspect(element);
+      const deferredOnly = found.missing.length > 0
+        && found.missing.every(({ attr }) => PROBEABLE.has(attr));
+      if (deferredOnly && budget > 0) {
+        budget--;
+        if (await probeDeferred(element, found.missing.map(({ id }) => id))) {
+          // The description materialises exactly when it would be announced.
+          outcomes[i] = { status: 'pass' };
           continue;
         }
-        const count = root.querySelectorAll(`[id="${CSS.escape(id)}"]`).length;
-        if (count > 1) {
-          ambiguous.push(`${attr}="${id}" — ${count} elements share this id; the reference binds to the FIRST one in the DOM`);
-        }
+        outcomes[i] = outcome(found, true, element, accessibleName);
+        continue;
       }
+      outcomes[i] = outcome(found, false, element, accessibleName);
     }
-    if (missing.length) {
-      return {
-        status: 'fail',
-        message: `Broken ARIA references: ${missing.join('; ')}.`,
-        fix: 'Correct or remove the reference, or give the target element that id.',
-      };
-    }
-    if (ambiguous.length) {
-      // Duplicate ids resolve deterministically to the first copy — often
-      // the right one (desktop/mobile double-renders). Real, but a human
-      // must judge whether the first copy is the wrong copy.
-      return {
-        status: 'incomplete',
-        message: `Ambiguous ARIA references: ${ambiguous.join('; ')}. If the first copy in the DOM is the intended target, this works today — but it's fragile.`,
-      };
-    }
-    return { status: 'pass' };
+    return outcomes;
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.27.0",
+  "version": "1.29.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",