@surea11y/core 1.0.0

package/src/checks/automatic/bypass-blocks-present.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * @check bypass-blocks-present
+ * @atomic true
+ * @summary The page must provide at least one mechanism to bypass repeated blocks of content
+ * @standard WCAG 2.2
+ * @sc 2.4.1
+ * @applicability
+ *   Always applicable to any HTML document with a <body> element —
+ *   "bypass blocks" is a whole-page concern, matching
+ *   aria-hidden-body / page-title-present's pattern of
+ *   evaluating the document directly rather than a scoped root.
+ * @expectation
+ *   At least one of the following recognized WCAG 2.4.1 techniques is
+ *   present:
+ *   (a) a main landmark (<main> or [role="main"]) — technique ARIA11: a
+ *       screen reader user can jump straight to it, bypassing everything
+ *       before it (nav, header, repeated blocks) in one step;
+ *   (b) a working same-page anchor link — technique G1/G123: an
+ *       <a href="#id"> (or legacy <a name="id">) whose target resolves to
+ *       a real element anywhere in the document. Deliberately NOT
+ *       required to be positioned before a <nav> or be keyboard-focus-
+ *       order-first — see implementation notes;
+ *   (c) at least one heading (<h1>-<h6> or [role="heading"]) — technique
+ *       H69: heading navigation is itself a standards-recognized bypass
+ *       mechanism (e.g. a screen reader's "jump by heading" command).
+ * @implementation-notes
+ * - This rule intentionally checks presence, not position, for the
+ *   same-page-anchor condition (b): a widely-used reference engine's real bypass algorithm is
+ *   heuristic (see ROADMAP.md's Tier 1a note on why this rule was
+ *   deferred from the rest of that batch), and getting DOM-order /
+ *   keyboard-focus-order positioning exactly right without introducing
+ *   false positives is materially harder than the rest of Tier 1a. Being
+ *   lenient about condition (b) can only produce a false NEGATIVE (missing
+ *   a page whose only anchor link isn't a real skip mechanism, e.g. a
+ *   "back to top" link) — never a false positive — which matches this
+ *   engine's non-negotiable "fail is reserved for high-confidence
+ *   violations" policy. A future revision can tighten (b) once a
+ *   positional heuristic has been validated against real pages without
+ *   regressions.
+ * - `fail` therefore means: no main landmark, no resolvable same-page
+ *   anchor link anywhere, and no heading anywhere on the page. That is a
+ *   strong, low-ambiguity signal that the page truly has zero recognized
+ *   bypass mechanism.
+ */
+
+const id = 'bypass-blocks-present';
+
+const meta = {
+  title: 'Page must provide a way to bypass repeated blocks',
+  description: 'Checks that the page has at least one recognized WCAG 2.4.1 bypass-blocks mechanism: a main landmark, a working same-page anchor link, or a heading.',
+  i18n: {
+    titleKey: 'bypassBlocksPresent_title',
+    descriptionKey: 'bypassBlocksPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag241', 'navigation', 'atomic', 'automatic'],
+  wcagSc: ['2.4.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.4.1', title: 'Bypass Blocks', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'operable',
+  type: 'automatic',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '2.4.1': ['bypass-blocks-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  const body = document && document.body ? document.body : null;
+  if (!body) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  function hasMainLandmark() {
+    try {
+      return !!document.querySelector('main, [role="main"]');
+    } catch {
+      return false;
+    }
+  }
+
+  function hasWorkingAnchorLink() {
+    let links = [];
+    try {
+      links = document.querySelectorAll('a[href]');
+    } catch {
+      links = [];
+    }
+    for (const a of links) {
+      if (!a || !a.getAttribute) continue;
+      const href = String(a.getAttribute('href') || '').trim();
+      if (href.length < 2 || href.charAt(0) !== '#') continue;
+      let fragment = href.slice(1);
+      try {
+        fragment = decodeURIComponent(fragment);
+      } catch {
+        // keep raw fragment if it isn't a valid percent-encoded string
+      }
+      fragment = fragment.trim();
+      if (!fragment) continue;
+
+      let target = null;
+      try {
+        target = document.getElementById(fragment);
+      } catch {
+        target = null;
+      }
+      if (!target) {
+        try {
+          target = document.querySelector('a[name="' + fragment.replace(/"/g, '\\"') + '"]');
+        } catch {
+          target = null;
+        }
+      }
+      if (target) return true;
+    }
+    return false;
+  }
+
+  function hasHeading() {
+    try {
+      return !!document.querySelector('h1, h2, h3, h4, h5, h6, [role="heading"]');
+    } catch {
+      return false;
+    }
+  }
+
+  const mainLandmark = hasMainLandmark();
+  const anchorLink = mainLandmark ? false : hasWorkingAnchorLink();
+  const heading = (mainLandmark || anchorLink) ? false : hasHeading();
+
+  if (mainLandmark || anchorLink || heading) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+
+  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
+  const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(body) : (body.outerHTML || '').slice(0, 200);
+
+  const occurrences = [{
+    selector: stableSelector,
+    html,
+    summary: 'This page has no recognized way to bypass repeated blocks of content.',
+    hint: 'Add a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content.',
+    i18n: {
+      summaryKey: 'bypassBlocksPresent_summary_fail',
+      hintKey: 'bypassBlocksPresent_hint_fail',
+      params: {}
+    },
+    data: {
+      details: { reasonCode: 'BYPASS_MECHANISM_ABSENT' },
+      visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
+    }
+  }];
+
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * @check canvas-text-alternative-present
+ * @atomic true
+ * @summary Accessible <canvas> elements must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <canvas> elements that are exposed to assistive technologies.
+ *   Elements otherwise hidden from the accessibility tree remain applicable
+ *   if they are focusable (tabbable) or referenced by IDREF relationships (per engine eligibility checks).
+ * @expectation
+ *   Each applicable <canvas> provides a text alternative via fallback content or an accessible name.
+ */
+
+const id = 'canvas-text-alternative-present';
+
+const meta = {
+  title: '<canvas> must provide a text alternative',
+  description: 'Checks that <canvas> elements provide a text alternative via fallback content or an accessible name.',
+  i18n: {
+    titleKey: 'canvas_textAltPresent_title',
+    descriptionKey: 'canvas_textAltPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'canvas', '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': ['canvas-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 getTextAlternativeInfo = helpers && typeof helpers.getTextAlternativeInfo === 'function'
+    ? helpers.getTextAlternativeInfo
+    : null;
+
+  const canvases = (() => {
+    try { return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []); }
+    catch { return queryAll('canvas'); }
+  })();
+
+  if (!canvases.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of canvases) {
+    if (!el) continue;
+
+    // Applicability: eligible in the accessibility tree (with focusable/IDREF exceptions handled by helper).
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
+    applicableCount += 1;
+
+    // Expectation: must provide a text alternative.
+    const ti = getTextAlternativeInfo
+      ? (() => { try { return getTextAlternativeInfo(el, ctx); } catch { return null; } })()
+      : null;
+
+    const hasTextAlt = !!(ti && ti.present);
+
+    if (hasTextAlt) continue;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      selector: '',
+      html: '',
+      summary: 'Missing text alternative for <canvas>.',
+      hint: 'Provide fallback text inside <canvas> or an accessible name (e.g., aria-label/aria-labelledby).',
+      i18n: {
+        summaryKey: 'canvas_textAltPresent_summary_fail',
+        hintKey: 'canvas_textAltPresent_hint_fail',
+        params: { element: 'canvas' }
+      },
+      data: {
+        // Always log eligibility/filter info (engine contract for targetSet=acc checks)
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        // Debuggable, deterministic helper facts (non-verdict)
+        textAlternative: ti || null
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      // Never compute selector/snippet in the rule.
+      occurrences.push({ ...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/combobox-name-present.js

@@ -0,0 +1,267 @@
+'use strict';
+
+const id = 'combobox-name-present';
+
+const meta = {
+  title: 'Comboboxes have an accessible name',
+  description: 'Checks that elements with role="combobox" expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'comboboxNamePresent_title',
+    descriptionKey: 'comboboxNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a','wcag412','forms','atomic','automatic','name','combobox'],
+  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': ['combobox-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 hasAttr(el, name) {
+    try { return !!(el && el.hasAttribute && el.hasAttribute(name)); } catch { return false; }
+  }
+
+  function isExplicitProgrammatic(el) {
+    // Programmatic name mechanisms we treat as authoritative (presence-only):
+    // - aria-label (non-empty)
+    // - aria-labelledby (non-empty)
+    // - title (non-empty) [weak but allowed for presence]
+    const al = getAttr(el, 'aria-label');
+    if (al) return true;
+    const alb = getAttr(el, 'aria-labelledby');
+    if (alb) return true;
+    const t = getAttr(el, 'title');
+    if (t) return true;
+    return false;
+  }
+
+  function buildLabelForMap(doc) {
+    const map = new Map(); // id -> label element (first)
+    try {
+      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
+      for (let i = 0; i < labels.length; i += 1) {
+        const lab = labels[i];
+        if (!lab || !lab.getAttribute) continue;
+        const f = normalizeWs(lab.getAttribute('for'));
+        if (!f) continue;
+        if (!map.has(f)) map.set(f, lab);
+      }
+    } catch {}
+    return map;
+  }
+
+  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();
+  }
+
+  // A <label> contributes a name via its own aria-label/aria-labelledby
+  // (checked first, same ARIA-over-content precedence any element's
+  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // aria-hidden="true">...</svg></label> names its control "Search" even
+  // though the label's only child content is aria-hidden) or, failing
+  // that, its rendered content (getConservativeSubtreeText).
+  function getLabelText(lab) {
+    if (helpers.getAriaNameInfo) {
+      try {
+        const aria = helpers.getAriaNameInfo(lab, ctx);
+        if (aria && aria.present && aria.value) return normalizeWs(aria.value);
+      } catch {}
+    }
+    const content = getConservativeSubtreeText(document, lab);
+    if (content) return content;
+    // Final fallback per the general accname text-alternative algorithm,
+    // which applies to any element being asked for its name regardless of
+    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // <label for> association): title, when nothing else yields a name.
+    // Purely additive (only fills in a name where there was none before),
+    // so it carries no false-positive risk — see dialog-name-present.js's
+    // identical <iframe>-title-fallback fix for the concrete real-world
+    // trigger this same accname step covers elsewhere.
+    return getAttr(lab, 'title');
+  }
+
+  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 getInputValueName(el) {
+    try {
+      const type = getAttr(el, 'type').toLowerCase();
+      if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
+      const v = getAttr(el, 'value');
+      return v;
+    } 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="combobox"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  // Precompute label[for] map for combobox elements that are labelable
+  // native form controls (e.g. <input role="combobox">).
+  const labelForMap = buildLabelForMap(document);
+
+  function getNativeLabelText(el) {
+    try {
+      if ('labels' in el && el.labels && el.labels.length) {
+        const parts = [];
+        const max = Math.min(4, el.labels.length);
+        for (let i = 0; i < max; i += 1) {
+          const lab = el.labels[i];
+          const t = lab ? getLabelText(lab) : '';
+          if (t) parts.push(t);
+        }
+        const joined = normalizeWs(parts.join(' '));
+        if (joined) return joined;
+      }
+    } catch {}
+    try {
+      if (el.closest) {
+        const wrap = el.closest('label');
+        if (wrap) {
+          const t = getLabelText(wrap);
+          if (t) return t;
+        }
+      }
+    } catch {}
+    try {
+      const idAttr = getAttr(el, 'id');
+      if (idAttr && labelForMap.has(idAttr)) {
+        const lab = labelForMap.get(idAttr);
+        const t = lab ? getLabelText(lab) : '';
+        if (t) return t;
+      }
+    } catch {}
+    return '';
+  }
+
+  function evaluate(el, controlType) {
+    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' };
+
+    // Native <label> association (e.g. <input role="combobox">).
+    const lab = getNativeLabelText(el);
+    if (lab) return { ok: true, method: 'label' };
+
+    // role="combobox" is name-from-author-only per WAI-ARIA: it must NOT
+    // fall back to subtree content. Visible text near/inside a custom
+    // combobox widget is not reliably exposed as its accessible name.
+    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 !== 'combobox') continue;
+
+    applicableCount += 1;
+
+    const res = evaluate(el, 'combobox');
+    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 combobox has no accessible name.',
+      hint: 'Provide aria-label or aria-labelledby (preferred), or ensure the element has visible text that is not hidden from assistive technologies.',
+      i18n: {
+        summaryKey: 'comboboxNamePresent_summary_fail',
+        hintKey: 'comboboxNamePresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'combobox', 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 };