@surea11y/core 1.5.0 → 1.6.0

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

@@ -2,6 +2,27 @@
 
 'use strict';
 
+/**
+ * @check slider-name-present
+ * @atomic true
+ * @summary Elements with role="slider" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="slider" (the attribute must name that
+ *   role alone, not a fallback list) that are included in the accessibility
+ *   tree. An element with the matching implicit role but no role attribute
+ *   is out of scope. A native <input type="range"> without the role belongs
+ *   to form-control-programmatic-label-present.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="slider" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom slider widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="slider">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'slider-name-present';
 
 const meta = {
@@ -67,7 +88,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -84,7 +105,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -99,10 +120,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -112,7 +133,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -209,7 +230,7 @@ function runInPage(ctx) {
     }
 
     // role="slider" is name-from-author-only per WAI-ARIA (unlike e.g.
-    // role="option"/"tab"), so it must NOT fall back to subtree content —
+    // role="option"/"tab"), so it must NOT fall back to subtree content,
     // visible text near/inside a custom slider widget is not reliably
     // exposed as its accessible name by assistive technologies.
     return { ok: false, method: 'none' };

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check spinbutton-name-present
+ * @atomic true
+ * @summary Elements with role="spinbutton" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="spinbutton" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="spinbutton" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom spinbutton widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="spinbutton">)
+ *   an associated <label> counts as well.
+ */
+
 const id = 'spinbutton-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Spinbuttons have an accessible name',
+  description: 'Checks that elements with role="spinbutton" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'spinbuttonNamePresent_title',
     descriptionKey: 'spinbuttonNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -231,7 +251,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This element has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this spinbutton's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this spinbutton's accessible name.",
         i18n: {
           summaryKey: 'spinbuttonNamePresent_summary_fail',
           hintKey: 'spinbuttonNamePresent_hint_fail',

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

@@ -2,6 +2,22 @@
 
 'use strict';
 
+/**
+ * @check summary-name-present
+ * @atomic true
+ * @summary <summary> elements must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <summary> elements included in the accessibility tree,
+ *   wherever they appear, a <summary> outside a <details> is still matched.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or from its
+ *   own subtree text, where a descendant's own name (an <img alt>,
+ *   aria-label or title) counts as that descendant's contribution.
+ */
+
 const id = 'summary-name-present';
 
 const meta = {
@@ -51,7 +67,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +86,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).

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

@@ -109,7 +109,7 @@ function runInPage(ctx) {
   }
 
   // <desc> counts when it is the first child, or the second child
-  // immediately following a <title> — the standard <title>+<desc> pairing.
+  // immediately following a <title>, the standard <title>+<desc> pairing.
   // A <desc> appearing later than that is not reliably read by AT.
   function descText(el) {
     try {

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

@@ -13,12 +13,15 @@
  *   "Intended to be conveyed" is approximated deterministically by at least one of:
  *     - 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.
+ *       roles, alongside img). Does NOT extend to arbitrary
+ *       role="img"/"graphics-symbol"/"graphics-document" descendants
+ *       nested inside an <svg>. This check's scope is the <svg> root
+ *       only; role-img-text-alternative-present covers those same three
+ *       roles on any other element, including nested SVG shapes (ACT
+ *       7d6734's own failed example: a bare `<svg>` root with a nested
+ *       `<circle role="graphics-symbol">`).
  *     - aria-label / aria-labelledby present
- *     - <title> or <desc> present (desc alone is an applicability signal only — see @expectation)
+ *     - <title> or <desc> present (desc alone is an applicability signal only, see @expectation)
  *     - focusable/tabbable (e.g., tabindex, native focusability)
  *
  *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
@@ -28,7 +31,7 @@
  *   Each applicable <svg> element provides a text alternative via:
  *     - non-empty <title> text, OR
  *     - an ARIA name (aria-label / aria-labelledby).
- *   A <desc> element alone does NOT satisfy this — per the SVG Accessibility
+ *   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. An <svg> with only a
  *   <desc> and no <title>/ARIA name is still "applicable" (desc signals
@@ -40,7 +43,7 @@ const id = 'svg-text-alternative-present';
 const meta = {
   title: '<svg> must provide a text alternative',
   description:
-    'Checks that inline <svg> elements provide a text alternative via a <title> element or an ARIA name (a <desc> element alone does not count — it only contributes to the accessible description, not the name).',
+    'Checks that inline <svg> elements provide a text alternative via a <title> element or an ARIA name (a <desc> element alone does not count).',
   i18n: {
     titleKey: 'svg_textAltPresent_title',
     descriptionKey: 'svg_textAltPresent_description'
@@ -124,7 +127,7 @@ function runInPage(ctx) {
   }
 
   // <desc> counts when it is the first child, or the second child
-  // immediately following a <title> — the standard <title>+<desc> pairing
+  // immediately following a <title>, the standard <title>+<desc> pairing
   // (e.g. <svg><title>...</title><desc>...</desc>...</svg>). A <desc>
   // appearing later than that is not reliably read by AT.
   function nonEmptyDescText(svg) {
@@ -277,7 +280,7 @@ function runInPage(ctx) {
     }
 
     // Per SVG-AAM §7.1: <desc> contributes only to the accessible
-    // DESCRIPTION, never the accessible NAME — so descText does not
+    // DESCRIPTION, never the accessible NAME, so descText does not
     // count here even though it does count toward applicability above.
     const ok = !!titleText || hasAriaName;
     if (ok) continue;
@@ -293,7 +296,7 @@ function runInPage(ctx) {
 
     const baseOccurrence = {
       summary: 'Missing text alternative for <svg>.',
-      hint: 'Provide a <title> element with text, or an ARIA name (aria-label/aria-labelledby) — a <desc> element alone does not provide an accessible name.',
+      hint: 'Provide a <title> element with text, or an ARIA name (aria-label/aria-labelledby); a <desc> element alone does not provide an accessible name.',
       i18n: {
         summaryKey: 'svg_textAltPresent_summary_fail',
         hintKey: 'svg_textAltPresent_hint_fail',

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check tab-name-present
+ * @atomic true
+ * @summary Elements with role="tab" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="tab" (the attribute must name that
+ *   role alone, not a fallback list) that are included in the accessibility
+ *   tree. An element with the matching implicit role but no role attribute
+ *   is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or,
+ *   role="tab" being name-from-content, from its own subtree text, where a
+ *   descendant's own name (an <img alt>, aria-label or title) counts as that
+ *   descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'tab-name-present';
 
 const meta = {
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).

package/src/checks/automatic/table-headers-attr-valid.js

@@ -9,11 +9,18 @@
  * @standard WCAG 2.2
  * @sc 1.3.1
  * @applicability
- *   Applies to <td>/<th> elements that carry a non-empty headers attribute.
+ *   Applies to <td>/<th> elements that carry a non-empty headers attribute,
+ *   within a <table> whose semantic role is still table/grid/treegrid --
+ *   an explicit role of anything else (role="presentation"/"none", but
+ *   also role="heading" or any other real role) replaces the native table
+ *   semantics, leaving no table for headers to describe. Matches ACT
+ *   a25f45's applicability.
  * @expectation
  *   Every id token in the headers attribute resolves to an element that:
- *   (a) exists, (b) is a <th> element, (c) is inside the same <table> as
- *   the referencing cell, and (d) is not the cell itself.
+ *   (a) exists, (b) is a cell (<td> or <th>) of the same <table> as the
+ *   referencing cell, and (c) is not the cell itself. A <td> serving as a
+ *   header via role="columnheader"/"rowheader" is a valid target, same as
+ *   a plain <th> -- ACT a25f45 does not require the native tag.
  * @implementation-notes
  * - One occurrence per offending cell (not per bad token), listing every
  *   invalid reference.
@@ -27,7 +34,7 @@ const id = 'table-headers-attr-valid';
 const meta = {
   title: 'Table cell "headers" attribute must reference valid header cells',
   description:
-    'Checks that each id in a <td>/<th> headers attribute resolves to a <th> element within the same table (not missing, not a non-th element, not itself).',
+    'Checks that each id in a <td>/<th> headers attribute resolves to a cell (<td> or <th>) within the same table (not missing, not a non-cell element, not itself).',
   i18n: {
     titleKey: 'tableHeadersAttrValid_title',
     descriptionKey: 'tableHeadersAttrValid_description'
@@ -54,6 +61,23 @@ const meta = {
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+
+  // The role attribute holds a fallback list; the first token naming a real
+  // role wins, and unknown tokens are skipped over.
+  function getExplicitRole(el) {
+    const raw = el && el.getAttribute ? el.getAttribute('role') : null;
+    if (!raw) return '';
+    const tokens = String(raw).trim().toLowerCase().split(/\s+/);
+    for (const token of tokens) {
+      if (!token) continue;
+      if (token === 'presentation' || token === 'none') return token;
+      const known = ariaHelpers ? ariaHelpers.isValidConcreteRole(token) : true;
+      if (known) return token;
+    }
+    return '';
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('td[headers], th[headers]')
     : helpers.queryAll('td[headers], th[headers]');
@@ -69,9 +93,19 @@ function runInPage(ctx) {
     const ids = raw.split(/\s+/).filter(Boolean);
     if (!ids.length) continue;
 
+    const table = el.closest ? el.closest('table') : null;
+
+    // An explicit role on the <table> replaces its native table role. Only
+    // the three roles that still describe a table keep the cell's headers
+    // attribute meaningful; anything else (presentation/none, heading, ...)
+    // takes the whole table out of scope. Unknown tokens name no role, so
+    // the native one stands.
+    const tableRole = table ? getExplicitRole(table) : '';
+    if (tableRole && tableRole !== 'table' && tableRole !== 'grid' && tableRole !== 'treegrid')
+      continue;
+
     applicableCount += 1;
 
-    const table = el.closest ? el.closest('table') : null;
     const invalid = [];
 
     for (const headerId of ids) {
@@ -90,8 +124,9 @@ function runInPage(ctx) {
         invalid.push({ id: headerId, reason: 'self-reference' });
         continue;
       }
-      if (!ref.tagName || ref.tagName.toLowerCase() !== 'th') {
-        invalid.push({ id: headerId, reason: 'not-a-th' });
+      const refTag = ref.tagName ? ref.tagName.toLowerCase() : '';
+      if (refTag !== 'th' && refTag !== 'td') {
+        invalid.push({ id: headerId, reason: 'not-a-cell' });
         continue;
       }
       if (table && (!ref.closest || ref.closest('table') !== table)) {
@@ -108,7 +143,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This cell’s headers attribute references one or more invalid header cells.',
-        hint: 'Update the headers attribute so every id refers to a <th> element within the same table.',
+        hint: 'Update the headers attribute so every id refers to a cell (<td> or <th>) within the same table.',
         i18n: {
           summaryKey: 'tableHeadersAttrValid_summary_fail',
           hintKey: 'tableHeadersAttrValid_hint_fail',

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

@@ -12,26 +12,29 @@
  *   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.
+ *   explicit role other than rowheader/columnheader. Also applies to the
+ *   ARIA-only equivalent: an element with role="grid"/"treegrid" (no
+ *   native <table> involved) that contains at least one in-scope
+ *   columnheader/rowheader-role element.
  * @expectation
  *   The table also contains at least one <td> somewhere in it.
  * @implementation-notes
- * - DELIBERATELY SCOPED (see aria-helpers.js file header for the same
+ * - SCOPED (see aria-helpers.js file header for the same
  *   conservative-scope rationale used throughout this engine): this rule
  *   does NOT implement the full HTML5 header-association algorithm
  *   (resolving which specific data cells a given <th scope="row"|"col">
  *   describes, accounting for colspan/rowspan and default-scope
  *   inference). That algorithm is one of the more error-prone parts of
  *   the HTML spec to reimplement correctly, and a wrong positional match
- *   would risk a false `fail` — unacceptable for this engine's fail-
+ *   would risk a false `fail`, unacceptable for this engine's fail-
  *   integrity bar.
  * - Instead, this rule only catches the single unambiguous case: a table
  *   that has <th> elements but ZERO <td> elements anywhere. In that case
- *   every <th> in the table trivially describes no data cell — no
+ *   every <th> in the table trivially describes no data cell, no
  *   positional analysis is needed to know that. A table that has at
  *   least one <td> somewhere is not evaluated further by this rule, even
  *   if some particular <th> in it doesn't actually describe any cell
- *   (false negative, not a false positive — acceptable under this
+ *   (false negative, not a false positive, acceptable under this
  *   engine's philosophy).
  * - Applicability IS gated, because the zero-<td> case above turns any
  *   over-broad scope straight into a false fail: a layout table marked
@@ -174,6 +177,59 @@ function runInPage(ctx) {
     }
   }
 
+  // ARIA-only equivalent: a role="grid"/"treegrid" container with no
+  // backing <table> at all. Same trivial "zero data cells anywhere" check,
+  // just keyed off ARIA roles instead of native tags -- a genuine
+  // columnheader/rowheader with zero gridcell/cell-role elements anywhere
+  // in the container is exactly as unambiguous as a <th>-only <table>.
+  const grids = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[role="grid"], [role="treegrid"]')
+    : helpers.queryAll('[role="grid"], [role="treegrid"]');
+
+  for (const grid of grids) {
+    if (!grid || !grid.querySelectorAll) continue;
+    if (grid.tagName && grid.tagName.toLowerCase() === 'table') continue; // already handled above
+    if (!isIncludedInTree(grid)) continue;
+
+    let headerNodes;
+    try {
+      headerNodes = grid.querySelectorAll('[role="columnheader"], [role="rowheader"]');
+    } catch {
+      headerNodes = [];
+    }
+    const headers = Array.from(headerNodes).filter(isHeaderCellInScope);
+    if (!headers.length) continue;
+
+    applicableCount += 1;
+
+    let hasDataCell;
+    try {
+      hasDataCell = grid.querySelectorAll('[role="gridcell"], [role="cell"]').length > 0;
+    } catch {
+      hasDataCell = false;
+    }
+    if (hasDataCell) continue;
+
+    for (const th of headers) {
+      if (!th) continue;
+
+      occurrences.push(
+        helpers.reportOccurrence(th, {
+          summary: 'This table has header cells but no data cells for them to describe.',
+          hint: 'Add data cells (<td>) to the table, or remove the header cells if the table has no data.',
+          i18n: {
+            summaryKey: 'tableThHasDataCells_summary_fail',
+            hintKey: 'tableThHasDataCells_hint_fail',
+            params: {}
+          },
+          data: {
+            details: { reasonCode: 'TABLE_TH_NO_DATA_CELLS' }
+          }
+        })
+      );
+    }
+  }
+
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }