@surea11y/core 1.2.0 → 1.4.0

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -11,20 +13,27 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "canvas-text-alternative-quality";
+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.",
+  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"
+    titleKey: 'canvas_textAltQuality_title',
+    descriptionKey: 'canvas_textAltQuality_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag111", "nontext", "canvas", "manual", "atomic"],
+  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' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'minor',
   category: 'perceivable',
@@ -38,133 +47,161 @@ const meta = {
 };
 
 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 { 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 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));
+  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;
+    if (getFocusableInfo) {
+      const fi = (() => {
+        try {
+          return getFocusableInfo(el, ctx);
+        } catch {
+          return null;
         }
-        return !focusable;
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      let tabindex;
+      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 els = (() => {
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []);
+    } catch {
+      return queryAll('canvas');
     }
+  })();
 
-    const occurrences = [];
-    let applicableCount = 0;
+  if (!els.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-    for (const el of els) {
-        if (!el || !el.getAttribute) continue;
+  const occurrences = [];
+  let applicableCount = 0;
 
-        if (isAccTreeEligible) {
-            const elig = accEligibleCached(el);
-            if (elig && elig.eligible === false) continue;
-        }
+  for (const el of els) {
+    if (!el || !el.getAttribute) continue;
 
-        if (isRolePresentationExcluded(el)) continue;
-
-        const getTextAlternativeInfo =
-            helpers && typeof helpers.getTextAlternativeInfo === 'function'
-                ? helpers.getTextAlternativeInfo
-                : null;
+    if (isAccTreeEligible) {
+      const elig = accEligibleCached(el);
+      if (elig && elig.eligible === false) continue;
+    }
 
-        const trim = (v) => (v == null ? '' : String(v)).trim();
+    if (isRolePresentationExcluded(el)) continue;
 
-        // 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 getTextAlternativeInfo =
+      helpers && typeof helpers.getTextAlternativeInfo === 'function'
+        ? helpers.getTextAlternativeInfo
+        : 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
-            }
-        };
+    const trim = (v) => (v == null ? '' : String(v)).trim();
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
-        }
+    // 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;
+      }
     }
 
-    if (applicableCount === 0) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    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 };
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
 }
 
 module.exports = { id, meta, runInPage };