@surea11y/core 1.0.0

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

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * @check img-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 = "img-alt-decorative";
+
+const meta = {
+  title: "<img> with alt=\"\" must be decorative (manual review)",
+  description: "Flags <img> elements with empty alt for human review that they are purely decorative.",
+  i18n: {
+    titleKey: "img_altDecorative_title",
+    descriptionKey: "img_altDecorative_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "nontext", "images", "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 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 = (() => {
+        // Only likely candidates:
+        // - alt="" (exact)
+        // - alt that starts/ends with space (to catch whitespace-only like "   ")
+        const sel = 'img[alt=""], img[alt^=" "], img[alt$=" "]';
+        try { return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []); }
+        catch { return queryAll(sel); }
+    })();
+    const uniqueEls = [];
+    const seen = new Set();
+    for (const el of els) {
+        if (!seen.has(el)) { seen.add(el); uniqueEls.push(el); }
+    }
+
+    if (!els.length) {
+        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of uniqueEls) {
+        if (!el || !el.getAttribute) 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)
+        const rawAlt = el.getAttribute('alt');
+        if (rawAlt == null) continue;
+        if (String(rawAlt).trim() !== '') continue;
+
+        applicableCount += 1;
+
+        const baseOccurrence = {
+            summary: 'Review whether <img> is decorative (alt="").',
+            hint: 'Confirm the image is purely decorative. If it conveys information or function, provide meaningful alt text.',
+            i18n: {
+                summaryKey: 'img_altDecorative_summary_cantTell',
+                hintKey: 'img_altDecorative_hint_cantTell',
+                params: { element: 'img' }
+            },
+            data: {
+                visibilityFilter: { 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/img-alt-quality-manual.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * @check img-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 = "img-alt-quality";
+
+const meta = {
+  title: "<img> alt text must be appropriate (manual review)",
+  description: "Flags <img> elements with non-empty alt text for human review of appropriateness.",
+  i18n: {
+    titleKey: "img_altQuality_title",
+    descriptionKey: "img_altQuality_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "nontext", "images", "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;
+
+    // Cap occurrences to keep manual “quality” checks fast on large pages.
+    // Deterministic: we keep DOM order, just stop collecting after N.
+    const MAX_OCCURRENCES = 50;
+
+    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 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 selector = 'img[alt]:not([alt=""])';
+    const els = (() => {
+        try { return Array.from((queryAllSmart ? queryAllSmart(selector) : queryAll(selector)) || []); }
+        catch { return queryAll(selector); }
+    })();
+
+    if (!els.length) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'notApplicable',
+            severity: 'minor',
+            occurrences: [],
+            data: { details: { applicableCount: 0, reportedCount: 0, maxOccurrences: MAX_OCCURRENCES, truncated: false } }
+        };
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;  // total applicable elements
+    let collectedCount = 0;   // how many occurrences we actually reported
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) 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: non-empty alt
+        const alt = (() => {
+            try { return String(el.getAttribute('alt') || '').trim(); } catch { return ''; }
+        })();
+        if (!alt) continue;
+
+        applicableCount += 1;
+
+        // IMPORTANT: stop doing expensive occurrence building after we hit the cap
+        if (collectedCount >= MAX_OCCURRENCES) continue;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+        const baseOccurrence = {
+            summary: 'Review alt text on <img> for accuracy and appropriateness.',
+            hint: 'Ensure the alt text conveys the image’s purpose/information in context (not redundant, not filename-like).',
+            i18n: {
+                summaryKey: 'img_altQuality_summary_cantTell',
+                hintKey: 'img_altQuality_hint_cantTell',
+                params: { element: 'img' }
+            },
+            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 });
+        }
+
+        collectedCount += 1;
+    }
+
+    if (applicableCount === 0) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'notApplicable',
+            severity: 'minor',
+            occurrences: [],
+            data: { details: { applicableCount: 0, reportedCount: 0, maxOccurrences: MAX_OCCURRENCES, truncated: false } }
+        };
+    }
+
+    const truncated = applicableCount > collectedCount;
+
+    return {
+        ruleId: rule.ruleId,
+        outcome: 'cantTell',
+        severity: 'minor',
+        occurrences,
+        data: {
+            details: {
+                applicableCount,
+                reportedCount: collectedCount,
+                maxOccurrences: MAX_OCCURRENCES,
+                truncated
+            }
+        }
+    };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/input-image-alt-decorative-manual.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * @check input-image-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 = "input-image-alt-decorative";
+
+const meta = {
+  title: "<input type=\"image\"> with alt=\"\" must be appropriate (manual review)",
+  description: "Flags <input type=\"image\"> elements with empty alt for human review (usually not appropriate for functional controls).",
+  i18n: {
+    titleKey: "inputImage_altDecorative_title",
+    descriptionKey: "inputImage_altDecorative_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "forms", "images", "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 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('input[type="image"]') : queryAll('input[type="image"]')) || []); }
+        catch { return queryAll('input[type="image"]'); }
+    })();
+
+    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 = (() => {
+                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)
+        if (!((el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() === ''))) continue;
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const baseOccurrence = {
+            summary: 'Review <input type="image"> with alt="".',
+            hint: 'This control is typically functional. Confirm it has an equivalent accessible name elsewhere, or provide meaningful alt text.',
+            i18n: {
+                summaryKey: 'inputImage_altDecorative_summary_cantTell',
+                hintKey: 'inputImage_altDecorative_hint_cantTell',
+                params: { element: 'input[type=image]' }
+            },
+            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/input-image-alt-quality-manual.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * @check input-image-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 = "input-image-alt-quality";
+
+const meta = {
+  title: "<input type=\"image\"> alt text must be appropriate (manual review)",
+  description: "Flags <input type=\"image\"> elements with non-empty alt text for human review of appropriateness.",
+  i18n: {
+    titleKey: "inputImage_altQuality_title",
+    descriptionKey: "inputImage_altQuality_description"
+  },
+  helpUrl: null,
+  tags: ["wcag2a", "wcag111", "forms", "images", "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 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('input[type="image"]') : queryAll('input[type="image"]')) || []); }
+        catch { return queryAll('input[type="image"]'); }
+    })();
+
+    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 = (() => {
+                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)
+        if (!((el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() !== ''))) continue;
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const baseOccurrence = {
+            summary: 'Review alt text on <input type="image"> for accuracy and appropriateness.',
+            hint: 'Ensure the alt text describes the control’s action (e.g., “Search”, “Submit order”) in context.',
+            i18n: {
+                summaryKey: 'inputImage_altQuality_summary_cantTell',
+                hintKey: 'inputImage_altQuality_hint_cantTell',
+                params: { element: 'input[type=image]' }
+            },
+            data: {
+                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details: { alt: String(el.getAttribute('alt') || '') } // optional but useful
+            }
+        };
+
+        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 };