@surea11y/core 1.4.0 → 1.5.0

package/src/checks/automatic/link-in-text-block.js

@@ -215,31 +215,29 @@ function runInPage(ctx) {
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
     const ratioStr = c.round2 ? c.round2(ratio) : String(ratio);
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
-      hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
-      i18n: {
-        summaryKey: 'linkInTextBlock_summary_fail',
-        hintKey: 'linkInTextBlock_hint_fail',
-        params: { element: tag, ratio: String(ratioStr), threshold: '3' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: {
-          reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
-          metrics: { ratio, threshold: 3 },
-          colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
+        hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
+        i18n: {
+          summaryKey: 'linkInTextBlock_summary_fail',
+          hintKey: 'linkInTextBlock_hint_fail',
+          params: { element: tag, ratio: String(ratioStr), threshold: '3' }
+        },
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
+            metrics: { ratio, threshold: 3 },
+            colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -59,7 +59,14 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     // isAccTreeEligible returns { eligible, reasons }, not a boolean.
-    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    // Naming rules apply only to elements included in the accessibility tree
+    // (ACT c487ae), which excludes focusable aria-hidden content;
+    // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
+    const eligResult = helpers.isIncludedInAccessibilityTree
+      ? helpers.isIncludedInAccessibilityTree(el, ctx)
+      : helpers.isAccTreeEligible
+        ? helpers.isAccTreeEligible(el, ctx)
+        : true;
     const eligible =
       typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
     if (!eligible) continue;
@@ -69,33 +76,59 @@ function runInPage(ctx) {
     const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
     const programmaticName = nameInfo && typeof nameInfo.value === 'string' ? nameInfo.value : '';
 
-    // A native <a href>/<area href> (or [role="link"]) whose role has been
-    // overridden to one of these roles is no longer semantically a link —
-    // per the WAI-ARIA Accessible Name and Description Computation spec
-    // these roles are name-from-author-only, and their rendered content
-    // represents a VALUE, not a NAME (see button-name-present.js's identical
-    // fix for a real-world example — <button role="combobox">List</button> —
-    // of the same class of bug on a different host tag).
     const role = el.getAttribute ? el.getAttribute('role') : null;
     const roleNorm = String(role || '')
       .replace(/\s+/g, ' ')
       .trim()
       .toLowerCase();
-    const VALUE_ROLES = [
-      'textbox',
-      'progressbar',
-      'scrollbar',
-      'slider',
-      'spinbutton',
-      'combobox',
-      'listbox'
+    // ARIA 1.2 "Name From: author, contents". Every other known role is
+    // name-from-author-only. An unknown role falls back to the implicit role.
+    // <generated:aria-name-from-content>
+    const NAME_FROM_CONTENT_ROLES = [
+      'button',
+      'cell',
+      'checkbox',
+      'columnheader',
+      'doc-backlink',
+      'doc-biblioref',
+      'doc-glossref',
+      'doc-noteref',
+      'graphics-object',
+      'gridcell',
+      'heading',
+      'link',
+      'menuitem',
+      'menuitemcheckbox',
+      'menuitemradio',
+      'option',
+      'radio',
+      'row',
+      'rowgroup',
+      'rowheader',
+      'switch',
+      'tab',
+      'tooltip',
+      'treeitem'
     ];
-    const isContentNameCandidate = !VALUE_ROLES.includes(roleNorm);
+    // </generated:aria-name-from-content>
+    const isKnownRoleToken =
+      helpers && helpers.aria && typeof helpers.aria.isKnownRole === 'function'
+        ? (() => {
+            try {
+              return !!helpers.aria.isKnownRole(roleNorm);
+            } catch {
+              return false;
+            }
+          })()
+        : false;
+    const isContentNameCandidate =
+      !roleNorm || !isKnownRoleToken || NAME_FROM_CONTENT_ROLES.includes(roleNorm);
 
     const contentName =
       programmaticName.trim().length === 0 && isContentNameCandidate
         ? getConservativeSubtreeText(el)
         : '';
+
     const finalName = (programmaticName.trim().length ? programmaticName : contentName).trim();
 
     if (finalName.length === 0) {
@@ -106,39 +139,34 @@ function runInPage(ctx) {
         ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
         : null;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
       const tag = (el.tagName || '').toLowerCase();
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-
-        // Human fallbacks (allowed)
-        summary: 'This link has no accessible name.',
-        hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
-
-        // Validator requires these keys to exist in the English dictionary
-        i18n: {
-          summaryKey: 'linkNamePresent_summary_fail',
-          hintKey: 'linkNamePresent_hint_fail',
-          params: { element: tag }
-        },
-
-        data: {
-          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-          details: {
-            reasonCode: 'name_missing',
-            metrics: {
-              programmaticNameLength: programmaticName.trim().length,
-              contentNameLength: contentName.trim().length
-            },
-            refs: { accessibleName: nameInfo || null }
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          // Human fallbacks (allowed)
+          summary: 'This link has no accessible name.',
+          hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
+
+          // Validator requires these keys to exist in the English dictionary
+          i18n: {
+            summaryKey: 'linkNamePresent_summary_fail',
+            hintKey: 'linkNamePresent_hint_fail',
+            params: { element: tag }
+          },
+
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: {
+              reasonCode: 'name_missing',
+              metrics: {
+                programmaticNameLength: programmaticName.trim().length,
+                contentNameLength: contentName.trim().length
+              },
+              refs: { accessibleName: nameInfo || null }
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/list-children-valid.js

@@ -122,23 +122,21 @@ function runInPage(ctx) {
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list contains a direct child that is not a list item.',
-      hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
-      i18n: {
-        summaryKey: 'listChildrenValid_summary_fail',
-        hintKey: 'listChildrenValid_hint_fail',
-        params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
-      },
-      data: {
-        details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list contains a direct child that is not a list item.',
+        hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
+        i18n: {
+          summaryKey: 'listChildrenValid_summary_fail',
+          hintKey: 'listChildrenValid_hint_fail',
+          params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
+        },
+        data: {
+          details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -109,9 +109,16 @@ function runInPage(ctx) {
     return '';
   }
 
+  // Naming rules apply only to elements included in the accessibility tree
+  // (ACT c487ae and siblings), which excludes focusable aria-hidden content.
+  // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
   function isEligibleAcc(helpers, el, ctx) {
     const fn =
-      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+      helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+        ? helpers.isIncludedInAccessibilityTree
+        : helpers && typeof helpers.isAccTreeEligible === 'function'
+          ? helpers.isAccTreeEligible
+          : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -220,24 +227,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      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 listbox's accessible name.",
-      i18n: {
-        summaryKey: 'listboxNamePresent_summary_fail',
-        hintKey: 'listboxNamePresent_hint_fail',
-        params: { controlType: 'listbox' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'listbox', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    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 listbox's accessible name.",
+        i18n: {
+          summaryKey: 'listboxNamePresent_summary_fail',
+          hintKey: 'listboxNamePresent_hint_fail',
+          params: { controlType: 'listbox' }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'listbox', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/listitem-parent-valid.js

@@ -116,23 +116,20 @@ function runInPage(ctx) {
 
     if (valid) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list item is not contained by a list container.',
-      hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
-      i18n: {
-        summaryKey: 'listitemParentValid_summary_fail',
-        hintKey: 'listitemParentValid_hint_fail',
-        params: { parentElement: parentTag }
-      },
-      data: {
-        details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list item is not contained by a list container.',
+        hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
+        i18n: {
+          summaryKey: 'listitemParentValid_summary_fail',
+          hintKey: 'listitemParentValid_hint_fail',
+          params: { parentElement: parentTag }
+        },
+        data: {
+          details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -84,9 +84,16 @@ function runInPage(ctx) {
     return '';
   }
 
+  // Naming rules apply only to elements included in the accessibility tree
+  // (ACT c487ae and siblings), which excludes focusable aria-hidden content.
+  // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
   function isEligibleAcc(helpers, el, ctx) {
     const fn =
-      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+      helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+        ? helpers.isIncludedInAccessibilityTree
+        : helpers && typeof helpers.isAccTreeEligible === 'function'
+          ? helpers.isAccTreeEligible
+          : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -143,24 +150,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This menu item has no accessible name.',
-      hint: 'Provide visible text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
-      i18n: {
-        summaryKey: 'menuitemNamePresent_summary_fail',
-        hintKey: 'menuitemNamePresent_hint_fail',
-        params: { role }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This menu item has no accessible name.',
+        hint: 'Provide visible text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+        i18n: {
+          summaryKey: 'menuitemNamePresent_summary_fail',
+          hintKey: 'menuitemNamePresent_hint_fail',
+          params: { role }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/meta-refresh-no-exceptions.js

@@ -87,6 +87,34 @@ function runInPage(ctx) {
     : [];
 
   const occurrences = [];
+  // HTML's shared declarative refresh steps. Returns the delay in seconds, or
+  // null when the value is not a valid refresh directive, in which case the
+  // browser never refreshes and there is nothing to report. Rejects a leading
+  // sign ("+72001"), a non-numeric time ("foo"), and a separator other than
+  // "," or ";" ("0:1").
+  function parseRefreshDelay(input) {
+    const s = String(input == null ? '' : input);
+    const isSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\f' || c === '\r';
+    let i = 0;
+    while (i < s.length && isSpace(s[i])) i++;
+    let digits = '';
+    while (i < s.length && s[i] >= '0' && s[i] <= '9') digits += s[i++];
+    if (!digits) return null;
+    if (s[i] === '.') {
+      i++;
+      while (i < s.length && s[i] >= '0' && s[i] <= '9') i++;
+    }
+    if (i >= s.length) return parseInt(digits, 10);
+    let sawSpace = false;
+    while (i < s.length && isSpace(s[i])) {
+      sawSpace = true;
+      i++;
+    }
+    if (i >= s.length) return parseInt(digits, 10);
+    if (s[i] === ';' || s[i] === ',' || sawSpace) return parseInt(digits, 10);
+    return null;
+  }
+
   let applicableCount = 0;
 
   for (const el of nodes) {
@@ -94,27 +122,25 @@ function runInPage(ctx) {
     if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
+    if (parseRefreshDelay(raw) === null) continue;
 
     applicableCount += 1;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This page uses a meta refresh, which is an automatic context change not initiated by the user.',
-      hint: 'Remove the meta refresh; trigger the redirect/refresh only in response to a user action instead.',
-      i18n: {
-        summaryKey: 'metaRefreshNoExceptions_summary_fail',
-        hintKey: 'metaRefreshNoExceptions_hint_fail',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'META_REFRESH_PRESENT' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This page uses a meta refresh, which is an automatic context change not initiated by the user.',
+        hint: 'Remove the meta refresh; trigger the redirect/refresh only in response to a user action instead.',
+        i18n: {
+          summaryKey: 'metaRefreshNoExceptions_summary_fail',
+          hintKey: 'metaRefreshNoExceptions_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'META_REFRESH_PRESENT' }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/meta-refresh-timing-absent.js

@@ -79,39 +79,62 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // HTML's shared declarative refresh steps. Returns the delay in seconds, or
+  // null when the value is not a valid refresh directive, in which case the
+  // browser never refreshes and there is nothing to report. Rejects a leading
+  // sign ("+72001"), a non-numeric time ("foo"), and a separator other than
+  // "," or ";" ("0:1").
+  function parseRefreshDelay(input) {
+    const s = String(input == null ? '' : input);
+    const isSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\f' || c === '\r';
+    let i = 0;
+    while (i < s.length && isSpace(s[i])) i++;
+    let digits = '';
+    while (i < s.length && s[i] >= '0' && s[i] <= '9') digits += s[i++];
+    if (!digits) return null;
+    if (s[i] === '.') {
+      i++;
+      while (i < s.length && s[i] >= '0' && s[i] <= '9') i++;
+    }
+    if (i >= s.length) return parseInt(digits, 10);
+    let sawSpace = false;
+    while (i < s.length && isSpace(s[i])) {
+      sawSpace = true;
+      i++;
+    }
+    if (i >= s.length) return parseInt(digits, 10);
+    if (s[i] === ';' || s[i] === ',' || sawSpace) return parseInt(digits, 10);
+    return null;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
     if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled — see meta-refresh-no-exceptions.js's header comment
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
 
-    const match = raw.match(/^([0-9]*\.?[0-9]+)/);
-    if (!match) continue;
-    const delay = parseFloat(match[1]);
-    if (Number.isNaN(delay)) continue;
+    const delay = parseRefreshDelay(raw);
+    if (delay === null) continue;
 
     applicableCount += 1;
 
     if (!(delay > 0)) continue;
     if (delay > EXEMPT_DELAY_SECONDS) continue; // WCAG 2.2.1 Exception 3 (>20 hours)
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This page refreshes itself automatically after a delay.',
-      hint: 'Remove the timed meta refresh, or provide a way for users to turn it off, extend it, or pause it before it triggers.',
-      i18n: {
-        summaryKey: 'metaRefreshTimingAbsent_summary_fail',
-        hintKey: 'metaRefreshTimingAbsent_hint_fail',
-        params: { delay: String(delay) }
-      },
-      data: {
-        details: { reasonCode: 'META_REFRESH_DELAYED', delay }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This page refreshes itself automatically after a delay.',
+        hint: 'Remove the timed meta refresh, or provide a way for users to turn it off, extend it, or pause it before it triggers.',
+        i18n: {
+          summaryKey: 'metaRefreshTimingAbsent_summary_fail',
+          hintKey: 'metaRefreshTimingAbsent_hint_fail',
+          params: { delay: String(delay) }
+        },
+        data: {
+          details: { reasonCode: 'META_REFRESH_DELAYED', delay }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {