@surea11y/core 1.5.0 → 1.7.0

package/src/checks/automatic/aria-valid-attr-value.js

@@ -15,9 +15,14 @@
  * @expectation
  *   Each attribute's value conforms to its WAI-ARIA-declared value type:
  *   boolean ("true"/"false"), tristate ("true"/"false"/"mixed"), a token
- *   from a fixed enumerated set, an integer, a real number, or an empty
- *   value or ID reference (list) that resolves to an existing element in
- *   the document.
+ *   from a fixed enumerated set, an integer, a real number, or an ID
+ *   reference (list) that resolves to an existing element in the document.
+ *   Per ACT 6a7281's own applicability ("any state or property that is
+ *   NOT empty"), an explicitly empty value, including a bare boolean-style
+ *   attribute with no "=value" at all, e.g. `aria-checked` alone, is out
+ *   of scope for every value type, not a violation: a common, deliberate
+ *   pattern in templated markup (e.g. React conditionally rendering
+ *   `aria-describedby={hasError ? errorId : ''}`).
  * @implementation-notes
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
@@ -25,16 +30,27 @@
  * - ID-reference resolution (see aria-helpers.js's idExists) only flags
  *   idref-list attributes (aria-labelledby, aria-describedby,
  *   aria-controls, aria-owns, etc.) when NONE of the space-separated ids
- *   resolve — a partially-dangling list (some ids exist, some don't) is
+ *   resolve, a partially-dangling list (some ids exist, some don't) is
  *   left unflagged (only invalidate when every token fails to resolve).
- *   Single-idref attributes (aria-activedescendant, aria-errormessage) are
- *   flagged whenever their one id doesn't resolve.
- * - An explicitly-EMPTY idref/idref-list value (e.g.
- *   `aria-describedby=""`) is valid, not a violation — `allowEmpty` holds
- *   for every idref/idref-list ARIA attribute. A common, deliberate pattern
- *   in templated markup (e.g. React conditionally rendering
- *   `aria-describedby={hasError ? errorId : ''}`); flagging it would be a
- *   false positive.
+ *   Of the two single-idref attributes, aria-activedescendant is flagged
+ *   whenever its one id doesn't resolve; aria-errormessage's existence is
+ *   never checked (format only), ACT 6a7281's own Background
+ *   text names it as a non-required property whose target "may be created
+ *   in response to an event that may or may not happen" (a validation
+ *   error message rendered only once the error actually occurs).
+ * - aria-controls is never a fail on a target that doesn't resolve, and
+ *   this is the one place the rule reports two tiers. The controlled
+ *   element is routinely built when the widget opens, so a static scan
+ *   that cannot find it has not found a defect; it has found markup it
+ *   cannot decide. A collapsed widget (aria-expanded="false" or
+ *   aria-selected="false") passes outright, since the absence is exactly
+ *   what that state means; anything else is a `cantTell` for human
+ *   review. Every other idref/idref-list attribute keeps its fail: a
+ *   dangling aria-labelledby or aria-owns names content that was supposed
+ *   to be there already.
+ * - Two tiers in one run means helpers.resolveTieredOutcome decides the
+ *   aggregate: a real fail elsewhere on the page still reports fail, and
+ *   the aria-controls occurrences ride along rather than being dropped.
  */
 
 const id = 'aria-valid-attr-value';
@@ -76,13 +92,15 @@ function runInPage(ctx) {
 
   const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*') : helpers.queryAll('*');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el || !el.attributes || !el.getAttribute) continue;
 
     let invalid = null;
+    let review = null;
     const attrs = el.attributes;
     for (let i = 0; i < attrs.length; i++) {
       const name = String(attrs[i].name || '').toLowerCase();
@@ -92,21 +110,26 @@ function runInPage(ctx) {
       applicableCount += 1;
 
       const rawValue = el.getAttribute(name);
-      const result = ariaHelpers.validateAttrValue(name, rawValue);
-      if (!result.valid) {
+      const result = ariaHelpers.validateAttrValue(name, rawValue, el);
+      if (result.valid) continue;
+
+      const item = {
+        name,
+        value: rawValue == null ? '' : String(rawValue),
+        reason: result.reason
+      };
+
+      if (result.review) {
+        if (!review) review = [];
+        review.push(item);
+      } else {
         if (!invalid) invalid = [];
-        invalid.push({
-          name,
-          value: rawValue == null ? '' : String(rawValue),
-          reason: result.reason
-        });
+        invalid.push(item);
       }
     }
 
-    if (!invalid || !invalid.length) continue;
-
-    for (const item of invalid) {
-      occurrences.push(
+    for (const item of invalid || []) {
+      failOccurrences.push(
         helpers.reportOccurrence(el, {
           summary: 'This element has an ARIA attribute with an invalid value.',
           hint: 'Use a value that matches the attribute’s expected type (see the WAI-ARIA specification for this attribute).',
@@ -126,20 +149,53 @@ function runInPage(ctx) {
         })
       );
     }
+
+    for (const item of review || []) {
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'No element with this id exists right now, so the engine cannot tell whether this reference is wrong.',
+          hint: 'Confirm the controlled element is created when the widget opens; if it never exists, remove or correct the reference.',
+          i18n: {
+            summaryKey: 'ariaValidAttrValue_summary_cantTell_idref',
+            hintKey: 'ariaValidAttrValue_hint_cantTell_idref',
+            params: { attr: item.name, value: item.value }
+          },
+          uncertainty: {
+            code: 'runtime-dependent',
+            needed: 'Whether the widget creates the referenced element when it opens.',
+            evidence: {
+              attribute: item.name,
+              referencedId: item.value,
+              resolvedAtScanTime: false
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'ARIA_ATTR_VALUE_TARGET_ABSENT',
+              attr: item.name,
+              value: item.value,
+              valueReason: item.reason
+            }
+          }
+        })
+      );
+    }
   }
 
   if (applicableCount === 0) {
     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: 'pass', severity: 'minor', occurrences: [] };
+
+  // See helpers.resolveTieredOutcome's own header comment
+  // (src/core/dom-helpers.js): a fail-tier finding never silently discards
+  // cantTell-tier findings from the same run.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-valid-attr.js

@@ -16,9 +16,15 @@
  *   specification (catches typos / made-up attribute names, which are
  *   silently ignored by assistive technology and therefore a real,
  *   deterministic defect).
+ *   Reported at CANTTELL rather than FAIL: an aria-* attribute the spec
+ *   does not define is inert, so nothing about the element's exposed name,
+ *   role or value changes because it is there. Where the author meant a real
+ *   attribute and the element ends up without a name, that absence is the
+ *   naming rules' decision, not this one's. ACT 5f99a7 maps 1.3.1/4.1.2 as
+ *   secondary requirements, "less strict" than the rule itself.
  * @implementation-notes
  * - Distinct from aria-valid-attr-value (which validates the VALUE
- *   of a recognized attribute) — this rule only validates the attribute
+ *   of a recognized attribute), this rule only validates the attribute
  *   NAME.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
@@ -96,6 +102,12 @@ function runInPage(ctx) {
             hintKey: 'ariaValidAttr_hint_fail',
             params: { attr: name }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether the misspelling cost the element a name or state it has no other source for.',
+            evidence: { attribute: name, definedInAria: false, exposedEffect: 'none' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ATTR_INVALID', attr: name }
           }
@@ -107,15 +119,8 @@ 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 || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome([], occurrences, rule.defaultSeverity || 'serious');
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/autocomplete-valid.js

@@ -26,7 +26,7 @@
  *   order) with the full fixed field-name vocabulary from the HTML
  *   Standard, rather than validating every field-specific constraint
  *   (e.g. which contact-modality tokens are legal for which field
- *   names) — matches this engine's established "deliberately scoped"
+ *   names), matches this engine's established "scoped"
  *   precedent (see aria-helpers.js) for keeping high-confidence fail
  *   without reimplementing the entire spec.
  */
@@ -63,7 +63,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const FIELD_NAMES = new Set([
     'name',

package/src/checks/automatic/avoid-inline-spacing.js

@@ -25,8 +25,12 @@
  * - Within one declaration block, importance outranks order, so the effective
  *   declaration is the last `!important` one for that property.
  * - ACT 78fd32/24afc2/9e45ec additionally require the text to contain a soft
- *   wrap break, which cannot be determined without layout. Not implemented, so
- *   a forced value on text that never wraps is still reported.
+ *   wrap break, which layout would settle and this cannot. Two shapes do
+ *   establish that no wrap is possible -- text not allowed to wrap, and a
+ *   fixed-width element inside a horizontally scrolling ancestor -- and those
+ *   are reported for review rather than failed. Anything else is treated as
+ *   wrapping, so a forced value on text that never wraps for some other reason
+ *   is still reported.
  */
 
 const id = 'avoid-inline-spacing';
@@ -83,6 +87,8 @@ function runInPage(ctx) {
 
   const occurrences = [];
   let applicableCount = 0;
+  const undecided = [];
+  const noWrap = [];
 
   // Within one declaration block, importance wins over order, so the last
   // important declaration is the one that takes effect. Passed Example 5 of ACT
@@ -148,6 +154,36 @@ function runInPage(ctx) {
     return null;
   }
 
+  // ACT 78fd32/24afc2/9e45ec apply only to text that contains a soft wrap
+  // break. Layout settles that; short of it, two shapes establish that no wrap
+  // can happen -- text not allowed to wrap, and a fixed-width element inside a
+  // horizontally scrolling ancestor, which narrowing the viewport cannot reach.
+  function cannotSoftWrap(el) {
+    const cs = computedStyleOf(el);
+    const whiteSpace = cs ? String(cs.whiteSpace || '').toLowerCase() : '';
+    if (whiteSpace === 'nowrap' || whiteSpace === 'pre') return true;
+
+    if (!/(^|;)\s*width\s*:/i.test(String(el.getAttribute('style') || ''))) return false;
+
+    const chain =
+      helpers && typeof helpers.ancestorsIncludingSelf === 'function'
+        ? helpers.ancestorsIncludingSelf(el)
+        : null;
+    const ancestors = chain || [];
+    if (!chain) {
+      for (let a = el.parentElement; a; a = a.parentElement) ancestors.push(a);
+    }
+
+    for (const ancestor of ancestors) {
+      if (ancestor === el) continue;
+      const acs = computedStyleOf(ancestor);
+      if (!acs) continue;
+      const overflowX = String(acs.overflowX || acs.overflow || '').toLowerCase();
+      if (overflowX === 'scroll' || overflowX === 'auto') return true;
+    }
+    return false;
+  }
+
   // ACT scopes these rules to text visible on screen, and text pushed far off
   // canvas is the one hidden shape the shared eligibility check keeps eligible.
   function isOffScreen(el) {
@@ -228,6 +264,7 @@ function runInPage(ctx) {
     if (!hasVisibleTextChild(el) || !isRendered(el) || isOffScreen(el)) continue;
 
     const flagged = [];
+    const unresolved = [];
     let inScope = false;
     for (const prop of SPACING_PROPS) {
       const decl = effectiveDeclaration(raw, prop);
@@ -235,14 +272,28 @@ function runInPage(ctx) {
       if (INHERITED_KEYWORDS.indexOf(decl.value.toLowerCase()) !== -1) continue;
       inScope = true;
       const ratio = spacingRatio(el, prop, decl.value);
-      // Unresolvable spacing is left alone: this engine reserves fail for
-      // high-confidence violations.
-      if (ratio === null) continue;
+      // Not flagged, since `fail` needs a measured value -- but recorded, so
+      // the element does not fall through to `pass` unmeasured.
+      if (ratio === null) {
+        unresolved.push(prop);
+        continue;
+      }
       if (ratio < MIN_RATIO[prop]) flagged.push(prop);
     }
 
     if (inScope) applicableCount += 1;
-    if (!flagged.length) continue;
+    if (!flagged.length) {
+      if (unresolved.length) undecided.push({ el, props: unresolved.slice() });
+      continue;
+    }
+
+    // A forced value on text that cannot wrap is outside these ACT rules'
+    // applicability, and whether it wraps is not decidable here, so it is
+    // reported for review rather than failed.
+    if (cannotSoftWrap(el)) {
+      noWrap.push({ el, props: flagged.slice() });
+      continue;
+    }
 
     const tag = el.tagName.toLowerCase();
 
@@ -273,6 +324,82 @@ function runInPage(ctx) {
       occurrences
     };
   }
+  if (noWrap.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      confidence: 'low',
+      occurrences: noWrap.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          summary: `This element's inline style forces ${props.join(', ')} with !important, but its text does not appear able to wrap, so the text-spacing criterion may not apply to it.`,
+          hint: 'Confirm whether this text ever wraps. If it cannot, the criterion does not apply; if it can, remove !important or set a value that already meets the metric.',
+          i18n: {
+            summaryKey: 'avoidInlineSpacing_summary_cantTell_noSoftWrap',
+            hintKey: 'avoidInlineSpacing_hint_cantTell_noSoftWrap',
+            params: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props.join(', ')
+            }
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed: 'Whether this text ever contains a soft wrap break, which needs layout.',
+            evidence: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props,
+              reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP',
+              element: (el.tagName || '').toLowerCase(),
+              properties: props
+            }
+          }
+        })
+      )
+    };
+  }
+  if (undecided.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      confidence: 'low',
+      occurrences: undecided.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          summary: `This element's inline style sets ${props.join(', ')} with !important, but the value could not be resolved, so whether it meets the WCAG text-spacing metric could not be determined.`,
+          hint: 'Check this value by hand against the metric (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em), or express it in a unit the engine can resolve against the element’s computed font size.',
+          i18n: {
+            summaryKey: 'avoidInlineSpacing_summary_cantTell',
+            hintKey: 'avoidInlineSpacing_hint_cantTell',
+            params: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props.join(', ')
+            }
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed: 'A resolved value for the spacing declarations marked !important.',
+            evidence: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props,
+              reasonCode: 'INLINE_SPACING_NOT_RESOLVABLE'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'INLINE_SPACING_NOT_RESOLVABLE',
+              element: (el.tagName || '').toLowerCase(),
+              properties: props
+            }
+          }
+        })
+      )
+    };
+  }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 

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).

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 : ''
     );