@surea11y/core 1.0.0

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

@@ -0,0 +1,157 @@
+'use strict';
+
+const id = 'treeitem-name-present';
+
+const meta = {
+  title: 'Accessible name is present',
+  description: 'Checks that elements expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'treeitemNamePresent_title',
+    descriptionKey: 'treeitemNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag412", "navigation", "atomic", "automatic", "name", "treeitem"],
+  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': ['treeitem-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=\"treeitem\"]";
+  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: 'treeitemNamePresent_summary_fail',
+        hintKey: 'treeitemNamePresent_hint_fail',
+        params: { controlType: 'treeitem' }
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'treeitem', 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/valid-lang.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * @check valid-lang
+ * @atomic true
+ * @summary Any element's lang attribute must be a syntactically valid language tag
+ * @standard WCAG 2.2
+ * @sc 3.1.2
+ * @applicability
+ *   Applies to any element other than the root <html> with a non-empty
+ *   lang attribute.
+ * @expectation
+ *   The lang value matches a valid BCP47 language-tag syntax. WCAG 3.1.2
+ *   (Language of Parts) requires that when a passage's language differs
+ *   from the page's default, it is identified programmatically — an
+ *   invalid tag fails to identify a real language at all.
+ * @implementation-notes
+ * - Distinct, atomic decision from html-lang-attr-present (that
+ *   rule covers the root <html> element only, for SC 3.1.1); this rule
+ *   covers every other element, for SC 3.1.2.
+ * - Same minimal BCP47 *syntax* check as html-lang-attr-present (primary
+ *   subtag + optional subtags), not IANA Language Subtag Registry
+ *   validation — same documented scope limitation (syntactically
+ *   well-formed but unregistered tags like "xx-ZZ" are not flagged).
+ */
+
+const id = 'valid-lang';
+
+const meta = {
+  title: 'Element lang attribute must be syntactically valid',
+  description: 'Checks that any element (other than the root <html>) with a non-empty lang attribute uses a syntactically valid language tag.',
+  i18n: {
+    titleKey: 'validLang_title',
+    descriptionKey: 'validLang_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2aa', 'wcag312', 'structure', 'language', 'atomic', 'automatic'],
+  wcagSc: ['3.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '3.1.2', title: 'Language of Parts', conformanceLevel: 'AA' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'understandable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '3.1.2': ['element-lang-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const BCP47_RE = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[lang]', safeRoot) : helpers.queryAll('[lang]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    if (el.tagName && el.tagName.toLowerCase() === 'html') continue;
+
+    const raw = String(el.getAttribute('lang') || '').trim();
+    if (!raw) continue;
+
+    applicableCount += 1;
+
+    if (BCP47_RE.test(raw)) 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 lang attribute value ("${raw}") is not a syntactically valid language tag.`,
+      hint: 'Use a valid BCP47 language tag (e.g. "fr", "es-MX").',
+      i18n: {
+        summaryKey: 'validLang_summary_fail',
+        hintKey: 'validLang_hint_fail',
+        params: { element: tag, value: raw }
+      },
+      data: {
+        details: { reasonCode: 'ELEMENT_LANG_INVALID', element: tag, value: raw }
+      }
+    });
+  }
+
+  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/video-poster-text-alternative-present.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * @check video-poster-text-alternative-present
+ * @atomic true
+ * @summary Accessible <video> elements with a poster must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <video> elements that:
+ *   1) have a non-empty poster attribute, AND
+ *   2) are exposed to assistive technologies (per engine eligibility checks).
+ *   Elements otherwise hidden from the accessibility tree remain applicable
+ *   if they are tabbable or referenced by IDREF relationships (per eligibility checks).
+ *   Videos with role="presentation" or role="none" are excluded only when they are not focusable.
+ * @expectation
+ *   Each applicable <video> element provides a text alternative for the poster image, via:
+ *   - an accessible name (aria-label / aria-labelledby / title).
+ *   Between-tag fallback content inside <video> is NOT accepted: it is only
+ *   rendered by browsers that don't support <video>, so it is not reliably
+ *   exposed to assistive technologies in practice. <video> is also not a
+ *   labelable element, so native <label for="..."> associations are not
+ *   accepted either.
+ */
+
+const id = 'video-poster-text-alternative-present';
+
+const meta = {
+  title: '<video> poster must have a text alternative',
+  description:
+    'Checks that <video> elements with a poster image provide a text alternative (accessible name).',
+  i18n: {
+    titleKey: 'videoPoster_textAltPresent_title',
+    descriptionKey: 'videoPoster_textAltPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'media', 'video', '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: 'medium',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['video-poster-text-alt-present']
+    }
+  }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const reportOccurrence = helpers && typeof helpers.reportOccurrence === 'function'
+      ? helpers.reportOccurrence
+      : null;
+
+  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll = helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : null;
+
+  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+    ? helpers.getEligibilityInfo
+    : null;
+
+  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
+    ? helpers.isAccTreeEligible
+    : null;
+
+  const isFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
+    ? helpers.getFocusableInfo
+    : null;
+
+  const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
+    ? helpers.getAriaNameInfo
+    : null;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  function computeNameInfo(el) {
+    // <video> is not a labelable element (no browser computes an accessible
+    // name from <label for="...">), so only ARIA naming and title count —
+    // do not accept native <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 };
+  }
+
+  const videos = (() => {
+    try {
+      if (queryAllSmart) return Array.from(queryAllSmart('video') || []);
+      if (queryAll) return Array.from(queryAll('video') || []);
+      return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll('video')) : [];
+    } catch {
+      try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll('video')) : []; }
+      catch { return []; }
+    }
+  })();
+
+  if (!videos.length) return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of videos) {
+    if (!el || !el.getAttribute) continue;
+
+    const poster = trim(el.getAttribute('poster'));
+    if (!poster) continue; // not applicable: no poster image
+
+    // Eligibility: only elements exposed to AT (with helper exceptions)
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
+    // Role presentation/none excluded ONLY if not focusable (mirrors img behavior)
+    const role = trim(el.getAttribute('role')).toLowerCase();
+    if (role === 'presentation' || role === 'none') {
+      let focusable = false;
+      if (isFocusableInfo) {
+        const fi = (() => { try { return isFocusableInfo(el, ctx); } catch { return null; } })();
+        focusable = !!(fi && fi.focusable);
+      } else {
+        const tabindex = el.getAttribute('tabindex');
+        focusable = tabindex != null && trim(tabindex) !== '' && !Number.isNaN(Number(trim(tabindex)));
+      }
+      if (!focusable) continue;
+    }
+
+    applicableCount += 1;
+
+    const nameInfo = computeNameInfo(el);
+    if (nameInfo.present) continue;
+
+    let eligInfo = null;
+    if (getEligibilityInfo) {
+      try { eligInfo = getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { eligInfo = null; }
+    }
+
+    const baseOccurrence = {
+      summary: 'Missing text alternative for <video> poster.',
+      hint: 'Provide an accessible name (e.g., aria-label/aria-labelledby) for the poster image.',
+      i18n: {
+        summaryKey: 'videoPoster_textAltPresent_summary_fail',
+        hintKey: 'videoPoster_textAltPresent_hint_fail',
+        params: { element: 'video' }
+      },
+      data: {
+        poster,
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        nameInfo: nameInfo || null
+      }
+    };
+
+    if (reportOccurrence) {
+      occurrences.push(reportOccurrence(el, baseOccurrence));
+    } else {
+      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/manual/accesskeys-manual.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * @check accesskeys
+ * @atomic true
+ * @summary accesskey values must be unique on the page
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies whenever two or more elements share the same non-empty
+ *   accesskey attribute value (case-insensitive).
+ * @expectation
+ *   Every accesskey value on the page is unique. Duplicate accesskeys
+ *   make keyboard-shortcut activation ambiguous — only one of the
+ *   elements sharing the key can actually be reached by it, and which
+ *   one is browser/platform-dependent.
+ * @implementation-notes
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule; see landmark-banner-is-top-level's
+ *   header comment for the shared rationale/precedent.
+ */
+
+const id = 'accesskeys';
+
+const meta = {
+  title: 'accesskey values must be unique',
+  description: 'Checks that no two elements on the page share the same accesskey attribute value.',
+  i18n: {
+    titleKey: 'accesskeys_title',
+    descriptionKey: 'accesskeys_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'keyboard', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('[accesskey]');
+  } catch {
+    nodes = [];
+  }
+
+  const groups = new Map(); // normalized key -> elements[]
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('accesskey') || '').trim();
+    if (!raw) continue;
+    const key = raw.toLowerCase();
+    const list = groups.get(key) || [];
+    list.push(el);
+    groups.set(key, list);
+  }
+
+  const occurrences = [];
+  for (const [key, els] of groups) {
+    if (els.length <= 1) continue;
+    for (const el of els) {
+      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\'s accesskey is shared with another element on the page.',
+        hint: 'Make each accesskey value unique across the page.',
+        i18n: {
+          summaryKey: 'accesskeys_summary_cantTell',
+          hintKey: 'accesskeys_hint_cantTell',
+          params: { accesskey: key, duplicateCount: String(els.length) }
+        },
+        data: {
+          details: { reasonCode: 'ACCESSKEY_DUPLICATE', accesskey: key, duplicateCount: els.length }
+        }
+      });
+    }
+  }
+
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+}
+
+module.exports = { id, meta, runInPage };