@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/duplicate-id.js

@@ -0,0 +1,198 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check duplicate-id
+ * @atomic true
+ * @summary Every id value must be unique within its own tree
+ * @standard WCAG 2.1
+ * @sc 4.1.1
+ * @applicability
+ *   Applies to any element carrying a non-empty id attribute. Visibility
+ *   is irrelevant. A duplicate id breaks the same lookups whether the
+ *   element renders or not, which is why ACT 3ea0c8 evaluates hidden
+ *   elements too.
+ * @expectation
+ *   No other element in the same tree carries the same id value. Ids are
+ *   scoped per document tree and per shadow tree, so the same id inside
+ *   two different shadow roots is not a duplicate.
+ * @implementation-notes
+ * - WCAG-VERSION SCOPED. SC 4.1.1 Parsing was removed in WCAG 2.2, so this
+ *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`. A
+ *   consumer targeting WCAG 2.2 excludes it with
+ *   `excludeTags: ['wcag22-removed']`; one targeting 2.0 or 2.1 keeps it
+ *   and gets a real 4.1.1 result. The alternative, dropping the SC
+ *   mapping entirely, would have made a genuine 2.0/2.1 failure
+ *   invisible to anyone conformance-testing against those versions. See
+ *   `docs/ENGINE_OPTIONS.md` for the tag, and `docs/DESIGN_CHALLENGES.md`
+ *   for the decision this reverses.
+ * - The defect outlives its Success Criterion: a duplicate id breaks
+ *   `<label for>` association, fragment navigation, `getElementById`, and
+ *   every ID-reference attribute, none of which stopped mattering when
+ *   4.1.1 was retired. The SC was removed because browsers recover from
+ *   malformed markup, not because ids became free-form.
+ * - Scoping is per ROOT NODE, not per document: `getRootNode()` groups
+ *   light DOM against the document and each shadow tree against itself,
+ *   matching the DOM's own id-lookup scope. Two components that each use
+ *   `id="title"` inside their own shadow root are correct markup and are
+ *   not reported.
+ * - Overlaps `duplicate-id-aria` by design, and the two say different
+ *   things. That rule reports a duplicate id that an ARIA attribute
+ *   actually references, as a `cantTell` under 4.1.2, the reference
+ *   resolves to the first match, so whether the right element was named is
+ *   an authoring question. This one is the flat structural fact under
+ *   4.1.1, for every id, referenced or not.
+ * - Detection is document-wide while reporting follows the scanned scope,
+ *   the same split `duplicate-id-aria` uses: a `contextSelector` narrows
+ *   which duplicates get reported, never which ones count as duplicates.
+ */
+
+const id = 'duplicate-id';
+
+const meta = {
+  title: 'IDs must be unique',
+  description:
+    'Checks that every non-empty id attribute value is unique within its own document or shadow tree (WCAG 2.0/2.1 SC 4.1.1, removed in WCAG 2.2).',
+  i18n: {
+    titleKey: 'duplicateId_title',
+    descriptionKey: 'duplicateId_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag411', 'wcag22-removed', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.1'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.1',
+      requirement: '4.1.1',
+      title: 'Parsing',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.1': ['id-unique-page-wide'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // Detection spans the whole document; see the header comment on scope.
+  const all = new Set();
+  try {
+    const nodes = document.querySelectorAll ? document.querySelectorAll('[id]') : [];
+    for (const el of nodes) all.add(el);
+  } catch {
+    // no-throw: fall through to the helper-provided set below
+  }
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+
+  // queryAllSmart reaches into open shadow roots when includeShadowDom is on,
+  // which document.querySelectorAll never does.
+  let inScope = null;
+  if (queryAllSmart) {
+    try {
+      const scoped = queryAllSmart('[id]');
+      const list = Array.isArray(scoped) ? scoped : Array.from(scoped || []);
+      inScope = new Set(list);
+      for (const el of list) all.add(el);
+    } catch {
+      inScope = null;
+    }
+  }
+
+  // Ids resolve within their own tree, so group by root before comparing.
+  function rootOf(el) {
+    try {
+      if (typeof el.getRootNode === 'function') return el.getRootNode();
+    } catch {
+      // fall through
+    }
+    return document;
+  }
+
+  const byRootAndId = new Map(); // root -> Map(idValue -> element[])
+  let applicableCount = 0;
+
+  for (const el of all) {
+    if (!el || el.nodeType !== 1 || !el.getAttribute) continue;
+    const value = String(el.getAttribute('id') || '').trim();
+    if (!value) continue;
+
+    applicableCount += 1;
+
+    const root = rootOf(el);
+    let idMap = byRootAndId.get(root);
+    if (!idMap) {
+      idMap = new Map();
+      byRootAndId.set(root, idMap);
+    }
+    const bucket = idMap.get(value);
+    if (bucket) bucket.push(el);
+    else idMap.set(value, [el]);
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const idMap of byRootAndId.values()) {
+    for (const [value, els] of idMap) {
+      if (els.length <= 1) continue;
+
+      for (const el of els) {
+        if (inScope && !inScope.has(el)) continue;
+
+        const eligInfo = helpers.getEligibilityInfo
+          ? (() => {
+              try {
+                return helpers.getEligibilityInfo(el, ctx, { targetSet: 'dom' });
+              } catch {
+                return null;
+              }
+            })()
+          : null;
+
+        occurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: `The id "${value}" is used on ${els.length} elements in the same tree.`,
+            hint: 'Give each element its own id. A duplicate breaks <label for>, fragment links, getElementById and every ID-reference attribute, all of which resolve to the first match only.',
+            i18n: {
+              summaryKey: 'duplicateId_summary_fail',
+              hintKey: 'duplicateId_hint_fail',
+              params: { id: value, count: String(els.length) }
+            },
+            data: {
+              details: {
+                reasonCode: 'DUPLICATE_ID',
+                id: value,
+                count: els.length
+              },
+              visibilityFilter: eligInfo || { targetSet: 'dom', accEligible: null, reasons: [] }
+            }
+          })
+        );
+      }
+    }
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/embed-text-alternative-present.js

@@ -135,8 +135,8 @@ function runInPage(ctx) {
   }
 
   // `title` is a weaker text-alternative mechanism than aria-label/
-  // aria-labelledby — it is not reliably exposed to assistive technology
-  // in every context (e.g. touch/mobile) — so a pass achieved only via
+  // aria-labelledby, it is not reliably exposed to assistive technology
+  // in every context (e.g. touch/mobile), so a pass achieved only via
   // `title` is reported at reduced confidence rather than the rule's
   // default `high`.
   let anyPassedViaWeakMechanism = false;

package/src/checks/automatic/form-control-programmatic-label-present.js

@@ -13,12 +13,29 @@
  *
  * WCAG mapping: matches technique H44 ("Using label elements to associate
  * text labels with form controls"), which WCAG's own Techniques document
- * lists as sufficient for 1.3.1, 3.3.2, AND 4.1.2 simultaneously — a label
+ * lists as sufficient for 1.3.1, 3.3.2, AND 4.1.2 simultaneously. A label
  * that programmatically associates with a control conveys the
  * relationship (1.3.1), provides the instruction (3.3.2), and exposes the
  * accessible name (4.1.2) all at once. This rule was originally only wired
  * to 4.1.2, even though its own `tags` already listed wcag131/wcag332 and
  * wcag-facets.js already had matching facet ids under those SCs.
+ *
+ * @applicability
+ *   Applies to <input>, <select> and <textarea> elements included in the
+ *   accessibility tree, excluding the input types hidden, submit, reset,
+ *   button and image, which take their name from a value or alt attribute
+ *   rather than from a label. A control carrying
+ *   an explicit ARIA widget role is out of scope, button, checkbox,
+ *   combobox, listbox, textbox, slider and the rest of ROLE_OWNED_ELSEWHERE
+ *   each have a naming rule of their own, and role="presentation"/"none"
+ *   removes a control unless it is still tabbable.
+ * @expectation
+ *   Each applicable control carries a programmatic label by one of the
+ *   mechanisms helpers.getLabelMethod resolves, in its priority order: an
+ *   associated <label>, aria-labelledby, aria-label, title, then
+ *   placeholder. Any of the five satisfies this rule. Whether the weaker two
+ *   are an appropriate primary label is a separate question, asked by
+ *   form-control-programmatic-label-quality.
  */
 
 const id = 'form-control-programmatic-label-present';
@@ -162,7 +179,7 @@ function runInPage(ctx) {
 
   // getLabelMethod is provided by the shared dom-helpers bundle that
   // dom-runner.js always constructs for every rule execution (built-in or
-  // custom) — see createDomHelpers's own getLabelMethod, which implements
+  // custom), see createDomHelpers's own getLabelMethod, which implements
   // this exact <label>/aria-labelledby/aria-label/title/placeholder
   // priority order. No local reimplementation is needed as a fallback.
   function getLabelMethodSafe(el) {

package/src/checks/automatic/form-control-single-label.js

@@ -13,7 +13,7 @@
  *   hidden/submit/reset/button/image; select; textarea).
  * @expectation
  *   At most one <label> that can contribute to the control's accessible name
- *   is associated with it — by wrapping it, or by a <label for="..."> on its
+ *   is associated with it, by wrapping it, or by a <label for="..."> on its
  *   id (a label that both wraps and self-references via for counts once).
  *   Graded by whether the surplus labels actually compete for the name:
  *   - PASS when an override (aria-labelledby / aria-label) supersedes every
@@ -140,51 +140,49 @@ function runInPage(ctx) {
       : [...eligibleLabels];
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     if (contributing.length >= 2) {
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This form control is associated with more than one <label>.',
-        hint: 'Keep only one <label> per form control (either wrapping it or referencing it via for/id).',
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'formControlSingleLabel_summary_fail',
-          hintKey: 'formControlSingleLabel_hint_fail',
-          params: { element: tag, labelCount: String(contributing.length) }
-        },
-        data: {
-          details: {
-            reasonCode: 'FORM_FIELD_MULTIPLE_LABELS',
-            element: tag,
-            labelCount: contributing.length
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This form control is associated with more than one <label>.',
+          hint: 'Keep only one <label> per form control (either wrapping it or referencing it via for/id).',
+          occurrenceOutcome: 'fail',
+          i18n: {
+            summaryKey: 'formControlSingleLabel_summary_fail',
+            hintKey: 'formControlSingleLabel_hint_fail',
+            params: { element: tag, labelCount: String(contributing.length) }
+          },
+          data: {
+            details: {
+              reasonCode: 'FORM_FIELD_MULTIPLE_LABELS',
+              element: tag,
+              labelCount: contributing.length
+            }
           }
-        }
-      });
+        })
+      );
     } else if (contributing.length === 1) {
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This form control has one labelling <label> plus an extra empty <label> association.',
-        hint: 'Remove the redundant empty <label> so exactly one <label> is associated with the control.',
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'formControlSingleLabel_summary_cantTell',
-          hintKey: 'formControlSingleLabel_hint_cantTell',
-          params: { element: tag, labelCount: String(eligibleLabels.size) }
-        },
-        data: {
-          details: {
-            reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',
-            element: tag,
-            labelCount: eligibleLabels.size,
-            contributingLabelCount: contributing.length
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This form control has one labelling <label> plus an extra empty <label> association.',
+          hint: 'Remove the redundant empty <label> so exactly one <label> is associated with the control.',
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'formControlSingleLabel_summary_cantTell',
+            hintKey: 'formControlSingleLabel_hint_cantTell',
+            params: { element: tag, labelCount: String(eligibleLabels.size) }
+          },
+          data: {
+            details: {
+              reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',
+              element: tag,
+              labelCount: eligibleLabels.size,
+              contributingLabelCount: contributing.length
+            }
           }
-        }
-      });
+        })
+      );
     }
     // contributing.length === 0: no label carries text, so nothing competes
     // for the name. A control left unnamed is form-control-programmatic-

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -84,15 +84,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(html) : 'html';
-  const htmlSnippet = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(html)
-    : (html.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html: htmlSnippet,
+    helpers.reportOccurrence(html, {
       summary: `The lang ("${lang}") and xml:lang ("${xmlLang}") attributes declare different languages.`,
       hint: 'Make lang and xml:lang declare the same primary language, or remove the deprecated xml:lang attribute.',
       i18n: {
@@ -103,7 +96,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'HTML_XML_LANG_MISMATCH', lang, xmlLang }
       }
-    }
+    })
   ];
 
   return {

package/src/checks/automatic/iframe-focusable-content.js

@@ -11,7 +11,7 @@
  * @applicability
  *   Applies to <iframe>/<frame> elements with an explicit negative
  *   tabindex, whose embedded document is same-origin and reachable via
- *   contentDocument (cross-origin/unreachable frames assert nothing — see
+ *   contentDocument (cross-origin/unreachable frames assert nothing, see
  *   implementation notes).
  * @expectation
  *   The frame's embedded document contains no focusable element. Browsers
@@ -19,14 +19,26 @@
  *   document: Tab can still reach focusable content inside, even though
  *   the frame itself is skipped. An author who set tabindex="-1" intending
  *   to remove the frame from the tab order has not actually done so if the
- *   embedded document contains focusable content.
+ *   embedded document contains focusable content. Exception: an iframe with
+ *   both a `width` and `height` HTML attribute of 2px or less (a common
+ *   "tracking pixel" pattern) cannot render any perceptible content, so
+ *   focusable content inside it never satisfies ACT akn7bn's "visible"
+ *   requirement and doesn't count.
  * @implementation-notes
- * - Deliberately scoped to same-origin, currently-accessible content only
+ * - Scoped to same-origin, currently-accessible content only
  *   (contentDocument access is wrapped in try/catch and treated as "no
- *   constraint asserted" — not counted as applicable — when unreachable),
+ *   constraint asserted", not counted as applicable, when unreachable),
  *   matching this engine's established scope-limiting rationale (see
  *   src/core/aria-helpers.js file header) rather than guessing at
  *   cross-origin content.
+ * - A `srcdoc` iframe's document is same-origin by definition, but some
+ *   environments (notably jsdom, including this library's own Node/jsdom
+ *   integration path, see docs/INTEGRATION.md) never populate
+ *   `contentDocument` from the attribute. When the live document looks
+ *   empty and a `srcdoc` attribute is present, its HTML string is parsed
+ *   directly via DOMParser as a static fallback, no rendering pipeline
+ *   needed, and a real browser's already-loaded contentDocument is always
+ *   preferred untouched.
  * - Focusability inside the embedded document is checked with a small,
  *   self-contained heuristic (native interactive tags + non-negative
  *   tabindex) rather than ctx.helpers.getFocusableInfo, since that helper
@@ -67,15 +79,15 @@ function runInPage(ctx) {
   const { helpers, rule, document } = ctx;
 
   // Self-contained rendering check for the embedded document (a distinct
-  // realm — see this rule's own header comment on why the outer
+  // realm, see this rule's own header comment on why the outer
   // document's shared eligibility helpers can't be reused here).
-  // Deliberately checks only genuine non-rendering (display:none,
+  // Checks only genuine non-rendering (display:none,
   // visibility:hidden, the hidden attribute) via the ancestor chain, NOT
   // aria-hidden: aria-hidden alone does not remove an element from a real
   // browser's native tab order (the same anti-pattern this engine's own
   // aria-hidden-focus rule exists to catch), so an aria-hidden-but-
   // visually-rendered focusable element inside the frame is still
-  // genuinely reachable by keyboard and must stay flagged.
+  // reachable by keyboard and must stay flagged.
   function isRenderedInDoc(doc, el) {
     try {
       const view = doc.defaultView;
@@ -296,6 +308,44 @@ function runInPage(ctx) {
     return !Number.isNaN(n) && n < 0;
   }
 
+  // A `srcdoc` iframe's embedded document is same-origin by definition, but
+  // some environments (jsdom, notably) never populate `contentDocument`
+  // from the attribute at all. Parsing the attribute's own HTML string is a
+  // static, deterministic fallback that needs no rendering pipeline. It
+  // only kicks in when the live document looks empty, so a real browser's
+  // already-loaded contentDocument is always preferred untouched.
+  function parseSrcdocFallback(el) {
+    try {
+      const raw = el.getAttribute('srcdoc');
+      if (raw == null) return null;
+      const view = el.ownerDocument && el.ownerDocument.defaultView;
+      const DOMParserCtor = view && view.DOMParser;
+      if (!DOMParserCtor) return null;
+      return new DOMParserCtor().parseFromString(raw, 'text/html');
+    } catch {
+      return null;
+    }
+  }
+
+  // ACT akn7bn's own Expectation only cares about focusable content that is
+  // also *visible*: a 1x1 (or similar tracking-pixel-sized) iframe cannot
+  // render any perceptible content, whatever's focusable inside it. Scoped
+  // to the iframe's own HTML width/height attributes, a static, always-
+  // readable signal, unlike computed/rendered size, which needs real
+  // layout jsdom doesn't have (see docs/LIMITATIONS.md).
+  function isIframeVisiblyTiny(el) {
+    try {
+      const wAttr = el.getAttribute('width');
+      const hAttr = el.getAttribute('height');
+      if (wAttr == null || hAttr == null) return false;
+      const w = Number(String(wAttr).trim());
+      const h = Number(String(hAttr).trim());
+      return Number.isFinite(w) && Number.isFinite(h) && w <= 2 && h <= 2;
+    } catch {
+      return false;
+    }
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('iframe, frame')
     : helpers.queryAll('iframe, frame');
@@ -314,55 +364,59 @@ function runInPage(ctx) {
     } catch {
       contentDoc = null;
     }
+    const looksEmpty = !contentDoc || !contentDoc.body || !contentDoc.body.hasChildNodes();
+    if (looksEmpty && el.getAttribute('srcdoc') != null) {
+      const parsed = parseSrcdocFallback(el);
+      if (parsed) contentDoc = parsed;
+    }
     if (!contentDoc || !contentDoc.querySelectorAll) continue; // cross-origin/unreachable: no constraint asserted
 
     applicableCount += 1;
 
     const candidates = getFocusableCandidates(contentDoc);
     if (!candidates.length) continue;
+    if (isIframeVisiblyTiny(el)) continue; // ACT akn7bn: no visible content at all
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const shouldProbe = candidates.length === 1;
     const runtimeProbe = shouldProbe
       ? probeImmediateFocusRedirect(el, contentDoc, candidates[0])
       : null;
 
     if (runtimeProbe && runtimeProbe.redirected) {
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
-        hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
-        i18n: null,
-        data: {
-          details: {
-            reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
-            element: tag,
-            runtimeProbe
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
+          hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
+          i18n: null,
+          data: {
+            details: {
+              reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
+              element: tag,
+              runtimeProbe
+            }
           }
-        }
-      });
+        })
+      );
       continue;
     }
 
-    failOccurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
-      hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
-      i18n: {
-        summaryKey: 'iframeFocusableContent_summary_fail',
-        hintKey: 'iframeFocusableContent_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
-      }
-    });
+    failOccurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
+        hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
+        i18n: {
+          summaryKey: 'iframeFocusableContent_summary_fail',
+          hintKey: 'iframeFocusableContent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {