@surea11y/core 1.4.1 → 1.6.0

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check tooltip-name-present
+ * @atomic true
+ * @summary Elements with role="tooltip" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="tooltip" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or,
+ *   role="tooltip" being name-from-content, from its own subtree text,
+ *   where a descendant's own name (an <img alt>, aria-label or title) counts
+ *   as that descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'tooltip-name-present';
 
 const meta = {
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -148,24 +167,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This tooltip has no accessible name.',
-      hint: 'Provide tooltip text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
-      i18n: {
-        summaryKey: 'tooltipNamePresent_summary_fail',
-        hintKey: 'tooltipNamePresent_hint_fail',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'tooltip', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This tooltip has no accessible name.',
+        hint: 'Provide tooltip text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+        i18n: {
+          summaryKey: 'tooltipNamePresent_summary_fail',
+          hintKey: 'tooltipNamePresent_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'tooltip', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -2,11 +2,30 @@
 
 'use strict';
 
+/**
+ * @check treeitem-name-present
+ * @atomic true
+ * @summary Elements with role="treeitem" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="treeitem" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or,
+ *   role="treeitem" being name-from-content, from its own subtree text,
+ *   where a descendant's own name (an <img alt>, aria-label or title) counts
+ *   as that descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'treeitem-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Tree items have an accessible name',
+  description: 'Checks that elements with role="treeitem" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'treeitemNamePresent_title',
     descriptionKey: 'treeitemNamePresent_description'
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -145,24 +164,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This element has no accessible name.',
-      hint: 'Provide aria-label or aria-labelledby (preferred), or provide visible text that is not hidden from assistive technologies.',
-      i18n: {
-        summaryKey: 'treeitemNamePresent_summary_fail',
-        hintKey: 'treeitemNamePresent_hint_fail',
-        params: { controlType: 'treeitem' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'treeitem', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This element has no accessible name.',
+        hint: 'Provide aria-label or aria-labelledby (preferred), or provide visible text that is not hidden from assistive technologies.',
+        i18n: {
+          summaryKey: 'treeitemNamePresent_summary_fail',
+          hintKey: 'treeitemNamePresent_hint_fail',
+          params: { controlType: 'treeitem' }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'treeitem', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/valid-lang.js

@@ -10,11 +10,23 @@
  * @sc 3.1.2
  * @applicability
  *   Applies to any element other than the root <html> with a non-empty
- *   lang attribute.
+ *   lang attribute AND at least some non-whitespace "governed text" that
+ *   actually inherits its language from that element, per ACT de46e4:
+ *   - Descendant text/alt is governed by the nearest lang-carrying
+ *     ancestor only, a nested descendant with its own non-empty lang
+ *     re-scopes everything inside it, so that subtree no longer counts
+ *     toward the outer element's applicability (it counts toward the
+ *     nested element's own, if that one is also being evaluated).
+ *   - A non-empty alt attribute on img/area/input[type=image] counts as
+ *     governed text, the same as a text node.
+ *   - Text (or alt) that CSS keeps out of the render tree (display:none,
+ *     the hidden attribute, ...) does not count. aria-hidden and
+ *     offscreen positioning do NOT exempt text, per ACT's own failed
+ *     examples for both, only actual non-rendering does.
  * @expectation
  *   The lang value matches a valid BCP47 language-tag syntax. WCAG 3.1.2
  *   (Language of Parts) requires that when a passage's language differs
- *   from the page's default, it is identified programmatically — an
+ *   from the page's default, it is identified programmatically. An
  *   invalid tag fails to identify a real language at all.
  * @implementation-notes
  * - Distinct, atomic decision from html-lang-attr-present (that
@@ -22,7 +34,7 @@
  *   covers every other element, for SC 3.1.2.
  * - Same minimal BCP47 *syntax* check as html-lang-attr-present (primary
  *   subtag + optional subtags), not IANA Language Subtag Registry
- *   validation — same documented scope limitation (syntactically
+ *   validation, same documented scope limitation (syntactically
  *   well-formed but unregistered tags like "xx-ZZ" are not flagged).
  */
 
@@ -66,6 +78,78 @@ function runInPage(ctx) {
       ? helpers.isValidLanguageTag
       : (v) => BCP47_RE.test(String(v || ''));
 
+  function isDomVisible(node) {
+    if (!node) return false;
+    if (helpers.isDomVisibleEligible)
+      return !!helpers.isDomVisibleEligible(node, ctx, { targetSet: 'dom' }).eligible;
+    if (helpers.getEligibilityInfo)
+      return !!helpers.getEligibilityInfo(node, ctx, { targetSet: 'dom' }).eligible;
+    return true;
+  }
+
+  function hasOwnNonEmptyLang(node) {
+    try {
+      const v = node.getAttribute ? node.getAttribute('lang') : null;
+      return v != null && v.trim() !== '';
+    } catch {
+      return false;
+    }
+  }
+
+  function isAltBearing(node) {
+    const tag = (node.tagName || '').toLowerCase();
+    if (tag === 'img' || tag === 'area') return true;
+    if (tag !== 'input') return false;
+    try {
+      return (node.getAttribute('type') || '').toLowerCase() === 'image';
+    } catch {
+      return false;
+    }
+  }
+
+  // "Governed text": non-whitespace text (or alt) that inherits its
+  // language from `root`, per ACT de46e4, see @applicability above. Walks
+  // the flat subtree, stopping at any descendant carrying its own non-empty
+  // lang (that subtree governs itself, not `root`), and treating
+  // display:none/hidden content as absent. Bails out as soon as any
+  // qualifying text is found; a node-visit budget guards pathological
+  // markup the same way other subtree walks in this engine do.
+  const MAX_VISITS = 5000;
+  function hasGovernedText(root) {
+    let found = false;
+    let visits = 0;
+
+    function walk(node, isRoot) {
+      if (found || visits++ > MAX_VISITS) return;
+      if (!node || node.nodeType !== 1) return;
+      if (!isRoot && hasOwnNonEmptyLang(node)) return; // re-scoped to itself
+
+      if (isAltBearing(node)) {
+        const alt = node.getAttribute ? node.getAttribute('alt') : null;
+        if (alt != null && alt.trim() !== '' && isDomVisible(node)) found = true;
+        return; // alt-bearing elements have no other text to walk into
+      }
+
+      if (!isDomVisible(node)) return;
+
+      const kids = node.childNodes ? Array.from(node.childNodes) : [];
+      for (const kid of kids) {
+        if (found) return;
+        if (kid.nodeType === 3) {
+          if (String(kid.nodeValue || '').trim()) {
+            found = true;
+            return;
+          }
+        } else if (kid.nodeType === 1) {
+          walk(kid, false);
+        }
+      }
+    }
+
+    walk(root, true);
+    return found;
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[lang]')
     : helpers.queryAll('[lang]');
@@ -80,10 +164,11 @@ function runInPage(ctx) {
     const rawAttr = el.getAttribute('lang');
     if (rawAttr === null || rawAttr === '') continue; // ACT de46e4: empty is out of scope
 
-    // The rule applies only where text actually inherits the language, so an
-    // element with no text, or whose text reaches no one, has nothing to
-    // declare a language for.
-    if (!String(el.textContent || '').trim()) continue;
+    // The rule applies only where text actually inherits the language from
+    // THIS element specifically, not merely where the subtree has any text
+    // at all, which could all belong to a nested element's own (possibly
+    // valid) lang instead. See hasGovernedText's doc comment.
+    if (!hasGovernedText(el)) continue;
 
     applicableCount += 1;
 
@@ -92,23 +177,21 @@ function runInPage(ctx) {
     if (isValidTag(raw)) continue;
 
     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 lang attribute value ("${raw}") is not a syntactically valid language tag.`,
-      hint: 'Use a valid BCP47 language tag (e.g. "fr", "es-MX").',
-      i18n: {
-        summaryKey: 'validLang_summary_fail',
-        hintKey: 'validLang_hint_fail',
-        params: { element: tag, value: raw }
-      },
-      data: {
-        details: { reasonCode: 'ELEMENT_LANG_INVALID', element: tag, value: raw }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This lang attribute value ("${raw}") is not a syntactically valid language tag.`,
+        hint: 'Use a valid BCP47 language tag (e.g. "fr", "es-MX").',
+        i18n: {
+          summaryKey: 'validLang_summary_fail',
+          hintKey: 'validLang_hint_fail',
+          params: { element: tag, value: raw }
+        },
+        data: {
+          details: { reasonCode: 'ELEMENT_LANG_INVALID', element: tag, value: raw }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/video-poster-text-alternative-present.js

@@ -87,7 +87,7 @@ function runInPage(ctx) {
 
   function computeNameInfo(el) {
     // <video> is not a labelable element (no browser computes an accessible
-    // name from <label for="...">), so only ARIA naming and title count —
+    // name from <label for="...">), so only ARIA naming and title count,
     // do not accept native <label> associations.
     const flags = [];
     let aria = null;

package/src/checks/manual/accesskeys-manual.js

@@ -6,17 +6,17 @@
  * @check accesskeys
  * @atomic true
  * @summary accesskey values must be unique on the page
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever two or more elements share the same non-empty
  *   accesskey attribute value (case-insensitive).
  * @expectation
  *   Every accesskey value on the page is unique. Duplicate accesskeys
- *   make keyboard-shortcut activation ambiguous — only one of the
+ *   make keyboard-shortcut activation ambiguous: only one of the
  *   elements sharing the key can actually be reached by it, and which
  *   one is browser/platform-dependent.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  */
@@ -62,25 +62,24 @@ function runInPage(ctx) {
   for (const [key, els] of groups) {
     if (els.length <= 1) continue;
     for (const el of els) {
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: "This element's accesskey is shared with another element on the page.",
-        hint: 'Make each accesskey value unique across the page.',
-        i18n: {
-          summaryKey: 'accesskeys_summary_cantTell',
-          hintKey: 'accesskeys_hint_cantTell',
-          params: { accesskey: key, duplicateCount: String(els.length) }
-        },
-        data: {
-          details: { reasonCode: 'ACCESSKEY_DUPLICATE', accesskey: key, duplicateCount: els.length }
-        }
-      });
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: "This element's accesskey is shared with another element on the page.",
+          hint: 'Make each accesskey value unique across the page.',
+          i18n: {
+            summaryKey: 'accesskeys_summary_cantTell',
+            hintKey: 'accesskeys_hint_cantTell',
+            params: { accesskey: key, duplicateCount: String(els.length) }
+          },
+          data: {
+            details: {
+              reasonCode: 'ACCESSKEY_DUPLICATE',
+              accesskey: key,
+              duplicateCount: els.length
+            }
+          }
+        })
+      );
     }
   }
 

package/src/checks/manual/area-alt-decorative-manual.js

@@ -9,6 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <area> elements whose alt attribute is present but empty once
+ *   trimmed, the markup that declares a hotspot decorative. The <area> must
+ *   belong to a <map> that an <img usemap> actually references, and both
+ *   that <img> and the <area> itself must be included in the accessibility
+ *   tree; an <area> in an unused map is out of scope.
+ *   role="presentation"/"none" takes an element out unless it is focusable.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/area-alt-quality-manual.js

@@ -9,6 +9,12 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <area> elements whose alt attribute is present and non-empty.
+ *   The <area> must belong to a <map> that an <img usemap> actually
+ *   references, and both that <img> and the <area> itself must be included
+ *   in the accessibility tree; an <area> in an unused map is out of scope.
+ *   role="presentation"/"none" takes an element out unless it is focusable.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/aria-checked-state-mismatch-manual.js

@@ -14,13 +14,13 @@
  * @expectation
  *   `aria-checked` is redundant on a native checkbox/radio (the role's
  *   checked state is already exposed natively), but when an author sets
- *   it explicitly it should agree with the element's actual state —
+ *   it explicitly it should agree with the element's actual state,
  *   otherwise assistive technology is told something different from what
  *   a sighted user perceives.
  * @implementation-notes
- * - Deliberately authored as `type: 'manual'` (cantTell-capped, never
- *   fail), unlike most ARIA-validity rules in this file family. This
- *   engine analyzes STATIC markup only (no script execution) — `.checked`
+ * - Authored as `type: 'manual'` (cantTell-capped, never fail), unlike
+ *   most ARIA-validity rules in this file family. This engine analyzes
+ *   STATIC markup only (no script execution), so `.checked`
  *   reliably reflects the static `checked` attribute for freshly-parsed
  *   markup, but a very common, entirely legitimate real-world pattern is a
  *   JS-hydrated widget whose server-rendered HTML intentionally ships
@@ -114,29 +114,26 @@ function runInPage(ctx) {
 
     if (normalizedAriaChecked === actualState) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This element’s aria-checked value does not match its actual checked/indeterminate state.',
-      hint: 'Set aria-checked to match the element’s real state, or remove it — a native checkbox/radio already exposes this state without it.',
-      i18n: {
-        summaryKey: 'ariaCheckedStateMismatch_summary_cantTell',
-        hintKey: 'ariaCheckedStateMismatch_hint_cantTell',
-        params: { ariaChecked: normalizedAriaChecked, actualState, type }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_CHECKED_STATE_MISMATCH',
-          ariaChecked: normalizedAriaChecked,
-          actualState,
-          type
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This element’s aria-checked value does not match its actual checked/indeterminate state.',
+        hint: 'Set aria-checked to match the element’s real state, or remove it; a native checkbox/radio already exposes this state without it.',
+        i18n: {
+          summaryKey: 'ariaCheckedStateMismatch_summary_cantTell',
+          hintKey: 'ariaCheckedStateMismatch_hint_cantTell',
+          params: { ariaChecked: normalizedAriaChecked, actualState, type }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_CHECKED_STATE_MISMATCH',
+            ariaChecked: normalizedAriaChecked,
+            actualState,
+            type
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/aria-text-manual.js

@@ -6,7 +6,7 @@
  * @check aria-text
  * @atomic true
  * @summary role="text" elements should have no focusable descendants
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Elements with an explicit `role="text"`.
  * @expectation
@@ -14,10 +14,10 @@
  *   subtree as a single unit of plain text (e.g. text visually split
  *   across multiple `<span>`s by styling). Per the WAI-ARIA Authoring
  *   Practices, this only makes sense when that subtree contains no
- *   focusable content — a focusable descendant inside a "this is just
+ *   focusable content: a focusable descendant inside a "this is just
  *   text" region is unreachable or confusing for keyboard/AT users.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule, matching the Tier 1b precedent (see
  *   `landmark-unique`'s header comment for the shared rationale).
  * - "Focusable descendant" is a presence check (link/button/form
@@ -80,7 +80,7 @@ function runInPage(ctx) {
       selector: stableSelector,
       html,
       summary: 'This role="text" element contains a focusable descendant.',
-      hint: 'Remove role="text" (or remove the focusable descendant) — a "plain text" region should not contain focusable content.',
+      hint: 'Remove role="text" (or remove the focusable descendant); a "plain text" region should not contain focusable content.',
       i18n: {
         summaryKey: 'ariaText_summary_cantTell',
         hintKey: 'ariaText_hint_cantTell',