@surea11y/core 1.4.0 → 1.4.1

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

@@ -9,9 +9,8 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <canvas> elements that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable (tabbable) or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <canvas> elements included in the accessibility tree.
+ *   Hidden elements are excluded whether or not they are focusable.
  * @expectation
  *   Each applicable <canvas> provides a text alternative via fallback content or an accessible name.
  */
@@ -71,8 +70,15 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // aria-hidden removes the canvas from the accessibility tree, so a text
+  // alternative on it cannot reach anyone; aria-hidden-focus reports a
+  // focusable one. Matches the other non-text-content rules.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getTextAlternativeInfo =
     helpers && typeof helpers.getTextAlternativeInfo === 'function'
@@ -97,15 +103,16 @@ function runInPage(ctx) {
   for (const el of canvases) {
     if (!el) continue;
 
-    // Applicability: eligible in the accessibility tree (with focusable/IDREF exceptions handled by helper).
-    if (isAccTreeEligible) {
+    // Applicability: included in the accessibility tree.
+    if (isEligibleHelper) {
       const elig = (() => {
         try {
-          return isAccTreeEligible(el, ctx);
+          return isEligibleHelper(el, ctx);
         } catch {
           return { eligible: true, reasons: [] };
         }
       })();
+      if (elig === false) continue;
       if (elig && elig.eligible === false) continue;
     }
 

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

@@ -124,9 +124,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/dialog-name-present.js

@@ -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/form-control-programmatic-label-present.js

@@ -73,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;
 
@@ -85,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,
@@ -108,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 {
@@ -193,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

@@ -12,20 +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
  * - 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.
+ *   (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';
@@ -62,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';
@@ -82,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) {
@@ -111,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/img-alt-present.js

@@ -9,10 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <img> elements that are exposed to assistive technologies.
- *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <img> elements included in the accessibility tree.
+ *   Images with role="presentation" or role="none" are excluded only when they are not focusable,
+ *   since a focusable one reverts to the img role under presentational roles conflict resolution.
+ *   Hidden images are excluded whether or not they are focusable.
  * @expectation
  *   Each applicable <img> element has an alt attribute.
  *   The alt attribute may be empty (alt="").
@@ -60,8 +60,15 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 23a2a8 exempts programmatically hidden images, and that glossary term
+  // has no focusability carve-out, so an aria-hidden image stays out of scope
+  // even when tabbable; 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 getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
   const getAriaNameInfo =
@@ -113,11 +120,11 @@ function runInPage(ctx) {
     const el = imgs[i];
     if (!el || !el.getAttribute) continue;
 
-    // Eligibility: only imgs exposed to assistive tech (with focusable/IDREF exceptions handled by helper)
-    if (isAccTreeEligible) {
+    // Eligibility: only imgs exposed to assistive tech.
+    if (isEligibleHelper) {
       let elig;
       try {
-        elig = isAccTreeEligible(el, ctx);
+        elig = isEligibleHelper(el, ctx);
       } catch {
         elig = null;
       }

package/src/checks/automatic/input-image-alt-present.js

@@ -9,11 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <input type="image"> elements that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <input type="image"> elements included in the accessibility tree.
  * @expectation
- *   Each applicable <input type="image"> element has an alt attribute.
+ *   Each applicable <input type="image"> element has an alt attribute, and its
+ *   accessible name is not the browser default for an image button.
  *   The alt attribute may be empty (alt="").
  */
 
@@ -72,8 +71,14 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 59796f applies to image buttons included in the accessibility tree,
+  // which excludes focusable content inside aria-hidden.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getAriaNameInfo =
     helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
@@ -99,63 +104,109 @@ function runInPage(ctx) {
   for (const el of inputs) {
     if (!el || !el.getAttribute) continue;
 
-    // Applicability: eligible in the acc tree (with helper exceptions).
-    if (isAccTreeEligible) {
+    if (isEligibleHelper) {
       const elig = (() => {
         try {
-          return isAccTreeEligible(el, ctx);
+          return isEligibleHelper(el, ctx);
         } catch {
-          return { eligible: true, reasons: [] };
+          return true;
         }
       })();
-      if (elig && elig.eligible === false) continue;
+      const eligible = typeof elig === 'boolean' ? elig : !(elig && elig.eligible === false);
+      if (!eligible) continue;
     }
 
     applicableCount += 1;
 
-    const hasAlt = el.getAttribute('alt') !== null;
-    if (hasAlt) continue;
-
-    // aria-label / aria-labelledby is also a valid, standards-recognized
-    // text-alternative mechanism for <input type="image"> (HTML-AAM
-    // accessible name computation includes ARIA naming before falling
-    // back to alt).
-    if (getAriaNameInfo) {
-      let ariaName;
-      try {
-        ariaName = getAriaNameInfo(el, ctx);
-      } catch {
-        ariaName = null;
+    // The browser's own fallback name for an image button carries no
+    // information, so an author-supplied name equal to it is treated as no
+    // name at all (ACT 59796f). Only the English defaults are recognised:
+    // "Submit Query" from HTML-AAM, "Submit" from Chrome.
+    const effectiveName = (() => {
+      let v = '';
+      if (getAriaNameInfo) {
+        try {
+          const aria = getAriaNameInfo(el, ctx);
+          if (aria && aria.present && aria.value) v = String(aria.value);
+        } catch {
+          v = '';
+        }
       }
-      if (ariaName && ariaName.present) continue;
-    }
-
-    // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent. Same gap img-alt-present handles
-    // for <img title="..."> with no alt.
-    const titleRaw = (() => {
-      try {
-        return el.getAttribute('title');
-      } catch {
-        return null;
+      if (!v) {
+        const alt = el.getAttribute('alt');
+        if (alt != null && String(alt).trim()) v = String(alt);
       }
+      if (!v) {
+        const t = el.getAttribute('title');
+        if (t != null && String(t).trim()) v = String(t);
+      }
+      return v.trim().toLowerCase();
     })();
-    if (titleRaw !== null && String(titleRaw).trim()) continue;
+
+    if (effectiveName === 'submit query' || effectiveName === 'submit') {
+      const eligInfoDefault = getEligibilityInfo
+        ? getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+        : null;
+      const defaultNameOccurrence = {
+        summary:
+          'Accessible name is the browser default for an image button, which conveys nothing.',
+        hint: 'Replace it with text describing what the button does, for example "Search".',
+        i18n: {
+          summaryKey: 'inputImage_altPresent_summary_defaultName',
+          hintKey: 'inputImage_altPresent_hint_defaultName',
+          params: { element: 'input[type=image]' }
+        },
+        data: {
+          visibilityFilter: eligInfoDefault || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: { reasonCode: 'default_name' }
+        }
+      };
+      occurrences.push(
+        helpers && typeof helpers.reportOccurrence === 'function'
+          ? helpers.reportOccurrence(el, defaultNameOccurrence)
+          : { selector: '', html: '', ...defaultNameOccurrence }
+      );
+      continue;
+    }
+
+    // effectiveName already covers the naming sources HTML-AAM allows here,
+    // in order: aria-label/aria-labelledby, then alt, then title.
+    if (effectiveName) continue;
+
+    // An image button is a control, so an empty name fails whether alt is
+    // absent or present-but-empty. alt="" marks a decorative image, and an
+    // image button is never decorative.
+    const emptyAlt = el.getAttribute('alt') !== null;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
-    const baseOccurrence = {
-      summary: 'Missing alt attribute on <input type="image">.',
-      hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
-      i18n: {
-        summaryKey: 'inputImage_altPresent_summary_fail',
-        hintKey: 'inputImage_altPresent_hint_fail',
-        params: { element: 'input[type=image]' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    };
+    const baseOccurrence = emptyAlt
+      ? {
+          summary: 'Empty alt="" on <input type="image"> leaves the control unnamed.',
+          hint: 'Describe the action in alt, or name the control with aria-label or aria-labelledby.',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_emptyAlt',
+            hintKey: 'inputImage_altPresent_hint_emptyAlt',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'empty_alt' }
+          }
+        }
+      : {
+          summary: 'Missing alt attribute on <input type="image">.',
+          hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_fail',
+            hintKey: 'inputImage_altPresent_hint_fail',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'missing_alt' }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));