pour-engine 1.35.5 → 1.37.0

package/config/project.config.js

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

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

@@ -2,7 +2,12 @@
 // 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 = {
+// Every row of ARIA 1.2's Required Owned Elements table; verify:aria-tables
+// diffs this map against the spec (2026-09-01, after feed and row were
+// found missing).
+export const REQUIRED_CHILDREN = {
+  feed: ['article'],
+  row: ['cell', 'columnheader', 'gridcell', 'rowheader'],
   list: ['listitem'],
   listbox: ['option', 'group'],
   menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'group'],

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

@@ -13,7 +13,13 @@
 // > group > treeitem exactly as authored). For the roles whose context does
 // not list group (listitem, tab, row, cell), group stays transparent as
 // before.
-const REQUIRED_PARENT = {
+// Every row of ARIA 1.2's Required Context Role table; verify:aria-tables
+// diffs this map against the spec (2026-09-01, after caption, columnheader
+// and rowheader were found missing).
+export const REQUIRED_PARENT = {
+  caption: ['figure', 'grid', 'table', 'treegrid'],
+  columnheader: ['row'],
+  rowheader: ['row'],
   listitem: ['list'],
   option: ['listbox', 'group'],
   menuitem: ['menu', 'menubar', 'group'],
@@ -27,7 +33,7 @@ const REQUIRED_PARENT = {
   gridcell: ['row'],
 };
 
-const IMPLICIT_CONTAINER = { ul: 'list', ol: 'list', menu: 'list', table: 'table', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup', tr: 'row' };
+const IMPLICIT_CONTAINER = { ul: 'list', ol: 'list', menu: 'list', table: 'table', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup', tr: 'row', figure: 'figure' };
 
 export default {
   id: 'aria-required-parent',

package/engine/rules/wcag/1.3.1-form-label.js

@@ -125,6 +125,23 @@ export default {
           : 'Put visible text inside the label.',
       };
     }
+    // A label points at this id, but the id is shared: for binds to the
+    // FIRST element with it, so this later twin has no label and no name
+    // even though a label sits beside it (hsbc.com download basket, two
+    // rows reusing one document id, 2026-09-01). The fix is a unique id,
+    // not another label.
+    if (element.id) {
+      const root = element.getRootNode();
+      const pointed = root.querySelector?.(`label[for="${CSS.escape(element.id)}"]`);
+      const first = root.getElementById?.(element.id);
+      if (pointed && first && first !== element) {
+        return {
+          status: 'fail',
+          message: `A <label for="${element.id}"> exists, but an earlier element on the page has the same id, so the label belongs to that one and this field has no label at all.`,
+          fix: `Give this field a unique id and point its label at that; ids must not repeat on a page.`,
+        };
+      }
+    }
     return {
       status: 'fail',
       message: 'This form field has no label — users cannot tell what to enter.',

package/engine/rules/wcag/1.3.1-table-headers.js

@@ -84,10 +84,16 @@ export default {
           message: 'This table has no header cells and its cells hold block content (headings, paragraphs, lists or forms), which is a layout-table signature. If it really presents data, mark its header cells with <th>; if it is layout scaffolding, add role="presentation".',
         };
       }
+      // A two-column table is a list of label-and-value pairs; its first
+      // column is the row headers, and that is the whole fix (gov.uk
+      // inheritance tax guidance, 2026-09-01: five such tables, all td).
+      const twoColumns = Math.max(0, ...rows.map((row) => row.cells.length)) === 2;
       return {
         status: 'fail',
         message: 'This looks like a data table but has no header cells — screen reader users get the data with no way to tell what each row/column means.',
-        fix: 'Mark header cells with <th> (add scope="col" or scope="row" when the table has both).',
+        fix: twoColumns
+          ? 'Mark the first cell of each row as <th scope="row">: in a two-column table the first column names what the second holds.'
+          : 'Mark header cells with <th> (add scope="col" or scope="row" when the table has both).',
       };
     }
     return { status: 'pass' };

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

@@ -40,6 +40,18 @@ const NAME_FROM_CONTENT = 'a[href], button, summary, h1, h2, h3, h4, h5, h6, th,
   + ' [role="checkbox"], [role="radio"], [role="switch"], [role="heading"],'
   + ' [role="cell"], [role="gridcell"], [role="columnheader"], [role="rowheader"], [role="tooltip"]';
 
+// ARIA 1.2's ten roles that prohibit naming, and the HTML elements that
+// carry them implicitly (HTML-AAM); verify:aria-tables diffs the set
+// against the spec. The rule started with div, span and p alone
+// (generic and paragraph); the other eight, explicit or as strong, em,
+// code, del, s, ins, sub and sup, joined 2026-09-01.
+export const NAME_PROHIBITED_ROLES = ['caption', 'code', 'deletion', 'emphasis', 'generic', 'insertion', 'paragraph', 'strong', 'subscript', 'superscript'];
+const IMPLICITLY_PROHIBITED = ['div', 'span', 'p', 'strong', 'em', 'code', 'del', 's', 'ins', 'sub', 'sup'];
+const SELECTOR = ['aria-label', 'aria-labelledby'].flatMap((attr) => [
+  ...IMPLICITLY_PROHIBITED.map((tag) => `${tag}[${attr}]:not([role]):not([tabindex])`),
+  ...NAME_PROHIBITED_ROLES.map((role) => `[role="${role}"][${attr}]:not([tabindex])`),
+]).join(', ');
+
 export default {
   id: 'aria-label-misuse',
   name: 'aria-label placement',
@@ -50,8 +62,7 @@ export default {
   // §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])',
+  selector: SELECTOR,
   evaluate(element) {
     // Inside a name-from-content ancestor the label is NOT ignored: accname
     // applies the whole algorithm to each descendant while building the
@@ -72,7 +83,7 @@ export default {
         })();
     return {
       status: 'incomplete',
-      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. Prohibited markup is not by itself a WCAG failure: the criterion that policed validity, 4.1.1 Parsing, was removed in WCAG 2.2 (w3.org/WAI/WCAG22/Understanding/parsing.html), so what decides this is what users actually hear.`,
+      message: `${attempt} on ${element.hasAttribute('role') ? `role="${element.getAttribute('role').trim()}"` : `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. Prohibited markup is not by itself a WCAG failure: the criterion that policed validity, 4.1.1 Parsing, was removed in WCAG 2.2 (w3.org/WAI/WCAG22/Understanding/parsing.html), so what decides this is what users actually hear.`,
       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/engine/rules/wcag/4.1.2-role-required-aria.js

@@ -1,13 +1,65 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
-// Roles that are meaningless without a state attribute alongside them.
-const REQUIRED = {
-  checkbox: 'aria-checked',
-  switch: 'aria-checked',
-  radio: 'aria-checked',
-  slider: 'aria-valuenow',
-  scrollbar: 'aria-valuenow',
-  combobox: 'aria-expanded',
+// Roles that are meaningless without a state or property alongside them.
+// The table is ARIA 1.2's "Required States and Properties" row for every
+// role that has one, read from the spec on 2026-09-01: checkbox, switch,
+// radio, menuitemcheckbox and menuitemradio need aria-checked; slider,
+// meter and scrollbar need aria-valuenow (scrollbar also aria-controls);
+// a SEPARATOR needs aria-valuenow only when it is focusable, because a
+// focusable separator is a resizing widget and a static one is a divider;
+// heading needs aria-level; combobox needs aria-expanded and aria-controls;
+// option needs aria-selected.
+//
+// Two of those properties are held at review rather than failed. Browsers
+// and screen readers get by without aria-controls (the relationship it
+// names is rarely announced, and a collapsed combobox has nothing to
+// control yet), and without aria-selected on an option (selection is
+// often conveyed by focus alone); the spec lists both, the DOM cannot
+// show a user is blocked, so the finding asks rather than asserts.
+export const REQUIRED = {
+  checkbox: ['aria-checked'],
+  switch: ['aria-checked'],
+  radio: ['aria-checked'],
+  menuitemcheckbox: ['aria-checked'],
+  menuitemradio: ['aria-checked'],
+  slider: ['aria-valuenow'],
+  meter: ['aria-valuenow'],
+  scrollbar: ['aria-valuenow', 'aria-controls'],
+  separator: ['aria-valuenow'],
+  heading: ['aria-level'],
+  combobox: ['aria-expanded', 'aria-controls'],
+  option: ['aria-selected'],
 };
+export const HELD_AT_REVIEW = new Set(['aria-controls', 'aria-selected']);
+
+// What each missing property costs the user, in the message.
+const COST = {
+  'aria-checked': "screen readers can't announce whether it is on or off",
+  'aria-valuenow': "screen readers can't announce its value or position",
+  'aria-level': 'browsers assume level 2 for a heading with no level, so the outline a screen reader user navigates by is a guess',
+  'aria-expanded': "screen readers can't announce whether its list is open",
+  'aria-controls': 'assistive technology has no link from the control to what it operates',
+  'aria-selected': 'a screen reader may not announce which option is selected',
+};
+
+// Native semantics supply the state regardless of WHICH state-bearing
+// role is claimed: HTML-AAM maps an input's checkedness to aria-checked
+// (input type=checkbox role="switch" — the standard toggle pattern —
+// exposes checked=false/true in the browser's tree with no ARIA at all),
+// a range input's or meter's value to aria-valuenow, a heading element's
+// rank to aria-level, an option's selectedness to aria-selected, and a
+// select's open state to aria-expanded.
+function suppliedNatively(element, attr) {
+  const tag = element.tagName;
+  const type = tag === 'INPUT' ? element.type : null;
+  switch (attr) {
+    case 'aria-checked': return type === 'checkbox' || type === 'radio';
+    case 'aria-valuenow': return type === 'range' || tag === 'METER' || tag === 'PROGRESS';
+    case 'aria-level': return /^H[1-6]$/.test(tag);
+    case 'aria-selected': return tag === 'OPTION';
+    case 'aria-expanded': return tag === 'SELECT';
+    default: return false;
+  }
+}
 
 export default {
   id: 'role-required-aria',
@@ -19,23 +71,31 @@ export default {
   selector: Object.keys(REQUIRED).map((role) => `[role="${role}"]`).join(', '),
   evaluate(element) {
     const role = element.getAttribute('role');
-    const required = REQUIRED[role];
-    if (element.hasAttribute(required)) return { status: 'pass' };
-    // Native semantics supply the state regardless of WHICH state-bearing
-    // role is claimed: HTML-AAM maps an input's checkedness to aria-checked
-    // (input type=checkbox role="switch" — the standard toggle pattern —
-    // exposes checked=false/true in the browser's tree with no ARIA at all),
-    // and a range input's value to aria-valuenow likewise.
-    const type = element.tagName === 'INPUT' ? element.type : null;
-    if (type === 'checkbox' || type === 'radio') {
-      if (required === 'aria-checked') return { status: 'pass' };
+    // A separator that cannot take focus is a static divider (an <hr> by
+    // another name) and requires nothing; only the focusable, moveable
+    // kind is a widget with a position to announce.
+    if (role === 'separator' && !(element.tabIndex >= 0)) return { status: 'pass' };
+    const missing = REQUIRED[role].filter((attr) => !element.hasAttribute(attr) && !suppliedNatively(element, attr));
+    if (!missing.length) return { status: 'pass' };
+    const failing = missing.filter((attr) => !HELD_AT_REVIEW.has(attr));
+    if (failing.length) {
+      const list = failing.join(' and ');
+      const why = role === 'separator'
+        ? `this separator takes focus, so it is a resizing widget, but without aria-valuenow ${COST['aria-valuenow']}`
+        : failing.map((attr) => COST[attr]).join('; ');
+      return {
+        status: 'fail',
+        message: `role="${role}" without ${list} — ${why}.`,
+        fix: `Add ${list} and keep it updated from your script, or use the native HTML element instead.`,
+      };
     }
-    if (type === 'range' && required === 'aria-valuenow') return { status: 'pass' };
-    if (element.tagName === 'SELECT' && role === 'combobox') return { status: 'pass' };
+    // Only review-held properties are missing. A collapsed combobox has no
+    // popup to point aria-controls at, so it is asked only while open.
+    if (role === 'combobox' && element.getAttribute('aria-expanded') !== 'true') return { status: 'pass' };
+    const list = missing.join(' and ');
     return {
-      status: 'fail',
-      message: `role="${role}" without ${required} — screen readers can't announce the control's state.`,
-      fix: `Add ${required} and keep it updated from your script, or use the native HTML element instead.`,
+      status: 'incomplete',
+      message: `role="${role}" without ${list}, which ARIA lists as required for the role — ${missing.map((attr) => COST[attr]).join('; ')}. Check the control is usable with a screen reader; adding ${list} settles it.`,
     };
   },
 };

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

@@ -1,7 +1,7 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
 import { attributesOf } from '../../lib/dom.js';
 // Concrete, usable roles — abstract roles are invalid in markup.
-const VALID_ROLES = new Set([
+export const VALID_ROLES = new Set([
   'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button',
   'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox', 'complementary',
   'contentinfo', 'definition', 'deletion', 'dialog', 'directory', 'document', 'emphasis',

package/package.json

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