@surea11y/core 1.0.0

package/src/checks/automatic/input-image-alt-present.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * @check inputImage-alt-present
+ * @atomic true
+ * @summary Accessible <input type="image"> elements must have an alt attribute
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <input type="image"> elements that are exposed to assistive technologies.
+ *   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 <input type="image"> element has an alt attribute.
+ *   The alt attribute may be empty (alt="").
+ */
+
+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']
+        }
+    }
+};
+
+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 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 occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of inputs) {
+        if (!el || !el.getAttribute) continue;
+
+        // 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;
+        }
+
+        // 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: [] }
+            }
+        };
+
+        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 });
+        }
+    }
+
+    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 };

package/src/checks/automatic/label-in-name.js

@@ -0,0 +1,326 @@
+'use strict';
+
+const id = 'label-in-name';
+
+const meta = {
+  title: 'Label in Name: accessible name contains visible text',
+  description:
+      'Checks that when a control has a visible text label, the accessible name (from aria-label/aria-labelledby) contains that visible label text (WCAG 2.5.3).',
+  i18n: {
+    titleKey: 'labelInName_title',
+    descriptionKey: 'labelInName_description'
+  },
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html',
+  tags: ['wcag21a', 'wcag253', 'forms', 'atomic', 'automatic'],
+  wcagSc: ['2.5.3'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.5.3',
+      title: 'Label in Name',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'operable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '2.5.3': ['label-in-name'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  // Applicability: focus/activation controls with explicit ARIA naming.
+  // NOTE: aria-hidden is intentionally NOT excluded here; it does not affect visual rendering.
+  const selector = ':is(button, a[href], summary, input:not([type="hidden"]), textarea, select, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="searchbox"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="treeitem"], [role="gridcell"]):not([hidden]):not([disabled]):not([aria-disabled="true"]):is([aria-label], [aria-labelledby])';
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  function norm(s) {
+    const v = (s == null ? '' : String(s));
+    // deterministic normalization: trim + collapse whitespace + case-fold
+    return v.replace(/\s+/g, ' ').trim().toLowerCase();
+  }
+
+  function getElementDescriptor(el) {
+    const tag = (el && el.tagName ? String(el.tagName).toLowerCase() : 'element');
+    let role = '';
+    try { role = el && el.getAttribute ? (el.getAttribute('role') || '') : ''; } catch { role = ''; }
+    const r = String(role || '').trim();
+    return r ? `${tag}[role="${r}"]` : tag;
+  }
+
+  function clipForSummary(s) {
+    const v = (s == null ? '' : String(s)).replace(/\s+/g, ' ').trim();
+    if (v.length <= 80) return v;
+    return v.slice(0, 77) + '...';
+  }
+
+  function isNonRenderedTag(el) {
+    const tn = (el && el.tagName ? String(el.tagName).toLowerCase() : '');
+    return tn === 'script' || tn === 'style' || tn === 'template' || tn === 'noscript' || tn === 'meta' || tn === 'link';
+  }
+
+  function isDomVisible(el) {
+    if (!el) return false;
+    if (helpers.isDomVisibleEligible) return !!helpers.isDomVisibleEligible(el, ctx, { targetSet: 'dom' }).eligible;
+    if (helpers.getEligibilityInfo) return !!helpers.getEligibilityInfo(el, ctx, { targetSet: 'dom' }).eligible;
+    return true;
+  }
+
+  // Unlike isDomVisible above, this also excludes aria-hidden subtrees.
+  // Needed specifically for collectVisibleTextUnder's per-text-node check
+  // below: an aria-hidden icon-font glyph (e.g. Material Icons' ligature
+  // pattern, <mat-icon aria-hidden="true">format_color_fill</mat-icon>) is
+  // technically DOM-visible pixels, but is never perceived by a sighted or
+  // voice-control user as literal readable words the way real visible text
+  // is — a widely-used reference engine's own label-content-name-mismatch check reaches the same
+  // practical outcome via a canvas-based ligature-detection heuristic
+  // (measuring rendered glyph shapes), not replicable here since this rule
+  // runs against static markup with no real canvas/font rendering
+  // available; excluding aria-hidden content is a cheaper, static-markup
+  // signal that gets the common case (decorative icon fonts) right without
+  // needing one. Confirmed via a live-DOM cross-engine run 2026-07-21
+  // (Angular Material's theme-picker button, aria-label="Select a theme",
+  // aria-hidden icon rendering literally as "format_color_fill").
+  function isAccEligible(el) {
+    if (!el) return false;
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return isDomVisible(el);
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return isDomVisible(el);
+    }
+  }
+
+  // DOM's NodeFilter.SHOW_TEXT constant, inlined as a numeric literal rather
+  // than referencing the global NodeFilter object directly: runInPage must
+  // have zero free vars (see docs/RULE_AUTHORING.md's free-var footgun) and
+  // NodeFilter is not itself present in the execution realm this function
+  // actually runs in, unlike window/document. Confirmed 2026-07-21 — this
+  // silently made createTreeWalker throw on every call, falling back to
+  // raw container.textContent (which respects none of isNonRenderedTag/
+  // isDomVisible/isAccEligible below, since that whole per-node loop is
+  // skipped in the fallback path). Same pattern already used correctly in
+  // region-manual.js's own createTreeWalker call.
+  const SHOW_TEXT = 4;
+
+  function collectVisibleTextUnder(container) {
+    if (!container) return '';
+    if (!isDomVisible(container)) return '';
+
+    // TreeWalker is deterministic in document order.
+    let walker = null;
+    try {
+      walker = document.createTreeWalker(container, SHOW_TEXT, null);
+    } catch {
+      walker = null;
+    }
+    if (!walker) {
+      try {
+        const t = container.textContent;
+        return t == null ? '' : String(t);
+      } catch {
+        return '';
+      }
+    }
+
+    const parts = [];
+    let n = null;
+    // eslint-disable-next-line no-cond-assign
+    while ((n = walker.nextNode())) {
+      try {
+        const raw = n && n.nodeValue != null ? String(n.nodeValue) : '';
+        const t = raw.replace(/\s+/g, ' ').trim();
+        if (!t) continue;
+
+        const p = n.parentElement || null;
+        if (!p || !p.tagName) continue;
+        if (isNonRenderedTag(p)) continue;
+
+        // Require the parent element to be visually eligible AND not inside
+        // an aria-hidden subtree (see isAccEligible's docblock above).
+        if (!isAccEligible(p)) continue;
+
+        parts.push(t);
+      } catch {
+        // no-throws
+      }
+    }
+    return parts.join(' ').replace(/\s+/g, ' ').trim();
+  }
+
+  function getAssociatedLabelElements(control) {
+    const labels = [];
+    try {
+      if (control && control.labels && typeof control.labels.length === 'number') {
+        for (const l of control.labels) labels.push(l);
+      }
+    } catch {
+      // ignore
+    }
+
+    // Fallback: wrapped label
+    try {
+      const w = control && control.closest ? control.closest('label') : null;
+      if (w) labels.push(w);
+    } catch {
+      // ignore
+    }
+
+    // Fallback: label[for=id]. Uses `document` directly rather than
+    // ctx.root/safeRoot -- label[for] association is a document-wide
+    // relationship (IDs are document-unique), not bounded by whatever
+    // contextSelector region happens to be scanned, and ctx.root is an
+    // array (multi-region contextSelector support), not a single element
+    // with its own .querySelector to call directly.
+    try {
+      const idAttribute = control && control.getAttribute ? (control.getAttribute('id') || '') : '';
+      const key = String(idAttribute || '').trim();
+      if (key && document && document.querySelector) {
+        const l = document.querySelector('label[for="' + CSS.escape(key) + '"]');
+        if (l) labels.push(l);
+      }
+    } catch {
+      // ignore
+    }
+
+    // De-dupe in document order
+    const seen = new Set();
+    const out = [];
+    for (const l of labels) {
+      try {
+        if (!l || !l.tagName) continue;
+        if (seen.has(l)) continue;
+        seen.add(l);
+        out.push(l);
+      } catch {
+        // ignore
+      }
+    }
+    return out;
+  }
+
+  function getVisibleTextLabelInfo(el) {
+    // Returns { text, source } where source helps reporting.
+    // Source policy (deterministic):
+    // 1) <label> association for form controls
+    // 2) visible text inside the element
+    // 3) visible text from aria-labelledby referenced elements
+    let text = '';
+    let source = 'none';
+
+    const tn = (el && el.tagName ? String(el.tagName).toLowerCase() : '');
+
+    // 1) Label association (native form controls)
+    const isFormControl = tn === 'input' || tn === 'select' || tn === 'textarea';
+    if (isFormControl) {
+      const labels = getAssociatedLabelElements(el);
+      const labelParts = [];
+      for (const l of labels) {
+        if (!l || !isDomVisible(l)) continue;
+        const t = collectVisibleTextUnder(l);
+        if (t) labelParts.push(t);
+      }
+      const joined = labelParts.join(' ').replace(/\s+/g, ' ').trim();
+      if (joined) return { text: joined, source: 'label' };
+    }
+
+    // 2) Text inside the control itself
+    text = collectVisibleTextUnder(el);
+    if (text) return { text, source: 'self' };
+
+    // 3) aria-labelledby referenced visible text (only if refs exist and are visible)
+    try {
+      const idrefs = el && el.getAttribute ? el.getAttribute('aria-labelledby') : null;
+      if (idrefs && helpers.resolveIdRefs) {
+        const r = helpers.resolveIdRefs(idrefs, ctx, { maxRefs: 8 });
+        const parts = [];
+        for (const ref of (r && Array.isArray(r.refs) ? r.refs : [])) {
+          if (!ref || !ref.tagName) continue;
+          if (!isDomVisible(ref)) continue;
+          const t = collectVisibleTextUnder(ref);
+          if (t) parts.push(t);
+        }
+        const joined = parts.join(' ').replace(/\s+/g, ' ').trim();
+        if (joined) return { text: joined, source: 'aria-labelledby' };
+      }
+    } catch {
+      // ignore
+    }
+
+    return { text: '', source };
+  }
+
+  for (const el of nodes) {
+    // Gate: control must be visually rendered (SC is about visual labels).
+    if (!isDomVisible(el)) continue;
+
+    const labelInfo = getVisibleTextLabelInfo(el);
+    const visibleLabel = labelInfo && labelInfo.text ? String(labelInfo.text) : '';
+    const visibleNorm = norm(visibleLabel);
+
+    // Applicability: only when we can deterministically extract visible label text.
+    if (!visibleNorm) continue;
+
+    applicableCount += 1;
+
+    let acc = { present: false, value: '', mechanism: 'none', flags: [] };
+    try {
+      acc = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 }) : acc;
+    } catch {
+      acc = { present: false, value: '', mechanism: 'none', flags: ['exception'] };
+    }
+    const accName = acc && acc.value != null ? String(acc.value) : '';
+    const accNorm = norm(accName);
+
+    const contains = !!(accNorm && visibleNorm && accNorm.indexOf(visibleNorm) !== -1);
+
+    if (!contains) {
+      const selectorOut = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+      occurrences.push({
+        selector: selectorOut,
+        html,
+        summary: 'Accessible name does not contain the visible label text.',
+        hint: 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
+        i18n: {
+          summaryKey: 'labelInName_summary_fail',
+          hintKey: 'labelInName_hint_fail',
+          params: {
+            element: getElementDescriptor(el),
+            visibleLabel: clipForSummary(visibleLabel),
+            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+          }
+        },
+        data: {
+          details: {
+            reasonCode: 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+            visibleLabel,
+            accessibleName: accName,
+            normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
+            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+          }
+        }
+      });
+    }
+  }
+
+  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: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * @check html-lang-attr-present
+ * @atomic true
+ * @summary The default language of the page must be programmatically declared
+ * @standard WCAG 2.2
+ * @sc 3.1.1
+ *
+ * @applicability
+ *   Applies to HTML documents with a root <html> element.
+ *   The rule evaluates the document element only and does not iterate over child nodes.
+ *   Non-HTML documents or documents without a document element are not applicable.
+ *
+ * @expectation
+ *   The <html> element has a lang attribute.
+ *   The lang attribute is not empty and contains a syntactically valid language tag.
+ *
+ * @outcomes
+ *   Pass:
+ *     The <html> element has a non-empty lang attribute with a valid language tag.
+ *
+ *   Fail:
+ *     The <html> element does not have a lang attribute.
+ *     The <html> element has a lang attribute that is present but empty or whitespace.
+ *     The <html> element has a lang attribute with an invalid language tag.
+ *
+ * @notes
+ *   This rule does not verify that the declared language matches the actual language
+ *   of the page content. Language correctness is out of scope for SC 3.1.1.
+ *   Changes of language within the page are covered by SC 3.1.2.
+ */
+
+const id = 'html-lang-attr-present';
+
+const meta = {
+    title: 'Page language is declared',
+    description: 'Checks that the default language of the page is programmatically declared.',
+    i18n: {
+        titleKey: 'html_lang_attr_title',
+        descriptionKey: 'html_lang_attr_description'
+    },
+    helpUrl: null,
+    tags: ['wcag2a', 'wcag311', 'structure', 'language', 'automatic', 'atomic'],
+    wcagSc: ['3.1.1'],
+    normativeMappings: [
+        {
+            standard: 'WCAG',
+            version: '2.2',
+            requirement: '3.1.1',
+            title: 'Language of Page',
+            conformanceLevel: 'A'
+        }
+    ],
+    defaultSeverity: 'serious',
+    category: 'understandable',
+    type: 'automatic',
+    defaultConfidence: 'high',
+    coverage: {
+        facetsBySc: {
+            '3.1.1': ['html-lang-attr-present']
+        }
+    }
+};
+
+function runInPage(ctx) {
+    const { document, rule, helpers } = ctx;
+    const html = document && document.documentElement;
+
+    const tag = (html && html.tagName) ? String(html.tagName).toLowerCase() : '';
+    if (!html || tag !== 'html') {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'notApplicable',
+            severity: 'minor',
+            occurrences: []
+        };
+    }
+
+    const visibilityFilter = { targetSet: 'acc', accEligible: true, reasons: [] };
+
+    function pushFail(summaryKey, hintKey, params, details) {
+        const baseOccurrence = {
+            summary: '',
+            hint: '',
+            i18n: {
+                summaryKey,
+                hintKey,
+                params: params && typeof params === 'object' ? params : {}
+            },
+            data: {
+                visibilityFilter,
+                details: details && typeof details === 'object' ? details : {}
+            }
+        };
+
+        if (helpers && typeof helpers.reportOccurrence === 'function') {
+            return [helpers.reportOccurrence(html, baseOccurrence)];
+        }
+
+        // Never compute selector/snippet in the rule.
+        return [{ selector: '', html: '', ...baseOccurrence }];
+    }
+
+    const rawLang = html.getAttribute('lang'); // null if missing
+    const lang = (rawLang || '').trim();
+
+    if (rawLang === null) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'fail',
+            severity: rule.defaultSeverity,
+            occurrences: pushFail(
+                'html_lang_attr_missing_absent',
+                'html_lang_attr_hint_missing_absent',
+                {},
+                { reasonCode: 'lang-missing', location: 'html' }
+            )
+        };
+    }
+
+    if (lang.length === 0) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'fail',
+            severity: rule.defaultSeverity,
+            occurrences: pushFail(
+                'html_lang_attr_missing_empty',
+                'html_lang_attr_hint_missing_empty',
+                {},
+                { reasonCode: 'lang-empty', location: 'html' }
+            )
+        };
+    }
+
+    // Minimal BCP47 primary subtag check
+    if (!/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(lang)) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'fail',
+            severity: rule.defaultSeverity,
+            occurrences: pushFail(
+                'html_lang_attr_invalid',
+                'html_lang_attr_hint_invalid',
+                { lang },
+                { reasonCode: 'lang-invalid-bcp47', lang }
+            )
+        };
+    }
+
+    return {
+        ruleId: rule.ruleId,
+        outcome: 'pass',
+        severity: 'minor',
+        occurrences: []
+    };
+}
+
+module.exports = { id, meta, runInPage };