@surea11y/core 1.0.0

package/src/checks/automatic/svg-image-text-alternative-present.js

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * @check svg-image-text-alternative-present
+ * @atomic true
+ * @summary Accessible SVG <image> elements must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to SVG <image> elements that are exposed to assistive technologies.
+ *   Elements otherwise hidden from the accessibility tree remain applicable
+ *   if they are tabbable or referenced by IDREF relationships (per engine eligibility checks).
+ *   SVG <image> elements with role="presentation" or role="none" are excluded only when they are not focusable.
+ * @expectation
+ *   Each applicable SVG <image> element has a text alternative via:
+ *   - a non-empty direct <title> child, OR
+ *   - a non-empty direct <desc> child, OR
+ *   - an accessible name (aria-label / aria-labelledby / title attribute).
+ */
+
+const id = 'svg-image-text-alternative-present';
+
+const meta = {
+  title: 'SVG <image> must have a text alternative',
+  description: 'Checks that SVG <image> elements provide a text alternative via <title>/<desc> or an ARIA accessible name.',
+  i18n: {
+    titleKey: 'svgImage_textAltPresent_title',
+    descriptionKey: 'svgImage_textAltPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'svg', 'image', 'atomic', 'automatic'],
+  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: 'medium',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['svg-image-text-alt-present']
+    }
+  }
+};
+
+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 isFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
+    ? helpers.getFocusableInfo
+    : null;
+
+  const getAccessibleNameInfo = helpers && typeof helpers.getAccessibleNameInfo === 'function'
+    ? helpers.getAccessibleNameInfo
+    : null;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  // Per SVG accessible-name conventions, only a <title> that is literally
+  // the first child element is used by assistive technologies as the
+  // element's accessible name; a <title> appearing later among the
+  // children is commonly ignored by AT even though it's still a valid DOM
+  // child.
+  function firstChildTitleText(el) {
+    try {
+      if (!el) return '';
+      const first = el.firstElementChild;
+      const tn = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+      if (tn === 'title') {
+        const t = trim(first.textContent);
+        if (t) return t;
+      }
+    } catch {}
+    return '';
+  }
+
+  // <desc> counts when it is the first child, or the second child
+  // immediately following a <title> — the standard <title>+<desc> pairing.
+  // A <desc> appearing later than that is not reliably read by AT.
+  function descText(el) {
+    try {
+      if (!el) return '';
+      const first = el.firstElementChild;
+      const firstTag = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+      if (firstTag === 'desc') {
+        const t = trim(first.textContent);
+        if (t) return t;
+      } else if (firstTag === 'title' && first.nextElementSibling) {
+        const second = first.nextElementSibling;
+        const secondTag = (second.localName || second.tagName || '').toLowerCase();
+        if (secondTag === 'desc') {
+          const t = trim(second.textContent);
+          if (t) return t;
+        }
+      }
+    } catch {}
+    return '';
+  }
+
+  const rawImages = (() => {
+    try { return Array.from((queryAllSmart ? queryAllSmart('image') : queryAll('image')) || []); }
+    catch { return queryAll('svg image'); }
+  })();
+
+  const images = rawImages.filter((el) => {
+    try { return el && (el.namespaceURI === 'http://www.w3.org/2000/svg') && (String(el.localName).toLowerCase() === 'image'); }
+    catch { return false; }
+  });
+
+  if (!images.length) return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of images) {
+    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;
+    }
+
+    const role = trim(el.getAttribute('role')).toLowerCase();
+    if (role === 'presentation' || role === 'none') {
+      let focusable = false;
+      if (isFocusableInfo) {
+        const fi = (() => { try { return isFocusableInfo(el, ctx); } catch { return null; } })();
+        focusable = !!(fi && fi.focusable);
+      } else {
+        const tabindex = el.getAttribute('tabindex');
+        focusable = tabindex != null && trim(tabindex) !== '' && !Number.isNaN(Number(trim(tabindex)));
+      }
+      if (!focusable) continue;
+    }
+
+    applicableCount += 1;
+
+    const titleText = firstChildTitleText(el);
+    if (titleText) continue;
+
+    const desc = descText(el);
+    if (desc) continue;
+
+    // Only now check “accessible name” (but scoped to allowed mechanisms)
+    const ariaLabelRaw = (() => { try { return el.getAttribute('aria-label'); } catch { return null; } })();
+    const ariaLabelledbyRaw = (() => { try { return el.getAttribute('aria-labelledby'); } catch { return null; } })();
+    const titleAttrRaw = (() => { try { return el.getAttribute('title'); } catch { return null; } })();
+
+    const ariaLabel = trim(ariaLabelRaw);
+    const ariaLabelledby = trim(ariaLabelledbyRaw);
+    const titleAttr = trim(titleAttrRaw);
+
+    const hasMechanism =
+        (ariaLabelRaw !== null && ariaLabel.length > 0) ||
+        (ariaLabelledbyRaw !== null && ariaLabelledby.length > 0) ||
+        (titleAttrRaw !== null && titleAttr.length > 0);
+
+    let nameInfo = null;
+    let hasName = false;
+
+    if (hasMechanism) {
+      if (getAccessibleNameInfo) {
+        nameInfo = (() => { try { return getAccessibleNameInfo(el, ctx); } catch { return null; } })();
+        hasName = !!(nameInfo && nameInfo.present && trim(nameInfo.value));
+      } else {
+        // Without helper, accept presence of non-empty allowed attributes
+        hasName = true;
+      }
+    }
+
+    if (hasName) continue;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Missing text alternative on SVG <image>.',
+      hint: 'Add a <title> (and optionally <desc>) inside <image>, or provide aria-label/aria-labelledby.',
+      i18n: {
+        summaryKey: 'svgImage_textAltPresent_summary_fail',
+        hintKey: 'svgImage_textAltPresent_hint_fail',
+        params: { element: 'image' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    };
+
+    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: [] };
+  if (!occurrences.length) return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/svg-text-alternative-present.js

@@ -0,0 +1,298 @@
+'use strict';
+
+/**
+ * @check svg-text-alternative-present
+ * @atomic true
+ * @summary Accessible <svg> elements must provide a text alternative
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to inline <svg> elements that are exposed to assistive technologies AND appear intended to be conveyed.
+ *   "Intended to be conveyed" is approximated deterministically by at least one of:
+ *     - role="img"
+ *     - aria-label / aria-labelledby present
+ *     - <title> or <desc> present (desc alone is an applicability signal only — see @expectation)
+ *     - focusable/tabbable (e.g., tabindex, native focusability)
+ *
+ *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
+ *   Elements otherwise hidden from the accessibility tree remain applicable
+ *   if they are tabbable-focusable or referenced by IDREF relationships (per engine eligibility checks).
+ * @expectation
+ *   Each applicable <svg> element provides a text alternative via:
+ *     - non-empty <title> text, OR
+ *     - an ARIA name (aria-label / aria-labelledby).
+ *   A <desc> element alone does NOT satisfy this — per the SVG Accessibility
+ *   API Mappings spec §7.1, <desc> only ever contributes to the accessible
+ *   DESCRIPTION, never the accessible NAME (verified 2026-07-20 directly
+ *   against the SVG-AAM spec text, not assumed). An <svg> with only a
+ *   <desc> and no <title>/ARIA name is still "applicable" (desc signals
+ *   authorial intent) but fails, matching a widely-used reference engine's svg-img-alt.
+ */
+
+const id = 'svg-text-alternative-present';
+
+const meta = {
+    title: '<svg> must provide a text alternative',
+    description: 'Checks that inline <svg> elements provide a text alternative via a <title> element or an ARIA name (a <desc> element alone does not count — it only contributes to the accessible description, not the name).',
+    i18n: {
+        titleKey: 'svg_textAltPresent_title',
+        descriptionKey: 'svg_textAltPresent_description'
+    },
+    helpUrl: null,
+    tags: ['wcag2a', 'wcag111', 'svg', 'nontext', 'images', 'atomic', 'automatic'],
+    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': ['svg-text-alternative-present']
+        }
+    }
+};
+
+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;
+
+    const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
+        ? helpers.getAriaNameInfo
+        : null;
+
+    function trim(v) {
+        try {
+            return (v == null ? '' : String(v)).trim();
+        } catch {
+            return '';
+        }
+    }
+
+    // Per SVG accessible-name conventions, only a <title> that is literally
+    // the first child element is used by assistive technologies as the
+    // SVG's accessible name; a <title> appearing later among the children
+    // is commonly ignored by AT even though it's still a valid DOM child.
+    function nonEmptyFirstChildTitleText(svg) {
+        try {
+            const first = svg.firstElementChild;
+            const tn = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+            if (tn === 'title') {
+                const txt = trim(first.textContent);
+                if (txt) return txt;
+            }
+        } catch {
+        }
+        return '';
+    }
+
+    // <desc> counts when it is the first child, or the second child
+    // immediately following a <title> — the standard <title>+<desc> pairing
+    // (e.g. <svg><title>...</title><desc>...</desc>...</svg>). A <desc>
+    // appearing later than that is not reliably read by AT.
+    function nonEmptyDescText(svg) {
+        try {
+            const first = svg.firstElementChild;
+            const firstTag = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+            if (firstTag === 'desc') {
+                const txt = trim(first.textContent);
+                if (txt) return txt;
+            } else if (firstTag === 'title' && first.nextElementSibling) {
+                const second = first.nextElementSibling;
+                const secondTag = (second.localName || second.tagName || '').toLowerCase();
+                if (secondTag === 'desc') {
+                    const txt = trim(second.textContent);
+                    if (txt) return txt;
+                }
+            }
+        } catch {
+        }
+        return '';
+    }
+
+    function isFocusable(svg) {
+        if (getFocusableInfo) {
+            const fi = (() => {
+                try {
+                    return getFocusableInfo(svg, ctx);
+                } catch {
+                    return null;
+                }
+            })();
+            return !!(fi && fi.focusable);
+        }
+        // deterministic fallback: tabindex presence/valid number
+        try {
+            const tabindex = svg && svg.getAttribute ? svg.getAttribute('tabindex') : null;
+            return tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
+        } catch {
+            return false;
+        }
+    }
+
+    const svgs = (() => {
+        try {
+            return Array.from((queryAllSmart ? queryAllSmart('svg') : queryAll('svg')) || []);
+        } catch {
+            return queryAll('svg');
+        }
+    })();
+
+    if (!svgs.length) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of svgs) {
+        if (!el || !el.getAttribute) continue;
+
+        // Applicability step 1: only acc-tree eligible nodes (with helper exceptions)
+        if (isAccTreeEligible) {
+            const elig = (() => {
+                try {
+                    return isAccTreeEligible(el, ctx);
+                } catch {
+                    return {eligible: true, reasons: []};
+                }
+            })();
+            if (elig && elig.eligible === false) continue;
+        }
+
+        // Applicability step 2: role (presentation/none) exclusion only when not focusable
+        const role = (() => {
+            try {
+                return String(el.getAttribute('role') || '').trim().toLowerCase();
+            } catch {
+                return '';
+            }
+        })();
+
+        const focusable = isFocusable(el);
+
+        if (role === 'presentation' || role === 'none') {
+            if (!focusable) continue;
+        }
+
+        // Applicability step 3: intent signal gating (computed once per element)
+        let hasAriaNamingAttr = false;
+        try {
+            hasAriaNamingAttr = (el.getAttribute('aria-label') != null) || (el.getAttribute('aria-labelledby') != null);
+        } catch {
+        }
+
+        const titleText = nonEmptyFirstChildTitleText(el);
+        const descText = titleText ? '' : nonEmptyDescText(el); // avoid second scan if title already passes
+        const hasTitleOrDesc = !!(titleText || descText);
+
+        const hasIntent =
+            role === 'img' ||
+            hasAriaNamingAttr ||
+            hasTitleOrDesc ||
+            focusable;
+
+        if (!hasIntent) continue;
+
+        applicableCount += 1;
+
+        // Expectation: non-empty title/desc OR ARIA name (but only resolve name if attrs exist)
+        let hasAriaName = false;
+        if (hasAriaNamingAttr) {
+            if (getAriaNameInfo) {
+                const info = (() => {
+                    try {
+                        return getAriaNameInfo(el, ctx);
+                    } catch {
+                        return null;
+                    }
+                })();
+                hasAriaName = !!(info && info.present && trim(info.value));
+            } else {
+                // minimal deterministic fallback
+                const ariaLabel = trim((() => {
+                    try {
+                        return el.getAttribute('aria-label');
+                    } catch {
+                        return '';
+                    }
+                })());
+                const ariaLabelledby = trim((() => {
+                    try {
+                        return el.getAttribute('aria-labelledby');
+                    } catch {
+                        return '';
+                    }
+                })());
+                hasAriaName = !!(ariaLabel || ariaLabelledby);
+            }
+        }
+
+        // Per SVG-AAM §7.1: <desc> contributes only to the accessible
+        // DESCRIPTION, never the accessible NAME — so descText does not
+        // count here even though it does count toward applicability above.
+        const ok = !!titleText || hasAriaName;
+        if (ok) continue;
+
+        let eligInfo = null;
+        if (getEligibilityInfo) {
+            try { eligInfo = getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { eligInfo = null; }
+        }
+
+        const baseOccurrence = {
+            summary: 'Missing text alternative for <svg>.',
+            hint: 'Provide a <title> element with text, or an ARIA name (aria-label/aria-labelledby) — a <desc> element alone does not provide an accessible name.',
+            i18n: {
+                summaryKey: 'svg_textAltPresent_summary_fail',
+                hintKey: 'svg_textAltPresent_hint_fail',
+                params: {element: 'svg'}
+            },
+            data: {
+                visibilityFilter: eligInfo || {targetSet: 'acc', accEligible: null, reasons: []}
+            }
+        };
+
+        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: []};
+    }
+
+    if (!occurrences.length) {
+        return {ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: []};
+    }
+
+    return {ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences};
+}
+
+module.exports = {id, meta, runInPage};