@surea11y/core 1.5.0 → 1.7.0

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
- *   `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
- *   only, matching this repo's other Tier 2 mechanical rules.
+ * - A candidate that cannot be evaluated reports cantTell, not pass:
+ *   contrast not confidently computable (the blockers `contrast-minimum`/
+ *   `contrast-computable` use), or `text-decoration` unreadable in both
+ *   the computed style and the CSSOM (see `decorationInfo`). `fail` stays
+ *   reserved for deterministic violations; this is the computability gate
+ *   RULE_TAXONOMY.md §1.1 allows automatic rules, as in `contrast-minimum`
+ *   and `target-size-minimum`.
  * - 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'
@@ -103,14 +103,176 @@ function runInPage(ctx) {
     return null;
   }
 
-  function decorationTokens(cs) {
-    const raw =
-      `${(cs && cs.textDecorationLine) || ''} ${(cs && cs.textDecoration) || ''}`.toLowerCase();
-    return raw.split(/\s+/).filter(Boolean);
+  // Whether the element is underlined, and whether the computed style can be
+  // trusted to say so. A conforming CSSOM serialises the `text-decoration`
+  // shorthand with the line value first, so it and `text-decoration-line`
+  // always agree on whether `underline` is present. jsdom does not cascade
+  // the property at all: the shorthand reads back as the UA's "underline"
+  // for every <a> whatever the author CSS says, and the longhand as "none"
+  // unless the author used the longhand. Either one taken alone is wrong in
+  // one direction, so disagreement is the signal to stop trusting both.
+  function decorationInfo(cs) {
+    if (!cs) return { underlined: false, trustworthy: false };
+
+    const lineRaw = String(cs.textDecorationLine || '')
+      .trim()
+      .toLowerCase();
+    const shortRaw = String(cs.textDecoration || '')
+      .trim()
+      .toLowerCase();
+
+    const lineTokens = lineRaw.split(/\s+/).filter(Boolean);
+    const shortTokens = shortRaw.split(/\s+/).filter(Boolean);
+
+    // Only one of the two exposed: nothing to cross-check against, take it.
+    if (!lineTokens.length) {
+      return { underlined: shortTokens.includes('underline'), trustworthy: shortTokens.length > 0 };
+    }
+    if (!shortTokens.length) {
+      return { underlined: lineTokens.includes('underline'), trustworthy: true };
+    }
+
+    const byLine = lineTokens.includes('underline');
+    const byShort = shortTokens.includes('underline');
+    return { underlined: byLine, trustworthy: byLine === byShort };
+  }
+
+  // Resolves `text-decoration` from the author stylesheets when the computed
+  // style is untrustworthy, reading the CSSOM as `css-orientation-lock` and
+  // `css-focus-indicator-suppressed` do. Without it the rule could not decide
+  // anything under a DOM emulator, which is how the CLI scans static HTML.
+  //
+  // A narrow cascade is enough: `text-decoration-line` is not inherited, so
+  // only declarations matching the element itself and its inline style apply,
+  // ordered by specificity. With no author declaration the UA default stands,
+  // and for a link that is an underline. Anything that would make the answer a
+  // guess yields `resolved: false` and the caller reports cantTell.
+  const CSS_STYLE_RULE = 1;
+  const MAX_NESTED_DEPTH = 8;
+
+  function splitSelectorList(selectorText) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(selectorText || '')) {
+      if (ch === '(') depth += 1;
+      if (ch === ')') depth = Math.max(0, depth - 1);
+      if (ch === ',' && depth === 0) {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      current += ch;
+    }
+    parts.push(current);
+    return parts.map((p) => p.trim()).filter(Boolean);
   }
 
-  function hasUnderline(cs) {
-    return decorationTokens(cs).includes('underline');
+  // Approximate CSS specificity as a single sortable integer. Exactness is
+  // not required: this only orders declarations of one property against each
+  // other, and near-ties are broken by document order as the cascade does.
+  function specificityOf(selector) {
+    const s = String(selector || '');
+    const ids = (s.match(/#[\w-]+/g) || []).length;
+    const classesEtc = (s.match(/\.[\w-]+|\[[^\]]*\]|:(?!:)[\w-]+/g) || []).length;
+    const types = (s.match(/(^|[\s>+~])[a-z][\w-]*/gi) || []).length;
+    return ids * 10000 + classesEtc * 100 + types;
+  }
+
+  // A declaration wins if it is the last one, in (specificity, order), whose
+  // selector matches. `!important` outranks everything non-important.
+  function underlineFromDeclaration(style) {
+    if (!style || typeof style.getPropertyValue !== 'function') return null;
+    for (const prop of ['text-decoration-line', 'text-decoration']) {
+      const raw = String(style.getPropertyValue(prop) || '')
+        .trim()
+        .toLowerCase();
+      if (!raw) continue;
+      const important = String(style.getPropertyPriority(prop) || '') === 'important';
+      return { underlined: /\bunderline\b/.test(raw), important };
+    }
+    return null;
+  }
+
+  function resolveUnderlineFromCssom(el) {
+    const doc = el && el.ownerDocument ? el.ownerDocument : null;
+    if (!doc || typeof el.matches !== 'function') return { underlined: false, resolved: false };
+
+    let best = null; // { rank, order, underlined }
+    let order = 0;
+    let unreadableSheet = false;
+    let unparsableSelector = false;
+
+    function consider(cssRule) {
+      const decl = underlineFromDeclaration(cssRule.style);
+      if (!decl) return;
+      for (const part of splitSelectorList(cssRule.selectorText)) {
+        // A pseudo-element rule paints a box other than the link's own text.
+        if (/::[a-z-]+/i.test(part)) continue;
+        // A state the static DOM is not in (:hover/:focus/...) does not
+        // describe the link's resting appearance, which is what this rule is
+        // about.
+        if (/:(hover|focus|focus-visible|focus-within|active|target|visited)\b/i.test(part)) {
+          continue;
+        }
+        let matched;
+        try {
+          matched = el.matches(part);
+        } catch {
+          unparsableSelector = true;
+          continue;
+        }
+        if (!matched) continue;
+        order += 1;
+        const rank = (decl.important ? 1e9 : 0) + specificityOf(part);
+        if (!best || rank >= best.rank) best = { rank, order, underlined: decl.underlined };
+      }
+    }
+
+    function walk(rules, depth) {
+      if (!rules || depth > MAX_NESTED_DEPTH) return;
+      for (const cssRule of rules) {
+        if (!cssRule) continue;
+        if (cssRule.type === CSS_STYLE_RULE && cssRule.selectorText) {
+          consider(cssRule);
+          continue;
+        }
+        let nested;
+        try {
+          nested = cssRule.cssRules || null;
+        } catch {
+          nested = null;
+        }
+        if (nested) walk(nested, depth + 1);
+      }
+    }
+
+    try {
+      for (const sheet of doc.styleSheets || []) {
+        let rules = null;
+        try {
+          rules = sheet && sheet.cssRules ? sheet.cssRules : null;
+        } catch {
+          unreadableSheet = true; // cross-origin, not inspectable
+          continue;
+        }
+        if (rules) walk(rules, 0);
+      }
+    } catch {
+      return { underlined: false, resolved: false };
+    }
+
+    // The inline style attribute outranks every stylesheet declaration.
+    const inline = underlineFromDeclaration(el.style);
+    if (inline) return { underlined: inline.underlined, resolved: true };
+
+    if (best) return { underlined: best.underlined, resolved: true };
+
+    // No author declaration reached this element. If a sheet or selector was
+    // unreadable, one of them might have, so the answer is unknown; otherwise
+    // the UA default stands, and for a link that means underlined.
+    if (unreadableSheet || unparsableSelector) return { underlined: false, resolved: false };
+    return { underlined: true, resolved: true };
   }
 
   function hasSurroundingText(el, parent) {
@@ -141,7 +303,15 @@ function runInPage(ctx) {
     : helpers.queryAll(selector);
 
   const occurrences = [];
+  const undecided = [];
   let applicableCount = 0;
+  let decidedCount = 0;
+
+  // Applicable, but not evaluable. Held separately so the outcome below can
+  // tell "checked and sound" apart from "never decided".
+  function markUndecided(el, reasonCode) {
+    undecided.push({ el, reasonCode });
+  }
 
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
@@ -159,27 +329,40 @@ function runInPage(ctx) {
     const linkCs = safeComputedStyle(el);
     const parentCs = safeComputedStyle(parent);
 
-    if (hasUnderline(linkCs)) continue;
-
+    // Cues that do not depend on `text-decoration` come first, so a link
+    // carrying one is decided even where decoration is unreadable.
     const linkWeight = c && linkCs ? c.normalizeFontWeight(linkCs.fontWeight) : 400;
     const parentWeight = c && parentCs ? c.normalizeFontWeight(parentCs.fontWeight) : 400;
-    if (linkWeight !== parentWeight) continue;
+    if (linkWeight !== parentWeight) {
+      decidedCount += 1;
+      continue;
+    }
 
     const linkStyle = (linkCs && linkCs.fontStyle) || 'normal';
     const parentStyle = (parentCs && parentCs.fontStyle) || 'normal';
-    if (linkStyle !== parentStyle) continue;
+    if (linkStyle !== parentStyle) {
+      decidedCount += 1;
+      continue;
+    }
 
-    if (!c) continue;
+    if (!c) {
+      markUndecided(el, 'CONTRAST_HELPERS_UNAVAILABLE');
+      continue;
+    }
 
     let flagged = false;
+    let computed = false;
     let ratio = null;
     let fgLinkHex = '';
     let fgParentHex = '';
+    let undecidedReason = 'COLOR_NOT_COMPUTABLE';
 
     try {
       const blocker = c.getComputabilityBlocker(el);
       if (blocker && blocker.ok === false) {
-        // Not confidently computable — skip (benefit of the doubt).
+        // Not confidently computable: recorded below rather than skipped, so
+        // it cannot be mistaken for a clean result.
+        if (blocker.reasonCode) undecidedReason = String(blocker.reasonCode);
       } else {
         const bg = c.computeEffectiveBackground(el, {
           contrast: { mode, rootCanvasFallback },
@@ -202,15 +385,49 @@ function runInPage(ctx) {
           fgLinkHex = c.rgbToHex ? c.rgbToHex(fgLinkOpaque) : '';
           fgParentHex = c.rgbToHex ? c.rgbToHex(fgParentOpaque) : '';
 
+          computed = true;
           if (!(ratio >= 3)) flagged = true;
         }
-        // else: not confidently computable — skip.
+        // else: not confidently computable, recorded below.
       }
     } catch {
-      // no-throw: treat as not computable, skip.
+      // No-throw: treat as not computable and record it.
+      undecidedReason = 'ENGINE_EXCEPTION';
+    }
+
+    if (!computed) {
+      markUndecided(el, undecidedReason);
+      continue;
+    }
+
+    // Contrast alone is an accepted alternative to an underline (G183), so a
+    // link clearing 3:1 is distinguishable regardless of decoration.
+    if (!flagged) {
+      decidedCount += 1;
+      continue;
+    }
+
+    // Below 3:1, an underline is the last remaining cue -- and only now does
+    // it matter whether this environment can actually report one.
+    const decoration = decorationInfo(linkCs);
+    let underlined;
+    if (decoration.trustworthy) {
+      underlined = decoration.underlined;
+    } else {
+      const fromCssom = resolveUnderlineFromCssom(el);
+      if (!fromCssom.resolved) {
+        markUndecided(el, 'TEXT_DECORATION_NOT_RESOLVABLE');
+        continue;
+      }
+      underlined = fromCssom.underlined;
+    }
+
+    if (underlined) {
+      decidedCount += 1;
+      continue;
     }
 
-    if (!flagged) continue;
+    decidedCount += 1;
 
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
@@ -243,6 +460,9 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
+
+  // A proven violation outranks an undecided candidate, which outranks a clean
+  // one. The middle step keeps an unevaluable link out of `pass`.
   if (occurrences.length) {
     return {
       ruleId: rule.ruleId,
@@ -251,7 +471,43 @@ function runInPage(ctx) {
       occurrences
     };
   }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  if (undecided.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'serious',
+      confidence: 'low',
+      occurrences: undecided.map(({ el, reasonCode }) =>
+        helpers.reportOccurrence(el, {
+          summary:
+            'Whether this link is distinguishable from the surrounding text by non-color means could not be determined.',
+          hint: 'Confirm by eye that the link carries an underline, a font-weight or font-style difference, or at least 3:1 contrast against the surrounding text. Running the engine in a real browser rather than a DOM emulator resolves most cases automatically.',
+          i18n: {
+            summaryKey: 'linkInTextBlock_summary_cantTell',
+            hintKey: 'linkInTextBlock_hint_cantTell'
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed:
+              'Whether the link carries an underline, weight or style difference, or 3:1 contrast against its surrounding text.',
+            evidence: { reasonCode }
+          },
+          data: {
+            visibilityFilter: helpers.getEligibilityInfo
+              ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+              : { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode }
+          }
+        })
+      )
+    };
+  }
+
+  if (decidedCount > 0) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
 module.exports = { id, meta, runInPage };

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';

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

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check menuitem-name-present
+ * @atomic true
+ * @summary Menu items must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="menuitem", role="menuitemcheckbox" or
+ *   role="menuitemradio" (the attribute must name one of those roles alone,
+ *   not a fallback list) that are included in the accessibility tree.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or, all
+ *   three roles being name-from-content, from its own subtree text, where a
+ *   descendant's own name (an <img alt>, aria-label or title) counts as that
+ *   descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'menuitem-name-present';
 
 const meta = {
@@ -52,7 +70,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
@@ -71,7 +89,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).