@surea11y/core 1.2.0 → 1.4.0

package/src/checks/automatic/nested-interactive-controls-absent.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,10 +22,9 @@
  *   technology — activating the outer control and the inner one become
  *   ambiguous, and some AT only exposes one of the two.
  * @implementation-notes
- * - Matches a widely-used reference engine's nested-interactive. Reports on the outer
- *   (containing) control, not the nested descendant — this engine
- *   considers the container the fixable unit ("move the nested control
- *   outside this element").
+ * - Reports on the outer (containing) control, not the nested descendant —
+ *   this engine considers the container the fixable unit ("move the nested
+ *   control outside this element").
  * - A container can be reported once even with multiple nested
  *   descendants (listed together); a deeply nested chain (A > B > C, all
  *   interactive) reports both A and B as separate occurrences, since each
@@ -34,7 +35,8 @@ const id = 'nested-interactive-controls-absent';
 
 const meta = {
   title: 'Interactive controls must not be nested',
-  description: 'Checks that an interactive control (link, button, form control, or ARIA widget role) does not contain another interactive control.',
+  description:
+    'Checks that an interactive control (link, button, form control, or ARIA widget role) does not contain another interactive control.',
   i18n: {
     titleKey: 'nestedInteractiveControlsAbsent_title',
     descriptionKey: 'nestedInteractiveControlsAbsent_description'
@@ -43,7 +45,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'structure', 'atomic', 'automatic'],
   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',
@@ -53,7 +61,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
@@ -82,29 +90,55 @@ function runInPage(ctx) {
     '[role="treeitem"]'
   ].join(', ');
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(INTERACTIVE_SELECTOR) : helpers.queryAll(INTERACTIVE_SELECTOR);
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isEligible(node) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(node, ctx);
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(INTERACTIVE_SELECTOR)
+    : helpers.queryAll(INTERACTIVE_SELECTOR);
 
   const occurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el || !el.querySelectorAll) continue;
+    if (!isEligible(el)) continue;
 
     applicableCount += 1;
 
-    let nested = [];
+    // The nested search uses the raw native querySelectorAll (not
+    // helpers.queryAllSmart), so it isn't subject to that helper's
+    // default hidden-content policy at all -- not even hard CSS-based
+    // hiding, let alone aria-hidden. A nested descendant that is never
+    // actually rendered or exposed to AT (display:none, aria-hidden,
+    // etc.) creates no real ambiguity for ANY user, since it isn't there
+    // to be confused with the outer control.
+    let nested;
     try {
-      nested = Array.from(el.querySelectorAll(INTERACTIVE_SELECTOR));
+      nested = Array.from(el.querySelectorAll(INTERACTIVE_SELECTOR)).filter(isEligible);
     } catch {
       nested = [];
     }
     if (!nested.length) continue;
 
     const nestedTags = nested.map((n) => (n && n.tagName ? n.tagName.toLowerCase() : 'unknown'));
+    const dedupedNestedTags = [
+      ...new Set(nested.map((n) => (n && n.tagName ? n.tagName.toLowerCase() : 'unknown')))
+    ];
 
     const tag = el.tagName.toLowerCase();
     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,
@@ -114,10 +148,14 @@ function runInPage(ctx) {
       i18n: {
         summaryKey: 'nestedInteractiveControlsAbsent_summary_fail',
         hintKey: 'nestedInteractiveControlsAbsent_hint_fail',
-        params: { element: tag, nestedElements: nestedTags.join(', ') }
+        params: { element: tag, nestedElements: dedupedNestedTags.join(', ') }
       },
       data: {
-        details: { reasonCode: 'NESTED_INTERACTIVE_CONTROL', element: tag, nestedElements: nestedTags }
+        details: {
+          reasonCode: 'NESTED_INTERACTIVE_CONTROL',
+          element: tag,
+          nestedElements: nestedTags
+        }
       }
     });
   }
@@ -126,9 +164,14 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -22,7 +24,8 @@ const id = 'object-text-alternative-present';
 
 const meta = {
   title: '<object> must provide a text alternative',
-  description: 'Checks that <object> elements provide a text alternative via fallback content or an accessible name.',
+  description:
+    'Checks that <object> elements provide a text alternative via fallback content or an accessible name.',
   i18n: {
     titleKey: 'object_textAltPresent_title',
     descriptionKey: 'object_textAltPresent_description'
@@ -31,7 +34,13 @@ const meta = {
   tags: ['wcag2a', 'wcag111', 'nontext', 'object', '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,33 +53,39 @@ 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 getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
-    ? helpers.getFocusableInfo
-    : null;
-
-  const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
-    ? helpers.getAriaNameInfo
-    : 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;
+
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
   const objects = (() => {
-    try { return Array.from((queryAllSmart ? queryAllSmart('object') : queryAll('object')) || []); }
-    catch { return queryAll('object'); }
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('object') : queryAll('object')) || []);
+    } catch {
+      return queryAll('object');
+    }
   })();
 
   if (!objects.length) {
@@ -88,11 +103,22 @@ function runInPage(ctx) {
     let aria = null;
 
     if (getAriaNameInfo) {
-      aria = (() => { try { return getAriaNameInfo(el, ctx); } catch { return null; } })();
+      aria = (() => {
+        try {
+          return getAriaNameInfo(el, ctx);
+        } catch {
+          return null;
+        }
+      })();
     }
 
     if (aria && aria.present && trim(aria.value)) {
-      return { present: true, value: trim(aria.value), mechanism: aria.mechanism || 'aria', flags: (aria.flags || []).slice(0) };
+      return {
+        present: true,
+        value: trim(aria.value),
+        mechanism: aria.mechanism || 'aria',
+        flags: (aria.flags || []).slice(0)
+      };
     }
 
     const title = trim(el.getAttribute && el.getAttribute('title'));
@@ -123,20 +149,43 @@ function runInPage(ctx) {
     if (!el || !el.getAttribute) continue;
 
     if (isAccTreeEligible) {
-      const elig = (() => { try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; } })();
+      const elig = (() => {
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
       if (elig && elig.eligible === false) continue;
     }
 
     // role presentation/none exclusion only when not focusable
-    const role = (() => { try { return String(el.getAttribute('role') || '').trim().toLowerCase(); } catch { return ''; } })();
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
     if (role === 'presentation' || role === 'none') {
-      let focusable = false;
+      let focusable;
       if (getFocusableInfo) {
-        const fi = (() => { try { return getFocusableInfo(el, ctx); } catch { return null; } })();
+        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()));
+        focusable =
+          tabindex != null &&
+          String(tabindex).trim() !== '' &&
+          !Number.isNaN(Number(String(tabindex).trim()));
       }
       if (!focusable) continue;
     }
@@ -147,18 +196,18 @@ function runInPage(ctx) {
 
     // Only compute fallback text if there is no name.
     // (textContent can be expensive; avoid when not needed)
-    const fb = name.present ? { present: false, value: '', mechanism: 'fallback', flags: ['skipped-name-present'] }
-        : computeFallbackText(el);
+    const fb = name.present
+      ? { present: false, value: '', mechanism: 'fallback', flags: ['skipped-name-present'] }
+      : computeFallbackText(el);
 
     const hasTextAlt = !!(name.present || fb.present);
     if (hasTextAlt) continue;
 
-
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
     const baseOccurrence = {
       summary: 'Missing text alternative for <object>.',
-      hint: 'Provide meaningful fallback content inside <object>, or add an accessible name (aria-label/aria-labelledby).',
+      hint: 'Provide meaningful fallback content inside <object>, add an accessible name (aria-label/aria-labelledby), or use a title attribute as a best-effort fallback.',
       i18n: {
         summaryKey: 'object_textAltPresent_summary_fail',
         hintKey: 'object_textAltPresent_hint_fail',
@@ -187,7 +236,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/option-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'option-name-present';
@@ -10,10 +12,16 @@ const meta = {
     descriptionKey: 'optionNamePresent_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag412", "forms", "atomic", "automatic", "name", "option"],
+  tags: ['wcag2a', 'wcag412', 'forms', 'atomic', 'automatic', 'name', 'option'],
   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,20 +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 ''; }
+    } catch {
+      return '';
+    }
   }
 
   function getConservativeSubtreeText(document, container) {
@@ -52,7 +62,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();
   }
 
@@ -74,7 +84,8 @@ function runInPage(ctx) {
   }
 
   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);
@@ -85,13 +96,13 @@ function runInPage(ctx) {
     }
   }
 
-
   const occurrences = [];
   let applicableCount = 0;
 
-  const selector = "[role=\"option\"]";
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
-
+  const selector = '[role="option"]';
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   function hasName(el) {
     const ariaLabel = getAttr(el, 'aria-label');
@@ -103,11 +114,9 @@ function runInPage(ctx) {
     const title = getAttr(el, 'title');
     if (title) return { ok: true, method: 'title' };
 
-
     const t = getConservativeSubtreeText(document, el);
     if (t) return { ok: true, method: 'content' };
 
-
     return { ok: false, method: 'none' };
   }
 
@@ -121,10 +130,16 @@ 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,
@@ -143,12 +158,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: [] };
 }

package/src/checks/automatic/page-title-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'page-title-present';
@@ -13,7 +15,13 @@ const meta = {
   tags: ['wcag2a', 'wcag242', 'titles', 'atomic', 'navigation', 'automatic'],
   wcagSc: ['2.4.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '2.4.2', title: 'Page Titled', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.4.2',
+      title: 'Page Titled',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'operable',
@@ -54,13 +62,13 @@ function runInPage(ctx) {
       selector: 'head > title',
       html: '',
       summary: missingTitleEl
-          ? 'The page is missing a <title> element.'
-          : 'The page has an empty <title>.',
+        ? 'The page is missing a <title> element.'
+        : 'The page has an empty <title>.',
       hint: 'Provide a descriptive, non-empty <title> that identifies the page topic or purpose.',
       i18n: {
         summaryKey: missingTitleEl
-            ? 'pageTitlePresent_summary_fail_missing'
-            : 'pageTitlePresent_summary_fail_empty',
+          ? 'pageTitlePresent_summary_fail_missing'
+          : 'pageTitlePresent_summary_fail_empty',
         hintKey: 'pageTitlePresent_hint_fail',
         params: {}
       },
@@ -86,7 +94,12 @@ function runInPage(ctx) {
     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: [] };
 }