Add --navigation.includeFolders

Closes #2388

Author: Gerrit0

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Features
 
+-   Added a `--navigation.includeFolders` (default: `true`) option to create nested navigation for projects which include many entry points, #2388.
 -   Type parameters on functions/classes can will now link to the "Type Parameters" section, #2322.
     Type parameters have also been changed to have a distinct color from type aliases when rendering, which can be changed with custom CSS.
 -   TypeDoc now provides warnings if a signature comment is directly specified on a signature and contains `@param` tags which do not apply, #2368.
@@ -29,6 +30,8 @@
 -   `@group` and `@category` organization is now applied later to allow inherited comments to create groups/categories, #2459.
 -   Conversion order should no longer affect link resolution for classes with properties whose type does not rely on `this`, #2466.
 -   Keyword syntax highlighting introduced in 0.25.4 was not always applied to keywords.
+-   Module reflections now have a custom `M` icon rather than sharing with the namespace icon.
+    Note: The default CSS still colors both modules and namespaces the same, as it is generally uncommon to have both in a generated site.
 -   If all members in a group are hidden from the page, the group will be hidden in the page index on page load.
 
 ## v0.25.4 (2023-11-26)

src/lib/output/themes/default/DefaultTheme.tsx

@@ -305,27 +305,70 @@ export class DefaultTheme extends Theme {
                 return parent.groups.map(toNavigation);
             }
 
+            if (
+                opts.includeFolders &&
+                parent.children?.every((child) => child.kindOf(ReflectionKind.Module)) &&
+                parent.children.some((child) => child.name.includes("/"))
+            ) {
+                return deriveModuleFolders(parent.children);
+            }
+
             return parent.children?.map(toNavigation);
         }
 
-        function shouldShowCategories(
-            reflection: Reflection,
-            opts: { includeCategories: boolean; includeGroups: boolean },
-        ) {
-            if (opts.includeCategories) {
-                return !reflection.comment?.hasModifier("@hideCategories");
+        function deriveModuleFolders(children: DeclarationReflection[]) {
+            const result: NavigationElement[] = [];
+
+            const resolveOrCreateParents = (
+                path: string[],
+                root: NavigationElement[] = result,
+            ): NavigationElement[] => {
+                if (path.length > 1) {
+                    const inner = root.find((el) => el.text === path[0]);
+                    if (inner) {
+                        inner.children ||= [];
+                        return resolveOrCreateParents(path.slice(1), inner.children);
+                    } else {
+                        root.push({
+                            text: path[0],
+                            children: [],
+                        });
+                        return resolveOrCreateParents(path.slice(1), root[root.length - 1].children);
+                    }
+                }
+
+                return root;
+            };
+
+            // Note: This might end up putting a module within another module if we document
+            // both foo/index.ts and foo/bar.ts.
+            for (const child of children) {
+                const parts = child.name.split("/");
+                const collection = resolveOrCreateParents(parts);
+                const nav = toNavigation(child);
+                nav.text = parts[parts.length - 1];
+                collection.push(nav);
             }
-            return reflection.comment?.hasModifier("@showCategories") === true;
-        }
 
-        function shouldShowGroups(
-            reflection: Reflection,
-            opts: { includeCategories: boolean; includeGroups: boolean },
-        ) {
-            if (opts.includeGroups) {
-                return !reflection.comment?.hasModifier("@hideGroups");
+            // Now merge single-possible-paths together so we don't have folders in our navigation
+            // which contain only another single folder.
+            const queue = [...result];
+            while (queue.length) {
+                const review = queue.shift()!;
+                queue.push(...(review.children || []));
+                if (review.kind || review.path) continue;
+
+                if (review.children?.length === 1) {
+                    const copyFrom = review.children[0];
+                    const fullName = `${review.text}/${copyFrom.text}`;
+                    delete review.children;
+                    Object.assign(review, copyFrom);
+                    review.text = fullName;
+                    queue.push(review);
+                }
             }
-            return reflection.comment?.hasModifier("@showGroups") === true;
+
+            return result;
         }
     }
 
@@ -401,3 +444,17 @@ function getReflectionClasses(reflection: DeclarationReflection, filters: Record
 
     return classes.join(" ");
 }
+
+function shouldShowCategories(reflection: Reflection, opts: { includeCategories: boolean; includeGroups: boolean }) {
+    if (opts.includeCategories) {
+        return !reflection.comment?.hasModifier("@hideCategories");
+    }
+    return reflection.comment?.hasModifier("@showCategories") === true;
+}
+
+function shouldShowGroups(reflection: Reflection, opts: { includeCategories: boolean; includeGroups: boolean }) {
+    if (opts.includeGroups) {
+        return !reflection.comment?.hasModifier("@hideGroups");
+    }
+    return reflection.comment?.hasModifier("@showGroups") === true;
+}

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

@@ -123,9 +123,14 @@ export const icons: Record<
             true,
         ),
     [ReflectionKind.Module]() {
-        return this[ReflectionKind.Namespace]();
+        return kindIcon(
+            <path
+                d="M9.162 16V7.24H10.578L11.514 10.072C11.602 10.328 11.674 10.584 11.73 10.84C11.794 11.088 11.842 11.28 11.874 11.416C11.906 11.28 11.954 11.088 12.018 10.84C12.082 10.584 12.154 10.324 12.234 10.06L13.122 7.24H14.538V16H13.482V12.82C13.482 12.468 13.49 12.068 13.506 11.62C13.53 11.172 13.558 10.716 13.59 10.252C13.622 9.78 13.654 9.332 13.686 8.908C13.726 8.476 13.762 8.1 13.794 7.78L12.366 12.16H11.334L9.894 7.78C9.934 8.092 9.97 8.456 10.002 8.872C10.042 9.28 10.078 9.716 10.11 10.18C10.142 10.636 10.166 11.092 10.182 11.548C10.206 12.004 10.218 12.428 10.218 12.82V16H9.162Z"
+                fill="var(--color-text)"
+            />,
+            "var(--color-ts-module)",
+        );
     },
-
     [ReflectionKind.Namespace]: () =>
         kindIcon(
             <path
@@ -138,7 +143,7 @@ export const icons: Record<
         return this[ReflectionKind.Property]();
     },
     [ReflectionKind.Project]() {
-        return this[ReflectionKind.Namespace]();
+        return this[ReflectionKind.Module]();
     },
     [ReflectionKind.Property]: () =>
         kindIcon(

src/lib/utils/options/declaration.ts

@@ -144,6 +144,7 @@ export interface TypeDocOptionMap {
     navigation: {
         includeCategories: boolean;
         includeGroups: boolean;
+        includeFolders: boolean;
         fullTree: boolean;
     };
     visibilityFilters: ManuallyValidatedOption<{

src/lib/utils/options/sources/typedoc.ts

@@ -464,6 +464,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         defaults: {
             includeCategories: false,
             includeGroups: false,
+            includeFolders: true,
             fullTree: false,
         },
     });