@surea11y/core 1.7.0 → 1.8.1

package/src/checks/automatic/aria-hidden-focus.js

@@ -17,6 +17,10 @@
  * Notes:
  * - Focusability is computed via ctx.helpers.getFocusableInfo (native + tabindex + contenteditable).
  * - Elements that are not rendered (e.g., display:none, visibility:hidden, [hidden]) are excluded.
+ * - Disabled controls are not focusable, including those disabled by an ancestor
+ *   <fieldset disabled> (matched with :disabled).
+ * - <area href> has no box of its own, so it is judged by the <img usemap> that uses its
+ *   <map>: it counts as focusable when such an image is rendered and not inert.
  * - Elements hidden via CSS in ways that still allow keyboard focus (e.g., opacity:0, off-screen, clip)
  *   remain in-scope and will be flagged when focusable.
  */
@@ -525,9 +529,69 @@ function runInPage(ctx) {
   // DOM-visibility gate to avoid false positives:
   // Exclude structural/CSS hidden cases that prevent focus (display:none, visibility:hidden, hidden attr, etc.).
   // IMPORTANT: Do NOT exclude opacity-based invisibility; opacity:0 remains in-scope.
+  // Style-only visibility gate. opacity:0 does not count as hidden: the
+  // element can still take focus.
+  function isRenderedForFocus(el) {
+    if (!isDomVisibleEligible) return true;
+    try {
+      const vis = isDomVisibleEligible(el, ctx, {
+        visibilityMode: 'styleOnly',
+        disableGeometry: true
+      });
+      if (vis && vis.eligible === false) {
+        const rs = Array.isArray(vis.reasons) ? vis.reasons : [];
+        const nonOpacity = rs.filter((r) => String(r) !== 'opacityZero');
+        if (nonOpacity.length) return false;
+      }
+    } catch {
+      // ignore
+    }
+    return true;
+  }
+
+  // <area href> generates no box of its own (browsers give it display:none),
+  // so the visibility gate cannot be applied to it. It takes focus when its
+  // <map> is used by an <img usemap> that is rendered and not inert; judge it
+  // by that image instead.
+  function isFocusableArea(el) {
+    if (!trim(el.getAttribute('href'))) return false;
+    let map;
+    try {
+      map = el.closest ? el.closest('map') : null;
+    } catch {
+      map = null;
+    }
+    if (!map) return false;
+    const name = trim(map.getAttribute('name') || map.getAttribute('id'));
+    if (!name) return false;
+    const scope = el.getRootNode ? el.getRootNode() : document;
+    if (!scope || typeof scope.querySelectorAll !== 'function') return false;
+    let imgs;
+    try {
+      imgs = Array.from(scope.querySelectorAll('img[usemap]'));
+    } catch {
+      imgs = [];
+    }
+    const want = name.toLowerCase();
+    for (const img of imgs) {
+      const usemap = lower(img.getAttribute('usemap')).replace(/^#/, '');
+      if (usemap !== want) continue;
+      if (hasInertAncestor(img)) continue;
+      if (isRenderedForFocus(img)) return true;
+    }
+    return false;
+  }
+
   function isActuallyFocusable(el) {
     if (!el || !el.getAttribute) return false;
 
+    // An explicit negative tabindex takes the area out of the tab order too.
+    if (lower(el.tagName || '') === 'area') {
+      const ti = trim(el.getAttribute('tabindex'));
+      if (ti !== '' && !Number.isNaN(Number(ti)) && Number(ti) < 0) return false;
+      return isFocusableArea(el);
+    }
+
     // Hard blockers that should always win (even if fallback logic would say "focusable")
     if (hasInertAncestor(el)) return false;
     if (isDisabledFormControl(el)) return false;
@@ -564,7 +628,7 @@ function runInPage(ctx) {
     const tag = lower(el.tagName || '');
     let fallbackFocusable = false;
 
-    if (tag === 'a' || tag === 'area') {
+    if (tag === 'a') {
       const href = trim(el.getAttribute('href'));
       fallbackFocusable = !!href;
     } else if (tag === 'button' || tag === 'select' || tag === 'textarea' || tag === 'summary') {
@@ -601,23 +665,7 @@ function runInPage(ctx) {
 
     // 2) exclude non-rendered / non-visible-by-style blockers
     // IMPORTANT: Do NOT exclude opacity-based invisibility; opacity:0 remains in-scope.
-    if (isDomVisibleEligible) {
-      try {
-        const vis = isDomVisibleEligible(el, ctx, {
-          visibilityMode: 'styleOnly',
-          disableGeometry: true
-        });
-        if (vis && vis.eligible === false) {
-          const rs = Array.isArray(vis.reasons) ? vis.reasons : [];
-          const nonOpacity = rs.filter((r) => String(r) !== 'opacityZero');
-          if (nonOpacity.length) return false;
-        }
-      } catch {
-        // ignore
-      }
-    }
-
-    return true;
+    return isRenderedForFocus(el);
   }
 
   function hasInertAncestor(el) {
@@ -635,6 +683,14 @@ function runInPage(ctx) {
   }
 
   function isDisabledFormControl(el) {
+    try {
+      // :disabled also covers a control disabled by an ancestor
+      // <fieldset disabled> (outside its first <legend>), which the
+      // `disabled` IDL attribute does not reflect.
+      if (typeof el.matches === 'function' && el.matches(':disabled')) return true;
+    } catch {
+      // ignore
+    }
     try {
       // Covers button/input/select/textarea/option/optgroup/fieldset etc.
       if (typeof el.disabled === 'boolean' && el.disabled) return true;

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

@@ -14,7 +14,9 @@
  *   list for naming attributes (pure text-semantics / non-naming
  *   structural roles: caption, code, deletion, emphasis, generic,
  *   insertion, mark, none, paragraph, presentation, strong, subscript,
- *   suggestion, superscript, time), and (b) elements with no role at all:
+ *   suggestion, superscript, time), plus a native <caption> with no valid
+ *   explicit role, whose implicit role is caption, and (b) elements with no
+ *   role at all:
  *   a curated set of native HTML tags verified to carry no implicit role
  *   (see ROLELESS_NATIVE_TAGS below), or any autonomous custom element (a
  *   hyphenated, author-defined tag per the Custom Elements spec; see
@@ -147,14 +149,25 @@ function runInPage(ctx) {
 
   // --- Tier 1: explicit, valid role from the naming-prohibited set ---
 
+  // A native <caption> has the caption role without saying so, and is judged
+  // the same way as role="caption"; only one that carries a naming attribute
+  // needs visiting.
+  const tier1Selector = '[role], caption[aria-label], caption[aria-labelledby]';
   const roleNodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('[role]')
-    : helpers.queryAll('[role]');
+    ? helpers.queryAllSmart(tier1Selector)
+    : helpers.queryAll(tier1Selector);
 
   for (const el of roleNodes) {
     if (!el || !el.getAttribute) continue;
 
-    const role = ariaHelpers.getExplicitRole(el);
+    const explicitRole = ariaHelpers.getExplicitRole(el);
+    let role = explicitRole;
+    if (
+      (!explicitRole || !ariaHelpers.isValidConcreteRole(explicitRole)) &&
+      String(el.localName || '').toLowerCase() === 'caption'
+    ) {
+      role = 'caption';
+    }
     if (!role || !ROLES_PROHIBITING_NAME.has(role)) continue;
 
     applicableCount += 1;

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

@@ -18,6 +18,11 @@
  *   <input type="checkbox" role="checkbox">, which is exempt because the
  *   native control's own state exposure already covers it; no aria-checked
  *   is required. helpers.aria.getNativeRoleForElement resolves this).
+ *   A native <input type="checkbox"> or <input type="radio"> with another
+ *   checkable role (switch, menuitemcheckbox, menuitemradio, or checkbox on
+ *   a radio and the reverse) is in scope, but its aria-checked counts as
+ *   supplied: the browser exposes the input's own checked state (HTML-AAM),
+ *   so it passes without the attribute.
  * @expectation
  *   Every required state/property for that role is present and non-empty.
  *   Graded by whether ARIA supplies a stand-in for the missing attribute:
@@ -136,6 +141,23 @@ function runInPage(ctx) {
     }
   }
 
+  const CHECKABLE_ROLES = new Set([
+    'checkbox',
+    'switch',
+    'radio',
+    'menuitemcheckbox',
+    'menuitemradio'
+  ]);
+
+  function isNativeCheckable(el) {
+    if (String(el.localName || '').toLowerCase() !== 'input') return false;
+    if (el.namespaceURI && el.namespaceURI !== 'http://www.w3.org/1999/xhtml') return false;
+    const type = String(el.getAttribute('type') || '')
+      .trim()
+      .toLowerCase();
+    return type === 'checkbox' || type === 'radio';
+  }
+
   function isMarkedBusy(el) {
     const v = el.getAttribute('aria-busy');
     return v != null && String(v).trim().toLowerCase() === 'true';
@@ -165,6 +187,12 @@ function runInPage(ctx) {
 
     const required = ariaHelpers.getRequiredAttrsForRole(role).slice();
 
+    // A native checkbox or radio exposes its own checked state whatever
+    // checkable role it carries (HTML-AAM maps the checkedness; ARIA in HTML
+    // tells authors not to set aria-checked on it), so aria-checked is
+    // supplied on <input type="checkbox" role="switch"> and the like.
+    const nativeChecked = isNativeCheckable(el) && CHECKABLE_ROLES.has(role);
+
     // combobox's aria-controls is required only once the popup is actually
     // displayed (aria-expanded="true") -- see this file's header comment.
     if (role === 'combobox' && String(el.getAttribute('aria-expanded') || '').trim() === 'true') {
@@ -187,6 +215,7 @@ function runInPage(ctx) {
     const missing = [];
     for (const attr of required) {
       const v = el.getAttribute(attr);
+      if (attr === 'aria-checked' && nativeChecked) continue;
       if (v == null || String(v).trim() === '') missing.push(attr);
     }
 

package/src/checks/automatic/aria-role-name-present.js

@@ -31,7 +31,11 @@
  *   to non-empty text, or a non-empty title. Every role in the set is
  *   name-from-author-only, so descendant text is not accepted:
  *   a labelled child inside a composite widget would otherwise pass the
- *   container that has no name of its own.
+ *   container that has no name of its own. The name the HTML host element
+ *   gives itself counts too, since the browser still computes it under the
+ *   role: the first child <legend> of a <fieldset>, the first child
+ *   <caption> of a <table>, and an associated <label> on a labelable
+ *   element such as <progress> or <meter>.
  */
 
 const id = 'aria-role-name-present';
@@ -186,7 +190,20 @@ function runInPage(ctx) {
 
     const title = ariaLabel || labelled ? '' : getAttr(el, 'title');
 
-    const ok = !!(ariaLabel || labelled || title);
+    // The host's own HTML naming still applies under the role: the first
+    // <legend> of <fieldset role="radiogroup">, the <caption> of
+    // <table role="grid">, a <label> of <progress role="progressbar">.
+    let hostName = '';
+    if (!(ariaLabel || labelled || title) && helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx);
+        hostName = host && host.present ? host.value : '';
+      } catch {
+        hostName = '';
+      }
+    }
+
+    const ok = !!(ariaLabel || labelled || title || hostName);
     if (ok) continue;
 
     const eligInfo = getEligibilityInfo

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

@@ -15,8 +15,9 @@
  * @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 ID
- *   reference (list) that resolves to an existing element in the document.
+ *   from a fixed enumerated set, an integer (within the range WAI-ARIA sets
+ *   for it), 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
@@ -27,7 +28,7 @@
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
- * - ID-reference resolution (see aria-helpers.js's idExists) only flags
+ * - ID-reference resolution (see aria-helpers.js's idExists) only considers
  *   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
@@ -38,16 +39,20 @@
  *   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.
+ * - An idref list that resolves to nothing is a `cantTell`, never a fail.
+ *   The element falls back to its other name and description sources (a
+ *   <button aria-describedby="nope">Save</button> is still named "Save"),
+ *   so whether anything was lost depends on what the reference was meant
+ *   to add, and the target may be created later. aria-controls goes one
+ *   step further: a collapsed widget (aria-expanded="false" or
+ *   aria-selected="false") passes outright, since the absence of the
+ *   controlled element is exactly what that state means. A name that goes
+ *   missing because of a dangling aria-labelledby is reported by the name
+ *   rules.
+ * - Integers are also checked against the lower bounds WAI-ARIA 1.2 sets:
+ *   aria-level, aria-posinset, aria-colindex, aria-rowindex and
+ *   aria-colspan at least 1, aria-rowspan at least 0, aria-setsize at
+ *   least 1 or exactly -1.
  * - 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.
@@ -151,19 +156,26 @@ function runInPage(ctx) {
     }
 
     for (const item of review || []) {
+      const controls = item.name === 'aria-controls';
       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.',
+          hint: controls
+            ? 'Confirm the controlled element is created when the widget opens; if it never exists, remove or correct the reference.'
+            : 'Check whether an element with this id is added later. If not, correct or remove the reference; until then the element uses its other name or description sources.',
           i18n: {
             summaryKey: 'ariaValidAttrValue_summary_cantTell_idref',
-            hintKey: 'ariaValidAttrValue_hint_cantTell_idref',
+            hintKey: controls
+              ? 'ariaValidAttrValue_hint_cantTell_idref'
+              : 'ariaValidAttrValue_hint_cantTell_idrefList',
             params: { attr: item.name, value: item.value }
           },
           uncertainty: {
             code: 'runtime-dependent',
-            needed: 'Whether the widget creates the referenced element when it opens.',
+            needed: controls
+              ? 'Whether the widget creates the referenced element when it opens.'
+              : 'Whether the referenced element is added later, and whether its absence loses a name, description or relationship.',
             evidence: {
               attribute: item.name,
               referencedId: item.value,

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

@@ -10,12 +10,15 @@
  * @sc 1.3.5
  * @applicability
  *   Applies to form controls (input, select, textarea) with a non-empty
- *   autocomplete attribute.
+ *   autocomplete attribute. Disabled controls (the disabled attribute,
+ *   including a control disabled by a disabled fieldset ancestor, or
+ *   aria-disabled="true") and input types with a fixed value are exempt,
+ *   as in ACT 73f2c2.
  * @expectation
  *   The value is "on"/"off" alone, or a well-formed autofill detail
  *   token list: an optional "section-*" token, then an optional
  *   "shipping"/"billing" token, then an optional contact-modality token
- *   (home/work/mobile/fax/pager/impp), then exactly one recognized
+ *   (home/work/mobile/fax/pager), then exactly one recognized
  *   field-name token (name, email, street-address, cc-number, tel, ...),
  *   optionally followed by "webauthn". A malformed value means the field
  *   is not reliably identified for assistive technology that relies on
@@ -23,12 +26,15 @@
  * @implementation-notes
  * - Implements the structural shape of the WHATWG autofill grammar
  *   (section/mode/contact-modality prefixes + one field-name token, in
- *   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 "scoped"
- *   precedent (see aria-helpers.js) for keeping high-confidence fail
- *   without reimplementing the entire spec.
+ *   order) with the 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 "scoped" precedent (see aria-helpers.js)
+ *   for keeping high-confidence fail without reimplementing the entire
+ *   spec.
+ * - A field name that does not suit its control (bday-day on type=tel)
+ *   passes: browsers still derive the purpose from it, and ACT 73f2c2
+ *   leaves contextual appropriateness out of scope.
  */
 
 const id = 'autocomplete-valid';
@@ -113,18 +119,20 @@ function runInPage(ctx) {
     'tel-national',
     'tel-area-code',
     'tel-local',
+    'tel-local-prefix',
+    'tel-local-suffix',
     'tel-extension',
     'email',
     'impp',
     'url',
     'photo'
   ]);
-  const CONTACT_MODALITY = new Set(['home', 'work', 'mobile', 'fax', 'pager', 'impp']);
+  const CONTACT_MODALITY = new Set(['home', 'work', 'mobile', 'fax', 'pager']);
 
+  // True when the value is a well-formed autofill detail token list.
   function isValidAutocomplete(raw) {
     const tokens = raw.trim().toLowerCase().split(/\s+/).filter(Boolean);
     if (!tokens.length) return false;
-    if (tokens.length === 1 && (tokens[0] === 'on' || tokens[0] === 'off')) return true;
 
     let i = 0;
     if (tokens[i] && tokens[i].startsWith('section-') && tokens[i].length > 'section-'.length)
@@ -175,6 +183,13 @@ function runInPage(ctx) {
       if (FIXED_VALUE_TYPES.has(type)) return true;
     }
     if (el.hasAttribute && el.hasAttribute('disabled')) return true;
+    // A control inside a disabled fieldset (outside its first legend) is
+    // disabled too.
+    try {
+      if (el.matches && el.matches(':disabled')) return true;
+    } catch {
+      /* selector unsupported */
+    }
     if (String(el.getAttribute('aria-disabled') || '').toLowerCase() === 'true') return true;
     return false;
   }
@@ -197,7 +212,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This autocomplete attribute value is not a valid autofill value.',
-        hint: 'Use "on"/"off", or a valid autofill token list (e.g. "shipping street-address", "cc-number").',
+        hint: 'Use "on"/"off", or a valid autofill token list (e.g. "shipping postal-code", "cc-number").',
         i18n: {
           summaryKey: 'autocompleteValid_summary_fail',
           hintKey: 'autocompleteValid_hint_fail',

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

@@ -25,12 +25,17 @@
  * - 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 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.
+ *   wrap break, which layout would settle and this cannot. Three shapes
+ *   establish that no wrap is possible -- text not allowed to wrap, a
+ *   fixed-width element inside a horizontally scrolling ancestor, and text
+ *   with no break opportunity (one word, no CJK characters) -- and those are
+ *   reported for review rather than failed.
+ * - Text short enough to fit on one line may never wrap either, so it is also
+ *   reviewed rather than failed. "Short" is an estimate made without layout:
+ *   the text's length at half an em per character (a full em for CJK and
+ *   other wide characters) fits within 320 CSS pixels, the narrowest width
+ *   WCAG 1.4.10 asks content to reflow to. Longer text is treated as wrapping
+ *   and fails.
  */
 
 const id = 'avoid-inline-spacing';
@@ -89,6 +94,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
   const undecided = [];
   const noWrap = [];
+  const shortText = [];
 
   // Within one declaration block, importance wins over order, so the last
   // important declaration is the one that takes effect. Passed Example 5 of ACT
@@ -184,6 +190,32 @@ function runInPage(ctx) {
     return false;
   }
 
+  // Text with no break opportunity cannot take a soft wrap break: a single
+  // word of a script that separates words with spaces. CJK text can break
+  // between most characters, so it never counts as unbreakable here.
+  const WIDE_CHAR =
+    /[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/;
+  function blockText(el) {
+    return String(el.textContent || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function hasNoBreakOpportunity(text) {
+    return !!text && !/\s/.test(text) && !WIDE_CHAR.test(text);
+  }
+
+  // Whether the text may fit on one line at the narrowest width WCAG 1.4.10
+  // asks content to reflow to (320 CSS pixels), estimated without layout at
+  // half an em per character and a full em per wide character.
+  const REFLOW_WIDTH_PX = 320;
+  function mayFitOnOneLine(el, text) {
+    const fontSize = fontSizeOf(computedStyleOf(el)) || 16;
+    let ems = 0;
+    for (const ch of text) ems += WIDE_CHAR.test(ch) ? 1 : 0.5;
+    return ems * fontSize <= REFLOW_WIDTH_PX;
+  }
+
   // 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) {
@@ -290,10 +322,15 @@ function runInPage(ctx) {
     // 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)) {
+    const text = blockText(el);
+    if (cannotSoftWrap(el) || hasNoBreakOpportunity(text)) {
       noWrap.push({ el, props: flagged.slice() });
       continue;
     }
+    if (mayFitOnOneLine(el, text)) {
+      shortText.push({ el, props: flagged.slice() });
+      continue;
+    }
 
     const tag = el.tagName.toLowerCase();
 
@@ -316,27 +353,48 @@ 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 || 'moderate',
-      occurrences
-    };
-  }
-  if (noWrap.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'cantTell',
-      severity: rule.defaultSeverity || 'moderate',
-      confidence: 'low',
-      occurrences: noWrap.map(({ el, props }) =>
+
+  const cantTellOccurrences = noWrap
+    .map(({ el, props }) =>
+      helpers.reportOccurrence(el, {
+        occurrenceOutcome: 'cantTell',
+        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
+          }
+        }
+      })
+    )
+    .concat(
+      shortText.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.',
+          occurrenceOutcome: 'cantTell',
+          summary: `This element's inline style forces ${props.join(', ')} with !important, but its text is short enough to fit on one line, so it may never wrap and the text-spacing criterion may not apply to it.`,
+          hint: 'Confirm whether this text wraps at narrow widths. If it always fits on one line, the criterion does not apply; if it can wrap, remove !important or set a value that already meets the metric.',
           i18n: {
-            summaryKey: 'avoidInlineSpacing_summary_cantTell_noSoftWrap',
-            hintKey: 'avoidInlineSpacing_hint_cantTell_noSoftWrap',
+            summaryKey: 'avoidInlineSpacing_summary_cantTell_shortText',
+            hintKey: 'avoidInlineSpacing_hint_cantTell_shortText',
             params: {
               element: (el.tagName || '').toLowerCase(),
               properties: props.join(', ')
@@ -348,28 +406,23 @@ function runInPage(ctx) {
             evidence: {
               element: (el.tagName || '').toLowerCase(),
               properties: props,
-              reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP'
+              reasonCode: 'INLINE_SPACING_SHORT_TEXT'
             }
           },
           data: {
             details: {
-              reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP',
+              reasonCode: 'INLINE_SPACING_SHORT_TEXT',
               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 }) =>
+    )
+    .concat(
+      undecided.map(({ el, props }) =>
         helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
           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: {
@@ -398,9 +451,21 @@ function runInPage(ctx) {
           }
         })
       )
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+    );
+
+  // See helpers.resolveTieredOutcome (src/core/dom-helpers.js): a fail-tier
+  // finding never silently discards the cantTell-tier findings from the same
+  // run, so an undecided element survives a failure elsewhere on the page.
+  const resolved = helpers.resolveTieredOutcome(
+    occurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return {
+    ruleId: rule.ruleId,
+    ...resolved,
+    ...(resolved.outcome === 'cantTell' ? { confidence: 'low' } : null)
+  };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -22,7 +22,8 @@
  *   "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.
+ *   aria-label, an <svg>'s <title> child, or title) rather than only text
+ *   nodes.
  */
 
 // NOTE: Repo ruleId contract requires ENGINE_TAG prefix in the rule id.