pour-engine 1.10.0 → 1.12.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -111,7 +111,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
+| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
 **Totals:** 30 partially automated · 56 manual — with 74 rules.

package/engine/lib/contrast.js

@@ -650,7 +650,24 @@ export function paintedBackdrop(element) {
     if ((style.mixBlendMode && style.mixBlendMode !== 'normal')
       || (style.filter && style.filter !== 'none')
       || (style.backdropFilter && style.backdropFilter !== 'none')) return 'unresolved';
-    if (style.backgroundImage !== 'none') return { image: layer, scrim };
+    // An ancestor carrying a background-image is only this text's backdrop if
+    // that image actually paints where the text is. The element's own image is
+    // adjudicated upstream against its paint rect; ancestors were not, so a
+    // decorative 4px accent stripe down a callout's left edge counted as the
+    // backdrop for text sitting 44px to its right, and the stripe's colour
+    // then failed the whole paragraph. Adjudicate at the same point the hit
+    // test used: if the rect resolves and does not cover it, this image is not
+    // what is behind the glyphs, so fall through to the layer's own colour.
+    // An unresolvable rect keeps the old behaviour, which errs toward asking a
+    // human rather than asserting from geometry we could not compute.
+    if (style.backgroundImage !== 'none') {
+      const rects = backgroundImagePaintRects(layer);
+      // An unresolvable layer (null) counts as covering: not knowing where a
+      // layer paints is a reason to ask a human, never to rule it out.
+      const covers = (r) => !r
+        || (point.x >= r.left && point.x < r.right && point.y >= r.top && point.y < r.bottom);
+      if (!rects.length || rects.some(covers)) return { image: layer, scrim };
+    }
     let color = parseColor(style.backgroundColor);
     if (!color) return 'unresolved';
     // A layer's own opacity thins its paint. (Group opacity shared with the
@@ -918,6 +935,100 @@ export function imageLuminanceRange(url, overlays = []) {
  * clear text that never overlaps the image — e.g. external-link icons
  * painted in a link's right padding (Wikipedia-style).
  */
+/**
+ * Paint rect for EVERY layer of a background-image list, one entry per layer,
+ * null where a layer's geometry cannot be resolved.
+ *
+ * background-size/position/repeat are comma-separated lists that pair up with
+ * the image list, so a four-layer background can be four separate 1px lines —
+ * which is how design systems draw a tile's border without a border. Judging
+ * such a background as one blob meant text in the middle of a tile was ruled
+ * unjudgeable because of four hairlines around its edge.
+ *
+ * A layer resolves to null (unknown, treat as covering) when it tiles, when
+ * cover/contain hands sizing to an intrinsic this function does not have, or
+ * when its position is not a plain length or percentage.
+ */
+export function backgroundImagePaintRects(element) {
+  const style = getComputedStyle(element);
+  const images = splitLayers(style.backgroundImage);
+  if (!images.length) return [];
+  const box = element.getBoundingClientRect();
+  const sizes = splitLayers(style.backgroundSize);
+  const positions = splitLayers(style.backgroundPosition);
+  const repeats = splitLayers(style.backgroundRepeat);
+  const per = (list, i) => (list.length ? list[i % list.length] : undefined);
+
+  return images.map((image, i) => {
+    if (image === 'none') return { left: 0, top: 0, right: 0, bottom: 0 }; // paints nothing
+    const repeat = per(repeats, i) ?? 'repeat';
+    if (repeat !== 'no-repeat') return null; // may tile under the text
+    const size = per(sizes, i) ?? 'auto';
+    if (size === 'cover' || size === 'contain') return null;
+    const parts = splitParts(size);
+    const extent = (value, total) => {
+      if (value?.endsWith('px')) return parseFloat(value);
+      if (value?.endsWith('%')) return (parseFloat(value) / 100) * total;
+      return null; // 'auto' on a gradient means the full box, but only for a
+      // single-layer background; per-layer we decline rather than guess.
+    };
+    const width = extent(parts[0], box.width);
+    const height = extent(parts[1] ?? parts[0], box.height);
+    if (width === null || height === null
+      || Number.isNaN(width) || Number.isNaN(height)) return null;
+    const pos = splitParts(per(positions, i) ?? '0% 0%');
+    const offset = (value, total, span) => {
+      if (value?.endsWith('%')) return (parseFloat(value) / 100) * (total - span);
+      if (value?.endsWith('px')) return parseFloat(value);
+      return null;
+    };
+    const offsetX = offset(pos[0], box.width, width);
+    const offsetY = offset(pos[1] ?? '50%', box.height, height);
+    // NaN, not just null: `calc(100% - 1px)` is a real position a design
+    // system writes, and a NaN that escapes as a rect is worse than an
+    // unresolved one — it compares false against everything, so a genuine
+    // image backdrop would be silently ruled clear of the text.
+    if (offsetX === null || offsetY === null
+      || Number.isNaN(offsetX) || Number.isNaN(offsetY)) return null;
+    const left = box.left + offsetX;
+    const top = box.top + offsetY;
+    return { left, top, right: left + width, bottom: top + height };
+  });
+}
+
+/** Split a space-separated CSS value, keeping function calls whole. Splitting
+ *  `calc(100% - 1px)` on whitespace yields `calc(100%`, which parseFloat reads
+ *  as 100 and every guard downstream then trusts. */
+function splitParts(value) {
+  const out = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth += 1;
+    if (ch === ')') depth -= 1;
+    if (/\s/.test(ch) && depth === 0) { if (current) out.push(current); current = ''; continue; }
+    current += ch;
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+/** Split a comma-separated CSS list, ignoring commas inside parentheses. */
+function splitLayers(value) {
+  if (!value || value === 'none') return value === 'none' ? ['none'] : [];
+  const out = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth += 1;
+    if (ch === ')') depth -= 1;
+    if (ch === ',' && depth === 0) { out.push(current.trim()); current = ''; continue; }
+    current += ch;
+  }
+  if (current.trim()) out.push(current.trim());
+  return out;
+}
+
 export function backgroundImagePaintRect(element, intrinsic) {
   const style = getComputedStyle(element);
   if ((style.backgroundImage.match(/url\(|gradient\(/g) ?? []).length !== 1) return null;

package/engine/rules/index.js

@@ -42,10 +42,13 @@ import audioControl from './wcag/1.4.2-audio-control.js';
 import pauseStopHide from './wcag/2.2.2-pause-stop-hide.js';
 import mediaCaptions from './wcag/1.2.2-media-captions.js';
 import ariaAttrValid from './wcag/4.1.2-aria-attr-valid.js';
-// Demoted to best-practice: an unsupported ARIA attribute breaks an ARIA
+// Reviews rather than asserts: an unsupported ARIA attribute breaks an ARIA
 // author MUST (1.2 §8.6) but is INERT, so name, role and value all survive
-// and no success criterion fails (see the note in the rule file).
-import ariaAllowedAttr from './best-practice/aria-allowed-attr.js';
+// and no success criterion provably fails. It sits in the WCAG scope anyway,
+// because a real authoring error that a browser silently discards should not
+// be invisible in a default audit, and it asks whether the state is real
+// instead of claiming a failure (see the note in the rule file).
+import ariaAllowedAttr from './wcag/4.1.2-aria-allowed-attr.js';
 import ariaFieldName from './wcag/4.1.2-aria-field-name.js';
 // Demoted to best-practice: prohibited-but-inert ARIA on a generic element
 // fails no success criterion (see the note in the rule file).

package/engine/rules/{best-practice/aria-allowed-attr.js → wcag/4.1.2-aria-allowed-attr.js}

@@ -3,19 +3,25 @@
 // state or property". An unsupported attribute breaks that MUST, so this is a
 // real, provable authoring error and the rule asserts it.
 //
-// It is NOT a WCAG failure, which is why it lives here rather than under
-// 4.1.2. An unsupported attribute is INERT, measured in Chromium:
-// aria-expanded on a button exposes expanded=false, while the same attribute
-// on a complementary landmark exposes no state at all. It is dropped, not
-// misreported. So the role is still exposed, the name is still computed, and
-// nothing is announced incorrectly. Name, role and value all survive, which
-// is all 4.1.2 asks for.
+// It is not, on its own, a WCAG failure. An unsupported attribute is INERT,
+// measured in Chromium: aria-expanded on a button exposes expanded=true,
+// while the same attribute on complementary, heading or list exposes no
+// state at all. It is dropped, not misreported. So the role is still
+// exposed, the name is still computed, and nothing is announced incorrectly.
+// Name, role and value all survive, which is all 4.1.2 asks for.
 //
 // What CAN fail 4.1.2 is the thing underneath: if the element genuinely has
-// the state the author reached for, that state is now invisible. Whether it
-// does is exactly what the DOM cannot establish, so the message asks rather
-// than asserts. Reporting the ARIA error as a WCAG violation would have been
-// asserting a criterion failure off the back of a question.
+// the state the author reached for, that state is now invisible to a screen
+// reader. Whether it does is exactly what the DOM cannot establish.
+//
+// So this sits in the WCAG scope and REVIEWS rather than asserts. It lived
+// under best-practice before, which was defensible on the letter of 4.1.2
+// and wrong in practice: teams act on what a tool marks as WCAG, so a real
+// ARIA error that a browser silently discards went unseen in a default
+// audit. Asserting a violation would state a criterion failure the browser
+// does not actually cause; staying silent leaves a genuine authoring error
+// unreported. Asking is the honest third option, and it is the one the
+// engine is built around.
 //
 // Note "unsupported" is distinct from "prohibited" (§5.2.5), a separate
 // category about naming that this rule does not cover.
@@ -34,9 +40,9 @@ const HANDLED_ELSEWHERE = new Set(['label', 'labelledby']);
 export default {
   id: 'aria-allowed-attr',
   impact: 'moderate',
-  tags: ['best-practice'],
+  tags: ['wcag2a', 'wcag412'],
   help: 'ARIA attributes must be supported by the element’s role',
-  helpUrl: 'https://www.w3.org/TR/wai-aria-1.2/#state_property_processing',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: '*',
   visibleOnly: false,
   evaluate(element) {
@@ -60,8 +66,8 @@ export default {
     if (!disallowed.length) return { status: 'pass' };
     const names = disallowed.map((n) => `aria-${n}`);
     return {
-      status: 'fail',
-      message: `${names.join(', ')} is not supported on role "${role}", so the browser drops it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. If this element really does have that state, it is currently invisible to anyone using a screen reader.`,
+      status: 'incomplete',
+      message: `${names.join(', ')} is not supported on role "${role}", so the browser drops it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. Does this element really have that state? If it does, it is invisible to a screen reader and this is a 4.1.2 failure. If it does not, the attribute is simply stray and no one is affected.`,
       fix: `Move ${names.join('/')} to the element whose role supports it, usually the control that toggles this one, or remove it if the element has no such state. Adding a role to this element to make the attribute legal is rarely right: the host language restricts which roles each element may take.`,
     };
   },

package/package.json

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