@surea11y/core 1.5.0 → 1.7.0

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

@@ -5,20 +5,34 @@
 /**
  * @check img-alt-decorative
  * @atomic true
- * @summary Manual review: text alternative appropriateness (WCAG 1.1.1)
+ * @summary Manual review: an image/canvas/svg excluded from the accessibility tree must be purely decorative
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to visible <img>, <canvas> or <svg> elements excluded from the
+ *   accessibility tree by any of: an aria-hidden ancestor-or-self, an
+ *   explicit role="none"/"presentation" not overridden by focusability, an
+ *   <img alt=""> (the native decorative marker, same focusability
+ *   override), an unlabeled <svg> whose implicit role is graphics-document
+ *   (no img/graphics-symbol role restatement, aria-name, <title>/<desc>, or
+ *   focusability), or an unlabeled <canvas> with no explicit role at all.
+ *   Per ACT e88epe, an element is skipped entirely when any ancestor
+ *   already has an author-supplied name (aria-label, aria-labelledby,
+ *   title, or an associated <label>), that ancestor's name is what
+ *   matters, not this element's exclusion (the common real case: an
+ *   icon-only button already named via aria-label).
  * @expectation
- *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ *   Human review is required to confirm the excluded element is purely
+ *   decorative and conveys no information a user would otherwise miss.
  */
 
 const id = 'img-alt-decorative';
 
 const meta = {
-  title: '<img> with alt="" must be decorative (manual review)',
+  title: 'Excluded <img>/<canvas>/<svg> must be decorative (manual review)',
   description:
-    'Flags <img> elements with empty alt for human review that they are purely decorative.',
+    'Flags <img>, <canvas> and <svg> elements excluded from the accessibility tree (aria-hidden, role="none"/"presentation", empty alt, or an unlabeled svg/canvas) for human review that they are purely decorative.',
   i18n: {
     titleKey: 'img_altDecorative_title',
     descriptionKey: 'img_altDecorative_description'
@@ -65,56 +79,207 @@ function runInPage(ctx) {
           }
         };
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const isIncludedInAccessibilityTree =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
-  function isRolePresentationExcluded(el) {
-    const role = (() => {
+  const getAccessibleNameInfo =
+    helpers && typeof helpers.getAccessibleNameInfo === 'function'
+      ? helpers.getAccessibleNameInfo
+      : null;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+
+  function trim(v) {
+    try {
+      return (v == null ? '' : String(v)).trim();
+    } catch {
+      return '';
+    }
+  }
+
+  function getExplicitRole(el) {
+    if (ariaHelpers && typeof ariaHelpers.getExplicitRole === 'function') {
       try {
-        return String(el.getAttribute('role') || '')
-          .trim()
-          .toLowerCase();
+        return ariaHelpers.getExplicitRole(el) || '';
       } catch {
         return '';
       }
-    })();
-    if (role !== 'presentation' && role !== 'none') return false;
+    }
+    try {
+      const raw = trim(el.getAttribute('role'));
+      return raw ? raw.split(/\s+/)[0].toLowerCase() : '';
+    } catch {
+      return '';
+    }
+  }
 
-    // Exclude only when NOT focusable (mirrors img-alt-present policy)
-    let focusable;
+  function isFocusable(el) {
     if (getFocusableInfo) {
-      const fi = (() => {
-        try {
-          return getFocusableInfo(el, ctx);
-        } catch {
-          return null;
-        }
-      })();
-      focusable = !!(fi && fi.focusable);
-    } else {
+      try {
+        const fi = getFocusableInfo(el, ctx);
+        return !!(fi && fi.focusable);
+      } catch {
+        return false;
+      }
+    }
+    try {
       const tabindex = el.getAttribute('tabindex');
-      focusable =
+      return (
         tabindex != null &&
         String(tabindex).trim() !== '' &&
-        !Number.isNaN(Number(String(tabindex).trim()));
+        !Number.isNaN(Number(String(tabindex).trim()))
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  function isDomVisible(el) {
+    if (!el) return false;
+    if (helpers && helpers.isDomVisibleEligible)
+      return !!helpers.isDomVisibleEligible(el, ctx, { targetSet: 'dom' }).eligible;
+    if (helpers && helpers.getEligibilityInfo)
+      return !!helpers.getEligibilityInfo(el, ctx, { targetSet: 'dom' }).eligible;
+    return true;
+  }
+
+  // Same offscreen-hint pattern as avoid-inline-spacing.js.
+  function isOffscreen(el) {
+    if (!helpers || typeof helpers.getVisibilityHintsInfo !== 'function') return false;
+    try {
+      const info = helpers.getVisibilityHintsInfo(el, ctx, {});
+      return !!(info && Array.isArray(info.hints) && info.hints.indexOf('offscreen') !== -1);
+    } catch {
+      return false;
     }
-    return !focusable;
+  }
+
+  function hasAriaNamingAttr(el) {
+    try {
+      return el.getAttribute('aria-label') != null || el.getAttribute('aria-labelledby') != null;
+    } catch {
+      return false;
+    }
+  }
+
+  // Same first-child <title>/<desc> convention as svg-text-alternative-present.js.
+  function hasNonEmptyFirstChildTitleOrDesc(svg) {
+    try {
+      const first = svg.firstElementChild;
+      const tn = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+      if (tn === 'title' || tn === 'desc') return !!trim(first.textContent);
+    } catch {
+      // ignore
+    }
+    return false;
+  }
+
+  // General exclusion: aria-hidden, inert, or otherwise not included per the
+  // shared eligibility model. Visibility is checked separately beforehand,
+  // so a display:none/hidden element never reaches this path.
+  function isGenerallyExcluded(el) {
+    if (!isIncludedInAccessibilityTree) return false;
+    try {
+      const r = isIncludedInAccessibilityTree(el, ctx);
+      if (typeof r === 'boolean') return !r;
+      return !(r && r.eligible !== false);
+    } catch {
+      return false;
+    }
+  }
+
+  // Presentational exclusion: explicit role="none"/"presentation", or (img
+  // only) the native alt="" marker. Both are overridden by focusability, per
+  // ARIA conflict resolution (a focusable element is never presentational).
+  function isPresentationallyExcluded(el, tag) {
+    const role = getExplicitRole(el);
+    let presentational = role === 'presentation' || role === 'none';
+    if (!presentational && tag === 'img') {
+      const alt = el.getAttribute('alt');
+      presentational = alt != null && trim(alt) === '';
+    }
+    if (!presentational) return false;
+    return !isFocusable(el);
+  }
+
+  // ACT e88epe's "ignored svg": an implicit graphics-document role (no
+  // explicit role, or role explicitly restated as graphics-document) with
+  // no accessible name and not focusable. An svg explicitly given role="img"
+  // /"graphics-symbol", an aria-name, a <title>/<desc>, or a tab stop is
+  // "included", a naming question for svg-text-alternative-present, not
+  // this rule's "is it decorative" question.
+  function isIgnoredSvg(el) {
+    const role = getExplicitRole(el);
+    if (role && role !== 'graphics-document') return false;
+    if (hasAriaNamingAttr(el)) return false;
+    if (hasNonEmptyFirstChildTitleOrDesc(el)) return false;
+    if (isFocusable(el)) return false;
+    return true;
+  }
+
+  // ACT e88epe's "ignored canvas": no explicit role at all and no
+  // accessible name. Canvas fallback content as a naming mechanism is not
+  // modeled here (a separate, narrower question than this rule needs to
+  // settle; see docs/DESIGN_CHALLENGES.md).
+  function isIgnoredCanvas(el) {
+    const role = getExplicitRole(el);
+    if (role) return false;
+    if (hasAriaNamingAttr(el)) return false;
+    return true;
+  }
+
+  const AUTHOR_NAME_MECHANISMS = new Set(['aria-label', 'aria-labelledby', 'title', 'label']);
+
+  // ACT e88epe's own exception: never applies under an ancestor already
+  // named by the author. The common real case is an icon-only button
+  // (<button aria-label="Close"><svg>...</svg></button>) that already has a
+  // correct name from the button itself. Whether the svg "is decorative"
+  // is moot there, and flagging it would just be noise on ordinary icon usage.
+  function hasAncestorNamedFromAuthor(el) {
+    if (!getAccessibleNameInfo) return false;
+    const getComposedParent =
+      helpers && typeof helpers.composedParent === 'function'
+        ? helpers.composedParent
+        : (n) => (n && n.parentElement ? n.parentElement : null);
+
+    let cur = getComposedParent(el);
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (cur.nodeType === 1) {
+        try {
+          const info = getAccessibleNameInfo(cur, ctx, { maxRefs: 8 });
+          if (
+            info &&
+            info.present &&
+            trim(info.value) &&
+            AUTHOR_NAME_MECHANISMS.has(info.mechanism)
+          )
+            return true;
+        } catch {
+          // ignore
+        }
+      }
+      cur = getComposedParent(cur);
+    }
+    return false;
   }
 
   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$=" "]';
+    const sel = 'img, canvas, svg';
     try {
       return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []);
     } catch {
       return queryAll(sel);
     }
   })();
+
   const uniqueEls = [];
   const seen = new Set();
   for (const el of els) {
@@ -124,7 +289,7 @@ function runInPage(ctx) {
     }
   }
 
-  if (!els.length) {
+  if (!uniqueEls.length) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
@@ -132,39 +297,33 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   for (const el of uniqueEls) {
-    if (!el || !el.getAttribute) continue;
+    if (!el || !el.tagName) continue;
+    const tag = el.tagName.toLowerCase();
 
-    if (isAccTreeEligible) {
-      const elig = (() => {
-        try {
-          return isAccTreeEligible(el, ctx);
-        } catch {
-          return { eligible: true, reasons: [] };
-        }
-      })();
-      if (elig && elig.eligible === false) continue;
-    }
+    if (!isDomVisible(el)) continue;
+    if (isOffscreen(el)) continue;
 
-    if (isRolePresentationExcluded(el)) continue;
+    let excluded = isGenerallyExcluded(el);
+    if (!excluded) excluded = isPresentationallyExcluded(el, tag);
+    if (!excluded && tag === 'svg') excluded = isIgnoredSvg(el);
+    if (!excluded && tag === 'canvas') excluded = isIgnoredCanvas(el);
 
-    // 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;
+    if (!excluded) continue;
+    if (hasAncestorNamedFromAuthor(el)) 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.',
+      summary: `Review whether this <${tag}> is decorative.`,
+      hint: 'Confirm the element is purely decorative. If it conveys information or function, give it a real text alternative (or an accessible name) instead of excluding it.',
       i18n: {
         summaryKey: 'img_altDecorative_summary_cantTell',
         hintKey: 'img_altDecorative_hint_cantTell',
-        params: { element: 'img' }
+        params: { element: tag }
       },
       data: {
         visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: null
+        details: { reasonCode: 'EXCLUDED_ELEMENT_REVIEW', element: tag }
       }
     };
 

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

@@ -9,6 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <img> elements whose alt attribute is present and non-empty.
+ *   The element must be included in the accessibility tree, and
+ *   role="presentation"/"none" takes it out of scope unless it is focusable,
+ *   which restores its role. An <img> with no alt at all is
+ *   img-alt-present's failure, and one with alt="" is img-alt-decorative's
+ *   review.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

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

@@ -9,6 +9,14 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <input type="image"> elements whose alt attribute is present
+ *   but empty once trimmed, and which still carry a name from another
+ *   source: an ARIA name resolving to non-empty text, or a title. Without
+ *   that other name there is nothing to weigh the empty alt against, and the
+ *   control is input-image-alt-present's failure instead. The element must
+ *   be included in the accessibility tree, and role="presentation"/"none"
+ *   takes it out of scope unless it is focusable, which restores its role.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

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

@@ -9,6 +9,11 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <input type="image"> elements whose alt attribute is present
+ *   and non-empty: an image button whose alt is its label. The element must
+ *   be included in the accessibility tree, and role="presentation"/"none"
+ *   takes it out of scope unless it is focusable, which restores its role.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/label-title-only-manual.js

@@ -6,19 +6,19 @@
  * @check label-title-only
  * @atomic true
  * @summary Form controls should not rely on the title attribute as their only label
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to labelable form controls (input, excluding
  *   hidden/submit/reset/button/image; select; textarea) that have a
  *   non-empty title attribute.
  * @expectation
- *   The control also has a real label — a wrapping/associated <label>,
- *   aria-label, or aria-labelledby — rather than depending on the title
+ *   The control also has a real label (a wrapping/associated <label>,
+ *   aria-label, or aria-labelledby), rather than depending on the title
  *   attribute alone. A title-only tooltip is not reliably exposed by all
  *   assistive technology and is not visible at all until hover/focus,
  *   unlike a persistent visible label.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Distinct from form-control-programmatic-label-present (that

package/src/checks/manual/landmark-banner-is-top-level-manual.js

@@ -6,20 +6,20 @@
  * @check landmark-banner-is-top-level
  * @atomic true
  * @summary The banner landmark must not be nested inside another landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever the page contains at least one banner candidate:
  *   explicit role="banner", OR a <header> with NO role attribute at all,
  *   regardless of nesting (see implementation notes on why candidate
- *   selection is deliberately unconditional).
+ *   selection is unconditional on purpose).
  * @expectation
  *   No banner candidate has an ancestor that is itself any landmark
  *   region. A banner nested inside another landmark is not a top-level,
  *   whole-page banner and confuses landmark-based navigation for
  *   assistive technology users.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
- *   `type: 'manual'` rule per ROADMAP.md Tier 1b and the design doc's policy model
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule per the design doc's policy model
  *   ("Advisory / best-practice rules may exist, but must not produce
  *   `fail`"). Matches the existing `page-title-patterns-manual.js`
  *   precedent: deterministic DOM analysis, no human required, but
@@ -61,7 +61,7 @@ const meta = {
 function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage; see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   function normalizeWs(s) {
     return String(s || '')
@@ -91,7 +91,7 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
@@ -110,7 +110,7 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — it keeps
+      // A named <aside> is never suppressed, even when nested. It keeps
       // "complementary" when it has an accessible name, even inside
       // sectioning content. Matches landmark-unique's precedent.
       if (!hasSectioningAncestor(el, false)) return 'complementary';