feat: add no-empty-headings rule to enforce accessible heading content (#373)

* feat: add no-empty-headings rule to enforce accessible heading content

* refactor: improve type definitions and clean up parameter annotations in no-empty-headings rule

* refactor: remove unused getHeadingText function from no-empty-headings rule

* fix

* Update no-empty-headings.js

---------

Co-authored-by: YeonJuan <[email protected]>

Author: ivioje

docs/rules.md

@@ -48,6 +48,7 @@
 | [no-accesskey-attrs](rules/no-accesskey-attrs)                   | Disallow to use of accesskey attribute                                 |     |
 | [no-aria-hidden-body](rules/no-aria-hidden-body)                 | Disallow to use aria-hidden attributes on the `body` element.          |     |
 | [no-aria-hidden-on-focusable](rules/no-aria-hidden-on-focusable) | Disallow aria-hidden="true" on focusable elements                      |     |
+| [no-empty-headings](rules/no-empty-headings)                     | Disallow empty or inaccessible headings.                               |     |
 | [no-heading-inside-button](rules/no-heading-inside-button)       | Disallows the use of heading elements inside <button>.                 |     |
 | [no-invalid-role](rules/no-invalid-role)                         | Disallows use of invalid role.                                         |     |
 | [no-non-scalable-viewport](rules/no-non-scalable-viewport)       | Disallow use of `user-scalable=no` in `<meta name="viewport">`.        |     |

docs/rules/no-empty-headings.md

@@ -0,0 +1,43 @@
+# no-empty-headings
+
+This rule enforces that all heading elements (h1–h6) and elements with `role="heading"` must have accessible text content.
+
+### Why?
+
+Headings relay the structure of a webpage and provide a meaningful, hierarchical order of its content. If headings are empty or their text contents are inaccessible, this could confuse users or prevent them from accessing sections of interest, especially for those using assistive technology.
+
+## How to use
+
+```js,.eslintrc.js
+module.exports = {
+  rules: {
+    "@html-eslint/no-empty-headings": "error",
+  },
+};
+```
+
+## Rule Details
+
+Headings that are empty or whose text is only present in elements with `aria-hidden="true"` are not allowed, as this can confuse users or prevent them from accessing sections of interest.
+
+### ❌ Incorrect
+
+```html
+<h1></h1>
+<div role="heading" aria-level="1"></div>
+<h2><span aria-hidden="true">Inaccessible text</span></h2>
+```
+
+### ✅ Correct
+
+```html
+<h1>Heading Content</h1>
+<h2><span>Text</span></h2>
+<div role="heading" aria-level="1">Heading Content</div>
+<h3 aria-hidden="true">Heading Content</h3>
+<h4 hidden>Heading Content</h4>
+```
+
+### Resources
+
+- [ember-template-lint: no-empty-headings](https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/no-empty-headings.md)

packages/eslint-plugin/lib/rules/index.js

@@ -48,6 +48,7 @@ const maxElementDepth = require("./max-element-depth");
 const requireExplicitSize = require("./require-explicit-size");
 const useBaseLine = require("./use-baseline");
 const noDuplicateClass = require("./no-duplicate-class");
+const noEmptyHeadings = require("./no-empty-headings");
 // import new rule here ↑
 // DO NOT REMOVE THIS COMMENT
 
@@ -102,6 +103,7 @@ const rules = {
   "require-explicit-size": requireExplicitSize,
   "use-baseline": useBaseLine,
   "no-duplicate-class": noDuplicateClass,
+  "no-empty-headings": noEmptyHeadings,
   // export new rule here ↑
   // DO NOT REMOVE THIS COMMENT
 };

packages/eslint-plugin/lib/rules/no-empty-headings.js

@@ -0,0 +1,122 @@
+/**
+ * @typedef { import("../types").RuleModule<[]> } RuleModule
+ * @typedef { import("@html-eslint/types").Tag } Tag
+ * @typedef { import("@html-eslint/types").Text } Text
+ */
+
+const { RULE_CATEGORY } = require("../constants");
+const { findAttr, isTag, isText } = require("./utils/node");
+const { createVisitors } = require("./utils/visitors");
+const { getRuleUrl } = require("./utils/rule");
+
+const MESSAGE_IDS = {
+  EMPTY_HEADING: "emptyHeading",
+  INACCESSIBLE_HEADING: "inaccessibleHeading",
+};
+
+const HEADING_NAMES = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+
+/**
+ * @param {Tag} node
+ */
+function isAriaHidden(node) {
+  const ariaHiddenAttr = findAttr(node, "aria-hidden");
+  return (
+    ariaHiddenAttr &&
+    ariaHiddenAttr.value &&
+    ariaHiddenAttr.value.value === "true"
+  );
+}
+
+/**
+ * @param {Tag} node
+ * @returns {boolean}
+ */
+function isRoleHeading(node) {
+  const roleAttr = findAttr(node, "role");
+  return !!roleAttr && !!roleAttr.value && roleAttr.value.value === "heading";
+}
+
+/**
+ * @param {Text | Tag} node
+ * @returns {string}
+ */
+function getAllText(node) {
+  if (!isTag(node) || !node.children.length) return "";
+  let text = "";
+  for (const child of node.children) {
+    if (isText(child)) {
+      text += child.value.trim();
+    } else if (isTag(child)) {
+      text += getAllText(child);
+    }
+  }
+  return text;
+}
+
+/**
+ * @param {Text | Tag} node
+ * @returns {string}
+ */
+function getAccessibleText(node) {
+  if (!isTag(node) || !node.children.length) return "";
+  let text = "";
+  for (const child of node.children) {
+    if (isText(child)) {
+      text += child.value.trim();
+    } else if (isTag(child) && !isAriaHidden(child)) {
+      text += getAccessibleText(child);
+    }
+  }
+  return text;
+}
+
+/**
+ * @type {RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: "code",
+    docs: {
+      description: "Disallow empty or inaccessible headings.",
+      category: RULE_CATEGORY.ACCESSIBILITY,
+      recommended: false,
+      url: getRuleUrl("no-empty-headings"),
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      [MESSAGE_IDS.EMPTY_HEADING]: "Headings must not be empty.",
+      [MESSAGE_IDS.INACCESSIBLE_HEADING]:
+        "Heading text is inaccessible to assistive technology.",
+    },
+  },
+  create(context) {
+    return createVisitors(context, {
+      Tag(node) {
+        const tagName = node.name.toLowerCase();
+        const isHeadingTag = HEADING_NAMES.has(tagName);
+        const isRoleHeadingEl = isRoleHeading(node);
+        if (!isHeadingTag && !isRoleHeadingEl) return;
+
+        // Gather all text (including aria-hidden)
+        const allText = getAllText(node);
+        if (!allText) {
+          context.report({
+            node,
+            messageId: MESSAGE_IDS.EMPTY_HEADING,
+          });
+          return;
+        }
+        // Gather accessible text (not aria-hidden)
+        const accessibleText = getAccessibleText(node);
+        if (!accessibleText) {
+          context.report({
+            node,
+            messageId: MESSAGE_IDS.INACCESSIBLE_HEADING,
+          });
+        }
+      },
+    });
+  },
+};

packages/eslint-plugin/tests/rules/no-empty-headings.test.js

@@ -0,0 +1,91 @@
+const createRuleTester = require("../rule-tester");
+const rule = require("../../lib/rules/no-empty-headings");
+
+const ruleTester = createRuleTester();
+const templateRuleTester = createRuleTester("espree");
+
+ruleTester.run("no-empty-headings", rule, {
+  valid: [
+    { code: "<h1>Heading Content</h1>" },
+    { code: "<h2><span>Text</span></h2>" },
+    { code: '<div role="heading" aria-level="1">Heading Content</div>' },
+    { code: '<h3 aria-hidden="true">Heading Content</h3>' },
+    { code: "<h4 hidden>Heading Content</h4>" },
+    { code: '<h2><span aria-hidden="true"></span>Visible</h2>' },
+    {
+      code: '<h2><span aria-hidden="true">Hidden</span><span>Visible</span></h2>',
+    },
+  ],
+  invalid: [
+    {
+      code: "<h1></h1>",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: "<h1> <span></span> </h1>",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: "<h1><!-- comment --></h1>",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: '<div role="heading" aria-level="1"></div>',
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: '<h2><span aria-hidden="true">Inaccessible text</span></h2>',
+      errors: [{ messageId: "inaccessibleHeading" }],
+    },
+    {
+      code: "<h3>   </h3>",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: '<h4><span aria-hidden="true"></span></h4>',
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: `<h4>
+</h4>`,
+      errors: [{ messageId: "emptyHeading" }],
+    },
+  ],
+});
+
+templateRuleTester.run("[template] no-empty-headings", rule, {
+  valid: [
+    { code: "html`<h1>Heading Content</h1>`" },
+    { code: "html`<h1>${foo}</h1>`" },
+    { code: "html`<h2><span>Text</span></h2>`" },
+    { code: 'html`<div role="heading" aria-level="1">Heading Content</div>`' },
+    { code: 'html`<h3 aria-hidden="true">Heading Content</h3>`' },
+    { code: "html`<h4 hidden>Heading Content</h4>`" },
+    { code: 'html`<h2><span aria-hidden="true"></span>Visible</h2>`' },
+    {
+      code: 'html`<h2><span aria-hidden="true">Hidden</span><span>Visible</span></h2>`',
+    },
+  ],
+  invalid: [
+    {
+      code: "html`<h1></h1>`",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: 'html`<div role="heading" aria-level="1"></div>`',
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: 'html`<h2><span aria-hidden="true">Inaccessible text</span></h2>`',
+      errors: [{ messageId: "inaccessibleHeading" }],
+    },
+    {
+      code: "html`<h3>   </h3>`",
+      errors: [{ messageId: "emptyHeading" }],
+    },
+    {
+      code: 'html`<h4><span aria-hidden="true"></span></h4>`',
+      errors: [{ messageId: "emptyHeading" }],
+    },
+  ],
+});