@surea11y/core 1.4.1 → 1.5.0

package/src/checks/automatic/form-control-single-label.js

@@ -140,51 +140,49 @@ function runInPage(ctx) {
       : [...eligibleLabels];
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     if (contributing.length >= 2) {
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This form control is associated with more than one <label>.',
-        hint: 'Keep only one <label> per form control (either wrapping it or referencing it via for/id).',
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'formControlSingleLabel_summary_fail',
-          hintKey: 'formControlSingleLabel_hint_fail',
-          params: { element: tag, labelCount: String(contributing.length) }
-        },
-        data: {
-          details: {
-            reasonCode: 'FORM_FIELD_MULTIPLE_LABELS',
-            element: tag,
-            labelCount: contributing.length
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This form control is associated with more than one <label>.',
+          hint: 'Keep only one <label> per form control (either wrapping it or referencing it via for/id).',
+          occurrenceOutcome: 'fail',
+          i18n: {
+            summaryKey: 'formControlSingleLabel_summary_fail',
+            hintKey: 'formControlSingleLabel_hint_fail',
+            params: { element: tag, labelCount: String(contributing.length) }
+          },
+          data: {
+            details: {
+              reasonCode: 'FORM_FIELD_MULTIPLE_LABELS',
+              element: tag,
+              labelCount: contributing.length
+            }
           }
-        }
-      });
+        })
+      );
     } else if (contributing.length === 1) {
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This form control has one labelling <label> plus an extra empty <label> association.',
-        hint: 'Remove the redundant empty <label> so exactly one <label> is associated with the control.',
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'formControlSingleLabel_summary_cantTell',
-          hintKey: 'formControlSingleLabel_hint_cantTell',
-          params: { element: tag, labelCount: String(eligibleLabels.size) }
-        },
-        data: {
-          details: {
-            reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',
-            element: tag,
-            labelCount: eligibleLabels.size,
-            contributingLabelCount: contributing.length
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This form control has one labelling <label> plus an extra empty <label> association.',
+          hint: 'Remove the redundant empty <label> so exactly one <label> is associated with the control.',
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'formControlSingleLabel_summary_cantTell',
+            hintKey: 'formControlSingleLabel_hint_cantTell',
+            params: { element: tag, labelCount: String(eligibleLabels.size) }
+          },
+          data: {
+            details: {
+              reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',
+              element: tag,
+              labelCount: eligibleLabels.size,
+              contributingLabelCount: contributing.length
+            }
           }
-        }
-      });
+        })
+      );
     }
     // contributing.length === 0: no label carries text, so nothing competes
     // for the name. A control left unnamed is form-control-programmatic-

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -84,15 +84,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(html) : 'html';
-  const htmlSnippet = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(html)
-    : (html.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html: htmlSnippet,
+    helpers.reportOccurrence(html, {
       summary: `The lang ("${lang}") and xml:lang ("${xmlLang}") attributes declare different languages.`,
       hint: 'Make lang and xml:lang declare the same primary language, or remove the deprecated xml:lang attribute.',
       i18n: {
@@ -103,7 +96,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'HTML_XML_LANG_MISMATCH', lang, xmlLang }
       }
-    }
+    })
   ];
 
   return {

package/src/checks/automatic/iframe-focusable-content.js

@@ -322,47 +322,45 @@ function runInPage(ctx) {
     if (!candidates.length) continue;
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const shouldProbe = candidates.length === 1;
     const runtimeProbe = shouldProbe
       ? probeImmediateFocusRedirect(el, contentDoc, candidates[0])
       : null;
 
     if (runtimeProbe && runtimeProbe.redirected) {
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
-        hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
-        i18n: null,
-        data: {
-          details: {
-            reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
-            element: tag,
-            runtimeProbe
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
+          hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
+          i18n: null,
+          data: {
+            details: {
+              reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
+              element: tag,
+              runtimeProbe
+            }
           }
-        }
-      });
+        })
+      );
       continue;
     }
 
-    failOccurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
-      hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
-      i18n: {
-        summaryKey: 'iframeFocusableContent_summary_fail',
-        hintKey: 'iframeFocusableContent_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
-      }
-    });
+    failOccurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
+        hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
+        i18n: {
+          summaryKey: 'iframeFocusableContent_summary_fail',
+          hintKey: 'iframeFocusableContent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -88,24 +88,22 @@ function runInPage(ctx) {
         })()
       : null;
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This frame has no accessible name.',
-      hint: 'Add a title attribute (or aria-label/aria-labelledby) describing the frame’s content or purpose.',
-      i18n: {
-        summaryKey: 'iframeNamePresent_summary_fail',
-        hintKey: 'iframeNamePresent_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'IFRAME_NAME_MISSING', element: tag },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This frame has no accessible name.',
+        hint: 'Add a title attribute (or aria-label/aria-labelledby) describing the frame’s content or purpose.',
+        i18n: {
+          summaryKey: 'iframeNamePresent_summary_fail',
+          hintKey: 'iframeNamePresent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'IFRAME_NAME_MISSING', element: tag },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -89,30 +89,25 @@ function runInPage(ctx) {
 
     for (const el of els) {
       const tag = el.tagName.toLowerCase();
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This frame’s title is not unique among the frames on this page.',
-        hint: 'Give each frame a distinct title describing its specific content or purpose.',
-        i18n: {
-          summaryKey: 'iframeTitleUnique_summary_fail',
-          hintKey: 'iframeTitleUnique_hint_fail',
-          params: { element: tag, title }
-        },
-        data: {
-          details: {
-            reasonCode: 'IFRAME_TITLE_DUPLICATE',
-            element: tag,
-            title,
-            duplicateCount: els.length
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This frame’s title is not unique among the frames on this page.',
+          hint: 'Give each frame a distinct title describing its specific content or purpose.',
+          i18n: {
+            summaryKey: 'iframeTitleUnique_summary_fail',
+            hintKey: 'iframeTitleUnique_hint_fail',
+            params: { element: tag, title }
+          },
+          data: {
+            details: {
+              reasonCode: 'IFRAME_TITLE_DUPLICATE',
+              element: tag,
+              title,
+              duplicateCount: els.length
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -366,43 +366,38 @@ function runInPage(ctx) {
     }
 
     if (!contains) {
-      const selectorOut = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: selectorOut,
-        html,
-        ...(uncertainty ? { outcome: 'cantTell' } : null),
-        summary: uncertainty
-          ? 'Accessible name may not contain the visible label text.'
-          : 'Accessible name does not contain the visible label text.',
-        hint: uncertainty
-          ? 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.'
-          : 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
-        i18n: {
-          summaryKey: uncertainty ? 'labelInName_summary_cantTell' : 'labelInName_summary_fail',
-          hintKey: uncertainty ? 'labelInName_hint_cantTell' : 'labelInName_hint_fail',
-          params: {
-            element: getElementDescriptor(el),
-            visibleLabel: clipForSummary(visibleLabel),
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          ...(uncertainty ? { outcome: 'cantTell' } : null),
+          summary: uncertainty
+            ? 'Accessible name may not contain the visible label text.'
+            : 'Accessible name does not contain the visible label text.',
+          hint: uncertainty
+            ? 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.'
+            : 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
+          i18n: {
+            summaryKey: uncertainty ? 'labelInName_summary_cantTell' : 'labelInName_summary_fail',
+            hintKey: uncertainty ? 'labelInName_hint_cantTell' : 'labelInName_hint_fail',
+            params: {
+              element: getElementDescriptor(el),
+              visibleLabel: clipForSummary(visibleLabel),
+              labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+              nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+              visibleLabel,
+              accessibleName: accName,
+              normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
+              tokenized: { visibleLabel: labelTokens, accessibleName: nameTokens },
+              labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+              nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+            }
           }
-        },
-        data: {
-          details: {
-            reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
-            visibleLabel,
-            accessibleName: accName,
-            normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
-            tokenized: { visibleLabel: labelTokens, accessibleName: nameTokens },
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
-          }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -215,31 +215,29 @@ function runInPage(ctx) {
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
     const ratioStr = c.round2 ? c.round2(ratio) : String(ratio);
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
-      hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
-      i18n: {
-        summaryKey: 'linkInTextBlock_summary_fail',
-        hintKey: 'linkInTextBlock_hint_fail',
-        params: { element: tag, ratio: String(ratioStr), threshold: '3' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: {
-          reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
-          metrics: { ratio, threshold: 3 },
-          colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
+        hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
+        i18n: {
+          summaryKey: 'linkInTextBlock_summary_fail',
+          hintKey: 'linkInTextBlock_hint_fail',
+          params: { element: tag, ratio: String(ratioStr), threshold: '3' }
+        },
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
+            metrics: { ratio, threshold: 3 },
+            colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -139,39 +139,34 @@ function runInPage(ctx) {
         ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
         : null;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
       const tag = (el.tagName || '').toLowerCase();
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-
-        // Human fallbacks (allowed)
-        summary: 'This link has no accessible name.',
-        hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
-
-        // Validator requires these keys to exist in the English dictionary
-        i18n: {
-          summaryKey: 'linkNamePresent_summary_fail',
-          hintKey: 'linkNamePresent_hint_fail',
-          params: { element: tag }
-        },
-
-        data: {
-          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-          details: {
-            reasonCode: 'name_missing',
-            metrics: {
-              programmaticNameLength: programmaticName.trim().length,
-              contentNameLength: contentName.trim().length
-            },
-            refs: { accessibleName: nameInfo || null }
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          // Human fallbacks (allowed)
+          summary: 'This link has no accessible name.',
+          hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
+
+          // Validator requires these keys to exist in the English dictionary
+          i18n: {
+            summaryKey: 'linkNamePresent_summary_fail',
+            hintKey: 'linkNamePresent_hint_fail',
+            params: { element: tag }
+          },
+
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: {
+              reasonCode: 'name_missing',
+              metrics: {
+                programmaticNameLength: programmaticName.trim().length,
+                contentNameLength: contentName.trim().length
+              },
+              refs: { accessibleName: nameInfo || null }
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -122,23 +122,21 @@ function runInPage(ctx) {
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list contains a direct child that is not a list item.',
-      hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
-      i18n: {
-        summaryKey: 'listChildrenValid_summary_fail',
-        hintKey: 'listChildrenValid_hint_fail',
-        params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
-      },
-      data: {
-        details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list contains a direct child that is not a list item.',
+        hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
+        i18n: {
+          summaryKey: 'listChildrenValid_summary_fail',
+          hintKey: 'listChildrenValid_hint_fail',
+          params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
+        },
+        data: {
+          details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -227,24 +227,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 listbox's accessible name.",
-      i18n: {
-        summaryKey: 'listboxNamePresent_summary_fail',
-        hintKey: 'listboxNamePresent_hint_fail',
-        params: { controlType: 'listbox' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'listbox', 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 listbox's accessible name.",
+        i18n: {
+          summaryKey: 'listboxNamePresent_summary_fail',
+          hintKey: 'listboxNamePresent_hint_fail',
+          params: { controlType: 'listbox' }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'listbox', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -116,23 +116,20 @@ function runInPage(ctx) {
 
     if (valid) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list item is not contained by a list container.',
-      hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
-      i18n: {
-        summaryKey: 'listitemParentValid_summary_fail',
-        hintKey: 'listitemParentValid_hint_fail',
-        params: { parentElement: parentTag }
-      },
-      data: {
-        details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list item is not contained by a list container.',
+        hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
+        i18n: {
+          summaryKey: 'listitemParentValid_summary_fail',
+          hintKey: 'listitemParentValid_hint_fail',
+          params: { parentElement: parentTag }
+        },
+        data: {
+          details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {