fix(template-require-mandatory-role-attributes): lowercase role; split whitespace-separated role lists

Two changes, shared root cause (both deal with role-token normalisation).

1. Case-insensitive role matching. Per HTML-AAM, ARIA role tokens
   compare as ASCII-case-insensitive. Before: <div role="COMBOBOX">
   was silently accepted because "COMBOBOX" didn't match "combobox" in
   aria-query. Now: lowercase before lookup.

2. Whitespace-separated role fallback lists. Per ARIA 1.2 §5.4, a role
   attribute may list multiple tokens to express a fallback; a UA picks
   the first one it recognises. Before: role="combobox listbox" was
   treated as one opaque string, aria-query returned undefined, and
   the rule skipped silently. Now: split on whitespace, check against
   the first recognised role's required attributes (matching jsx-a11y).

Helpers renamed to plural forms (getStaticRolesFromElement,
getStaticRolesFromMustache) and getMissingRequiredAttributes now
returns { role, missing } so the reporter can use the actually-checked
role in the error message.

Four new tests cover the two cases (valid + invalid of each).

Author: johanrd

lib/rules/template-require-mandatory-role-attributes.js

@@ -1,26 +1,37 @@
 const { roles } = require('aria-query');
 const { AXObjectRoles, elementAXObjects } = require('axobject-query');
 
-function getStaticRoleFromElement(node) {
+// ARIA role values are whitespace-separated tokens compared ASCII-case-insensitively.
+// Returns the list of normalised tokens, or undefined when the attribute is
+// missing or dynamic.
+function getStaticRolesFromElement(node) {
   const roleAttr = node.attributes?.find((attr) => attr.name === 'role');
 
   if (roleAttr?.value?.type === 'GlimmerTextNode') {
-    return roleAttr.value.chars || undefined;
+    return splitRoleTokens(roleAttr.value.chars);
   }
 
   return undefined;
 }
 
-function getStaticRoleFromMustache(node) {
+function getStaticRolesFromMustache(node) {
   const rolePair = node.hash?.pairs?.find((pair) => pair.key === 'role');
 
   if (rolePair?.value?.type === 'GlimmerStringLiteral') {
-    return rolePair.value.value;
+    return splitRoleTokens(rolePair.value.value);
   }
 
   return undefined;
 }
 
+function splitRoleTokens(value) {
+  if (!value) {
+    return undefined;
+  }
+  const tokens = value.trim().toLowerCase().split(/\s+/u).filter(Boolean);
+  return tokens.length > 0 ? tokens : undefined;
+}
+
 // Reads the static lowercase value of `name` from either a GlimmerElementNode
 // (angle-bracket attributes) or a GlimmerMustacheStatement (hash pairs).
 // Returns undefined for dynamic values or missing attributes.
@@ -79,15 +90,15 @@ const AX_CONCEPTS_BY_TAG = buildAxConceptsByTag();
 function buildAxConceptsByTag() {
   const index = new Map();
   for (const [concept, axObjectNames] of elementAXObjects) {
-    const roles = new Set();
+    const conceptRoles = new Set();
     for (const axName of axObjectNames) {
       const axRoles = AXObjectRoles.get(axName);
       if (!axRoles) continue;
       for (const axRole of axRoles) {
-        roles.add(axRole.name);
+        conceptRoles.add(axRole.name);
       }
     }
-    const entry = { attributes: concept.attributes || [], roles };
+    const entry = { attributes: concept.attributes || [], roles: conceptRoles };
     if (!index.has(concept.name)) {
       index.set(concept.name, []);
     }
@@ -106,8 +117,8 @@ function isSemanticRoleElement(node, role) {
     return false;
   }
   const targetRole = role.toLowerCase();
-  for (const { attributes, roles } of entries) {
-    if (!roles.has(targetRole)) {
+  for (const { attributes, roles: conceptRoles } of entries) {
+    if (!conceptRoles.has(targetRole)) {
       continue;
     }
     const allMatch = attributes.every((cAttr) => {
@@ -127,26 +138,39 @@ function isSemanticRoleElement(node, role) {
   return false;
 }
 
-function getMissingRequiredAttributes(role, foundAriaAttributes, node) {
-  const roleDefinition = roles.get(role);
-
-  if (!roleDefinition) {
-    return null;
-  }
-
-  // If axobject-query classifies this {element, role} pair as a semantic role
-  // element, the native element provides all required ARIA state — skip the
-  // missing-attribute check entirely (matches jsx-a11y's approach).
-  if (isSemanticRoleElement(node, role)) {
-    return null;
+// For an ARIA role-fallback list like "combobox listbox", check required
+// attributes against the FIRST recognised role (the primary) per ARIA 1.2
+// role-fallback semantics — a user agent picks the first role it recognises.
+// Abstract roles (widget, input, command, section, … — ARIA §5.3) are
+// ontology categories, not valid authoring roles, so UAs skip them too.
+//
+// When the primary role is a semantic-role element (axobject-query says the
+// native element provides the required ARIA state natively — e.g. <input
+// type=checkbox role=switch>), the element is exempt: return { role, missing: null }.
+//
+// Diverges from jsx-a11y, which validates every recognised token.
+function getMissingRequiredAttributes(roleTokens, foundAriaAttributes, node) {
+  for (const role of roleTokens) {
+    const roleDefinition = roles.get(role);
+    if (!roleDefinition || roleDefinition.abstract) {
+      continue;
+    }
+    // Semantic-role elements expose required ARIA state natively — skip.
+    if (isSemanticRoleElement(node, role)) {
+      return { role, missing: null };
+    }
+    const requiredAttributes = Object.keys(roleDefinition.requiredProps);
+    const missingRequiredAttributes = requiredAttributes
+      .filter((requiredAttribute) => !foundAriaAttributes.includes(requiredAttribute))
+      // Sort for deterministic report order (aria-query's requiredProps
+      // iteration order is not guaranteed stable across versions).
+      .sort();
+    return {
+      role,
+      missing: missingRequiredAttributes.length > 0 ? missingRequiredAttributes : null,
+    };
   }
-
-  const requiredAttributes = Object.keys(roleDefinition.requiredProps);
-  const missingRequiredAttributes = requiredAttributes.filter(
-    (requiredAttribute) => !foundAriaAttributes.includes(requiredAttribute)
-  );
-
-  return missingRequiredAttributes.length > 0 ? missingRequiredAttributes : null;
+  return null;
 }
 
 /** @type {import('eslint').Rule.RuleModule} */
@@ -189,46 +213,38 @@ module.exports = {
 
     return {
       GlimmerElementNode(node) {
-        const role = getStaticRoleFromElement(node);
+        const roleTokens = getStaticRolesFromElement(node);
 
-        if (!role) {
+        if (!roleTokens) {
           return;
         }
 
         const foundAriaAttributes = (node.attributes ?? [])
           .filter((attribute) => attribute.name?.startsWith('aria-'))
           .map((attribute) => attribute.name);
 
-        const missingRequiredAttributes = getMissingRequiredAttributes(
-          role,
-          foundAriaAttributes,
-          node
-        );
+        const result = getMissingRequiredAttributes(roleTokens, foundAriaAttributes, node);
 
-        if (missingRequiredAttributes) {
-          reportMissingAttributes(node, role, missingRequiredAttributes);
+        if (result?.missing) {
+          reportMissingAttributes(node, result.role, result.missing);
         }
       },
 
       GlimmerMustacheStatement(node) {
-        const role = getStaticRoleFromMustache(node);
+        const roleTokens = getStaticRolesFromMustache(node);
 
-        if (!role) {
+        if (!roleTokens) {
           return;
         }
 
         const foundAriaAttributes = (node.hash?.pairs ?? [])
           .filter((pair) => pair.key.startsWith('aria-'))
           .map((pair) => pair.key);
 
-        const missingRequiredAttributes = getMissingRequiredAttributes(
-          role,
-          foundAriaAttributes,
-          node
-        );
+        const result = getMissingRequiredAttributes(roleTokens, foundAriaAttributes, node);
 
-        if (missingRequiredAttributes) {
-          reportMissingAttributes(node, role, missingRequiredAttributes);
+        if (result?.missing) {
+          reportMissingAttributes(node, result.role, result.missing);
         }
       },
     };

tests/lib/rules/template-require-mandatory-role-attributes.js

@@ -44,6 +44,17 @@ ruleTester.run('template-require-mandatory-role-attributes', rule, {
     '<template>{{input type="checkbox" role="switch"}}</template>',
     '<template>{{input type="Checkbox" role="switch"}}</template>',
     '<template>{{input type="range" role="slider"}}</template>',
+
+    // Case-insensitive role matching — ARIA role tokens compare as ASCII-case-insensitive.
+    '<template><div role="COMBOBOX" aria-expanded="false" aria-controls="ctrl" /></template>',
+    // Role fallback list — primary role's required attributes are satisfied.
+    '<template><div role="combobox listbox" aria-expanded="false" aria-controls="ctrl" /></template>',
+    // Abstract roles (ARIA §5.3) are skipped per §4.1 fallback semantics —
+    // `widget` isn't an authoring role, so the UA walks past it to the next
+    // recognised token. Here `button` has no required attrs → valid.
+    '<template><div role="widget button" /></template>',
+    // Abstract role followed by a concrete role that IS satisfied.
+    '<template><div role="command slider" aria-valuenow="0" /></template>',
   ],
 
   invalid: [
@@ -148,6 +159,38 @@ ruleTester.run('template-require-mandatory-role-attributes', rule, {
       output: null,
       errors: [{ message: 'The attribute aria-checked is required by the role menuitemradio' }],
     },
+    // Case-insensitivity surfaces previously-unflagged mistakes.
+    {
+      code: '<template><div role="COMBOBOX"></div></template>',
+      output: null,
+      errors: [
+        {
+          message: 'The attributes aria-controls, aria-expanded are required by the role combobox',
+        },
+      ],
+    },
+    // Role-fallback list: when the primary role is missing required props, flag it.
+    {
+      code: '<template><div role="combobox listbox"></div></template>',
+      output: null,
+      errors: [
+        {
+          message: 'The attributes aria-controls, aria-expanded are required by the role combobox',
+        },
+      ],
+    },
+    // Abstract role (`widget`) followed by a concrete role that's missing
+    // required attrs — UA skips the abstract, lands on `slider`, which
+    // requires aria-valuenow.
+    {
+      code: '<template><div role="widget slider"></div></template>',
+      output: null,
+      errors: [
+        {
+          message: 'The attribute aria-valuenow is required by the role slider',
+        },
+      ],
+    },
   ],
 });