@surea11y/core 1.5.0 → 1.7.0

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

@@ -10,17 +10,34 @@
  * @sc 4.1.2
  * @applicability
  *   Applies to <iframe>/<frame> elements that are eligible for the
- *   accessibility tree (isAccTreeEligible).
+ *   accessibility tree (isAccTreeEligible) AND reachable by sequential
+ *   focus navigation, both conditions required, regardless of role.
  * @expectation
  *   The element has a non-empty accessible name via aria-labelledby,
  *   aria-label, or the title attribute. Unlike most interactive elements,
  *   an iframe's name is never derived from its rendered content (the
- *   embedded document is a separate browsing context) — this mirrors
+ *   embedded document is a separate browsing context), this mirrors
  *   dialog-name-present's "name-from-author-only" reasoning.
  * @implementation-notes
  * - Uses helpers.getAccessibleNameInfo, which already stops at
  *   aria-label/aria-labelledby/label[for]/title without falling back to
- *   subtree text content — the right shape for this element.
+ *   subtree text content, the right shape for this element.
+ * - Per ACT cae760's own Applicability text, an iframe is only in scope
+ *   when it is BOTH accessibility-tree-eligible AND reachable by
+ *   sequential focus navigation, unconditionally, not only as a
+ *   role="none"/"presentation" exception. Unlike most elements,
+ *   <iframe>/<frame> are natively focusable by default (no tabindex
+ *   needed), so `tabindex="-1"` (or any negative tabindex) exempts a
+ *   frame regardless of whether it also carries a role, a plain
+ *   `<iframe tabindex="-1">` with no role at all is just as out of scope
+ *   as `<iframe role="none" tabindex="-1">`; ACT cae760's own passed
+ *   example is the roleless case. (The role="none" reasoning, "because
+ *   iframe elements are part of sequential focus navigation, the
+ *   explicit semantic role of none will be ignored, due to Presentational
+ *   Roles Conflict Resolution", is *why* a focusable role="none" iframe
+ *   still needs a name, not a separate applicability path of its own.)
+ *   helpers.getFocusableInfo doesn't model iframe/frame's native
+ *   focusability at all, so it's computed locally here instead.
  */
 
 const id = 'iframe-name-present';
@@ -62,9 +79,26 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // <iframe>/<frame> are natively focusable by default (no tabindex
+  // needed), unlike most elements, only an explicit negative tabindex
+  // removes them from the tab order.
+  function isFrameFocusable(el) {
+    try {
+      const tabindexRaw = el.getAttribute ? el.getAttribute('tabindex') : null;
+      if (tabindexRaw == null) return true;
+      const n = Number(String(tabindexRaw).trim());
+      if (Number.isFinite(n) && n < 0) return false;
+      return true;
+    } catch {
+      return true;
+    }
+  }
+
   for (const el of nodes) {
     if (!el || !el.tagName) continue;
 
+    if (!isFrameFocusable(el)) continue;
+
     if (helpers.isAccTreeEligible) {
       const elig = helpers.isAccTreeEligible(el);
       const isEligible = typeof elig === 'boolean' ? elig : !!(elig && elig.eligible);

package/src/checks/automatic/iframe-title-unique.js

@@ -13,7 +13,7 @@
  *   attribute.
  * @expectation
  *   No two frames in scope share the same (trimmed, case-sensitive) title
- *   attribute value — a duplicate title prevents assistive technology
+ *   attribute value, a duplicate title prevents assistive technology
  *   users from telling frames apart when scanning by name.
  * @implementation-notes
  * - Distinct, atomic decision from iframe-name-present (presence):

package/src/checks/automatic/img-alt-present.js

@@ -157,13 +157,21 @@ function runInPage(ctx) {
     // From here: applicable
     applicableCount += 1;
 
-    // alt attribute presence check (empty allowed)
-    let hasAlt;
+    // alt attribute presence check. A literally empty alt ("") is the
+    // HTML decorative marker and always satisfies this check. A present
+    // alt that is non-empty but trims to nothing (a lone space, a tab)
+    // does not get that treatment: per HTML-AAM the img-role conflict-
+    // resolution flip to presentation only triggers on the literal empty
+    // string, so the element keeps its img role while its computed
+    // accessible name is empty -- a real failure, not a decorative image.
+    let rawAlt;
     try {
-      hasAlt = el.getAttribute('alt') !== null;
+      rawAlt = el.getAttribute('alt');
     } catch {
-      hasAlt = false;
+      rawAlt = null;
     }
+    const isWhitespaceOnlyAlt = rawAlt !== null && rawAlt !== '' && trim(rawAlt) === '';
+    const hasAlt = rawAlt !== null && !isWhitespaceOnlyAlt;
     if (hasAlt) continue;
 
     // aria-label / aria-labelledby is also a valid, standards-recognized

package/src/checks/automatic/label-in-name.js

@@ -2,12 +2,45 @@
 
 'use strict';
 
+/**
+ * @check label-in-name
+ * @atomic true
+ * @summary A control's accessible name must contain its visible label text
+ * @standard WCAG 2.2
+ * @sc 2.5.3
+ * @applicability
+ *   Applies to controls that carry aria-label or aria-labelledby, are
+ *   visually rendered, and have visible label text this engine can extract
+ *   deterministically, from an associated <label>, from the control's own
+ *   rendered text, or from the elements aria-labelledby points at. The
+ *   candidates are <button>, <a href>, <summary>, non-hidden form controls,
+ *   and the button, link, checkbox, radio, switch, searchbox, tab, menuitem,
+ *   menuitemcheckbox, menuitemradio, option, treeitem and gridcell roles,
+ *   minus anything hidden or disabled. aria-hidden is not
+ *   excluded: it changes nothing about what is rendered on screen, which is
+ *   what this SC is about.
+ * @expectation
+ *   The accessible name contains the visible label's words, adjacent and in
+ *   order. The comparison is over words rather than characters:
+ *   parenthesised text is dropped, case is folded, text is NFKD-normalised,
+ *   and every non-letter/digit becomes a separator, so punctuation and
+ *   spacing differences never decide the outcome. Four shapes markup cannot
+ *   settle are reported as cantTell instead of fail: a word hyphenated
+ *   differently in the two places; a visible word the author may have
+ *   abbreviated, marked by its trailing period; visible text rendered
+ *   through a known icon font (the DOM text is real words, but nothing
+ *   readable actually renders); and a whole visible label of exactly one
+ *   character that doesn't even appear inside the accessible name, which
+ *   per ACT 2ee8b8 may be "non-text content" (e.g. "X" meaning "close")
+ *   rather than literal text.
+ */
+
 const id = 'label-in-name';
 
 const meta = {
   title: 'Label in Name: accessible name contains visible text',
   description:
-    'Checks that when a control has a visible text label, the accessible name (from aria-label/aria-labelledby) contains that visible label text (WCAG 2.5.3).',
+    'Checks that when a control has a visible text label, the accessible name contains that visible label text (WCAG 2.5.3).',
   i18n: {
     titleKey: 'labelInName_title',
     descriptionKey: 'labelInName_description'
@@ -147,7 +180,7 @@ function runInPage(ctx) {
   // rendering as "format_color_fill") is DOM-visible pixels but is never
   // perceived as literal readable words the way real visible text is.
   // Excluding aria-hidden content is a cheap static-markup signal that gets
-  // the common case (decorative icon fonts) right — an icon-only button
+  // the common case (decorative icon fonts) right. An icon-only button
   // named via aria-label shouldn't have its glyph name counted as text.
   function isAccEligible(el) {
     if (!el) return false;
@@ -221,59 +254,28 @@ function runInPage(ctx) {
     return parts.join(' ').replace(/\s+/g, ' ').trim();
   }
 
+  // Real <label> elements associated with a native form control -- the
+  // shared dom-helpers.js implementation (a `for`-attribute index plus a
+  // bounded closest('label') walk), not the native `.labels`/`.control`
+  // pair: jsdom implements those as a whole-document walk on every access
+  // (see that function's own header comment for the full explanation),
+  // real cost this engine's Node/jsdom runtime pays, not just a browser
+  // realm this code happens to also run in.
   function getAssociatedLabelElements(control) {
-    const labels = [];
-    try {
-      if (control && control.labels && typeof control.labels.length === 'number') {
-        for (const l of control.labels) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // Fallback: wrapped label
-    try {
-      const w = control && control.closest ? control.closest('label') : null;
-      if (w) labels.push(w);
-    } catch {
-      // ignore
-    }
-
-    // Fallback: label[for=id]. Uses `document` directly rather than
-    // ctx.root -- label[for] association is a document-wide relationship
-    // (IDs are document-unique), not bounded by whatever contextSelector
-    // region happens to be scanned, and ctx.root is an array (multi-region
-    // contextSelector support), not a single element with its own
-    // .querySelector to call directly.
-    try {
-      const idAttribute = control && control.getAttribute ? control.getAttribute('id') || '' : '';
-      const key = String(idAttribute || '').trim();
-      if (key && document && document.querySelector) {
-        const l = document.querySelector('label[for="' + CSS.escape(key) + '"]');
-        if (l) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // De-dupe in document order
-    const seen = new Set();
-    const out = [];
-    for (const l of labels) {
+    if (helpers && typeof helpers.getAssociatedLabelElements === 'function') {
       try {
-        if (!l || !l.tagName) continue;
-        if (seen.has(l)) continue;
-        seen.add(l);
-        out.push(l);
+        return helpers.getAssociatedLabelElements(control) || [];
       } catch {
-        // ignore
+        return [];
       }
     }
-    return out;
+    return [];
   }
 
   function getVisibleTextLabelInfo(el) {
-    // Returns { text, source } where source helps reporting.
+    // Returns { text, source, sourceElements } where source helps reporting
+    // and sourceElements (the actual DOM nodes the visible text came from)
+    // lets the icon-font check below look at the right element's own style.
     // Source policy (deterministic):
     // 1) <label> association for form controls
     // 2) visible text inside the element
@@ -288,18 +290,22 @@ function runInPage(ctx) {
     if (isFormControl) {
       const labels = getAssociatedLabelElements(el);
       const labelParts = [];
+      const contributing = [];
       for (const l of labels) {
         if (!l || !isDomVisible(l)) continue;
         const t = collectVisibleTextUnder(l);
-        if (t) labelParts.push(t);
+        if (t) {
+          labelParts.push(t);
+          contributing.push(l);
+        }
       }
       const joined = labelParts.join(' ').replace(/\s+/g, ' ').trim();
-      if (joined) return { text: joined, source: 'label' };
+      if (joined) return { text: joined, source: 'label', sourceElements: contributing };
     }
 
     // 2) Text inside the control itself
     text = collectVisibleTextUnder(el);
-    if (text) return { text, source: 'self' };
+    if (text) return { text, source: 'self', sourceElements: [el] };
 
     // 3) aria-labelledby referenced visible text (only if refs exist and are visible)
     try {
@@ -307,20 +313,115 @@ function runInPage(ctx) {
       if (idrefs && helpers.resolveIdRefs) {
         const r = helpers.resolveIdRefs(idrefs, ctx, { maxRefs: 8 });
         const parts = [];
+        const contributing = [];
         for (const ref of r && Array.isArray(r.refs) ? r.refs : []) {
           if (!ref || !ref.tagName) continue;
           if (!isDomVisible(ref)) continue;
           const t = collectVisibleTextUnder(ref);
-          if (t) parts.push(t);
+          if (t) {
+            parts.push(t);
+            contributing.push(ref);
+          }
         }
         const joined = parts.join(' ').replace(/\s+/g, ' ').trim();
-        if (joined) return { text: joined, source: 'aria-labelledby' };
+        if (joined)
+          return { text: joined, source: 'aria-labelledby', sourceElements: contributing };
       }
     } catch {
       // ignore
     }
 
-    return { text: '', source };
+    return { text: '', source, sourceElements: [] };
+  }
+
+  // Curated real-world icon-font family names. These fonts remap ordinary
+  // word glyphs to unrelated symbols via ligatures/PUA codepoints, so the
+  // DOM text is real words but nothing readable actually renders, ACT
+  // 2ee8b8's own passed example is exactly this (a button's DOM text
+  // "search" rendered as a magnifying-glass icon by "Material Icons").
+  // Same curated-list tradeoff as link-name-quality's phrase list.
+  const ICON_FONT_FAMILIES = new Set([
+    'material icons',
+    'material icons outlined',
+    'material icons round',
+    'material icons sharp',
+    'material icons two tone',
+    'material symbols outlined',
+    'material symbols rounded',
+    'material symbols sharp',
+    'font awesome 5 free',
+    'font awesome 5 brands',
+    'font awesome 5 pro',
+    'font awesome 6 free',
+    'font awesome 6 brands',
+    'font awesome 6 pro',
+    'fontawesome',
+    'glyphicons halflings',
+    'ionicons',
+    'icomoon',
+    'bootstrap-icons',
+    'bootstrap icons',
+    'feather'
+  ]);
+
+  // Same two-tier lookup as avoid-inline-spacing.js's computedStyleOf:
+  // helpers.computedStyle isn't actually part of the public helpers API
+  // (it's internal to dom-helpers.js), so the realm's own getComputedStyle
+  // is what actually resolves a stylesheet-declared font-family.
+  function computedStyleOf(node) {
+    if (helpers && typeof helpers.computedStyle === 'function') {
+      try {
+        const cs = helpers.computedStyle(node);
+        if (cs) return cs;
+      } catch {
+        // fall through to the realm's own view
+      }
+    }
+    try {
+      const view = node.ownerDocument && node.ownerDocument.defaultView;
+      if (view && typeof view.getComputedStyle === 'function') return view.getComputedStyle(node);
+    } catch {
+      // no computed style available
+    }
+    return null;
+  }
+
+  function isIconFontElement(node) {
+    if (!node) return false;
+    const cs = computedStyleOf(node);
+    if (!cs) return false;
+    let family;
+    try {
+      family =
+        cs.fontFamily || (cs.getPropertyValue ? cs.getPropertyValue('font-family') : '') || '';
+    } catch {
+      family = '';
+    }
+    if (!family) return false;
+    const names = String(family)
+      .split(',')
+      .map((s) =>
+        s
+          .trim()
+          .replace(/^['"]|['"]$/g, '')
+          .toLowerCase()
+      );
+    return names.some((n) => ICON_FONT_FAMILIES.has(n));
+  }
+
+  // ACT 2ee8b8's own passed example `<button aria-label="close">X</button>`:
+  // a single character standing in for an icon ("x" meaning "close") is
+  // "non-text content" per the rule's own background text, which names no
+  // algorithmic test for it. Scoped narrowly to a whole visible label of
+  // exactly one character that doesn't even appear inside the accessible
+  // name: "x" has no relation at all to "close", which is the icon-glyph
+  // shape. A single character that DOES appear in the name (e.g. visible
+  // "1" against aria-label "1a") is a real word-boundary mismatch, not a
+  // symbol standing in for something else, and still fails outright.
+  function isSingleSymbolicCharacter(text, accessibleNameNorm) {
+    const t = norm(text);
+    if (!t || Array.from(t).length !== 1) return false;
+    return accessibleNameNorm.indexOf(t) === -1;
   }
 
   for (const el of nodes) {
@@ -351,33 +452,54 @@ function runInPage(ctx) {
     const nameTokens = tokenize(accName, false);
     const contains = containsWordRun(labelTokens, nameTokens, null);
 
-    // An abbreviation, or a word hyphenated differently in the two places, is
-    // not something markup settles: the author may have meant either. Report
-    // without asserting a defect instead of failing or staying silent.
-    let uncertainty = '';
+    // An abbreviation, a word hyphenated differently, or visible text that
+    // may not be literal text at all (an icon-font glyph, a single symbolic
+    // character) is not something markup settles: the author may have meant
+    // either. Report without asserting a defect instead of failing or
+    // staying silent.
+    let uncertainReason = '';
     if (!contains) {
       if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
-        uncertainty = 'HYPHENATION_DIFFERS';
+        uncertainReason = 'HYPHENATION_DIFFERS';
       } else {
         const abbreviated = abbreviatedWords(visibleLabel);
-        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated))
-          uncertainty = 'POSSIBLE_ABBREVIATION';
+        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated)) {
+          uncertainReason = 'POSSIBLE_ABBREVIATION';
+        } else if ((labelInfo.sourceElements || []).some(isIconFontElement)) {
+          uncertainReason = 'POSSIBLE_ICON_FONT_GLYPH';
+        } else if (isSingleSymbolicCharacter(visibleLabel, accNorm)) {
+          uncertainReason = 'POSSIBLE_SYMBOLIC_CHARACTER';
+        }
       }
     }
 
+    const isSymbolicUncertainty =
+      uncertainReason === 'POSSIBLE_ICON_FONT_GLYPH' ||
+      uncertainReason === 'POSSIBLE_SYMBOLIC_CHARACTER';
+
     if (!contains) {
       occurrences.push(
         helpers.reportOccurrence(el, {
-          ...(uncertainty ? { outcome: 'cantTell' } : null),
-          summary: uncertainty
+          ...(uncertainReason ? { outcome: 'cantTell' } : null),
+          summary: uncertainReason
             ? 'Accessible name may not contain the visible label text.'
             : 'Accessible name does not contain the visible label text.',
-          hint: uncertainty
-            ? 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.'
-            : 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
+          hint: !uncertainReason
+            ? 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).'
+            : isSymbolicUncertainty
+              ? 'Check by hand: the visible text may render as an icon or symbol rather than literal words, which markup cannot settle.'
+              : 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.',
           i18n: {
-            summaryKey: uncertainty ? 'labelInName_summary_cantTell' : 'labelInName_summary_fail',
-            hintKey: uncertainty ? 'labelInName_hint_cantTell' : 'labelInName_hint_fail',
+            summaryKey: !uncertainReason
+              ? 'labelInName_summary_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_summary_cantTell_symbolic'
+                : 'labelInName_summary_cantTell',
+            hintKey: !uncertainReason
+              ? 'labelInName_hint_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_hint_cantTell_symbolic'
+                : 'labelInName_hint_cantTell',
             params: {
               element: getElementDescriptor(el),
               visibleLabel: clipForSummary(visibleLabel),
@@ -385,9 +507,23 @@ function runInPage(ctx) {
               nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
             }
           },
+          ...(uncertainReason
+            ? {
+                uncertainty: {
+                  code: 'equivalence-unknown',
+                  needed:
+                    'Whether the accessible name and the visible label say the same thing to a user.',
+                  evidence: {
+                    visibleLabel,
+                    accessibleName: accName,
+                    difference: uncertainReason
+                  }
+                }
+              }
+            : null),
           data: {
             details: {
-              reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+              reasonCode: uncertainReason || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
               visibleLabel,
               accessibleName: accName,
               normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },