@surea11y/core 1.3.0 → 1.4.0

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check region
  * @atomic true
  * @summary Page content should be contained within a landmark region
- * @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 to any element under <body> that directly carries visible text
  *   (or other own content — see @implementation-notes) and is not itself a
@@ -20,18 +22,15 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent and the landmark-
  *   detection model.
- * - Recursive tree walk, not a direct-<body>-children-only scan (that was
- *   this check's original scope, replaced 2026-08-01). The direct-children
- *   scope was originally chosen to keep this check quiet, but it turned out
- *   to be nearly inert on the single most common real-world page shape: a
- *   modern framework's single root mount div
- *   (`<body><div id="root">...everything...</div></body>`, confirmed
- *   present as the ONLY direct <body> child on 37 of ~90 pages in a
- *   real-world corpus). On that shape, the old scan had at most one
- *   candidate for the entire page and either missed every real gap inside
- *   it or collapsed the whole page into one undifferentiated report.
- * - Algorithm, using this engine's own (already more spec-correct in
- *   places — see hasLandmarkScopingAncestor's header comment) helpers:
+ * - Recursive tree walk, not a direct-<body>-children-only scan: a
+ *   direct-children-only scope is nearly inert on the single most common
+ *   real-world page shape, a modern framework's single root mount div
+ *   (`<body><div id="root">...everything...</div></body>`) — that shape
+ *   gives at most one candidate for the entire page and either misses
+ *   every real gap inside it or collapses the whole page into one
+ *   undifferentiated report.
+ * - Algorithm, using this engine's own helpers (see
+ *   hasLandmarkScopingAncestor's header comment):
  *     1. Depth-first walk from <body>'s children.
  *     2. At each node: if it's ineligible for the accessibility tree
  *        (helpers.isAccTreeEligible), OR is itself a "stopper" (landmark,
@@ -52,7 +51,7 @@
  *   contiguous unplaced content into one occurrence per real gap instead
  *   of reporting every individual text-bearing leaf — this is what keeps
  *   the walk from being noisy on ordinary pages that mix landmarked and
- *   stray content, not the old direct-children-only restriction.
+ *   stray content.
  * - "Stopper" exemptions (button, dialog, <svg>, resolvable skip-links)
  *   are a deliberate scope choice, not an oversight: these
  *   are extremely common real-world patterns (floating action buttons,
@@ -119,9 +118,7 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.getLandmarkNameInfo (aria-label -> aria-labelledby, via the
   // target's own accessible name, not raw textContent -> title attribute fallback) rather than a
-  // local copy -- see that function's header comment in src/core/dom-helpers.js for the real bug
-  // (missing title fallback) this replaced across all 7 landmark rule files that had their own
-  // copy of this logic.
+  // local copy -- see that function's header comment in src/core/dom-helpers.js.
   function getAccessibleLandmarkName(el) {
     try {
       if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
@@ -144,10 +141,9 @@ function runInPage(ctx) {
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm and the real page
-  // (handsontable.com's docs-assistant side panel, an
-  // <aside role="dialog"> containing its own <header>) that surfaced this
-  // rule's own former tag-only copy as a false negative.
+  // in src/core/aria-helpers.js for the full algorithm — e.g. an
+  // <aside role="dialog"> containing its own <header>, where the <header>
+  // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
     return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
       ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
@@ -161,11 +157,9 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — matches
-      // landmark-unique's own verified-against-reference-engine precedent
-      // (that engine's real `aside` implicit-role function keeps
+      // A named <aside> is never suppressed, even when nested: keeps
       // "complementary" when the element has an accessible name, even
-      // inside sectioning content); propagated here for consistency.
+      // inside sectioning content. See landmark-unique-manual.js.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
@@ -196,8 +190,7 @@ function runInPage(ctx) {
 
   // Roles/attributes that make an element its own self-contained
   // announced area — not literally a WAI-ARIA landmark, but not "content
-  // that needs a landmark" either. Same live-region role list a widely-used
-  // reference engine's own region rule stops recursion at.
+  // that needs a landmark" either.
   const LIVE_REGION_ROLES = new Set(['alert', 'status', 'log', 'marquee', 'timer']);
 
   function isAriaLive(el) {
@@ -257,12 +250,11 @@ function runInPage(ctx) {
   const VISUAL_CONTENT_TAGS = new Set(['img', 'video', 'audio', 'canvas', 'object', 'embed']);
 
   // Non-recursive "does THIS element, on its own, carry content" check —
-  // deliberately mirrors only the direct-content half of getContentNameInfo/
-  // a widely-used reference engine's own has-content check, not a full
-  // name-from-content recursion: the whole point is to keep recursing
-  // through plain wrapper elements (a framework's root mount <div> included)
-  // until reaching the actual content-bearing node, rather than a coarse
-  // ancestor swallowing everything beneath it into one report.
+  // deliberately mirrors only the direct-content half of getContentNameInfo,
+  // not a full name-from-content recursion: the whole point is to keep
+  // recursing through plain wrapper elements (a framework's root mount
+  // <div> included) until reaching the actual content-bearing node, rather
+  // than a coarse ancestor swallowing everything beneath it into one report.
   function hasOwnContent(el) {
     const kids = el.childNodes || [];
     for (let i = 0; i < kids.length; i++) {
@@ -341,9 +333,8 @@ function runInPage(ctx) {
   // Collapse each candidate leaf upward through parents that have no OTHER
   // stopper anywhere in their subtree, so contiguous unplaced content
   // merges into ONE occurrence per real gap instead of one per text node --
-  // this collapsing, not the old direct-children-only scope, is what keeps
-  // ordinary pages (landmarked content mixed with a little stray content)
-  // from producing noisy, one-per-leaf reports.
+  // this collapsing is what keeps ordinary pages (landmarked content mixed
+  // with a little stray content) from producing noisy, one-per-leaf reports.
   const collapsed = [];
   const seen = new Set();
   for (const leaf of leaves) {

package/src/checks/manual/scope-attr-valid-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check scope-attr-valid
  * @atomic true
  * @summary The scope attribute must have a valid value
- * @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 to elements with a non-empty scope attribute.
  * @expectation

package/src/checks/manual/scrollable-region-focusable-manual.js

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

package/src/checks/manual/skip-link-manual.js

@@ -1,20 +1,21 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check skip-link
  * @atomic true
  * @summary A "skip" link must resolve to a real, usable target
- * @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 to <a href="#fragment"> elements whose accessible name
  *   matches a common "skip to ..." / "jump to ..." authoring convention
  *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
  *   pattern for a skip-navigation link, not every same-page anchor link
- *   on the page. "jump to" added 2026-07-23 after a real page (Wish.com)
- *   surfaced a skip link reading "Jump to section" with a genuinely
- *   missing target — invisible to the original "skip"-only pattern,
- *   while a widely-used reference engine's own (purely positional, not text-based) matching
- *   caught it. Text-pattern matching itself stays deliberate (see
+ *   on the page. "jump to" is included alongside "skip" since real skip
+ *   links use both conventions (e.g. a "Jump to section" link, which a
+ *   purely positional match would catch but a "skip"-only text pattern
+ *   would miss). Text-pattern matching itself stays deliberate (see
  *   implementation-notes) — this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document

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

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

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check tabindex
  * @atomic true
  * @summary tabindex should not be greater than 0
- * @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 to elements with a tabindex attribute whose value parses as
  *   a valid integer.

package/src/checks/manual/table-duplicate-name-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check table-duplicate-name
  * @atomic true
  * @summary A table's caption must not duplicate its summary attribute
- * @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 to <table> elements that have both a <caption> with text
  *   content and a (deprecated but still encountered) summary attribute.
@@ -17,9 +19,8 @@
  * - 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.
- * - Narrowly scoped to caption-vs-summary duplication specifically
- *   (matching a reference engine's table-duplicate-name check), not a general "table
- *   name quality" check.
+ * - Narrowly scoped to caption-vs-summary duplication specifically, not a
+ *   general "table name quality" check.
  */
 
 const id = 'table-duplicate-name';

package/src/checks/manual/table-fake-caption-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -64,6 +66,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 nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
   const occurrences = [];
@@ -75,20 +90,26 @@ function runInPage(ctx) {
     const hasCaption = !!(table.querySelector && table.querySelector('caption'));
     if (hasCaption) continue;
 
-    const rows = Array.from(table.rows);
+    // An aria-hidden row (or cell) isn't part of the AT-perceived table
+    // structure at all -- it must not be treated as the table's "first
+    // row" (or counted toward a row's cell count) for this positional
+    // heuristic.
+    const rows = Array.from(table.rows).filter(isEligible);
     if (rows.length < 2) continue;
 
     applicableCount += 1;
 
     const firstRow = rows[0];
-    const firstRowCells = Array.from(firstRow.cells || []);
+    const firstRowCells = Array.from(firstRow.cells || []).filter(isEligible);
     if (firstRowCells.length !== 1) continue;
 
     const candidateCell = firstRowCells[0];
     const candidateText = trim(candidateCell.textContent || '');
     if (!candidateText) continue;
 
-    const hasMultiCellRow = rows.slice(1).some((r) => Array.from(r.cells || []).length > 1);
+    const hasMultiCellRow = rows
+      .slice(1)
+      .some((r) => Array.from(r.cells || []).filter(isEligible).length > 1);
     if (!hasMultiCellRow) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(table) : 'html';

package/src/checks/manual/video-caption-manual.js

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

package/src/checks/manual-review.js

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