@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/binary-control-name-present.js

@@ -2,6 +2,28 @@
 
 'use strict';
 
+/**
+ * @check binary-control-name-present
+ * @atomic true
+ * @summary Checkboxes, radios and switches must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="checkbox", role="radio" or
+ *   role="switch" (the attribute must name one of those roles alone, not a
+ *   fallback list) that are included in the accessibility tree. A native
+ *   <input type="checkbox">/<input type="radio"> is in scope only when it
+ *   carries one of those roles explicitly; without a role attribute it
+ *   belongs to form-control-programmatic-label-present.
+ * @expectation
+ *   The control has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title. A native
+ *   checkbox or radio additionally accepts an associated <label>, the
+ *   labels API, a wrapping <label>, or label[for], with at most four labels
+ *   read for determinism, and any other element accepts its own subtree
+ *   text, those roles being name-from-content.
+ */
+
 const id = 'binary-control-name-present';
 
 const meta = {
@@ -79,7 +101,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
@@ -96,7 +118,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).
@@ -111,10 +133,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');
@@ -124,7 +146,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).
@@ -272,28 +294,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 control has no accessible name.',
-      hint: 'Provide a label, aria-label, aria-labelledby, or other accessible-name mechanism so assistive technologies can identify the control.',
-      i18n: {
-        summaryKey: 'binaryControlNamePresent_summary_fail',
-        hintKey: 'binaryControlNamePresent_hint_fail',
-        params: { controlType }
-      },
-      data: {
-        details: {
-          reasonCode: 'name_missing',
-          controlType,
-          methodTried: res.method
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This control has no accessible name.',
+        hint: 'Provide a label, aria-label, aria-labelledby, or other accessible-name mechanism so assistive technologies can identify the control.',
+        i18n: {
+          summaryKey: 'binaryControlNamePresent_summary_fail',
+          hintKey: 'binaryControlNamePresent_hint_fail',
+          params: { controlType }
         },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+        data: {
+          details: {
+            reasonCode: 'name_missing',
+            controlType,
+            methodTried: res.method
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -2,6 +2,29 @@
 
 'use strict';
 
+/**
+ * @check button-name-present
+ * @atomic true
+ * @summary Buttons must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <button>, <input type="button">, <input type="submit">,
+ *   <input type="reset"> and elements with role="button", where the element
+ *   is included in the accessibility tree. role="presentation"/"none" takes
+ *   an element out of scope unless a global ARIA attribute or focusability
+ *   restores its role, per presentational roles conflict resolution.
+ * @expectation
+ *   The element has a non-empty accessible name. A programmatic name is
+ *   taken first (aria-labelledby, aria-label, an associated <label>, title).
+ *   Failing that, an <input> button falls back to its value attribute, and
+ *   type="submit"/type="reset" fall back to the user agent's own
+ *   "Submit"/"Reset" default, which is why those two are never nameless.
+ *   Failing both, a button whose role is name-from-content falls back to its
+ *   subtree text, counting each descendant's own name (an <img alt>,
+ *   aria-label or title) rather than only text nodes.
+ */
+
 // NOTE: Repo ruleId contract requires ENGINE_TAG prefix in the rule id.
 // File name intentionally has no prefix, per request.
 const id = 'button-name-present';
@@ -45,7 +68,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(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
@@ -64,7 +87,16 @@ function runInPage(ctx) {
       const type = normalizeWs(el.getAttribute ? el.getAttribute('type') : '').toLowerCase();
       if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
       const vAttr = el.getAttribute ? el.getAttribute('value') : '';
-      return normalizeWs(vAttr != null ? vAttr : typeof el.value === 'string' ? el.value : '');
+      const explicit = normalizeWs(
+        vAttr != null ? vAttr : typeof el.value === 'string' ? el.value : ''
+      );
+      if (explicit) return explicit;
+      // HTML spec: input[type=submit]/[type=reset] with no `value` fall back
+      // to a UA-supplied default label ("Submit"/"Reset"), so they are never
+      // actually nameless -- unlike type=button, whose value defaults to "".
+      if (type === 'submit') return 'Submit';
+      if (type === 'reset') return 'Reset';
+      return '';
     } catch {
       return '';
     }
@@ -90,17 +122,71 @@ function runInPage(ctx) {
       typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
     if (!eligible) continue;
 
-    applicableCount += 1;
-
     const tag = (el.tagName || '').toLowerCase();
     const role = el.getAttribute ? el.getAttribute('role') : null;
     const roleNorm = normalizeWs(role).toLowerCase();
 
+    // role="none"/"presentation" removes this element from the accessibility
+    // tree as a button (WAI-ARIA Presentational Roles Conflict Resolution),
+    // UNLESS a conflicting global ARIA attribute or focusability restores
+    // its native/explicit role -- mirrors presentation-role-conflict-manual.js's
+    // detection logic. Kept local to this rule rather than routed through
+    // the shared eligibility helper: several other rules rely
+    // on that helper staying permissive for role="none" wrappers they walk
+    // through themselves (e.g. aria-prohibited-children's "transparent
+    // wrapper" traversal).
+    if (roleNorm === 'none' || roleNorm === 'presentation') {
+      const ariaHiddenTrue = el.getAttribute && el.getAttribute('aria-hidden') === 'true';
+      if (!ariaHiddenTrue) {
+        const GLOBAL_ARIA_ATTRS = [
+          'aria-atomic',
+          'aria-braillelabel',
+          'aria-brailleroledescription',
+          'aria-busy',
+          'aria-controls',
+          'aria-current',
+          'aria-describedby',
+          'aria-description',
+          'aria-details',
+          'aria-disabled',
+          'aria-dropeffect',
+          'aria-errormessage',
+          'aria-flowto',
+          'aria-grabbed',
+          'aria-haspopup',
+          'aria-hidden',
+          'aria-invalid',
+          'aria-keyshortcuts',
+          'aria-label',
+          'aria-labelledby',
+          'aria-live',
+          'aria-owns',
+          'aria-relevant',
+          'aria-roledescription'
+        ];
+        const hasConflict = GLOBAL_ARIA_ATTRS.some((a) =>
+          el.hasAttribute ? el.hasAttribute(a) : false
+        );
+        let isFocusable = false;
+        if (!hasConflict && helpers.getFocusableInfo) {
+          try {
+            const fi = helpers.getFocusableInfo(el, ctx);
+            isFocusable = !!(fi && fi.focusable);
+          } catch {
+            isFocusable = false;
+          }
+        }
+        if (!hasConflict && !isFocusable) continue;
+      }
+    }
+
+    applicableCount += 1;
+
     const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
 
     // getAccessibleNameInfo only resolves programmatic mechanisms (aria-labelledby,
-    // aria-label, native <label> association, title) — it never falls back to
-    // subtree content — so it's safe to trust directly whenever present.
+    // aria-label, native <label> association, title), it never falls back to
+    // subtree content, so it's safe to trust directly whenever present.
     const trustedProgrammaticName = normalizeWs(
       nameInfo && nameInfo.present && typeof nameInfo.value === 'string' ? nameInfo.value : ''
     );
@@ -170,35 +256,30 @@ 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 || '';
-
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This button has no accessible name.',
-        hint: 'Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.',
-        i18n: {
-          summaryKey: 'buttonNamePresent_summary_fail',
-          hintKey: 'buttonNamePresent_hint_fail',
-          params: { element: tag }
-        },
-        data: {
-          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-          details: {
-            reasonCode: 'name_missing',
-            metrics: {
-              trustedProgrammaticNameLength: trustedProgrammaticName.length,
-              inputValueNameLength: inputValueName.length,
-              contentNameLength: contentName.length,
-              explicitProgrammatic: explicitProg ? 1 : 0
-            },
-            refs: { accessibleName: nameInfo || null }
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This button has no accessible name.',
+          hint: 'Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.',
+          i18n: {
+            summaryKey: 'buttonNamePresent_summary_fail',
+            hintKey: 'buttonNamePresent_hint_fail',
+            params: { element: tag }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: {
+              reasonCode: 'name_missing',
+              metrics: {
+                trustedProgrammaticNameLength: trustedProgrammaticName.length,
+                inputValueNameLength: inputValueName.length,
+                contentNameLength: contentName.length,
+                explicitProgrammatic: explicitProg ? 1 : 0
+              },
+              refs: { accessibleName: nameInfo || null }
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -2,6 +2,26 @@
 
 'use strict';
 
+/**
+ * @check combobox-name-present
+ * @atomic true
+ * @summary Elements with role="combobox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="combobox" (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="combobox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom combobox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="combobox">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'combobox-name-present';
 
 const meta = {
@@ -66,7 +86,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
@@ -83,7 +103,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).
@@ -98,10 +118,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');
@@ -111,7 +131,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).
@@ -231,24 +251,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 combobox has no accessible name.',
-      hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this combobox's accessible name.",
-      i18n: {
-        summaryKey: 'comboboxNamePresent_summary_fail',
-        hintKey: 'comboboxNamePresent_hint_fail',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'combobox', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This combobox has no accessible name.',
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this combobox's accessible name.",
+        i18n: {
+          summaryKey: 'comboboxNamePresent_summary_fail',
+          hintKey: 'comboboxNamePresent_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'combobox', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/contrast-computable.js

@@ -2,6 +2,37 @@
 
 'use strict';
 
+/**
+ * @check contrast-computable
+ * @atomic true
+ * @summary Color contrast must be computable from CSS for rendered text
+ * @standard WCAG 2.2
+ * @sc 1.4.3
+ * @sc 1.4.6
+ * @applicability
+ *   Applies to every visible text node in scope, plus the label of <input
+ *   type="button">/[type="submit"]/[type="reset"], which is rendered from
+ *   the value attribute and so is invisible to a text-node walk. Text counts
+ *   only when its element is DOM-visible under the run's visibility mode, is
+ *   not clipped out of sight by the sr-only technique (clip or clip-path),
+ *   and belongs neither to a disabled control nor to the label of one,
+ *   WCAG's inactive-user-interface-component exception. Subtrees excluded
+ *   via engineOptions.excludeSelectors are skipped, and open shadow roots
+ *   are walked as roots in their own right.
+ * @expectation
+ *   Both sides of the contrast calculation can be established from CSS for
+ *   every applicable text node: an effective background resolving to an
+ *   opaque color, and a parsable foreground color. Where either cannot be,
+ *   a background image or gradient, mix-blend-mode, a filter or
+ *   backdrop-filter, a text-shadow (which may add contrast this engine has
+ *   no glyph-rendering model to account for), ancestor opacity, a root
+ *   background that never becomes opaque, or a color that does not parse,
+ *   the result is cantTell naming the blocker. This rule is the one that
+ *   reports that uncertainty, which is what lets contrast-minimum and
+ *   contrast-enhanced stay silent on the same text instead of guessing at
+ *   a ratio.
+ */
+
 const id = 'contrast-computable';
 
 const meta = {
@@ -118,6 +149,7 @@ function runInPage(ctx) {
         else summaryKey = 'contrastComputable_cantTell_filterOrBackdropFilter';
       } else if (rc === 'BACKGROUND_NOT_OPAQUE_AT_ROOT')
         summaryKey = 'contrastComputable_cantTell_rootNotOpaque';
+      else if (rc === 'TEXT_SHADOW') summaryKey = 'contrastComputable_cantTell_textShadow';
 
       const details = Object.assign(
         { reasonCode: rc },

package/src/checks/automatic/contrast-enhanced.js

@@ -2,10 +2,30 @@
 
 'use strict';
 
+/**
+ * @check contrast-enhanced
+ * @atomic true
+ * @summary Text must meet the WCAG AAA contrast ratio for its size
+ * @standard WCAG 2.2
+ * @sc 1.4.6
+ * @applicability
+ *   Applies to the visible text contrast-computable applies to, see that
+ *   rule for the eligibility gates, narrowed to text whose background and
+ *   foreground are actually computable. Eligible text that is not computable
+ *   leaves this rule notApplicable rather than cantTell: reporting that
+ *   uncertainty belongs to contrast-computable, so the two never report the
+ *   same text twice.
+ * @expectation
+ *   Every computable text node reaches the ratio SC 1.4.6 requires for its
+ *   size: 4.5:1 for large text, 7:1 for everything else. Text is large at
+ *   24px or more, or at 14pt (about 18.667px) or more when the computed font
+ *   weight is 700 or higher.
+ */
+
 const id = 'contrast-enhanced';
 
 const meta = {
-  title: 'Text must meet the enhanced color contrast ratio',
+  title: 'Text meets enhanced color contrast (AAA)',
   description:
     'Checks that visible text has a contrast ratio of at least 7:1 (normal) or 4.5:1 (large), when contrast is computable from CSS.',
   i18n: {

package/src/checks/automatic/contrast-minimum.js

@@ -2,10 +2,30 @@
 
 'use strict';
 
+/**
+ * @check contrast-minimum
+ * @atomic true
+ * @summary Text must meet the WCAG AA contrast ratio for its size
+ * @standard WCAG 2.2
+ * @sc 1.4.3
+ * @applicability
+ *   Applies to the visible text contrast-computable applies to, see that
+ *   rule for the eligibility gates, narrowed to text whose background and
+ *   foreground are actually computable. Eligible text that is not computable
+ *   leaves this rule notApplicable rather than cantTell: reporting that
+ *   uncertainty belongs to contrast-computable, so the two never report the
+ *   same text twice.
+ * @expectation
+ *   Every computable text node reaches the ratio SC 1.4.3 requires for its
+ *   size: 3:1 for large text, 4.5:1 for everything else. Text is large at
+ *   24px or more, or at 14pt (about 18.667px) or more when the computed font
+ *   weight is 700 or higher.
+ */
+
 const id = 'contrast-minimum';
 
 const meta = {
-  title: 'Text must meet the minimum color contrast ratio',
+  title: 'Text meets minimum color contrast (AA)',
   description:
     'Checks that visible text has a contrast ratio of at least 4.5:1 (normal) or 3:1 (large), when contrast is computable from CSS.',
   i18n: {