@surea11y/core 1.0.0

package/src/checks/manual/aria-text-manual.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * @check aria-text
+ * @atomic true
+ * @summary role="text" elements should have no focusable descendants
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Elements with an explicit `role="text"`.
+ * @expectation
+ *   `role="text"` tells assistive technology to treat an element's whole
+ *   subtree as a single unit of plain text (e.g. text visually split
+ *   across multiple `<span>`s by styling). Per the WAI-ARIA Authoring
+ *   Practices, this only makes sense when that subtree contains no
+ *   focusable content — a focusable descendant inside a "this is just
+ *   text" region is unreachable or confusing for keyboard/AT users.
+ * @implementation-notes
+ * - Not WCAG-normative by a widely-used reference engine's own classification — authored as an
+ *   advisory, cantTell-capped `type: 'manual'` rule, matching the Tier 1b
+ *   precedent (see `landmark-unique`'s header comment for the shared
+ *   rationale).
+ * - "Focusable descendant" is a presence check (link/button/form
+ *   control/`[tabindex]`/`iframe`/`[contenteditable]`), the same
+ *   conservative selector `scrollable-region-focusable` uses, not a full
+ *   focusability computation (disabled state, visibility, etc.).
+ */
+
+const id = 'aria-text';
+
+const meta = {
+  title: 'role="text" elements should have no focusable descendants',
+  description: 'Checks that elements with role="text" contain no focusable descendant (link, button, form control, tabindex, iframe, or contenteditable).',
+  i18n: {
+    titleKey: 'ariaText_title',
+    descriptionKey: 'ariaText_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'aria', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'robust',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const FOCUSABLE_DESCENDANT_SELECTOR =
+    'a[href], button, input, select, textarea, [tabindex], iframe, [contenteditable]:not([contenteditable="false"])';
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role="text"]', safeRoot) : helpers.queryAll('[role="text"]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.querySelector) continue;
+
+    applicableCount += 1;
+
+    let focusableDescendant = null;
+    try {
+      focusableDescendant = el.querySelector(FOCUSABLE_DESCENDANT_SELECTOR);
+    } catch {
+      focusableDescendant = null;
+    }
+    if (!focusableDescendant) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: 'This role="text" element contains a focusable descendant.',
+      hint: 'Remove role="text" (or remove the focusable descendant) — a "plain text" region should not contain focusable content.',
+      i18n: {
+        summaryKey: 'ariaText_summary_cantTell',
+        hintKey: 'ariaText_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'ROLE_TEXT_HAS_FOCUSABLE_DESCENDANT' }
+      }
+    };
+
+    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 || 'minor', occurrences };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * @check canvas-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 = "canvas-text-alternative-quality";
+
+const meta = {
+  title: "<canvas> text alternative must be appropriate (manual review)",
+  description: "Flags <canvas> elements with a detected text alternative for human review of equivalence and appropriateness.",
+  i18n: {
+    titleKey: "canvas_textAltQuality_title",
+    descriptionKey: "canvas_textAltQuality_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "nontext", "canvas", "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 getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+        ? helpers.getEligibilityInfo
+        : null;
+
+    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
+
+    const __accEligCache = new WeakMap();
+    function accEligibleCached(node) {
+        if (!isAccTreeEligible) return { eligible: true, reasons: [] };
+        if (!node || typeof node !== 'object') return { eligible: true, reasons: [] };
+        const c = __accEligCache.get(node);
+        if (c) return c;
+        let r;
+        try { r = isAccTreeEligible(node, ctx); } catch { r = { eligible: true, reasons: [] }; }
+        r = r && typeof r === 'object' ? r : { eligible: !!r, reasons: [] };
+        __accEligCache.set(node, r);
+        return r;
+    }
+
+    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 {
+            let tabindex = null;
+            try { tabindex = el.getAttribute('tabindex'); } catch { tabindex = null; }
+            const t = tabindex == null ? '' : String(tabindex).trim();
+            focusable = t !== '' && !Number.isNaN(Number(t));
+        }
+        return !focusable;
+    }
+
+
+    const els = (() => {
+        try { return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []); }
+        catch { return queryAll('canvas'); }
+    })();
+
+    if (!els.length) {
+        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) continue;
+
+        if (isAccTreeEligible) {
+            const elig = accEligibleCached(el);
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        const getTextAlternativeInfo =
+            helpers && typeof helpers.getTextAlternativeInfo === 'function'
+                ? helpers.getTextAlternativeInfo
+                : null;
+
+        const trim = (v) => (v == null ? '' : String(v)).trim();
+
+        // Rule-specific applicability (only elements that already have a text alternative mechanism)
+        let textAltInfo = null;
+        if (getTextAlternativeInfo) {
+            try { textAltInfo = getTextAlternativeInfo(el, ctx); } catch { textAltInfo = null; }
+        }
+
+        const hasTextAlt = !!(textAltInfo && textAltInfo.present);
+        if (!hasTextAlt) continue;
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const baseOccurrence = {
+            summary: 'Review text alternative for <canvas> for equivalence and appropriateness.',
+            hint: 'Confirm the fallback text or accessible name conveys the same information/function as the canvas content.',
+            i18n: {
+                summaryKey: 'canvas_textAltQuality_summary_cantTell',
+                hintKey: 'canvas_textAltQuality_hint_cantTell',
+                params: { element: (el.tagName || '').toLowerCase() }
+            },
+            data: {
+                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details: textAltInfo || null
+            }
+        };
+
+        if (helpers && typeof helpers.reportOccurrence === 'function') {
+            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+        } else {
+            occurrences.push({ selector: '', 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 };

package/src/checks/manual/css-hidden-focus.js

@@ -0,0 +1,259 @@
+'use strict';
+
+/**
+ * @check css-hidden-focus
+ * @atomic true
+ * @summary focusable elements must be visible to sighted keyboard users
+ * @standard WCAG 2.2
+ * @sc 2.4.7
+ * @applicability
+ *   Applies to elements that are tabbable (keyboard-focusable) but are visually hidden
+ *   via CSS techniques that can leave them in the tab order.
+ * @expectation
+ *   No element should be tabbable while visually hidden (e.g., opacity:0, clipped, off-screen).
+ *
+ * Notes:
+ * - This rule intentionally targets CSS techniques that *can* keep an element focusable.
+ * - Elements removed from rendering (display:none, visibility:hidden, [hidden]) are excluded.
+ * - The rule uses deterministic heuristics (computed style parsing) and does not rely on layout geometry.
+ */
+
+const id = 'css-hidden-focus';
+
+const meta = {
+    title: 'Focusable elements must not be visually hidden',
+    description:
+        'Checks that keyboard-focusable elements are not visually hidden by CSS techniques that can leave them in the tab order.',
+    i18n: {
+        titleKey: 'cssHidden_focus_title',
+        descriptionKey: 'cssHidden_focus_description'
+    },
+    helpUrl: null,
+    tags: ['wcag2aa', 'wcag247', 'navigation', 'focus', 'css', 'atomic', 'manual'],
+    wcagSc: ['2.4.7'],
+    normativeMappings: [
+        {standard: 'WCAG', version: '2.2', requirement: '2.4.7', title: 'Focus Visible', conformanceLevel: 'AA'}
+    ],
+    defaultSeverity: 'serious',
+    category: 'operable',
+    type: 'manual',
+    defaultConfidence: 'low',
+    coverage: {
+        facetsBySc: {
+            '2.4.7': ['css-hidden-focusable']
+        }
+    }
+};
+
+function runInPage(ctx) {
+    const {document, root, helpers, rule} = ctx;
+    const safeRoot = root || document;
+
+    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+    const isDomVisibleEligible = helpers && typeof helpers.isDomVisibleEligible === 'function' ? helpers.isDomVisibleEligible : null;
+    const reportOccurrence = helpers && typeof helpers.reportOccurrence === 'function' ? helpers.reportOccurrence : null;
+
+    const trim = (v) => (v == null ? '' : String(v)).trim();
+    const lower = (v) => trim(v).toLowerCase();
+
+    function qAll(sel) {
+        try {
+            if (queryAllSmart) {
+                const r = queryAllSmart(sel);
+                if (Array.isArray(r)) return r;
+                return Array.from(r || []);
+            }
+        } catch {
+            // fall through
+        }
+        try {
+            if (safeRoot && typeof safeRoot.querySelectorAll === 'function') return Array.from(safeRoot.querySelectorAll(sel));
+        } catch {
+            // fall through
+        }
+        return [];
+    }
+
+    function getComputedStyleSafe(el) {
+        try {
+            const w = (document && document.defaultView) ? document.defaultView : (typeof window !== 'undefined' ? window : null);
+            return w && w.getComputedStyle ? w.getComputedStyle(el) : null;
+        } catch {
+            return null;
+        }
+    }
+
+    // Returns deterministic "visually hidden but can remain focusable" hints.
+    function getVisibilityHints(el) {
+        const out = [];
+        if (!el) return out;
+        const cs = getComputedStyleSafe(el);
+
+        // opacity:0
+        try {
+            const rawOp = cs && cs.opacity != null ? String(cs.opacity).trim() : '';
+            const op = rawOp ? Number.parseFloat(rawOp) : 1;
+            if (Number.isFinite(op) && op <= 0.0001) out.push('opacityZero');
+        } catch {
+        }
+
+        // clip / clip-path
+        try {
+            const clip = cs && cs.clip != null ? String(cs.clip).trim() : '';
+            const clipPath = cs && cs.clipPath != null ? String(cs.clipPath).trim() : '';
+            const clipLow = (clip || '').toLowerCase();
+            const clipPathLow = (clipPath || '').toLowerCase();
+
+            if (clipLow && clipLow !== 'auto') {
+                if (clipLow.indexOf('rect(') !== -1 && clipLow.replace(/\s+/g, '').indexOf('rect(0') !== -1) out.push('clipped');
+            }
+            if (clipPathLow && clipPathLow !== 'none') {
+                if (clipPathLow.indexOf('inset(') !== -1 && (clipPathLow.indexOf('100%') !== -1 || clipPathLow.indexOf('50%') !== -1)) {
+                    out.push('clipped');
+                }
+            }
+        } catch {
+        }
+
+        // zero-size + overflow hidden/clip
+        try {
+            const wv = cs && cs.width != null ? String(cs.width).trim() : '';
+            const hv = cs && cs.height != null ? String(cs.height).trim() : '';
+            const ov = cs && cs.overflow != null ? String(cs.overflow).trim().toLowerCase() : '';
+            const isZeroW = wv === '0px' || wv === '0';
+            const isZeroH = hv === '0px' || hv === '0';
+            const hidesOverflow = ov === 'hidden' || ov === 'clip';
+            if ((isZeroW || isZeroH) && hidesOverflow) out.push('zeroSizeOverflowHidden');
+        } catch {
+        }
+
+        // off-screen heuristic (absolute/fixed + left/top <= -5000 OR text-indent <= -5000)
+        try {
+            const pos = cs && cs.position != null ? String(cs.position).trim().toLowerCase() : '';
+            const left = cs && cs.left != null ? String(cs.left).trim().toLowerCase() : '';
+            const top = cs && cs.top != null ? String(cs.top).trim().toLowerCase() : '';
+            const ti = cs && cs.textIndent != null ? String(cs.textIndent).trim().toLowerCase() : '';
+
+            const parsePx = (s) => {
+                if (!s || s === 'auto') return null;
+                const m = String(s).match(/-?\d+(\.\d+)?/);
+                if (!m) return null;
+                const n = Number.parseFloat(m[0]);
+                return Number.isFinite(n) ? n : null;
+            };
+
+            const l = parsePx(left);
+            const t = parsePx(top);
+            const ind = parsePx(ti);
+
+            if (pos === 'absolute' || pos === 'fixed') {
+                if ((l != null && l <= -5000) || (t != null && t <= -5000)) out.push('offscreen');
+            }
+            if (ind != null && ind <= -5000) out.push('offscreen');
+        } catch {
+        }
+
+        // Dedup
+        const seen = new Set();
+        const uniq = [];
+        for (const k of out) {
+            const kk = String(k);
+            if (!seen.has(kk)) {
+                seen.add(kk);
+                uniq.push(kk);
+            }
+        }
+        return uniq;
+    }
+
+    function getFocusableInfoSafe(el) {
+        if (!getFocusableInfo) return null;
+        try {
+            return getFocusableInfo(el, ctx);
+        } catch {
+            return null;
+        }
+    }
+
+    function isTabbable(el, info) {
+        const f = info || getFocusableInfoSafe(el);
+        return !!(f && f.focusable && f.tabbable);
+    }
+
+    // Exclude elements that are not rendered / not in the visual rendering tree.
+    function isRendered(el) {
+        if (!isDomVisibleEligible) return true;
+        try {
+            const vis = isDomVisibleEligible(el, ctx, {visibilityMode: 'styleOnly', disableGeometry: true});
+            if (vis && vis.eligible === false) {
+                const rs = Array.isArray(vis.reasons) ? vis.reasons : [];
+                // We *include* opacityZero in this rule. Everything else is treated as not rendered for this purpose.
+                const nonOpacity = rs.filter((r) => String(r) !== 'opacityZero');
+                if (nonOpacity.length) return false;
+            }
+        } catch {
+            // If in doubt, keep deterministic behavior and consider it rendered.
+        }
+        return true;
+    }
+  const candidates = qAll('a[href],area[href],button,input,select,textarea,summary,[tabindex],[contenteditable]');
+  if (!candidates.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const el of candidates) {
+    if (!el || !el.getAttribute) continue;
+
+    const finfo = getFocusableInfoSafe(el);
+    if (!isTabbable(el, finfo)) continue;
+
+    // Skip elements not rendered (display:none, visibility:hidden, [hidden], etc.)
+    if (!isRendered(el)) continue;
+
+    const hints = getVisibilityHints(el);
+    if (!hints.length) continue; // <-- applicability gate
+
+    const tagName = (() => { try { return lower(el.tagName || ''); } catch { return ''; } })();
+
+    const hintOrder = ['opacityZero', 'offscreen', 'clipped', 'zeroSizeOverflowHidden'];
+    const hintsArr = [];
+    for (const k of hintOrder) if (hints.includes(k)) hintsArr.push(k);
+
+    const baseOccurrence = {
+      summary: `Focusable ${tagName} appears visually hidden (${hintsArr.join(',')}). Verify it becomes visible on keyboard focus.`,
+      hint: 'Manually tab to the element and confirm a visible focus indicator and that the element is visible when focused. If it remains hidden while focused, fix CSS/JS so it becomes visible or is removed from the tab order until visible.',
+      i18n: {
+        summaryKey: 'cssHidden_focus_summary_cantTell',
+        hintKey: 'cssHidden_focus_hint_cantTell',
+        params: { element: tagName, visibilityHints: hintsArr.join(',') }
+      },
+      data: {
+        details: {
+          reasonCode: 'cssHiddenTabbable_needsFocusStateVerification',
+          metrics: { visibilityHints: hintsArr.slice(0) }
+        }
+      }
+    };
+
+    occurrences.push(
+        reportOccurrence ? reportOccurrence(el, baseOccurrence) : { __node: el, selector: '', html: '', ...baseOccurrence }
+    );
+  }
+
+  // Manual rule + validator invariant: cantTell must have >= 1 occurrence
+  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};