@surea11y/core 1.0.0

package/src/checks/manual/scope-attr-valid-manual.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * @check scope-attr-valid
+ * @atomic true
+ * @summary The scope attribute must have a valid value
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to elements with a non-empty scope attribute.
+ * @expectation
+ *   The scope value is one of "row", "col", "rowgroup", or "colgroup"
+ *   (case-insensitive). An invalid scope value is not recognized by
+ *   assistive technology, silently losing the row/column header
+ *   association it was meant to declare.
+ * @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 = 'scope-attr-valid';
+
+const meta = {
+  title: 'scope attribute must have a valid value',
+  description: 'Checks that scope="..." is one of row, col, rowgroup, or colgroup.',
+  i18n: {
+    titleKey: 'scopeAttrValid_title',
+    descriptionKey: 'scopeAttrValid_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'tables', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  const VALID_SCOPES = new Set(['row', 'col', 'rowgroup', 'colgroup']);
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('[scope]');
+  } catch {
+    nodes = [];
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('scope') || '').trim();
+    if (!raw) continue;
+
+    applicableCount += 1;
+
+    if (VALID_SCOPES.has(raw.toLowerCase())) 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 scope attribute value is not recognized.',
+      hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
+      i18n: {
+        summaryKey: 'scopeAttrValid_summary_cantTell',
+        hintKey: 'scopeAttrValid_hint_cantTell',
+        params: { value: raw }
+      },
+      data: {
+        details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/scrollable-region-focusable-manual.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * @check scrollable-region-focusable
+ * @atomic true
+ * @summary A scrollable region with no focusable content should itself be keyboard-focusable
+ * @standard WCAG 2.2
+ * @sc 2.1.1, 2.1.3
+ * @applicability
+ *   Deliberately scoped to a fixed set of likely-to-scroll container tags
+ *   (div, section, article, aside, main, nav, pre, table, blockquote, ul,
+ *   ol, textarea) with computed `overflow-x`/`overflow-y` of `auto` or
+ *   `scroll` — not every element on the page, to keep this deterministic
+ *   and performant (same style of scope-down as `region`).
+ * @expectation
+ *   A region whose CSS declares it may scroll (`auto`/`scroll`) should be
+ *   reachable by keyboard: either it already contains a focusable
+ *   descendant (a link, button, form control, or `tabindex`-bearing
+ *   element a keyboard user could tab into and then use arrow keys to
+ *   scroll from), or the region itself carries a non-negative `tabindex`.
+ * @implementation-notes
+ * - jsdom does not perform layout, so `scrollHeight`/`clientHeight` are
+ *   not available to confirm the region's content actually overflows —
+ *   only that the CSS declares it *may*. Many elements declare
+ *   `overflow: auto` defensively without their content ever actually
+ *   overflowing, which would be a false positive if treated as a hard
+ *   `fail`. For that reason this is authored as `type: 'manual'`
+ *   (cantTell-capped, never fail) rather than `automatic` — same class of
+ *   layout-dependent gap as `iframe-focusable-content`'s
+ *   `contentDocument` limitation.
+ * - "Has a focusable descendant" is a presence check (link/button/form
+ *   control/`[tabindex]`/`iframe`/`[contenteditable]`), not a full
+ *   focusability computation (disabled state, visibility, etc.) — a
+ *   deliberate simplification to keep this rule self-contained and fast.
+ */
+
+const id = 'scrollable-region-focusable';
+
+const meta = {
+  title: 'Scrollable regions with no focusable content should be keyboard-focusable',
+  description:
+    'Flags elements whose CSS declares overflow:auto/scroll, contain no focusable descendant, and are not themselves keyboard-focusable, for manual review of whether their content actually overflows and needs keyboard scroll access.',
+  i18n: {
+    titleKey: 'scrollableRegionFocusable_title',
+    descriptionKey: 'scrollableRegionFocusable_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag2aaa', 'wcag211', 'wcag213', 'structure', 'atomic', 'manual'],
+  wcagSc: ['2.1.1', '2.1.3'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.1.1', title: 'Keyboard', conformanceLevel: 'A' },
+    { standard: 'WCAG', version: '2.2', requirement: '2.1.3', title: 'Keyboard (No Exception)', conformanceLevel: 'AAA' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'low',
+  coverage: {
+    facetsBySc: {
+      '2.1.1': ['scrollable-region-focusable-evidence'],
+      '2.1.3': ['scrollable-region-focusable-evidence']
+    }
+  }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function safeComputedStyle(el) {
+    try {
+      if (!el || el.nodeType !== 1) return null;
+      if (helpers && typeof helpers.computedStyle === 'function') {
+        const cs = helpers.computedStyle(el);
+        if (cs) return cs;
+      }
+      const view = (el.ownerDocument && el.ownerDocument.defaultView) ? el.ownerDocument.defaultView : null;
+      if (view && typeof view.getComputedStyle === 'function') return view.getComputedStyle(el);
+    } catch {}
+    return null;
+  }
+
+  function isScrollableOverflow(cs) {
+    if (!cs) return false;
+    const x = String(cs.overflowX || '').trim().toLowerCase();
+    const y = String(cs.overflowY || '').trim().toLowerCase();
+    return x === 'auto' || x === 'scroll' || y === 'auto' || y === 'scroll';
+  }
+
+  function isSelfFocusable(el) {
+    try {
+      const tabindexAttr = el.getAttribute ? el.getAttribute('tabindex') : null;
+      if (tabindexAttr != null) {
+        const n = Number.parseInt(tabindexAttr, 10);
+        if (Number.isFinite(n) && n >= 0) return true;
+      }
+    } catch {}
+    return false;
+  }
+
+  const FOCUSABLE_DESCENDANT_SELECTOR =
+    'a[href], button, input, select, textarea, [tabindex], iframe, [contenteditable]:not([contenteditable="false"])';
+
+  function hasFocusableDescendant(el) {
+    try {
+      return !!(el.querySelector && el.querySelector(FOCUSABLE_DESCENDANT_SELECTOR));
+    } catch {
+      return false;
+    }
+  }
+
+  const CANDIDATE_SELECTOR = 'div, section, article, aside, main, nav, pre, table, blockquote, ul, ol, textarea';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(CANDIDATE_SELECTOR, safeRoot) : helpers.queryAll(CANDIDATE_SELECTOR, safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const cs = safeComputedStyle(el);
+    if (!isScrollableOverflow(cs)) continue;
+
+    applicableCount += 1;
+
+    if (isSelfFocusable(el)) continue;
+    if (hasFocusableDescendant(el)) continue;
+
+    const tag = (el.tagName || '').toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: 'This element declares overflow:auto/scroll, has no focusable descendant, and is not itself keyboard-focusable.',
+      hint: 'If this region’s content actually overflows, add tabindex="0" (and a suitable label) so keyboard users can focus it and scroll with the arrow keys.',
+      i18n: {
+        summaryKey: 'scrollableRegionFocusable_summary_cantTell',
+        hintKey: 'scrollableRegionFocusable_hint_cantTell',
+        params: { element: tag }
+      },
+      data: {
+        details: { reasonCode: 'SCROLLABLE_OVERFLOW_NOT_FOCUSABLE', element: tag }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push(baseOccurrence);
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'moderate', occurrences };
+  }
+
+  // Manual rules may only emit cantTell/notApplicable (never pass/fail):
+  // every scrollable-overflow candidate is already reachable by keyboard.
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/skip-link-manual.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * @check skip-link
+ * @atomic true
+ * @summary A "skip" link must resolve to a real, focusable target
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to <a href="#fragment"> elements whose accessible name
+ *   matches a common "skip to ..." / "jump to ..." authoring convention
+ *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
+ *   pattern for a skip-navigation link, not every same-page anchor link
+ *   on the page. "jump to" added 2026-07-23 after a real page (Wish.com)
+ *   surfaced a skip link reading "Jump to section" with a genuinely
+ *   missing target — invisible to the original "skip"-only pattern,
+ *   while a widely-used reference engine's own (purely positional, not text-based) matching
+ *   caught it. Text-pattern matching itself stays deliberate (see
+ *   implementation-notes) — this only widens the known-convention list.
+ * @expectation
+ *   The link's fragment resolves to a real element in the document
+ *   (via a matching id, or a legacy <a name="...">). A skip link whose
+ *   target does not exist silently does nothing when activated.
+ * @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.
+ * - Keyed on the "skip" text-pattern convention rather than positional
+ *   heuristics (first link in tab order, etc.), matching the same
+ *   deliberate-leniency reasoning documented in
+ *   bypass-blocks-present's implementation notes.
+ */
+
+const id = 'skip-link';
+
+const meta = {
+  title: 'Skip link must have a resolvable target',
+  description: 'Checks that a "skip to ..." link\'s href fragment resolves to a real element in the document.',
+  i18n: {
+    titleKey: 'skipLink_title',
+    descriptionKey: 'skipLink_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'keyboard', 'navigation', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getAccessibleNameText(el) {
+    const al = normalizeWs(el.getAttribute && el.getAttribute('aria-label'));
+    if (al) return al;
+    const alb = normalizeWs(el.getAttribute && el.getAttribute('aria-labelledby'));
+    if (alb) {
+      const parts = [];
+      for (const refId of alb.split(/\s+/).filter(Boolean)) {
+        try {
+          const ref = document.getElementById(refId);
+          if (ref) {
+            const t = normalizeWs(ref.textContent);
+            if (t) parts.push(t);
+          }
+        } catch {}
+      }
+      const joined = normalizeWs(parts.join(' '));
+      if (joined) return joined;
+    }
+    return normalizeWs(el.textContent);
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]', safeRoot) : helpers.queryAll('a[href]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const href = String(el.getAttribute('href') || '').trim();
+    if (href.length < 2 || href.charAt(0) !== '#') continue;
+
+    const name = getAccessibleNameText(el);
+    if (!/skip/i.test(name) && !/jump\s*to/i.test(name)) continue;
+
+    applicableCount += 1;
+
+    let fragment = href.slice(1);
+    try {
+      fragment = decodeURIComponent(fragment);
+    } catch {}
+    fragment = fragment.trim();
+
+    let target = null;
+    if (fragment) {
+      try {
+        target = document.getElementById(fragment);
+      } catch {
+        target = null;
+      }
+      if (!target) {
+        try {
+          target = document.querySelector('a[name="' + fragment.replace(/"/g, '\\"') + '"]');
+        } catch {
+          target = null;
+        }
+      }
+    }
+
+    if (target) 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 skip link\'s target does not exist.',
+      hint: 'Point the skip link\'s href at an id that exists in the document, or add the missing target element.',
+      i18n: {
+        summaryKey: 'skipLink_summary_cantTell',
+        hintKey: 'skipLink_hint_cantTell',
+        params: { href }
+      },
+      data: {
+        details: { reasonCode: 'SKIP_LINK_TARGET_MISSING', href }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/svg-text-alternative-quality-manual.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * @check svg-text-alternative-quality
+ * @atomic true
+ * @summary Manual review: text alternative appropriateness (WCAG 1.1.1)
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @type manual
+ * @expectation
+ *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ */
+
+const id = "svg-text-alternative-quality";
+
+const meta = {
+    title: "<svg> text alternative must be appropriate (manual review)",
+    description: "Flags applicable <svg> graphics with a detected text alternative for human review of appropriateness.",
+    i18n: {
+        titleKey: "svg_textAltQuality_title",
+        descriptionKey: "svg_textAltQuality_description"
+    },
+    helpUrl: null,
+    tags: ["wcag2a", "wcag111", "nontext", "svg", "manual", "atomic"],
+    wcagSc: ['1.1.1'],
+    normativeMappings: [
+        {standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A'}
+    ],
+    defaultSeverity: 'minor',
+    category: 'perceivable',
+    type: 'manual',
+    defaultConfidence: 'medium',
+    coverage: {
+        facetsBySc: {
+            '1.1.1': ['text-alternative-quality']
+        }
+    }
+};
+
+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 buildSelector = helpers && typeof helpers.buildSelector === 'function'
+        ? helpers.buildSelector
+        : (el) => {
+            try {
+                if (!el || !el.tagName) return 'html';
+                const tag = (el.tagName || 'html').toLowerCase();
+                return el.id ? `${tag}#${el.id}` : tag;
+            } catch {
+                return 'html';
+            }
+        };
+
+    const getOuterHtmlSnippet = helpers && typeof helpers.getOuterHtmlSnippet === 'function'
+        ? helpers.getOuterHtmlSnippet
+        : (el) => { try { return (el && el.outerHTML) ? String(el.outerHTML).slice(0, 2000) : ''; } 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;
+
+    function isRolePresentationExcluded(el) {
+        const role = (() => {
+            try {
+                return String(el.getAttribute('role') || '').trim().toLowerCase();
+            } catch {
+                return '';
+            }
+        })();
+        if (role !== 'presentation' && role !== 'none') return false;
+
+        // Exclude only when NOT focusable (mirrors img-alt-present policy)
+        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()));
+        }
+        return !focusable;
+    }
+
+
+    const els = (() => {
+        try {
+            return Array.from((queryAllSmart ? queryAllSmart('svg') : queryAll('svg')) || []);
+        } catch {
+            return queryAll('svg');
+        }
+    })();
+
+    if (!els.length) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    const trim = (v) => (v == null ? '' : String(v)).trim();
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) continue;
+
+        // acc eligibility
+        if (isAccTreeEligible) {
+            const elig = (() => { try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; } })();
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        // Detect mechanisms once
+        let titleText = '';
+        let descText = '';
+        let ariaLabel = '';
+        let ariaLabelledBy = '';
+        let labelledByText = '';
+
+        try {
+            const titleEl = el.querySelector ? el.querySelector('title') : null;
+            const descEl = el.querySelector ? el.querySelector('desc') : null;
+            titleText = trim(titleEl && titleEl.textContent);
+            descText = trim(descEl && descEl.textContent);
+
+            ariaLabel = trim(el.getAttribute('aria-label'));
+            ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
+        } catch {}
+
+        if (!ariaLabel && ariaLabelledBy && helpers && typeof helpers.getTextFromIdRefs === 'function') {
+            try {
+                const t = helpers.getTextFromIdRefs(ariaLabelledBy, ctx);
+                labelledByText = trim(t && t.text);
+            } catch {}
+        }
+
+        const hasNonEmptyTitle = !!titleText;
+        const hasNonEmptyDesc = !!descText;
+        const hasAriaLabel = !!ariaLabel;
+        const hasResolvedLabelledBy = !!labelledByText;
+
+        const hasMechanism = hasNonEmptyTitle || hasNonEmptyDesc || hasAriaLabel || hasResolvedLabelledBy;
+        if (!hasMechanism) continue;
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const baseOccurrence = {
+            summary: 'Review text alternative for <svg> for accuracy and appropriateness.',
+            hint: 'Confirm the <title>/<desc> or ARIA name conveys the meaning/purpose of the graphic in context.',
+            i18n: {
+                summaryKey: 'svg_textAltQuality_summary_cantTell',
+                hintKey: 'svg_textAltQuality_hint_cantTell',
+                params: { element: 'svg' }
+            },
+            data: {
+                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details: {
+                    hasNonEmptyTitle,
+                    hasNonEmptyDesc,
+                    ariaLabel: ariaLabel || null,
+                    ariaLabelledBy: ariaLabelledBy || null,
+                    ariaLabelledByText: labelledByText ? labelledByText.slice(0, 120) : null // deterministic truncation
+                }
+            }
+        };
+
+        if (helpers && typeof helpers.reportOccurrence === 'function') {
+            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+        } else {
+            const selectorStr = (() => { try { return buildSelector(el); } catch { return 'html'; } })();
+            const html = getOuterHtmlSnippet(el);
+            occurrences.push({ selector: selectorStr, html, ...baseOccurrence });
+        }
+    }
+
+    if (applicableCount === 0) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    return {ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences};
+}
+
+module.exports = {id, meta, runInPage};