@surea11y/core 1.6.0 → 1.8.0

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

@@ -11,16 +11,15 @@
  * @applicability
  *   Applies to any element with a non-empty role="" attribute in the composed DOM.
  * @expectation
- *   The role attribute's first token (the role actually used by assistive technology;
- *   later space-separated tokens are author-supplied fallbacks and are not evaluated
- *   here) must be a real WAI-ARIA role name, and must not be an abstract role
- *   (abstract roles exist only for the specification's own role taxonomy and must
- *   never be used directly in markup).
- * @implementation-notes
- * - Unlike this engine's accessible-name rules, ARIA validity is a static markup
- *   property independent of current visibility/eligibility, so this rule does not
- *   gate on isAccTreeEligible: an invalid role is a defect whether or not the
- *   element happens to be hidden right now.
+ *   At least one role token names a concrete, non-abstract ARIA role.
+ *   Graded by what the element falls back to when none does:
+ *   - FAIL on a roleless host (div, span, custom element), which is left
+ *     exposed as generic, so the role the author meant reaches no one.
+ *   - CANTTELL where the element has a native role (a <button>, <nav>,
+ *     <a href>), which the accessibility tree keeps using. ACT 674b10 lists
+ *     4.1.2 as a secondary requirement only, "satisfied through the implicit
+ *     role," so the bad token is worth reporting but is not itself the
+ *     criterion failing.
  */
 
 const id = 'aria-roles-valid';
@@ -64,7 +63,8 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   // Programmatically hidden per the ACT glossary: display:none, visibility not
@@ -121,8 +121,42 @@ function runInPage(ctx) {
     const isKnown = tokens.some((t) => ariaHelpers.isKnownRole(t));
     const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
 
-    occurrences.push(
+    // An unusable role token leaves the element on its native role, when it
+    // has one: ACT 674b10 lists 4.1.2 as only a secondary requirement for
+    // exactly that reason. A roleless host (div, span, custom element) has
+    // nothing to fall back to and is exposed as generic instead.
+    const nativeRole =
+      typeof ariaHelpers.getNativeRoleForElement === 'function'
+        ? ariaHelpers.getNativeRoleForElement(el) || ''
+        : '';
+
+    if (nativeRole) {
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
+          summary: `The role attribute value is not usable, so this element is still exposed as its native role="${nativeRole}".`,
+          hint: 'Fix or remove the role token; assistive technology is using the native role in the meantime.',
+          i18n: {
+            summaryKey: 'ariaRolesValid_summary_cantTell',
+            hintKey: 'ariaRolesValid_hint_cantTell',
+            params: { role, nativeRole }
+          },
+          uncertainty: {
+            code: 'spec-only',
+            needed: 'Whether the native role this element falls back to is the one intended.',
+            evidence: { role, nativeRole, fallbackExposed: true }
+          },
+          data: {
+            details: { reasonCode, role, nativeRole }
+          }
+        })
+      );
+      continue;
+    }
+
+    failOccurrences.push(
       helpers.reportOccurrence(el, {
+        occurrenceOutcome: 'fail',
         summary: !isKnown
           ? 'The role attribute value is not a recognized ARIA role.'
           : 'The role attribute value is an abstract ARIA role, which must not be used directly.',
@@ -146,15 +180,12 @@ 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(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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,6 +39,23 @@
  *   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).
+ * - 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.
  */
 
 const id = 'aria-valid-attr-value';
@@ -79,13 +97,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();
@@ -95,21 +115,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).',
@@ -129,20 +154,60 @@ 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: 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: controls
+              ? 'ariaValidAttrValue_hint_cantTell_idref'
+              : 'ariaValidAttrValue_hint_cantTell_idrefList',
+            params: { attr: item.name, value: item.value }
+          },
+          uncertainty: {
+            code: 'runtime-dependent',
+            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,
+              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,6 +16,12 @@
  *   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
@@ -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

@@ -10,25 +10,40 @@
  * @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
- *   autocomplete to describe the expected input purpose.
+ *   optionally followed by "webauthn". The field name must also suit the
+ *   control: the HTML Standard gives each field name a control group, and
+ *   each group is allowed only on some input types (street-address only on
+ *   textarea or select; email only on text, search or email inputs; and so
+ *   on). A malformed or unsuitable value means the field is not reliably
+ *   identified for assistive technology that relies on autocomplete to
+ *   describe the expected input purpose.
  * @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.
+ * - Control groups: textarea, select and input type=hidden accept every
+ *   group. input types text and search (and a missing or unknown type)
+ *   accept every group except Multiline (street-address). password, email,
+ *   url, tel, number, month and date inputs accept only their own group
+ *   (email also accepts username). Other input types (time, week,
+ *   datetime-local, range, color) are not checked for the group, as the
+ *   W3C validator does not check them either. A mismatch is reported with
+ *   reasonCode AUTOCOMPLETE_FIELD_CONTROL_MISMATCH.
  */
 
 const id = 'autocomplete-valid';
@@ -113,18 +128,78 @@ 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']);
 
-  function isValidAutocomplete(raw) {
+  // Control group of each field name that is not in the Text group (HTML
+  // Standard, autofill field table).
+  const FIELD_GROUP = {
+    username: 'username',
+    'new-password': 'password',
+    'current-password': 'password',
+    'one-time-code': 'password',
+    'street-address': 'multiline',
+    'cc-exp': 'month',
+    'cc-exp-month': 'numeric',
+    'cc-exp-year': 'numeric',
+    'transaction-amount': 'numeric',
+    bday: 'date',
+    'bday-day': 'numeric',
+    'bday-month': 'numeric',
+    'bday-year': 'numeric',
+    url: 'url',
+    photo: 'url',
+    impp: 'url',
+    tel: 'tel',
+    email: 'email'
+  };
+  // Groups accepted by input types other than text and search. text and
+  // search accept every group except multiline.
+  const GROUPS_BY_INPUT_TYPE = {
+    password: ['password'],
+    email: ['email', 'username'],
+    url: ['url'],
+    tel: ['tel'],
+    number: ['numeric'],
+    month: ['month'],
+    date: ['date']
+  };
+  const KNOWN_INPUT_TYPES = new Set([
+    'hidden',
+    'text',
+    'search',
+    'tel',
+    'url',
+    'email',
+    'password',
+    'date',
+    'month',
+    'week',
+    'time',
+    'datetime-local',
+    'number',
+    'range',
+    'color',
+    'checkbox',
+    'radio',
+    'file',
+    'submit',
+    'image',
+    'reset',
+    'button'
+  ]);
+
+  // Returns the field-name token of a well-formed value, or null.
+  function getFieldName(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;
+    if (!tokens.length) return null;
 
     let i = 0;
     if (tokens[i] && tokens[i].startsWith('section-') && tokens[i].length > 'section-'.length)
@@ -136,7 +211,7 @@ function runInPage(ctx) {
       const next = tokens[i + 1];
       const isContactField =
         next === 'email' || next === 'impp' || next === 'tel' || (next || '').startsWith('tel-');
-      if (!isContactField) return false;
+      if (!isContactField) return null;
       i += 1;
     }
 
@@ -144,8 +219,24 @@ function runInPage(ctx) {
     if (tokens[end - 1] === 'webauthn') end -= 1;
 
     const remaining = tokens.slice(i, end);
-    if (remaining.length !== 1) return false;
-    return FIELD_NAMES.has(remaining[0]);
+    if (remaining.length !== 1) return null;
+    return FIELD_NAMES.has(remaining[0]) ? remaining[0] : null;
+  }
+
+  // True when the field name's control group is allowed on this control.
+  function fieldSuitsControl(el, fieldName) {
+    const tag = String(el.tagName || '').toLowerCase();
+    if (tag !== 'input') return true;
+    let type = String(el.getAttribute('type') || 'text')
+      .trim()
+      .toLowerCase();
+    if (!KNOWN_INPUT_TYPES.has(type)) type = 'text';
+    if (type === 'hidden') return true;
+    const group = FIELD_GROUP[fieldName] || 'text';
+    if (type === 'text' || type === 'search') return group !== 'multiline';
+    const allowed = GROUPS_BY_INPUT_TYPE[type];
+    if (!allowed) return true;
+    return allowed.includes(group);
   }
 
   const nodes = helpers.queryAllSmart
@@ -175,6 +266,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;
   }
@@ -190,21 +288,49 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    if (isValidAutocomplete(raw)) continue;
-
+    const fieldName = getFieldName(raw);
     const tag = el.tagName.toLowerCase();
 
+    if (!fieldName) {
+      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 postal-code", "cc-number").',
+          i18n: {
+            summaryKey: 'autocompleteValid_summary_fail',
+            hintKey: 'autocompleteValid_hint_fail',
+            params: { element: tag, value: raw }
+          },
+          data: {
+            details: { reasonCode: 'AUTOCOMPLETE_VALUE_INVALID', element: tag, value: raw }
+          }
+        })
+      );
+      continue;
+    }
+
+    if (fieldSuitsControl(el, fieldName)) continue;
+
+    const inputType = String(el.getAttribute('type') || 'text')
+      .trim()
+      .toLowerCase();
     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").',
+        summary: `The autofill field name "${fieldName}" is not allowed on an input of type "${inputType}".`,
+        hint: 'Use a field name that suits this type of control, or change the control (street-address needs a textarea; email needs a text, search or email input; bday-day needs a text, search or number input).',
         i18n: {
-          summaryKey: 'autocompleteValid_summary_fail',
-          hintKey: 'autocompleteValid_hint_fail',
-          params: { element: tag, value: raw }
+          summaryKey: 'autocompleteValid_summary_mismatch',
+          hintKey: 'autocompleteValid_hint_mismatch',
+          params: { element: tag, value: raw, fieldName, inputType }
         },
         data: {
-          details: { reasonCode: 'AUTOCOMPLETE_VALUE_INVALID', element: tag, value: raw }
+          details: {
+            reasonCode: 'AUTOCOMPLETE_FIELD_CONTROL_MISMATCH',
+            element: tag,
+            value: raw,
+            fieldName,
+            inputType
+          }
         }
       })
     );