fix+docs: add native-element gate, handle hidden anchors, fix doc examples (Copilot review)

Author: johanrd

docs/rules/template-anchor-has-content.md

@@ -41,8 +41,8 @@ This rule **forbids** the following:
   <a href="/x" />
   <a href="/x"></a>
   <a href="/x">   </a>
-  <a href="/x"><span aria-hidden>X</span></a>
-  <a href="/x"><img aria-hidden alt="Search" /></a>
+  <a href="/x"><span aria-hidden="true">X</span></a>
+  <a href="/x"><img aria-hidden="true" alt="Search" /></a>
   <a href="/x"><img /></a>
   <a href="/x" aria-label="" />
 </template>

lib/rules/template-anchor-has-content.js

@@ -150,17 +150,38 @@ module.exports = {
     const sourceCode = context.sourceCode || context.getSourceCode();
     return {
       GlimmerElementNode(node) {
-        if (node.tag !== 'a') {
+        // Only the native <a> element — in strict GJS, a lowercase tag can be
+        // shadowed by an in-scope local binding, and components shouldn't be
+        // validated here. `isNativeElement` combines authoritative html/svg/
+        // mathml tag lists with scope-shadowing detection.
+        if (!isNativeElement(node, sourceCode)) {
+          return;
+        }
+        if (node.tag?.toLowerCase() !== 'a') {
           return;
         }
 
         // Only anchors acting as links (with href) are in scope. An <a> without
         // href is covered by `template-link-href-attributes` / not a link.
-        const hasHref = (node.attributes || []).some((a) => a.name === 'href');
+        const attrs = node.attributes || [];
+        const hasHref = attrs.some((a) => a.name === 'href');
         if (!hasHref) {
           return;
         }
 
+        // Skip anchors the author has explicitly hidden — either via the HTML
+        // `hidden` boolean attribute (element is not rendered at all) or
+        // `aria-hidden="true"` (element removed from the accessibility tree).
+        // In both cases, "accessible name of an anchor" is moot.
+        const hasHidden = attrs.some((a) => a.name === 'hidden');
+        if (hasHidden) {
+          return;
+        }
+        const ariaHiddenAttr = attrs.find((a) => a.name === 'aria-hidden');
+        if (isAriaHiddenTrue(ariaHiddenAttr)) {
+          return;
+        }
+
         if (hasAccessibleNameAttribute(node)) {
           return;
         }

tests/lib/rules/template-anchor-has-content.js

@@ -79,6 +79,41 @@ ruleTester.run('template-anchor-has-content', rule, {
       filename: 'test.gjs',
       code: '<template><a href="/x"><img aria-hidden alt="Nope" /></a></template>',
     },
+
+    // Anchor itself hidden via HTML `hidden` boolean attribute — element is
+    // not rendered, so "accessible name of an anchor" is moot.
+    {
+      filename: 'test.gjs',
+      code: '<template><a href="/x" hidden /></template>',
+    },
+    {
+      filename: 'test.gjs',
+      code: '<template><a href="/x" hidden></a></template>',
+    },
+
+    // Anchor itself hidden via aria-hidden="true" — removed from the a11y
+    // tree, so the accessible-name check does not apply.
+    {
+      filename: 'test.gjs',
+      code: '<template><a href="/x" aria-hidden="true" /></template>',
+    },
+    {
+      filename: 'test.gjs',
+      code: '<template><a href="/x" aria-hidden={{true}}></a></template>',
+    },
+
+    // Scope-shadowed lowercase `a` (local binding in GJS) — not the native
+    // HTML anchor, so the rule does not validate it. `isNativeElement`
+    // detects the shadowing via scope reference tracking.
+    {
+      filename: 'test.gjs',
+      code: `
+        const a = '';
+        <template>
+          <a href="/x" />
+        </template>
+      `,
+    },
   ],
 
   invalid: [