@surea11y/core 1.2.0 → 1.4.0

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'link-name-present';
@@ -13,7 +15,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'links', 'name'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -24,7 +32,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const occurrences = [];
   let applicableCount = 0;
@@ -40,48 +48,68 @@ function runInPage(ctx) {
       const info = helpers.getContentNameInfo(container, ctx);
       return info && info.present ? info.value : '';
     }
-    const t = (container && container.textContent) ? String(container.textContent) : '';
+    const t = container && container.textContent ? String(container.textContent) : '';
     return t.replace(/\s+/g, ' ').trim();
   }
 
   const selector = 'a[href], area[href], [role="link"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   for (const el of nodes) {
     // isAccTreeEligible returns { eligible, reasons }, not a boolean.
     const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
-    const eligible = typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    const eligible =
+      typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
     if (!eligible) continue;
 
     applicableCount += 1;
 
     const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
-    const programmaticName = (nameInfo && typeof nameInfo.value === 'string') ? nameInfo.value : '';
+    const programmaticName = nameInfo && typeof nameInfo.value === 'string' ? nameInfo.value : '';
 
     // A native <a href>/<area href> (or [role="link"]) whose role has been
     // overridden to one of these roles is no longer semantically a link —
     // per the WAI-ARIA Accessible Name and Description Computation spec
     // these roles are name-from-author-only, and their rendered content
-    // represents a VALUE, not a NAME (mirrors axe-core's controlValueRoles,
-    // verified against its source; see button-name-present.js's identical
+    // represents a VALUE, not a NAME (see button-name-present.js's identical
     // fix for a real-world example — <button role="combobox">List</button> —
     // of the same class of bug on a different host tag).
     const role = el.getAttribute ? el.getAttribute('role') : null;
-    const roleNorm = String(role || '').replace(/\s+/g, ' ').trim().toLowerCase();
-    const VALUE_ROLES = ['textbox', 'progressbar', 'scrollbar', 'slider', 'spinbutton', 'combobox', 'listbox'];
+    const roleNorm = String(role || '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .toLowerCase();
+    const VALUE_ROLES = [
+      'textbox',
+      'progressbar',
+      'scrollbar',
+      'slider',
+      'spinbutton',
+      'combobox',
+      'listbox'
+    ];
     const isContentNameCandidate = !VALUE_ROLES.includes(roleNorm);
 
-    const contentName = (programmaticName.trim().length === 0 && isContentNameCandidate) ? getConservativeSubtreeText(el) : '';
+    const contentName =
+      programmaticName.trim().length === 0 && isContentNameCandidate
+        ? getConservativeSubtreeText(el)
+        : '';
     const finalName = (programmaticName.trim().length ? programmaticName : contentName).trim();
 
     if (finalName.length === 0) {
       // Only compute the richer eligibility-info payload (used solely for
       // the occurrence's visibilityFilter) once we know an occurrence is
       // actually being built, rather than for every applicable element.
-      const eligInfo = helpers.getEligibilityInfo ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+      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 html = helpers.getOuterHtmlSnippet
+        ? helpers.getOuterHtmlSnippet(el)
+        : el.outerHTML || '';
       const tag = (el.tagName || '').toLowerCase();
 
       occurrences.push({
@@ -118,7 +146,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -24,35 +26,25 @@
  *   inverse relationship: does a given <li> have a valid parent).
  * - Direct children that are not exposed to the accessibility tree (e.g.
  *   display:none, [hidden], aria-hidden="true") are excluded from
- *   consideration entirely — matching a widely-used reference engine's own
- *   `only-listitems` check, which likewise skips non-AT-visible children. Confirmed against
- *   two real sites: Spotify's newsroom has a stray `<input type="hidden">`
- *   as a direct <ul> child (UA-stylesheet display:none by spec for
- *   input[type=hidden]), and Stanford's main nav interleaves `<li>` with
- *   `<span style="display:none">` hydration markers. Neither is reachable
- *   by assistive technology, so neither breaks the list semantics a screen
- *   reader actually announces.
- * - The explicit-role-overrides-tag behavior above was added after reading
- *   a widely-used reference engine's ACTUAL `only-listitems` evaluate function
- *   directly (`invalidChildrenEvaluate`/`getInvalidSelector` — note this is a
- *   DIFFERENT function from the similarly-named, unused `onlyListitemsEvaluate`
- *   elsewhere in that engine's source; don't confuse the two when re-verifying). Its
- *   exact rule: if a child has an explicit role, only `validRoles` (here,
- *   `['listitem']`) is consulted — the tag name is never checked. Only
- *   without an explicit role does the tag name (`validNodeNames`) matter.
- *   Found via two real sites: Notion's footer nav lists include a
- *   `<li role="none">` used purely to host the list's own visually-hidden
- *   label (referenced by the `<ul>`'s `aria-labelledby`), and LinkedIn has
- *   both an all-`<li role="menuitem">` menu list and a footer list mixing
- *   real `<li>`s with one `<li role="presentation">` — that reference engine
- *   correctly flags all of these, surea11y's tag-only check missed them entirely.
+ *   consideration entirely — an element not reachable by assistive
+ *   technology can't break the list semantics a screen reader announces.
+ *   Common cases: a stray `<input type="hidden">` as a direct <ul> child
+ *   (UA-stylesheet display:none by spec), or `<span style="display:none">`
+ *   hydration markers interleaved with real `<li>`s.
+ * - Explicit-role-overrides-tag: if a child has an explicit role, only
+ *   `['listitem']` is consulted — the tag name is never checked. Only
+ *   without an explicit role does the tag name matter. Catches cases a
+ *   tag-only check misses: `<li role="none">` hosting a list's own
+ *   visually-hidden label, `<li role="menuitem">` menu items, or a real
+ *   `<li>` mixed with an `<li role="presentation">`.
  */
 
 const id = 'list-children-valid';
 
 const meta = {
   title: 'Lists must only directly contain list items',
-  description: 'Checks that <ul>/<ol> elements only have <li>, <script>, or <template> as direct children.',
+  description:
+    'Checks that <ul>/<ol> elements only have <li>, <script>, or <template> as direct children.',
   i18n: {
     titleKey: 'listChildrenValid_title',
     descriptionKey: 'listChildrenValid_description'
@@ -61,7 +53,13 @@ const meta = {
   tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'list'],
   wcagSc: ['1.3.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -71,15 +69,18 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const ALLOWED_CHILD_TAGS = new Set(['li', 'script', 'template']);
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('ul, ol') : helpers.queryAll('ul, ol');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('ul, ol')
+    : helpers.queryAll('ul, ol');
 
-  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
   function isExposedToAt(el) {
     if (!isAccTreeEligible) return true;
@@ -110,8 +111,7 @@ function runInPage(ctx) {
       const roleAttr = child.getAttribute ? String(child.getAttribute('role') || '').trim() : '';
       const explicitRole = roleAttr ? (roleAttr.split(/\s+/)[0] || '').toLowerCase() : '';
 
-      // An explicit role always wins over the tag — see the header
-      // comment's Notion/LinkedIn examples.
+      // An explicit role always wins over the tag — see header comment.
       const valid = explicitRole ? explicitRole === 'listitem' : ALLOWED_CHILD_TAGS.has(tag);
 
       if (!valid) invalidTags.push(tag);
@@ -119,9 +119,11 @@ function runInPage(ctx) {
 
     if (!invalidTags.length) continue;
 
+    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 || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -131,7 +133,7 @@ function runInPage(ctx) {
       i18n: {
         summaryKey: 'listChildrenValid_summary_fail',
         hintKey: 'listChildrenValid_hint_fail',
-        params: { element: tag, invalidChildren: invalidTags.join(', ') }
+        params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
       },
       data: {
         details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
@@ -143,9 +145,14 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'listbox-name-present';
@@ -10,10 +12,16 @@ const meta = {
     descriptionKey: 'listboxNamePresent_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag412", "forms", "atomic", "automatic", "name", "listbox"],
+  tags: ['wcag2a', 'wcag412', 'forms', 'atomic', 'automatic', 'name', 'listbox'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -24,20 +32,22 @@ const meta = {
 
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-      ? helpers.getEligibilityInfo
-      : null;
-
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getAttr(el, name) {
     try {
       if (!el || !el.getAttribute) return '';
       return normalizeWs(el.getAttribute(name));
-    } catch { return ''; }
+    } catch {
+      return '';
+    }
   }
 
   function getConservativeSubtreeText(document, container) {
@@ -52,7 +62,7 @@ function runInPage(ctx) {
       const info = helpers.getContentNameInfo(container, ctx);
       return info && info.present ? info.value : '';
     }
-    const t = (container && container.textContent) ? String(container.textContent) : '';
+    const t = container && container.textContent ? String(container.textContent) : '';
     return t.replace(/\s+/g, ' ').trim();
   }
 
@@ -100,7 +110,8 @@ function runInPage(ctx) {
   }
 
   function isEligibleAcc(helpers, el, ctx) {
-    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    const fn =
+      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -126,12 +137,13 @@ function runInPage(ctx) {
     return map;
   }
 
-
   const occurrences = [];
   let applicableCount = 0;
 
-  const selector = "[role=\"listbox\"]";
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
+  const selector = '[role="listbox"]';
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   // Precompute label[for] map for listbox elements that are labelable
   // native form controls (e.g. <select multiple role="listbox">).
@@ -200,16 +212,22 @@ function runInPage(ctx) {
     if (res.ok) continue;
 
     const eligInfo = getEligibilityInfo
-        ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
-        : null;
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    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 or aria-labelledby (preferred), or provide visible text that is not hidden from assistive technologies.',
+      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',
@@ -222,12 +240,16 @@ function runInPage(ctx) {
     });
   }
 
-
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -25,19 +27,27 @@
  *   native role is fully replaced by the explicit one — the same "any
  *   explicit role overrides the element's native role" ARIA principle
  *   applied elsewhere in this engine), so an <li> inside it is invalid
- *   despite the <ul> tag — found on a real site, Nike's desktop nav
- *   dropdown (`<ul class="desktop-category" role="menu"><li>...`).
- *   Conversely role="presentation"/"none" on the parent is still a valid
- *   (list-semantics-suppressing) parent, matching a widely-used reference
- *   engine's own `listitem` check (`['presentation', 'none', 'list'].includes(parentRole)`,
- *   confirmed by reading its source directly).
+ *   despite the <ul> tag (e.g. `<ul role="menu"><li>...`). Conversely
+ *   role="presentation"/"none" on the parent is still a valid
+ *   (list-semantics-suppressing) parent — the accepted parent roles are
+ *   presentation, none, and list.
+ * - The SAME "explicit role wins" principle applies to the <li> ELEMENT
+ *   ITSELF: an <li role="tab">/role="menuitem">/role="presentation"> etc.
+ *   is exposed to AT with that role, never "listitem" — the whole point
+ *   of this check (list items need a valid list-container parent) doesn't
+ *   apply when the element isn't claiming listitem semantics in the first
+ *   place. Any `<li>` with an explicit `role` attribute is excluded from
+ *   candidacy. `role="listitem"` itself is a no-op restatement (not an
+ *   override), so it still falls through to the normal parent-validity
+ *   check below.
  */
 
 const id = 'listitem-parent-valid';
 
 const meta = {
   title: 'List items must be inside a list container',
-  description: 'Checks that <li> elements are contained by <ul>, <ol>, or an element with role="list".',
+  description:
+    'Checks that <li> elements are contained by <ul>, <ol>, or an element with role="list".',
   i18n: {
     titleKey: 'listitemParentValid_title',
     descriptionKey: 'listitemParentValid_description'
@@ -46,7 +56,13 @@ const meta = {
   tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'list'],
   wcagSc: ['1.3.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -56,7 +72,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('li') : helpers.queryAll('li');
 
@@ -68,6 +84,20 @@ function runInPage(ctx) {
     const parent = el.parentElement;
     if (!parent) continue;
 
+    // An explicit role on the <li> ITSELF overrides its native "listitem"
+    // role entirely, the same "any explicit role wins over the tag's
+    // native role" principle this check already applies to the PARENT
+    // (see the header comment). An <li role="tab">/
+    // role="menuitem">/role="presentation"> etc. is exposed to AT with
+    // THAT role, never "listitem" -- so the "list item needs a valid list
+    // container parent" concern this rule exists for doesn't apply to it
+    // at all; there's no listitem semantics being claimed to validate.
+    // role="listitem" itself is a no-op restatement, not an override, so
+    // it still falls through to the normal parent check below.
+    const ownRoleAttr = el.getAttribute ? String(el.getAttribute('role') || '').trim() : '';
+    const ownExplicitRole = ownRoleAttr ? (ownRoleAttr.split(/\s+/)[0] || '').toLowerCase() : '';
+    if (ownExplicitRole && ownExplicitRole !== 'listitem') continue;
+
     applicableCount += 1;
 
     const parentTag = parent.tagName ? parent.tagName.toLowerCase() : '';
@@ -78,7 +108,7 @@ function runInPage(ctx) {
     let valid;
     if (explicitRole) {
       // An explicit role always wins over the tag's native role, in either
-      // direction — see the header comment's Nike example.
+      // direction — see the header comment.
       valid = explicitRole === 'list' || explicitRole === 'presentation' || explicitRole === 'none';
     } else {
       valid = parentTag === 'ul' || parentTag === 'ol';
@@ -87,7 +117,7 @@ function runInPage(ctx) {
     if (valid) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -109,9 +139,14 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };