@surea11y/core 1.4.1 → 1.5.0

package/src/checks/manual/mouse-only-event-handlers-manual.js

@@ -117,30 +117,28 @@ function runInPage(ctx) {
     const hasKeyboardEquiv = KEYBOARD_EQUIV_ATTRS.some((a) => trim(el.getAttribute(a)));
     if (hasKeyboardEquiv) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This element has ${presentMouseAttrs.join(', ')} but no keyboard-reachable equivalent handler.`,
-      hint: 'Add onkeydown/onkeyup/onkeypress (or onfocus/onblur for hover-triggered behavior) so this functionality is also reachable by keyboard.',
-      i18n: {
-        summaryKey: 'mouseOnlyEventHandlers_summary_cantTell',
-        hintKey: 'mouseOnlyEventHandlers_hint_cantTell',
-        params: { attrs: presentMouseAttrs.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'MOUSE_ONLY_HANDLER_NO_KEYBOARD_EQUIVALENT',
-          mouseAttrs: presentMouseAttrs
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This element has ${presentMouseAttrs.join(', ')} but no keyboard-reachable equivalent handler.`,
+        hint: 'Add onkeydown/onkeyup/onkeypress (or onfocus/onblur for hover-triggered behavior) so this functionality is also reachable by keyboard.',
+        i18n: {
+          summaryKey: 'mouseOnlyEventHandlers_summary_cantTell',
+          hintKey: 'mouseOnlyEventHandlers_hint_cantTell',
+          params: { attrs: presentMouseAttrs.join(', ') }
         },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+        data: {
+          details: {
+            reasonCode: 'MOUSE_ONLY_HANDLER_NO_KEYBOARD_EQUIVALENT',
+            mouseAttrs: presentMouseAttrs
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/page-has-heading-one-manual.js

@@ -126,19 +126,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   return {
     ruleId: rule.ruleId,
     outcome: 'cantTell',
     severity: rule.defaultSeverity || 'minor',
     occurrences: [
-      {
-        selector: stableSelector,
-        html,
+      helpers.reportOccurrence(body, {
         summary: 'This page has no level-one heading.',
         hint: 'Add a level-one heading (<h1> or role="heading" aria-level="1") that identifies the page\'s main content.',
         i18n: {
@@ -149,7 +142,7 @@ function runInPage(ctx) {
         data: {
           details: { reasonCode: 'HEADING_ONE_MISSING' }
         }
-      }
+      })
     ]
   };
 }

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -171,28 +171,26 @@ function runInPage(ctx) {
       String(el.getAttribute('role') || '')
         .trim()
         .toLowerCase() || 'presentation';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
-      hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'presentationRoleConflict_summary_cantTell',
-        hintKey: 'presentationRoleConflict_hint_cantTell',
-        params: { role, attrs: parts.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'PRESENTATION_ROLE_CONFLICT',
-          role,
-          conflictingAttrs: present,
-          focusable: isFocusable
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
+        hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'presentationRoleConflict_summary_cantTell',
+          hintKey: 'presentationRoleConflict_hint_cantTell',
+          params: { role, attrs: parts.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'PRESENTATION_ROLE_CONFLICT',
+            role,
+            conflictingAttrs: present,
+            focusable: isFocusable
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/region-manual.js

@@ -352,14 +352,11 @@ function runInPage(ctx) {
     }
   }
 
+  // Report the element itself: without a node reference the engine re-finds
+  // each one with document.querySelector to build its structuralPath.
   const occurrences = collapsed.map((el) => {
     const tag = el.tagName ? lower(el.tagName) : '';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    const partial = {
       summary: 'This content is not contained within a landmark region.',
       hint: 'Move this content inside a landmark region (main, nav, aside, a labeled section, etc.).',
       i18n: {
@@ -371,6 +368,16 @@ function runInPage(ctx) {
         details: { reasonCode: 'CONTENT_OUTSIDE_LANDMARK', element: tag }
       }
     };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      return helpers.reportOccurrence(el, partial);
+    }
+
+    return {
+      selector: helpers.buildSelector ? helpers.buildSelector(el) : 'html',
+      html: helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '',
+      ...partial
+    };
   });
 
   if (occurrences.length === 0) {

package/src/checks/manual/scope-attr-valid-manual.js

@@ -61,23 +61,20 @@ function runInPage(ctx) {
 
     if (VALID_SCOPES.has(raw.toLowerCase())) 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 scope attribute value is not recognized.',
-      hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
-      i18n: {
-        summaryKey: 'scopeAttrValid_summary_cantTell',
-        hintKey: 'scopeAttrValid_hint_cantTell',
-        params: { value: raw }
-      },
-      data: {
-        details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This scope attribute value is not recognized.',
+        hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
+        i18n: {
+          summaryKey: 'scopeAttrValid_summary_cantTell',
+          hintKey: 'scopeAttrValid_hint_cantTell',
+          params: { value: raw }
+        },
+        data: {
+          details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/skip-link-manual.js

@@ -184,59 +184,51 @@ function runInPage(ctx) {
       const unusableByGeometry = !!geometryReasonCode;
       if (!unusableByAcc && !unusableByGeometry) continue;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This skip link points to a target that exists but is not currently usable.',
+          hint: 'Point this skip link to a target that is exposed and usable as a navigation destination.',
+          i18n: {
+            summaryKey: 'skipLink_summary_unusableTarget_cantTell',
+            hintKey: 'skipLink_hint_unusableTarget_cantTell',
+            params: { href }
+          },
+          data: {
+            details: {
+              reasonCode: 'SKIP_LINK_TARGET_UNUSABLE',
+              href,
+              unusableReasonCode: unusableByAcc ? 'ACC_TREE_INELIGIBLE' : geometryReasonCode,
+              targetSelector: helpers.buildSelector ? helpers.buildSelector(target) : null,
+              geometryCheckEnabled: geometrySupported
+            },
+            visibilityFilter: {
+              targetSet: 'acc',
+              accEligible: accEligibility.eligible,
+              reasons: accEligibility.reasons
+            },
+            targetGeometry: geometryEligibility
+              ? { eligible: geometryEligibility.eligible, reasons: geometryEligibility.reasons }
+              : { eligible: null, reasons: [] }
+          }
+        })
+      );
+      continue;
+    }
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This skip link points to a target that exists but is not currently usable.',
-        hint: 'Point this skip link to a target that is exposed and usable as a navigation destination.',
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: "This skip link's target does not exist.",
+        hint: "Point the skip link's href at an id that exists in the document, or add the missing target element.",
         i18n: {
-          summaryKey: 'skipLink_summary_unusableTarget_cantTell',
-          hintKey: 'skipLink_hint_unusableTarget_cantTell',
+          summaryKey: 'skipLink_summary_cantTell',
+          hintKey: 'skipLink_hint_cantTell',
           params: { href }
         },
         data: {
-          details: {
-            reasonCode: 'SKIP_LINK_TARGET_UNUSABLE',
-            href,
-            unusableReasonCode: unusableByAcc ? 'ACC_TREE_INELIGIBLE' : geometryReasonCode,
-            targetSelector: helpers.buildSelector ? helpers.buildSelector(target) : null,
-            geometryCheckEnabled: geometrySupported
-          },
-          visibilityFilter: {
-            targetSet: 'acc',
-            accEligible: accEligibility.eligible,
-            reasons: accEligibility.reasons
-          },
-          targetGeometry: geometryEligibility
-            ? { eligible: geometryEligibility.eligible, reasons: geometryEligibility.reasons }
-            : { eligible: null, reasons: [] }
+          details: { reasonCode: 'SKIP_LINK_TARGET_MISSING', href }
         }
-      });
-      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 skip link's target does not exist.",
-      hint: "Point the skip link's href at an id that exists in the document, or add the missing target element.",
-      i18n: {
-        summaryKey: 'skipLink_summary_cantTell',
-        hintKey: 'skipLink_hint_cantTell',
-        params: { href }
-      },
-      data: {
-        details: { reasonCode: 'SKIP_LINK_TARGET_MISSING', href }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/tabindex-manual.js

@@ -62,23 +62,20 @@ function runInPage(ctx) {
 
     if (n <= 0) 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 element has a positive tabindex, overriding the natural tab order.',
-      hint: 'Use tabindex="0" (or a negative value to remove from tab order) instead of a positive number; fix the DOM order if a different tab order is needed.',
-      i18n: {
-        summaryKey: 'tabindex_summary_cantTell',
-        hintKey: 'tabindex_hint_cantTell',
-        params: { value: String(n) }
-      },
-      data: {
-        details: { reasonCode: 'TABINDEX_POSITIVE', value: n }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This element has a positive tabindex, overriding the natural tab order.',
+        hint: 'Use tabindex="0" (or a negative value to remove from tab order) instead of a positive number; fix the DOM order if a different tab order is needed.',
+        i18n: {
+          summaryKey: 'tabindex_summary_cantTell',
+          hintKey: 'tabindex_hint_cantTell',
+          params: { value: String(n) }
+        },
+        data: {
+          details: { reasonCode: 'TABINDEX_POSITIVE', value: n }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/table-duplicate-name-manual.js

@@ -73,23 +73,20 @@ function runInPage(ctx) {
 
     if (captionText.toLowerCase() !== summary.toLowerCase()) 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 table's caption duplicates its summary attribute.",
-      hint: 'Remove the redundant summary attribute, or make it provide different information than the caption.',
-      i18n: {
-        summaryKey: 'tableDuplicateName_summary_cantTell',
-        hintKey: 'tableDuplicateName_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'TABLE_CAPTION_SUMMARY_DUPLICATE' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: "This table's caption duplicates its summary attribute.",
+        hint: 'Remove the redundant summary attribute, or make it provide different information than the caption.',
+        i18n: {
+          summaryKey: 'tableDuplicateName_summary_cantTell',
+          hintKey: 'tableDuplicateName_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'TABLE_CAPTION_SUMMARY_DUPLICATE' }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {