@surea11y/core 1.5.0 → 1.6.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;
@@ -273,7 +306,9 @@ function runInPage(ctx) {
   }
 
   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 +323,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 +346,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,20 +485,30 @@ 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.
+    // 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 uncertainty = '';
     if (!contains) {
       if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
         uncertainty = 'HYPHENATION_DIFFERS';
       } else {
         const abbreviated = abbreviatedWords(visibleLabel);
-        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated))
+        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated)) {
           uncertainty = 'POSSIBLE_ABBREVIATION';
+        } else if ((labelInfo.sourceElements || []).some(isIconFontElement)) {
+          uncertainty = 'POSSIBLE_ICON_FONT_GLYPH';
+        } else if (isSingleSymbolicCharacter(visibleLabel, accNorm)) {
+          uncertainty = 'POSSIBLE_SYMBOLIC_CHARACTER';
+        }
       }
     }
 
+    const isSymbolicUncertainty =
+      uncertainty === 'POSSIBLE_ICON_FONT_GLYPH' || uncertainty === 'POSSIBLE_SYMBOLIC_CHARACTER';
+
     if (!contains) {
       occurrences.push(
         helpers.reportOccurrence(el, {
@@ -372,12 +516,22 @@ function runInPage(ctx) {
           summary: uncertainty
             ? '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: !uncertainty
+            ? '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: !uncertainty
+              ? 'labelInName_summary_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_summary_cantTell_symbolic'
+                : 'labelInName_summary_cantTell',
+            hintKey: !uncertainty
+              ? 'labelInName_hint_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_hint_cantTell_symbolic'
+                : 'labelInName_hint_cantTell',
             params: {
               element: getElementDescriptor(el),
               visibleLabel: clipForSummary(visibleLabel),

package/src/checks/automatic/link-in-text-block.js

@@ -12,7 +12,7 @@
  *   Applies to <a href> elements whose immediate parent element also has
  *   at least one direct-child text node with non-whitespace content
  *   (i.e. the link sits inline within a run of plain text, not as a
- *   standalone item — e.g. not the sole content of a <li> nav item).
+ *   standalone item, e.g. not the sole content of a <li> nav item).
  * @expectation
  *   A link inside a text block must be visually distinguishable from the
  *   surrounding text by at least one non-color means:
@@ -20,29 +20,29 @@
  *     - a different font-weight than the surrounding text, OR
  *     - a different font-style than the surrounding text, OR
  *     - a contrast ratio of at least 3:1 between the link's text color and
- *       the surrounding text's color (WCAG technique G183's threshold —
+ *       the surrounding text's color (WCAG technique G183's threshold,
  *       sufficient contrast alone is an accepted alternative to underline).
  *   Fails only when none of the above hold AND the color contrast between
- *   link and surrounding text is confidently computable and below 3:1 —
+ *   link and surrounding text is confidently computable and below 3:1,
  *   i.e. color is demonstrably the only cue.
  * @implementation-notes
  * - "Surrounding text style" is approximated as the link's immediate
  *   parent element's own computed style, not a full inline-context walk
- *   of the actual adjacent text node(s) — a deliberate scope-down, since
+ *   of the actual adjacent text node(s), a deliberate scope-down, since
  *   plain text nodes inherit their rendering from the parent in the
  *   overwhelming majority of real markup.
  * - When contrast is not confidently computable (background image/
- *   gradient, blend mode, filter, non-opaque ancestor — same blockers
+ *   gradient, blend mode, filter, non-opaque ancestor, same blockers
  *   `contrast-minimum`/`contrast-computable` use), the link is silently
  *   skipped rather than flagged or reported as cantTell, to keep `fail`
  *   reserved for deterministic, high-confidence violations. This means
- *   the rule never emits cantTell — outcome is notApplicable/pass/fail
+ *   the rule never emits cantTell, outcome is notApplicable/pass/fail
  *   only, matching this repo's other Tier 2 mechanical rules.
  * - Reuses the shared `helpers.contrast` subsystem (same
  *   computeEffectiveForeground/Background, getComputabilityBlocker,
  *   contrastRatio helpers as `contrast-minimum`), rather than re-deriving
  *   color math independently.
- * - Scoped to `a[href]` only (not `area[href]` or `[role="link"]`) —
+ * - Scoped to `a[href]` only (not `area[href]` or `[role="link"]`),
  *   matches the common real-world shape of this issue (prose links).
  */
 
@@ -52,7 +52,7 @@ const meta = {
   title:
     'Links in text blocks must be distinguishable from surrounding text without relying on color alone',
   description:
-    'Checks that a link inside a run of text is visually distinguishable from the surrounding text by underline, a font-weight/style difference, or a sufficient (>=3:1) color-contrast difference — not by color alone.',
+    'Checks that a link inside a run of text is visually distinguishable from the surrounding text by underline, a font-weight/style difference, or a sufficient (>=3:1) color-contrast difference, not by color alone.',
   i18n: {
     titleKey: 'linkInTextBlock_title',
     descriptionKey: 'linkInTextBlock_description'
@@ -179,7 +179,7 @@ function runInPage(ctx) {
     try {
       const blocker = c.getComputabilityBlocker(el);
       if (blocker && blocker.ok === false) {
-        // Not confidently computable — skip (benefit of the doubt).
+        // Not confidently computable, skip (benefit of the doubt).
       } else {
         const bg = c.computeEffectiveBackground(el, {
           contrast: { mode, rootCanvasFallback },
@@ -204,7 +204,7 @@ function runInPage(ctx) {
 
           if (!(ratio >= 3)) flagged = true;
         }
-        // else: not confidently computable — skip.
+        // else: not confidently computable, skip.
       }
     } catch {
       // no-throw: treat as not computable, skip.

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

@@ -2,6 +2,27 @@
 
 'use strict';
 
+/**
+ * @check link-name-present
+ * @atomic true
+ * @summary Links must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <a href>, <area href> and elements with role="link" that are
+ *   included in the accessibility tree. An <a> without an href is not a link
+ *   and is not matched.
+ * @expectation
+ *   The element has a non-empty accessible name. A programmatic name is
+ *   taken first (aria-labelledby, aria-label, an associated <label>, title),
+ *   and failing that the element falls back to its own subtree text,
+ *   counting each descendant's own name (an <img alt>, aria-label or title),
+ *   the shape behind the common <a><img alt="..."></a> logo link. The
+ *   content fallback is suppressed when an explicit, known role that is not
+ *   name-from-content is present; an unrecognized role token falls back to
+ *   the implicit role.
+ */
+
 const id = 'link-name-present';
 
 const meta = {
@@ -38,7 +59,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   function getConservativeSubtreeText(container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale

package/src/checks/automatic/list-children-valid.js

@@ -12,7 +12,7 @@
  *   Applies to <ul>/<ol> elements that have at least one direct element
  *   child.
  * @expectation
- *   Every direct element child is <li>, <script>, or <template> — UNLESS it
+ *   Every direct element child is <li>, <script>, or <template>. UNLESS it
  *   has an explicit `role` attribute, in which case the explicit role wins
  *   over the tag entirely: a child is valid iff that role is "listitem"
  *   (so `<li role="presentation">`/`<li role="menuitem">` are invalid
@@ -20,19 +20,19 @@
  *   given `role="listitem"` is valid). A wrapper <div> used for styling
  *   (no role at all) still breaks list semantics the same as before.
  * @implementation-notes
- * - Checked via el.children, which already excludes text/comment nodes —
+ * - Checked via el.children, which already excludes text/comment nodes,
  *   no whitespace-node filtering needed.
  * - Distinct, atomic decision from listitem-parent-valid (the
  *   inverse relationship: does a given <li> have a valid parent).
  * - Direct children that are not exposed to the accessibility tree (e.g.
  *   display:none, [hidden], aria-hidden="true") are excluded from
- *   consideration entirely — an element not reachable by assistive
+ *   consideration entirely. An element not reachable by assistive
  *   technology can't break the list semantics a screen reader announces.
  *   Common cases: a stray `<input type="hidden">` as a direct <ul> child
  *   (UA-stylesheet display:none by spec), or `<span style="display:none">`
  *   hydration markers interleaved with real `<li>`s.
  * - Explicit-role-overrides-tag: if a child has an explicit role, only
- *   `['listitem']` is consulted — the tag name is never checked. Only
+ *   `['listitem']` is consulted, the tag name is never checked. Only
  *   without an explicit role does the tag name matter. Catches cases a
  *   tag-only check misses: `<li role="none">` hosting a list's own
  *   visually-hidden label, `<li role="menuitem">` menu items, or a real
@@ -71,7 +71,7 @@ const meta = {
 function runInPage(ctx) {
   const { 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").
   const ALLOWED_CHILD_TAGS = new Set(['li', 'script', 'template']);
 
@@ -111,7 +111,7 @@ function runInPage(ctx) {
       const roleAttr = child.getAttribute ? String(child.getAttribute('role') || '').trim() : '';
       const explicitRole = roleAttr ? (roleAttr.split(/\s+/)[0] || '').toLowerCase() : '';
 
-      // An explicit role always wins over the tag — see header comment.
+      // An explicit role always wins over the tag, see header comment.
       const valid = explicitRole ? explicitRole === 'listitem' : ALLOWED_CHILD_TAGS.has(tag);
 
       if (!valid) invalidTags.push(tag);

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check listbox-name-present
+ * @atomic true
+ * @summary Elements with role="listbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="listbox" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="listbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom listbox widget is not reliably
+ *   exposed as its name. On a labelable element (<select multiple
+ *   role="listbox">) an associated <label> counts as well.
+ */
+
 const id = 'listbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Listboxes have an accessible name',
+  description: 'Checks that elements with role="listbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'listboxNamePresent_title',
     descriptionKey: 'listboxNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -231,7 +251,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This element has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this listbox's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this listbox's accessible name.",
         i18n: {
           summaryKey: 'listboxNamePresent_summary_fail',
           hintKey: 'listboxNamePresent_hint_fail',

package/src/checks/automatic/listitem-parent-valid.js

@@ -24,16 +24,16 @@
  *   e.g. aria-helpers.js getExplicitRole).
  * - An explicit role on the parent WINS over its tag name, in either
  *   direction: a <ul role="menu"> no longer exposes role "list" (its own
- *   native role is fully replaced by the explicit one — the same "any
+ *   native role is fully replaced by the explicit one, the same "any
  *   explicit role overrides the element's native role" ARIA principle
  *   applied elsewhere in this engine), so an <li> inside it is invalid
  *   despite the <ul> tag (e.g. `<ul role="menu"><li>...`). Conversely
  *   role="presentation"/"none" on the parent is still a valid
- *   (list-semantics-suppressing) parent — the accepted parent roles are
+ *   (list-semantics-suppressing) parent, the accepted parent roles are
  *   presentation, none, and list.
  * - The SAME "explicit role wins" principle applies to the <li> ELEMENT
  *   ITSELF: an <li role="tab">/role="menuitem">/role="presentation"> etc.
- *   is exposed to AT with that role, never "listitem" — the whole point
+ *   is exposed to AT with that role, never "listitem". The whole point
  *   of this check (list items need a valid list-container parent) doesn't
  *   apply when the element isn't claiming listitem semantics in the first
  *   place. Any `<li>` with an explicit `role` attribute is excluded from
@@ -108,7 +108,7 @@ function runInPage(ctx) {
     let valid;
     if (explicitRole) {
       // An explicit role always wins over the tag's native role, in either
-      // direction — see the header comment.
+      // direction, see the header comment.
       valid = explicitRole === 'list' || explicitRole === 'presentation' || explicitRole === 'none';
     } else {
       valid = parentTag === 'ul' || parentTag === 'ol';