Include page groups in page TOC

Resolves #2616

Author: Gerrit0

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+### Features
+
+-   "On This Page" navigation now includes the page groups in collapsible sections, #2616.
+
 ### Bug Fixes
 
 -   `mailto:` links are no longer incorrectly recognized as relative paths, #2613.

src/lib/output/events.ts

@@ -69,6 +69,14 @@ export class RendererEvent {
     }
 }
 
+export interface PageHeading {
+    link: string;
+    text: string;
+    level?: number;
+    kind?: ReflectionKind;
+    classes?: string;
+}
+
 /**
  * An event emitted by the {@link Renderer} class before and after the
  * markup of a page is rendered.
@@ -108,13 +116,29 @@ export class PageEvent<out Model = unknown> extends Event {
      * Links to content within this page that should be rendered in the page navigation.
      * This is built when rendering the document content.
      */
-    pageHeadings: Array<{
-        link: string;
-        text: string;
-        level?: number;
-        kind?: ReflectionKind;
-        classes?: string;
-    }> = [];
+    pageHeadings: PageHeading[] = [];
+
+    /**
+     * Sections of the page, generally set by `@group`s
+     */
+    pageSections = [
+        {
+            title: "",
+            headings: this.pageHeadings,
+        },
+    ];
+
+    /**
+     * Start a new section of the page. Sections are collapsible within
+     * the "On This Page" sidebar.
+     */
+    startNewSection(title: string) {
+        this.pageHeadings = [];
+        this.pageSections.push({
+            title,
+            headings: this.pageHeadings,
+        });
+    }
 
     /**
      * Triggered before a document will be rendered.

src/lib/output/themes/default/DefaultThemeRenderContext.ts

@@ -32,7 +32,6 @@ import { memberSignatureTitle } from "./partials/member.signature.title";
 import { memberSignatures } from "./partials/member.signatures";
 import { memberSources } from "./partials/member.sources";
 import { members } from "./partials/members";
-import { membersGroup } from "./partials/members.group";
 import {
     sidebar,
     pageSidebar,
@@ -63,7 +62,7 @@ export class DefaultThemeRenderContext {
     i18n: TranslationProxy;
 
     constructor(
-        private theme: DefaultTheme,
+        readonly theme: DefaultTheme,
         public page: PageEvent<Reflection>,
         options: Options,
     ) {
@@ -144,7 +143,8 @@ export class DefaultThemeRenderContext {
     memberSignatures = bind(memberSignatures, this);
     memberSources = bind(memberSources, this);
     members = bind(members, this);
-    membersGroup = bind(membersGroup, this);
+    /** @deprecated Since 0.26.3 members does group/category flattening internally */
+    membersGroup?: Function;
     sidebar = bind(sidebar, this);
     pageSidebar = bind(pageSidebar, this);
     sidebarLinks = bind(sidebarLinks, this);

src/lib/output/themes/default/partials/members.group.tsx

@@ -1,35 +1,61 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
-import { JSX } from "../../../../utils";
-import { type ContainerReflection, DeclarationReflection } from "../../../../models";
-import { classNames } from "../../lib";
+import { filterMap, JSX } from "../../../../utils";
+import type { ContainerReflection } from "../../../../models";
 
-export function members(context: DefaultThemeRenderContext, props: ContainerReflection) {
-    if (props.categories && props.categories.length) {
-        return (
-            <>
-                {props.categories.map(
-                    (item) =>
-                        !item.allChildrenHaveOwnDocument() && (
-                            <details
-                                class={classNames(
-                                    { "tsd-panel-group": true, "tsd-member-group": true, "tsd-accordion": true },
-                                    props instanceof DeclarationReflection ? context.getReflectionClasses(props) : "",
-                                )}
-                            >
-                                <summary class="tsd-accordion-summary" data-key={"section-" + item.title}>
-                                    <h2>
-                                        {context.icons.chevronDown()} {item.title}
-                                    </h2>
-                                </summary>
-                                <section>
-                                    {item.children.map((item) => !item.hasOwnDocument && context.member(item))}
-                                </section>
-                            </details>
-                        ),
-                )}
-            </>
-        );
+function getMemberSections(parent: ContainerReflection) {
+    if (parent.categories?.length) {
+        return filterMap(parent.categories, (cat) => {
+            if (!cat.allChildrenHaveOwnDocument()) {
+                return {
+                    title: cat.title,
+                    children: cat.children.filter((child) => !child.hasOwnDocument),
+                };
+            }
+        });
     }
 
-    return <>{props.groups?.map((item) => !item.allChildrenHaveOwnDocument() && context.membersGroup(item))}</>;
+    if (parent.groups?.length) {
+        return parent.groups.flatMap((group) => {
+            if (group.categories?.length) {
+                return filterMap(group.categories, (cat) => {
+                    if (!cat.allChildrenHaveOwnDocument()) {
+                        return {
+                            title: `${group.title} - ${cat.title}`,
+                            children: cat.children.filter((child) => !child.hasOwnDocument),
+                        };
+                    }
+                });
+            }
+
+            return {
+                title: group.title,
+                children: group.children.filter((child) => !child.hasOwnDocument),
+            };
+        });
+    }
+
+    return [];
+}
+
+export function members(context: DefaultThemeRenderContext, props: ContainerReflection) {
+    const sections = getMemberSections(props).filter((sect) => sect.children.length);
+
+    return (
+        <>
+            {sections.map(({ title, children }) => {
+                context.page.startNewSection(title);
+
+                return (
+                    <details class="tsd-panel-group tsd-member-group tsd-accordion" open>
+                        <summary class="tsd-accordion-summary" data-key={"section-" + title}>
+                            <h2>
+                                {context.icons.chevronDown()} {title}
+                            </h2>
+                        </summary>
+                        <section>{children.map((item) => context.member(item))}</section>
+                    </details>
+                );
+            })}
+        </>
+    );
 }

src/lib/output/themes/default/partials/members.tsx

@@ -1,6 +1,6 @@
 import { type Reflection, ReflectionFlag, ReflectionKind } from "../../../../models";
 import { JSX } from "../../../../utils";
-import type { PageEvent } from "../../../events";
+import type { PageEvent, PageHeading } from "../../../events";
 import { classNames, getDisplayName, wbr } from "../../lib";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 
@@ -145,7 +145,7 @@ export function pageSidebar(context: DefaultThemeRenderContext, props: PageEvent
     );
 }
 
-export function pageNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>) {
+function buildSectionNavigation(context: DefaultThemeRenderContext, headings: PageHeading[]) {
     const levels: JSX.Element[][] = [[]];
 
     function finalizeLevel(finishedHandlingHeadings: boolean) {
@@ -165,8 +165,12 @@ export function pageNavigation(context: DefaultThemeRenderContext, props: PageEv
         levels[levels.length - 1].push(built);
     }
 
-    for (const heading of props.pageHeadings) {
-        const inferredLevel = heading.level ? heading.level + 1 : 1;
+    for (const heading of headings) {
+        const inferredLevel = heading.level
+            ? heading.level + 2 // regular heading
+            : heading.kind
+              ? 2 // reflection
+              : 1; // group/category
         while (inferredLevel < levels.length) {
             finalizeLevel(false);
         }
@@ -187,12 +191,33 @@ export function pageNavigation(context: DefaultThemeRenderContext, props: PageEv
         finalizeLevel(true);
     }
 
-    if (!levels[0].length) {
+    levels.unshift([]);
+    finalizeLevel(true);
+    return levels[0];
+}
+
+export function pageNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>) {
+    if (!props.pageSections.some((sect) => sect.headings.length)) {
         return <></>;
     }
 
-    levels.unshift([]);
-    finalizeLevel(true);
+    const sections: JSX.Children = [];
+
+    for (const section of props.pageSections) {
+        if (section.title) {
+            sections.push(
+                <details open class="tsd-accordion tsd-page-navigation-section">
+                    <summary class="tsd-accordion-summary" data-key={`tsd-otp-${section.title}`}>
+                        {context.icons.chevronDown()}
+                        {section.title}
+                    </summary>
+                    <div>{buildSectionNavigation(context, section.headings)}</div>
+                </details>,
+            );
+        } else {
+            sections.push(buildSectionNavigation(context, section.headings));
+        }
+    }
 
     return (
         <details open={true} class="tsd-accordion tsd-page-navigation">
@@ -202,7 +227,7 @@ export function pageNavigation(context: DefaultThemeRenderContext, props: PageEv
                     {context.i18n.theme_on_this_page()}
                 </h3>
             </summary>
-            <div class="tsd-accordion-details">{levels[0]}</div>
+            <div class="tsd-accordion-details">{sections}</div>
         </details>
     );
 }

src/lib/output/themes/default/partials/navigation.tsx

@@ -34,6 +34,6 @@ export function getEnumKeys(Enum: {}): string[] {
     return Object.keys(E).filter((k) => E[E[k]] === k);
 }
 
-export type EnumKeys<E extends {}> = keyof {
-    [K in keyof E as number extends E[K] ? K : never]: 1;
-};
+export type EnumKeys<E extends {}> = {
+    [K in keyof E]: number extends E[K] ? K : never;
+}[keyof E] & {};

src/lib/utils/enum.ts

@@ -110,7 +110,7 @@ export interface TypeDocOptionMap {
     externalPattern: string[];
     excludeExternals: boolean;
     excludeNotDocumented: boolean;
-    excludeNotDocumentedKinds: Array<keyof typeof ReflectionKind>;
+    excludeNotDocumentedKinds: ReflectionKind.KindString[];
     excludeInternal: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;

src/lib/utils/options/declaration.ts

@@ -793,6 +793,15 @@ input[type="checkbox"]:checked ~ svg .tsd-checkbox-checkmark {
     margin-left: -1.5rem;
 }
 
+.tsd-page-navigation-section {
+    margin-left: 10px;
+}
+.tsd-page-navigation-section > summary {
+    padding: 0.25rem;
+}
+.tsd-page-navigation-section > div {
+    margin-left: 20px;
+}
 .tsd-page-navigation ul {
     padding-left: 1.75rem;
 }
@@ -841,6 +850,7 @@ a.tsd-index-link {
 }
 .tsd-accordion .tsd-accordion-summary > svg {
     margin-left: 0.25rem;
+    vertical-align: text-top;
 }
 .tsd-index-content > :not(:first-child) {
     margin-top: 0.75rem;