@surea11y/core 1.3.0 → 1.4.0

package/src/checks/automatic/nested-interactive-controls-absent.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,10 +22,9 @@
  *   technology — activating the outer control and the inner one become
  *   ambiguous, and some AT only exposes one of the two.
  * @implementation-notes
- * - Matches a widely-used reference engine's nested-interactive. Reports on the outer
- *   (containing) control, not the nested descendant — this engine
- *   considers the container the fixable unit ("move the nested control
- *   outside this element").
+ * - Reports on the outer (containing) control, not the nested descendant —
+ *   this engine considers the container the fixable unit ("move the nested
+ *   control outside this element").
  * - A container can be reported once even with multiple nested
  *   descendants (listed together); a deeply nested chain (A > B > C, all
  *   interactive) reports both A and B as separate occurrences, since each
@@ -89,6 +90,19 @@ function runInPage(ctx) {
     '[role="treeitem"]'
   ].join(', ');
 
+  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 nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(INTERACTIVE_SELECTOR)
     : helpers.queryAll(INTERACTIVE_SELECTOR);
@@ -98,12 +112,20 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     if (!el || !el.querySelectorAll) continue;
+    if (!isEligible(el)) continue;
 
     applicableCount += 1;
 
+    // The nested search uses the raw native querySelectorAll (not
+    // helpers.queryAllSmart), so it isn't subject to that helper's
+    // default hidden-content policy at all -- not even hard CSS-based
+    // hiding, let alone aria-hidden. A nested descendant that is never
+    // actually rendered or exposed to AT (display:none, aria-hidden,
+    // etc.) creates no real ambiguity for ANY user, since it isn't there
+    // to be confused with the outer control.
     let nested;
     try {
-      nested = Array.from(el.querySelectorAll(INTERACTIVE_SELECTOR));
+      nested = Array.from(el.querySelectorAll(INTERACTIVE_SELECTOR)).filter(isEligible);
     } catch {
       nested = [];
     }

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

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

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'option-name-present';

package/src/checks/automatic/page-title-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'page-title-present';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'progressbar-name-present';
@@ -96,16 +98,12 @@ function runInPage(ctx) {
     const title = getAttr(el, 'title');
     if (title) return { ok: true, method: 'title' };
 
-    // role="progressbar" is name-from-author-only per WAI-ARIA (verified
-    // against a widely-used reference engine's own aria-progressbar-name check: any:
-    // ['aria-label', 'aria-labelledby', title] — no content-based naming
-    // method at all). It must NOT fall back to subtree content: found on a
-    // real site, Instacart's <ul role="progressbar"> loading skeleton has
-    // no name of its own, but nested descendants carry their own
-    // aria-label="Loading Box" (for a completely different purpose) —
-    // falling back to subtree content picked that up and wrongly treated
-    // it as the progressbar's own name, when that reference engine correctly
-    // still flags it as unnamed.
+    // role="progressbar" is name-from-author-only per WAI-ARIA: aria-label,
+    // aria-labelledby, or title — no content-based naming method at all. It
+    // must NOT fall back to subtree content: e.g. a <ul role="progressbar">
+    // loading skeleton with no name of its own, whose nested descendants
+    // carry their own aria-label for a different purpose — falling back to
+    // subtree content would wrongly treat that as the progressbar's name.
     return { ok: false, method: 'none' };
   }
 

package/src/checks/automatic/role-img-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,8 +16,7 @@
  *   Each applicable element with role="img" has an accessible text alternative:
  *    - aria-label with a non-empty value; OR
  *    - aria-labelledby referencing at least one existing element that contributes non-empty text; OR
- *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM,
- *      also accepted by a widely-used reference engine's equivalent role-img-alt rule).
+ *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM).
  */
 
 const id = 'role-img-text-alternative-present';
@@ -152,8 +153,7 @@ function runInPage(ctx) {
     const hasValidAriaLabel = hasAriaLabelAttr && ariaLabel.length > 0;
     const hasValidAriaLabelledbyAttr = hasAriaLabelledbyAttr && ariaLabelledby.length > 0;
 
-    // Last-resort naming mechanism per HTML-AAM (also accepted by
-    // a widely-used reference engine's role-img-alt): a non-empty title attribute.
+    // Last-resort naming mechanism per HTML-AAM: a non-empty title attribute.
     const titleRaw = (() => {
       try {
         return el.getAttribute('title');

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'searchbox-name-present';

package/src/checks/automatic/server-side-image-map-absent.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -16,9 +18,8 @@
  *   users. Client-side image maps (<map>/<area>, each with real href/alt)
  *   are the accessible alternative and are not flagged by this rule.
  * @implementation-notes
- * - Matches a widely-used reference engine's server-side-image-map: presence of ismap is itself
- *   the violation (there is no automatable way to verify a "usable
- *   alternative" exists elsewhere on the page).
+ * - Presence of ismap is itself the violation (there is no automatable way
+ *   to verify a "usable alternative" exists elsewhere on the page).
  */
 
 const id = 'server-side-image-map-absent';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'slider-name-present';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'spinbutton-name-present';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'summary-name-present';

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

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

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';

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';
 
 /**

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';

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';

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';

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

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

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

package/src/checks/manual/canvas-text-alternative-quality-manual.js

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