@surea11y/core 1.2.0 → 1.4.0

package/src/checks/manual/empty-table-header-manual.js

@@ -1,36 +1,30 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check empty-table-header
  * @atomic true
  * @summary Table header cells must not be empty
- * @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 <th> elements that don't carry a conflicting explicit role,
  *   plus any element (native <th> or not) with role="columnheader" or
- *   role="rowheader" — matches a widely-used reference engine's own
- *   `empty-table-header` selector exactly (`th:not([role]), [role="columnheader"], [role="rowheader"]`,
- *   verified directly against its rule descriptor): a <th> that explicitly
- *   restates role="columnheader"/"rowheader" is still covered via the second
- *   clause, but a <th role="presentation"> (no longer meaningfully a header)
- *   is correctly excluded, and an ARIA-role-only header (e.g. a <div
- *   role="columnheader"> in a role="grid"/role="table" widget) is caught too
- *   — found missing entirely via the cross-engine diff tool 2026-07-23.
+ *   role="rowheader" (`th:not([role]), [role="columnheader"], [role="rowheader"]`):
+ *   a <th> that explicitly restates role="columnheader"/"rowheader" is still
+ *   covered via the second clause, but a <th role="presentation"> (no longer
+ *   meaningfully a header) is correctly excluded, and an ARIA-role-only header
+ *   (e.g. a <div role="columnheader"> in a role="grid"/role="table" widget) is
+ *   caught too.
  * @expectation
  *   The header cell has visible text content. A <th> named only via
  *   aria-label/aria-labelledby (no visible text) is ALSO flagged, not
- *   treated as equivalent — real screen-reader/browser testing (found via
- *   a live-DOM cross-engine run 2026-07-21, verified against
- *   https://butterpep.com/table-header-naming.html and
- *   https://html5accessibility.com/stuff/2024/05/22/not-so-short-note-on-aria-label-usage-big-table-edition/)
- *   confirms aria-label support on <th> is genuinely inconsistent in
- *   practice: NVDA+Firefox and iOS VoiceOver+Safari ignore it entirely
- *   (only visible text is announced), JAWS+Chrome/IE11 also only announce
- *   visible text in the header cell itself. Visible text is the one
- *   mechanism confirmed to work across every tested combination. A widely-used
- *   reference engine's own equivalent check (`has-visible-text` only, no aria-label/
- *   aria-labelledby alternative — confirmed directly against its rule
- *   descriptor) reaches the same conclusion.
+ *   treated as equivalent — aria-label support on <th> is genuinely
+ *   inconsistent in practice: NVDA+Firefox and iOS VoiceOver+Safari ignore
+ *   it entirely (only visible text is announced), JAWS+Chrome/IE11 also only
+ *   announce visible text in the header cell itself. Visible text is the one
+ *   mechanism confirmed to work across every tested combination. See
+ *   https://html5accessibility.com/stuff/2024/05/22/not-so-short-note-on-aria-label-usage-big-table-edition/.
  * @implementation-notes
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
@@ -46,7 +40,8 @@ const id = 'empty-table-header';
 
 const meta = {
   title: 'Table header cells must not be empty',
-  description: 'Checks that table header cells (<th>, or any element with role="columnheader"/"rowheader") have visible text content — a header named only via aria-label/aria-labelledby is also flagged, since real screen-reader/browser support for that is inconsistent.',
+  description:
+    'Checks that table header cells (<th>, or any element with role="columnheader"/"rowheader") have visible text content — a header named only via aria-label/aria-labelledby is also flagged, since real screen-reader/browser support for that is inconsistent.',
   i18n: {
     titleKey: 'emptyTableHeader_title',
     descriptionKey: 'emptyTableHeader_description'
@@ -66,11 +61,41 @@ function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .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;
+    }
   }
 
+  // Plain el.textContent includes text from aria-hidden descendants, which
+  // a real screen reader never announces. A <th> whose only text comes from
+  // an aria-hidden descendant (e.g. <th><span aria-hidden="true">Name</span
+  // ></th>) would otherwise be treated as having visible text, even though
+  // AT announces nothing for it.
   function getVisibleText(el) {
-    return normalizeWs(el.textContent);
+    function walk(node) {
+      if (node.nodeType === 3) return node.nodeValue || '';
+      if (node.nodeType !== 1) return '';
+      if (!isEligible(node)) return '';
+      let text = '';
+      for (const child of node.childNodes || []) text += walk(child);
+      return text;
+    }
+    let text = '';
+    for (const child of el.childNodes || []) text += walk(child);
+    return normalizeWs(text);
   }
 
   function getAriaOnlyName(el) {
@@ -94,30 +119,38 @@ function runInPage(ctx) {
     return '';
   }
 
-  // Matches a widely-used reference engine's own empty-table-header selector exactly: a <th> with
-  // no conflicting explicit role, plus any element carrying an explicit
-  // columnheader/rowheader role (native or not).
+  // A <th> with no conflicting explicit role, plus any element carrying an
+  // explicit columnheader/rowheader role (native or not).
   const selector = 'th:not([role]), [role="columnheader"], [role="rowheader"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el) continue;
+
+    // A fully aria-hidden header cell isn't part of the AT-perceived
+    // table structure at all -- queryAllSmart's default hidden-content
+    // policy only excludes "hard" CSS-based hiding, not aria-hidden.
+    if (!isEligible(el)) continue;
+
     applicableCount += 1;
 
     if (getVisibleText(el)) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     const ariaName = getAriaOnlyName(el);
     if (ariaName) {
       occurrences.push({
         selector: stableSelector,
         html,
-        summary: 'This table header cell has no visible text — its only accessible name comes from aria-label/aria-labelledby, which real screen-reader/browser combinations (e.g. NVDA+Firefox, iOS VoiceOver+Safari) are known to ignore on <th> elements.',
+        summary:
+          'This table header cell has no visible text — its only accessible name comes from aria-label/aria-labelledby, which real screen-reader/browser combinations (e.g. NVDA+Firefox, iOS VoiceOver+Safari) are known to ignore on <th> elements.',
         hint: 'Add visible text content to this header cell (in addition to, or instead of, aria-label/aria-labelledby) — visible text is the only naming mechanism confirmed to work across tested screen readers.',
         i18n: {
           summaryKey: 'emptyTableHeader_summary_cantTell_ariaOnly',
@@ -151,7 +184,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }

package/src/checks/manual/focus-order-semantics-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check focus-order-semantics
  * @atomic true
  * @summary Elements added to the tab order should have interactive semantics
- * @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 `tabindex` of `0` or greater (in the tab
  *   order) AND an explicit `role` attribute that is one of a curated set
@@ -16,8 +18,8 @@
  *   announce, which is confusing for keyboard users who land on it and
  *   get no indication of what activating it (if anything) would do.
  * @implementation-notes
- * - Not WCAG-normative by a widely-used reference engine's own classification — authored as an
- *   advisory, cantTell-capped `type: 'manual'` rule.
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule.
  * - The non-interactive role list is deliberately curated and
  *   conservative (structural/document roles only) — legitimate custom
  *   widget patterns using `tabindex` with a genuinely interactive role
@@ -25,13 +27,25 @@
  *   `tabindex` and NO role at all are also not flagged: native semantics
  *   or an intentionally generic custom-interactive pattern cannot be
  *   distinguished from markup alone with the same confidence.
+ * - `region` is deliberately NOT in the non-interactive role list: a
+ *   tabbable `role="region"` is a real, WCAG 2.1.1/2.1.3-grounded pattern
+ *   this engine's own `scrollable-region-focusable` check exists to
+ *   RECOMMEND (a scrollable landmark with no other focusable content
+ *   needs `tabindex="0"` to be keyboard-reachable at all) — flagging it
+ *   here would be internally inconsistent with that sibling check. A
+ *   `role="region"` is also commonly made tabbable on its own merits
+ *   (e.g. a cookie-consent banner or notification/toast region a keyboard
+ *   user should be able to reach directly, as in
+ *   `<div role="region" tabindex="0">`). Scoped to `region` only;
+ *   navigation/status/tabpanel remain flagged pending their own evidence.
  */
 
 const id = 'focus-order-semantics';
 
 const meta = {
   title: 'Elements added to the tab order should have interactive semantics',
-  description: 'Flags elements with tabindex >= 0 whose explicit role is a non-interactive structural/document role (e.g. heading, list, region, presentation), for manual review.',
+  description:
+    'Flags elements with tabindex >= 0 whose explicit role is a non-interactive structural/document role (e.g. heading, list, region, presentation), for manual review.',
   i18n: {
     titleKey: 'focusOrderSemantics_title',
     descriptionKey: 'focusOrderSemantics_description'
@@ -48,17 +62,45 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const NON_INTERACTIVE_ROLES = new Set([
-    'generic', 'group', 'text', 'presentation', 'none', 'img', 'heading',
-    'region', 'article', 'banner', 'contentinfo', 'main', 'navigation',
-    'complementary', 'document', 'note', 'list', 'listitem', 'table',
-    'row', 'cell', 'columnheader', 'rowheader', 'figure', 'term',
-    'definition', 'paragraph', 'caption', 'status', 'alert', 'log', 'tooltip'
+    'generic',
+    'group',
+    'text',
+    'presentation',
+    'none',
+    'img',
+    'heading',
+    'article',
+    'banner',
+    'contentinfo',
+    'main',
+    'navigation',
+    'complementary',
+    'document',
+    'note',
+    'list',
+    'listitem',
+    'table',
+    'row',
+    'cell',
+    'columnheader',
+    'rowheader',
+    'figure',
+    'term',
+    'definition',
+    'paragraph',
+    'caption',
+    'status',
+    'alert',
+    'log',
+    'tooltip'
   ]);
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex][role]') : helpers.queryAll('[tabindex][role]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[tabindex][role]')
+    : helpers.queryAll('[tabindex][role]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -78,7 +120,7 @@ function runInPage(ctx) {
     if (!NON_INTERACTIVE_ROLES.has(role)) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     const baseOccurrence = {
       selector: stableSelector,
@@ -107,7 +149,12 @@ function runInPage(ctx) {
   }
 
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
 
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };