@surea11y/core 1.4.1 → 1.6.0

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check progressbar-name-present
+ * @atomic true
+ * @summary Elements with role="progressbar" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to elements carrying role="progressbar" (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="progressbar" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom progressbar widget is not
+ *   reliably exposed as its name.
+ */
+
 const id = 'progressbar-name-present';
 
 const meta = {
@@ -54,7 +73,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).
@@ -106,10 +125,10 @@ function runInPage(ctx) {
     if (title) return { ok: true, method: 'title' };
 
     // role="progressbar" is name-from-author-only per WAI-ARIA: aria-label,
-    // aria-labelledby, or title — no content-based naming method at all. It
+    // aria-labelledby, or title, no content-based naming method at all. It
     // must NOT fall back to subtree content: e.g. a <ul role="progressbar">
     // loading skeleton with no name of its own, whose nested descendants
-    // carry their own aria-label for a different purpose — falling back to
+    // carry their own aria-label for a different purpose, falling back to
     // subtree content would wrongly treat that as the progressbar's name.
     return { ok: false, method: 'none' };
   }
@@ -135,28 +154,26 @@ 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 progress bar has no accessible name.',
-      hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this progress bar's accessible name.",
-      i18n: {
-        summaryKey: 'progressbarNamePresent_summary_fail',
-        hintKey: 'progressbarNamePresent_hint_fail',
-        params: {}
-      },
-      data: {
-        details: {
-          reasonCode: 'name_missing',
-          controlType: 'progressbar',
-          methodTried: res.method
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This progress bar has no accessible name.',
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this progress bar's accessible name.",
+        i18n: {
+          summaryKey: 'progressbarNamePresent_summary_fail',
+          hintKey: 'progressbarNamePresent_hint_fail',
+          params: {}
         },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+        data: {
+          details: {
+            reasonCode: 'name_missing',
+            controlType: 'progressbar',
+            methodTried: res.method
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -5,26 +5,36 @@
 /**
  * @check role-img-text-alternative-present
  * @atomic true
- * @summary Accessible elements with role="img" must have an alternative text via aria-label or aria-labelledby
+ * @summary Accessible elements with role="img"/"graphics-symbol"/"graphics-document" must have a text alternative
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to elements with role="img" that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to elements with role="img", role="graphics-symbol" or
+ *   role="graphics-document" that are included in the accessibility tree
+ *   (ACT 23a2a8's "programmatically hidden" exemption:
+ *   display:none/visibility:hidden/aria-hidden="true" on the element or an
+ *   ancestor, with no carve-out for focusable or IDREF-referenced elements,
+ *   aria-hidden-focus and duplicate-id-aria own those separately). Per ACT
+ *   7d6734, this reaches any element carrying one of these roles, not only
+ *   the <svg> root, e.g. a <circle role="graphics-symbol"> nested inside a
+ *   plain <svg>. The <svg> root itself is left to svg-text-alternative-present's
+ *   own (already ACT-clean) title/aria-name handling; the <img> tag is
+ *   excluded here since it has its own dedicated rule.
  * @expectation
- *   Each applicable element with role="img" has an accessible text alternative:
+ *   Each applicable element has an accessible text alternative:
  *    - aria-label with a non-empty value; OR
  *    - aria-labelledby referencing at least one existing element that contributes non-empty text; OR
- *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM).
+ *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM); OR
+ *    - for an SVG-namespace element, a non-empty first-child <title> (SVG-AAM's own naming mechanism, not only for the <svg> root).
  */
 
 const id = 'role-img-text-alternative-present';
 
 const meta = {
-  title: '[role="img"] must have an accessible text alternative',
+  title:
+    '[role="img"/"graphics-symbol"/"graphics-document"] must have an accessible text alternative',
   description:
-    'Checks that elements with role="img" provide an accessible text alternative via aria-label, aria-labelledby, or a title attribute.',
+    'Checks that elements with role="img", "graphics-symbol" or "graphics-document" provide an accessible text alternative using aria-label, aria-labelledby, a title attribute, or (for SVG elements) a first-child <title>.',
   i18n: {
     titleKey: 'roleImg_textAlternativePresent_title',
     descriptionKey: 'roleImg_textAlternativePresent_description'
@@ -86,7 +96,7 @@ function runInPage(ctx) {
 
   const imgElements = (() => {
     // do not consider element "img" because it has its own rule
-    const sel = '[role="img" i]:not(img)';
+    const sel = '[role="img" i]:not(img), [role="graphics-symbol" i], [role="graphics-document" i]';
     try {
       return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []);
     } catch {
@@ -101,8 +111,16 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // ACT 23a2a8 (same rule as native img-alt-present) exempts programmatically
+  // hidden images and that glossary term has no focusability carve-out, so a
+  // tabbable/IDREF-referenced role="img" inside aria-hidden stays out of
+  // scope here too; aria-hidden-focus reports that markup instead.
   const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getAccessibleNameInfo =
     helpers && typeof helpers.getAccessibleNameInfo === 'function'
@@ -122,10 +140,21 @@ function runInPage(ctx) {
         }
       })();
       if (elig && elig.eligible === false) continue;
+      // isIncludedInAccessibilityTree returns a plain boolean, not an
+      // {eligible, reasons} object like isAccTreeEligible's fallback shape.
+      if (typeof elig === 'boolean' && elig === false) continue;
     }
 
     applicableCount += 1;
 
+    const matchedRole = (() => {
+      try {
+        return trim(el.getAttribute('role')).split(/\s+/)[0].toLowerCase();
+      } catch {
+        return 'img';
+      }
+    })();
+
     // Expectation: aria-label OR aria-labelledby. We use helper name-info when available,
     // but we also validate the source to keep this rule scoped/deterministic.
 
@@ -163,6 +192,25 @@ function runInPage(ctx) {
     })();
     const hasValidTitle = titleRaw !== null && trim(titleRaw).length > 0;
 
+    // SVG-AAM's own accessible-name mechanism: a first-child <title>
+    // element (not the HTML title attribute) is the standard way to name
+    // any element in the SVG namespace, not only the <svg> root -- a
+    // role="graphics-symbol" <circle> named only this way still has a real
+    // text alternative, same as a role="img" <svg>.
+    const svgTitleChildText = (() => {
+      try {
+        const isSvgNamespace = el.namespaceURI === 'http://www.w3.org/2000/svg';
+        if (!isSvgNamespace) return '';
+        const first = el.firstElementChild;
+        const firstTag = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+        if (firstTag !== 'title') return '';
+        return trim(first.textContent);
+      } catch {
+        return '';
+      }
+    })();
+    const hasValidTitleSource = hasValidTitle || !!svgTitleChildText;
+
     let nameInfo = null;
 
     // Fast outcomes first (no helper needed)
@@ -170,19 +218,19 @@ function runInPage(ctx) {
     let hasName = false;
 
     if (!hasAriaLabelAttr && !hasAriaLabelledbyAttr) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'missingTextAlternative';
       }
     } else if (hasAriaLabelAttr && !hasValidAriaLabel) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'emptyAriaLabel';
       }
     } else if (hasAriaLabelledbyAttr && !hasValidAriaLabelledbyAttr) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'emptyAriaLabelledby';
@@ -214,12 +262,12 @@ function runInPage(ctx) {
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
     const baseOccurrence = {
-      summary: 'Missing text alternative on element with role="img".',
-      hint: 'Provide aria-label or aria-labelledby (referencing non-empty text) to give this image a text alternative.',
+      summary: `Missing text alternative on element with role="${matchedRole}".`,
+      hint: 'Provide aria-label or aria-labelledby (referencing non-empty text) to give this element a text alternative.',
       i18n: {
         summaryKey: 'roleImg_textAlternativePresent_summary_fail',
         hintKey: 'roleImg_textAlternativePresent_hint_fail',
-        params: { role: 'img' }
+        params: { role: matchedRole }
       },
       data: {
         details: {

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check searchbox-name-present
+ * @atomic true
+ * @summary Elements with role="searchbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="searchbox" (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="searchbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom searchbox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="searchbox">)
+ *   an associated <label> counts as well.
+ */
+
 const id = 'searchbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Searchboxes have an accessible name',
+  description: 'Checks that elements with role="searchbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'searchboxNamePresent_title',
     descriptionKey: 'searchboxNamePresent_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,26 @@ 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 searchbox's accessible name.",
-      i18n: {
-        summaryKey: 'searchboxNamePresent_summary_fail',
-        hintKey: 'searchboxNamePresent_hint_fail',
-        params: { controlType: 'searchbox' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'searchbox', 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 searchbox's accessible name.",
+        i18n: {
+          summaryKey: 'searchboxNamePresent_summary_fail',
+          hintKey: 'searchboxNamePresent_hint_fail',
+          params: { controlType: 'searchbox' }
+        },
+        data: {
+          details: {
+            reasonCode: 'name_missing',
+            controlType: 'searchbox',
+            methodTried: res.method
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/server-side-image-map-absent.js

@@ -13,7 +13,7 @@
  * @expectation
  *   The image does not use ismap at all. Server-side image maps depend on
  *   the browser sending click coordinates to the server, which has no
- *   keyboard-operable equivalent — there is no way to determine or expose
+ *   keyboard-operable equivalent, there is no way to determine or expose
  *   individual clickable regions to assistive technology or keyboard
  *   users. Client-side image maps (<map>/<area>, each with real href/alt)
  *   are the accessible alternative and are not flagged by this rule.
@@ -66,24 +66,21 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This image uses a server-side image map, which has no keyboard-operable equivalent.',
-      hint: 'Replace the server-side image map (ismap) with a client-side image map (<map>/<area>) or separate accessible links/buttons.',
-      i18n: {
-        summaryKey: 'serverSideImageMapAbsent_summary_fail',
-        hintKey: 'serverSideImageMapAbsent_hint_fail',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'SERVER_SIDE_IMAGE_MAP' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This image uses a server-side image map, which has no keyboard-operable equivalent.',
+        hint: 'Replace the server-side image map (ismap) with a client-side image map (<map>/<area>) or separate accessible links/buttons.',
+        i18n: {
+          summaryKey: 'serverSideImageMapAbsent_summary_fail',
+          hintKey: 'serverSideImageMapAbsent_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'SERVER_SIDE_IMAGE_MAP' }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -2,6 +2,27 @@
 
 'use strict';
 
+/**
+ * @check slider-name-present
+ * @atomic true
+ * @summary Elements with role="slider" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="slider" (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. A native <input type="range"> without the role belongs
+ *   to form-control-programmatic-label-present.
+ * @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="slider" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom slider widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="slider">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'slider-name-present';
 
 const meta = {
@@ -67,7 +88,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
@@ -84,7 +105,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).
@@ -99,10 +120,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');
@@ -112,7 +133,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).
@@ -209,7 +230,7 @@ function runInPage(ctx) {
     }
 
     // role="slider" is name-from-author-only per WAI-ARIA (unlike e.g.
-    // role="option"/"tab"), so it must NOT fall back to subtree content —
+    // role="option"/"tab"), so it must NOT fall back to subtree content,
     // visible text near/inside a custom slider widget is not reliably
     // exposed as its accessible name by assistive technologies.
     return { ok: false, method: 'none' };
@@ -242,24 +263,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 slider has no accessible name.',
-      hint: 'Provide a label, aria-label, or aria-labelledby so assistive technologies can identify the slider.',
-      i18n: {
-        summaryKey: 'sliderNamePresent_summary_fail',
-        hintKey: 'sliderNamePresent_hint_fail',
-        params: { kind }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: kind, methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This slider has no accessible name.',
+        hint: 'Provide a label, aria-label, or aria-labelledby so assistive technologies can identify the slider.',
+        i18n: {
+          summaryKey: 'sliderNamePresent_summary_fail',
+          hintKey: 'sliderNamePresent_hint_fail',
+          params: { kind }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: kind, methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check spinbutton-name-present
+ * @atomic true
+ * @summary Elements with role="spinbutton" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="spinbutton" (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="spinbutton" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom spinbutton widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="spinbutton">)
+ *   an associated <label> counts as well.
+ */
+
 const id = 'spinbutton-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Spinbuttons have an accessible name',
+  description: 'Checks that elements with role="spinbutton" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'spinbuttonNamePresent_title',
     descriptionKey: 'spinbuttonNamePresent_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,26 @@ 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 spinbutton's accessible name.",
-      i18n: {
-        summaryKey: 'spinbuttonNamePresent_summary_fail',
-        hintKey: 'spinbuttonNamePresent_hint_fail',
-        params: { controlType: 'spinbutton' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'spinbutton', 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 spinbutton's accessible name.",
+        i18n: {
+          summaryKey: 'spinbuttonNamePresent_summary_fail',
+          hintKey: 'spinbuttonNamePresent_hint_fail',
+          params: { controlType: 'spinbutton' }
+        },
+        data: {
+          details: {
+            reasonCode: 'name_missing',
+            controlType: 'spinbutton',
+            methodTried: res.method
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {