@surea11y/core 1.0.0

package/src/checks/automatic/iframe-focusable-content.js

@@ -0,0 +1,141 @@
+'use strict';
+
+/**
+ * @check iframe-focusable-content
+ * @atomic true
+ * @summary <iframe>/<frame> elements with tabindex="-1" must not contain focusable content
+ * @standard WCAG 2.2
+ * @sc 2.1.1
+ * @applicability
+ *   Applies to <iframe>/<frame> elements with an explicit negative
+ *   tabindex, whose embedded document is same-origin and reachable via
+ *   contentDocument (cross-origin/unreachable frames assert nothing — see
+ *   implementation notes).
+ * @expectation
+ *   The frame's embedded document contains no focusable element. Browsers
+ *   do not propagate tabindex="-1" on the host <iframe> into its embedded
+ *   document: Tab can still reach focusable content inside, even though
+ *   the frame itself is skipped. An author who set tabindex="-1" intending
+ *   to remove the frame from the tab order has not actually done so if the
+ *   embedded document contains focusable content.
+ * @implementation-notes
+ * - Deliberately scoped to same-origin, currently-accessible content only
+ *   (contentDocument access is wrapped in try/catch and treated as "no
+ *   constraint asserted" — not counted as applicable — when unreachable),
+ *   matching this engine's established scope-limiting rationale (see
+ *   src/core/aria-helpers.js file header) rather than guessing at
+ *   cross-origin content.
+ * - Focusability inside the embedded document is checked with a small,
+ *   self-contained heuristic (native interactive tags + non-negative
+ *   tabindex) rather than ctx.helpers.getFocusableInfo, since that helper
+ *   is built for the outer document's realm/caches, not an embedded
+ *   document that may be a distinct realm.
+ */
+
+const id = 'iframe-focusable-content';
+
+const meta = {
+  title: 'Frames with tabindex="-1" must not contain focusable content',
+  description: 'Checks that same-origin <iframe>/<frame> elements with tabindex="-1" do not contain focusable content, since browsers do not propagate that restriction into the frame’s embedded document.',
+  i18n: {
+    titleKey: 'iframeFocusableContent_title',
+    descriptionKey: 'iframeFocusableContent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag211', 'structure', 'atomic', 'automatic', 'keyboard', 'iframe'],
+  wcagSc: ['2.1.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.1.1', title: 'Keyboard', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'operable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '2.1.1': ['iframe-tabindex-negative-content-not-focusable'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function hasFocusableCandidate(doc) {
+    if (!doc || !doc.querySelectorAll) return false;
+    let els = [];
+    try {
+      els = doc.querySelectorAll(
+        'a[href], area[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), ' +
+        'select:not([disabled]), textarea:not([disabled]), iframe, [contenteditable="true"], [tabindex]'
+      );
+    } catch {
+      return false;
+    }
+    for (const el of els) {
+      if (!el || !el.getAttribute) continue;
+      const raw = el.getAttribute('tabindex');
+      if (raw != null) {
+        const n = Number(String(raw).trim());
+        if (!Number.isNaN(n) && n < 0) continue; // explicitly removed from tab order
+      }
+      return true;
+    }
+    return false;
+  }
+
+  function getNegativeTabIndex(el) {
+    const raw = el.getAttribute('tabindex');
+    if (raw == null) return false;
+    const n = Number(String(raw).trim());
+    return !Number.isNaN(n) && n < 0;
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame', safeRoot) : helpers.queryAll('iframe, frame', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    if (!getNegativeTabIndex(el)) continue;
+
+    let contentDoc = null;
+    try {
+      contentDoc = el.contentDocument || null;
+    } catch {
+      contentDoc = null;
+    }
+    if (!contentDoc || !contentDoc.querySelectorAll) continue; // cross-origin/unreachable: no constraint asserted
+
+    applicableCount += 1;
+
+    if (!hasFocusableCandidate(contentDoc)) continue;
+
+    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 frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
+      hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
+      i18n: {
+        summaryKey: 'iframeFocusableContent_summary_fail',
+        hintKey: 'iframeFocusableContent_hint_fail',
+        params: { element: tag }
+      },
+      data: {
+        details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    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 };

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

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * @check iframe-name-present
+ * @atomic true
+ * @summary <iframe>/<frame> elements must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <iframe>/<frame> elements that are eligible for the
+ *   accessibility tree (isAccTreeEligible).
+ * @expectation
+ *   The element has a non-empty accessible name via aria-labelledby,
+ *   aria-label, or the title attribute. Unlike most interactive elements,
+ *   an iframe's name is never derived from its rendered content (the
+ *   embedded document is a separate browsing context) — this mirrors
+ *   dialog-name-present's "name-from-author-only" reasoning.
+ * @implementation-notes
+ * - Uses helpers.getAccessibleNameInfo, which already stops at
+ *   aria-label/aria-labelledby/label[for]/title without falling back to
+ *   subtree text content — the right shape for this element.
+ */
+
+const id = 'iframe-name-present';
+
+const meta = {
+  title: 'Frames have an accessible name',
+  description: 'Checks that <iframe>/<frame> elements expose a non-empty accessible name via aria-label, aria-labelledby, or the title attribute.',
+  i18n: {
+    titleKey: 'iframeNamePresent_title',
+    descriptionKey: 'iframeNamePresent_description'
+  },
+  helpUrl: null,
+  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' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['iframe-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame', safeRoot) : helpers.queryAll('iframe, frame', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.tagName) continue;
+
+    if (helpers.isAccTreeEligible) {
+      const elig = helpers.isAccTreeEligible(el);
+      const isEligible = typeof elig === 'boolean' ? elig : !!(elig && elig.eligible);
+      if (!isEligible) continue;
+    }
+
+    applicableCount += 1;
+
+    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 }) : null;
+    if (nameInfo && nameInfo.present && nameInfo.value) continue;
+
+    const eligInfo = helpers.getEligibilityInfo
+      ? (() => { try { return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+      : null;
+    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 frame has no accessible name.',
+      hint: 'Add a title attribute (or aria-label/aria-labelledby) describing the frame’s content or purpose.',
+      i18n: {
+        summaryKey: 'iframeNamePresent_summary_fail',
+        hintKey: 'iframeNamePresent_hint_fail',
+        params: { element: tag }
+      },
+      data: {
+        details: { reasonCode: 'IFRAME_NAME_MISSING', element: tag },
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    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: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * @check iframe-title-unique
+ * @atomic true
+ * @summary <iframe>/<frame> title attributes must be unique among frames
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <iframe>/<frame> elements that carry a non-empty title
+ *   attribute.
+ * @expectation
+ *   No two frames in scope share the same (trimmed, case-sensitive) title
+ *   attribute value — a duplicate title prevents assistive technology
+ *   users from telling frames apart when scanning by name.
+ * @implementation-notes
+ * - Distinct, atomic decision from iframe-name-present (presence):
+ *   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.
+ * - Not gated on isAccTreeEligible: a duplicate title is a static markup
+ *   property independent of the frame's current visibility.
+ */
+
+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.',
+  i18n: {
+    titleKey: 'iframeTitleUnique_title',
+    descriptionKey: 'iframeTitleUnique_description'
+  },
+  helpUrl: null,
+  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' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['iframe-title-unique'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame', safeRoot) : helpers.queryAll('iframe, frame', safeRoot);
+
+  const groups = new Map(); // trimmed title -> elements[]
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const title = String(el.getAttribute('title') || '').trim();
+    if (!title) continue;
+
+    applicableCount += 1;
+
+    const list = groups.get(title);
+    if (list) list.push(el);
+    else groups.set(title, [el]);
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const [title, els] of groups) {
+    if (els.length < 2) continue;
+
+    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 || '');
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This frame’s title is not unique among the frames on this page.',
+        hint: 'Give each frame a distinct title describing its specific content or purpose.',
+        i18n: {
+          summaryKey: 'iframeTitleUnique_summary_fail',
+          hintKey: 'iframeTitleUnique_hint_fail',
+          params: { element: tag, title }
+        },
+        data: {
+          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: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * @check img-alt-present
+ * @atomic true
+ * @summary Accessible <img> elements must have an alt attribute
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <img> elements that are exposed to assistive technologies.
+ *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
+ *   Elements otherwise hidden from the accessibility tree remain applicable
+ *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ * @expectation
+ *   Each applicable <img> element has an alt attribute.
+ *   The alt attribute may be empty (alt="").
+ */
+
+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.',
+  i18n: {
+    titleKey: 'img_altPresent_title',
+    descriptionKey: 'img_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': ['img-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 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;
+
+  // Prefer tagName collection when available (cheap), otherwise fall back.
+  function getImgsCollection() {
+    try {
+      if (queryAllSmart) {
+        const r = queryAllSmart('img');
+        return Array.isArray(r) ? r : Array.from(r || []);
+      }
+    } catch {
+      // fall through
+    }
+
+    try {
+      if (safeRoot && typeof safeRoot.getElementsByTagName === 'function') {
+        return safeRoot.getElementsByTagName('img'); // HTMLCollection (live)
+      }
+    } catch {
+      // fall through
+    }
+
+    try {
+      if (safeRoot && typeof safeRoot.querySelectorAll === 'function') return safeRoot.querySelectorAll('img');
+    } catch {
+      // fall through
+    }
+
+    return [];
+  }
+
+  const imgs = getImgsCollection();
+  const imgLen = imgs && typeof imgs.length === 'number' ? imgs.length : 0;
+
+  if (!imgLen) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  // 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;
+
+    // Eligibility: only imgs exposed to assistive tech (with focusable/IDREF exceptions handled by helper)
+    if (isAccTreeEligible) {
+      let elig;
+      try {
+        elig = isAccTreeEligible(el, ctx);
+      } catch {
+        elig = null;
+      }
+      if (elig && elig.eligible === false) continue;
+      // If helper returns boolean, treat false as ineligible.
+      if (typeof elig === 'boolean' && elig === false) continue;
+    }
+
+    // Role (presentation/none) exclusion only when NOT focusable.
+    let role = '';
+    try {
+      role = trim(el.getAttribute('role')).toLowerCase();
+    } catch {
+      role = '';
+    }
+
+    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);
+      }
+
+      if (!focusable) continue;
+    }
+
+    // From here: applicable
+    applicableCount += 1;
+
+    // alt attribute presence check (empty allowed)
+    let hasAlt = false;
+    try {
+      hasAlt = el.getAttribute('alt') !== null;
+    } catch {
+      hasAlt = false;
+    }
+    if (hasAlt) continue;
+
+    // aria-label / aria-labelledby is also a valid, standards-recognized
+    // text-alternative mechanism for <img> (HTML-AAM accessible name
+    // computation includes ARIA naming before falling back to alt); an
+    // 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;
+      try {
+        ariaName = getAriaNameInfo(el, ctx);
+      } catch {
+        ariaName = null;
+      }
+      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.
+    const title = trim(el.getAttribute('title'));
+    if (title) continue;
+
+    const eligInfo = getEligibilityInfo ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })() : null;
+
+    const baseOccurrence = {
+      summary: 'Missing alt attribute on <img>.',
+      hint: 'Add an alt attribute (use alt="" only for decorative images).',
+      i18n: {
+        summaryKey: 'img_altPresent_summary_fail',
+        hintKey: 'img_altPresent_hint_fail',
+        params: {}
+      },
+      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 });
+    }
+  }
+
+  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 };