fix: mark section hidden when all children are hidden

Prevents empty section headers from appearing when consumers filter
hidden items. Also fixes misleading comment ("no visible children"
→ "no children").

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dslovinsky

src/content-indexer/visitors/__tests__/visit-section.test.ts

@@ -223,6 +223,84 @@ describe("visitSection", () => {
     expect(Object.keys(result.indexEntries).length).toBeGreaterThan(0);
   });
 
+  test("should mark section hidden when all children are hidden", () => {
+    const context = new ProcessingContext("docs");
+    const cache = new ContentCache();
+
+    const result = visitSection(
+      {
+        item: {
+          section: "Looks Visible",
+          contents: [
+            {
+              page: "Hidden A",
+              path: "fern/guides/a.mdx",
+              hidden: true,
+            },
+            {
+              page: "Hidden B",
+              path: "fern/guides/b.mdx",
+              hidden: true,
+            },
+          ],
+        },
+        parentPath: PathBuilder.init("guides"),
+        tab: "guides",
+        stripPathPrefix: undefined,
+        contentCache: cache,
+        context,
+        navigationAncestors: [],
+      },
+      visitNavigationItem,
+    );
+
+    // Section itself should be marked hidden since all children are hidden
+    expect(result.navItem).toBeDefined();
+    expect(result.navItem).toHaveProperty("hidden", true);
+    // Children should still be present
+    if (
+      result.navItem &&
+      !Array.isArray(result.navItem) &&
+      "children" in result.navItem
+    ) {
+      expect(result.navItem.children).toHaveLength(2);
+    }
+  });
+
+  test("should not mark section hidden when some children are visible", () => {
+    const context = new ProcessingContext("docs");
+    const cache = new ContentCache();
+
+    const result = visitSection(
+      {
+        item: {
+          section: "Mixed Section",
+          contents: [
+            {
+              page: "Hidden Page",
+              path: "fern/guides/hidden.mdx",
+              hidden: true,
+            },
+            {
+              page: "Visible Page",
+              path: "fern/guides/visible.mdx",
+            },
+          ],
+        },
+        parentPath: PathBuilder.init("guides"),
+        tab: "guides",
+        stripPathPrefix: undefined,
+        contentCache: cache,
+        context,
+        navigationAncestors: [],
+      },
+      visitNavigationItem,
+    );
+
+    expect(result.navItem).toBeDefined();
+    expect(result.navItem).not.toHaveProperty("hidden");
+  });
+
   test("should recursively process nested sections", () => {
     const context = new ProcessingContext("docs");
     const cache = new ContentCache();

src/content-indexer/visitors/visit-section.ts

@@ -138,14 +138,17 @@ export const visitSection = (
     .flat()
     .filter((child): child is NavItem => child !== undefined);
 
-  // Skip section from nav if it has no visible children
+  // Skip section from nav if it has no children
   if (children.length === 0) {
     return { indexEntries, navItem: undefined };
   }
 
-  // Update section nav item with children (mark hidden if applicable)
+  // Update section nav item with children.
+  // Mark hidden if explicitly hidden OR if every child is hidden
+  // (prevents empty section headers when consumers filter hidden items).
   sectionNavItem.children = children;
-  if (sectionItem.hidden) {
+  const allChildrenHidden = children.every((child) => child.hidden === true);
+  if (sectionItem.hidden || allChildrenHidden) {
     sectionNavItem.hidden = true;
   }