@surea11y/core 1.4.1 → 1.6.0

package/src/checks/manual/landmark-main-is-top-level-manual.js

@@ -6,7 +6,7 @@
  * @check landmark-main-is-top-level
  * @atomic true
  * @summary The main landmark must not be nested inside another landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever the page contains at least one main landmark
  *   (explicit role="main", or an implicit <main> element).
@@ -16,15 +16,15 @@
  *   whole-page main content area and confuses landmark-based navigation
  *   for assistive technology users.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent (this rule mirrors
  *   its structure with main in place of banner/header).
  * - Unlike landmark-banner-is-top-level/landmark-contentinfo-is-top-level
  *   (see that file's header comment), candidate selection here doesn't
  *   need to be unconditional: `<main>`'s implicit role is unconditional
- *   per HTML-AAM — unlike `<header>`/`<footer>`, nesting never suppresses
- *   it — so `getImplicitLandmarkRole`'s `main` branch is never subject to
+ *   per HTML-AAM. Unlike `<header>`/`<footer>`, nesting never suppresses
+ *   it, so `getImplicitLandmarkRole`'s `main` branch is never subject to
  *   the self-defeating candidate-selection problem those two rules guard
  *   against.
  */
@@ -81,7 +81,7 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
@@ -100,7 +100,7 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — it keeps
+      // A named <aside> is never suppressed, even when nested. It keeps
       // "complementary" when it has an accessible name, even inside
       // sectioning content. Matches landmark-unique's precedent.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
@@ -192,23 +192,20 @@ function runInPage(ctx) {
   for (const el of mains) {
     if (!hasLandmarkAncestor(el)) 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 main landmark is nested inside another landmark region.',
-      hint: 'Move the main landmark (<main>/role="main") so it is not contained by another landmark; main should be a top-level region of the page.',
-      i18n: {
-        summaryKey: 'landmarkMainIsTopLevel_summary_cantTell',
-        hintKey: 'landmarkMainIsTopLevel_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'LANDMARK_MAIN_NOT_TOP_LEVEL' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This main landmark is nested inside another landmark region.',
+        hint: 'Move the main landmark (<main>/role="main") so it is not contained by another landmark; main should be a top-level region of the page.',
+        i18n: {
+          summaryKey: 'landmarkMainIsTopLevel_summary_cantTell',
+          hintKey: 'landmarkMainIsTopLevel_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'LANDMARK_MAIN_NOT_TOP_LEVEL' }
+        }
+      })
+    );
   }
 
   if (occurrences.length) {

package/src/checks/manual/landmark-no-duplicate-banner-manual.js

@@ -6,19 +6,19 @@
  * @check landmark-no-duplicate-banner
  * @atomic true
  * @summary A page must not have more than one banner landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever the page contains at least one banner landmark
- *   (explicit role="banner", or an implicit, non-nested <header> — see
+ *   (explicit role="banner", or an implicit, non-nested <header>; see
  *   landmark-banner-is-top-level's implementation notes for the
  *   shared landmark-detection model).
  * @expectation
  *   At most one banner landmark exists on the page. Per WAI-ARIA
  *   Authoring Practices, the banner landmark represents site-oriented
- *   content that identifies the page as a whole — having more than one
+ *   content that identifies the page as a whole, so having more than one
  *   is ambiguous for assistive technology users navigating by landmark.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Flags every banner instance (not just the "extra" ones) when more
@@ -81,11 +81,11 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm — e.g. an
+  // in src/core/aria-helpers.js for the full algorithm, e.g. an
   // <aside role="dialog"> containing its own <header>, where the <header>
   // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
@@ -171,12 +171,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = banners.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one banner landmark.',
       hint: 'Keep only one banner landmark (header/role="banner") per page.',
       i18n: {
@@ -187,7 +182,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_BANNER', count: banners.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-no-duplicate-contentinfo-manual.js

@@ -6,18 +6,18 @@
  * @check landmark-no-duplicate-contentinfo
  * @atomic true
  * @summary A page must not have more than one contentinfo landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever the page contains at least one contentinfo landmark
  *   (explicit role="contentinfo", or an implicit, non-nested <footer>).
  * @expectation
- *   At most one contentinfo landmark exists on the page — mirrors
+ *   At most one contentinfo landmark exists on the page, mirroring
  *   landmark-no-duplicate-banner's rationale for contentinfo.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - Only landmarks actually exposed to assistive technology can collide —
+ * - Only landmarks actually exposed to assistive technology can collide,
  *   same as the sibling banner/main rules, avoiding hidden-duplicate false
  *   positives.
  */
@@ -74,7 +74,7 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
@@ -93,7 +93,7 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — it keeps
+      // A named <aside> is never suppressed, even when nested. It keeps
       // "complementary" when it has an accessible name, even inside
       // sectioning content. Matches landmark-unique's precedent.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
@@ -163,12 +163,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = contentinfos.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one contentinfo landmark.',
       hint: 'Keep only one contentinfo landmark (footer/role="contentinfo") per page.',
       i18n: {
@@ -179,7 +174,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_CONTENTINFO', count: contentinfos.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-no-duplicate-main-manual.js

@@ -6,7 +6,7 @@
  * @check landmark-no-duplicate-main
  * @atomic true
  * @summary A page must not have more than one main landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever the page contains at least one main landmark
  *   (explicit role="main", or an implicit <main>).
@@ -15,7 +15,7 @@
  *   decision from landmark-one-main (that rule flags zero
  *   mains too; this one only flags more than one).
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Only landmarks actually exposed to assistive technology can collide.
@@ -108,12 +108,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = mains.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one main landmark.',
       hint: 'Keep only one main landmark (<main>/role="main") per page.',
       i18n: {
@@ -124,7 +119,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_MAIN', count: mains.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-one-main-manual.js

@@ -6,24 +6,24 @@
  * @check landmark-one-main
  * @atomic true
  * @summary The page should have a main landmark
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
- *   Always applicable to any HTML document with a <body> element —
+ *   Always applicable to any HTML document with a <body> element:
  *   "does the page have a main landmark" is a whole-page concern,
  *   matching bypass-blocks-present's pattern of evaluating the
  *   document directly.
  * @expectation
  *   At least one main landmark (role="main" or <main>), exposed to
- *   assistive technology, exists on the page — a page with none gives
+ *   assistive technology, exists on the page. A page with none gives
  *   AT users no landmark to jump straight to for the primary content.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Presence-only: a plain descendant-exists test. It does NOT flag more
  *   than one main. "More than one main" is a separate rule,
- *   `landmark-no-duplicate-main`, already implemented — deliberately not
- *   duplicated here, since a page can genuinely have two visible `<main>`
+ *   `landmark-no-duplicate-main`, already implemented and not
+ *   duplicated here, since a page can legitimately have two visible `<main>`
  *   elements, which is out of scope for "does a main landmark exist," not
  *   a violation this rule should report.
  * - Filters candidates through `isAccTreeEligible` (hidden/aria-hidden/
@@ -123,19 +123,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 main landmark.',
         hint: 'Add a main landmark (<main> or role="main") around the page\'s primary content.',
         i18n: {
@@ -146,7 +139,7 @@ function runInPage(ctx) {
         data: {
           details: { reasonCode: 'LANDMARK_MAIN_MISSING' }
         }
-      }
+      })
     ]
   };
 }

package/src/checks/manual/landmark-unique-manual.js

@@ -6,20 +6,20 @@
  * @check landmark-unique
  * @atomic true
  * @summary Landmarks sharing the same role must have unique accessible names
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever two or more landmark regions on the page share the
  *   same landmark role (banner, contentinfo, main, navigation,
- *   complementary, region, form, or search — see implementation notes
+ *   complementary, region, form, or search; see implementation notes
  *   for the detection model).
  * @expectation
  *   Among landmarks sharing a role, each has a distinct accessible name
- *   (via aria-label/aria-labelledby — landmarks are not named from
+ *   (via aria-label/aria-labelledby; landmarks are not named from
  *   content). Two same-role landmarks with the same name (including two
  *   both left unnamed) are indistinguishable to assistive technology
  *   users navigating by landmark.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent and the landmark-
  *   detection model (HTML-AAM implicit-role mapping + explicit role
@@ -80,18 +80,18 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor (role-aware:
   // an ancestor's bare TAG only counts when it carries no role attribute at
-  // all; an explicit role="dialog"-style override no longer suppresses —
+  // all; an explicit role="dialog"-style override no longer suppresses;
   // see that function's header comment in src/core/aria-helpers.js), using
   // two distinct ancestor scopes rather than one shared list: <header>/
   // <footer> use "sectioning content PLUS <main>" (includeMain: true) to
   // decide banner/contentinfo suppression, but <aside> uses PLAIN
-  // sectioning content only — NOT main (includeMain: false) — to decide
+  // sectioning content only, not main (includeMain: false), to decide
   // complementary suppression. A single shared sectioning-ancestors set
   // that includes 'main' is correct for header/footer but wrong for aside:
   // e.g. two unnamed <aside> elements that are direct children of <main>
   // would have their implicit "complementary" role incorrectly suppressed,
   // hiding a real duplicate-landmark violation. The role-aware half matters
-  // too: e.g. an <aside role="dialog"> containing its own <header> —
+  // too: take an <aside role="dialog"> containing its own <header>.
   // role="dialog" isn't one of the four scoping roles, so the nested
   // <header> keeps "banner" per spec, but a tag-only (non-role-aware)
   // check would unconditionally suppress it just because the ancestor TAG
@@ -110,7 +110,7 @@ function runInPage(ctx) {
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
       // An <aside> is suppressed by a sectioning-content ancestor ONLY
-      // when it also has no accessible name — a named <aside> is never
+      // when it also has no accessible name. A named <aside> is never
       // suppressed, even when nested.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
@@ -137,7 +137,7 @@ function runInPage(ctx) {
     if (explicit) {
       if (!LANDMARK_ROLES.has(explicit)) return '';
       // <form>/<section> only count as landmarks when they have an
-      // accessible name — a property of the ELEMENT, not of how the role
+      // accessible name, a property of the ELEMENT, not of how the role
       // got there. This applies whether the role is implicit (already
       // handled in getImplicitLandmarkRole below) or explicit. Per the W3C
       // ARIA-in-HTML spec ("a form is not exposed as a landmark region
@@ -219,34 +219,29 @@ function runInPage(ctx) {
       if (group.length <= 1) continue;
 
       for (const { el } of group) {
-        const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-        const html = helpers.getOuterHtmlSnippet
-          ? helpers.getOuterHtmlSnippet(el)
-          : el.outerHTML || '';
-
-        occurrences.push({
-          selector: stableSelector,
-          html,
-          summary: normalizedName
-            ? `This ${role} landmark shares its accessible name with another ${role} landmark.`
-            : `This ${role} landmark has no accessible name, and more than one unnamed ${role} landmark exists on this page.`,
-          hint: `Give each ${role} landmark a distinct name via aria-label or aria-labelledby.`,
-          i18n: {
-            summaryKey: normalizedName
-              ? 'landmarkUnique_summary_cantTell_duplicateName'
-              : 'landmarkUnique_summary_cantTell_bothUnnamed',
-            hintKey: 'landmarkUnique_hint_cantTell',
-            params: { role }
-          },
-          data: {
-            details: {
-              reasonCode: 'LANDMARK_NOT_UNIQUE',
-              role,
-              name: normalizedName,
-              groupSize: group.length
+        occurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: normalizedName
+              ? `This ${role} landmark shares its accessible name with another ${role} landmark.`
+              : `This ${role} landmark has no accessible name, and more than one unnamed ${role} landmark exists on this page.`,
+            hint: `Give each ${role} landmark a distinct name via aria-label or aria-labelledby.`,
+            i18n: {
+              summaryKey: normalizedName
+                ? 'landmarkUnique_summary_cantTell_duplicateName'
+                : 'landmarkUnique_summary_cantTell_bothUnnamed',
+              hintKey: 'landmarkUnique_hint_cantTell',
+              params: { role }
+            },
+            data: {
+              details: {
+                reasonCode: 'LANDMARK_NOT_UNIQUE',
+                role,
+                name: normalizedName,
+                groupSize: group.length
+              }
             }
-          }
-        });
+          })
+        );
       }
     }
   }