pour-engine 1.19.0 → 1.21.0

package/engine/rules/wcag/3.2.2-on-input-navigation.js

@@ -0,0 +1,47 @@
+// WCAG SC 3.2.2 On Input (Level A) — plus the inline slice of 3.2.1 On Focus
+// The classic jump menu: <select onchange="location.href=this.value">.
+// Changing a setting must not change the user's context unless they were
+// told beforehand (3.2.2), and merely receiving focus must never do so at
+// all (3.2.1).
+//
+// Only INLINE handlers are visible to a DOM audit — addEventListener
+// registrations can't be enumerated — and only a navigation-shaped handler
+// body is evidence. That makes this a rare, legacy, high-precision
+// signature: pages that never use inline handlers produce zero findings.
+// Both branches ask rather than assert: the handler string proves a
+// navigation call EXISTS in the code path, not that it runs unconditionally
+// (it may sit behind a confirm(), a flag, or a selected-value check), and
+// for 3.2.2 whether the user "has been advised beforehand" is text on the
+// page only a human can weigh.
+// Writes and calls only: reading location (analytics, hash checks) is not
+// navigation, so the pattern demands an assignment to location or one of
+// the navigating members/calls.
+const NAVIGATES = /\blocation\s*(=|\.\s*(href|assign|replace|reload))|\.(submit|requestSubmit)\s*\(|window\.open\s*\(/;
+
+export default {
+  id: 'on-input-navigation',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag322', 'wcag321'],
+  help: 'Changing or focusing a control must not unexpectedly change context',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/on-input.html',
+  selector: 'select[onchange], input[onchange], textarea[onchange], select[oninput], input[oninput], textarea[oninput], [onfocus]',
+  evaluate(element) {
+    const onfocus = element.getAttribute('onfocus');
+    if (onfocus && NAVIGATES.test(onfocus)) {
+      return {
+        status: 'incomplete',
+        message: 'Focusing this element appears to navigate or submit (its onfocus handler reaches for location/submit). A change of context on focus alone fails WCAG 3.2.1 — check what the handler actually does when focus lands.',
+        fix: 'Trigger navigation from activation (click/Enter), never from focus.',
+      };
+    }
+    const onchange = element.getAttribute('onchange') ?? element.getAttribute('oninput');
+    if (onchange && NAVIGATES.test(onchange)) {
+      return {
+        status: 'incomplete',
+        message: 'Changing this control appears to navigate or submit (its onchange handler reaches for location/submit). WCAG 3.2.2 allows that only when users are told beforehand — check the page says so before the control.',
+        fix: 'Describe the behaviour before the control, or navigate from an explicit Go button instead of the change event.',
+      };
+    }
+    return { status: 'pass' };
+  },
+};

package/engine/rules/wcag/3.3.1-error-message-linkage.js

@@ -0,0 +1,69 @@
+// WCAG SC 3.3.1 Error Identification (Level A)
+// "If an input error is automatically detected, the item that is in error
+// is identified and the error is described to the user in text."
+//
+// A snapshot audit only ever sees this criterion in force when the page is
+// captured mid-error — a pristine form has no detected error and nothing to
+// judge. That makes the rule state-dependent and quiet by construction:
+// aria-invalid="true" IS the page saying "an error was detected here", and
+// from that admission two things become checkable.
+//
+//   - aria-errormessage must point at an element that exists, is visible,
+//     and says something (ARIA 1.2 requires the target to be displayed and
+//     pertinent while the field is invalid). A broken or empty target is a
+//     real authoring defect — the reference AT follows leads nowhere — but
+//     it is NOT a provable 3.3.1 failure: the Understanding document is
+//     explicit that programmatic association is not required, so adjacent
+//     visible text (which a machine cannot tie to the field) may satisfy
+//     the criterion on its own. Both shapes therefore go to review, with
+//     the broken reference named when present.
+//
+// aria-errormessage on a field that is NOT in an invalid state is inert:
+// user agents expose it only while the field is invalid, so a dangling
+// reference there breaks nothing a user receives (the engine's standing
+// inertness doctrine says pass, not assert). Invalid means any aria-invalid
+// value except false/undefined — "spelling" and "grammar" count.
+export default {
+  id: 'error-message-linkage',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag331'],
+  help: 'Fields marked invalid need their error described in text',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html',
+  selector: '[aria-invalid="true"], [aria-invalid="spelling"], [aria-invalid="grammar"], [aria-errormessage]',
+  evaluate(element, { isVisible, accessibleName }) {
+    const root = element.getRootNode();
+    const state = element.getAttribute('aria-invalid');
+    const invalid = !!state && state !== 'false' && state !== 'undefined';
+    const targetsOf = (attribute) => (element.getAttribute(attribute) ?? '')
+      .trim().split(/\s+/).filter(Boolean)
+      .map((id) => root.getElementById?.(id))
+      .filter(Boolean);
+    // An image-of-text error message still describes the error; textContent
+    // alone would miss it, so fall back to the accessible-name walk.
+    const hasText = (targets) => targets.some((target) =>
+      isVisible(target) && (target.textContent.trim() || accessibleName(target)));
+
+    if (element.hasAttribute('aria-errormessage')) {
+      if (!invalid) return { status: 'pass' }; // inert until the field is invalid
+      const targets = targetsOf('aria-errormessage');
+      if (hasText(targets)) return { status: 'pass' };
+      return {
+        status: 'incomplete',
+        message: (targets.length
+          ? 'This field is marked invalid, but the element its aria-errormessage points at is empty or hidden — screen readers follow the reference and find no text.'
+          : 'This field is marked invalid, but its aria-errormessage points at nothing — screen readers follow the reference and find no text.')
+          + ' The error must be described in text: check a visible message exists, and fix the reference so it reaches assistive technology too.',
+        fix: 'Point aria-errormessage at the visible element containing the error text, and keep that element populated while the field is invalid.',
+      };
+    }
+    // aria-invalid="true" with no aria-errormessage: a described-by message
+    // satisfies the criterion; with no linkage at all, the error may still
+    // sit in adjacent text only a human can connect to the field.
+    if (hasText(targetsOf('aria-describedby'))) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This field is marked invalid, but no error text is programmatically linked to it. The error must be described to the user in text — check a message exists, and associate it with aria-describedby or aria-errormessage so screen readers announce it with the field.',
+      fix: 'Add the error text near the field and reference it with aria-describedby (or aria-errormessage).',
+    };
+  },
+};

package/engine/rules/wcag/4.1.2-composite-widget-name.js

@@ -0,0 +1,32 @@
+// WCAG SC 4.1.2 Name, Role, Value (Level A)
+// The icon-only tab strip. Items of composite widgets — tabs, menu items,
+// options, tree items — take their name from their contents per ARIA 1.2,
+// and every one of these roles requires an accessible name. So an item
+// whose contents render no text and whose author supplied no label is
+// provably announced as an unnamed control: "tab", selected, of what?
+//
+// The container roles (tablist, menu, listbox, tree) are name-recommended
+// rather than required and are deliberately not judged here; the items are
+// where the binary, assertable failure lives.
+export default {
+  id: 'composite-widget-name',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag412'],
+  help: 'Tabs, menu items, options and tree items need an accessible name',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  selector: '[role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="treeitem"]',
+  evaluate(element, { accessibleName }) {
+    // <button role="tab"> and <a href role="tab"> are already selected by
+    // button-name/link-name (their selectors match the tag regardless of
+    // the role override) — one nameless control must not become two
+    // findings, so this rule owns only the div/span/li-style hosts.
+    if (element.matches('button, a[href], input, select, textarea, summary')) return { status: 'pass' };
+    if (accessibleName(element)) return { status: 'pass' };
+    const role = element.getAttribute('role');
+    return {
+      status: 'fail',
+      message: `This ${role} has no accessible name — a screen reader announces an unnamed ${role}, and users cannot tell what choosing it does.`,
+      fix: 'Put text inside the element, or add aria-label="…" for icon-only items.',
+    };
+  },
+};

package/engine/rules/wcag/4.1.2-summary-name.js

@@ -0,0 +1,31 @@
+// WCAG SC 4.1.2 Name, Role, Value (Level A)
+// <summary> is the interactive disclosure control of <details> — focusable,
+// activatable, exposed to AT as a button-like widget — and button-name's
+// selector never reaches it. An icon-only summary (chevron glyph, no text,
+// no label) announces as an unnamed control.
+//
+// Only the FIRST summary child of a <details> is the control: the HTML spec
+// gives any further summary elements, and summaries outside <details>, no
+// special behaviour — they are plain content and owe no name. A <details>
+// with no summary at all also passes: the browser supplies its own default
+// label ("Details").
+export default {
+  id: 'summary-name',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag412'],
+  help: 'Disclosure controls (<summary>) need an accessible name',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  selector: 'summary',
+  evaluate(element, { accessibleName }) {
+    const details = element.parentElement;
+    const isControl = details?.tagName === 'DETAILS'
+      && details.querySelector(':scope > summary') === element;
+    if (!isControl) return { status: 'pass' };
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This disclosure control has no accessible name — a screen reader announces an unnamed button, and users cannot tell what it expands.',
+      fix: 'Put text inside the <summary>, or add aria-label="…" for icon-only disclosures.',
+    };
+  },
+};

package/engine/wcag22.js

@@ -69,7 +69,7 @@ export default [
   sc('2.3.3', 'Animation from Interactions', 'AAA', 'manual', '2.1'),
   sc('2.4.1', 'Bypass Blocks', 'A', 'partial'), // partial: "repeated across pages" can't be established from one page
   sc('2.4.2', 'Page Titled', 'A', 'partial'), // partial: document-title proves a title exists and catches known placeholders; whether a real one DESCRIBES the page needs a reader
-  sc('2.4.3', 'Focus Order', 'A', 'manual'), // no rule automates this yet; order judgment needs humans
+  sc('2.4.3', 'Focus Order', 'A', 'partial'), // visual-order-divergence flags CSS order/*-reverse against DOM order; whether an order preserves MEANING stays human
   sc('2.4.4', 'Link Purpose (In Context)', 'A', 'partial'),
   sc('2.4.5', 'Multiple Ways', 'AA', 'manual'),
   sc('2.4.6', 'Headings and Labels', 'AA', 'manual'),
@@ -95,13 +95,13 @@ export default [
   sc('3.1.4', 'Abbreviations', 'AAA', 'manual'),
   sc('3.1.5', 'Reading Level', 'AAA', 'manual'),
   sc('3.1.6', 'Pronunciation', 'AAA', 'manual'),
-  sc('3.2.1', 'On Focus', 'A', 'manual'),
-  sc('3.2.2', 'On Input', 'A', 'manual'),
+  sc('3.2.1', 'On Focus', 'A', 'partial'), // on-input-navigation flags inline onfocus handlers that navigate; addEventListener handlers are invisible to a DOM audit
+  sc('3.2.2', 'On Input', 'A', 'partial'), // on-input-navigation flags the inline jump-menu signature; "advised beforehand" stays a human call
   sc('3.2.3', 'Consistent Navigation', 'AA', 'manual'),
   sc('3.2.4', 'Consistent Identification', 'AA', 'manual'),
   sc('3.2.5', 'Change on Request', 'AAA', 'manual'),
   sc('3.2.6', 'Consistent Help', 'A', 'manual', '2.2'),
-  sc('3.3.1', 'Error Identification', 'A', 'manual'),
+  sc('3.3.1', 'Error Identification', 'A', 'partial'), // error-message-linkage proves broken aria-errormessage targets; only in force when the page is captured mid-error
   sc('3.3.2', 'Labels or Instructions', 'A', 'partial'),
   sc('3.3.3', 'Error Suggestion', 'AA', 'manual'),
   sc('3.3.4', 'Error Prevention (Legal, Financial, Data)', 'AA', 'manual'),

package/package.json

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