pour-engine 1.1.0

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

@@ -0,0 +1,109 @@
+// WCAG SC 1.4.11 Non-text Contrast (Level AA)
+// The automatable slice: whether a form field's fill or border reaches 3:1
+// against its surroundings. Verdicts are pass or NEEDS-REVIEW, never fail:
+// per the Understanding document a boundary is only required when it is
+// the visual information needed to IDENTIFY the field — a labelled field
+// 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);
+
+export default {
+  id: 'non-text-contrast',
+  impact: 'serious',
+  tags: ['wcag21aa', 'wcag1411'],
+  help: 'Form fields and icons need a 3:1 visible boundary',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html',
+  selector:
+    'input:not([type="hidden"]):not([type="checkbox"]):not([type="radio"]):not([type="submit"])'
+    + ':not([type="button"]):not([type="reset"]):not([type="image"]), select, textarea',
+  visibility: 'visual',
+  evaluate(element) {
+    // Inactive controls are exempt (same carve-out 1.4.3 makes).
+    if (element.disabled || element.closest('[aria-disabled="true"]')) return { status: 'pass' };
+    // Zero-area controls (JS-widget hidden duplicates) paint no boundary
+    // to judge.
+    const ownRect = element.getBoundingClientRect();
+    if (ownRect.width <= 1 || ownRect.height <= 1) return { status: 'pass' };
+    const style = getComputedStyle(element);
+    // A native default-styled control's boundary comes from the UA.
+    if (style.appearance !== 'none' && element.tagName === 'SELECT') return { status: 'pass' };
+    const surrounding = effectiveBackground(element.parentElement ?? element);
+    if (!surrounding) {
+      return { status: 'incomplete', message: 'The background around this field could not be determined — check the field has a visible boundary by eye.' };
+    }
+    // Every candidate boundary colour, translucents composited over the
+    // surroundings so a 30%-white border on blue is judged as the lighter
+    // blue the user actually sees.
+    const boundaries = [];
+    let translucentSeen = false;
+    const fill = parseColor(style.backgroundColor);
+    if (fill && fill.a > 0) {
+      boundaries.push(fill.a >= 1 ? fill : composite(fill, surrounding));
+      if (fill.a < 1) translucentSeen = true;
+    }
+    let hasBorder = false;
+    for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+      if (parseFloat(style[`border${side}Width`]) <= 0) continue;
+      if (style[`border${side}Style`] === 'none') continue;
+      hasBorder = true;
+      const color = parseColor(style[`border${side}Color`]);
+      if (!color || color.a === 0) continue;
+      boundaries.push(color.a >= 1 ? color : composite(color, surrounding));
+      if (color.a < 1) translucentSeen = true;
+    }
+    const best = Math.max(1, ...boundaries.map((color) => contrastRatio(color, surrounding)));
+    if (best >= 3) return { status: 'pass' };
+    // Box-shadow outlines and background images can also draw the boundary;
+    // those aren't statically comparable — abstain rather than assert.
+    if (style.boxShadow !== 'none' || style.backgroundImage !== 'none') {
+      return {
+        status: 'incomplete',
+        message: 'This field’s boundary may come from a box-shadow or background image — check it reaches 3:1 against the page by eye.',
+      };
+    }
+    // Translucent layers compound (a tinted fill under a tinted border):
+    // the compositing above is per-layer, so a near-miss stays a human call.
+    if (translucentSeen) {
+      return {
+        status: 'incomplete',
+        message: `This field's boundary uses translucent colours and reaches about ${showRatio(best)}:1 against the page — near the 3:1 minimum; check by eye.`,
+      };
+    }
+    // Input-group pattern: a borderless input inside a wrapper that carries
+    // the visible boundary (border, or a fill contrasting with the page
+    // around it). The FIELD the user perceives is the wrapper — but only a
+    // SNUG wrapper counts: a page section's border is not a field boundary.
+    for (let wrapper = element.parentElement, depth = 0; wrapper && depth < 2; wrapper = wrapper.parentElement, depth++) {
+      const wrapperRect = wrapper.getBoundingClientRect();
+      if (wrapperRect.height > ownRect.height + 24 || wrapperRect.width > ownRect.width + 160) break;
+      const wrapperStyle = getComputedStyle(wrapper);
+      const wrapperHasBorder = ['Top', 'Right', 'Bottom', 'Left'].some((side) =>
+        parseFloat(wrapperStyle[`border${side}Width`]) > 0 && wrapperStyle[`border${side}Style`] !== 'none'
+        && (parseColor(wrapperStyle[`border${side}Color`])?.a ?? 0) > 0);
+      if (wrapperHasBorder) return { status: 'pass' };
+      const wrapperFill = parseColor(wrapperStyle.backgroundColor);
+      if (wrapperFill && wrapperFill.a >= 1) {
+        const around = effectiveBackground(wrapper.parentElement ?? wrapper);
+        if (around && contrastRatio(wrapperFill, around) >= 3) return { status: 'pass' };
+        break; // opaque wrapper IS the visual field and it doesn't contrast — judge as found
+      }
+    }
+    // Per the Understanding document, a boundary is only REQUIRED when it
+    // is the visual information needed to identify the field — a clearly
+    // labelled field with placeholder text inside it can conform without
+    // one. That judgment needs human eyes, so this rule never asserts.
+    if (!hasBorder && (!fill || fill.a === 0)) {
+      return {
+        status: 'incomplete',
+        message: 'This field has no border and no distinct fill — if its label and layout don’t already make it findable, low-vision users can’t locate it. Check by eye (3:1 boundary or clear identification needed).',
+      };
+    }
+    return {
+      status: 'incomplete',
+      message: `This field's boundary reaches only ${showRatio(best)}:1 against the page — below the 3:1 minimum. That’s conformant ONLY if the field is identifiable without the boundary (visible label, placeholder position); check by eye.`,
+    };
+  },
+};

package/engine/rules/wcag/1.4.12-text-spacing.js

@@ -0,0 +1,71 @@
+// WCAG SC 1.4.12 Text Spacing (Level AA)
+// Active probe, in the spirit of the criterion's own test procedure: apply
+// the SC's exact spacing overrides and check that no text gets cut off.
+// The override is injected and removed inside one synchronous pass — the
+// engine only yields to the renderer between rules, so the page never
+// paints the probed state.
+const OVERRIDE = `* {
+  line-height: 1.5 !important;
+  letter-spacing: 0.12em !important;
+  word-spacing: 0.16em !important;
+}
+p { margin-bottom: 2em !important; }`;
+
+const clipped = (element) =>
+  element.scrollWidth > element.clientWidth + 2 || element.scrollHeight > element.clientHeight + 2;
+
+export default {
+  id: 'text-spacing',
+  impact: 'serious',
+  tags: ['wcag21aa', 'wcag1412'],
+  help: 'Text must survive user spacing overrides without being cut off',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html',
+  // Candidates: containers that CAN clip. Everything else reflows freely
+  // and passes by construction.
+  selector: 'p, h1, h2, h3, h4, h5, h6, a, button, li, span, div, td, th, label, dt, dd, figcaption',
+  visibility: 'visual',
+  evaluateAll(elements) {
+    const doc = elements[0]?.ownerDocument ?? document;
+    // The candidate scan computes styles per element — fine on real pages,
+    // ruinous on 200k-node single-page specs, whose plain flowing text is
+    // also the least likely content on the web to clip. Past a scale where
+    // the probe's cost dwarfs its yield, abstain wholesale.
+    if (elements.length > 20_000) return elements.map(() => ({ status: 'pass' }));
+    // Only containers that hide overflow and hold text can lose content.
+    // Collapsed containers (accordion panels at height 0) show nothing —
+    // there is no visible text for the override to clip.
+    const candidates = elements.map((element) => {
+      const style = getComputedStyle(element);
+      const hides = /(hidden|clip)/.test(`${style.overflowX} ${style.overflowY}`);
+      if (!hides || !element.textContent.trim()) return null;
+      return element.clientWidth > 4 && element.clientHeight > 4 ? element : null;
+    });
+    if (!candidates.some(Boolean)) return elements.map(() => ({ status: 'pass' }));
+
+    const before = candidates.map((element) => element && clipped(element));
+    const probe = doc.createElement('style');
+    probe.dataset.pourAudit = 'probe';
+    probe.textContent = OVERRIDE;
+    doc.documentElement.append(probe);
+    let after;
+    try {
+      // Force the reflow the measurements depend on.
+      void doc.documentElement.offsetHeight;
+      after = candidates.map((element) => element && clipped(element));
+    } finally {
+      probe.remove();
+    }
+
+    return elements.map((element, i) => {
+      if (!candidates[i]) return { status: 'pass' };
+      // Only NEW clipping counts: content already truncated by design
+      // (ellipsis patterns) is judged as-authored, not under the probe.
+      if (before[i] || !after[i]) return { status: 'pass' };
+      return {
+        status: 'fail',
+        message: 'With the WCAG text-spacing overrides applied (line height 1.5, letter/word spacing bumps), text in this element gets cut off — users who need wider spacing lose content.',
+        fix: 'Let the container grow (min-height instead of height, avoid overflow:hidden on text), so spacing changes reflow instead of clip.',
+      };
+    });
+  },
+};

package/engine/rules/wcag/1.4.2-audio-control.js

@@ -0,0 +1,40 @@
+// WCAG SC 1.4.2 Audio Control (Level A)
+export default {
+  id: 'audio-control',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag142'],
+  help: 'Auto-playing audio must be stoppable or muted',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/audio-control.html',
+  selector: 'audio[autoplay], video[autoplay]',
+  visibleOnly: false,
+  evaluate(element) {
+    // Muted is checked as a PROPERTY first: frameworks (React) set it on
+    // the DOM object without reflecting the attribute, and browsers only
+    // allow autoplay when muted — attribute-only checking failed every
+    // silent background video on the modern web.
+    if (element.muted || element.volume === 0) return { status: 'pass' };
+    if (element.hasAttribute('muted') || element.hasAttribute('controls')) return { status: 'pass' };
+    // The criterion applies to audio playing for MORE than 3 seconds; a
+    // short non-looping chime is exempt — but a LOOPING clip exceeds any
+    // duration by definition, so it fails without needing metadata.
+    if (element.loop) {
+      return {
+        status: 'fail',
+        message: 'This media auto-plays on a loop with no controls and no muting — its audio talks over screen readers indefinitely.',
+        fix: 'Add controls (or muted), or don’t autoplay.',
+      };
+    }
+    if (Number.isFinite(element.duration) && element.duration <= 3) return { status: 'pass' };
+    if (!Number.isFinite(element.duration)) {
+      return {
+        status: 'incomplete',
+        message: 'This media auto-plays without controls or muting; its duration isn’t loaded yet, and only audio playing longer than 3 seconds fails 1.4.2 — check whether it has sound and how long it plays.',
+      };
+    }
+    return {
+      status: 'fail',
+      message: 'This media auto-plays with no controls and no muting — its audio talks over screen readers.',
+      fix: 'Add controls (or muted), or don’t autoplay.',
+    };
+  },
+};