docs: cite ARIA §4.6 for deliberate non-recursion vs. vue-a11y

Author: johanrd

docs/rules/template-no-role-presentation-on-focusable.md

@@ -37,7 +37,27 @@ This rule **allows** the following:
 </template>
 ```
 
+## Scope / Rationale
+
+This rule inspects **only the element that carries the `role="presentation"` / `role="none"`** — it does not recurse into descendants. Per [WAI-ARIA 1.2 §4.6 Conflict Resolution](https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none) and [§5.3.3 Document Structure](https://www.w3.org/TR/wai-aria-1.2/#document_structure_roles), `role="presentation"` / `role="none"` does **not** cascade to descendants — each descendant retains its own role and semantics.
+
+As a result, wrapper patterns are **not flagged**:
+
+```gjs
+<template>
+  {{! Not flagged: the div's role is a no-op (div had no meaningful role to
+      suppress), and the button keeps its role + keyboard behavior. }}
+  <div role="presentation">
+    <button type="button">Click</button>
+  </div>
+</template>
+```
+
+This is a deliberate divergence from [eslint-plugin-vuejs-accessibility's `no-role-presentation-on-focusable`](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility/blob/main/docs/rules/no-role-presentation-on-focusable.md), which recurses into descendants and flags the wrapper case above. Vue's recursion is uncommented in their source and appears to have been copy-pasted from their `aria-hidden` rule, where descendant recursion **is** spec-correct because `aria-hidden` **does** cascade (see [`template-no-aria-hidden-on-focusable`](./template-no-aria-hidden-on-focusable.md)).
+
 ## References
 
 - [WAI-ARIA 1.2 — presentation role](https://www.w3.org/TR/wai-aria-1.2/#presentation)
+- [WAI-ARIA 1.2 §4.6 — Conflict Resolution for the `presentation` / `none` roles](https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none)
+- [WAI-ARIA 1.2 §5.3.3 — Document Structure Roles](https://www.w3.org/TR/wai-aria-1.2/#document_structure_roles)
 - [`no-role-presentation-on-focusable` — eslint-plugin-vuejs-accessibility](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility/blob/main/docs/rules/no-role-presentation-on-focusable.md)

lib/rules/template-no-role-presentation-on-focusable.js

@@ -1,3 +1,18 @@
+// Per WAI-ARIA 1.2 §4.6 Conflict Resolution, role="presentation" / role="none"
+// does NOT cascade to descendants — each descendant retains its own role and
+// semantics. So `<div role="presentation"><button>X</button></div>` is NOT a
+// semantic problem: the div's role is a no-op (div had no meaningful role to
+// suppress), and the button remains fully interactive with its role intact.
+//
+// Therefore, unlike our template-no-aria-hidden-on-focusable rule (which recurses
+// into descendants because aria-hidden DOES cascade and creates a keyboard trap
+// landing on AT-hidden content), this rule only checks the element carrying the
+// presentation role.
+//
+// Deliberately diverges from vue-a11y's no-role-presentation-on-focusable, which
+// recurses into descendants. Vue's recursion is uncommented in their source and
+// appears to be a copy-paste from their aria-hidden rule.
+
 const INHERENTLY_FOCUSABLE_TAGS = new Set([
   'button',
   'details',

tests/audit/no-role-presentation-on-focusable/peer-parity.js

@@ -89,15 +89,32 @@ ruleTester.run('audit:no-role-presentation-on-focusable (gts)', rule, {
 // DESCENDANT is focusable:
 //   <div role='presentation'><button>Submit</button></div>      → vue: INVALID
 // Our rule only inspects the element bearing the role. A non-focusable wrapper
-// is left alone; the authoring error vue targets (stripping semantics from
-// a container whose children remain focusable) is not detected by us.
+// is left alone.
+//
+// Spec grounding (WAI-ARIA 1.2):
+//  - §4.6 "Presentational Roles Conflict Resolution"
+//    (https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none)
+//    describes how role="presentation" / role="none" behaves on the element
+//    that carries it — NOT a cascade. It explicitly states that descendants
+//    retain their own semantics, and only the host element's implicit role is
+//    suppressed (and even that is overridden when the host is focusable or has
+//    global ARIA state/property attributes).
+//  - §5.3.3 "Document Structure Roles"
+//    (https://www.w3.org/TR/wai-aria-1.2/#document_structure_roles)
+//    reaffirms: role="presentation" / "none" does not propagate into the
+//    subtree; each descendant keeps its role and interactivity.
+//
+// So `<div role="presentation"><button>X</button></div>` is not a semantic
+// problem: the div's role is a no-op (div had no meaningful role to suppress),
+// and the button remains fully interactive with its role intact. Vue's flagging
+// of the wrapper is not spec-mandated; their descendant recursion is uncommented
+// in source and appears to be a copy-paste from their aria-hidden rule.
+//
+// Contrast with `template-no-aria-hidden-on-focusable` (see G5.1), where
+// recursion into descendants IS spec-correct because aria-hidden DOES cascade
+// to the entire subtree per WAI-ARIA 1.2 §6.6 and creates a real keyboard trap
+// (focus lands on AT-hidden content).
 //
-// This is a known gap, not a bug fix waiting to happen:
-//  - The WAI-ARIA §4.6 conflict-resolution text is phrased for elements with
-//    role=presentation that are themselves focusable. Applying it to ancestors
-//    is vue's interpretation, not a spec mandate.
-//  - Our rule is narrower and has fewer false positives, at the cost of this
-//    true positive.
 // Captured here as a "valid" bucket for OUR rule to make the divergence
 // explicit in the audit output.
 ruleTester.run('audit:no-role-presentation-on-focusable — wrapper scope (gts)', rule, {