@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/target-size-minimum.js

@@ -8,6 +8,24 @@
  * @summary Pointer-operable targets should be at least 24×24 CSS px (or meet an exception)
  * @standard WCAG 2.2
  * @sc 2.5.8
+ * @applicability
+ *   Applies to <button>, <summary>, <a href>, <area href>, <input>,
+ *   <select>, <textarea> and elements with role="button"/"link" that are
+ *   pointer-reachable: rendered, not suppressed by pointer-events:none, and
+ *   with a measurable box of non-zero size. Accessibility-tree exclusion isn't
+ *   a filter here: an aria-hidden control is still a target a pointer can hit.
+ *   <area> is matched but never actually evaluated, for the reason given below.
+ * @expectation
+ *   Each target is at least 24 by 24 CSS pixels, or meets one of the SC
+ *   2.5.8 exceptions this rule can establish from geometry: spacing (a
+ *   24px-diameter circle centred on the target reaches no unrelated target),
+ *   the inline exception for a link inside a run of text, or user-agent
+ *   sizing (an unstyled native checkbox or radio, detected by appearance not
+ *   having been reset to none). An undersized target too close to a
+ *   neighbour fails. Where an exception may apply but geometry cannot
+ *   confirm it (two inline links in one run of text, or a target inside an
+ *   SVG, canvas or image map that may be essential), the result is cantTell
+ *   rather than a guess.
  *
  * Notes (engine intent):
  * - This rule is DOM-based and measures pointer hit regions available to sighted pointer users.
@@ -19,38 +37,43 @@
  * - Spacing: a 24px-diameter circle centered on an undersized target must not
  *   intersect another (unrelated) target's box or another undersized
  *   target's own circle. Two passes: a fast center-distance check (exact for
- *   undersized-vs-undersized; a reasonable proxy otherwise) and a 16-point
+ *   undersized-vs-undersized, a reasonable proxy otherwise) and a 16-point
  *   perimeter sample via elementFromPoint as a more precise fallback for
  *   cases the distance check under-detects (e.g. a small target adjacent to
  *   a large, elongated neighbor). Ancestor/descendant relationships between
- *   the target and the "other" element are never treated as a conflict —
- *   see isRelated — since a nested-interactive shape (a small control inside
- *   its own wrapping link/button) is one visual region, not two independent
- *   targets; that pattern is nested-interactive-controls-absent's
- *   concern, not a spacing one.
- * - Inline: a link inside a run of text (isInlineTextExceptionTarget).
+ *   the target and the "other" element are never treated as a conflict (see
+ *   isRelated): a nested-interactive shape, a small control inside its own
+ *   wrapping link/button, is one visual region, not two independent targets.
+ *   That pattern is nested-interactive-controls-absent's concern, not a
+ *   spacing one.
+ * - Inline: a link inside a text-block container passes outright
+ *   (isInlineTextExceptionTarget). An inline link whose only spacing conflict
+ *   is another inline link in the same run is reported as cantTell
+ *   (isInlineLinkTarget), since the inline exception may cover it but
+ *   geometry can't confirm that.
  * - User Agent Control: an unstyled native checkbox/radio, detected via
- *   `appearance` not being reset to `none` (see isUserAgentSizedControl) —
- *   scoped narrowly to checkbox/radio specifically, not every form control,
+ *   `appearance` not being reset to `none` (see isUserAgentSizedControl).
+ *   Scoped narrowly to checkbox/radio specifically, not every form control,
  *   since those are the only types with unambiguous native rendering.
  * - Essential/Equivalent: only a narrow, high-confidence subset is asserted
- *   (SVG/canvas/map-embedded controls) — see isPlausiblyEssentialOrEquivalent;
+ *   (SVG/canvas/map-embedded controls, see isPlausiblyEssentialOrEquivalent);
  *   anything else defers to cantTell rather than guessing "essential" from a
  *   layout container.
  *
- * Known, deliberately unimplemented gap: `<area>` (image-map hotspot)
+ * Known gap, left unimplemented on purpose: `<area>` (image-map hotspot)
  * elements are not evaluated at all. `area[href]` is in CANDIDATE_SELECTOR
- * for forward-compatibility, but it's currently a no-op: `<area>` has no
+ * for forward-compatibility, but it's currently a no-op. `<area>` has no
  * CSS box of its own (`display: none` by the HTML spec's default UA
- * stylesheet — verified, not a jsdom quirk), so `getBoundingClientRect()`
- * always reports zero geometry and `isPointerReachable`'s existing
- * `display:none` check rejects it before any size/exception logic runs. A
- * real `<area>` hit-region is computed by the browser from its `shape`/
- * `coords` attributes against the associated `<img>`'s *rendered* size —
- * an entirely different measurement path than every other candidate here.
- * Implementing that properly (parsing `coords`, resolving the owning
- * `<img>` via its `usemap`, accounting for the image's CSS-scaled render
- * size) is a separate, larger feature, not attempted in this pass.
+ * stylesheet, confirmed against the spec rather than a jsdom quirk), so
+ * `getBoundingClientRect()` always reports zero geometry and
+ * `isPointerReachable`'s existing `display:none` check rejects it before any
+ * size/exception logic runs. A real `<area>` hit-region is computed by the
+ * browser from its `shape`/`coords` attributes against the associated
+ * `<img>`'s *rendered* size, an entirely different measurement path than
+ * every other candidate here. Implementing that properly (parsing `coords`,
+ * resolving the owning `<img>` via its `usemap`, accounting for the image's
+ * CSS-scaled render size) is a separate, larger feature, not attempted in
+ * this pass.
  *
  * This is an automatic, deterministic approximation intended to be:
  * - strict on clear failures,
@@ -60,7 +83,8 @@
 const id = 'target-size-minimum';
 
 const meta = {
-  title: 'Pointer targets meet minimum size (AA)',
+  title:
+    'Pointer targets must be at least 24x24px large, or leave sufficient distance to other targets',
   description:
     'Checks that pointer-operable targets have an effective hit region of at least 24 by 24 CSS pixels, or meet an allowed exception (e.g. sufficient spacing).',
   i18n: {
@@ -147,23 +171,10 @@ function runInPage(ctx) {
     return 'html';
   }
 
-  function htmlSnippet(el) {
-    try {
-      if (helpers && typeof helpers.getOuterHtmlSnippet === 'function')
-        return helpers.getOuterHtmlSnippet(el);
-    } catch {}
-    try {
-      return el && el.outerHTML ? String(el.outerHTML) : '';
-    } catch {}
-    return '';
-  }
-
-  function isInlineTextExceptionTarget(el) {
-    // SC 2.5.8 exception: target is in a sentence/block of text (inline)
-    // Deterministic heuristic:
-    // - must be a link-like target
-    // - must be rendered as inline/inline-*
-    // - must be inside a typical text container
+  // A link-like target (a[href] or role="link") rendered inline/inline-* and
+  // carrying visible text. This is the shape the SC 2.5.8 inline exception is
+  // about, without the surrounding-container requirement.
+  function isInlineLinkTarget(el) {
     try {
       if (!el || el.nodeType !== 1) return false;
 
@@ -180,27 +191,31 @@ function runInPage(ctx) {
 
       const cs = getStyle(el);
       const display = cs && cs.display ? String(cs.display) : '';
-      if (!display) return false;
-
-      // Inline exception is for inline text runs; many design systems use inline-block for links,
-      // so treat inline-block variants as eligible for this exception.
+      // Many design systems use inline-block for links, so treat the
+      // inline-block variants as inline here too.
       const isInline =
         display === 'inline' ||
         display === 'inline-block' ||
         display === 'inline-flex' ||
         display === 'inline-grid' ||
         display === 'inline-table';
-
       if (!isInline) return false;
 
-      const t = (el.textContent || '').trim();
-      if (!t) return false;
+      return (el.textContent || '').trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  function isInlineTextExceptionTarget(el) {
+    // SC 2.5.8 exception: an inline link that sits inside a run of text.
+    try {
+      if (!isInlineLinkTarget(el)) return false;
 
-      // Require that it sits in a "text block" context
       const textContainer = closest(el, 'p, li, dd, dt, blockquote, figcaption, caption, td, th');
       if (textContainer) return true;
 
-      // Fallback: sometimes links are inside spans within a paragraph-like region
+      // Links are often wrapped in an inline element inside the text block.
       const inlineContainer = closest(el, 'span, em, strong, small, label');
       if (inlineContainer) {
         const outerTextBlock = closest(
@@ -359,11 +374,11 @@ function runInPage(ctx) {
   // element, or either one is an ancestor of the other. A nested-interactive
   // pattern (e.g. a small <button> inside a wrapping <a href>, or vice
   // versa) is a single visual/interactive region, not two independently
-  // placed targets — the spacing exception's "does the circle intersect
+  // placed targets. The spacing exception's "does the circle intersect
   // ANOTHER target" language is about separate targets, not an element and
   // its own container. (Nested interactive controls are their own,
-  // separately-flagged anti-pattern — nested-interactive-controls-
-  // absent — not a target-size spacing concern.)
+  // separately-flagged anti-pattern, nested-interactive-controls-absent,
+  // not a target-size spacing concern.)
   function isRelated(a, b) {
     try {
       if (!a || !b) return false;
@@ -420,7 +435,7 @@ function runInPage(ctx) {
   function hasSpacingConflict(target) {
     // 0) Pure geometry: deterministic center-distance check against ANY
     // nearby target, not just other undersized ones. Per WCAG 2.5.8, the
-    // spacing exception depends on proximity to any adjacent target — an
+    // spacing exception depends on proximity to any adjacent target, so an
     // undersized target sitting flush against an adequately-sized one still
     // fails the exception, which an undersized-only comparison would miss.
     for (const other of items) {
@@ -444,8 +459,8 @@ function runInPage(ctx) {
     // as a confident conflict. Perimeter sampling is an approximation
     // (rounded corners, border-radius, and sub-pixel geometry can shift a
     // sample point in or out of a neighboring element), so a result that
-    // merely reaches HIT_THRESHOLD is not asserted as a deterministic
-    // fail — see the ambiguous band below.
+    // merely reaches HIT_THRESHOLD is not asserted as a deterministic fail.
+    // See the ambiguous band below.
     const CONFIDENT_THRESHOLD = 5;
     let hitCount = 0;
     let firstConflictEl = null;
@@ -491,20 +506,20 @@ function runInPage(ctx) {
 
   // WCAG 2.5.8 "User Agent Control" exception: the target's size requirement
   // does not apply at all when its size is determined by the user agent and
-  // not modified by the author — the canonical example being an unstyled
-  // native checkbox/radio (browsers render these well under 24px by
-  // default, and that's not the author's choice). Scoped narrowly to
-  // input[type=checkbox]/[type=radio] specifically (the only form-control
-  // types with a universally-recognized, unambiguous native rendering) —
-  // deliberately not extended to select/range/color/file, whose "default"
-  // sizing varies enough across browsers/OSes that a wrong exemption there
-  // risks masking a real author-introduced undersized target.
+  // not modified by the author. The canonical example is an unstyled native
+  // checkbox/radio (browsers render these well under 24px by default, and
+  // that's not the author's choice). Scoped narrowly to
+  // input[type=checkbox]/[type=radio] specifically, the only form-control
+  // types with a universally-recognized, unambiguous native rendering, and
+  // not extended to select/range/color/file, whose "default" sizing varies
+  // enough across browsers/OSes that a wrong exemption there risks masking a
+  // real author-introduced undersized target.
   //
   // Detection signal: `appearance` (or the legacy `-webkit-appearance`)
   // computed as `none` is the near-universal first step of custom
-  // checkbox/radio styling across every CSS framework/design system —
-  // if the author hasn't reset it, the browser is still rendering its own
-  // default control chrome, so the size is genuinely UA-determined.
+  // checkbox/radio styling across every CSS framework/design system. If the
+  // author hasn't reset it, the browser is still rendering its own default
+  // control chrome, so the size is UA-determined rather than authored.
   function isUserAgentSizedControl(el) {
     try {
       if (!el || el.nodeType !== 1) return false;
@@ -550,8 +565,8 @@ function runInPage(ctx) {
       // Image map targets are often constrained by the underlying image.
       // Currently unreachable in practice: <area> never becomes a
       // measurable candidate at all (see the file header's "Known,
-      // deliberately unimplemented gap" note) — kept for forward
-      // compatibility if that gap is closed later.
+      // unimplemented gap" note). Kept for forward compatibility if that
+      // gap is closed later.
       if (tag === 'area') return true;
 
       // Graphics / spatial interaction regions are commonly essential by design.
@@ -575,7 +590,7 @@ function runInPage(ctx) {
 
     // User Agent Control exception: size isn't the author's choice, so the
     // size requirement (and therefore any spacing conflict stemming from
-    // it) doesn't apply at all — skip straight to pass, no need to even
+    // it) doesn't apply at all. Skip straight to pass, no need to even
     // evaluate spacing.
     if (isUserAgentSizedControl(it.el)) {
       continue;
@@ -584,91 +599,117 @@ function runInPage(ctx) {
     const info = hasSpacingConflict(it);
 
     if (!info.conflict && info.confident === false) {
-      // Ambiguous perimeter-sampling result near the decision threshold —
-      // previously recorded only as a page-level boolean with no per-target
-      // occurrence at all, so this specific target was unrecoverable from
-      // the result once any other target on the page had a confident
-      // fail (see helpers.resolveTieredOutcome's header comment). Now
-      // reported as its own cantTell-tier occurrence instead.
-      cantTellOccurrences.push({
-        selector: buildSelector(it.el),
-        html: htmlSnippet(it.el),
-        occurrenceOutcome: 'cantTell',
-        summary:
-          'Target may be too small and too close to another target, but the overlap is near the detection threshold and could not be confidently measured.',
-        hint: 'Manually verify the effective spacing between this target and its neighbor; increase target size or spacing if the overlap is real.',
-        i18n: {
-          summaryKey: 'targetSizeMinimum_summary_cantTell_ambiguousSpacing',
-          hintKey: 'targetSizeMinimum_hint_cantTell_ambiguousSpacing',
-          params: {}
-        },
-        data: {
-          details: {
-            measured: { width: it.rect.width, height: it.rect.height },
-            reasonCode: 'undersized-ambiguous-spacing',
-            conflictHitCount: info.hitCount,
-            conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+      // Ambiguous perimeter-sampling result near the decision threshold: report
+      // it as its own cantTell-tier occurrence for this target so it isn't lost
+      // once any other target on the page has a confident fail (see
+      // helpers.resolveTieredOutcome's header comment).
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(it.el, {
+          occurrenceOutcome: 'cantTell',
+          summary:
+            'Target may be too small and too close to another target, but the overlap is near the detection threshold and could not be confidently measured.',
+          hint: 'Manually verify the effective spacing between this target and its neighbor; increase target size or spacing if the overlap is real.',
+          i18n: {
+            summaryKey: 'targetSizeMinimum_summary_cantTell_ambiguousSpacing',
+            hintKey: 'targetSizeMinimum_hint_cantTell_ambiguousSpacing',
+            params: {}
+          },
+          data: {
+            details: {
+              measured: { width: it.rect.width, height: it.rect.height },
+              reasonCode: 'undersized-ambiguous-spacing',
+              conflictHitCount: info.hitCount,
+              conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+            }
           }
-        }
-      });
+        })
+      );
       continue;
     }
 
     if (info.conflict) {
       if (isPlausiblyEssentialOrEquivalent(it.el)) {
         // Confident spacing conflict, but the target may be exempt as part
-        // of an essential graphic/image-map region — same "previously
-        // unrecoverable" gap as above, now reported instead of dropped.
-        cantTellOccurrences.push({
-          selector: buildSelector(it.el),
-          html: htmlSnippet(it.el),
-          occurrenceOutcome: 'cantTell',
-          summary:
-            'Target is too small and too close to another target, but may be exempt as part of an essential graphic or image-map region.',
-          hint: 'Verify whether this target’s size is genuinely essential to its function (e.g. part of an SVG/canvas/image map); if not, increase target size or spacing.',
+        // of an essential graphic/image-map region, so report it as
+        // cantTell rather than dropping it.
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(it.el, {
+            occurrenceOutcome: 'cantTell',
+            summary:
+              'Target is too small and too close to another target, but may be exempt as part of an essential graphic or image-map region.',
+            hint: 'Verify whether this target’s size is essential to its function (e.g. part of an SVG/canvas/image map); if not, increase target size or spacing.',
+            i18n: {
+              summaryKey: 'targetSizeMinimum_summary_cantTell_plausiblyEssential',
+              hintKey: 'targetSizeMinimum_hint_cantTell_plausiblyEssential',
+              params: {}
+            },
+            data: {
+              details: {
+                measured: { width: it.rect.width, height: it.rect.height },
+                reasonCode: 'undersized-plausibly-essential',
+                conflictHitCount: info.hitCount,
+                conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+              }
+            }
+          })
+        );
+        continue;
+      }
+
+      // This target and its conflicting neighbor are both inline links in the
+      // same text run, where the SC 2.5.8 inline exception may apply. That
+      // can't be decided from geometry alone, so defer to manual review.
+      if (isInlineLinkTarget(it.el) && info.conflictEl && isInlineLinkTarget(info.conflictEl)) {
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(it.el, {
+            occurrenceOutcome: 'cantTell',
+            summary:
+              'Target is smaller than 24×24 CSS px and close to another inline link in the same run of text, where the inline exception may apply.',
+            hint: 'Confirm whether these links form a run of inline text (which is exempt); otherwise increase the target size to at least 24×24 CSS px or add spacing.',
+            i18n: {
+              summaryKey: 'targetSizeMinimum_summary_cantTell_inlineLinkRun',
+              hintKey: 'targetSizeMinimum_hint_cantTell_inlineLinkRun',
+              params: {}
+            },
+            data: {
+              details: {
+                measured: { width: it.rect.width, height: it.rect.height },
+                reasonCode: 'undersized-inline-link-run',
+                conflictHitCount: info.hitCount,
+                conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+              }
+            }
+          })
+        );
+        continue;
+      }
+
+      failOccurrences.push(
+        helpers.reportOccurrence(it.el, {
+          occurrenceOutcome: 'fail',
+          summary: 'Target is too small and too close to another target.',
+          hint: 'Increase target size to at least 24 by 24 CSS pixels, or add sufficient spacing.',
           i18n: {
-            summaryKey: 'targetSizeMinimum_summary_cantTell_plausiblyEssential',
-            hintKey: 'targetSizeMinimum_hint_cantTell_plausiblyEssential',
+            summaryKey: 'targetSizeMinimum_summary_fail',
+            hintKey: 'targetSizeMinimum_hint_fail',
             params: {}
           },
           data: {
             details: {
               measured: { width: it.rect.width, height: it.rect.height },
-              reasonCode: 'undersized-plausibly-essential',
+              reasonCode: 'undersized-and-too-close',
               conflictHitCount: info.hitCount,
               conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
             }
           }
-        });
-        continue;
-      }
-
-      failOccurrences.push({
-        selector: buildSelector(it.el),
-        html: htmlSnippet(it.el),
-        occurrenceOutcome: 'fail',
-        summary: 'Target is too small and too close to another target.',
-        hint: 'Increase target size to at least 24 by 24 CSS pixels, or add sufficient spacing.',
-        i18n: {
-          summaryKey: 'targetSizeMinimum_summary_fail',
-          hintKey: 'targetSizeMinimum_hint_fail',
-          params: {}
-        },
-        data: {
-          details: {
-            measured: { width: it.rect.width, height: it.rect.height },
-            reasonCode: 'undersized-and-too-close',
-            conflictHitCount: info.hitCount,
-            conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
-          }
-        }
-      });
+        })
+      );
     }
   }
 
   // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
   // a fail-tier finding never silently discards cantTell-tier findings from
-  // the same run — both are returned together when the outcome is 'fail'.
+  // the same run. Both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     cantTellOccurrences,

package/src/checks/automatic/td-has-header.js

@@ -11,7 +11,7 @@
  * @applicability
  *   `<table>` elements with at least 4 rows and at least 4 columns
  *   (a "large" table, where implicit row/column header association is
- *   genuinely useful — small tables are usually self-evident), and with
+ *   useful; small tables are usually self-evident), and with
  *   NO `colspan`/`rowspan` anywhere in the table.
  * @expectation
  *   Every `<td>` has an associated header, via one of:
@@ -22,14 +22,14 @@
  *       earlier row, OR
  *     - an implicit row header: some `<th>` earlier in the same row.
  * @implementation-notes
- * - Closes the gap `table-th-has-data-cells` deliberately deferred (see
+ * - Closes the gap `table-th-has-data-cells` deferred (see
  *   that rule's own implementation notes): this is the fuller positional
- *   header-association algorithm, but still intentionally scoped —
+ *   header-association algorithm, but still intentionally scoped,
  *   tables with any `colspan`/`rowspan` are skipped entirely (marked
  *   `notApplicable`) rather than risk a wrong column-index computation
  *   producing a false `fail`.
  * - The `headers`-attribute branch does not itself validate that the
- *   referenced ids exist or point at `<th>` elements — that's already
+ *   referenced ids exist or point at `<th>` elements, that's already
  *   `table-headers-attr-valid`'s job.
  */
 
@@ -38,7 +38,7 @@ const id = 'td-has-header';
 const meta = {
   title: 'Data cells in large tables must have an associated header',
   description:
-    'Checks that every <td> in a large, simple (no colspan/rowspan) table has an associated header — via a headers attribute, an implicit column <th> above it, or an implicit row <th> to its left.',
+    'Checks that every <td> in a large, simple (no colspan/rowspan) table has an associated header, via a headers attribute, an implicit column <th> above it, or an implicit row <th> to its left.',
   i18n: {
     titleKey: 'tdHasHeader_title',
     descriptionKey: 'tdHasHeader_description'
@@ -150,26 +150,21 @@ function runInPage(ctx) {
         if (hasColumnHeaderAbove(r, c)) continue;
         if (hasRowHeaderBefore(r, c)) continue;
 
-        const stableSelector = helpers.buildSelector ? helpers.buildSelector(cell) : 'html';
-        const html = helpers.getOuterHtmlSnippet
-          ? helpers.getOuterHtmlSnippet(cell)
-          : cell.outerHTML || '';
-
-        occurrences.push({
-          selector: stableSelector,
-          html,
-          summary:
-            'This data cell has no associated header (no headers attribute, no column <th> above it, no row <th> to its left).',
-          hint: 'Add a headers attribute referencing the relevant <th> id(s), or restructure the table so this cell has an implicit row/column header.',
-          i18n: {
-            summaryKey: 'tdHasHeader_summary_fail',
-            hintKey: 'tdHasHeader_hint_fail',
-            params: { row: String(r), column: String(c) }
-          },
-          data: {
-            details: { reasonCode: 'TD_NO_ASSOCIATED_HEADER', row: r, column: c }
-          }
-        });
+        occurrences.push(
+          helpers.reportOccurrence(cell, {
+            summary:
+              'This data cell has no associated header (no headers attribute, no column <th> above it, no row <th> to its left).',
+            hint: 'Add a headers attribute referencing the relevant <th> id(s), or restructure the table so this cell has an implicit row/column header.',
+            i18n: {
+              summaryKey: 'tdHasHeader_summary_fail',
+              hintKey: 'tdHasHeader_hint_fail',
+              params: { row: String(r), column: String(c) }
+            },
+            data: {
+              details: { reasonCode: 'TD_NO_ASSOCIATED_HEADER', row: r, column: c }
+            }
+          })
+        );
       }
     }
   }

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check textbox-name-present
+ * @atomic true
+ * @summary Elements with role="textbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="textbox" (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="textbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom textbox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="textbox">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'textbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Textboxes have an accessible name',
+  description: 'Checks that elements with role="textbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'textboxNamePresent_title',
     descriptionKey: 'textboxNamePresent_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).
@@ -227,24 +247,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      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 textbox's accessible name.",
-      i18n: {
-        summaryKey: 'textboxNamePresent_summary_fail',
-        hintKey: 'textboxNamePresent_hint_fail',
-        params: { controlType: 'textbox' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'textbox', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    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 textbox's accessible name.",
+        i18n: {
+          summaryKey: 'textboxNamePresent_summary_fail',
+          hintKey: 'textboxNamePresent_hint_fail',
+          params: { controlType: 'textbox' }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'textbox', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {