feat: recurse into focusable descendants for aria-hidden check

Flag `aria-hidden="true"` on an element whose subtree contains a focusable
descendant, not just on the element itself. Per WAI-ARIA 1.2 §aria-hidden
("SHOULD NOT use aria-hidden='true' on any element that has focus or may
receive focus"), "may receive focus" includes focusable descendants:
aria-hidden hides the subtree from assistive tech, but descendants remain
keyboard-reachable — a keyboard trap onto AT-invisible content.

- Add `hasFocusableDescendant(node)` that walks GlimmerElementNode children
  and recurses; uses the existing `isFocusable` helper. Skips opaque tags
  (PascalCase components, `@`-prefixed, `this.`-prefixed, path-/namespace-
  pathed) and non-element AST nodes (TextNode, mustache) — bias toward
  no-FP.
- New messageId `noAriaHiddenOnAncestorOfFocusable` distinguishes the
  descendant case from the carrier case in reports.
- Rule doc adds spec citation and opaque-descendant caveat.
- Rule tests: add invalid cases for descendant buttons, links, inputs,
  tabindex descendants, and nested depth; add valid cases for text-only
  descendants, component descendants, hidden inputs, dynamic mustaches.
- Audit fixture: descendant-focusable case moves from DIVERGENCE to
  parity with vue-a11y; `tabindex="-1"` on descendants documented as an
  extension of the existing tabindex="-1" divergence (we flag, they don't).

Author: johanrd

docs/rules/template-no-aria-hidden-on-focusable.md

@@ -2,14 +2,16 @@
 
 <!-- end auto-generated rule header -->
 
-Disallow `aria-hidden="true"` on focusable elements.
+Disallow `aria-hidden="true"` on focusable elements or elements containing focusable descendants.
 
-An element with `aria-hidden="true"` is removed from the accessibility tree but remains keyboard-focusable. This creates a keyboard trap — users reach the element via Tab but can't perceive it.
+An element with `aria-hidden="true"` is removed from the accessibility tree but remains keyboard-focusable. This creates a keyboard trap — users reach the element via Tab but can't perceive it. The same applies to focusable descendants of an `aria-hidden` ancestor, since `aria-hidden` does not remove elements from the tab order.
 
 Per [WAI-ARIA 1.2 — aria-hidden](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden):
 
 > Authors SHOULD NOT use `aria-hidden="true"` on any element that has focus or may receive focus, either directly via interaction with the user or indirectly via programmatic means such as JavaScript-based event handling.
 
+The phrase "may receive focus" is interpreted to include focusable descendants: `aria-hidden` cascades to hide the entire subtree from assistive tech, while any focusable descendant within that subtree remains reachable via Tab — landing keyboard users on AT-invisible content.
+
 ## Examples
 
 This rule **forbids** the following:
@@ -19,6 +21,11 @@ This rule **forbids** the following:
   <button aria-hidden="true">Trapped</button>
   <a href="/x" aria-hidden="true">Link</a>
   <div tabindex="0" aria-hidden="true">Focusable but hidden</div>
+
+  {{! Focusable descendant inside an aria-hidden ancestor — classic modal backdrop trap }}
+  <div aria-hidden="true">
+    <button>Close</button>
+  </div>
 </template>
 ```
 
@@ -34,11 +41,25 @@ This rule **allows** the following:
 
   {{! input type="hidden" is not focusable }}
   <input type="hidden" aria-hidden="true" />
+
+  {{! Component/dynamic descendants are opaque — conservatively not flagged }}
+  <div aria-hidden="true"><CustomBtn /></div>
 </template>
 ```
 
+## Caveats
+
+Component invocations, argument/`this`/path-based tags, and namespace-pathed
+tags are "opaque" — we can't statically know what they render. The descendant
+check skips these branches to avoid false positives. If a component renders a
+focusable element beneath an `aria-hidden` ancestor, the keyboard trap still
+exists at runtime; this rule can't detect it.
+
+Dynamic content inside `{{...}}` mustache statements is similarly not inspected.
+
 ## References
 
 - [WAI-ARIA 1.2 — aria-hidden](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden)
 - [WebAIM — Hiding content from assistive tech](https://webaim.org/techniques/css/invisiblecontent/)
 - [`no-aria-hidden-on-focusable` — eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/main/docs/rules/no-aria-hidden-on-focusable.md)
+- [`no-aria-hidden-on-focusable` — eslint-plugin-vuejs-accessibility](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility/blob/main/docs/rules/no-aria-hidden-on-focusable.md)

lib/rules/template-no-aria-hidden-on-focusable.js

@@ -79,6 +79,56 @@ function isFocusable(node) {
   return false;
 }
 
+// A tag name is "opaque" if we cannot statically know what element it renders.
+// This covers component invocations (PascalCase), argument/this/path-based
+// dynamic tags, and namespace-pathed tags. Per WAI-ARIA 1.2 §aria-hidden, we
+// conservatively do not descend into these branches (bias toward no-FP).
+function isOpaqueTag(tag) {
+  if (!tag) {
+    return true;
+  }
+  if (/^[A-Z]/.test(tag)) {
+    return true;
+  }
+  if (tag.startsWith('@') || tag.startsWith('this.')) {
+    return true;
+  }
+  if (tag.includes('.') || tag.includes('::')) {
+    return true;
+  }
+  return false;
+}
+
+// Per WAI-ARIA 1.2 §aria-hidden: "Authors SHOULD NOT use aria-hidden='true' on
+// any element that has focus or may receive focus". A focusable descendant of
+// an aria-hidden ancestor can still receive focus (aria-hidden does not remove
+// elements from the tab order), so the ancestor hides AT-visible content that
+// remains keyboard-reachable — a keyboard trap.
+function hasFocusableDescendant(node) {
+  const children = node.children;
+  if (!children || children.length === 0) {
+    return false;
+  }
+  for (const child of children) {
+    if (child.type !== 'GlimmerElementNode') {
+      // Skip TextNode, GlimmerMustacheStatement (dynamic content), yield
+      // expressions, and anything else whose rendered element we can't inspect.
+      continue;
+    }
+    if (isOpaqueTag(child.tag)) {
+      // Component / dynamic tag — opaque. Don't recurse.
+      continue;
+    }
+    if (isFocusable(child)) {
+      return true;
+    }
+    if (hasFocusableDescendant(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
   meta: {
@@ -94,6 +144,8 @@ module.exports = {
     messages: {
       noAriaHiddenOnFocusable:
         'aria-hidden="true" must not be set on focusable elements — it creates a keyboard trap (element reachable via Tab but hidden from assistive tech).',
+      noAriaHiddenOnAncestorOfFocusable:
+        'aria-hidden="true" must not be set on an element that contains focusable descendants — the descendants remain keyboard-reachable but are hidden from assistive tech.',
     },
   },
 
@@ -105,6 +157,10 @@ module.exports = {
         }
         if (isFocusable(node)) {
           context.report({ node, messageId: 'noAriaHiddenOnFocusable' });
+          return;
+        }
+        if (hasFocusableDescendant(node)) {
+          context.report({ node, messageId: 'noAriaHiddenOnAncestorOfFocusable' });
         }
       },
     };

tests/audit/no-aria-hidden-on-focusable/peer-parity.js

@@ -44,24 +44,6 @@ ruleTester.run('audit:no-aria-hidden-on-focusable (gts)', rule, {
     // so it's still valid.
     '<template><div {{on "click" this.handler}} aria-hidden="true"></div></template>',
 
-    // === Upstream parity with vue-a11y (valid in both) ===
-    // vue-a11y: valid — descendant focusable with its own tabindex="-1" is
-    // "escorted out" of the tab order. Our rule only inspects the element
-    // that carries aria-hidden; we agree by not descending.
-    `<template>
-      <div aria-hidden="true">
-        <button tabindex="-1">Some text</button>
-      </div>
-    </template>`,
-
-    // vue-a11y: valid — `<a href tabindex="-1">` is escorted out of tab order.
-    // We don't flag because the aria-hidden is on the non-focusable <div>.
-    `<template>
-      <div aria-hidden="true">
-        <a href="#" tabindex="-1">Link</a>
-      </div>
-    </template>`,
-
     // vue-a11y: valid — no aria-hidden anywhere.
     `<template>
       <div>
@@ -131,6 +113,18 @@ ruleTester.run('audit:no-aria-hidden-on-focusable (gts)', rule, {
       errors: [{ messageId: 'noAriaHiddenOnFocusable' }],
     },
 
+    // === Upstream parity with vue-a11y descendant-focusable check (G5.1) ===
+    // vue-a11y: INVALID when aria-hidden is on an ancestor and a focusable
+    //   descendant exists. Our rule now matches this via hasFocusableDescendant.
+    //   Per WAI-ARIA 1.2 §aria-hidden "may receive focus", a focusable
+    //   descendant beneath an aria-hidden ancestor is keyboard-reachable while
+    //   hidden from AT — a keyboard trap.
+    {
+      code: '<template><div aria-hidden="true"><button>Submit</button></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+
     // === DIVERGENCE — `tabindex="-1"` on an inherently focusable element ===
     // This is the load-bearing, intentional divergence that PR #19 encodes.
     // jsx-a11y: VALID — `<button aria-hidden="true" tabIndex="-1" />` is
@@ -155,6 +149,30 @@ ruleTester.run('audit:no-aria-hidden-on-focusable (gts)', rule, {
       output: null,
       errors: [{ messageId: 'noAriaHiddenOnFocusable' }],
     },
+
+    // === DIVERGENCE (extended by G5.1) — tabindex="-1" on a DESCENDANT ===
+    // Same rationale as above, applied through hasFocusableDescendant: our
+    // `isFocusable` treats any tabindex (including "-1") as programmatically
+    // focusable. vue-a11y considers these VALID (descendant is "escorted out"
+    // of tab order). We flag.
+    {
+      code: `<template>
+      <div aria-hidden="true">
+        <button tabindex="-1">Some text</button>
+      </div>
+    </template>`,
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      code: `<template>
+      <div aria-hidden="true">
+        <a href="#" tabindex="-1">Link</a>
+      </div>
+    </template>`,
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
   ],
 });
 
@@ -168,31 +186,17 @@ ruleTester.run('audit:no-aria-hidden-on-focusable (gts)', rule, {
 // jsx-a11y: has no explicit case for this. Our rule special-cases
 //   `<input type="hidden">` as non-focusable. Captured in main rule tests.
 
-// === DIVERGENCE — vue-a11y descendant-focusable check ===
+// === PARITY — vue-a11y descendant-focusable check (G5.1, PR #19 follow-up) ===
 // vue-a11y: INVALID when aria-hidden is on an ancestor and a focusable
 //   descendant exists:
 //     `<div aria-hidden="true"><button>Submit</button></div>`  → flagged
 //   Its rule descends into children and fires on the aria-hidden ancestor
 //   if any descendant is focusable.
-// Our rule: VALID — we only inspect the element that carries aria-hidden.
-//   A div is not focusable, so we do not flag. This is a deliberate scope
-//   decision (match jsx-a11y) and leaves vue-a11y's descendant-check behavior
-//   as a capture-only difference. The PR's doc should note that users relying
-//   on vue-a11y's broader semantic should pair this rule with an additional
-//   check or use `aria-hidden` sparingly on wrappers.
-//
-// Captured below as valid cases (reflecting OUR non-flagging behavior).
-ruleTester.run('audit:no-aria-hidden-on-focusable descendant-only (gts)', rule, {
-  valid: [
-    // vue-a11y flags this; we don't.
-    `<template>
-      <div aria-hidden="true">
-        <button>Submit</button>
-      </div>
-    </template>`,
-  ],
-  invalid: [],
-});
+// Our rule: now INVALID — matches vue-a11y. Per WAI-ARIA 1.2 §aria-hidden
+//   "may receive focus" we flag via `hasFocusableDescendant` under the
+//   `noAriaHiddenOnAncestorOfFocusable` messageId. The parity case is in the
+//   invalid[] block above. Component/dynamic descendants remain opaque
+//   (no-FP bias).
 
 // === AUDIT-SKIP — curly-literal aria-hidden value forms ===
 // jsx-a11y: tests use string-literal `aria-hidden="true"`. It also recognizes
@@ -215,13 +219,6 @@ hbsRuleTester.run('audit:no-aria-hidden-on-focusable (hbs)', rule, {
     '<a aria-hidden="false" href="#"></a>',
     '<button></button>',
     '<a href="/"></a>',
-
-    // vue-a11y parity — descendant has its own tabindex="-1" opt-out.
-    '<div aria-hidden="true"><button tabindex="-1">Some text</button></div>',
-    '<div aria-hidden="true"><a href="#" tabindex="-1">Link</a></div>',
-
-    // DIVERGENCE captured in hbs — we don't descend (vue-a11y does).
-    '<div aria-hidden="true"><button>Submit</button></div>',
   ],
   invalid: [
     {
@@ -266,5 +263,22 @@ hbsRuleTester.run('audit:no-aria-hidden-on-focusable (hbs)', rule, {
       output: null,
       errors: [{ messageId: 'noAriaHiddenOnFocusable' }],
     },
+    // G5.1 parity — aria-hidden ancestor with focusable descendant.
+    {
+      code: '<div aria-hidden="true"><button>Submit</button></div>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    // G5.1 — DIVERGENCE extended: descendant with tabindex="-1".
+    {
+      code: '<div aria-hidden="true"><button tabindex="-1">Some text</button></div>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      code: '<div aria-hidden="true"><a href="#" tabindex="-1">Link</a></div>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
   ],
 });

tests/lib/rules/template-no-aria-hidden-on-focusable.js

@@ -31,6 +31,22 @@ ruleTester.run('template-no-aria-hidden-on-focusable', rule, {
 
     // Components — we don't know if they render a focusable element.
     '<template><CustomBtn aria-hidden="true" /></template>',
+
+    // Descendant-focusable check — valid cases.
+    // No focusable descendant.
+    '<template><div aria-hidden="true"><span>Just text</span></div></template>',
+    // Component descendants are opaque — conservatively not flagged.
+    '<template><div aria-hidden="true"><Button>X</Button></div></template>',
+    // No focusable descendants (alt-less img is decorative, not focusable).
+    '<template><div aria-hidden="true"><img alt="static" /></div></template>',
+    // <input type="hidden"> is non-focusable per isFocusable.
+    '<template><div aria-hidden="true"><input type="hidden" /></div></template>',
+    // Dynamic mustache descendants are not inspected.
+    '<template><div aria-hidden="true">{{this.label}}</div></template>',
+    // `@arg`-prefixed tag is opaque.
+    '<template><div aria-hidden="true"><@thing /></div></template>',
+    // `this.`-prefixed tag is opaque.
+    '<template><div aria-hidden="true"><this.Item /></div></template>',
   ],
   invalid: [
     // Native interactive elements.
@@ -89,6 +105,46 @@ ruleTester.run('template-no-aria-hidden-on-focusable', rule, {
       output: null,
       errors: [{ messageId: 'noAriaHiddenOnFocusable' }],
     },
+
+    // Descendant-focusable check (G5.1). Per WAI-ARIA 1.2 §aria-hidden
+    // "may receive focus" — focusable descendants are keyboard-reachable
+    // under an aria-hidden ancestor, creating a keyboard trap.
+    {
+      // Classic modal-backdrop trap.
+      code: '<template><div aria-hidden="true"><button>Close</button></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      // Deeper descendant.
+      code: '<template><div aria-hidden="true"><span><button>Deep</button></span></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      code: '<template><div aria-hidden="true"><a href="/x">Link</a></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      code: '<template><div aria-hidden="true"><input /></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      // Depth check — focusable descendant two levels deep.
+      // (Our isFocusable doesn't treat <video controls> as focusable because
+      // it's not in INHERENTLY_FOCUSABLE_TAGS; use <textarea> instead.)
+      code: '<template><section aria-hidden="true"><div><textarea></textarea></div></section></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      // tabindex on a descendant makes it focusable.
+      code: '<template><div aria-hidden="true"><span tabindex="0">x</span></div></template>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
   ],
 });
 
@@ -103,6 +159,10 @@ hbsRuleTester.run('template-no-aria-hidden-on-focusable', rule, {
     '<button>Click me</button>',
     '<input type="hidden" aria-hidden="true" />',
     '<CustomBtn aria-hidden="true" />',
+    // Descendant-focusable — non-focusable child.
+    '<div aria-hidden="true"><span>Just text</span></div>',
+    // Component descendant is opaque.
+    '<div aria-hidden="true"><Button>X</Button></div>',
   ],
   invalid: [
     {
@@ -115,5 +175,16 @@ hbsRuleTester.run('template-no-aria-hidden-on-focusable', rule, {
       output: null,
       errors: [{ messageId: 'noAriaHiddenOnFocusable' }],
     },
+    // Descendant-focusable check (G5.1).
+    {
+      code: '<div aria-hidden="true"><button>Close</button></div>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
+    {
+      code: '<section aria-hidden="true"><div><a href="/x">Link</a></div></section>',
+      output: null,
+      errors: [{ messageId: 'noAriaHiddenOnAncestorOfFocusable' }],
+    },
   ],
 });