@surea11y/core 1.4.1 → 1.6.0

package/src/checks/manual/empty-heading-manual.js

@@ -6,7 +6,7 @@
  * @check empty-heading
  * @atomic true
  * @summary Heading elements must not be empty
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with a heading role: native <h1>-<h6>, or any
  *   element with explicit role="heading" (unless overridden by another
@@ -18,20 +18,20 @@
  *   heading is announced as "heading, level N" with nothing else, which
  *   is confusing when navigating by heading.
  * @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.
  * - This is also the reconciliation point for the ACT-rules
- *   "heading-name-present" requirement (see ROADMAP.md "Tier 5
- *   candidates"): already covered by this pre-existing rule under a
- *   different name, not a separate gap. `title` is accepted as a naming
+ *   "heading-name-present" requirement: already covered by this
+ *   pre-existing rule under a different name, not a separate gap.
+ *   `title` is accepted as a naming
  *   fallback, and hidden/aria-hidden/display:none headings are excluded
  *   (gated on `isAccTreeEligible`), so an empty heading no AT user could
  *   ever reach is not flagged.
  * - Descendant name resolution uses the shared, accname-aligned
- *   `helpers.getContentNameInfo` (see dom-helpers.js) — the same "name
+ *   `helpers.getContentNameInfo` (see dom-helpers.js), the same "name
  *   from content" implementation the 19 `-name-present` rules already
- *   use — rather than a narrower hand-rolled walker, so an `<img alt="...">`
+ *   use, rather than a narrower hand-rolled walker, so an `<img alt="...">`
  *   descendant's alt text (e.g. a
  *   `<h1><a><div><img alt="..."></div></a></h1>` logo header) is correctly
  *   picked up as the heading's name instead of producing a false "empty
@@ -74,11 +74,58 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
+  // Same Global States and Properties set used elsewhere in this engine
+  // (aria-required-parent.js, aria-prohibited-children.js) for the same
+  // presentational-roles-conflict-resolution concept: a native h1-h6
+  // marked role="none"/"presentation" still reverts to its native heading
+  // role when it carries a global ARIA attribute (even one with an empty
+  // value, like aria-label="" -- the attribute's presence is what
+  // triggers conflict resolution, not its value).
+  const GLOBAL_ARIA_ATTRS = [
+    'aria-atomic',
+    'aria-braillelabel',
+    'aria-brailleroledescription',
+    'aria-busy',
+    'aria-controls',
+    'aria-current',
+    'aria-describedby',
+    'aria-description',
+    'aria-details',
+    'aria-disabled',
+    'aria-dropeffect',
+    'aria-errormessage',
+    'aria-flowto',
+    'aria-grabbed',
+    'aria-haspopup',
+    'aria-hidden',
+    'aria-invalid',
+    'aria-keyshortcuts',
+    'aria-label',
+    'aria-labelledby',
+    'aria-live',
+    'aria-owns',
+    'aria-relevant',
+    'aria-roledescription'
+  ];
+
+  function hasGlobalAriaAttr(el) {
+    for (const attr of GLOBAL_ARIA_ATTRS) {
+      if (el.getAttribute && el.getAttribute(attr) != null) return true;
+    }
+    return false;
+  }
+
   function isHeading(el) {
-    const explicit = getExplicitRoleToken(el);
-    if (explicit) return explicit === 'heading';
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    return /^h[1-6]$/.test(tag);
+    const isNativeHeadingTag = /^h[1-6]$/.test(tag);
+
+    const explicit = getExplicitRoleToken(el);
+    if (!explicit) return isNativeHeadingTag;
+    if (explicit === 'heading') return true;
+    if ((explicit === 'none' || explicit === 'presentation') && isNativeHeadingTag) {
+      return hasGlobalAriaAttr(el);
+    }
+    return false;
   }
 
   function getAccessibleNameText(el) {
@@ -100,7 +147,7 @@ function runInPage(ctx) {
       if (joined) return joined;
     }
     // Shared, accname-aligned "name from content" implementation (see
-    // dom-helpers.js's getContentNameInfo header comment) — resolves an
+    // dom-helpers.js's getContentNameInfo header comment). Resolves an
     // <img> descendant's own alt text, an aria-label/aria-labelledby'd
     // descendant's own name, etc., and already gates every descendant on
     // full accessibility-tree eligibility (aria-hidden, display:none,
@@ -148,8 +195,6 @@ function runInPage(ctx) {
     const name = getAccessibleNameText(el);
     if (name) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const eligInfo = helpers.getEligibilityInfo
       ? (() => {
           try {
@@ -160,21 +205,21 @@ function runInPage(ctx) {
         })()
       : null;
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This heading has no accessible name.',
-      hint: 'Add text content (or aria-label/aria-labelledby) to this heading, or remove it if it is not needed.',
-      i18n: {
-        summaryKey: 'emptyHeading_summary_cantTell',
-        hintKey: 'emptyHeading_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'HEADING_EMPTY' },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This heading has no accessible name.',
+        hint: 'Add text content (or aria-label/aria-labelledby) to this heading, or remove it if it is not needed.',
+        i18n: {
+          summaryKey: 'emptyHeading_summary_cantTell',
+          hintKey: 'emptyHeading_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'HEADING_EMPTY' },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -6,7 +6,7 @@
  * @check empty-table-header
  * @atomic true
  * @summary Table header cells must not be empty
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to <th> elements that don't carry a conflicting explicit role,
  *   plus any element (native <th> or not) with role="columnheader" or
@@ -19,19 +19,19 @@
  * @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 — aria-label support on <th> is genuinely
- *   inconsistent in practice: NVDA+Firefox and iOS VoiceOver+Safari ignore
+ *   treated as equivalent: aria-label support on <th> is 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
+ * - 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.
  * - Two distinct reasonCodes: TABLE_HEADER_EMPTY (no accessible name at
  *   all) vs. TABLE_HEADER_NAME_NOT_VISIBLE_TEXT (has aria-label/
- *   aria-labelledby but no visible text) — the latter gets a different
+ *   aria-labelledby but no visible text), the latter gets a different
  *   summary/hint explaining the AT-support gap, since the header isn't
  *   literally nameless, just unreliably named in practice.
  */
@@ -41,7 +41,7 @@ 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.',
+    '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'
@@ -141,43 +141,40 @@ function runInPage(ctx) {
 
     if (getVisibleText(el)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    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.',
-        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.',
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          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',
+            hintKey: 'emptyTableHeader_hint_cantTell_ariaOnly',
+            params: {}
+          },
+          data: {
+            details: { reasonCode: 'TABLE_HEADER_NAME_NOT_VISIBLE_TEXT', ariaName }
+          }
+        })
+      );
+      continue;
+    }
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This table header cell has no accessible name.',
+        hint: 'Add text content (or aria-label/aria-labelledby) to this header cell, or remove it if it is not needed.',
         i18n: {
-          summaryKey: 'emptyTableHeader_summary_cantTell_ariaOnly',
-          hintKey: 'emptyTableHeader_hint_cantTell_ariaOnly',
+          summaryKey: 'emptyTableHeader_summary_cantTell',
+          hintKey: 'emptyTableHeader_hint_cantTell',
           params: {}
         },
         data: {
-          details: { reasonCode: 'TABLE_HEADER_NAME_NOT_VISIBLE_TEXT', ariaName }
+          details: { reasonCode: 'TABLE_HEADER_EMPTY' }
         }
-      });
-      continue;
-    }
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This table header cell has no accessible name.',
-      hint: 'Add text content (or aria-label/aria-labelledby) to this header cell, or remove it if it is not needed.',
-      i18n: {
-        summaryKey: 'emptyTableHeader_summary_cantTell',
-        hintKey: 'emptyTableHeader_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'TABLE_HEADER_EMPTY' }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -6,32 +6,32 @@
  * @check focus-order-semantics
  * @atomic true
  * @summary Elements added to the tab order should have interactive semantics
- * @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 `tabindex` of `0` or greater (in the tab
  *   order) AND an explicit `role` attribute that is one of a curated set
  *   of clearly non-interactive, structural/document roles.
  * @expectation
- *   An element deliberately placed in the tab order should communicate
- *   why it's focusable — a role like `heading`, `list`, `region`, or
+ *   An element placed in the tab order on purpose should communicate
+ *   why it's focusable: a role like `heading`, `list`, `region`, or
  *   `presentation` gives assistive technology no interactive semantic to
  *   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 — authored as an advisory, cantTell-capped
+ * - 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
- *   (`option`, `tab`, `menuitem`, etc.) are never flagged. Elements with
- *   `tabindex` and NO role at all are also not flagged: native semantics
- *   or an intentionally generic custom-interactive pattern cannot be
+ * - The non-interactive role list is curated and conservative
+ *   (structural/document roles only). Legitimate custom widget patterns
+ *   using `tabindex` with an actually interactive role (`option`, `tab`,
+ *   `menuitem`, etc.) are never flagged. Elements with `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
+ * - `region` is intentionally excluded from 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), so 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