WIP: Improve navigation

Resolves #2218

Author: Gerrit0

.config/typedoc.json

@@ -16,6 +16,7 @@
     "excludeExternals": true,
     "excludeInternal": false,
     "excludePrivate": true,
+    "excludeReferences": true,
     "treatWarningsAsErrors": false,
     "validation": {
         "notExported": true,

CHANGELOG.md

@@ -35,6 +35,8 @@
 -   Removed `CallbackLogger`.
 -   Removed `SerializeEventData` from serialization events.
 -   A `PageEvent` is no longer passed to `getRenderContext` by the default theme.
+-   Removed `secondaryNavigation` member on `DefaultThemeRenderContext`.
+-   Renamed `navigation` to `sidebar` on `DefaultThemeRenderContext` and `navigation.begin`/`navigation.end` hooks to `sidebar.begin`/`sidebar.end`.
 
 ### Features
 
@@ -50,6 +52,8 @@
 -   Moved sidebar to left of content for consistency with most other websites, #2189.
 -   Added `--cacheBust` option to tell TypeDoc to include include the generation time in files, #2124.
 -   Added support for `@namespace` on variable declarations to tell TypeDoc to convert the variable as a namespace, #2055.
+-   Added `--excludeReferences` option to tell TypeDoc to omit re-exports of a symbol already included from the documentation.
+-   Introduced new render hooks `pageSidebar.begin` and `pageSidebar.end`.
 
 ### Bug Fixes
 

src/index.ts

@@ -3,6 +3,10 @@ export { Application } from "./lib/application";
 export { EventDispatcher, Event } from "./lib/utils/events";
 export { resetReflectionID } from "./lib/models/reflections/abstract";
 export { normalizePath } from "./lib/utils/fs";
+/**
+ * All symbols documented under the Models namespace are also available in the root import.
+ */
+export * as Models from "./lib/models";
 export * from "./lib/models";
 export {
     Converter,

src/lib/converter/converter.ts

@@ -70,6 +70,10 @@ export class Converter extends ChildableComponent<
     @BindOption("excludeProtected")
     excludeProtected!: boolean;
 
+    /** @internal */
+    @BindOption("excludeReferences")
+    excludeReferences!: boolean;
+
     /** @internal */
     @BindOption("commentStyle")
     commentStyle!: CommentStyle;
@@ -117,15 +121,15 @@ export class Converter extends ChildableComponent<
 
     /**
      * Triggered when the converter has created a declaration reflection.
-     * The listener will be given {@link Context} and a {@link DeclarationReflection}.
+     * The listener will be given {@link Context} and a {@link Models.DeclarationReflection}.
      * @event
      */
     static readonly EVENT_CREATE_DECLARATION =
         ConverterEvents.CREATE_DECLARATION;
 
     /**
      * Triggered when the converter has created a signature reflection.
-     * The listener will be given {@link Context}, {@link SignatureReflection} | {@link ProjectReflection} the declaration,
+     * The listener will be given {@link Context}, {@link Models.SignatureReflection} | {@link Models.ProjectReflection} the declaration,
      * `ts.SignatureDeclaration | ts.IndexSignatureDeclaration | ts.JSDocSignature | undefined`,
      * and `ts.Signature | undefined`. The signature will be undefined if the created signature is an index signature.
      * @event
@@ -134,14 +138,14 @@ export class Converter extends ChildableComponent<
 
     /**
      * Triggered when the converter has created a parameter reflection.
-     * The listener will be given {@link Context}, {@link ParameterReflection} and a `ts.Node?`
+     * The listener will be given {@link Context}, {@link Models.ParameterReflection} and a `ts.Node?`
      * @event
      */
     static readonly EVENT_CREATE_PARAMETER = ConverterEvents.CREATE_PARAMETER;
 
     /**
      * Triggered when the converter has created a type parameter reflection.
-     * The listener will be given {@link Context} and a {@link TypeParameterReflection}
+     * The listener will be given {@link Context} and a {@link Models.TypeParameterReflection}
      * @event
      */
     static readonly EVENT_CREATE_TYPE_PARAMETER =

src/lib/converter/symbols.ts

@@ -128,7 +128,9 @@ export function convertSymbol(
     const previous = context.project.getReflectionFromSymbol(symbol);
     if (
         previous &&
-        previous.parent?.kindOf(ReflectionKind.Module | ReflectionKind.Project)
+        previous.parent?.kindOf(
+            ReflectionKind.SomeModule | ReflectionKind.Project
+        )
     ) {
         createAlias(previous, context, symbol, exportSymbol);
         return;
@@ -819,6 +821,8 @@ function createAlias(
     symbol: ts.Symbol,
     exportSymbol: ts.Symbol | undefined
 ) {
+    if (context.converter.excludeReferences) return;
+
     // We already have this. Create a reference.
     const ref = new ReferenceReflection(
         exportSymbol?.name ?? symbol.name,

src/lib/output/renderer.ts

@@ -63,14 +63,24 @@ export interface RendererHooks {
     "content.end": [DefaultThemeRenderContext];
 
     /**
-     * Applied immediately before calling `context.navigation`.
+     * Applied immediately before calling `context.sidebar`.
      */
-    "navigation.begin": [DefaultThemeRenderContext];
+    "sidebar.begin": [DefaultThemeRenderContext];
 
     /**
-     * Applied immediately after calling `context.navigation`.
+     * Applied immediately after calling `context.sidebar`.
      */
-    "navigation.end": [DefaultThemeRenderContext];
+    "sidebar.end": [DefaultThemeRenderContext];
+
+    /**
+     * Applied immediately before calling `context.pageSidebar`.
+     */
+    "pageSidebar.begin": [DefaultThemeRenderContext];
+
+    /**
+     * Applied immediately after calling `context.pageSidebar`.
+     */
+    "pageSidebar.end": [DefaultThemeRenderContext];
 }
 
 /**

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

@@ -29,9 +29,10 @@ import { memberSources } from "./partials/member.sources";
 import { members } from "./partials/members";
 import { membersGroup } from "./partials/members.group";
 import {
+    sidebar,
+    pageSidebar,
     navigation,
-    primaryNavigation,
-    secondaryNavigation,
+    pageNavigation,
     settings,
     sidebarLinks,
 } from "./partials/navigation";
@@ -121,11 +122,12 @@ export class DefaultThemeRenderContext {
     memberSources = bind(memberSources, this);
     members = bind(members, this);
     membersGroup = bind(membersGroup, this);
-    navigation = bind(navigation, this);
+    sidebar = bind(sidebar, this);
+    pageSidebar = bind(pageSidebar, this);
     sidebarLinks = bind(sidebarLinks, this);
     settings = bind(settings, this);
-    primaryNavigation = bind(primaryNavigation, this);
-    secondaryNavigation = bind(secondaryNavigation, this);
+    navigation = bind(navigation, this);
+    pageNavigation = bind(pageNavigation, this);
     parameter = bind(parameter, this);
     toolbar = bind(toolbar, this);
     type = bind(type, this);

src/lib/output/themes/default/assets/bootstrap.ts

@@ -1,5 +1,4 @@
 import { Application, registerComponent } from "./typedoc/Application";
-import { MenuHighlight } from "./typedoc/components/MenuHighlight";
 import { initSearch } from "./typedoc/components/Search";
 import { Toggle } from "./typedoc/components/Toggle";
 import { Filter } from "./typedoc/components/Filter";
@@ -8,7 +7,6 @@ import { initTheme } from "./typedoc/Theme";
 
 initSearch();
 
-registerComponent(MenuHighlight, ".menu-highlight");
 registerComponent(Toggle, "a[data-toggle]");
 registerComponent(Accordion, ".tsd-index-accordion");
 registerComponent(Filter, ".tsd-filter-item input[type=checkbox]");
@@ -18,6 +16,6 @@ if (themeChoice) {
     initTheme(themeChoice as HTMLOptionElement);
 }
 
-const app: Application = new Application();
+const app = new Application();
 
 Object.defineProperty(window, "app", { value: app });

src/lib/output/themes/default/assets/typedoc/Application.ts

@@ -37,6 +37,7 @@ export class Application {
      */
     constructor() {
         this.createComponents(document.body);
+        this.ensureActivePageVisible();
         this.ensureFocusedElementVisible();
         window.addEventListener("hashchange", () =>
             this.ensureFocusedElementVisible()
@@ -61,6 +62,21 @@ export class Application {
         this.ensureFocusedElementVisible();
     }
 
+    private ensureActivePageVisible() {
+        const pageLink = document.querySelector(".tsd-navigation .current");
+        let iter = pageLink?.parentElement;
+        while (iter && !iter.classList.contains(".tsd-navigation")) {
+            // Expand parent namespaces if collapsed, don't expand current namespace
+            if (
+                iter instanceof HTMLDetailsElement &&
+                pageLink?.parentElement?.parentElement !== iter
+            ) {
+                iter.open = true;
+            }
+            iter = iter.parentElement;
+        }
+    }
+
     /**
      * Ensures that if a user was linked to a reflection which is hidden because of filter
      * settings, that reflection is still shown.
@@ -72,6 +88,8 @@ export class Application {
             this.alwaysVisibleMember = null;
         }
 
+        if (!location.hash) return;
+
         const reflAnchor = document.getElementById(location.hash.substring(1));
         if (!reflAnchor) return;