@surea11y/core 1.0.0

package/src/checks/manual/area-alt-decorative-manual.js

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * @check area-alt-decorative
+ * @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 = "area-alt-decorative";
+
+const meta = {
+    title: "<area> with alt=\"\" must be decorative (manual review)",
+    description: "Flags <area> elements with empty alt for human review that they are decorative/non-informative.",
+    i18n: {
+        titleKey: "area_altDecorative_title",
+        descriptionKey: "area_altDecorative_description"
+    },
+    helpUrl: null,
+    tags: ["wcag2a", "wcag111", "nontext", "images", "imagemap", "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 __accEligCache = new WeakMap();
+    function accEligibleCached(node) {
+        if (!isAccTreeEligible) return { eligible: true, reasons: [] };
+        if (!node || typeof node !== 'object') return { eligible: true, reasons: [] };
+        const cached = __accEligCache.get(node);
+        if (cached) return cached;
+        let res;
+        try { res = isAccTreeEligible(node, ctx); }
+        catch { res = { eligible: true, reasons: [] }; }
+        res = res && typeof res === 'object' ? res : { eligible: !!res, reasons: [] };
+        __accEligCache.set(node, res);
+        return res;
+    }
+
+    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+        ? helpers.getEligibilityInfo
+        : null;
+
+    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
+
+
+// --- image-map semantics (rule-local; match automatic <area> applicability) ---
+    function normUsemap(val) {
+        try {
+            const t = String(val || '').trim();
+            if (!t) return '';
+            return (t[0] === '#') ? t.slice(1).trim().toLowerCase() : t.toLowerCase();
+        } catch {
+            return '';
+        }
+    }
+
+    function getMapName(mapEl) {
+        try {
+            if (!mapEl || !mapEl.getAttribute) return '';
+            const n = String(mapEl.getAttribute('name') || mapEl.getAttribute('id') || '').trim();
+            return n ? n.toLowerCase() : '';
+        } catch {
+            return '';
+        }
+    }
+
+    function getReferencingImgForArea(areaEl) {
+        try {
+            if (!areaEl || !areaEl.closest) return null;
+            const map = areaEl.closest('map');
+            if (!map) return null;
+            const mapName = getMapName(map);
+            if (!mapName) return null;
+
+            const imgs = Array.from(document.querySelectorAll('img[usemap]'));
+            for (const img of imgs) {
+                const u = normUsemap(img.getAttribute('usemap'));
+                if (u && u === mapName) return img; // deterministic: first match in doc order
+            }
+        } catch {
+        }
+        return 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("area") : queryAll("area")) || []);
+        } catch {
+            return queryAll("area");
+        }
+    })();
+
+    const __usemapIndex = new Map(); // mapName -> img (first in document order)
+    try {
+        const imgs = Array.from(document.querySelectorAll('img[usemap]'));
+        for (const img of imgs) {
+            const u = normUsemap(img.getAttribute('usemap'));
+            if (!u) continue;
+            if (!__usemapIndex.has(u)) __usemapIndex.set(u, img); // keep first match only
+        }
+    } catch {
+    }
+
+    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;
+
+        // Must belong to a *used* image map (referenced by an <img usemap>). If unused, not applicable.
+        let img = null;
+        try {
+            const map = el.closest && el.closest('map');
+            const mapName = map ? getMapName(map) : '';
+            img = mapName ? (__usemapIndex.get(mapName) || null) : null;
+        } catch {
+            img = null;
+        }
+        if (!img) continue;
+
+        // The referencing <img> must be eligible in the accessibility tree.
+        if (isAccTreeEligible) {
+            const imgElig = accEligibleCached(img);
+            if (imgElig && imgElig.eligible === false) continue;
+        }
+
+        if (isAccTreeEligible) {
+            const elig = (() => {
+                try {
+                    return isAccTreeEligible(el, ctx);
+                } catch {
+                    return {eligible: true, reasons: []};
+                }
+            })();
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        // Rule-specific applicability (only elements that already have a text alternative mechanism)
+        let alt = null;
+        try { alt = el.getAttribute('alt'); } catch { alt = null; }
+        if (alt === null) continue;
+        if (String(alt).trim() !== '') continue; // only alt=""
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, {targetSet: 'acc'}) : null;
+
+        const baseOccurrence = {
+            summary: 'Review whether <area> is decorative (alt="").',
+            hint: 'Confirm the area does not convey information or function. If it is interactive or meaningful, provide meaningful alt text.',
+            i18n: {
+                summaryKey: 'area_altDecorative_summary_cantTell',
+                hintKey: 'area_altDecorative_hint_cantTell',
+                params: {element: (el.tagName || '').toLowerCase()}
+            },
+            data: {
+                visibilityFilter: eligInfo || {targetSet: 'acc', accEligible: null, reasons: []},
+                details: 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/area-alt-quality-manual.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * @check area-alt-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 = "area-alt-quality";
+
+const meta = {
+  title: "<area> alt text must be appropriate (manual review)",
+  description: "Flags <area> elements with non-empty alt text for human review of appropriateness.",
+  i18n: {
+    titleKey: "area_altQuality_title",
+    descriptionKey: "area_altQuality_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "nontext", "images", "imagemap", "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;
+    }
+
+// --- image-map semantics (rule-local; match automatic <area> applicability) ---
+function normUsemap(val) {
+    try {
+        const t = String(val || '').trim();
+        if (!t) return '';
+        return (t[0] === '#') ? t.slice(1).trim().toLowerCase() : t.toLowerCase();
+    } catch { return ''; }
+}
+function getMapName(mapEl) {
+    try {
+        if (!mapEl || !mapEl.getAttribute) return '';
+        const n = String(mapEl.getAttribute('name') || mapEl.getAttribute('id') || '').trim();
+        return n ? n.toLowerCase() : '';
+    } catch { return ''; }
+}
+
+    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('area') : queryAll('area')) || []); }
+        catch { return queryAll('area'); }
+    })();
+
+    if (!els.length) {
+        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    const __usemapIndex = new Map(); // mapName -> img (first in document order)
+    try {
+        const imgs = Array.from(document.querySelectorAll('img[usemap]'));
+        for (const img of imgs) {
+            const u = normUsemap(img.getAttribute('usemap'));
+            if (!u) continue;
+            if (!__usemapIndex.has(u)) __usemapIndex.set(u, img);
+        }
+    } catch {}
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) continue;
+
+// Must belong to a *used* image map (referenced by an <img usemap>). If unused, not applicable.
+        let img = null;
+        try {
+            const map = el.closest && el.closest('map');
+            const mapName = map ? getMapName(map) : '';
+            img = mapName ? (__usemapIndex.get(mapName) || null) : null;
+        } catch {
+            img = null;
+        }
+        if (!img) continue;
+
+// The referencing <img> must be eligible in the accessibility tree.
+if (isAccTreeEligible) {
+    const imgElig = accEligibleCached(img);
+    if (imgElig && imgElig.eligible === false) continue;
+}
+
+        if (isAccTreeEligible) {
+            const elig = accEligibleCached(el);
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        // Rule-specific applicability (only elements that already have a text alternative mechanism)
+        let alt = null;
+        try { alt = el.getAttribute('alt'); } catch { alt = null; }
+        if (alt === null) continue;
+        if (String(alt).trim() === '') continue; // only non-empty alt is applicable here
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        let altVal = '';
+        try { altVal = String(el.getAttribute('alt') || ''); } catch { altVal = ''; }
+
+        const baseOccurrence = {
+            summary: 'Review alt text on <area> for accuracy and appropriateness.',
+            hint: 'Ensure the alt text identifies the destination/action of the image map area in context.',
+            i18n: {
+                summaryKey: 'area_altQuality_summary_cantTell',
+                hintKey: 'area_altQuality_hint_cantTell',
+                params: { element: (el.tagName || '').toLowerCase() }
+            },
+            data: {
+                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details: { alt: altVal.trim() } // optional but useful for manual review
+            }
+        };
+
+        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/aria-checked-state-mismatch-manual.js

@@ -0,0 +1,141 @@
+'use strict';
+
+/**
+ * @check aria-checked-state-mismatch
+ * @atomic true
+ * @summary A native checkbox/radio's aria-checked should match its actual checked/indeterminate state
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Native `<input type="checkbox">` / `<input type="radio">` elements
+ *   that carry an explicit `aria-checked` attribute.
+ * @expectation
+ *   `aria-checked` is redundant on a native checkbox/radio (the role's
+ *   checked state is already exposed natively), but when an author sets
+ *   it explicitly it should agree with the element's actual state —
+ *   otherwise assistive technology is told something different from what
+ *   a sighted user perceives. This is the same static/live-DOM check
+ *   a widely-used reference engine's own `aria-conditional-attr` rule
+ *   performs (verified directly against its `ariaConditionalCheckboxAttr`/
+ *   `ariaConditionalRadioAttr` source).
+ * @implementation-notes
+ * - Deliberately authored as `type: 'manual'` (cantTell-capped, never
+ *   fail), unlike most ARIA-validity rules in this file family. That
+ *   reference engine runs as a script injected into the LIVE, already-hydrated DOM, so a
+ *   mismatch it reports is a genuine, current-state fact. This engine
+ *   analyzes STATIC markup only (no script execution) — `.checked`
+ *   reliably reflects the static `checked` attribute for freshly-parsed
+ *   markup (verified directly against jsdom), but a very common, entirely
+ *   legitimate real-world pattern is a JS-hydrated widget whose
+ *   server-rendered HTML intentionally ships `aria-checked="true"` (or
+ *   `"mixed"`) BEFORE client JS sets the native `checked`/`indeterminate`
+ *   property to match on hydration. A hard `fail` here would misfire on
+ *   that pattern constantly — real risk given how common it is in exactly
+ *   the kind of JS-framework-heavy pages this engine's own real-world
+ *   corpus is full of. Flagging for human review (cantTell) captures the
+ *   same signal without the false-positive risk of asserting it as a
+ *   confirmed violation.
+ * - `aria-checked="mixed"` is only meaningful for checkboxes (radio
+ *   buttons have no indeterminate state) — matches that reference engine's
+ *   own `normalizeAriaChecked` (radio) vs `normalizeAriaChecked2` (checkbox)
+ *   split, verified directly against its source.
+ * - Any `aria-checked` value other than "true"/"false"/"mixed" (checkbox)
+ *   or "true"/"false" (radio) is treated as equivalent to "false" — also
+ *   matches that reference engine's own normalization exactly.
+ * - Not gated on isAccTreeEligible: whether the accessible state matches
+ *   is a markup-correctness property independent of current visibility.
+ */
+
+const id = 'aria-checked-state-mismatch';
+
+const meta = {
+  title: 'Native checkbox/radio aria-checked should match its actual state',
+  description: 'Flags a native <input type="checkbox">/<input type="radio"> whose explicit aria-checked value disagrees with its actual checked/indeterminate state, for manual review.',
+  i18n: {
+    titleKey: 'ariaCheckedStateMismatch_title',
+    descriptionKey: 'ariaCheckedStateMismatch_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'forms', 'atomic', 'manual'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '4.1.2': ['aria-checked-state-mismatch'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]', safeRoot)
+    : helpers.queryAll('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const type = trim(el.getAttribute('type')).toLowerCase();
+    const isCheckbox = type === 'checkbox';
+    const isRadio = type === 'radio';
+    if (!isCheckbox && !isRadio) continue;
+
+    const rawAriaChecked = trim(el.getAttribute('aria-checked')).toLowerCase();
+    if (!rawAriaChecked) continue;
+
+    applicableCount += 1;
+
+    let normalizedAriaChecked;
+    if (isCheckbox) {
+      normalizedAriaChecked = (rawAriaChecked === 'mixed' || rawAriaChecked === 'true') ? rawAriaChecked : 'false';
+    } else {
+      normalizedAriaChecked = (rawAriaChecked === 'true') ? 'true' : 'false';
+    }
+
+    let actualState;
+    if (isCheckbox && el.indeterminate) {
+      actualState = 'mixed';
+    } else {
+      actualState = el.checked ? 'true' : 'false';
+    }
+
+    if (normalizedAriaChecked === actualState) 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 element’s aria-checked value does not match its actual checked/indeterminate state.',
+      hint: 'Set aria-checked to match the element’s real state, or remove it — a native checkbox/radio already exposes this state without it.',
+      i18n: {
+        summaryKey: 'ariaCheckedStateMismatch_summary_cantTell',
+        hintKey: 'ariaCheckedStateMismatch_hint_cantTell',
+        params: { ariaChecked: normalizedAriaChecked, actualState, type }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_CHECKED_STATE_MISMATCH', ariaChecked: normalizedAriaChecked, actualState, type }
+      }
+    });
+  }
+
+  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 };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };