pour-engine 1.30.0 → 1.31.1

package/config/project.config.js

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

package/engine/rules/best-practice/heading-order.js

@@ -1,8 +1,21 @@
+import { effectiveRole } from '../../lib/roles.js';
+
 const level = (el) =>
   el.hasAttribute('aria-level')
     ? parseInt(el.getAttribute('aria-level'), 10)
     : parseInt(el.tagName[1], 10) || 2; // role="heading" without aria-level defaults to 2
 
+// An honoured presentational role (or any other role override, e.g. role="tab")
+// removes the element from the page's heading outline: Chromium exposes no
+// heading node for <h3 role="none">, so it can neither skip a level nor set
+// the level the next heading is judged against. A null effective role means an
+// unknown explicit role, which browsers ignore in favour of the implicit one —
+// still a heading for everything this selector matches.
+const inOutline = (el) => {
+  const role = effectiveRole(el);
+  return role === 'heading' || role === null;
+};
+
 export default {
   id: 'heading-order',
   name: 'Heading order',
@@ -15,6 +28,7 @@ export default {
   evaluateAll(elements) {
     let previous = 0;
     return elements.map((element) => {
+      if (!inOutline(element)) return { status: 'pass' };
       const current = level(element);
       const skipped = previous > 0 && current > previous + 1;
       const outcome = skipped

package/engine/rules/best-practice/landmark-one-main.js

@@ -1,3 +1,5 @@
+import { collectRoots } from '../../lib/dom.js';
+
 export default {
   id: 'landmark-one-main',
   name: 'One main landmark',
@@ -9,8 +11,14 @@ export default {
   visibleOnly: false,
   evaluate(element, { isVisible }) {
     // Hidden mains (responsive/SPA double-renders kept display:none) are
-    // not exposed and must not count as duplicates.
-    const count = [...element.ownerDocument.querySelectorAll('main, [role="main"]')].filter(isVisible).length;
+    // not exposed and must not count as duplicates. The count spans every
+    // open shadow root: a web-component SPA whose only <main> renders
+    // inside its app shell's shadow tree HAS a main (measured on a live
+    // archive home, where the light-DOM-only count reported a false
+    // "no main" on a page whose shadow main is plainly exposed).
+    const count = collectRoots(element.ownerDocument)
+      .flatMap((root) => [...root.querySelectorAll('main, [role="main"]')])
+      .filter(isVisible).length;
     if (count === 1) return { status: 'pass' };
     return {
       status: 'fail',

package/engine/rules/best-practice/landmark-top-level.js

@@ -1,5 +1,8 @@
-// ARIA APG landmark pattern: banner, main, and contentinfo are page-level
-// regions — nesting them inside other landmarks breaks the page outline.
+// ARIA APG landmark pattern: banner, main, contentinfo and complementary
+// are page-level regions — nesting them inside other landmarks breaks the
+// page outline. Complementary joins via the aside demotion semantics in
+// lib/roles.js: only an aside that actually reaches the accessibility tree
+// as complementary owes top-levelness.
 import { implicitRole } from '../../lib/roles.js';
 
 const LANDMARK_ROLES = new Set([
@@ -25,9 +28,9 @@ export default {
   name: 'Top-level landmarks',
   impact: 'moderate',
   tags: ['best-practice'],
-  help: 'banner, main and contentinfo landmarks must be top level',
+  help: 'banner, main, contentinfo and complementary landmarks must be top level',
   helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
-  selector: 'header, footer, main, [role="banner"], [role="contentinfo"], [role="main"]',
+  selector: 'header, footer, main, aside, [role="banner"], [role="contentinfo"], [role="main"], [role="complementary"]',
   evaluate(element) {
     const tag = element.tagName.toLowerCase();
     // <header>/<footer> inside sectioning content are not landmarks at all.
@@ -35,9 +38,20 @@ export default {
         element.closest('article, aside, main, nav, section')) {
       return { status: 'pass' };
     }
+    // An <aside> is complementary only when implicitRole says so: unnamed
+    // inside sectioning content it is generic (Chromium exposes NO
+    // complementary node for a news home full of related-content asides,
+    // measured live) — there is no landmark to be top level. An aside
+    // directly inside <main> is NOT demoted (main is not sectioning
+    // content), so an ad-slot aside nested in main is a real finding.
+    if (tag === 'aside' && !element.hasAttribute('role') &&
+        implicitRole(element) !== 'complementary') {
+      return { status: 'pass' };
+    }
     const container = landmarkAncestor(element);
     if (!container) return { status: 'pass' };
-    const role = element.getAttribute('role') ?? { header: 'banner', footer: 'contentinfo', main: 'main' }[tag];
+    const role = element.getAttribute('role') ??
+      { header: 'banner', footer: 'contentinfo', main: 'main', aside: 'complementary' }[tag];
     return {
       status: 'fail',
       message: `This ${role} landmark is nested inside a ${container.role} landmark (<${container.element.tagName.toLowerCase()}>) — page-level regions lose their meaning when nested.`,

package/engine/rules/best-practice/redundant-image-alt.js

@@ -1,3 +1,36 @@
+// The question this rule answers: does the image's text alternative
+// duplicate text the control ALREADY announces beside it? Both halves of
+// that must be measured in accname terms, not raw DOM text:
+//  - The comparison text is the container's AT-exposed text (aria-hidden,
+//    hidden, display:none and visibility:hidden subtrees never reach the
+//    name — a display:none "Search" span does not make the alt redundant,
+//    it makes the alt the button's ONLY name, and advising alt="" there
+//    would delete it. Measured on a live banking home + Chromium AX tree.)
+//  - The alternative is alt when present, else title: HTML-AAM's fallback
+//    chain names an alt-less image from its title, so a card thumbnail
+//    whose title repeats the headline doubles the link name just the same
+//    (measured on a live news home where every card did exactly this).
+const HIDDEN_TAGS = new Set(['script', 'style', 'noscript', 'template']);
+
+/** The container's name-contributing text EXCLUDING image alternatives:
+ *  mirrors the accname content walk's hidden-content rules. */
+function exposedText(root) {
+  let text = '';
+  for (const node of root.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE) { text += node.textContent; continue; }
+    if (node.nodeType !== Node.ELEMENT_NODE) continue;
+    const tag = node.tagName.toLowerCase();
+    if (HIDDEN_TAGS.has(tag) || tag === 'img' || tag === 'area' || tag === 'svg') continue;
+    if (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden')) continue;
+    const style = getComputedStyle(node);
+    if (style.display === 'none' || style.visibility === 'hidden') continue;
+    text += exposedText(node);
+  }
+  return text;
+}
+
+const norm = (s) => (s ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+
 export default {
   id: 'redundant-image-alt',
   name: 'Redundant image alt',
@@ -5,17 +38,27 @@ export default {
   tags: ['best-practice'],
   help: 'Image alt should not repeat adjacent link or button text',
   helpUrl: 'https://www.w3.org/WAI/tutorials/images/functional/',
-  selector: 'a[href] img[alt], button img[alt]',
+  selector: 'a[href] img[alt], button img[alt], a[href] img[title]:not([alt]), button img[title]:not([alt])',
   evaluate(element) {
-    const alt = element.getAttribute('alt').replace(/\s+/g, ' ').trim().toLowerCase();
-    if (!alt) return { status: 'pass' };
+    const alt = element.getAttribute('alt');
+    const usesTitle = alt === null;
+    const alternative = norm(usesTitle ? element.getAttribute('title') : alt);
+    if (!alternative) return { status: 'pass' };
     const container = element.closest('a[href], button');
-    const text = container.textContent.replace(/\s+/g, ' ').trim().toLowerCase();
-    if (alt !== text) return { status: 'pass' };
+    const text = norm(exposedText(container));
+    // No exposed text: the image's alternative is the control's only name.
+    // Nothing is announced twice — and removing it would unname the control.
+    if (!text) return { status: 'pass' };
+    if (alternative !== text) return { status: 'pass' };
+    const kind = container.tagName === 'A' ? 'link' : 'button';
     return {
       status: 'fail',
-      message: `The image alt repeats the ${container.tagName === 'A' ? 'link' : 'button'} text — screen readers announce "${element.getAttribute('alt')}" twice.`,
-      fix: 'Use alt="" on the image; the visible text already names the control.',
+      message: usesTitle
+        ? `The image title repeats the ${kind} text — the title names the image, so screen readers announce "${element.getAttribute('title')}" twice.`
+        : `The image alt repeats the ${kind} text — screen readers announce "${element.getAttribute('alt')}" twice.`,
+      fix: usesTitle
+        ? 'Add alt="" to the image (and drop the title if it is not needed as a tooltip); the visible text already names the control.'
+        : 'Use alt="" on the image; the visible text already names the control.',
     };
   },
 };

package/engine/rules/best-practice/region.js

@@ -1,8 +1,17 @@
+// header/footer are banner/contentinfo ONLY outside sectioning content
+// (HTML-AAM; mirrored from lib/roles.js implicitRole): a footer buried in an
+// <article> is generic, so treating it as a landmark hid its stray content.
+// Divs do NOT demote — a header wrapped in plain divs is still a banner.
+// role="alertdialog" joins dialog: both are modal containers whose content
+// region navigation reaches through the dialog itself, and consent banners
+// (measured on a live news home) are exactly this shape.
 const LANDMARK =
-  'main, nav, header, footer, aside, form[aria-label], form[aria-labelledby], ' +
+  'main, nav, aside, form[aria-label], form[aria-labelledby], ' +
+  'header:not(:is(article, aside, main, nav, section) header), ' +
+  'footer:not(:is(article, aside, main, nav, section) footer), ' +
   'section[aria-label], section[aria-labelledby], [role="main"], [role="navigation"], ' +
   '[role="banner"], [role="contentinfo"], [role="complementary"], [role="region"], ' +
-  '[role="search"], [role="form"], [role="dialog"]';
+  '[role="search"], [role="form"], [role="dialog"], [role="alertdialog"]';
 
 export default {
   id: 'region',
@@ -29,8 +38,12 @@ export default {
     // Any perceivable content counts, not just text — but only content in
     // the accessibility tree: decorative images (alt="", presentation) and
     // unnamed inline svg are invisible to AT, so they can't be "unreachable".
+    // Bare form controls belong here too: an input has no text of its own,
+    // yet it is exactly the content a region-navigating user needs to reach
+    // (a booking form outside every landmark was invisible to this rule).
     const isMedia = element.matches(
-      'img:not([alt=""]):not([role="presentation"]):not([role="none"]), svg[role="img"], video, audio, canvas, iframe',
+      'img:not([alt=""]):not([role="presentation"]):not([role="none"]), svg[role="img"], video, audio, canvas, iframe, ' +
+        'input:not([type="hidden"]), select, textarea, button',
     );
     if (!ownText(element) && !isMedia) return { status: 'pass' };
     if (element.closest(LANDMARK)) return { status: 'pass' };

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

@@ -211,7 +211,26 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     // usually) belongs to the name rules, not to size judgment. Pointer-
     // invisible targets (clipped skip links etc.) are excluded the same
     // way, on both sides of the crowding test.
-    const laidOut = rects.map((r, i) => r.width > 0 && r.height > 0 && !isHiddenFromPointer(elements[i], r));
+    //
+    // Content-visibility-skipped subtrees have PLACEHOLDER geometry, not
+    // geometry: an offscreen article under content-visibility:auto skips
+    // layout, its 40×40 icon buttons measure 12×12 and stack on top of each
+    // other, and the rule read that as "tiny AND crowded" (measured live on
+    // a long-feed blog home: the same button is 40×40 the moment it scrolls
+    // into view). The browser itself knows the difference — checkVisibility
+    // with contentVisibilityAuto reports skipped subtrees as not visible —
+    // so those targets are unmeasurable in this state and sit out of the
+    // judgment AND the crowding field. Engines that don't recognise the
+    // option ignore unknown keys and behave as before.
+    const layoutSkipped = (element) => {
+      try {
+        return typeof element.checkVisibility === 'function'
+          && element.checkVisibility({ visibilityProperty: true })
+          && !element.checkVisibility({ contentVisibilityAuto: true, visibilityProperty: true });
+      } catch { return false; }
+    };
+    const laidOut = rects.map((r, i) =>
+      r.width > 0 && r.height > 0 && !isHiddenFromPointer(elements[i], r) && !layoutSkipped(elements[i]));
     const undersized = rects.map((r, i) => laidOut[i] && (r.width < min || r.height < min));
     // One rect fully inside another is one control drawn twice (stretched-
     // link cards, overlay + inner button) — not two targets crowding.

package/engine/rules/wcag/4.1.2-aria-label-misuse.js

@@ -45,9 +45,13 @@ export default {
   name: 'aria-label placement',
   impact: 'moderate',
   tags: ['wcag2a', 'wcag412'],
-  help: 'aria-label on a plain container is prohibited by ARIA, so its announcement is not guaranteed',
+  help: 'aria-label or aria-labelledby on a plain container is prohibited by ARIA, so its announcement is not guaranteed',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
-  selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex])',
+  // §5.2.8.6 prohibits BOTH naming attributes on generic — aria-labelledby
+  // pointing at perfectly real text is the same authoring error as an inline
+  // aria-label, and the more tempting one (a card labelled by its own title).
+  selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex]),'
+    + ' div[aria-labelledby]:not([role]):not([tabindex]), span[aria-labelledby]:not([role]):not([tabindex]), p[aria-labelledby]: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
@@ -55,9 +59,20 @@ export default {
     // 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' };
+    const label = element.getAttribute('aria-label');
+    const attempt = label !== null
+      ? `aria-label="${label}"`
+      : (() => {
+          const text = (element.getAttribute('aria-labelledby') ?? '').trim().split(/\s+/)
+            .map((id) => element.ownerDocument.getElementById(id)?.textContent?.trim())
+            .filter(Boolean).join(' ');
+          return text
+            ? `aria-labelledby (naming it "${text.slice(0, 80)}")`
+            : 'aria-labelledby (whose references resolve to no text)';
+        })();
     return {
       status: 'incomplete',
-      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard.`,
+      message: `${attempt} on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard.`,
       fix: 'If this element must reliably announce something of its own, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposure is guaranteed — or move the spoken text into visible or visually-hidden real text. If the label is stray, remove it. Do not add a role solely to legalise the label.',
     };
   },

package/package.json

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