BUGFIX: template-no-empty-headings — recognize boolean aria-hidden

[johanrd]

Note

This is part of a series where Claude has audited eslint-plugin-ember against jsx-a11y, vuejs-accessibility, angular-eslint, lit-a11y and html-validate, ember-template-lint, and the HTML and WCAG specs.

This PR is part of a Phase 3 a11y-parity audit against jsx-a11y / vue-a11y / angular-eslint-template / lit-a11y.

• Premise: A heading that's marked as decorative via aria-hidden is intentionally invisible to assistive technology — requiring text content in that heading is a false positive.
• Problem: Our isHidden check only matched aria-hidden="true" as a case-sensitive string literal, so <h1 aria-hidden>, <h1 aria-hidden="">, <h1 aria-hidden="TRUE">, <h1 aria-hidden={{true}}>, etc. were treated as visible and flagged for missing content.

Fix: extract isAriaHiddenTruthy() that recognizes every plausible "hide-this" form (valueless, empty-string, "true" case-insensitive, mustache boolean/string-literal true/case-variants).

Prior art

Plugin	Rule	Verified behavior
jsx-a11y	heading-has-content	Flags empty <h1>–<h6>; skips hidden headings via isHiddenFromAT (jsx-a11y's aria-hidden interpretation — see Contested-semantics table below).
vuejs-accessibility	heading-has-content	Flags empty <h1>–<h6>; uses isHiddenFromScreenReader (vue's (value || "").toString() !== "false" — see Contested-semantics table below).
@angular-eslint/template	elements-content	Covers <h1>–<h6> together with <a> / <button> via a single regex matcher; skips hidden via isHiddenFromScreenReader. Not a dedicated heading rule.
lit-a11y	no direct equivalent	lit-a11y ships heading-hidden (headings must not be hidden) but no "heading has content" rule. Inverse concern.

Four ecosystem positions on valueless aria-hidden

The question "what does <el aria-hidden> (bare), aria-hidden="" (empty), or aria-hidden={{false}} mean?" has no single authoritative answer. Four defensible positions exist:

#	Source	Interpretation	Evidence
1	jsx-a11y	Valueless → hidden	Side effect of jsx-ast-utils coercing valueless JSX attrs to boolean true, combined with rule check ariaHidden === true. Quirk: string aria-hidden="true" is NOT recognized because "true" !== true. Not a deliberate ARIA interpretation.
2	vue-a11y	Anything not literal "false" → hidden	isHiddenFromScreenReader.ts: (value || "").toString() !== "false". Catches valueless, empty, "TRUE", "anything". Non-spec shortcut.
3	axe-core / W3C ACT Rules	Valueless/empty → INCOMPLETE, needs author review	axe-core PR #3635: empty ARIA values reported as incomplete, "There is no real difference between an empty ARIA attribute, a null attribute, and not having the attribute at all." W3C ACT Rule 6a7281 explicitly scopes out empty values as inapplicable.
4	WAI-ARIA 1.2 spec	Valueless/empty → default undefined → not hidden	The aria-hidden value table lists exactly true / false / undefined (default). A missing attribute resolves to that default; an empty-string value isn't enumerated, so it isn't interpreted as true. aria-hidden is also not in HTML's boolean attributes list, so the "presence-implies-true" rule that applies to e.g. disabled does not extend here. WAI-ARIA 1.2 §9.2 further specifies that for boolean-like platform API states, values of "" or no attribute present SHOULD both be treated as false — consistent with the undefined-default interpretation. (aria-hidden has no per-attribute empty-string text, so the empty-string case remains inference backed by §9.2's SHOULD.)

Browser testing shows disagreement even on the explicit aria-hidden="true" case (see Steve Faulkner's post and Mozilla bug 948540); no documented browser testing on valueless specifically — most likely a no-op matching the spec's undefined-default.

Design choice for this rule

We lean toward fewer false positives. A linter that flags a heading the author intentionally marked decorative (via bare aria-hidden) creates friction and loss of trust; a linter that silently accepts some genuinely-empty unhidden headings is the smaller cost when the signal is ambiguous. So any aria-hidden form that could plausibly mean "hide this" exempts the heading from the empty-content check.

Exempt (don't flag empty heading):

• <h1 aria-hidden>, <h1 aria-hidden="">, <h1 aria-hidden="true">, "TRUE", "True"
• <h1 aria-hidden={{true}}>, {{"true"}}, {{"TRUE"}}, {{"True"}}

Still flag (explicit opt-in to the content check):

• <h1 aria-hidden="false">, {{false}}, {{"false"}}

Tests

Valid (heading exempted):

• Valueless, empty, "true" / "TRUE" / "True", {{true}}, {{"true"}} / case-variants

Invalid (falsy explicitly → flagged):

• <h1 aria-hidden="false"></h1>, {{false}}, {{"false"}}