@surea11y/core 1.7.0 → 1.8.1

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

@@ -12,7 +12,16 @@
  *   Applies to <canvas> elements included in the accessibility tree.
  *   Hidden elements are excluded whether or not they are focusable.
  * @expectation
- *   Each applicable <canvas> provides a text alternative via fallback content or an accessible name.
+ *   Each applicable <canvas> provides a text alternative via fallback content
+ *   or an accessible name, with two exceptions:
+ *   - role="img" (first role token) makes the canvas's children
+ *     presentational and its name comes from the author only, so fallback
+ *     content does not count: aria-labelledby, aria-label or title must name
+ *     it.
+ *   - role="none"/"presentation" marks the canvas decorative, and it passes.
+ *     The role is ignored (presentational role conflict) when the canvas is
+ *     focusable or carries aria-label/aria-labelledby, and the canvas is then
+ *     judged like any other.
  */
 
 const id = 'canvas-text-alternative-present';
@@ -85,6 +94,64 @@ function runInPage(ctx) {
       ? helpers.getTextAlternativeInfo
       : null;
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  function attrText(el, name) {
+    try {
+      const v = el.getAttribute(name);
+      return v == null ? '' : String(v).trim();
+    } catch {
+      return '';
+    }
+  }
+
+  function firstRoleToken(el) {
+    const raw = attrText(el, 'role').toLowerCase();
+    return raw ? raw.split(/\s+/)[0] : '';
+  }
+
+  // ARIA's presentational role conflict: a focusable element, or one with a
+  // global naming attribute, keeps its native role.
+  function isPresentationHonoured(el) {
+    if (attrText(el, 'aria-label') || attrText(el, 'aria-labelledby')) return false;
+    if (getFocusableInfo) {
+      try {
+        const fi = getFocusableInfo(el, ctx);
+        if (fi && fi.focusable) return false;
+      } catch {}
+    } else if (attrText(el, 'tabindex') !== '') {
+      return false;
+    }
+    return true;
+  }
+
+  // role="img": the name comes from the author (aria-labelledby, aria-label,
+  // then title), never from the children.
+  function getRoleImgNameInfo(el) {
+    let aria = null;
+    if (getAriaNameInfo) {
+      try {
+        aria = getAriaNameInfo(el, ctx);
+      } catch {
+        aria = null;
+      }
+    }
+    if (aria && aria.present && aria.value) {
+      return { present: true, value: aria.value, mechanism: aria.mechanism };
+    }
+    if (!getAriaNameInfo) {
+      const label = attrText(el, 'aria-label');
+      if (label) return { present: true, value: label, mechanism: 'aria-label' };
+    }
+    const title = attrText(el, 'title');
+    if (title) return { present: true, value: title, mechanism: 'title' };
+    return { present: false, value: '', mechanism: 'none' };
+  }
+
   const canvases = (() => {
     try {
       return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []);
@@ -118,16 +185,25 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
+    const role = firstRoleToken(el);
+
+    // A decorative canvas needs no text alternative.
+    if ((role === 'none' || role === 'presentation') && isPresentationHonoured(el)) continue;
+
+    const isRoleImg = role === 'img';
+
     // Expectation: must provide a text alternative.
-    const ti = getTextAlternativeInfo
-      ? (() => {
-          try {
-            return getTextAlternativeInfo(el, ctx);
-          } catch {
-            return null;
-          }
-        })()
-      : null;
+    const ti = isRoleImg
+      ? getRoleImgNameInfo(el)
+      : getTextAlternativeInfo
+        ? (() => {
+            try {
+              return getTextAlternativeInfo(el, ctx);
+            } catch {
+              return null;
+            }
+          })()
+        : null;
 
     const hasTextAlt = !!(ti && ti.present);
 
@@ -135,14 +211,29 @@ function runInPage(ctx) {
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
+    const messages = isRoleImg
+      ? {
+          summary:
+            'This <canvas role="img"> has no accessible name; with role="img" its fallback content does not count.',
+          hint: 'Name it with aria-label or aria-labelledby, or remove role="img" so that its fallback content can serve as the text alternative.',
+          summaryKey: 'canvas_textAltPresent_summary_fail_roleImg',
+          hintKey: 'canvas_textAltPresent_hint_fail_roleImg'
+        }
+      : {
+          summary: 'Missing text alternative for <canvas>.',
+          hint: 'Provide fallback text inside <canvas> or an accessible name (e.g., aria-label/aria-labelledby).',
+          summaryKey: 'canvas_textAltPresent_summary_fail',
+          hintKey: 'canvas_textAltPresent_hint_fail'
+        };
+
     const baseOccurrence = {
       selector: '',
       html: '',
-      summary: 'Missing text alternative for <canvas>.',
-      hint: 'Provide fallback text inside <canvas> or an accessible name (e.g., aria-label/aria-labelledby).',
+      summary: messages.summary,
+      hint: messages.hint,
       i18n: {
-        summaryKey: 'canvas_textAltPresent_summary_fail',
-        hintKey: 'canvas_textAltPresent_hint_fail',
+        summaryKey: messages.summaryKey,
+        hintKey: messages.hintKey,
         params: { element: 'canvas' }
       },
       data: {

package/src/checks/automatic/combobox-name-present.js

@@ -20,6 +20,9 @@
  *   accepted: text sitting inside a custom combobox widget is not reliably
  *   exposed as its name. On a labelable element (<input role="combobox">) an
  *   associated <label> counts as well.
+ *   On a text-like <input> or a <textarea>, the placeholder counts last
+ *   (HTML-AAM's final name source): a placeholder-only label is a 3.3.2
+ *   question, not a missing name.
  */
 
 const id = 'combobox-name-present';
@@ -70,21 +73,6 @@ function runInPage(ctx) {
     }
   }
 
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
-  }
-
   function getConservativeSubtreeText(document, container) {
     // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
@@ -172,45 +160,30 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  // Precompute label[for] map for combobox elements that are labelable
-  // native form controls (e.g. <input role="combobox">).
-  const labelForMap = buildLabelForMap(document);
-
+  // Delegates to the shared, spec-guarded lookup (dom-helpers.js's
+  // getAssociatedLabelElements): a <label> -- wrapping or via `for` --
+  // only ever associates with a genuinely labelable element, so this
+  // correctly returns nothing for role-only widgets a <label> merely sits
+  // next to, and the real thing for a labelable element like
+  // <input role="combobox">.
   function getNativeLabelText(el) {
+    if (!helpers || typeof helpers.getAssociatedLabelElements !== 'function') return '';
+    let labels;
     try {
-      if ('labels' in el && el.labels && el.labels.length) {
-        const parts = [];
-        const max = Math.min(4, el.labels.length);
-        for (let i = 0; i < max; i += 1) {
-          const lab = el.labels[i];
-          const t = lab ? getLabelText(lab) : '';
-          if (t) parts.push(t);
-        }
-        const joined = normalizeWs(parts.join(' '));
-        if (joined) return joined;
-      }
-    } catch {}
-    try {
-      if (el.closest) {
-        const wrap = el.closest('label');
-        if (wrap) {
-          const t = getLabelText(wrap);
-          if (t) return t;
-        }
-      }
-    } catch {}
-    try {
-      const idAttr = getAttr(el, 'id');
-      if (idAttr && labelForMap.has(idAttr)) {
-        const lab = labelForMap.get(idAttr);
-        const t = lab ? getLabelText(lab) : '';
-        if (t) return t;
-      }
-    } catch {}
-    return '';
+      labels = helpers.getAssociatedLabelElements(el) || [];
+    } catch {
+      labels = [];
+    }
+    const parts = [];
+    const max = Math.min(4, labels.length);
+    for (let i = 0; i < max; i += 1) {
+      const t = getLabelText(labels[i]);
+      if (t) parts.push(t);
+    }
+    return normalizeWs(parts.join(' '));
   }
 
-  function evaluate(el, controlType) {
+  function evaluate(el) {
     const ariaLabel = getAttr(el, 'aria-label');
     if (ariaLabel) return { ok: true, method: 'aria-label' };
 
@@ -224,6 +197,16 @@ function runInPage(ctx) {
     const lab = getNativeLabelText(el);
     if (lab) return { ok: true, method: 'label' };
 
+    // HTML-AAM's last name source for a text-like <input> or a <textarea>,
+    // after title: the placeholder. A placeholder-only label is a 3.3.2
+    // question, not a missing name.
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx, { placeholder: true });
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
+    }
+
     // role="combobox" is name-from-author-only per WAI-ARIA: it must NOT
     // fall back to subtree content. Visible text near/inside a custom
     // combobox widget is not reliably exposed as its accessible name.
@@ -239,7 +222,7 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const res = evaluate(el, 'combobox');
+    const res = evaluate(el);
     if (res.ok) continue;
 
     const eligInfo = getEligibilityInfo

package/src/checks/automatic/contrast-computable.js

@@ -115,6 +115,25 @@ function runInPage(ctx) {
 
   const seenFailEls = new Set();
 
+  // Defined inside runInPage, which is serialized into the page and cannot
+  // reach module scope. English fallbacks for the dictionary keys below.
+  const CANT_TELL_HINT_KEYS = {
+    background: 'contrastComputable_hint_cantTell_background',
+    effect: 'contrastComputable_hint_cantTell_effect',
+    rootNotOpaque: 'contrastComputable_hint_cantTell_rootNotOpaque',
+    generic: 'contrast_hint_cantTell_manual'
+  };
+  const CANT_TELL_HINTS = {
+    background:
+      'Measure the contrast by hand on the rendered page, where the background behind the text gives the least contrast. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).',
+    effect:
+      'Measure the contrast by hand on the rendered page with the effect applied, since the declared CSS colors are not what ends up on screen. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).',
+    rootNotOpaque:
+      'No element behind this text, up to the root, has a fully opaque background, so the color it sits on depends on where the page is displayed. Set an opaque background color on html or body, or measure the contrast against the background the page is actually shown on.',
+    generic:
+      "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA)."
+  };
+
   function pushCantTellOccurrence(el, reasonCode, extraDetails) {
     try {
       if (!el || seenFailEls.has(el)) return;
@@ -151,6 +170,18 @@ function runInPage(ctx) {
         summaryKey = 'contrastComputable_cantTell_rootNotOpaque';
       else if (rc === 'TEXT_SHADOW') summaryKey = 'contrastComputable_cantTell_textShadow';
 
+      // Every cantTell leaves a person to measure the contrast, so each one
+      // says how, grouped by what blocked the calculation.
+      let hintKind = 'generic';
+      if (rc === 'BACKGROUND_IMAGE_OR_GRADIENT') hintKind = 'background';
+      else if (
+        rc === 'MIX_BLEND_MODE' ||
+        rc === 'BACKGROUND_FILTER_OR_BACKDROP_FILTER' ||
+        rc === 'TEXT_SHADOW'
+      )
+        hintKind = 'effect';
+      else if (rc === 'BACKGROUND_NOT_OPAQUE_AT_ROOT') hintKind = 'rootNotOpaque';
+
       const details = Object.assign(
         { reasonCode: rc },
         extraDetails && typeof extraDetails === 'object' ? extraDetails : {}
@@ -160,10 +191,10 @@ function runInPage(ctx) {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: CANT_TELL_HINTS[hintKind],
         i18n: {
           summaryKey,
-          hintKey: '',
+          hintKey: CANT_TELL_HINT_KEYS[hintKind],
           params: Object.assign(
             { reasonCode: rc },
             details && typeof details === 'object'
@@ -374,11 +405,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: CANT_TELL_HINTS.generic,
             html: '',
             i18n: {
               summaryKey: 'contrastComputable_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: CANT_TELL_HINT_KEYS.generic,
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }

package/src/checks/automatic/contrast-enhanced.js

@@ -231,10 +231,10 @@ function runInPage(ctx) {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: `Change the text color, the background color, or both, so the contrast ratio reaches at least ${params && params.threshold}:1.`,
         i18n: {
           summaryKey: 'contrastEnhanced_fail_belowThreshold',
-          hintKey: '',
+          hintKey: 'contrastEnhanced_hint_fail',
           params: params && typeof params === 'object' ? params : {}
         },
         ...(uncertainty ? { uncertainty } : {}),
@@ -498,11 +498,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).",
             html: '',
             i18n: {
               summaryKey: 'contrastEnhanced_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: 'contrast_hint_cantTell_manual',
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }

package/src/checks/automatic/contrast-minimum.js

@@ -20,6 +20,10 @@
  *   size: 3:1 for large text, 4.5:1 for everything else. Text is large at
  *   24px or more, or at 14pt (about 18.667px) or more when the computed font
  *   weight is 700 or higher.
+ * @implementation-notes
+ * - Its thresholds are settings (`settings` below), so another standard's
+ *   contrast requirement is a variant of this rule rather than a copy
+ *   (docs/RULE_AUTHORING.md, "Rule variants"). Without settings it is WCAG's.
  */
 
 const id = 'contrast-minimum';
@@ -65,6 +69,21 @@ function runInPage(ctx) {
     }
   }
 
+  // Thresholds (see `settings` below): WCAG 1.4.3's by default. A variant of
+  // this rule, another standard's contrast requirement, passes its own in
+  // ctx.config (docs/RULE_AUTHORING.md, "Rule variants").
+  const cfg = ctx.config && typeof ctx.config === 'object' ? ctx.config : {};
+  const setting = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+  const BOLD_LARGE_MIN_PX = setting(cfg.boldLargeMinPx, null);
+  const LARGE_TEXT_RATIO = setting(cfg.largeTextRatio, 3);
+  const NORMAL_TEXT_RATIO = setting(cfg.normalTextRatio, 4.5);
+  // The font and analysis caches hold verdicts that depend on those
+  // thresholds, so other thresholds get caches of their own.
+  const SETTINGS_KEY =
+    BOLD_LARGE_MIN_PX === null && LARGE_TEXT_RATIO === 3 && NORMAL_TEXT_RATIO === 4.5
+      ? ''
+      : '|' + [BOLD_LARGE_MIN_PX, LARGE_TEXT_RATIO, NORMAL_TEXT_RATIO].join('|');
+
   const __contrastSharedCache =
     helpers && helpers.contrast && helpers.contrast.sharedCache
       ? helpers.contrast.sharedCache
@@ -82,8 +101,9 @@ function runInPage(ctx) {
     ? __contrastSharedCache.__elFgCache || (__contrastSharedCache.__elFgCache = new WeakMap())
     : null;
 
+  const FONT_CACHE = '__elFontCache' + SETTINGS_KEY;
   const __elFontCache = __contrastSharedCache
-    ? __contrastSharedCache.__elFontCache || (__contrastSharedCache.__elFontCache = new WeakMap())
+    ? __contrastSharedCache[FONT_CACHE] || (__contrastSharedCache[FONT_CACHE] = new WeakMap())
     : new WeakMap();
 
   function safeComputedStyle(el) {
@@ -124,7 +144,10 @@ function runInPage(ctx) {
 
       const sizePx = Number.isFinite(fontSizePx) ? fontSizePx : 0;
       const isBold = Number.isFinite(fontWeightNum) && fontWeightNum >= 700;
-      const isLarge = helpers.contrast.isLargeText(sizePx, fontWeightNum);
+      const isLarge =
+        BOLD_LARGE_MIN_PX === null
+          ? helpers.contrast.isLargeText(sizePx, fontWeightNum)
+          : helpers.contrast.isLargeText(sizePx, fontWeightNum, BOLD_LARGE_MIN_PX);
 
       const out = {
         fontSizePx: sizePx,
@@ -228,10 +251,10 @@ function runInPage(ctx) {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: `Change the text color, the background color, or both, so the contrast ratio reaches at least ${params && params.threshold}:1.`,
         i18n: {
           summaryKey: 'contrastMinimum_fail_belowThreshold',
-          hintKey: '',
+          hintKey: 'contrastMinimum_hint_fail',
           params: params && typeof params === 'object' ? params : {}
         },
         ...(uncertainty ? { uncertainty } : {}),
@@ -278,9 +301,10 @@ function runInPage(ctx) {
   let __elAnalysisCache = new WeakMap();
   if (__contrastSharedCache) {
     try {
-      if (!__contrastSharedCache.__elAnalysisCacheAA)
-        __contrastSharedCache.__elAnalysisCacheAA = new WeakMap();
-      __elAnalysisCache = __contrastSharedCache.__elAnalysisCacheAA;
+      const ANALYSIS_CACHE = '__elAnalysisCacheAA' + SETTINGS_KEY;
+      if (!__contrastSharedCache[ANALYSIS_CACHE])
+        __contrastSharedCache[ANALYSIS_CACHE] = new WeakMap();
+      __elAnalysisCache = __contrastSharedCache[ANALYSIS_CACHE];
     } catch {
       __elAnalysisCache = new WeakMap();
     }
@@ -372,7 +396,12 @@ function runInPage(ctx) {
               const ratio = helpers.contrast.contrastRatio(fgOpaque, bgOpaque);
 
               const font = getFontInfo(el);
-              const threshold = helpers.contrast.requiredRatio('AA', font.isLargeText);
+              const threshold =
+                SETTINGS_KEY === ''
+                  ? helpers.contrast.requiredRatio('AA', font.isLargeText)
+                  : font.isLargeText
+                    ? LARGE_TEXT_RATIO
+                    : NORMAL_TEXT_RATIO;
 
               analysis = {
                 computable: true,
@@ -491,11 +520,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).",
             html: '',
             i18n: {
               summaryKey: 'contrastMinimum_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: 'contrast_hint_cantTell_manual',
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }
@@ -564,4 +593,9 @@ function runInPage(ctx) {
   };
 }
 
-module.exports = { id, meta, runInPage };
+// The thresholds a variant may change (docs/RULE_AUTHORING.md, "Rule
+// variants"), with WCAG 1.4.3's as defaults: the size from which bold text is
+// large (null: WCAG's 14pt), and the ratios large and other text need.
+const settings = { boldLargeMinPx: null, largeTextRatio: 3, normalTextRatio: 4.5 };
+
+module.exports = { id, meta, runInPage, settings };