@surea11y/core 1.1.2 → 1.3.0

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

@@ -11,194 +11,205 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "embed-text-alternative-quality";
+const id = 'embed-text-alternative-quality';
 
 const meta = {
-    title: "<embed> text alternative must be appropriate (manual review)",
-    description: "Flags <embed> elements with a detected name for human review of appropriateness.",
-    i18n: {
-        titleKey: "embed_textAltQuality_title",
-        descriptionKey: "embed_textAltQuality_description"
-    },
-    helpUrl: null,
-    tags: ["wcag2a", "wcag111", "nontext", "embed", "manual", "atomic"],
-    wcagSc: ['1.1.1'],
-    normativeMappings: [
-        {standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A'}
-    ],
-    defaultSeverity: 'minor',
-    category: 'perceivable',
-    type: 'manual',
-    defaultConfidence: 'medium',
-    coverage: {
-        facetsBySc: {
-            '1.1.1': ['text-alternative-quality']
-        }
+  title: '<embed> text alternative must be appropriate (manual review)',
+  description: 'Flags <embed> elements with a detected name for human review of appropriateness.',
+  i18n: {
+    titleKey: 'embed_textAltQuality_title',
+    descriptionKey: 'embed_textAltQuality_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'embed', 'manual', 'atomic'],
+  wcagSc: ['1.1.1'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['text-alternative-quality']
     }
+  }
 };
 
 function runInPage(ctx) {
-    const {document, root, helpers, rule} = ctx;
-    const safeRoot = root || document;
-
-    const trim = (v) => (v == null ? '' : String(v)).trim();
-    const getTextFromIdRefs =
-        helpers && typeof helpers.getTextFromIdRefs === 'function' ? helpers.getTextFromIdRefs : null;
-
-    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-    const queryAll = helpers && typeof helpers.queryAll === 'function'
-        ? helpers.queryAll
-        : (sel) => {
-            try {
-                return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : [];
-            } catch {
-                return [];
-            }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const trim = (v) => (v == null ? '' : String(v)).trim();
+  const getTextFromIdRefs =
+    helpers && typeof helpers.getTextFromIdRefs === 'function' ? helpers.getTextFromIdRefs : null;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
         };
 
-    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-        ? helpers.getEligibilityInfo
-        : null;
-
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-        ? helpers.isAccTreeEligible
-        : null;
-
-    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
-        ? helpers.getFocusableInfo
-        : null;
-
-    function isRolePresentationExcluded(el) {
-        const role = (() => {
-            try {
-                return String(el.getAttribute('role') || '').trim().toLowerCase();
-            } catch {
-                return '';
-            }
-        })();
-        if (role !== 'presentation' && role !== 'none') return false;
-
-        // Exclude only when NOT focusable (mirrors img-alt-present policy)
-        let focusable = false;
-        if (getFocusableInfo) {
-            const fi = (() => {
-                try {
-                    return getFocusableInfo(el, ctx);
-                } catch {
-                    return null;
-                }
-            })();
-            focusable = !!(fi && fi.focusable);
-        } else {
-            const tabindex = el.getAttribute('tabindex');
-            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
-        }
-        return !focusable;
-    }
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
-    const els = (() => {
+  function isRolePresentationExcluded(el) {
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (role !== 'presentation' && role !== 'none') return false;
+
+    // Exclude only when NOT focusable (mirrors img-alt-present policy)
+    let focusable;
+    if (getFocusableInfo) {
+      const fi = (() => {
         try {
-            return Array.from((queryAllSmart ? queryAllSmart('embed') : queryAll('embed')) || []);
+          return getFocusableInfo(el, ctx);
         } catch {
-            return queryAll('embed');
+          return null;
         }
-    })();
-
-    if (!els.length) {
-        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      const tabindex = el.getAttribute('tabindex');
+      focusable =
+        tabindex != null &&
+        String(tabindex).trim() !== '' &&
+        !Number.isNaN(Number(String(tabindex).trim()));
     }
+    return !focusable;
+  }
+
+  const els = (() => {
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('embed') : queryAll('embed')) || []);
+    } catch {
+      return queryAll('embed');
+    }
+  })();
 
-    const occurrences = [];
-    let applicableCount = 0;
-
-    for (const el of els) {
-        if (!el || !el.getAttribute) continue;
-
-        if (isAccTreeEligible) {
-            const elig = (() => {
-                try {
-                    return isAccTreeEligible(el, ctx);
-                } catch {
-                    return {eligible: true, reasons: []};
-                }
-            })();
-            if (elig && elig.eligible === false) continue;
-        }
+  if (!els.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-        if (isRolePresentationExcluded(el)) continue;
+  const occurrences = [];
+  let applicableCount = 0;
 
-        let ariaLabel = '';
-        let ariaLabelledBy = '';
-        let title = '';
+  for (const el of els) {
+    if (!el || !el.getAttribute) continue;
+
+    if (isAccTreeEligible) {
+      const elig = (() => {
         try {
-            ariaLabel = trim(el.getAttribute('aria-label'));
-            ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
-            title = trim(el.getAttribute('title'));
+          return isAccTreeEligible(el, ctx);
         } catch {
-            ariaLabel = '';
-            ariaLabelledBy = '';
-            title = '';
-        }
-
-        // Only resolve IDREF text if aria-labelledby is present and aria-label is not already sufficient
-        let labelledByText = '';
-        let hasLabelledByMechanism = false;
-
-        if (!ariaLabel && ariaLabelledBy) {
-            hasLabelledByMechanism = true;
-
-            if (getTextFromIdRefs) {
-                try {
-                    const t = getTextFromIdRefs(ariaLabelledBy, ctx);
-                    labelledByText = trim(t && t.text);
-                    // If it resolves to empty, still treat as a mechanism present for manual review.
-                } catch {
-                    labelledByText = '';
-                }
-            }
+          return { eligible: true, reasons: [] };
         }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
 
-        const hasNameMechanism = !!(ariaLabel || title || hasLabelledByMechanism);
-        if (!hasNameMechanism) continue;
+    if (isRolePresentationExcluded(el)) continue;
+
+    let ariaLabel;
+    let ariaLabelledBy;
+    let title;
+    try {
+      ariaLabel = trim(el.getAttribute('aria-label'));
+      ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
+      title = trim(el.getAttribute('title'));
+    } catch {
+      ariaLabel = '';
+      ariaLabelledBy = '';
+      title = '';
+    }
 
-        const details = {
-            ariaLabel: ariaLabel || null,
-            ariaLabelledBy: ariaLabelledBy || null,
-            ariaLabelledByText: labelledByText || null,
-            title: title || null
-        };
+    // Only resolve IDREF text if aria-labelledby is present and aria-label is not already sufficient
+    let labelledByText = '';
+    let hasLabelledByMechanism = false;
 
-        applicableCount += 1;
-
-        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, {targetSet: 'acc'}) : null;
-
-        const baseOccurrence = {
-            summary: 'Review text alternative for <embed> for accuracy and appropriateness.',
-            hint: 'Confirm the ARIA name or title accurately identifies the embedded content in context.',
-            i18n: {
-                summaryKey: 'embed_textAltQuality_summary_cantTell',
-                hintKey: 'embed_textAltQuality_hint_cantTell',
-                params: {element: (el.tagName || '').toLowerCase()}
-            },
-            data: {
-                visibilityFilter: eligInfo || {targetSet: 'acc', accEligible: null, reasons: []},
-                details
-            }
-        };
+    if (!ariaLabel && ariaLabelledBy) {
+      hasLabelledByMechanism = true;
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({selector: '', html: '', ...baseOccurrence});
+      if (getTextFromIdRefs) {
+        try {
+          const t = getTextFromIdRefs(ariaLabelledBy, ctx);
+          labelledByText = trim(t && t.text);
+          // If it resolves to empty, still treat as a mechanism present for manual review.
+        } catch {
+          labelledByText = '';
         }
+      }
     }
 
-    if (applicableCount === 0) {
-        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    const hasNameMechanism = !!(ariaLabel || title || hasLabelledByMechanism);
+    if (!hasNameMechanism) continue;
+
+    const details = {
+      ariaLabel: ariaLabel || null,
+      ariaLabelledBy: ariaLabelledBy || null,
+      ariaLabelledByText: labelledByText || null,
+      title: title || null
+    };
+
+    applicableCount += 1;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Review text alternative for <embed> for accuracy and appropriateness.',
+      hint: 'Confirm the ARIA name or title accurately identifies the embedded content in context.',
+      i18n: {
+        summaryKey: 'embed_textAltQuality_summary_cantTell',
+        hintKey: 'embed_textAltQuality_hint_cantTell',
+        params: { element: (el.tagName || '').toLowerCase() }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-    return {ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences};
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
 }
 
-module.exports = {id, meta, runInPage};
+module.exports = { id, meta, runInPage };

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

@@ -42,7 +42,8 @@ const id = 'empty-heading';
 
 const meta = {
   title: 'Headings must not be empty',
-  description: 'Checks that heading elements (<h1>-<h6> or role="heading") have a non-empty accessible name.',
+  description:
+    'Checks that heading elements (<h1>-<h6> or role="heading") have a non-empty accessible name.',
   i18n: {
     titleKey: 'emptyHeading_title',
     descriptionKey: 'emptyHeading_description'
@@ -62,7 +63,9 @@ 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();
   }
 
   function getExplicitRoleToken(el) {
@@ -112,18 +115,16 @@ function runInPage(ctx) {
     return normalizeWs(el.getAttribute && el.getAttribute('title'));
   }
 
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('h1, h2, h3, h4, h5, h6, [role]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('h1, h2, h3, h4, h5, h6, [role]')
+    : helpers.queryAll('h1, h2, h3, h4, h5, h6, [role]');
 
   const occurrences = [];
   let applicableCount = 0;
   const seen = new Set();
 
-  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
   function isEligible(el) {
     if (!isAccTreeEligible) return true;
@@ -148,9 +149,15 @@ function runInPage(ctx) {
     if (name) 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 eligInfo = helpers.getEligibilityInfo
-      ? (() => { try { return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+      ? (() => {
+          try {
+            return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
       : null;
 
     occurrences.push({
@@ -174,7 +181,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/empty-table-header-manual.js

@@ -46,7 +46,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,7 +67,9 @@ 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();
   }
 
   function getVisibleText(el) {
@@ -94,15 +97,13 @@ function runInPage(ctx) {
     return '';
   }
 
-  let nodes = [];
-  try {
-    // 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).
-    nodes = document.querySelectorAll('th:not([role]), [role="columnheader"], [role="rowheader"]');
-  } catch {
-    nodes = [];
-  }
+  // 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).
+  const selector = 'th:not([role]), [role="columnheader"], [role="rowheader"]';
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;
@@ -114,14 +115,15 @@ 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 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',
@@ -155,7 +157,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

@@ -31,7 +31,8 @@ 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 +49,46 @@ 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',
+    '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'
   ]);
 
-  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 +108,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 +137,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: [] };