@surea11y/core 1.0.0

package/src/checks/automatic/meta-refresh-timing-absent.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * @check meta-refresh-timing-absent
+ * @atomic true
+ * @summary <meta http-equiv="refresh"> must not impose a delayed page refresh
+ * @standard WCAG 2.2
+ * @sc 2.2.1
+ * @applicability
+ *   Applies to <meta http-equiv="refresh"> elements that carry a non-empty
+ *   content attribute with a parseable leading delay value.
+ * @expectation
+ *   The delay is 0 (an immediate redirect, which users cannot be caught by
+ *   mid-read), or exceeds 20 hours. Any other positive delay refreshes or
+ *   redirects the page on a timer the user did not initiate and cannot
+ *   pause, stop, or extend, which WCAG 2.2.1 (Timing Adjustable) requires
+ *   be possible.
+ * @implementation-notes
+ * - An unparseable content value (no leading numeric delay) is not
+ *   flagged — this rule only reports a clearly-detected timed refresh,
+ *   matching this engine's no-false-positives policy.
+ * - WCAG 2.2.1 Exception 3 exempts time limits longer than 20 hours (the
+ *   rationale being that a delay this long gives users enough real-world
+ *   time to act, so "adjustable" ceases to be a meaningful requirement).
+ *   A delay over 72000 seconds is therefore not flagged.
+ * - A <meta> nested inside <noscript> is excluded — see
+ *   meta-refresh-no-exceptions's header comment for why.
+ */
+
+const id = 'meta-refresh-timing-absent';
+
+const meta = {
+  title: 'Page must not use a timed meta refresh',
+  description: 'Checks that <meta http-equiv="refresh"> does not impose a positive delay of 20 hours or less.',
+  i18n: {
+    titleKey: 'metaRefreshTimingAbsent_title',
+    descriptionKey: 'metaRefreshTimingAbsent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag221', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['2.2.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.2.1', title: 'Timing Adjustable', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'operable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '2.2.1': ['meta-refresh-timing-absent'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // WCAG 2.2.1 Exception 3: time limits longer than 20 hours are exempt.
+  const EXEMPT_DELAY_SECONDS = 20 * 60 * 60;
+
+  const nodes = document.querySelectorAll ? document.querySelectorAll('meta[http-equiv="refresh" i]') : [];
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled — see meta-refresh-no-exceptions.js's header comment
+    const raw = String(el.getAttribute('content') || '').trim();
+    if (!raw) continue;
+
+    const match = raw.match(/^([0-9]*\.?[0-9]+)/);
+    if (!match) continue;
+    const delay = parseFloat(match[1]);
+    if (Number.isNaN(delay)) continue;
+
+    applicableCount += 1;
+
+    if (!(delay > 0)) continue;
+    if (delay > EXEMPT_DELAY_SECONDS) continue; // WCAG 2.2.1 Exception 3 (>20 hours)
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This page refreshes itself automatically after a delay.',
+      hint: 'Remove the timed meta refresh, or provide a way for users to turn it off, extend it, or pause it before it triggers.',
+      i18n: {
+        summaryKey: 'metaRefreshTimingAbsent_summary_fail',
+        hintKey: 'metaRefreshTimingAbsent_hint_fail',
+        params: { delay: String(delay) }
+      },
+      data: {
+        details: { reasonCode: 'META_REFRESH_DELAYED', delay }
+      }
+    });
+  }
+
+  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/meta-viewport-zoom-enabled.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * @check meta-viewport-zoom-enabled
+ * @atomic true
+ * @summary <meta name="viewport"> must not disable or cap pinch-zoom below 200%
+ * @standard WCAG 2.2
+ * @sc 1.4.4
+ * @applicability
+ *   Applies to <meta name="viewport"> elements that carry a non-empty
+ *   content attribute.
+ * @expectation
+ *   The content attribute does not set user-scalable to "no"/"0", and does
+ *   not set maximum-scale below 2 (200%). Either disables the user's
+ *   ability to zoom text to at least 200%, which WCAG 1.4.4 (Resize Text)
+ *   requires be possible.
+ * @implementation-notes
+ * - Malformed/unparseable maximum-scale values are ignored (not flagged) —
+ *   this rule only reports a clearly-detected zoom restriction, matching
+ *   this engine's no-false-positives policy.
+ */
+
+const id = 'meta-viewport-zoom-enabled';
+
+const meta = {
+  title: 'Viewport meta tag must not disable zoom',
+  description: 'Checks that <meta name="viewport"> does not set user-scalable=no or maximum-scale below 2 (200%).',
+  i18n: {
+    titleKey: 'metaViewportZoomEnabled_title',
+    descriptionKey: 'metaViewportZoomEnabled_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2aa', 'wcag144', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.4.4'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.4.4', title: 'Resize Text', conformanceLevel: 'AA' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.4.4': ['meta-viewport-zoom-enabled'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function parseContent(raw) {
+    const out = {};
+    for (const pair of String(raw || '').split(/[,;]/)) {
+      const eq = pair.indexOf('=');
+      if (eq === -1) continue;
+      const key = pair.slice(0, eq).trim().toLowerCase();
+      const value = pair.slice(eq + 1).trim().toLowerCase();
+      if (key) out[key] = value;
+    }
+    return out;
+  }
+
+  const nodes = document.querySelectorAll ? document.querySelectorAll('meta[name="viewport" i]') : [];
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('content') || '').trim();
+    if (!raw) continue;
+
+    applicableCount += 1;
+
+    const parsed = parseContent(raw);
+    const reasons = [];
+
+    const userScalable = parsed['user-scalable'];
+    if (userScalable === 'no' || userScalable === '0') {
+      reasons.push('user-scalable=' + userScalable);
+    }
+
+    const maxScaleRaw = parsed['maximum-scale'];
+    if (maxScaleRaw !== undefined) {
+      const maxScale = parseFloat(maxScaleRaw);
+      if (!Number.isNaN(maxScale) && maxScale < 2) {
+        reasons.push('maximum-scale=' + maxScaleRaw);
+      }
+    }
+
+    if (!reasons.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This viewport meta tag restricts the user’s ability to zoom.',
+      hint: 'Remove user-scalable=no and any maximum-scale below 2 from the viewport meta content.',
+      i18n: {
+        summaryKey: 'metaViewportZoomEnabled_summary_fail',
+        hintKey: 'metaViewportZoomEnabled_hint_fail',
+        params: { reasons: reasons.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'VIEWPORT_ZOOM_RESTRICTED', 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 || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,160 @@
+'use strict';
+
+const id = 'meter-name-present';
+
+const meta = {
+  title: 'Meters have an accessible name',
+  description: 'Checks that elements with role="meter" expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'meterNamePresent_title',
+    descriptionKey: 'meterNamePresent_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': ['meter-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="meter"]';
+  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="meter" is name-from-author-only per WAI-ARIA (verified against
+    // a widely-used reference engine's own aria-meter-name check: any: ['aria-label',
+    // 'aria-labelledby', title] — no content-based naming method at all).
+    // It must NOT fall back to subtree content — visible text near/inside a
+    // custom meter 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 !== 'meter') 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 meter has no accessible name.',
+      hint: 'Provide meter text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+      i18n: {
+        summaryKey: 'meterNamePresent_summary_fail',
+        hintKey: 'meterNamePresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'meter', 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/nested-interactive-controls-absent.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * @check nested-interactive-controls-absent
+ * @atomic true
+ * @summary An interactive control must not contain another interactive control
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements matching the interactive-control set (native
+ *   a[href], button, input (not hidden), select, textarea; or an explicit
+ *   ARIA widget role: button, link, checkbox, radio, switch, tab, textbox,
+ *   combobox, listbox, menuitem, menuitemcheckbox, menuitemradio, option,
+ *   slider, spinbutton, searchbox, treeitem).
+ * @expectation
+ *   The element does not contain, as a descendant, another element from
+ *   that same interactive-control set (e.g. a <button> wrapping a
+ *   <select>, or a link containing a checkbox). Nested interactive
+ *   controls are not reliably announced or operable via assistive
+ *   technology — activating the outer control and the inner one become
+ *   ambiguous, and some AT only exposes one of the two.
+ * @implementation-notes
+ * - Matches a widely-used reference engine's nested-interactive. Reports on the outer
+ *   (containing) control, not the nested descendant — this engine
+ *   considers the container the fixable unit ("move the nested control
+ *   outside this element").
+ * - A container can be reported once even with multiple nested
+ *   descendants (listed together); a deeply nested chain (A > B > C, all
+ *   interactive) reports both A and B as separate occurrences, since each
+ *   genuinely contains a nested interactive control.
+ */
+
+const id = 'nested-interactive-controls-absent';
+
+const meta = {
+  title: 'Interactive controls must not be nested',
+  description: 'Checks that an interactive control (link, button, form control, or ARIA widget role) does not contain another interactive control.',
+  i18n: {
+    titleKey: 'nestedInteractiveControlsAbsent_title',
+    descriptionKey: 'nestedInteractiveControlsAbsent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', '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': ['nested-interactive-controls-absent'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const INTERACTIVE_SELECTOR = [
+    'a[href]',
+    'button',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="checkbox"]',
+    '[role="radio"]',
+    '[role="switch"]',
+    '[role="tab"]',
+    '[role="textbox"]',
+    '[role="combobox"]',
+    '[role="listbox"]',
+    '[role="menuitem"]',
+    '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]',
+    '[role="option"]',
+    '[role="slider"]',
+    '[role="spinbutton"]',
+    '[role="searchbox"]',
+    '[role="treeitem"]'
+  ].join(', ');
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(INTERACTIVE_SELECTOR, safeRoot) : helpers.queryAll(INTERACTIVE_SELECTOR, safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.querySelectorAll) continue;
+
+    applicableCount += 1;
+
+    let nested = [];
+    try {
+      nested = Array.from(el.querySelectorAll(INTERACTIVE_SELECTOR));
+    } catch {
+      nested = [];
+    }
+    if (!nested.length) continue;
+
+    const nestedTags = nested.map((n) => (n && n.tagName ? n.tagName.toLowerCase() : 'unknown'));
+
+    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 interactive control contains one or more other interactive controls.',
+      hint: 'Move the nested interactive control(s) outside this element; nested interactive controls are not reliably operable via assistive technology.',
+      i18n: {
+        summaryKey: 'nestedInteractiveControlsAbsent_summary_fail',
+        hintKey: 'nestedInteractiveControlsAbsent_hint_fail',
+        params: { element: tag, nestedElements: nestedTags.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'NESTED_INTERACTIVE_CONTROL', element: tag, nestedElements: nestedTags }
+      }
+    });
+  }
+
+  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 };