Merge pull request #2729 from johanrd/fix/invalid-role-aria-query

BUGFIX: template-no-invalid-role — support DPUB/Graphics-ARIA and role-fallback lists

Author: NullVoxPopuli

lib/rules/template-no-invalid-role.js

@@ -1,92 +1,22 @@
-const VALID_ROLES = new Set([
-  'alert',
-  'alertdialog',
-  'application',
-  'article',
+const { roles } = require('aria-query');
+
+// Valid ARIA roles = concrete (non-abstract) entries from aria-query, plus the
+// WAI-ARIA 1.3 draft roles that aria-query 5.3.2 doesn't yet ship. The
+// ARIA 1.2 base roles, DPUB-ARIA (doc-*), and Graphics-ARIA (graphics-*) all
+// come from aria-query. `associationlist*`, `comment`, and `suggestion` are in
+// the current ARIA 1.3 editor's draft (https://w3c.github.io/aria/) but not
+// yet in aria-query, so they're listed here until the next aria-query release
+// adds them.
+const ARIA_13_DRAFT_ROLES = [
   'associationlist',
   'associationlistitemkey',
   'associationlistitemvalue',
-  'banner',
-  'blockquote',
-  'button',
-  'caption',
-  'cell',
-  'checkbox',
-  'code',
-  'columnheader',
-  'combobox',
   'comment',
-  'complementary',
-  'contentinfo',
-  'definition',
-  'deletion',
-  'dialog',
-  'directory',
-  'document',
-  'emphasis',
-  'feed',
-  'figure',
-  'form',
-  'generic',
-  'grid',
-  'gridcell',
-  'group',
-  'heading',
-  'img',
-  'insertion',
-  'link',
-  'list',
-  'listbox',
-  'listitem',
-  'log',
-  'main',
-  'mark',
-  'marquee',
-  'math',
-  'menu',
-  'menubar',
-  'menuitem',
-  'menuitemcheckbox',
-  'menuitemradio',
-  'meter',
-  'navigation',
-  'none',
-  'note',
-  'option',
-  'paragraph',
-  'presentation',
-  'progressbar',
-  'radio',
-  'radiogroup',
-  'region',
-  'row',
-  'rowgroup',
-  'rowheader',
-  'scrollbar',
-  'search',
-  'searchbox',
-  'separator',
-  'slider',
-  'spinbutton',
-  'status',
-  'strong',
-  'subscript',
   'suggestion',
-  'superscript',
-  'switch',
-  'tab',
-  'table',
-  'tablist',
-  'tabpanel',
-  'term',
-  'textbox',
-  'time',
-  'timer',
-  'toolbar',
-  'tooltip',
-  'tree',
-  'treegrid',
-  'treeitem',
+];
+const VALID_ROLES = new Set([
+  ...[...roles.keys()].filter((role) => !roles.get(role).abstract),
+  ...ARIA_13_DRAFT_ROLES,
 ]);
 
 // Elements with semantic meaning that should not be given role="presentation" or role="none"
@@ -225,34 +155,56 @@ module.exports = {
           return;
         }
 
-        const role = roleAttr.value.chars.trim();
-        if (!role) {
-          return;
-        }
-
-        const roleLower = role.toLowerCase();
-
-        // Check for nonexistent roles
-        if (catchNonexistentRoles && !VALID_ROLES.has(roleLower)) {
+        // ARIA role attribute is a whitespace-separated list of tokens
+        // (role-fallback pattern per ARIA 1.2 §5.4). An empty / whitespace-
+        // only value supplies zero tokens — flag as `role=""` to catch the
+        // authoring mistake (matches jsx-a11y / vue-a11y).
+        const raw = roleAttr.value.chars.trim();
+        if (!raw) {
           context.report({
             node: roleAttr,
             messageId: 'invalid',
-            data: { role },
+            data: { role: '' },
           });
           return;
         }
 
-        // Check for presentation/none role on semantic elements (case-insensitive per WAI-ARIA 1.2:
-        // "Case-sensitivity of the comparison inherits from the case-sensitivity of the host language"
-        // and HTML is case-insensitive — https://www.w3.org/TR/wai-aria-1.2/#document-handling_author-errors_roles)
+        // Validate each token. Keep the original casing alongside the
+        // normalized (lowercase) form so reported tokens preserve author
+        // intent — validation is case-insensitive, the ERROR MESSAGE isn't.
+        const rawTokens = raw.split(/\s+/u);
+        const tokens = rawTokens.map((t) => t.toLowerCase());
+
+        if (catchNonexistentRoles) {
+          const invalidIdx = tokens.findIndex((token) => !VALID_ROLES.has(token));
+          if (invalidIdx !== -1) {
+            context.report({
+              node: roleAttr,
+              messageId: 'invalid',
+              data: { role: rawTokens[invalidIdx] },
+            });
+            return;
+          }
+        }
+
+        // Flag presentation/none only when it's the FIRST recognised role per
+        // WAI-ARIA §4.1 fallback semantics — UAs walk the token list and use
+        // the first role they recognise; subsequent tokens are author-provided
+        // fallbacks that never take effect if the first is recognised. So
+        // `role="button presentation"` resolves to `button` at runtime and
+        // should NOT flag. `role="xxyxyz presentation"` resolves to
+        // `presentation` (unknown tokens are skipped) and SHOULD flag on a
+        // semantic element. Case-insensitivity inherits from HTML per §4.1:
+        // https://www.w3.org/TR/wai-aria-1.2/#document-handling_author-errors_roles
+        const firstRecognisedRole = tokens.find((t) => VALID_ROLES.has(t));
         if (
-          (roleLower === 'presentation' || roleLower === 'none') &&
+          (firstRecognisedRole === 'presentation' || firstRecognisedRole === 'none') &&
           SEMANTIC_ELEMENTS.has(node.tag)
         ) {
           context.report({
             node: roleAttr,
             messageId: 'presentationOnSemantic',
-            data: { role, tag: node.tag },
+            data: { role: firstRecognisedRole, tag: node.tag },
           });
         }
       },

tests/lib/rules/template-no-invalid-role.js

@@ -57,9 +57,6 @@ ruleTester.run('template-no-invalid-role', rule, {
     '<template><table role="textbox"></table></template>',
     '<template><div role="{{if this.inModal "dialog" "contentinfo" }}"></div></template>',
 
-    // Missing VALID_ROLES entries: associationlistitemkey, associationlistitemvalue, cell
-    '<template><div role="associationlistitemkey">Key</div></template>',
-    '<template><div role="associationlistitemvalue">Value</div></template>',
     '<template><td role="cell">Data</td></template>',
 
     // Case-insensitive role matching
@@ -71,9 +68,56 @@ ruleTester.run('template-no-invalid-role', rule, {
       code: '<template><div role="command interface"></div></template>',
       options: [{ catchNonexistentRoles: false }],
     },
+
+    // DPUB-ARIA (doc-*) and Graphics-ARIA (graphics-*) are valid per aria-query.
+    '<template><div role="doc-abstract">Abstract</div></template>',
+    '<template><section role="doc-chapter"></section></template>',
+    '<template><svg role="graphics-document"></svg></template>',
+    '<template><svg role="graphics-object"></svg></template>',
+
+    // Whitespace-separated role fallback list — ARIA 1.2 §5.4. Each token
+    // must individually be valid.
+    '<template><div role="tabpanel row"></div></template>',
+    '<template><svg role="graphics-document document"></svg></template>',
+    '<template><section role="doc-appendix doc-bibliography"></section></template>',
+
+    // Role-fallback: `presentation`/`none` in a non-first position does NOT
+    // flag on a semantic element — UAs pick the first recognised role per
+    // §4.1. Here `button` resolves, `presentation` is an unused fallback.
+    '<template><ul role="list presentation"></ul></template>',
+    '<template><table role="grid none"></table></template>',
+
+    // ARIA 1.3 draft roles — not in aria-query 5.3.2 but spec-blessed, so
+    // the rule accepts them via the inline allowlist.
+    '<template><div role="associationlist"></div></template>',
+    '<template><div role="associationlistitemkey"></div></template>',
+    '<template><div role="associationlistitemvalue"></div></template>',
+    '<template><div role="comment"></div></template>',
+    '<template><div role="suggestion"></div></template>',
   ],
 
   invalid: [
+    // Common authoring confusion — `datepicker` looks like it could be a
+    // role (it's a UI concept) but isn't in the ARIA registry. Same lookup
+    // path as `role="invalid"`, exercised here for the more likely typo.
+    {
+      code: '<template><div role="datepicker"></div></template>',
+      output: null,
+      errors: [{ messageId: 'invalid' }],
+    },
+    // Empty / whitespace-only role attribute supplies no recognized role
+    // token — flag as an authoring mistake. Aligns with jsx-a11y and
+    // vue-a11y (both flag).
+    {
+      code: '<template><div role=""></div></template>',
+      output: null,
+      errors: [{ messageId: 'invalid' }],
+    },
+    {
+      code: '<template><div role="   "></div></template>',
+      output: null,
+      errors: [{ messageId: 'invalid' }],
+    },
     {
       code: `<template>
         <div role="invalid">Content</div>
@@ -144,6 +188,18 @@ ruleTester.run('template-no-invalid-role', rule, {
         { message: 'The role "presentation" should not be used on the semantic element <button>.' },
       ],
     },
+    // Role-fallback: unknown leading token is skipped per §4.1, so the
+    // first RECOGNISED role is `presentation` → flag on semantic element.
+    // Uses catchNonexistentRoles: false so the unknown `xxyxyz` doesn't
+    // intercept the check via the invalid-role path.
+    {
+      code: '<template><ul role="xxyxyz presentation"></ul></template>',
+      output: null,
+      options: [{ catchNonexistentRoles: false }],
+      errors: [
+        { message: 'The role "presentation" should not be used on the semantic element <ul>.' },
+      ],
+    },
     {
       code: '<template><button role="none"></button></template>',
       output: null,
@@ -164,18 +220,20 @@ ruleTester.run('template-no-invalid-role', rule, {
     {
       code: '<template><div role="command interface"></div></template>',
       output: null,
-      errors: [{ message: "Invalid ARIA role 'command interface'. Must be a valid ARIA role." }],
+      errors: [{ message: "Invalid ARIA role 'command'. Must be a valid ARIA role." }],
     },
     {
       code: '<template><div role="COMMAND INTERFACE"></div></template>',
       output: null,
-      errors: [{ message: "Invalid ARIA role 'COMMAND INTERFACE'. Must be a valid ARIA role." }],
+      // Validation is case-insensitive, but the error message echoes the
+      // author-provided token verbatim so authors see their own text.
+      errors: [{ message: "Invalid ARIA role 'COMMAND'. Must be a valid ARIA role." }],
     },
     {
       code: '<template><div role="command interface"></div></template>',
       output: null,
       options: [{ catchNonexistentRoles: true }],
-      errors: [{ message: "Invalid ARIA role 'command interface'. Must be a valid ARIA role." }],
+      errors: [{ message: "Invalid ARIA role 'command'. Must be a valid ARIA role." }],
     },
 
     // Newly added SEMANTIC_ELEMENTS: presentation/none on iframe, video, audio
@@ -234,9 +292,6 @@ hbsRuleTester.run('template-no-invalid-role', rule, {
     '<AwesomeThing role="presentation"></AwesomeThing>',
     '<table role="textbox"></table>',
     '<div role="{{if this.inModal "dialog" "contentinfo" }}"></div>',
-    // Missing VALID_ROLES entries: associationlistitemkey, associationlistitemvalue, cell
-    '<div role="associationlistitemkey">Key</div>',
-    '<div role="associationlistitemvalue">Value</div>',
     '<td role="cell">Data</td>',
     // Case-insensitive role matching
     '<div role="Button">Click</div>',
@@ -247,6 +302,24 @@ hbsRuleTester.run('template-no-invalid-role', rule, {
       code: '<div role="command interface"></div>',
       options: [{ catchNonexistentRoles: false }],
     },
+
+    // DPUB-ARIA (doc-*) and Graphics-ARIA (graphics-*) roles.
+    '<div role="doc-abstract">Abstract</div>',
+    '<section role="doc-chapter"></section>',
+    '<svg role="graphics-document"></svg>',
+
+    // Whitespace-separated role fallback list.
+    '<div role="tabpanel row"></div>',
+    '<svg role="graphics-document document"></svg>',
+    '<section role="doc-appendix doc-bibliography"></section>',
+
+    // ARIA 1.3 draft roles — not in aria-query 5.3.2 but spec-blessed, so
+    // the rule accepts them via the inline allowlist.
+    '<div role="associationlist"></div>',
+    '<div role="associationlistitemkey"></div>',
+    '<div role="associationlistitemvalue"></div>',
+    '<div role="comment"></div>',
+    '<div role="suggestion"></div>',
   ],
   invalid: [
     {
@@ -302,18 +375,20 @@ hbsRuleTester.run('template-no-invalid-role', rule, {
     {
       code: '<div role="command interface"></div>',
       output: null,
-      errors: [{ message: "Invalid ARIA role 'command interface'. Must be a valid ARIA role." }],
+      errors: [{ message: "Invalid ARIA role 'command'. Must be a valid ARIA role." }],
     },
     {
       code: '<div role="command interface"></div>',
       output: null,
       options: [{ catchNonexistentRoles: true }],
-      errors: [{ message: "Invalid ARIA role 'command interface'. Must be a valid ARIA role." }],
+      errors: [{ message: "Invalid ARIA role 'command'. Must be a valid ARIA role." }],
     },
     {
       code: '<div role="COMMAND INTERFACE"></div>',
       output: null,
-      errors: [{ message: "Invalid ARIA role 'COMMAND INTERFACE'. Must be a valid ARIA role." }],
+      // Validation is case-insensitive, but the error message echoes the
+      // author-provided token verbatim so authors see their own text.
+      errors: [{ message: "Invalid ARIA role 'COMMAND'. Must be a valid ARIA role." }],
     },
     // Newly added SEMANTIC_ELEMENTS: presentation/none on iframe, video, audio, embed
     {