pour-engine 1.1.6 → 1.1.8

package/config/project.config.js

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

package/engine/lib/roles.js

@@ -116,10 +116,34 @@ export function implicitRole(element) {
 }
 
 /** The element's effective role: explicit (first modelled token) or implicit. */
+/**
+ * Presentational Roles Conflict Resolution: a `presentation`/`none` role is
+ * DISCARDED when the element is focusable or carries a global ARIA property,
+ * and the implicit role is exposed instead. Reporting against the written role
+ * in those cases names a role the browser already threw away, and sends the
+ * author to fix the wrong thing.
+ *
+ * The two triggers below are what browsers actually implement, verified in
+ * Chromium's accessibility tree: `<h2 role="presentation">` exposes StaticText,
+ * but adding tabindex or aria-describedby exposes `heading`. Note a non-global
+ * property applicable to the implicit role (aria-level on a heading) does NOT
+ * trigger it, even though a strict reading of the spec suggests it should.
+ */
+function presentationDiscarded(element) {
+  if (element.tabIndex >= 0) return true;
+  if (element.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"]')) return true;
+  return [...GLOBAL_ARIA].some((name) => element.hasAttribute(`aria-${name}`));
+}
+
 export function effectiveRole(element) {
   const explicit = element.getAttribute('role')?.trim().split(/\s+/) ?? [];
   for (const token of explicit) {
-    if (ROLE_ARIA[token.toLowerCase()]) return token.toLowerCase();
+    const role = token.toLowerCase();
+    if (!ROLE_ARIA[role]) continue;
+    if ((role === 'presentation' || role === 'none') && presentationDiscarded(element)) {
+      return implicitRole(element);
+    }
+    return role;
   }
   return explicit.length ? null : implicitRole(element); // unknown explicit role: don't judge
 }

package/engine/rules/wcag/2.4.11-focus-not-obscured.js

@@ -1,12 +1,34 @@
 // WCAG SC 2.4.11 Focus Not Obscured (Minimum) (Level AA)
-// When a focusable element's box lies ENTIRELY under an opaque fixed or
-// sticky overlay at its resting position, focusing it shows the user
-// nothing — the criterion's core case (bottom cookie bars covering footer
-// links). Partial overlap passes 2.4.11 by definition ("not entirely
-// hidden"), so only full containment is judged, and only for elements
-// currently inside the viewport where the geometry is real.
+// An opaque fixed/sticky overlay covering a focusable element is the
+// criterion's core case (bottom cookie bars over footer links). Partial
+// overlap passes by definition ("not entirely hidden"), so only full
+// containment counts.
+//
+// This REVIEWS rather than fails, deliberately. What a snapshot can see is
+// "element X is under the panel right now", and that is a fact about the
+// current scroll position, not about the page: scrolling the same page a few
+// hundred pixels names entirely different elements, or none at all. The
+// criterion asks about the state focus ARRIVES in, which depends on tab order,
+// on whether the browser scrolls (it won't, for an element already inside the
+// viewport — merely covered), and on any author focus handler that moves the
+// page. None of that is knowable from geometry alone, so the honest output is
+// a pointer to the overlay and a request for a keyboard pass.
+//
+// Sites that apply the spec's own sufficient technique — scroll-padding for
+// the overlay's edge — are not flagged at all.
 const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]:not([tabindex="-1"])';
 
+/** Does the scroll container reserve room for an overlay on this edge?
+ *  scroll-padding is what the Understanding doc cites as sufficient: it keeps
+ *  the browser's own scroll-into-view clear of a sticky panel. */
+function edgeReserved(doc, edge, needed) {
+  const scroller = doc.scrollingElement ?? doc.documentElement;
+  const style = getComputedStyle(scroller);
+  const value = edge === 'top' ? style.scrollPaddingTop : style.scrollPaddingBottom;
+  const px = value && value.endsWith('px') ? parseFloat(value) : 0;
+  return px >= needed - 1;
+}
+
 export default {
   id: 'focus-not-obscured',
   impact: 'serious',
@@ -70,10 +92,16 @@ export default {
         !layer.contains(element) && !element.contains(layer)
         && isObscuringOverlay(layer) && covered(rect, layer.getBoundingClientRect()));
       if (!blocker) return { status: 'pass' };
+      // Which viewport edge is the panel pinned to? That is the edge the
+      // browser's scroll-into-view has to clear.
+      const panel = blocker.getBoundingClientRect();
+      const edge = panel.top <= 1 && panel.bottom < win.innerHeight ? 'top'
+        : panel.bottom >= win.innerHeight - 1 ? 'bottom' : null;
+      if (edge && edgeReserved(doc, edge, panel.height)) return { status: 'pass' };
       return {
-        status: 'fail',
-        message: 'This focusable element sits entirely behind an opaque fixed/sticky overlay — when keyboard focus lands on it, nothing visible changes and the user is lost.',
-        fix: 'Add scroll-padding for the overlay height, or make the overlay dismissible/non-overlapping so focused elements stay at least partly visible.',
+        status: 'incomplete',
+        message: 'This element is currently underneath an opaque fixed panel. Whether that breaks 2.4.11 depends on where the page sits when focus reaches it — the browser does not scroll an element that is already in the viewport, merely covered, so focus can land invisibly. Tab through the page and check the focus indicator is never entirely hidden.',
+        fix: `Reserve room for the panel with scroll-padding-${edge ?? 'bottom'} on the scrolling container, or move focus clear of it when the panel is up.`,
       };
     });
   },

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

@@ -38,6 +38,17 @@ function isHiddenFromPointer(element, rect) {
   return false;
 }
 
+/** Text this element contributes that is NOT inside a target — i.e. does it
+ *  read as prose beside the link, or is it just another control in a list? */
+function textOutsideTargets(element) {
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE && node.textContent.trim()) return true;
+    if (node.nodeType === Node.ELEMENT_NODE && !node.matches(TARGETS)
+      && textOutsideTargets(node)) return true;
+  }
+  return false;
+}
+
 function isInTextLine(element) {
   let node = element;
   // inline-block/inline-flex links inside a sentence are still "in a line
@@ -48,9 +59,17 @@ function isInTextLine(element) {
     for (const sibling of node.parentNode?.childNodes ?? []) {
       if (sibling === node) continue;
       if (sibling.nodeType === Node.TEXT_NODE && sibling.textContent.trim()) return true;
+      // What counts is text the sibling contributes OUTSIDE any target, not
+      // merely that the sibling isn't a target itself. Testing identity alone
+      // let a list of links exempt itself — each <li> is not an anchor, so a
+      // sibling <li><a>t</a></li> read as prose and granted the exception to
+      // the whole cluster, exactly the nav list this function's contract says
+      // to exclude (Wikipedia's "v · t · e" navbox slipped through there).
+      // Testing `querySelector(TARGETS)` instead over-corrects the other way:
+      // a prose wrapper containing a link is still prose.
       if (sibling.nodeType === Node.ELEMENT_NODE
         && !sibling.matches(TARGETS)
-        && sibling.textContent.trim()
+        && textOutsideTargets(sibling)
         && getComputedStyle(sibling).display.startsWith('inline')) return true;
     }
     node = node.parentElement;

package/engine/rules/wcag/4.1.2-valid-role.js

@@ -45,7 +45,12 @@ export default {
     // canonical harmless case. The failure worth reporting is an invalid
     // role MASKING real semantics or decorating an interactive element.
     const tag = element.tagName.toLowerCase();
-    const genericFallback = tag === 'div' || tag === 'span';
+    // What the element falls back to when the bogus role is ignored. div/span
+    // expose generic; <svg> exposes image (or graphics-document) in every
+    // current engine, which is what an author writing role="img"/"image" on it
+    // wanted anyway — so a typo there costs an AT user nothing. Elements with
+    // real semantics to mask (headings, lists, controls) stay out of the hatch.
+    const genericFallback = tag === 'div' || tag === 'span' || tag === 'svg';
     const focusable = element.tabIndex >= 0
       || element.matches('a[href], button, input, select, textarea, summary');
     const hasAriaProps = [...element.attributes].some(

package/package.json

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