@surea11y/core 1.2.0 → 1.4.0

package/src/checks/automatic/iframe-title-unique.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,7 +20,7 @@
  *   a frame can have a non-empty title while still failing uniqueness.
  * - Compares the title ATTRIBUTE specifically, not the full computed
  *   accessible name (aria-label could legitimately differ in wording even
- *   when title happens to collide) — matches a widely-used reference engine's frame-title-unique.
+ *   when title happens to collide).
  * - Not rule-gated on isAccTreeEligible: duplicate titles are a static
  *   markup property. Engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
@@ -28,7 +30,8 @@ const id = 'iframe-title-unique';
 
 const meta = {
   title: 'Frame titles must be unique',
-  description: 'Checks that no two <iframe>/<frame> elements in scope share the same title attribute value.',
+  description:
+    'Checks that no two <iframe>/<frame> elements in scope share the same title attribute value.',
   i18n: {
     titleKey: 'iframeTitleUnique_title',
     descriptionKey: 'iframeTitleUnique_description'
@@ -37,7 +40,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'structure', 'atomic', 'automatic', 'name', 'iframe'],
   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: 'moderate',
   category: 'robust',
@@ -47,9 +56,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame') : helpers.queryAll('iframe, frame');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('iframe, frame')
+    : helpers.queryAll('iframe, frame');
 
   const groups = new Map(); // trimmed title -> elements[]
   let applicableCount = 0;
@@ -79,7 +90,9 @@ function runInPage(ctx) {
     for (const el of els) {
       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,
@@ -92,16 +105,26 @@ function runInPage(ctx) {
           params: { element: tag, title }
         },
         data: {
-          details: { reasonCode: 'IFRAME_TITLE_DUPLICATE', element: tag, title, duplicateCount: els.length }
+          details: {
+            reasonCode: 'IFRAME_TITLE_DUPLICATE',
+            element: tag,
+            title,
+            duplicateCount: els.length
+          }
         }
       });
     }
   }
 
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/img-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,7 +22,8 @@ const id = 'img-alt-present';
 
 const meta = {
   title: '<img> must have an alt attribute',
-  description: 'Checks that <img> elements provide an alt attribute to support a text alternative mechanism.',
+  description:
+    'Checks that <img> elements provide an alt attribute to support a text alternative mechanism.',
   i18n: {
     titleKey: 'img_altPresent_title',
     descriptionKey: 'img_altPresent_description'
@@ -29,7 +32,13 @@ const meta = {
   tags: ['wcag2a', 'wcag111', 'nontext', 'images', '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',
@@ -46,12 +55,17 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  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 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;
 
   // Prefer tagName collection when available (cheap), otherwise fall back.
   function getImgsCollection() {
@@ -73,7 +87,8 @@ function runInPage(ctx) {
     }
 
     try {
-      if (safeRoot && typeof safeRoot.querySelectorAll === 'function') return safeRoot.querySelectorAll('img');
+      if (safeRoot && typeof safeRoot.querySelectorAll === 'function')
+        return safeRoot.querySelectorAll('img');
     } catch {
       // fall through
     }
@@ -94,19 +109,6 @@ function runInPage(ctx) {
   // Helper-safe trim
   const trim = (v) => (v == null ? '' : String(v)).trim();
 
-  // Deterministic tabindex fallback (only used if helper missing)
-  function isFocusableFallback(el) {
-    try {
-      const tabindex = el.getAttribute('tabindex');
-      if (tabindex == null) return false;
-      const s = String(tabindex).trim();
-      if (!s) return false;
-      return !Number.isNaN(Number(s));
-    } catch {
-      return false;
-    }
-  }
-
   for (let i = 0; i < imgLen; i++) {
     const el = imgs[i];
     if (!el || !el.getAttribute) continue;
@@ -125,7 +127,7 @@ function runInPage(ctx) {
     }
 
     // Role (presentation/none) exclusion only when NOT focusable.
-    let role = '';
+    let role;
     try {
       role = trim(el.getAttribute('role')).toLowerCase();
     } catch {
@@ -133,17 +135,13 @@ function runInPage(ctx) {
     }
 
     if (role === 'presentation' || role === 'none') {
-      let focusable = false;
-      if (getFocusableInfo) {
-        try {
-          const fi = getFocusableInfo(el, ctx);
-          // Preserve existing behavior: prefer fi.focusable; fall back to fi.tabbable if present.
-          focusable = !!(fi && (fi.focusable || fi.tabbable));
-        } catch {
-          focusable = false;
-        }
-      } else {
-        focusable = isFocusableFallback(el);
+      let focusable;
+      try {
+        const fi = getFocusableInfo(el, ctx);
+        // Preserve existing behavior: prefer fi.focusable; fall back to fi.tabbable if present.
+        focusable = !!(fi && (fi.focusable || fi.tabbable));
+      } catch {
+        focusable = false;
       }
 
       if (!focusable) continue;
@@ -153,7 +151,7 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     // alt attribute presence check (empty allowed)
-    let hasAlt = false;
+    let hasAlt;
     try {
       hasAlt = el.getAttribute('alt') !== null;
     } catch {
@@ -167,7 +165,7 @@ function runInPage(ctx) {
     // image with a non-empty ARIA name is not missing a text alternative
     // just because it lacks an alt attribute.
     if (getAriaNameInfo) {
-      let ariaName = null;
+      let ariaName;
       try {
         ariaName = getAriaNameInfo(el, ctx);
       } catch {
@@ -176,19 +174,23 @@ function runInPage(ctx) {
       if (ariaName && ariaName.present) continue;
     }
 
-    // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source for <img> once alt is entirely absent (not merely alt="",
-    // which explicitly marks decorative and stays excluded from this
-    // branch since hasAlt already short-circuited above) -- confirmed
-    // against a widely-used reference engine's own image-alt rule, which lists a non-empty
-    // title as one of its "any" satisfying conditions alongside has-alt/
-    // aria-label/aria-labelledby. Found via a real page (AliExpress's
-    // logo, 2026-07-23): <img src="..." title="...">, no alt attribute
-    // at all -- a real false positive, not a missing text alternative.
+    // A non-empty title attribute is HTML-AAM's next fallback naming source
+    // for <img> once alt is entirely absent (not merely alt="", which
+    // explicitly marks decorative and stays excluded from this branch since
+    // hasAlt already short-circuited above). An `<img src="..." title="...">`
+    // with no alt attribute at all is not missing a text alternative.
     const title = trim(el.getAttribute('title'));
     if (title) continue;
 
-    const eligInfo = getEligibilityInfo ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })() : null;
+    const eligInfo = getEligibilityInfo
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
 
     const baseOccurrence = {
       summary: 'Missing alt attribute on <img>.',
@@ -201,12 +203,7 @@ function runInPage(ctx) {
       data: { visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] } }
     };
 
-    if (helpers && typeof helpers.reportOccurrence === 'function') {
-      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-    } else {
-      // Never compute selector/snippet in the rule.
-      occurrences.push({ __node: el, selector: '', html: '', ...baseOccurrence });
-    }
+    occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
   }
 
   if (applicableCount === 0) {
@@ -217,7 +214,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/input-image-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,138 +20,165 @@
 const id = 'input-image-alt-present';
 
 const meta = {
-    title: '<input type="image"> must have an alt attribute',
-    description:
-        'Checks that <input type="image"> elements provide an alt attribute to support a text alternative mechanism.',
-    i18n: {
-        titleKey: 'inputImage_altPresent_title',
-        descriptionKey: 'inputImage_altPresent_description'
-    },
-    helpUrl: null,
-    tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'atomic', 'automatic'],
-    wcagSc: ['1.1.1'],
-    normativeMappings: [
-        { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
-    ],
-    defaultSeverity: 'serious',
-    category: 'perceivable',
-    type: 'automatic',
-    defaultConfidence: 'high',
-    coverage: {
-        facetsBySc: {
-            '1.1.1': ['input-image-alt-attr-present']
-        }
+  title: '<input type="image"> must have an alt attribute',
+  description:
+    'Checks that <input type="image"> elements provide an alt attribute to support a text alternative mechanism.',
+  i18n: {
+    titleKey: 'inputImage_altPresent_title',
+    descriptionKey: 'inputImage_altPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'atomic', 'automatic'],
+  wcagSc: ['1.1.1'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['input-image-alt-attr-present']
     }
+  }
 };
 
 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 { 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 getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-        ? helpers.isAccTreeEligible
-        : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
-    const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
-        ? helpers.getAriaNameInfo
-        : null;
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
-    const inputs = (() => {
-        try { return Array.from((queryAllSmart ? queryAllSmart('input[type="image"]') : queryAll('input[type="image"]')) || []); }
-        catch { return queryAll('input[type="image"]'); }
-    })();
-
-    if (!inputs.length) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  const inputs = (() => {
+    try {
+      return Array.from(
+        (queryAllSmart ? queryAllSmart('input[type="image"]') : queryAll('input[type="image"]')) ||
+          []
+      );
+    } catch {
+      return queryAll('input[type="image"]');
     }
+  })();
 
-    const occurrences = [];
-    let applicableCount = 0;
-
-    for (const el of inputs) {
-        if (!el || !el.getAttribute) continue;
+  if (!inputs.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-        // Applicability: eligible in the acc tree (with helper exceptions).
-        if (isAccTreeEligible) {
-            const elig = (() => {
-                try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
-            })();
-            if (elig && elig.eligible === false) continue;
-        }
-
-        applicableCount += 1;
-
-        const hasAlt = el.getAttribute('alt') !== null;
-        if (hasAlt) continue;
-
-        // aria-label / aria-labelledby is also a valid, standards-recognized
-        // text-alternative mechanism for <input type="image"> (HTML-AAM
-        // accessible name computation includes ARIA naming before falling
-        // back to alt).
-        if (getAriaNameInfo) {
-            let ariaName = null;
-            try {
-                ariaName = getAriaNameInfo(el, ctx);
-            } catch {
-                ariaName = null;
-            }
-            if (ariaName && ariaName.present) continue;
-        }
+  const occurrences = [];
+  let applicableCount = 0;
 
-        // A non-empty title attribute is HTML-AAM's own next fallback naming
-        // source once alt is entirely absent -- also accepted by a widely-used
-        // reference engine's equivalent input-image-alt rule (non-empty-title, same "any" list
-        // as non-empty-alt/aria-label/aria-labelledby). See img-alt-present's
-        // sibling fix (2026-07-23, AliExpress's title-only logo <img>) for
-        // the real page this was found via -- same gap, same fix, different
-        // element.
-        const titleRaw = (() => { try { return el.getAttribute('title'); } catch { return null; } })();
-        if (titleRaw !== null && String(titleRaw).trim()) continue;
-
-        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
-
-        const baseOccurrence = {
-            summary: 'Missing alt attribute on <input type="image">.',
-            hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
-            i18n: {
-                summaryKey: 'inputImage_altPresent_summary_fail',
-                hintKey: 'inputImage_altPresent_hint_fail',
-                params: { element: 'input[type=image]' }
-            },
-            data: {
-                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-            }
-        };
+  for (const el of inputs) {
+    if (!el || !el.getAttribute) continue;
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            // Never compute selector/snippet in the rule.
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
+    // Applicability: eligible in the acc tree (with helper exceptions).
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
         }
+      })();
+      if (elig && elig.eligible === false) continue;
     }
 
-    if (applicableCount === 0) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    applicableCount += 1;
+
+    const hasAlt = el.getAttribute('alt') !== null;
+    if (hasAlt) continue;
+
+    // aria-label / aria-labelledby is also a valid, standards-recognized
+    // text-alternative mechanism for <input type="image"> (HTML-AAM
+    // accessible name computation includes ARIA naming before falling
+    // back to alt).
+    if (getAriaNameInfo) {
+      let ariaName;
+      try {
+        ariaName = getAriaNameInfo(el, ctx);
+      } catch {
+        ariaName = null;
+      }
+      if (ariaName && ariaName.present) continue;
     }
 
-    if (!occurrences.length) {
-        return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+    // A non-empty title attribute is HTML-AAM's own next fallback naming
+    // source once alt is entirely absent. Same gap img-alt-present handles
+    // for <img title="..."> with no alt.
+    const titleRaw = (() => {
+      try {
+        return el.getAttribute('title');
+      } catch {
+        return null;
+      }
+    })();
+    if (titleRaw !== null && String(titleRaw).trim()) continue;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Missing alt attribute on <input type="image">.',
+      hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
+      i18n: {
+        summaryKey: 'inputImage_altPresent_summary_fail',
+        hintKey: 'inputImage_altPresent_hint_fail',
+        params: { element: 'input[type=image]' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      // Never compute selector/snippet in the rule.
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
-
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'minor',
+    occurrences
+  };
 }
 
 module.exports = { id, meta, runInPage };