pour-engine 1.6.0 → 1.7.0

package/config/project.config.js

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

package/engine/rules/best-practice/aria-label-misuse.js

@@ -5,6 +5,14 @@
 // component", so no success criterion (4.1.2 included) actually fails.
 // Best-practice scope is the honest home; demoted from WCAG scope after an
 // independent audit found it dominating WCAG results on news/commerce pages.
+/** Roles whose accessible name is built from their contents, so a label on
+ *  anything inside them contributes to that name rather than being dropped. */
+const NAME_FROM_CONTENT = 'a[href], button, summary, h1, h2, h3, h4, h5, h6, th, td,'
+  + ' [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"],'
+  + ' [role="menuitemradio"], [role="option"], [role="tab"], [role="treeitem"],'
+  + ' [role="checkbox"], [role="radio"], [role="switch"], [role="heading"],'
+  + ' [role="cell"], [role="gridcell"], [role="columnheader"], [role="rowheader"], [role="tooltip"]';
+
 export default {
   id: 'aria-label-misuse',
   impact: 'moderate',
@@ -13,6 +21,12 @@ export default {
   helpUrl: 'https://www.w3.org/TR/using-aria/#practical-support-aria-label-aria-labelledby-and-aria-describedby',
   selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex])',
   evaluate(element) {
+    // Inside a name-from-content ancestor the label is NOT ignored: accname
+    // applies the whole algorithm to each descendant while building the
+    // ancestor's name, so this label becomes the button's or link's name.
+    // Chromium reports exactly that. Claiming it does nothing is false, and
+    // the advised fix would delete the control's only name.
+    if (element.closest(NAME_FROM_CONTENT)) return { status: 'pass' };
     return {
       status: 'fail',
       message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> does nothing — screen readers only announce labels on interactive elements or landmarks.`,

package/engine/rules/best-practice/fieldset-legend.js

@@ -1,5 +1,6 @@
 // WAI forms tutorial: radio/checkbox groups need a group label — each
 // input's own label isn't enough to convey what the group asks.
+import { labelledByName } from '../../lib/accessible-name.js';
 export default {
   id: 'fieldset-legend',
   impact: 'moderate',
@@ -19,10 +20,20 @@ export default {
     for (const indexes of Object.values(groups)) {
       if (indexes.length < 2) continue;
       const first = elements[indexes[0]];
-      const fieldset = first.closest('fieldset');
-      const grouped =
-        (fieldset && fieldset.querySelector('legend')?.textContent.trim()) ||
-        first.closest('[role="group"][aria-label], [role="group"][aria-labelledby], [role="radiogroup"][aria-label], [role="radiogroup"][aria-labelledby]');
+      // A <fieldset> IS a group; it does not need role="group" written on it
+      // to be one, and a legend is one way to name it rather than the only
+      // way. Requiring an explicit role attribute reported a correctly named
+      // group as unlabelled, which the browser plainly contradicts.
+      // Name the GROUP the three ways a group can be named: its own legend,
+      // a reference, or a label. Not a general accessible-name call, which
+      // would fall through to name-from-contents and read the options inside
+      // the fieldset as if they were its name.
+      const group = first.closest('fieldset, [role="group"], [role="radiogroup"]');
+      const grouped = group && (
+        group.querySelector(':scope > legend')?.textContent.trim()
+        || labelledByName(group)
+        || group.getAttribute('aria-label')?.trim()
+      );
       if (grouped) continue;
       outcomes[indexes[0]] = {
         status: 'fail',

package/engine/rules/best-practice/redundant-aria-label.js

@@ -1,3 +1,14 @@
+import { effectiveRole } from '../../lib/roles.js';
+
+// "Redundant" only means anything for a role that takes its name FROM its
+// contents. A landmark is never named by the text inside it, and neither is
+// a select (its text is the option list), so an aria-label that happens to
+// match that text is the element's ONLY name. Removing it, as this rule
+// advises, leaves the element anonymous.
+const NAME_FROM_CONTENT = new Set(['button', 'link', 'menuitem', 'menuitemcheckbox',
+  'menuitemradio', 'option', 'tab', 'treeitem', 'checkbox', 'radio', 'switch', 'heading',
+  'cell', 'gridcell', 'columnheader', 'rowheader', 'tooltip']);
+
 export default {
   id: 'redundant-aria-label',
   impact: 'minor',
@@ -6,6 +17,7 @@ export default {
   helpUrl: 'https://www.w3.org/TR/using-aria/#rule2',
   selector: '[aria-label]',
   evaluate(element) {
+    if (!NAME_FROM_CONTENT.has(effectiveRole(element))) return { status: 'pass' };
     const label = element.getAttribute('aria-label').replace(/\s+/g, ' ').trim().toLowerCase();
     const visible = element.textContent.replace(/\s+/g, ' ').trim().toLowerCase();
     if (!visible || label !== visible) return { status: 'pass' };

package/engine/rules/wcag/1.3.1-aria-required-children.js

@@ -1,6 +1,7 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
 // Composite roles are meaningless without their required child roles —
 // role="list" with no listitems announces as an empty list.
+import { implicitRole } from '../../lib/roles.js';
 const REQUIRED_CHILDREN = {
   list: ['listitem'],
   listbox: ['option', 'group'],
@@ -15,30 +16,33 @@ const REQUIRED_CHILDREN = {
   rowgroup: ['row'],
 };
 
-const IMPLICIT = { li: 'listitem', option: 'option', tr: 'row', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup' };
-
 const roleOf = (element) =>
   element.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
-  IMPLICIT[element.tagName.toLowerCase()];
+  implicitRole(element);
 
 /**
- * The children a composite role OWNS in the accessibility tree — not the
- * DOM children. role="presentation"/"none" removes an element but leaves
- * its children in place, and role-less div/span wrappers are generic nodes
- * the required-ownership relation passes straight through (tabs inside a
- * styling wrapper inside a tablist are still the tablist's tabs).
+ * Everything the container could plausibly own: its whole subtree, plus any
+ * element it claims by aria-owns.
+ *
+ * This deliberately does not model ownership precisely. The rule's job is to
+ * catch a container that holds NONE of the children its role needs, which is
+ * what makes a screen reader announce an empty list. Enumerating which wrapper
+ * tags ownership passes through was the wrong shape for that: the allow-list
+ * held div and span only, so the ordinary tabs-in-list-items pattern was
+ * reported as a broken tablist. A required role anywhere inside means the
+ * container is not empty, and that is the only claim this rule should make.
  */
-function ownedChildren(element) {
-  const owned = [];
-  for (const child of element.children) {
-    if (child.matches('script, style, template')) continue;
-    const role = child.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase();
-    const passThrough = role === 'presentation' || role === 'none'
-      || (!role && (child.tagName === 'DIV' || child.tagName === 'SPAN'));
-    if (passThrough) owned.push(...ownedChildren(child));
-    else owned.push(child);
+function candidateDescendants(element) {
+  const found = [...element.querySelectorAll('*')].filter((el) => !el.matches('script, style, template'));
+  const owns = element.getAttribute('aria-owns');
+  if (owns) {
+    const root = element.getRootNode();
+    for (const id of owns.split(/\s+/).filter(Boolean)) {
+      const target = root.getElementById?.(id);
+      if (target) found.push(target, ...target.querySelectorAll('*'));
+    }
   }
-  return owned;
+  return found;
 }
 
 export default {
@@ -55,11 +59,13 @@ export default {
     const children = [...element.children].filter((c) => !c.matches('script, style, template'));
     // A completely empty container is a lazy-load placeholder more often
     // than a defect — it announces as an empty list, which is accurate.
-    if (!children.length) return { status: 'pass' };
-    if (ownedChildren(element).some((child) => required.includes(roleOf(child)))) return { status: 'pass' };
+    if (!children.length && !element.hasAttribute('aria-owns')) return { status: 'pass' };
+    if (candidateDescendants(element).some((child) => required.includes(roleOf(child)))) {
+      return { status: 'pass' };
+    }
     return {
       status: 'fail',
-      message: `role="${role}" contains no ${required.join('/')} children (not even through wrapper elements) — screen readers announce a broken, empty ${role}.`,
+      message: `role="${role}" contains no ${required.join('/')} anywhere inside it, and claims none by aria-owns — screen readers announce a broken, empty ${role}.`,
       fix: `Give the item elements role="${required[0]}", or remove role="${role}" from the container.`,
     };
   },

package/engine/rules/wcag/1.3.1-aria-required-parent.js

@@ -28,6 +28,16 @@ export default {
   evaluate(element) {
     const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
     const containers = REQUIRED_PARENT[role];
+    // aria-owns makes the relationship without containment: the owner can sit
+    // anywhere in the document and the browser still builds the structure.
+    // Judging by DOM ancestry alone failed every remotely-owned child.
+    if (element.id) {
+      const owner = element.getRootNode().querySelector?.(`[aria-owns~="${CSS.escape(element.id)}"]`);
+      const ownerRole = owner && (
+        owner.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase()
+        ?? IMPLICIT_CONTAINER[owner.tagName.toLowerCase()]);
+      if (ownerRole && containers.includes(ownerRole)) return { status: 'pass' };
+    }
     for (let parent = element.parentElement; parent; parent = parent.parentElement) {
       const parentRole =
         parent.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??

package/engine/rules/wcag/1.3.1-list-structure.js

@@ -1,5 +1,9 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
-const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE']);
+// Nothing here reaches the accessibility tree, so none of it can corrupt a
+// list's structure. STYLE belongs with them: CSS-in-JS libraries inject
+// <style> right where the markup sits, and it was being counted as a stray
+// child that broke the list.
+const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
 const ITEM_ROLES = ['listitem', 'presentation', 'none'];
 
 export default {
@@ -9,7 +13,7 @@ export default {
   help: 'Lists must only contain list items',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
   selector: 'ul, ol',
-  evaluate(element) {
+  evaluate(element, { isRendered }) {
     // A role attribute replaces the HTML list semantics — a <ul role="tablist">
     // is judged by ARIA structure rules, not HTML list rules.
     if (element.hasAttribute('role') && element.getAttribute('role') !== 'list') return { status: 'pass' };
@@ -29,6 +33,9 @@ export default {
     // genuinely corrupts the list.
     const isValidChild = (child) => {
       if (NEVER_RENDERED.has(child.tagName)) return true;
+      // A child the browser never renders is not in the accessibility tree
+      // either, so it cannot be corrupting the list a reader hears.
+      if (isRendered && !isRendered(child)) return true;
       // An explicit role REPLACES an <li>'s listitem semantics: a carousel
       // built as <ul> with <li role="group"> slides no longer owns any
       // listitems, so the list announces broken/empty. Only a role-less

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

@@ -15,15 +15,19 @@ export default {
     // List ownership passes through presentation/none wrappers and
     // role-less div/span grouping wrappers (generic nodes) — an <li> in a
     // framework's wrapping div inside a <ul> is still that list's item.
-    while (parent && (
+    // A list CONTAINER stops the walk even when it is itself presentational:
+    // ARIA propagates an explicit presentation role to a role's required
+    // 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';
+    while (parent && !listContainer(parent) && (
       ['presentation', 'none'].includes(parent.getAttribute('role') ?? '')
       || (!parent.hasAttribute('role') && (parent.tagName === 'DIV' || parent.tagName === 'SPAN'))
     )) {
       parent = parent.assignedSlot?.parentElement ?? parent.parentElement ?? parent.getRootNode()?.host;
     }
-    if (parent && (parent.matches('ul, ol, menu') || parent.getAttribute('role') === 'list')) {
-      return { status: 'pass' };
-    }
+    if (parent && listContainer(parent)) return { status: 'pass' };
     return {
       status: 'fail',
       message: `This <li> sits inside <${parent?.tagName.toLowerCase() ?? 'nothing'}> — outside a list, screen readers lose the item's list context entirely.`,

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

@@ -4,6 +4,7 @@
 // endemic ~2.8:1 gray-on-white) was previously never measured by any rule.
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
+  backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity,
 } from '../../lib/contrast.js';
 
 const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
@@ -28,14 +29,31 @@ export default {
     const rect = element.getBoundingClientRect();
     if (rect.width <= 1 || rect.height <= 1) return { status: 'pass' };
     const style = getComputedStyle(element);
+    // Judge the opacity the text RESTS at, matching the main contrast rule:
+    // a control faded out by an ancestor (fade-in-on-scroll, a collapsed
+    // panel) presents no text at all, and one held at a low opacity presents
+    // far less contrast than its declared colours suggest.
+    const opacity = opacityAnimating(element) ? restingOpacity(element) : cumulativeOpacity(element);
+    if (opacity < 0.05) return { status: 'pass' };
     // The control's own background wins; else whatever shows through it.
     const own = parseColor(style.backgroundColor);
-    const background = own && own.a >= 1
-      ? own
-      : (() => {
-        const behind = effectiveBackground(element);
-        return behind && own && own.a > 0 ? composite(own, behind) : behind;
-      })();
+    let background;
+    if (own && own.a >= 1) {
+      background = own;
+    } else {
+      // An image or gradient painted under a see-through control is a
+      // backdrop of pixels this rule cannot sample. The main rule samples
+      // them; here the honest answer is to hand it to a person rather than
+      // judge against the colour layer alone as if the image were not there.
+      if (backgroundImageSource(element)) {
+        return {
+          status: 'incomplete',
+          message: 'This field is see-through and sits over a background image or gradient, so its real text contrast depends on the pixels behind it. Check it by eye.',
+        };
+      }
+      const behind = effectiveBackground(element);
+      background = behind && own && own.a > 0 ? composite(own, behind) : behind;
+    }
     if (!background) {
       return { status: 'incomplete', message: 'The control’s background could not be determined — check its text contrast by eye.' };
     }
@@ -44,7 +62,10 @@ export default {
     const judge = (color, what) => {
       const parsed = parseColor(color);
       if (!parsed || parsed.a === 0) return null;
-      const fg = parsed.a < 1 ? composite(parsed, background) : parsed;
+      // Same treatment the main rule gives faded text: what reaches the eye
+      // is the declared colour thinned by the opacity it is painted at.
+      const faded = opacity < 1 ? { ...parsed, a: parsed.a * opacity } : parsed;
+      const fg = faded.a < 1 ? composite(faded, background) : faded;
       const ratio = contrastRatio(fg, background);
       if (ratio >= required) return null;
       return { what, ratio };

package/engine/rules/wcag/2.4.1-bypass-blocks.js

@@ -18,18 +18,41 @@ export default {
     const doc = element.ownerDocument;
     const roots = collectRoots(doc);
     const inAnyRoot = (selector) => roots.some((root) => root.querySelector?.(selector));
-    if (inAnyRoot('main, [role="main"]')) return { status: 'pass' };
+    // ARIA11 accepts landmarks generally, not the main landmark alone: a
+    // banner and a navigation region are exactly what landmark navigation
+    // skips between. Requiring `main` failed pages that were already using
+    // the technique the spec names.
+    const LANDMARKS = 'main, [role="main"], header, [role="banner"], nav, [role="navigation"],'
+      + ' aside, [role="complementary"], footer, [role="contentinfo"], [role="search"], form[role="search"]';
+    if (inAnyRoot(LANDMARKS)) return { status: 'pass' };
     if (inAnyRoot('h1, h2, h3, h4, h5, h6, [role="heading"]')) return { status: 'pass' };
+    // G1/G123/G124: ANY in-page link that resolves is a bypass mechanism.
+    // Reading only the first one hid a real skip link behind the href="#"
+    // that scripts use as a button.
     for (const root of roots) {
-      const firstLink = root.querySelector?.('a[href^="#"]');
-      const id = firstLink?.getAttribute('href').slice(1);
-      if (id && roots.some((r) => r.getElementById?.(id) || r.querySelector?.(`[id="${CSS.escape(id)}"]`))) {
-        return { status: 'pass' };
+      for (const link of root.querySelectorAll?.('a[href^="#"]') ?? []) {
+        const id = link.getAttribute('href').slice(1);
+        if (!id) continue;
+        if (roots.some((r) => r.getElementById?.(id) || r.querySelector?.(`[id="${CSS.escape(id)}"]`))) {
+          return { status: 'pass' };
+        }
       }
     }
+    // H64: a titled iframe is itself a way past the block it holds.
+    const frames = [...(doc.querySelectorAll('iframe, frame') ?? [])];
+    if (frames.length && frames.every((frame) => frame.getAttribute('title')?.trim())) {
+      return { status: 'pass' };
+    }
+    // The criterion governs "blocks of content that are repeated on multiple
+    // Web pages". One page cannot prove repetition, but it can show there is
+    // no block to bypass at all: a page with barely any links has nothing a
+    // reader would need to skip, and failing it names a duty that never
+    // applied.
+    const linkCount = roots.reduce((n, root) => n + (root.querySelectorAll?.('a[href], button').length ?? 0), 0);
+    if (linkCount < 4) return { status: 'pass' };
     return {
       status: 'fail',
-      message: 'No skip link, main landmark, or headings — keyboard users must Tab through the whole header/nav to reach anything.',
+      message: `This page has ${linkCount} links and buttons but no landmark, heading, skip link, or titled frame — keyboard and screen-reader users must go through the whole header and nav to reach anything.`,
       fix: 'Add a skip link like <a href="#content">Skip to content</a>, wrap primary content in <main>, or structure the page with headings.',
     };
   },

package/engine/rules/wcag/3.3.8-auth-field-obstruction.js

@@ -1,10 +1,16 @@
 // WCAG SC 3.3.8 Accessible Authentication (Minimum) (Level AA)
-// The SC requires a cognitive-function-test-free way to authenticate, and
-// names copy-paste and password managers as the mechanisms that provide
-// it. Blocking paste on a password/OTP field removes exactly that
-// mechanism — a provable failure. autocomplete="off" merely ASKS the
-// browser not to help; password managers often fill anyway, so that's a
-// review flag, not an assertion.
+// The SC permits a cognitive function test when the step offers an
+// Alternative, a Mechanism, Object Recognition, or Personal Content. Note 2
+// names TWO example mechanisms, separately: password-manager support, and
+// copy and paste.
+//
+// That separation is what this rule turns on. Blocking paste removes one of
+// the two, but a password manager fills a field programmatically and never
+// touches the clipboard, so the other mechanism usually survives — and a
+// page may also offer an Alternative (a passkey, a federated sign-in, an
+// emailed link) that this rule cannot see. Blocked paste is therefore
+// reported for REVIEW, not failed. Both mechanisms obstructed at once is the
+// case worth asserting.
 export default {
   id: 'auth-field-obstruction',
   impact: 'serious',
@@ -19,14 +25,23 @@ export default {
       const handler = element.getAttribute(attr) ?? '';
       return /return\s+false|preventDefault/.test(handler);
     });
-    if (blocking) {
+    const autocompleteOff = (element.getAttribute('autocomplete') ?? '').trim().toLowerCase() === 'off';
+    const action = blocking === 'onpaste' ? 'pasting' : 'dropping';
+    if (blocking && autocompleteOff) {
       return {
         status: 'fail',
-        message: `This authentication field blocks ${blocking === 'onpaste' ? 'pasting' : 'dropping'} — users of password managers must retype credentials from memory, a cognitive function test 3.3.8 forbids.`,
-        fix: 'Remove the paste/drop blocking; let password managers and copy-paste work.',
+        message: `This authentication field blocks ${action} AND sets autocomplete="off", so both of the mechanisms 3.3.8 names are obstructed at once: copy and paste, and password-manager entry. What is left is typing the credential from memory.`,
+        fix: 'Remove the paste/drop blocking, and drop autocomplete="off" so a password manager can fill the field.',
+      };
+    }
+    if (blocking) {
+      return {
+        status: 'incomplete',
+        message: `This authentication field blocks ${action}, which removes copy and paste, one of the two mechanisms 3.3.8 names. A password manager fills the field directly and is unaffected, so this is only a failure if nothing else here helps. Check whether a password manager can complete this login, or whether the page offers another way in such as a passkey or a federated sign-in.`,
+        fix: `Remove the ${action === 'pasting' ? 'paste' : 'drop'} blocking, or make sure another way to sign in is available that does not rely on recalling the credential.`,
       };
     }
-    if ((element.getAttribute('autocomplete') ?? '').trim().toLowerCase() === 'off') {
+    if (autocompleteOff) {
       return {
         status: 'incomplete',
         message: 'This authentication field sets autocomplete="off", discouraging password managers. Browsers often fill anyway — verify a password manager can complete this login without retyping.',

package/package.json

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