@surea11y/core 1.3.0 → 1.4.1

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -9,7 +11,12 @@
  * @applicability
  *   Applies to inline <svg> elements that are exposed to assistive technologies AND appear intended to be conveyed.
  *   "Intended to be conveyed" is approximated deterministically by at least one of:
- *     - role="img"
+ *     - role="img", role="graphics-symbol", or role="graphics-document"
+ *       on the SVG root element itself (the WAI-ARIA Graphics Module
+ *       roles, alongside img). Deliberately does NOT extend to arbitrary
+ *       role="graphics-symbol" descendants nested inside an <svg> — this
+ *       check's scope is the <svg> root only; a broader feature, not
+ *       attempted here.
  *     - aria-label / aria-labelledby present
  *     - <title> or <desc> present (desc alone is an applicability signal only — see @expectation)
  *     - focusable/tabbable (e.g., tabindex, native focusability)
@@ -23,10 +30,9 @@
  *     - an ARIA name (aria-label / aria-labelledby).
  *   A <desc> element alone does NOT satisfy this — per the SVG Accessibility
  *   API Mappings spec §7.1, <desc> only ever contributes to the accessible
- *   DESCRIPTION, never the accessible NAME (verified 2026-07-20 directly
- *   against the SVG-AAM spec text, not assumed). An <svg> with only a
+ *   DESCRIPTION, never the accessible NAME. An <svg> with only a
  *   <desc> and no <title>/ARIA name is still "applicable" (desc signals
- *   authorial intent) but fails, matching a widely-used reference engine's svg-img-alt.
+ *   authorial intent) but fails.
  */
 
 const id = 'svg-text-alternative-present';
@@ -222,7 +228,13 @@ function runInPage(ctx) {
     const descText = titleText ? '' : nonEmptyDescText(el); // avoid second scan if title already passes
     const hasTitleOrDesc = !!(titleText || descText);
 
-    const hasIntent = role === 'img' || hasAriaNamingAttr || hasTitleOrDesc || focusable;
+    const hasIntent =
+      role === 'img' ||
+      role === 'graphics-symbol' ||
+      role === 'graphics-document' ||
+      hasAriaNamingAttr ||
+      hasTitleOrDesc ||
+      focusable;
 
     if (!hasIntent) continue;
 

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'tab-name-present';
@@ -81,9 +83,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/table-headers-attr-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,8 +16,7 @@
  *   the referencing cell, and (d) is not the cell itself.
  * @implementation-notes
  * - One occurrence per offending cell (not per bad token), listing every
- *   invalid reference — matches a widely-used reference engine's
- *   td-headers-attr reporting granularity.
+ *   invalid reference.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.

package/src/checks/automatic/table-th-has-data-cells.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -7,7 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.3.1
  * @applicability
- *   Applies to <table> elements that contain at least one <th>.
+ *   Applies to <table> elements that keep their table semantics and are included
+ *   in the accessibility tree, and that contain at least one <th> which is
+ *   visible, included in the accessibility tree, and not overridden by an
+ *   explicit role other than rowheader/columnheader.
  * @expectation
  *   The table also contains at least one <td> somewhere in it.
  * @implementation-notes
@@ -28,9 +33,10 @@
  *   if some particular <th> in it doesn't actually describe any cell
  *   (false negative, not a false positive — acceptable under this
  *   engine's philosophy).
- * - Not rule-gated on isAccTreeEligible: this remains a static-markup
- *   property, while engine-level hidden-subtree filtering still applies
- *   unless engineOptions.includeHiddenElements is true.
+ * - Applicability IS gated, because the zero-<td> case above turns any
+ *   over-broad scope straight into a false fail: a layout table marked
+ *   role="presentation" with a stray <th> and no <td> was being failed,
+ *   as were tables whose only header was hidden or carried role="cell".
  */
 
 const id = 'table-th-has-data-cells';
@@ -70,16 +76,73 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  function explicitRole(el) {
+    try {
+      return String((el && el.getAttribute && el.getAttribute('role')) || '')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)[0];
+    } catch {
+      return '';
+    }
+  }
+
+  function isIncludedInTree(el) {
+    const fn =
+      helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+        ? helpers.isIncludedInAccessibilityTree
+        : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      return typeof r === 'boolean' ? r : !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  // role="presentation"/"none" removes the table role, and with it every
+  // header cell the role would have implied. A table is not focusable, so
+  // presentational role conflict resolution does not restore it.
+  function hasTableSemantics(table) {
+    const role = explicitRole(table);
+    if (role === 'presentation' || role === 'none') return false;
+    if (role && role !== 'table' && role !== 'grid' && role !== 'treegrid') return false;
+    return isIncludedInTree(table);
+  }
+
+  // A <th> only carries a rowheader/columnheader role while nothing overrides
+  // it, and a hidden header describes nothing to a screen reader either way.
+  function isHeaderCellInScope(th) {
+    if (!th) return false;
+    const role = explicitRole(th);
+    if (role && role !== 'rowheader' && role !== 'columnheader') return false;
+    if (helpers.isDomVisibleEligible) {
+      try {
+        if (!helpers.isDomVisibleEligible(th, ctx, { targetSet: 'dom' }).eligible) return false;
+      } catch {
+        // fall through to the tree check
+      }
+    }
+    return isIncludedInTree(th);
+  }
+
   for (const table of tables) {
     if (!table || !table.querySelectorAll) continue;
 
+    // A table stripped of its semantics has no header cells to describe
+    // anything, so nothing in it is in scope.
+    if (!hasTableSemantics(table)) continue;
+
     let ths;
     try {
       ths = table.querySelectorAll('th');
     } catch {
       ths = [];
     }
-    if (!ths.length) continue;
+
+    const headers = Array.from(ths).filter(isHeaderCellInScope);
+    if (!headers.length) continue;
 
     applicableCount += 1;
 
@@ -91,7 +154,7 @@ function runInPage(ctx) {
     }
     if (hasDataCell) continue;
 
-    for (const th of ths) {
+    for (const th of headers) {
       if (!th) continue;
       const stableSelector = helpers.buildSelector ? helpers.buildSelector(th) : 'html';
       const html = helpers.getOuterHtmlSnippet

package/src/checks/automatic/target-size-minimum.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -591,6 +593,7 @@ function runInPage(ctx) {
       cantTellOccurrences.push({
         selector: buildSelector(it.el),
         html: htmlSnippet(it.el),
+        occurrenceOutcome: 'cantTell',
         summary:
           'Target may be too small and too close to another target, but the overlap is near the detection threshold and could not be confidently measured.',
         hint: 'Manually verify the effective spacing between this target and its neighbor; increase target size or spacing if the overlap is real.',
@@ -619,6 +622,7 @@ function runInPage(ctx) {
         cantTellOccurrences.push({
           selector: buildSelector(it.el),
           html: htmlSnippet(it.el),
+          occurrenceOutcome: 'cantTell',
           summary:
             'Target is too small and too close to another target, but may be exempt as part of an essential graphic or image-map region.',
           hint: 'Verify whether this target’s size is genuinely essential to its function (e.g. part of an SVG/canvas/image map); if not, increase target size or spacing.',
@@ -642,6 +646,7 @@ function runInPage(ctx) {
       failOccurrences.push({
         selector: buildSelector(it.el),
         html: htmlSnippet(it.el),
+        occurrenceOutcome: 'fail',
         summary: 'Target is too small and too close to another target.',
         hint: 'Increase target size to at least 24 by 24 CSS pixels, or add sufficient spacing.',
         i18n: {

package/src/checks/automatic/td-has-header.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -69,6 +71,19 @@ function runInPage(ctx) {
     return (v == null ? '' : String(v)).trim();
   }
 
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isEligible(node) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(node, ctx);
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
   const tables = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
   const occurrences = [];
@@ -95,8 +110,12 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
+    // An aria-hidden <th> is removed from the accessibility tree entirely
+    // -- a screen reader never announces it, so it can't actually serve as
+    // another cell's row/column header, even though it's still structurally
+    // a <th>.
     function isHeaderCell(cell) {
-      return !!(cell && cell.tagName && cell.tagName.toLowerCase() === 'th');
+      return !!(cell && cell.tagName && cell.tagName.toLowerCase() === 'th' && isEligible(cell));
     }
 
     function hasColumnHeaderAbove(r, c) {
@@ -121,6 +140,10 @@ function runInPage(ctx) {
         const cell = cells[c];
         if (!cell || isHeaderCell(cell)) continue;
 
+        // An aria-hidden data cell isn't exposed to AT either, so it has
+        // no need for an accessible header association.
+        if (!isEligible(cell)) continue;
+
         const headersAttr = trim(cell.getAttribute('headers'));
         if (headersAttr) continue;
 

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'textbox-name-present';
@@ -107,9 +109,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/tooltip-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'tooltip-name-present';
@@ -81,9 +83,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/treeitem-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'treeitem-name-present';
@@ -81,9 +83,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/valid-lang.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -56,7 +58,13 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
+  // Shape alone accepts unregistered tags such as "eng" and "em-US", so the
+  // primary subtag is checked against the IANA registry via the shared helper.
   const BCP47_RE = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+  const isValidTag =
+    typeof helpers.isValidLanguageTag === 'function'
+      ? helpers.isValidLanguageTag
+      : (v) => BCP47_RE.test(String(v || ''));
 
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[lang]')
@@ -69,12 +77,19 @@ function runInPage(ctx) {
     if (!el || !el.getAttribute) continue;
     if (el.tagName && el.tagName.toLowerCase() === 'html') continue;
 
-    const raw = String(el.getAttribute('lang') || '').trim();
-    if (!raw) continue;
+    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;
 
     applicableCount += 1;
 
-    if (BCP47_RE.test(raw)) continue;
+    // A whitespace-only value is in scope and has no primary language tag.
+    const raw = String(rawAttr).trim();
+    if (isValidTag(raw)) continue;
 
     const tag = el.tagName.toLowerCase();
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';

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

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

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check accesskeys
  * @atomic true
  * @summary accesskey values must be unique on the page
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies whenever two or more elements share the same non-empty
  *   accesskey attribute value (case-insensitive).

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

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

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

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

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,34 +16,23 @@
  *   checked state is already exposed natively), but when an author sets
  *   it explicitly it should agree with the element's actual state —
  *   otherwise assistive technology is told something different from what
- *   a sighted user perceives. This is the same static/live-DOM check
- *   a widely-used reference engine's own `aria-conditional-attr` rule
- *   performs (verified directly against its `ariaConditionalCheckboxAttr`/
- *   `ariaConditionalRadioAttr` source).
+ *   a sighted user perceives.
  * @implementation-notes
  * - Deliberately authored as `type: 'manual'` (cantTell-capped, never
- *   fail), unlike most ARIA-validity rules in this file family. That
- *   reference engine runs as a script injected into the LIVE, already-hydrated DOM, so a
- *   mismatch it reports is a genuine, current-state fact. This engine
- *   analyzes STATIC markup only (no script execution) — `.checked`
+ *   fail), unlike most ARIA-validity rules in this file family. This
+ *   engine analyzes STATIC markup only (no script execution) — `.checked`
  *   reliably reflects the static `checked` attribute for freshly-parsed
- *   markup (verified directly against jsdom), but a very common, entirely
- *   legitimate real-world pattern is a JS-hydrated widget whose
- *   server-rendered HTML intentionally ships `aria-checked="true"` (or
- *   `"mixed"`) BEFORE client JS sets the native `checked`/`indeterminate`
- *   property to match on hydration. A hard `fail` here would misfire on
- *   that pattern constantly — real risk given how common it is in exactly
- *   the kind of JS-framework-heavy pages this engine's own real-world
- *   corpus is full of. Flagging for human review (cantTell) captures the
- *   same signal without the false-positive risk of asserting it as a
- *   confirmed violation.
+ *   markup, but a very common, entirely legitimate real-world pattern is a
+ *   JS-hydrated widget whose server-rendered HTML intentionally ships
+ *   `aria-checked="true"` (or `"mixed"`) BEFORE client JS sets the native
+ *   `checked`/`indeterminate` property to match on hydration. A hard
+ *   `fail` here would misfire on that pattern constantly. Flagging for
+ *   human review (cantTell) captures the same signal without the
+ *   false-positive risk of asserting it as a confirmed violation.
  * - `aria-checked="mixed"` is only meaningful for checkboxes (radio
- *   buttons have no indeterminate state) — matches that reference engine's
- *   own `normalizeAriaChecked` (radio) vs `normalizeAriaChecked2` (checkbox)
- *   split, verified directly against its source.
+ *   buttons have no indeterminate state).
  * - Any `aria-checked` value other than "true"/"false"/"mixed" (checkbox)
- *   or "true"/"false" (radio) is treated as equivalent to "false" — also
- *   matches that reference engine's own normalization exactly.
+ *   or "true"/"false" (radio) is treated as equivalent to "false".
  * - Not rule-gated on isAccTreeEligible: whether the accessible state
  *   matches is still a markup-correctness property, while engine-level
  *   hidden-subtree filtering applies unless engineOptions.includeHiddenElements

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check aria-text
  * @atomic true
  * @summary role="text" elements should have no focusable descendants
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Elements with an explicit `role="text"`.
  * @expectation
@@ -15,10 +17,9 @@
  *   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 by a widely-used reference engine's own classification — authored as an
- *   advisory, cantTell-capped `type: 'manual'` rule, matching the Tier 1b
- *   precedent (see `landmark-unique`'s header comment for the shared
- *   rationale).
+ * - 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
  *   control/`[tabindex]`/`iframe`/`[contenteditable]`), the same
  *   conservative selector `scrollable-region-focusable` uses, not a full