@surea11y/core 1.0.0

package/src/checks/automatic/avoid-inline-spacing.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * @check avoid-inline-spacing
+ * @atomic true
+ * @summary Inline style must not force text-spacing properties with !important
+ * @standard WCAG 2.2
+ * @sc 1.4.12
+ * @applicability
+ *   Applies to elements with an inline style attribute that sets
+ *   line-height, letter-spacing, or word-spacing.
+ * @expectation
+ *   None of those three properties are declared with `!important` in the
+ *   inline style. WCAG 1.4.12 (Text Spacing) requires that users be able
+ *   to override these properties via a user stylesheet without losing
+ *   content or functionality; `!important` on an inline declaration
+ *   defeats that override (inline `!important` wins over nearly every
+ *   other origin, including user stylesheets applied the normal way).
+ * @implementation-notes
+ * - Static text-based parsing of the style attribute string (regex for
+ *   the three property names followed by `!important`), not computed
+ *   style — matches the property list a widely-used reference engine's avoid-inline-spacing
+ *   rule checks.
+ */
+
+const id = 'avoid-inline-spacing';
+
+const meta = {
+  title: 'Inline style must not force text spacing with !important',
+  description: 'Checks that inline style does not set line-height, letter-spacing, or word-spacing with !important, which blocks user text-spacing overrides.',
+  i18n: {
+    titleKey: 'avoidInlineSpacing_title',
+    descriptionKey: 'avoidInlineSpacing_description'
+  },
+  helpUrl: null,
+  tags: ['wcag21aa', 'wcag1412', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.4.12'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.4.12', title: 'Text Spacing', conformanceLevel: 'AA' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.4.12': ['avoid-inline-spacing'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const SPACING_PROPS = ['line-height', 'letter-spacing', 'word-spacing'];
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[style]', safeRoot) : helpers.queryAll('[style]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('style') || '');
+    if (!raw.trim()) continue;
+
+    const lower = raw.toLowerCase();
+    const hasAnySpacingProp = SPACING_PROPS.some((p) => lower.includes(p));
+    if (!hasAnySpacingProp) continue;
+
+    applicableCount += 1;
+
+    const flagged = [];
+    for (const prop of SPACING_PROPS) {
+      const re = new RegExp(prop.replace('-', '\\-') + '\\s*:[^;]*!important', 'i');
+      if (re.test(raw)) flagged.push(prop);
+    }
+
+    if (!flagged.length) 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 element's inline style forces ${flagged.join(', ')} with !important, blocking user text-spacing overrides.`,
+      hint: 'Remove !important from line-height/letter-spacing/word-spacing in inline styles so users can override text spacing.',
+      i18n: {
+        summaryKey: 'avoidInlineSpacing_summary_fail',
+        hintKey: 'avoidInlineSpacing_hint_fail',
+        params: { element: tag, properties: flagged.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'INLINE_SPACING_IMPORTANT', element: tag, properties: flagged }
+      }
+    });
+  }
+
+  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/binary-control-name-present.js

@@ -0,0 +1,294 @@
+'use strict';
+
+const id = 'binary-control-name-present';
+
+const meta = {
+  title: 'Binary controls have an accessible name',
+  description: 'Checks that checkbox, radio, and switch controls expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'binaryControlNamePresent_title',
+    descriptionKey: 'binaryControlNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a','wcag412','forms','atomic','automatic','name','checkbox','radio','switch'],
+  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': ['checkbox-name-present','radio-name-present','switch-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 = 'input[type="checkbox"], input[type="radio"], [role="checkbox"], [role="radio"], [role="switch"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+
+  // Precompute label[for] associations once for speed/determinism.
+  const labelForMap = buildLabelForMap(document);
+
+  function getNativeLabelText(el) {
+    // 1) labels API
+    try {
+      if ('labels' in el && el.labels && el.labels.length) {
+        // concatenate conservative text of all associated labels (cap at 4 for determinism)
+        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 {}
+
+    // 2) wrapped by <label>
+    try {
+      if (el.closest) {
+        const wrap = el.closest('label');
+        if (wrap) {
+          const t = getLabelText(wrap);
+          if (t) return t;
+        }
+      }
+    } catch {}
+
+    // 3) label[for=id]
+    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) {
+    // Programmatic mechanisms
+    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 input label association (for input[type=checkbox|radio])
+    if (controlType === 'checkbox' || controlType === 'radio') {
+      const lab = getNativeLabelText(el);
+      if (lab) return { ok: true, method: 'label' };
+    }
+
+    // ARIA roles (checkbox/radio/switch) can use content as name
+    if (controlType === 'switch' || controlType === 'aria-checkbox' || controlType === 'aria-radio') {
+      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;
+
+    // Determine control type
+    const tag = (el.tagName || '').toLowerCase();
+    const type = getAttr(el, 'type').toLowerCase();
+    const role = getAttr(el, 'role').toLowerCase();
+
+    let controlType = '';
+    if (tag === 'input' && type === 'checkbox') controlType = 'checkbox';
+    else if (tag === 'input' && type === 'radio') controlType = 'radio';
+    else if (role === 'checkbox') controlType = 'aria-checkbox';
+    else if (role === 'radio') controlType = 'aria-radio';
+    else if (role === 'switch') controlType = 'switch';
+    else continue;
+
+    applicableCount += 1;
+
+    const res = evaluate(el, controlType);
+    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 control has no accessible name.',
+      hint: 'Provide a label, aria-label, aria-labelledby, or other accessible-name mechanism so assistive technologies can identify the control.',
+      i18n: {
+        summaryKey: 'binaryControlNamePresent_summary_fail',
+        hintKey: 'binaryControlNamePresent_hint_fail',
+        params: { controlType }
+      },
+      data: {
+        details: {
+          reasonCode: 'name_missing',
+          controlType,
+          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/button-name-present.js

@@ -0,0 +1,146 @@
+'use strict';
+
+// NOTE: Repo ruleId contract requires ENGINE_TAG prefix in the rule id.
+// File name intentionally has no prefix, per request.
+const id = 'button-name-present';
+
+const meta = {
+  title: 'Buttons have an accessible name',
+  description: 'Checks that buttons expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'buttonNamePresent_title',
+    descriptionKey: 'buttonNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'forms', 'atomic', 'automatic', 'buttons', 'name'],
+  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': ['button-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getConservativeSubtreeText(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 getInputButtonValueName(el) {
+    try {
+      const type = normalizeWs(el.getAttribute ? el.getAttribute('type') : '').toLowerCase();
+      if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
+      const vAttr = el.getAttribute ? el.getAttribute('value') : '';
+      return normalizeWs(vAttr != null ? vAttr : (typeof el.value === 'string' ? el.value : ''));
+    } catch {
+      return '';
+    }
+  }
+
+  const selector = 'button, input[type="button"], input[type="submit"], input[type="reset"], [role="button"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  for (const el of nodes) {
+    // isAccTreeEligible returns { eligible, reasons }, not a boolean.
+    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    const eligible = typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    if (!eligible) continue;
+
+    applicableCount += 1;
+
+    const tag = (el.tagName || '').toLowerCase();
+    const role = el.getAttribute ? el.getAttribute('role') : null;
+
+    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
+
+    // getAccessibleNameInfo only resolves programmatic mechanisms (aria-labelledby,
+    // aria-label, native <label> association, title) — it never falls back to
+    // subtree content — so it's safe to trust directly whenever present.
+    const trustedProgrammaticName =
+      normalizeWs(nameInfo && nameInfo.present && typeof nameInfo.value === 'string' ? nameInfo.value : '');
+    const explicitProg = !!trustedProgrammaticName;
+
+    let inputValueName = '';
+    if (!trustedProgrammaticName && tag === 'input') {
+      inputValueName = getInputButtonValueName(el);
+    }
+
+    const isContentNameCandidate = tag === 'button' || role === 'button';
+    const contentName =
+      (!trustedProgrammaticName && !inputValueName && isContentNameCandidate)
+        ? getConservativeSubtreeText(el)
+        : '';
+
+    const finalName = normalizeWs(trustedProgrammaticName || inputValueName || contentName);
+
+    if (!finalName) {
+      // Only compute the richer eligibility-info payload (used solely for
+      // the occurrence's visibilityFilter) once we know an occurrence is
+      // actually being built, rather than for every applicable element.
+      const eligInfo = helpers.getEligibilityInfo ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : 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 button has no accessible name.',
+        hint: 'Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.',
+        i18n: {
+          summaryKey: 'buttonNamePresent_summary_fail',
+          hintKey: 'buttonNamePresent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'name_missing',
+            metrics: {
+              trustedProgrammaticNameLength: trustedProgrammaticName.length,
+              inputValueNameLength: inputValueName.length,
+              contentNameLength: contentName.length,
+              explicitProgrammatic: explicitProg ? 1 : 0
+            },
+            refs: { accessibleName: nameInfo || null }
+          }
+        }
+      });
+    }
+  }
+
+  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 };