Merge pull request #2728 from johanrd/fix/role-required-aria-case-and-space-split

NullVoxPopuli · web-flow · commit 414d6d5d7590 · 2026-04-27T09:12:00.000-04:00
BUGFIX: template-require-mandatory-role-attributes — lowercase role + split whitespace role lists
diff --git a/docs/rules/template-require-mandatory-role-attributes.md b/docs/rules/template-require-mandatory-role-attributes.md
@@ -47,14 +47,14 @@ When the role attribute explicitly declares a role that the native element alrea
 
 Exempt pairings include (non-exhaustive):
 
-| Element                   | Role                 | Required ARIA state supplied by                  |
-| ------------------------- | -------------------- | ------------------------------------------------ |
-| `<input type="checkbox">` | `checkbox`, `switch` | native `checked` state                           |
-| `<input type="radio">`    | `radio`              | native `checked` state                           |
-| `<input type="range">`    | `slider`             | native `value` / `min` / `max`                   |
-| `<input type="number">`   | `spinbutton`         | native `value` (spinbutton has no required ARIA) |
-| `<input type="text">`     | `textbox`            | no required ARIA                                 |
-| `<input type="search">`   | `searchbox`          | no required ARIA                                 |
+| Element                   | Role                 | Required ARIA state supplied by                                                                           |
+| ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `<input type="checkbox">` | `checkbox`, `switch` | native `checked` state                                                                                    |
+| `<input type="radio">`    | `radio`              | native `checked` state                                                                                    |
+| `<input type="range">`    | `slider`             | native `value` / `min` / `max`                                                                            |
+| `<input type="number">`   | `spinbutton`         | native `value` / `min` / `max` (spinbutton's required `aria-valuenow` is derived from the native `value`) |
+| `<input type="text">`     | `textbox`            | no required ARIA                                                                                          |
+| `<input type="search">`   | `searchbox`          | no required ARIA                                                                                          |
 
 Undocumented pairings (e.g. `<input type="checkbox" role="menuitemcheckbox">` — axobject-query does not list this) remain flagged.
 
diff --git a/lib/rules/template-require-mandatory-role-attributes.js b/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.
@@ -42,20 +53,30 @@ function getStaticAttrValue(node, name) {
   return undefined;
 }
 
-function getTagName(node) {
+// In classic Handlebars (.hbs) `{{input}}` globally resolves to Ember's
+// built-in input helper, which renders a native <input>. In strict-mode
+// GJS/GTS there is no corresponding lowercase `input` export from
+// `@ember/component` (only the PascalCase `<Input>` component), so
+// `{{input}}` in strict mode is always a user-bound identifier and cannot
+// be assumed to render a native <input>. Treating it as native there
+// would silently skip required-ARIA checks on arbitrary components.
+function isClassicHbsFilename(context) {
+  const filename = context.filename || context.getFilename?.() || '';
+  return !filename.endsWith('.gjs') && !filename.endsWith('.gts');
+}
+
+function getTagName(node, context) {
   if (node?.type === 'GlimmerElementNode') {
-    return node.tag;
+    // HTML tag names are case-insensitive; normalize so <INPUT>/<Input> match
+    // the lowercase keys in AX_CONCEPTS_BY_TAG and the semantic-role maps.
+    return node.tag?.toLowerCase();
   }
   if (node?.type === 'GlimmerMustacheStatement' && node.path?.original === 'input') {
-    // The classic `{{input}}` helper renders a native <input>.
-    //
-    // Caveat: in strict GJS/GTS mode, `{{input}}` is whatever was imported
-    // under the name `input` — it could be the classic helper (still renders
-    // native <input>) or some user-defined component. We assume the classic
-    // helper; the false-positive rate in practice is low because strict-mode
-    // authors rarely use `{{input}}` at all (idiomatic is <input> or
-    // <Input>), and when they do, it's almost always the imported built-in.
-    return 'input';
+    if (!context || isClassicHbsFilename(context)) {
+      return 'input';
+    }
+    // Strict-mode {{input}} — not the classic helper, can't claim native.
+    return null;
   }
   return null;
 }
@@ -79,17 +100,17 @@ 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, []);
     }
@@ -98,8 +119,8 @@ function buildAxConceptsByTag() {
   return index;
 }
 
-function isSemanticRoleElement(node, role) {
-  const tag = getTagName(node);
+function isSemanticRoleElement(node, role, context) {
+  const tag = getTagName(node, context);
   if (!tag || typeof role !== 'string') {
     return false;
   }
@@ -108,8 +129,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) => {
@@ -129,26 +150,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, context) {
+  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, context)) {
+      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} */
@@ -191,46 +225,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, context);
 
-        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, context);
 
-        if (missingRequiredAttributes) {
-          reportMissingAttributes(node, role, missingRequiredAttributes);
+        if (result?.missing) {
+          reportMissingAttributes(node, result.role, result.missing);
         }
       },
     };
diff --git a/tests/lib/rules/template-require-mandatory-role-attributes.js b/tests/lib/rules/template-require-mandatory-role-attributes.js
@@ -45,16 +45,17 @@ ruleTester.run('template-require-mandatory-role-attributes', rule, {
     '<template>{{input type="Checkbox" role="switch"}}</template>',
     '<template>{{input type="range" role="slider"}}</template>',
 
-    // Documented divergences from jsx-a11y / vue-a11y / angular-eslint:
-    // - Space-separated role tokens: peers split on whitespace and require
-    //   attrs for each token. We pass the whole string to aria-query, so
-    //   `role="combobox listbox"` lookup misses → no flag. (Case below.)
-    // - Case-folding role values: peers lowercase before lookup; we don't.
-    //   `role="COMBOBOX"` similarly misses lookup → no flag.
-    // - Unknown role: all plugins skip — parity, captured for completeness.
-    '<template><div role="combobox listbox" /></template>',
-    '<template><div role="COMBOBOX" /></template>',
-    '<template><div 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>',
+    // Unknown roles are skipped — rule only checks required attrs for known roles.
     '<template><div role="foobar" /></template>',
   ],
 
@@ -73,6 +74,18 @@ ruleTester.run('template-require-mandatory-role-attributes', rule, {
       output: null,
       errors: [{ message: 'The attribute aria-selected is required by the role option' }],
     },
+    // Plain widget roles missing all required attrs — basic coverage that
+    // peer plugins (jsx-a11y / vue-a11y / angular-eslint) also flag.
+    {
+      code: '<template><div role="slider" /></template>',
+      output: null,
+      errors: [{ message: 'The attribute aria-valuenow is required by the role slider' }],
+    },
+    {
+      code: '<template><div role="checkbox" /></template>',
+      output: null,
+      errors: [{ message: 'The attribute aria-checked is required by the role checkbox' }],
+    },
     {
       code: '<template><CustomComponent role="checkbox" aria-required="true" /></template>',
       output: null,
@@ -160,6 +173,62 @@ ruleTester.run('template-require-mandatory-role-attributes', rule, {
       output: null,
       errors: [{ message: 'The attribute aria-checked is required by the role menuitemradio' }],
     },
+    // Case-insensitive role matching — uppercase role missing required props is flagged.
+    {
+      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',
+        },
+      ],
+    },
+    // Strict-mode {{input}} is a scope binding, not Ember's classic helper
+    // (which doesn't exist as a strict-mode export from @ember/component).
+    // The semantic-role exemption must NOT apply — we can't prove the
+    // imported identifier renders a native <input>. Flag the missing ARIA.
+    {
+      filename: 'component.gjs',
+      code: '<template>{{input type="checkbox" role="switch"}}</template>',
+      output: null,
+      errors: [
+        {
+          message: 'The attribute aria-checked is required by the role switch',
+        },
+      ],
+    },
+    {
+      filename: 'component.gts',
+      code: '<template>{{input type="range" role="slider"}}</template>',
+      output: null,
+      errors: [
+        {
+          message: 'The attribute aria-valuenow is required by the role slider',
+        },
+      ],
+    },
   ],
 });
 
