fix(template-no-empty-headings): align aria-hidden with WAI-ARIA spec via shared helper (Copilot review)

johanrd · johanrd · commit ceaf0cfed63e · 2026-04-24T19:21:26.000+02:00
Extract a new `getStaticAttrValue` util that resolves literal-valued mustaches (`{{"foo"}}`, `{{true}}`, `{{-1}}`) and single-part concat statements (`"{{true}}"`) to their static string value. `isAriaHiddenTruthy` now delegates to the helper and compares the resolved string to `'true'` (case-insensitive, whitespace-trimmed). Behavior change: valueless `<h1 aria-hidden>`, `aria-hidden=""`, and the mustache-empty-string equivalents (`aria-hidden={{""}}`, `aria-hidden="{{""}}"`, `aria-hidden={{" "}}`) are no longer treated as hidden. Per WAI-ARIA 1.2 §6.6 value table, those shapes resolve to the default `undefined` — NOT `true` — so the empty-content check still applies. Drops the previous "fewer false positives" deviation rationale in favour of spec-literal consistency with sibling rules (#19, #35, #41) that share the same aria-hidden resolution. Byte-identical carrier of lib/utils/static-attr-value.js across all PRs that land it.
diff --git a/docs/rules/template-no-empty-headings.md b/docs/rules/template-no-empty-headings.md
@@ -52,18 +52,11 @@ If violations are found, remediation should be planned to ensure text content is
 
 ## Notes on `aria-hidden` semantics
 
-This rule treats valueless / empty-string `aria-hidden` (`<h1 aria-hidden>` or `<h1 aria-hidden="">`) as exempting the heading from the empty-content check — those forms count as "hidden" for this rule.
+This rule follows [WAI-ARIA 1.2 §`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden) verbatim: only an explicit truthy value hides the element. Ambiguous shapes — valueless `aria-hidden`, empty string, and mustache literals that resolve to an empty / whitespace-only string — all resolve to the default `undefined` and do NOT exempt the heading from the empty-content check.
 
-**This is a deliberate deviation from [WAI-ARIA 1.2 §`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden)**, which resolves valueless / empty-string `aria-hidden` to the default value `undefined` — not `true` — and therefore does not hide the element per spec. The spec-literal reading would say "valueless `aria-hidden` doesn't hide, so the empty heading is still a violation."
-
-We lean toward fewer false positives here: if the author wrote `aria-hidden` at all, they signaled an intent to hide, and flagging the empty heading on top of what is already a malformed `aria-hidden` usage layers a second-order complaint on a first-order problem. Axe-core and the W3C ACT rules consistently treat this shape as INCOMPLETE (needs manual review) rather than a definitive failure, which is consistent with leaning away from a hard flag here.
-
-For rules that ask the _opposite_ question ("is this element authoritatively hidden?"), the spec-literal reading applies, and valueless `aria-hidden` should be treated as **not** hidden. This split is applied per-rule, picking the interpretation that produces the fewest false positives for each specific check.
-
-Unambiguous forms always follow the spec:
-
-- `aria-hidden="true"` / `aria-hidden={{true}}` / `aria-hidden={{"true"}}` (any case) → hidden, exempts the heading.
-- `aria-hidden="false"` / `aria-hidden={{false}}` / `aria-hidden={{"false"}}` → not hidden, the empty-content check still applies.
+- `aria-hidden="true"` / `aria-hidden={{true}}` / `aria-hidden={{"true"}}` (any case, whitespace-trimmed) → hidden, exempts the heading.
+- `aria-hidden="false"` / `aria-hidden={{false}}` / `aria-hidden={{"false"}}` → not hidden, the empty-content check applies.
+- `<h1 aria-hidden>` / `aria-hidden=""` / `aria-hidden={{""}}` / `aria-hidden={{" "}}` → spec-default `undefined`, the empty-content check applies.
 
 ## References
 
diff --git a/lib/rules/template-no-empty-headings.js b/lib/rules/template-no-empty-headings.js
@@ -1,74 +1,23 @@
+const { getStaticAttrValue } = require('../utils/static-attr-value');
+
 const HEADINGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
 
-// aria-hidden semantics for valueless / empty / "false" are genuinely
-// contested across common accessibility tooling and spec interpretations.
-// For this rule, we prefer FEWER false positives: when the author has written
-// `aria-hidden` in any form that could plausibly mean "hide this", we exempt
-// the heading from the empty-content check. The downside (missing some
-// genuinely-empty headings) is preferable to flagging correctly-authored
-// headings the developer intentionally decorated. See
-// docs/rules/template-no-empty-headings.md for the rule-level rationale.
-//
-// Truthy:
-//  - valueless attr (`<h1 aria-hidden>`) — default-undefined per spec, but
-//    authors who write bare `aria-hidden` plausibly intend hidden.
-//  - empty string `aria-hidden=""` — same.
-//  - `aria-hidden="true"` / "TRUE" / "True" (ASCII case-insensitive).
-//  - `aria-hidden={{true}}` mustache boolean literal.
-//  - `aria-hidden={{"true"}}` / case-variants as mustache string literal.
-// Not truthy (falls through):
-//  - `aria-hidden="false"` / `{{false}}` / `{{"false"}}` — explicit opt-out.
+// Aligned with WAI-ARIA 1.2 §6.6 aria-hidden value table: only an explicit
+// "true" (ASCII case-insensitive, whitespace-trimmed) hides the element.
+// Valueless `<h1 aria-hidden>`, empty-string `aria-hidden=""`, and
+// `aria-hidden="false"` all resolve to the default `undefined` / explicit
+// false — so the empty-content check still applies. All shape-unwrapping
+// (mustache/concat) goes through the shared `getStaticAttrValue` helper.
 function isAriaHiddenTruthy(attr) {
   if (!attr) {
     return false;
   }
-  const value = attr.value;
-  // Valueless attribute — no `value` property at all.
-  if (!value) {
-    return true;
-  }
-  if (value.type === 'GlimmerTextNode') {
-    // Normalize like other aria-* value checks: trim incidental whitespace
-    // and compare case-insensitively. `aria-hidden=" true "` is semantically
-    // "true" per the trim step used elsewhere in this rule family.
-    const chars = value.chars.trim().toLowerCase();
-    // Empty string is exempted (lean toward fewer false positives).
-    return chars === '' || chars === 'true';
-  }
-  if (value.type === 'GlimmerMustacheStatement' && value.path) {
-    if (value.path.type === 'GlimmerBooleanLiteral') {
-      return value.path.value === true;
-    }
-    if (value.path.type === 'GlimmerStringLiteral') {
-      return value.path.value.trim().toLowerCase() === 'true';
-    }
-  }
-  if (value.type === 'GlimmerConcatStatement') {
-    // Quoted-mustache form like aria-hidden="{{true}}" or aria-hidden="{{x}}".
-    // Only resolve when the concat is a single static-literal part; any
-    // dynamic path makes the runtime value unknown. Lean toward "truthy"
-    // only on literal `true` / empty-literal / bare-valueless to stay aligned
-    // with the doc-stated ethos (fewer false positives — don't flag headings
-    // the author has intentionally decorated with aria-hidden).
-    const parts = value.parts || [];
-    if (parts.length === 1) {
-      const only = parts[0];
-      if (only.type === 'GlimmerMustacheStatement' && only.path) {
-        if (only.path.type === 'GlimmerBooleanLiteral') {
-          return only.path.value === true;
-        }
-        if (only.path.type === 'GlimmerStringLiteral') {
-          return only.path.value.trim().toLowerCase() === 'true';
-        }
-      }
-      if (only.type === 'GlimmerTextNode') {
-        const chars = only.chars.trim().toLowerCase();
-        return chars === '' || chars === 'true';
-      }
-    }
+  const resolved = getStaticAttrValue(attr.value);
+  if (resolved === undefined) {
+    // Dynamic — can't prove truthy.
     return false;
   }
-  return false;
+  return resolved.trim().toLowerCase() === 'true';
 }
 
 function isHidden(node) {
diff --git a/lib/utils/static-attr-value.js b/lib/utils/static-attr-value.js
@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Return the statically-known string value of a Glimmer attribute value node,
+ * or `undefined` when the value is dynamic (cannot be resolved at lint time).
+ *
+ * Unwraps:
+ *   - GlimmerTextNode → chars
+ *   - GlimmerMustacheStatement with a literal path (boolean/string/number) → stringified value
+ *   - GlimmerConcatStatement whose parts are all statically resolvable → joined string
+ *
+ * A missing/undefined value (valueless attribute, e.g. `<input disabled>`)
+ * returns the empty string. Pass `attr.value` — not the attribute itself.
+ */
+function getStaticAttrValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  if (value.type === 'GlimmerTextNode') {
+    return value.chars;
+  }
+  if (value.type === 'GlimmerMustacheStatement') {
+    return extractLiteral(value.path);
+  }
+  if (value.type === 'GlimmerConcatStatement') {
+    const parts = value.parts || [];
+    let out = '';
+    for (const part of parts) {
+      if (part.type === 'GlimmerTextNode') {
+        out += part.chars;
+        continue;
+      }
+      if (part.type === 'GlimmerMustacheStatement') {
+        const literal = extractLiteral(part.path);
+        if (literal === undefined) {
+          return undefined;
+        }
+        out += literal;
+        continue;
+      }
+      return undefined;
+    }
+    return out;
+  }
+  return undefined;
+}
+
+function extractLiteral(path) {
+  if (!path) {
+    return undefined;
+  }
+  if (path.type === 'GlimmerBooleanLiteral') {
+    return path.value ? 'true' : 'false';
+  }
+  if (path.type === 'GlimmerStringLiteral') {
+    return path.value;
+  }
+  if (path.type === 'GlimmerNumberLiteral') {
+    return String(path.value);
+  }
+  return undefined;
+}
+
+module.exports = { getStaticAttrValue };
diff --git a/tests/lib/rules/template-no-empty-headings.js b/tests/lib/rules/template-no-empty-headings.js
@@ -44,10 +44,8 @@ ruleTester.run('template-no-empty-headings', rule, {
     '<template><h2><@heading /></h2></template>',
     '<template><h3><ns.Heading /></h3></template>',
 
-    // aria-hidden variants are exempt from the empty-heading check to avoid
-    // false positives when headings are intentionally hidden from assistive tech.
-    '<template><h1 aria-hidden></h1></template>',
-    '<template><h1 aria-hidden=""></h1></template>',
+    // Explicit "true" exempts the empty-heading check — author has
+    // signalled the heading is intentionally hidden from assistive tech.
     '<template><h1 aria-hidden={{true}}></h1></template>',
     '<template><h1 aria-hidden="true">Visible to sighted only</h1></template>',
     '<template><h1 aria-hidden="TRUE"></h1></template>',
@@ -170,5 +168,35 @@ ruleTester.run('template-no-empty-headings', rule, {
       output: null,
       errors: [{ messageId: 'emptyHeading' }],
     },
+    // Per WAI-ARIA 1.2 §6.6 aria-hidden value table: valueless /
+    // empty-string `aria-hidden` resolves to the default `undefined`,
+    // not `true`. Empty headings with these forms still flag.
+    {
+      code: '<template><h1 aria-hidden></h1></template>',
+      output: null,
+      errors: [{ messageId: 'emptyHeading' }],
+    },
+    {
+      code: '<template><h1 aria-hidden=""></h1></template>',
+      output: null,
+      errors: [{ messageId: 'emptyHeading' }],
+    },
+    // Mustache / concat forms that resolve to an empty / whitespace-only
+    // string — same spec-aligned treatment.
+    {
+      code: '<template><h1 aria-hidden={{""}}></h1></template>',
+      output: null,
+      errors: [{ messageId: 'emptyHeading' }],
+    },
+    {
+      code: '<template><h1 aria-hidden="{{""}}"></h1></template>',
+      output: null,
+      errors: [{ messageId: 'emptyHeading' }],
+    },
+    {
+      code: '<template><h1 aria-hidden={{" "}}></h1></template>',
+      output: null,
+      errors: [{ messageId: 'emptyHeading' }],
+    },
   ],
 });
diff --git a/tests/lib/utils/static-attr-value-test.js b/tests/lib/utils/static-attr-value-test.js
@@ -0,0 +1,129 @@
+'use strict';
+
+const { getStaticAttrValue } = require('../../../lib/utils/static-attr-value');
+
+describe('getStaticAttrValue', () => {
+  it('returns empty string for null/undefined (valueless attribute)', () => {
+    expect(getStaticAttrValue(null)).toBe('');
+    expect(getStaticAttrValue(undefined)).toBe('');
+  });
+
+  it('returns chars for GlimmerTextNode', () => {
+    expect(getStaticAttrValue({ type: 'GlimmerTextNode', chars: 'hello' })).toBe('hello');
+    expect(getStaticAttrValue({ type: 'GlimmerTextNode', chars: '' })).toBe('');
+  });
+
+  it('unwraps GlimmerMustacheStatement with BooleanLiteral', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerBooleanLiteral', value: true },
+      })
+    ).toBe('true');
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerBooleanLiteral', value: false },
+      })
+    ).toBe('false');
+  });
+
+  it('unwraps GlimmerMustacheStatement with StringLiteral', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerStringLiteral', value: 'foo' },
+      })
+    ).toBe('foo');
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerStringLiteral', value: '' },
+      })
+    ).toBe('');
+  });
+
+  it('unwraps GlimmerMustacheStatement with NumberLiteral', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerNumberLiteral', value: -1 },
+      })
+    ).toBe('-1');
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerNumberLiteral', value: 0 },
+      })
+    ).toBe('0');
+  });
+
+  it('returns undefined for GlimmerMustacheStatement with a dynamic PathExpression', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerMustacheStatement',
+        path: { type: 'GlimmerPathExpression', original: 'this.foo' },
+      })
+    ).toBeUndefined();
+  });
+
+  it('joins GlimmerConcatStatement with only static parts', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerConcatStatement',
+        parts: [
+          { type: 'GlimmerTextNode', chars: 'prefix-' },
+          {
+            type: 'GlimmerMustacheStatement',
+            path: { type: 'GlimmerStringLiteral', value: 'mid' },
+          },
+          { type: 'GlimmerTextNode', chars: '-suffix' },
+        ],
+      })
+    ).toBe('prefix-mid-suffix');
+  });
+
+  it('joins concat with boolean and number literal parts', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerConcatStatement',
+        parts: [
+          {
+            type: 'GlimmerMustacheStatement',
+            path: { type: 'GlimmerBooleanLiteral', value: true },
+          },
+        ],
+      })
+    ).toBe('true');
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerConcatStatement',
+        parts: [
+          {
+            type: 'GlimmerMustacheStatement',
+            path: { type: 'GlimmerNumberLiteral', value: -1 },
+          },
+        ],
+      })
+    ).toBe('-1');
+  });
+
+  it('returns undefined for GlimmerConcatStatement with a dynamic part', () => {
+    expect(
+      getStaticAttrValue({
+        type: 'GlimmerConcatStatement',
+        parts: [
+          { type: 'GlimmerTextNode', chars: 'x-' },
+          {
+            type: 'GlimmerMustacheStatement',
+            path: { type: 'GlimmerPathExpression', original: 'this.foo' },
+          },
+        ],
+      })
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for an unknown node type', () => {
+    expect(getStaticAttrValue({ type: 'GlimmerSubExpression' })).toBeUndefined();
+  });
+});
