From 8151b3f789e1b84e35fd081ba946cd1c29f61bc3 Mon Sep 17 00:00:00 2001
From: btea <2356281422@qq.com>
Date: Tue, 29 Sep 2026 10:41:40 +0800
Subject: [PATCH] fix(react): include depth-4 headings in the table of contents

---
 .changeset/toc-heading-depth.md               |  5 +++++
 packages/react/src/jsx-ast/constants.mjs      |  4 +++-
 .../utils/__tests__/buildBarProps.test.mjs    | 21 +++++++++++++++++++
 3 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/toc-heading-depth.md

diff --git a/.changeset/toc-heading-depth.md b/.changeset/toc-heading-depth.md
new file mode 100644
index 000000000..e2ee5ddc1
--- /dev/null
+++ b/.changeset/toc-heading-depth.md
@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+fix: include depth-4 headings in the table of contents
diff --git a/packages/react/src/jsx-ast/constants.mjs b/packages/react/src/jsx-ast/constants.mjs
index 0327b8bcb..edeceb452 100644
--- a/packages/react/src/jsx-ast/constants.mjs
+++ b/packages/react/src/jsx-ast/constants.mjs
@@ -45,7 +45,9 @@ export const STABILITY_LEVELS = [
 ];
 
 // How deep should the Table of Contents go?
-export const TOC_MAX_HEADING_DEPTH = 3;
+// Capped at 4 to match the MetaBar component, which only renders depth 2-4
+// (many modules, e.g. diagnostics_channel, document class methods at depth 4)
+export const TOC_MAX_HEADING_DEPTH = 4;
 
 // 'Type: '.length
 export const TYPE_PREFIX_LENGTH = 6;
diff --git a/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs
index bd5fe6d8b..23be1eec4 100644
--- a/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs
+++ b/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs
@@ -138,6 +138,27 @@ describe('extractHeadings', () => {
     );
   });
 
+  it('includes headings up to depth 4 and drops deeper ones', () => {
+    const entries = [2, 3, 4, 5].map(depth => ({
+      heading: {
+        depth,
+        data: {
+          text: `heading ${depth}`,
+          name: `heading ${depth}`,
+          slug: `heading-${depth}`,
+          type: 'misc',
+        },
+      },
+    }));
+
+    const result = extractHeadings(entries);
+
+    assert.deepEqual(
+      result.map(({ depth }) => depth),
+      [2, 3, 4]
+    );
+  });
+
   it('drops overload headings and links to the first signature', () => {
     const entries = [
       {