@surea11y/core 1.0.0

package/src/checks/automatic/dlitem-parent-valid.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * @check dlitem-parent-valid
+ * @atomic true
+ * @summary <dt>/<dd> elements must be contained by a <dl> (directly or via one wrapping <div>)
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   Applies to <dt>/<dd> elements that have a parent element.
+ * @expectation
+ *   The parent is <dl>, or the parent is a <div> whose own parent is <dl>
+ *   (a single level of wrapping div is allowed, matching how authors
+ *   commonly group dt/dd pairs). A <dt>/<dd> used outside a real
+ *   description-list container is not exposed as a term/definition to
+ *   assistive technologies.
+ * @implementation-notes
+ * - Distinct, atomic decision from definition-list-children-valid
+ *   (the inverse relationship: does a given <dl> have valid children).
+ */
+
+const id = 'dlitem-parent-valid';
+
+const meta = {
+  title: 'Description-list items must be inside a description list',
+  description: 'Checks that <dt>/<dd> elements are contained by a <dl>, directly or via one wrapping <div>.',
+  i18n: {
+    titleKey: 'dlitemParentValid_title',
+    descriptionKey: 'dlitemParentValid_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'list'],
+  wcagSc: ['1.3.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.3.1': ['dlitem-parent-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('dt, dd', safeRoot) : helpers.queryAll('dt, dd', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el) continue;
+    const parent = el.parentElement;
+    if (!parent) continue;
+
+    applicableCount += 1;
+
+    const parentTag = parent.tagName ? parent.tagName.toLowerCase() : '';
+    let valid = parentTag === 'dl';
+
+    if (!valid && parentTag === 'div') {
+      const grandparent = parent.parentElement;
+      const grandparentTag = grandparent && grandparent.tagName ? grandparent.tagName.toLowerCase() : '';
+      valid = grandparentTag === 'dl';
+    }
+
+    if (valid) 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 description-list item is not contained by a <dl>.',
+      hint: 'Place this <dt>/<dd> inside a <dl>, directly or wrapped in a single <div>.',
+      i18n: {
+        summaryKey: 'dlitemParentValid_summary_fail',
+        hintKey: 'dlitemParentValid_hint_fail',
+        params: { element: tag, parentElement: parentTag }
+      },
+      data: {
+        details: { reasonCode: 'DLITEM_INVALID_PARENT', element: tag, parentElement: parentTag }
+      }
+    });
+  }
+
+  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/duplicate-id-aria.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * @check duplicate-id-aria
+ * @atomic true
+ * @summary Any id referenced by an ARIA ID-reference attribute must be unique in the document
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies when the document contains at least one non-empty
+ *   aria-labelledby, aria-describedby, aria-owns, aria-controls,
+ *   aria-activedescendant, aria-flowto, aria-errormessage, or aria-details
+ *   attribute (i.e. at least one ARIA ID reference exists to resolve).
+ * @expectation
+ *   For every id value referenced by one of those attributes, exactly one
+ *   element in the document carries that id. A duplicated id referenced by
+ *   ARIA is ambiguous: assistive technologies cannot reliably determine
+ *   which element the reference resolves to (typically the first, silently
+ *   dropping the others).
+ * @implementation-notes
+ * - Scoped deliberately to ids referenced by ARIA (matching a widely-used
+ *   reference engine's duplicate-id-aria, not the broader/deprecated page-wide duplicate-id
+ *   check — see ROADMAP.md's "Skip" list).
+ * - Document-wide by design: id uniqueness and ARIA id references are a
+ *   whole-document property, not scoped to a sub-root.
+ */
+
+const id = 'duplicate-id-aria';
+
+const meta = {
+  title: 'IDs referenced by ARIA must be unique',
+  description: 'Checks that any id value referenced by an ARIA ID-reference attribute (aria-labelledby, aria-describedby, aria-owns, aria-controls, aria-activedescendant, aria-flowto, aria-errormessage, aria-details) is unique in the document.',
+  i18n: {
+    titleKey: 'duplicateIdAria_title',
+    descriptionKey: 'duplicateIdAria_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  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': ['duplicate-id-aria'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const IDREF_ATTRS = [
+    'aria-labelledby',
+    'aria-describedby',
+    'aria-owns',
+    'aria-controls',
+    'aria-activedescendant',
+    'aria-flowto',
+    'aria-errormessage',
+    'aria-details'
+  ];
+
+  const idMap = new Map(); // id -> element[]
+  const idNodes = document.querySelectorAll ? document.querySelectorAll('[id]') : [];
+  for (const el of idNodes) {
+    if (!el || !el.getAttribute) continue;
+    const value = String(el.getAttribute('id') || '').trim();
+    if (!value) continue;
+    if (!idMap.has(value)) idMap.set(value, []);
+    idMap.get(value).push(el);
+  }
+
+  const referencedIds = new Set();
+  for (const attr of IDREF_ATTRS) {
+    const selector = `[${attr}]`;
+    const nodes = document.querySelectorAll ? document.querySelectorAll(selector) : [];
+    for (const el of nodes) {
+      if (!el || !el.getAttribute) continue;
+      const raw = String(el.getAttribute(attr) || '').trim();
+      if (!raw) continue;
+      for (const token of raw.split(/\s+/)) {
+        if (token) referencedIds.add(token);
+      }
+    }
+  }
+
+  const occurrences = [];
+
+  for (const refId of referencedIds) {
+    const els = idMap.get(refId) || [];
+    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 id is referenced by an ARIA attribute but is used by more than one element.',
+        hint: 'Make ids referenced by ARIA attributes unique within the document.',
+        i18n: {
+          summaryKey: 'duplicateIdAria_summary_fail',
+          hintKey: 'duplicateIdAria_hint_fail',
+          params: { id: refId, duplicateCount: String(els.length) }
+        },
+        data: {
+          details: { reasonCode: 'DUPLICATE_ID_ARIA_REFERENCED', id: refId, duplicateCount: els.length }
+        }
+      });
+    }
+  }
+
+  if (referencedIds.size === 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/embed-text-alternative-present.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * @check embed-text-alternative-present
+ * @atomic true
+ * @summary Accessible <embed> elements must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <embed> elements that are exposed to assistive technologies.
+ *   Elements 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 <embed> provides a text alternative via:
+ *   - an accessible name (aria-labelledby/aria-label), OR
+ *   - a title attribute (best-effort fallback).
+ *
+ * Note: <embed> does not support fallback content in HTML, so this rule does not check children.
+ */
+
+const id = 'embed-text-alternative-present';
+
+const meta = {
+  title: '<embed> must provide a text alternative',
+  description: 'Checks that <embed> elements provide a text alternative via an accessible name.',
+  i18n: {
+    titleKey: 'embed_textAltPresent_title',
+    descriptionKey: 'embed_textAltPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'embed', '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': ['embed-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 embeds = (() => {
+    try { return Array.from((queryAllSmart ? queryAllSmart('embed') : queryAll('embed')) || []); }
+    catch { return queryAll('embed'); }
+  })();
+
+  if (!embeds.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 <embed>, 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 };
+  }
+
+  // `title` is a weaker text-alternative mechanism than aria-label/
+  // aria-labelledby — it is not reliably exposed to assistive technology
+  // in every context (e.g. touch/mobile) — so a pass achieved only via
+  // `title` is reported at reduced confidence rather than the rule's
+  // default `high`.
+  let anyPassedViaWeakMechanism = false;
+
+  for (const el of embeds) {
+    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);
+    if (name.present) {
+      if (name.mechanism === 'title') anyPassedViaWeakMechanism = true;
+      continue;
+    }
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Missing text alternative for <embed>.',
+      hint: 'Add an accessible name to <embed> (aria-label/aria-labelledby).',
+      i18n: {
+        summaryKey: 'embed_textAltPresent_summary_fail',
+        hintKey: 'embed_textAltPresent_hint_fail',
+        params: { element: 'embed' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        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',
+      confidence: anyPassedViaWeakMechanism ? 'medium' : 'high',
+      occurrences: []
+    };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+}
+
+module.exports = { id, meta, runInPage };