pour-engine 1.16.0 → 1.18.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -93,6 +93,21 @@ export function contrastRatio(foreground, background) {
   return (lighter + 0.05) / (darker + 0.05);
 }
 
+/**
+ * Display a ratio truncated, never rounded up: 4.495 must read "4.49",
+ * because "4.50:1 — below the 4.5:1 minimum" reads as a contradiction.
+ * Shared by the rules and the /contrast/ checker so the two surfaces can
+ * never show the same ratio differently. Above 10 one decimal is plenty
+ * (no text threshold lives up there), and "21:1" reads better than
+ * "21.0:1" — a trailing zero implies precision the eye can use.
+ */
+export function showRatio(ratio) {
+  const text = ratio >= 10
+    ? (Math.floor(ratio * 10) / 10).toFixed(1)
+    : (Math.floor(ratio * 100) / 100).toFixed(2);
+  return text.replace(/\.0+$/, '');
+}
+
 /** Alpha-composite `top` over `bottom` (both {r,g,b,a}) → opaque colour. */
 export function composite(top, bottom) {
   const a = top.a + bottom.a * (1 - top.a);

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

@@ -52,7 +52,28 @@ export default {
       return !hasStrayText && effectiveChildren(child).every(isValidChild);
     };
     const invalid = effectiveChildren(element).filter((child) => !isValidChild(child));
-    if (!invalid.length) return { status: 'pass' };
+    if (!invalid.length) {
+      // Every rendered item neutralised: role="none" on each <li> strips
+      // its listitem semantics while the <ul> keeps announcing "list" —
+      // Chromium exposes the list role over the none children (measured
+      // 2026-08-09), so readers hear a list that owns zero items around
+      // content they can plainly see. That is the same broken announcement
+      // as <ul><div>, reached via a different door. A PARTIAL
+      // neutralisation stays valid: hiding a decorative separator item
+      // from the count is what role="none" on an <li> is for.
+      const renderedItems = effectiveChildren(element).filter((child) =>
+        child.tagName === 'LI' && (!isRendered || isRendered(child)));
+      const neutralised = renderedItems.filter((child) =>
+        ['presentation', 'none'].includes(child.getAttribute('role') ?? ''));
+      if (renderedItems.length && neutralised.length === renderedItems.length) {
+        return {
+          status: 'fail',
+          message: `Every item in this list carries role="${neutralised[0].getAttribute('role')}", so the list announces itself with zero items while ${renderedItems.length} are visible — screen readers lose the count and the positions.`,
+          fix: 'Remove the role from the <li> elements, or neutralise the whole structure by putting role="presentation" (or the intended widget role) on the list element itself.',
+        };
+      }
+      return { status: 'pass' };
+    }
     const tags = [...new Set(invalid.map((child) => {
       const role = child.getAttribute('role');
       return `<${child.tagName.toLowerCase()}${role ? ` role="${role}"` : ''}>`;

package/engine/rules/wcag/1.4.11-non-text-contrast.js

@@ -6,9 +6,7 @@
 // with placeholder text can conform with a faint border (#ccc borders are
 // endemic, WebAIM's own search field included), and that judgment needs
 // eyes. Focus-indicator contrast is not statically computable — manual.
-import { parseColor, contrastRatio, composite, effectiveBackground } from '../../lib/contrast.js';
-
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
+import { parseColor, contrastRatio, composite, effectiveBackground, showRatio } from '../../lib/contrast.js';
 
 export default {
   id: 'non-text-contrast',

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

@@ -6,11 +6,15 @@ import {
   opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
+  showRatio,
 } from '../../lib/contrast.js';
 
-/** Display a ratio truncated (never rounded up): 4.495 must read "4.49",
- *  because "4.50:1 — below the 4.5:1 minimum" reads as a contradiction. */
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
+/** Serialise a judged colour for the report and the checker link. Composited
+ *  channels keep up to two decimals: rounding them to integers changes the
+ *  pair enough that the checker scores a different ratio than the audit
+ *  reported (4.21 vs 4.19 on a 70%-opacity footer). */
+const channelText = (value) => String(Math.round(value * 100) / 100);
+const asRgb = (color) => `rgb(${channelText(color.r)}, ${channelText(color.g)}, ${channelText(color.b)})`;
 
 /** The one case a full-page veil still can't be judged for the author: the
  *  resting page and the dimmed one land on opposite sides of the threshold,
@@ -699,8 +703,10 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
           message: `Contrast is ${showRatio(haloRatio)}:1 against this text's own outline and ${showRatio(ratio)}:1 against the background — below the ${required}:1 WCAG minimum for this text size.`,
           fix: `Increase the difference between the text colour and its text-shadow outline (or the background) until the ratio reaches ${required}:1.`,
           data: {
-            foreground: style.color,
-            background: `rgb(${Math.round(halo.r)}, ${Math.round(halo.g)}, ${Math.round(halo.b)})`,
+            // The judged (composited) colour, not style.color: the checker
+            // link must score the pair the viewer actually sees.
+            foreground: asRgb(foreground),
+            background: asRgb(halo),
             ratio: Number(showRatio(haloRatio)),
             required,
           },
@@ -737,22 +743,44 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // carried alongside, never instead: a page written in oklch() or
     // color(srgb …) would otherwise be handed an rgb() value that appears
     // nowhere in its stylesheet.
-    const asRgb = (color) => `rgb(${Math.round(color.r)}, ${Math.round(color.g)}, ${Math.round(color.b)})`;
     const foregroundRgb = asRgb(foreground);
     const backgroundRgb = asRgb(background);
-    const foregroundCss = style.color !== foregroundRgb ? style.color : null;
+    // …but only when the authored string is the judged colour in another
+    // spelling. An authored colour that differs in VALUE (translucent text,
+    // an ancestor's opacity dimming the glyphs) still names what to search
+    // the stylesheet for, yet must never reach the checker link: the checker
+    // would score a pair the page never renders, showing a passing ratio for
+    // this very failure.
+    const sameValue = (css, judged) => {
+      const parsed = parseColor(css);
+      return parsed != null && parsed.a >= 1 && asRgb(parsed) === judged;
+    };
+    const authoredFg = style.color !== foregroundRgb ? style.color : null;
     const backgroundSource = backgroundColorSource(element);
-    const backgroundCss = backgroundSource && backgroundSource !== backgroundRgb ? backgroundSource : null;
+    const authoredBg = backgroundSource && backgroundSource !== backgroundRgb ? backgroundSource : null;
+    const foregroundCss = authoredFg && sameValue(authoredFg, foregroundRgb) ? authoredFg : null;
+    const backgroundCss = authoredBg && sameValue(authoredBg, backgroundRgb) ? authoredBg : null;
     const authored = [
-      foregroundCss && `the text as ${foregroundCss}`,
-      backgroundCss && `the background as ${backgroundCss}`,
+      authoredFg && `the text as ${authoredFg}`,
+      authoredBg && `the background as ${authoredBg}`,
     ].filter(Boolean).join(' and ');
+    // Say WHY the rendered colour differs when the mechanism is provable, so
+    // the author learns the cause along with the finding.
+    const parsedAuthoredFg = authoredFg && !foregroundCss ? parseColor(authoredFg) : null;
+    const dimmedNote = parsedAuthoredFg
+      ? (opacity < 1
+        ? ` The gap is opacity: this element or an ancestor renders at ${Math.round(opacity * 100)}% opacity, dimming the text to the sRGB value above.`
+        : (parsedAuthoredFg.a < 1
+          ? ' The text colour is translucent, so it composites with the background into the sRGB value above.'
+          : ''))
+      : '';
 
     return {
       status: 'fail',
       message: `Contrast is ${showRatio(ratio)}:1 — below the ${required}:1 WCAG minimum for this text size.`,
       fix: `Darken the text or lighten the background until the ratio reaches ${required}:1 (currently ${foregroundRgb} on ${backgroundRgb}).`
-        + (authored ? ` Your CSS writes ${authored}, so searching it for the sRGB values above won't find them.` : ''),
+        + (authored ? ` Your CSS writes ${authored}, so searching it for the sRGB values above won't find them.` : '')
+        + dimmedNote,
       // The exact pair, for the UIs to link out to an interactive checker.
       data: {
         foreground: foregroundRgb,

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

@@ -4,11 +4,9 @@
 // endemic ~2.8:1 gray-on-white) was previously never measured by any rule.
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
-  backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity,
+  backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity, showRatio,
 } from '../../lib/contrast.js';
 
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
-
 export default {
   id: 'control-contrast',
   impact: 'serious',

package/engine/rules/wcag/4.1.2-aria-field-name.js

@@ -7,7 +7,11 @@
 // naming counts. Toggle roles (checkbox/radio/switch) DO name from content.
 import { labelledByName } from '../../lib/accessible-name.js';
 
-const AUTHOR_ONLY = ['textbox', 'searchbox', 'combobox', 'listbox', 'spinbutton', 'slider'];
+// progressbar and meter belong here too: ARIA 1.2 marks both roles
+// "Accessible Name Required: True", they never name from content, and a
+// nameless one announces a bare value — "25%, progress bar" — of nothing
+// in particular (found live: unlabelled ant-progress widgets).
+const AUTHOR_ONLY = ['textbox', 'searchbox', 'combobox', 'listbox', 'spinbutton', 'slider', 'progressbar', 'meter'];
 const FROM_CONTENT = ['checkbox', 'radio', 'switch'];
 
 function authorName(element) {
@@ -21,7 +25,7 @@ export default {
   id: 'aria-field-name',
   impact: 'serious',
   tags: ['wcag2a', 'wcag412'],
-  help: 'ARIA form fields must have an accessible name',
+  help: 'ARIA fields and value widgets must have an accessible name',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: [...AUTHOR_ONLY, ...FROM_CONTENT]
     .map((role) => `[role="${role}"]:not(input):not(select):not(textarea)`)
@@ -42,7 +46,7 @@ export default {
     }
     return {
       status: 'fail',
-      message: `This role="${role}" field has no accessible name — screen readers announce the role with no idea what it's for.${
+      message: `This role="${role}" control has no accessible name — screen readers announce the role and value with no idea what it's for.${
         AUTHOR_ONLY.includes(role) ? ' (Content inside it does not count as a name for this role.)' : ''}`,
       fix: 'Add aria-label="…" or aria-labelledby pointing at its visible label.',
     };

package/package.json

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