@surea11y/core 1.0.0

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

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * @check object-text-alternative-present
+ * @atomic true
+ * @summary Accessible <object> elements must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <object> elements that are exposed to assistive technologies.
+ *   Objects otherwise hidden from the accessibility tree remain applicable
+ *   if they are tabbable or referenced by IDREF relationships (per engine eligibility checks).
+ *   role="presentation"/role="none" are excluded only when not focusable.
+ * @expectation
+ *   Each applicable <object> provides a text alternative via:
+ *   - fallback content (non-empty text content inside <object>), OR
+ *   - an accessible name (aria-labelledby/aria-label), OR
+ *   - a title attribute (best-effort fallback).
+ */
+
+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.',
+  i18n: {
+    titleKey: 'object_textAltPresent_title',
+    descriptionKey: 'object_textAltPresent_description'
+  },
+  helpUrl: null,
+  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' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.1.1': ['object-text-alternative-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 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'); }
+  })();
+
+  if (!objects.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  const trim = (v) => (v == null ? '' : String(v)).trim();
+
+  function computeNameInfo(el) {
+    // For <object>, treat ARIA name as primary. Do not accept HTML <label> associations.
+    const flags = [];
+    let aria = null;
+
+    if (getAriaNameInfo) {
+      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) };
+    }
+
+    const title = trim(el.getAttribute && el.getAttribute('title'));
+    if (title) {
+      flags.push('title-used');
+      return { present: true, value: title, mechanism: 'title', flags };
+    }
+
+    if (aria && aria.flags && aria.flags.length) {
+      for (const f of aria.flags) flags.push(f);
+    }
+
+    return { present: false, value: '', mechanism: 'none', flags };
+  }
+
+  function computeFallbackText(el) {
+    try {
+      // Deterministic + bounded: textContent can be large
+      const raw = trim(el.textContent || '');
+      const t = raw.length > 1000 ? raw.slice(0, 1000) : raw;
+      return { present: !!t, value: t, mechanism: 'fallback', flags: t ? [] : ['empty'] };
+    } catch {
+      return { present: false, value: '', mechanism: 'fallback', flags: ['error'] };
+    }
+  }
+
+  for (const el of objects) {
+    if (!el || !el.getAttribute) continue;
+
+    if (isAccTreeEligible) {
+      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 ''; } })();
+    if (role === 'presentation' || role === 'none') {
+      let focusable = false;
+      if (getFocusableInfo) {
+        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()));
+      }
+      if (!focusable) continue;
+    }
+
+    applicableCount += 1;
+
+    const name = computeNameInfo(el);
+
+    // 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 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).',
+      i18n: {
+        summaryKey: 'object_textAltPresent_summary_fail',
+        hintKey: 'object_textAltPresent_hint_fail',
+        params: { element: 'object' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        fallback: fb,
+        name
+      }
+    };
+
+    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/option-name-present.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const id = 'option-name-present';
+
+const meta = {
+  title: 'Accessible name is present',
+  description: 'Checks that elements expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'optionNamePresent_title',
+    descriptionKey: 'optionNamePresent_description'
+  },
+  helpUrl: null,
+  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' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['option-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+      ? helpers.getEligibilityInfo
+      : null;
+  const safeRoot = root || document;
+
+
+  function normalizeWs(s) {
+    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 getConservativeSubtreeText(document, container) {
+    // "Name from content" — recurses into descendants and uses each one's
+    // own accessible name (img alt, aria-label/aria-labelledby, title) when
+    // it has one, not just literal text nodes. See getContentNameInfo's
+    // header comment in src/core/dom-helpers.js for the full rationale
+    // (this replaced a text-node-only TreeWalker that missed the common
+    // "<a><img alt='...'></a>" logo-link / "<button><img alt='...'></button>"
+    // icon-button pattern).
+    if (helpers.getContentNameInfo) {
+      const info = helpers.getContentNameInfo(container, ctx);
+      return info && info.present ? info.value : '';
+    }
+    const t = (container && container.textContent) ? String(container.textContent) : '';
+    return t.replace(/\s+/g, ' ').trim();
+  }
+
+  function resolveAriaLabelledbyText(document, el, maxRefs) {
+    const raw = getAttr(el, 'aria-labelledby');
+    if (!raw) return '';
+    // Delegates to the shared getTextFromIdRefs helper instead of computing
+    // name-from-content of the referenced element — see dialog-name-
+    // present.js's identical fix for the full rationale (an <iframe>
+    // aria-labelledby target's only name source is its title attribute,
+    // which name-from-content alone can never see).
+    if (helpers.getTextFromIdRefs) {
+      try {
+        const r = helpers.getTextFromIdRefs(raw, ctx, { maxRefs: maxRefs || 8 });
+        return normalizeWs(r && r.text);
+      } catch {}
+    }
+    return '';
+  }
+
+  function isEligibleAcc(helpers, el, ctx) {
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  const selector = "[role=\"option\"]";
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+
+  function hasName(el) {
+    const ariaLabel = getAttr(el, 'aria-label');
+    if (ariaLabel) return { ok: true, method: 'aria-label' };
+
+    const labelled = resolveAriaLabelledbyText(document, el, 8);
+    if (labelled) return { ok: true, method: 'aria-labelledby' };
+
+    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' };
+  }
+
+  for (const el of nodes) {
+    if (!el) continue;
+    if (!isEligibleAcc(helpers, el, ctx)) continue;
+
+    applicableCount += 1;
+
+    const res = hasName(el);
+    if (res.ok) continue;
+
+    const eligInfo = getEligibilityInfo
+        ? (() => { 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 || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This element has no accessible name.',
+      hint: 'Provide aria-label or aria-labelledby (preferred), or provide visible text that is not hidden from assistive technologies.',
+      i18n: {
+        summaryKey: 'optionNamePresent_summary_fail',
+        hintKey: 'optionNamePresent_hint_fail',
+        params: { controlType: 'option' }
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'option', methodTried: res.method },
+        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 || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,86 @@
+'use strict';
+
+const id = 'page-title-present';
+
+const meta = {
+  title: 'Page title is present and non-empty',
+  description: 'Checks that the document has a non-empty <title> element (WCAG 2.2 SC 2.4.2).',
+  i18n: {
+    titleKey: 'pageTitlePresent_title',
+    descriptionKey: 'pageTitlePresent_description'
+  },
+  helpUrl: null,
+  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' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'operable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '2.4.2': ['page-title-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  const occurrences = [];
+  let applicableCount = 1;
+
+  // Not restricted to `head > title`: per HTML parsing, a <title> encountered
+  // after <head> has closed is not re-parented into <head>, yet the browser
+  // (and document.title, used below) still recognizes it as the document's
+  // title — matching that here avoids a false "missing title" report for a
+  // <title> that legitimately ended up outside <head>.
+  const titleEl = document.querySelector('title');
+  const titleText = (document.title || '').replace(/\s+/g, ' ').trim();
+
+  const missingTitleEl = !titleEl;
+  const emptyTitle = !missingTitleEl && titleText.length === 0;
+
+  if (missingTitleEl || emptyTitle) {
+    const reasonCode = missingTitleEl ? 'missingTitleElement' : 'emptyTitleText';
+
+    const occBase = {
+      selector: 'head > title',
+      html: '',
+      summary: missingTitleEl
+          ? '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',
+        hintKey: 'pageTitlePresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: {
+          reasonCode,
+          titleText
+        },
+        visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    };
+
+    if (!missingTitleEl && titleEl && helpers && typeof helpers.reportOccurrence === 'function') {
+      // empty title: we have a node, so engine can attach html
+      occurrences.push(helpers.reportOccurrence(titleEl, occBase));
+    } else {
+      // missing title element: no node exists, keep deterministic html string
+      occurrences.push({ ...occBase, html: '<title>(missing)</title>' });
+    }
+  }
+
+  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/progressbar-name-present.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const id = 'progressbar-name-present';
+
+const meta = {
+  title: 'Progress bars have an accessible name',
+  description: 'Checks that elements with role="progressbar" expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'progressbarNamePresent_title',
+    descriptionKey: 'progressbarNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'atomic', 'automatic', 'name'],
+  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': ['progressbar-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+      ? helpers.getEligibilityInfo
+      : null;
+  const safeRoot = root || document;
+
+
+  function normalizeWs(s) {
+    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 getConservativeSubtreeText(document, container) {
+    // "Name from content" — recurses into descendants and uses each one's
+    // own accessible name (img alt, aria-label/aria-labelledby, title) when
+    // it has one, not just literal text nodes. See getContentNameInfo's
+    // header comment in src/core/dom-helpers.js for the full rationale
+    // (this replaced a text-node-only TreeWalker that missed the common
+    // "<a><img alt='...'></a>" logo-link / "<button><img alt='...'></button>"
+    // icon-button pattern).
+    if (helpers.getContentNameInfo) {
+      const info = helpers.getContentNameInfo(container, ctx);
+      return info && info.present ? info.value : '';
+    }
+    const t = (container && container.textContent) ? String(container.textContent) : '';
+    return t.replace(/\s+/g, ' ').trim();
+  }
+
+  function resolveAriaLabelledbyText(document, el, maxRefs) {
+    const raw = getAttr(el, 'aria-labelledby');
+    if (!raw) return '';
+    // Delegates to the shared getTextFromIdRefs helper instead of computing
+    // name-from-content of the referenced element — see dialog-name-
+    // present.js's identical fix for the full rationale (an <iframe>
+    // aria-labelledby target's only name source is its title attribute,
+    // which name-from-content alone can never see).
+    if (helpers.getTextFromIdRefs) {
+      try {
+        const r = helpers.getTextFromIdRefs(raw, ctx, { maxRefs: maxRefs || 8 });
+        return normalizeWs(r && r.text);
+      } catch {}
+    }
+    return '';
+  }
+
+  function isEligibleAcc(helpers, el, ctx) {
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  const selector = '[role="progressbar"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+
+  function evaluate(el) {
+    const ariaLabel = getAttr(el, 'aria-label');
+    if (ariaLabel) return { ok: true, method: 'aria-label' };
+
+    const ariaLabelledby = resolveAriaLabelledbyText(document, el, 8);
+    if (ariaLabelledby) return { ok: true, method: 'aria-labelledby' };
+
+    const title = getAttr(el, 'title');
+    if (title) return { ok: true, method: 'title' };
+
+    // role="progressbar" is name-from-author-only per WAI-ARIA (verified
+    // against a widely-used reference engine's own aria-progressbar-name check: any:
+    // ['aria-label', 'aria-labelledby', title] — no content-based naming
+    // method at all). It must NOT fall back to subtree content: found on a
+    // real site, Instacart's <ul role="progressbar"> loading skeleton has
+    // no name of its own, but nested descendants carry their own
+    // aria-label="Loading Box" (for a completely different purpose) —
+    // falling back to subtree content picked that up and wrongly treated
+    // it as the progressbar's own name, when that reference engine correctly
+    // still flags it as unnamed.
+    return { ok: false, method: 'none' };
+  }
+
+  for (const el of nodes) {
+    if (!el) continue;
+    if (!isEligibleAcc(helpers, el, ctx)) continue;
+
+    const role = getAttr(el, 'role').toLowerCase();
+    if (role !== 'progressbar') continue;
+
+    applicableCount += 1;
+
+    const res = evaluate(el);
+    if (res.ok) continue;
+
+    const eligInfo = getEligibilityInfo
+        ? (() => { 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 || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This progress bar has no accessible name.',
+      hint: 'Provide progress bar text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+      i18n: {
+        summaryKey: 'progressbarNamePresent_summary_fail',
+        hintKey: 'progressbarNamePresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'progressbar', methodTried: res.method },
+        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 || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };