@surea11y/core 1.2.0 → 1.4.0

package/src/checks/automatic/bypass-blocks-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -27,8 +29,8 @@
  *       mechanism (e.g. a screen reader's "jump by heading" command).
  * @implementation-notes
  * - This rule intentionally checks presence, not position, for the
- *   same-page-anchor condition (b): a widely-used reference engine's real bypass algorithm is
- *   heuristic (see ROADMAP.md's Tier 1a note on why this rule was
+ *   same-page-anchor condition (b): a full bypass algorithm is heuristic
+ *   (see ROADMAP.md's Tier 1a note on why this rule was
  *   deferred from the rest of that batch), and getting DOM-order /
  *   keyboard-focus-order positioning exactly right without introducing
  *   false positives is materially harder than the rest of Tier 1a. Being
@@ -49,7 +51,8 @@ const id = 'bypass-blocks-present';
 
 const meta = {
   title: 'Page must provide a way to bypass repeated blocks',
-  description: 'Checks that the page has at least one recognized WCAG 2.4.1 bypass-blocks mechanism: a main landmark, a working same-page anchor link, or a heading.',
+  description:
+    'Checks that the page has at least one recognized WCAG 2.4.1 bypass-blocks mechanism: a main landmark, a working same-page anchor link, or a heading.',
   i18n: {
     titleKey: 'bypassBlocksPresent_title',
     descriptionKey: 'bypassBlocksPresent_description'
@@ -58,7 +61,13 @@ const meta = {
   tags: ['wcag2a', 'wcag241', 'navigation', 'atomic', 'automatic'],
   wcagSc: ['2.4.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '2.4.1', title: 'Bypass Blocks', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.4.1',
+      title: 'Bypass Blocks',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'operable',
@@ -83,7 +92,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
   function isExposedToAt(el) {
     if (!isAccTreeEligible) return true;
@@ -107,12 +117,12 @@ function runInPage(ctx) {
   }
 
   // Filters through isAccTreeEligible (hidden/aria-hidden/display:none/inert
-  // don't count as "a bypass mechanism is present") -- see page-has-heading-
-  // one-manual.js's identical fix for the real-world trigger (CDC's flu
-  // page, 2026-07-30: its only <h1> sits inside a display:none ancestor,
+  // don't count as "a bypass mechanism is present") -- see
+  // page-has-heading-one-manual.js for the identical real-world trigger
+  // (e.g. a page whose only <h1> sits inside a display:none ancestor,
   // unreachable by sighted and screen reader users alike). A fully
-  // non-rendered <main>/heading was previously credited here too, wrongly
-  // returning `pass` for a page with zero actual bypass mechanisms.
+  // non-rendered <main>/heading must not be credited here, since that would
+  // wrongly return `pass` for a page with zero actual bypass mechanisms.
   function hasMainLandmark() {
     for (const el of queryAll('main, [role="main"]')) {
       if (el && isExposedToAt(el)) return true;
@@ -121,7 +131,7 @@ function runInPage(ctx) {
   }
 
   function hasWorkingAnchorLink() {
-    let links = [];
+    let links;
     try {
       links = document.querySelectorAll('a[href]');
     } catch {
@@ -140,7 +150,7 @@ function runInPage(ctx) {
       fragment = fragment.trim();
       if (!fragment) continue;
 
-      let target = null;
+      let target;
       try {
         target = document.getElementById(fragment);
       } catch {
@@ -167,32 +177,41 @@ function runInPage(ctx) {
 
   const mainLandmark = hasMainLandmark();
   const anchorLink = mainLandmark ? false : hasWorkingAnchorLink();
-  const heading = (mainLandmark || anchorLink) ? false : hasHeading();
+  const heading = mainLandmark || anchorLink ? false : hasHeading();
 
   if (mainLandmark || anchorLink || heading) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
   const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(body) : (body.outerHTML || '').slice(0, 200);
-
-  const occurrences = [{
-    selector: stableSelector,
-    html,
-    summary: 'This page has no recognized way to bypass repeated blocks of content.',
-    hint: 'Add a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content.',
-    i18n: {
-      summaryKey: 'bypassBlocksPresent_summary_fail',
-      hintKey: 'bypassBlocksPresent_hint_fail',
-      params: {}
-    },
-    data: {
-      details: { reasonCode: 'BYPASS_MECHANISM_ABSENT' },
-      visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
+  const html = helpers.getOuterHtmlSnippet
+    ? helpers.getOuterHtmlSnippet(body)
+    : (body.outerHTML || '').slice(0, 200);
+
+  const occurrences = [
+    {
+      selector: stableSelector,
+      html,
+      summary: 'This page has no recognized way to bypass repeated blocks of content.',
+      hint: 'Add a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content.',
+      i18n: {
+        summaryKey: 'bypassBlocksPresent_summary_fail',
+        hintKey: 'bypassBlocksPresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'BYPASS_MECHANISM_ABSENT' },
+        visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
     }
-  }];
-
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  ];
+
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'serious',
+    occurrences
+  };
 }
 
-module.exports = { id, meta, runInPage, applicability };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,7 +20,8 @@ const id = 'canvas-text-alternative-present';
 
 const meta = {
   title: '<canvas> must provide a text alternative',
-  description: 'Checks that <canvas> elements provide a text alternative via fallback content or an accessible name.',
+  description:
+    'Checks that <canvas> elements provide a text alternative via fallback content or an accessible name.',
   i18n: {
     titleKey: 'canvas_textAltPresent_title',
     descriptionKey: 'canvas_textAltPresent_description'
@@ -27,7 +30,13 @@ const meta = {
   tags: ['wcag2a', 'wcag111', 'nontext', 'canvas', 'atomic', 'automatic'],
   wcagSc: ['1.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -44,29 +53,38 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  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 getTextAlternativeInfo = helpers && typeof helpers.getTextAlternativeInfo === 'function'
-    ? helpers.getTextAlternativeInfo
-    : 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 getTextAlternativeInfo =
+    helpers && typeof helpers.getTextAlternativeInfo === 'function'
+      ? helpers.getTextAlternativeInfo
+      : null;
 
   const canvases = (() => {
-    try { return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []); }
-    catch { return queryAll('canvas'); }
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []);
+    } catch {
+      return queryAll('canvas');
+    }
   })();
 
   if (!canvases.length) {
@@ -82,7 +100,11 @@ function runInPage(ctx) {
     // Applicability: eligible in the accessibility tree (with focusable/IDREF exceptions handled by helper).
     if (isAccTreeEligible) {
       const elig = (() => {
-        try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
       })();
       if (elig && elig.eligible === false) continue;
     }
@@ -91,7 +113,13 @@ function runInPage(ctx) {
 
     // Expectation: must provide a text alternative.
     const ti = getTextAlternativeInfo
-      ? (() => { try { return getTextAlternativeInfo(el, ctx); } catch { return null; } })()
+      ? (() => {
+          try {
+            return getTextAlternativeInfo(el, ctx);
+          } catch {
+            return null;
+          }
+        })()
       : null;
 
     const hasTextAlt = !!(ti && ti.present);
@@ -134,7 +162,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'minor',
+    occurrences
+  };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'combobox-name-present';
@@ -10,10 +12,16 @@ const meta = {
     descriptionKey: 'comboboxNamePresent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a','wcag412','forms','atomic','automatic','name','combobox'],
+  tags: ['wcag2a', 'wcag412', 'forms', 'atomic', 'automatic', 'name', 'combobox'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -24,38 +32,22 @@ const meta = {
 
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-      ? helpers.getEligibilityInfo
-      : null;
-
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getAttr(el, name) {
     try {
       if (!el || !el.getAttribute) return '';
       return normalizeWs(el.getAttribute(name));
-    } catch { return ''; }
-  }
-
-  function hasAttr(el, name) {
-    try { return !!(el && el.hasAttribute && el.hasAttribute(name)); } catch { return false; }
-  }
-
-  function isExplicitProgrammatic(el) {
-    // Programmatic name mechanisms we treat as authoritative (presence-only):
-    // - aria-label (non-empty)
-    // - aria-labelledby (non-empty)
-    // - title (non-empty) [weak but allowed for presence]
-    const al = getAttr(el, 'aria-label');
-    if (al) return true;
-    const alb = getAttr(el, 'aria-labelledby');
-    if (alb) return true;
-    const t = getAttr(el, 'title');
-    if (t) return true;
-    return false;
+    } catch {
+      return '';
+    }
   }
 
   function buildLabelForMap(doc) {
@@ -85,7 +77,7 @@ function runInPage(ctx) {
       const info = helpers.getContentNameInfo(container, ctx);
       return info && info.present ? info.value : '';
     }
-    const t = (container && container.textContent) ? String(container.textContent) : '';
+    const t = container && container.textContent ? String(container.textContent) : '';
     return t.replace(/\s+/g, ' ').trim();
   }
 
@@ -132,17 +124,9 @@ function runInPage(ctx) {
     return '';
   }
 
-  function getInputValueName(el) {
-    try {
-      const type = getAttr(el, 'type').toLowerCase();
-      if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
-      const v = getAttr(el, 'value');
-      return v;
-    } catch { return ''; }
-  }
-
   function isEligibleAcc(helpers, el, ctx) {
-    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    const fn =
+      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -153,12 +137,13 @@ function runInPage(ctx) {
     }
   }
 
-
   const occurrences = [];
   let applicableCount = 0;
 
   const selector = '[role="combobox"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   // Precompute label[for] map for combobox elements that are labelable
   // native form controls (e.g. <input role="combobox">).
@@ -231,16 +216,22 @@ function runInPage(ctx) {
     if (res.ok) continue;
 
     const eligInfo = getEligibilityInfo
-        ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
-        : null;
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
     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 || '';
 
     occurrences.push({
       selector: stableSelector,
       html,
       summary: 'This combobox has no accessible name.',
-      hint: 'Provide aria-label or aria-labelledby (preferred), or ensure the element has visible text that is not hidden from assistive technologies.',
+      hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this combobox's accessible name.",
       i18n: {
         summaryKey: 'comboboxNamePresent_summary_fail',
         hintKey: 'comboboxNamePresent_hint_fail',
@@ -253,12 +244,16 @@ function runInPage(ctx) {
     });
   }
 
-
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }