@surea11y/core 1.3.0 → 1.4.1

package/src/checks/automatic/dialog-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'dialog-name-present';
@@ -55,16 +57,14 @@ function runInPage(ctx) {
     // Resolve via the shared getTextFromIdRefs helper — computes each
     // referenced element's own ACCESSIBLE NAME (aria-label, then
     // aria-labelledby, then a value-like name, then content, then title),
-    // not just its content text. Found via a real page (BBC News' cookie-
-    // consent dialog, 2026-07-22): aria-labelledby pointed at an
-    // <iframe title="SP Consent Message">, whose only name source is its
-    // title attribute (an iframe's content is opaque/cross-origin per
-    // HTML-AAM, so "name from content" is always empty). The previous
-    // version here only ever computed name-from-content of the referenced
-    // node (via getConservativeSubtreeText), silently missing the title
-    // fallback and reporting no accessible name at all — the identical
-    // pattern was hand-copied into 15 other *-name-present rules; all
-    // fixed the same way.
+    // not just its content text. This matters when aria-labelledby points
+    // at an <iframe title="..."> (e.g. BBC News' cookie-consent dialog,
+    // pointing at an `<iframe title="SP Consent Message">`), whose only
+    // name source is its title attribute — an iframe's content is
+    // opaque/cross-origin per HTML-AAM, so "name from content" is always
+    // empty. Computing only name-from-content of the referenced node would
+    // silently miss the title fallback and report no accessible name at
+    // all, the same pattern every other *-name-present rule guards against.
     if (helpers.getTextFromIdRefs) {
       try {
         const r = helpers.getTextFromIdRefs(raw, ctx, { maxRefs: maxRefs || 8 });
@@ -74,9 +74,16 @@ function runInPage(ctx) {
     return '';
   }
 
+  // Naming rules apply only to elements included in the accessibility tree
+  // (ACT c487ae and siblings), which excludes focusable aria-hidden content.
+  // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
   function isEligibleAcc(helpers, el, ctx) {
     const fn =
-      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+      helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+        ? helpers.isIncludedInAccessibilityTree
+        : helpers && typeof helpers.isAccTreeEligible === 'function'
+          ? helpers.isAccTreeEligible
+          : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);

package/src/checks/automatic/dlitem-parent-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,9 +20,8 @@
  *   which element the reference resolves to (typically the first, silently
  *   dropping the others).
  * @implementation-notes
- * - Scoped deliberately to ids referenced by ARIA (matching a widely-used
- *   reference engine's duplicate-id-aria, not the broader/deprecated page-wide duplicate-id
- *   check — see ROADMAP.md's "Skip" list).
+ * - Scoped deliberately to ids referenced by ARIA, not the broader/
+ *   deprecated page-wide duplicate-id check (see ROADMAP.md's "Skip" list).
  * - Document-wide by design: id uniqueness and ARIA id references are a
  *   whole-document property, not scoped to a sub-root.
  */

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -71,8 +73,15 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT e086e5 applies only to controls included in the accessibility tree, so
+  // a focusable control inside aria-hidden is out of scope; aria-hidden-focus
+  // reports that markup instead.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
@@ -83,6 +92,41 @@ function runInPage(ctx) {
 
   const trim = (v) => (v == null ? '' : String(v)).trim();
 
+  // Roles with their own *-name-present rule; a control carrying one
+  // explicitly is skipped here so it is reported once.
+  const ROLE_OWNED_ELSEWHERE = [
+    'alertdialog',
+    'button',
+    'checkbox',
+    'combobox',
+    'dialog',
+    'grid',
+    'link',
+    'listbox',
+    'menu',
+    'menubar',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'meter',
+    'option',
+    'progressbar',
+    'radio',
+    'radiogroup',
+    'scrollbar',
+    'searchbox',
+    'slider',
+    'spinbutton',
+    'switch',
+    'tab',
+    'tablist',
+    'textbox',
+    'toolbar',
+    'tooltip',
+    'tree',
+    'treeitem'
+  ];
+
   const metrics = {
     applicableCount: 0,
     passCount: 0,
@@ -106,9 +150,9 @@ function runInPage(ctx) {
   }
 
   function isEligibleAcc(el) {
-    if (!isAccTreeEligible) return true;
+    if (!isEligibleHelper) return true;
     try {
-      const r = isAccTreeEligible(el, ctx);
+      const r = isEligibleHelper(el, ctx);
       if (typeof r === 'boolean') return r;
       return !!(r && r.eligible);
     } catch {
@@ -191,6 +235,8 @@ function runInPage(ctx) {
       role = '';
     }
 
+    if (role && ROLE_OWNED_ELSEWHERE.indexOf(role) !== -1) continue;
+
     if (role === 'presentation' || role === 'none') {
       const fi = getFocusableInfo
         ? (() => {

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -10,23 +12,29 @@
  *   Applies to labelable form controls (input, excluding
  *   hidden/submit/reset/button/image; select; textarea).
  * @expectation
- *   At most one <label> is associated with the control — either by
- *   wrapping it, or by a <label for="..."> pointing to its id
- *   (deduplicated: a label that both wraps the control and
- *   self-references it via for counts once). Multiple associated labels
- *   are ambiguous: many screen readers only announce one of them, and it
- *   is not deterministic which.
+ *   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
+ *   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
+ *     native <label>: the labels then contribute nothing to the name, so
+ *     they cannot be ambiguous. A visible-label-vs-name mismatch is SC 2.5.3
+ *     Label in Name's concern, not this rule's.
+ *   - FAIL when two or more non-empty labels compete and there is no
+ *     override: screen readers announce a non-deterministic subset.
+ *   - CANTTELL when one non-empty label is joined by empty label
+ *     association(s) and there is no override: the name usually resolves to
+ *     the real label, but handling of the empty association is not
+ *     guaranteed across user agents.
+ *   All-empty associations with no override are a missing-name case (the
+ *   sibling rule below), not an ambiguity, so this rule stays silent.
  * @implementation-notes
- * - Matches a widely-used reference engine's form-field-multiple-labels. Distinct, atomic
- *   decision from form-control-programmatic-label-present (that
- *   rule checks a label exists at all; this one checks there is at most
- *   one).
- * - A label that isn't accessibility-tree-eligible (display:none,
- *   aria-hidden, etc.) is excluded before counting: it can't contribute to
- *   the control's accessible name, so it can't create the ambiguity this
- *   rule exists to catch. Matches the reference engine's own
- *   multiple-label check, which filters hidden labels the same way before
- *   deciding whether there's more than one.
+ * - Distinct, atomic decision from form-control-programmatic-label-present
+ *   (that rule checks a label exists at all; this one checks at most one
+ *   matters). Whether a label contributes a name is decided by the shared
+ *   helpers.labelContributesAccessibleName, so the two rules agree.
+ * - Accessibility-tree-ineligible labels (display:none, aria-hidden, etc.)
+ *   are excluded before counting: they can't contribute to the name.
  */
 
 const id = 'form-control-single-label';
@@ -63,6 +71,12 @@ function runInPage(ctx) {
 
   const isAccTreeEligible =
     helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+  const labelContributesName =
+    helpers && typeof helpers.labelContributesAccessibleName === 'function'
+      ? helpers.labelContributesAccessibleName
+      : null;
 
   const selector =
     'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
@@ -83,7 +97,8 @@ function runInPage(ctx) {
     labelsByFor.get(forValue).push(lab);
   }
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
@@ -112,42 +127,94 @@ function runInPage(ctx) {
 
     if (eligibleLabels.size <= 1) continue;
 
+    // An override (aria-labelledby / aria-label) supersedes every native
+    // <label>, so the labels contribute nothing to the accessible name and
+    // cannot compete.
+    const override = getAriaNameInfo ? getAriaNameInfo(el, ctx) : null;
+    if (override && override.present && override.value) continue;
+
+    // Without an override the labels feed the name; only labels with their
+    // own text compete for it.
+    const contributing = labelContributesName
+      ? [...eligibleLabels].filter((lab) => labelContributesName(lab))
+      : [...eligibleLabels];
+
     const tag = el.tagName.toLowerCase();
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.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).',
-      i18n: {
-        summaryKey: 'formControlSingleLabel_summary_fail',
-        hintKey: 'formControlSingleLabel_hint_fail',
-        params: { element: tag, labelCount: String(eligibleLabels.size) }
-      },
-      data: {
-        details: {
-          reasonCode: 'FORM_FIELD_MULTIPLE_LABELS',
-          element: tag,
-          labelCount: eligibleLabels.size
+    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
+          }
+        }
+      });
+    } 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
+          }
         }
-      }
-    });
+      });
+    }
+    // contributing.length === 0: no label carries text, so nothing competes
+    // for the name. A control left unnamed is form-control-programmatic-
+    // label-present's concern.
   }
 
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  const resolved = helpers.resolveTieredOutcome
+    ? helpers.resolveTieredOutcome(
+        failOccurrences,
+        cantTellOccurrences,
+        rule.defaultSeverity || 'moderate'
+      )
+    : failOccurrences.length
+      ? {
+          outcome: 'fail',
+          severity: rule.defaultSeverity || 'moderate',
+          occurrences: failOccurrences
+        }
+      : cantTellOccurrences.length
+        ? {
+            outcome: 'cantTell',
+            severity: rule.defaultSeverity || 'moderate',
+            occurrences: cantTellOccurrences
+          }
+        : { outcome: 'pass', severity: 'minor', occurrences: [] };
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**