Improve doc HTML output

Closes #2491
Closes #2505

This technically contains a breaking change as icons can no longer be overwritten via DefaultThemeRenderContext, but no published theme uses this, so I've decided not to care.

CHANGELOG.md

@@ -3,6 +3,10 @@
 ### Bug Fixes
 
 -   Constructed references to enum types will be properly linked with `@interface`, #2508.
+-   Reduced rendered docs size by writing icons to a referenced SVG asset, #2505.
+    For TypeDoc's docs, this reduced the rendered documentation size by ~30%.
+-   The HTML docs now attempt to reduce repaints caused by dynamically loading the navigation, #2491.
+-   When navigating to a link that contains an anchor, the page will now be properly highlighted in the page navigation.
 
 ## v0.25.9 (2024-02-26)
 

src/lib/output/plugins/IconsPlugin.tsx

@@ -0,0 +1,60 @@
+import { Component, RendererComponent } from "../components";
+import { RendererEvent } from "../events";
+import { writeFile } from "../../utils/fs";
+import { DefaultTheme } from "../themes/default/DefaultTheme";
+import { join } from "path";
+import { JSX, renderElement } from "../../utils";
+
+/**
+ * Plugin which is responsible for creating an icons.js file that embeds the icon SVGs
+ * within the page on page load to reduce page sizes.
+ */
+@Component({ name: "icons" })
+export class IconsPlugin extends RendererComponent {
+    iconHtml?: string;
+
+    override initialize() {
+        this.listenTo(this.owner, {
+            [RendererEvent.BEGIN]: this.onBeginRender,
+        });
+    }
+
+    private onBeginRender(_event: RendererEvent) {
+        if (this.owner.theme instanceof DefaultTheme) {
+            this.owner.postRenderAsyncJobs.push((event) => this.onRenderEnd(event));
+        }
+    }
+
+    private async onRenderEnd(event: RendererEvent) {
+        const children: JSX.Element[] = [];
+        const icons = (this.owner.theme as DefaultTheme).icons;
+
+        for (const [name, icon] of Object.entries(icons)) {
+            children.push(<g id={`icon-${name}`}>{icon.call(icons).children}</g>);
+        }
+
+        const svg = renderElement(<svg xmlns="http://www.w3.org/2000/svg">{children}</svg>);
+        const js = [
+            "(function(svg) {",
+            "    svg.innerHTML = `" + renderElement(<>{children}</>).replaceAll("`", "\\`") + "`;",
+            "    svg.style.display = 'none';",
+            "    if (location.protocol === 'file:') {",
+            "        if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', updateUseElements);",
+            "        else updateUseElements()",
+            "        function updateUseElements() {",
+            "            document.querySelectorAll('use').forEach(el => {",
+            "                if (el.getAttribute('href').includes('#icon-')) {",
+            "                    el.setAttribute('href', el.getAttribute('href').replace(/.*#/, '#'));",
+            "                }",
+            "            });",
+            "        }",
+            "    }",
+            "})(document.body.appendChild(document.createElementNS('http://www.w3.org/2000/svg', 'svg')))",
+        ].join("\n");
+
+        const svgPath = join(event.outputDirectory, "assets/icons.svg");
+        const jsPath = join(event.outputDirectory, "assets/icons.js");
+
+        await Promise.all([writeFile(svgPath, svg), writeFile(jsPath, js)]);
+    }
+}

src/lib/output/plugins/index.ts

@@ -1,5 +1,6 @@
 export { MarkedPlugin } from "../themes/MarkedPlugin";
 export { AssetsPlugin } from "./AssetsPlugin";
+export { IconsPlugin } from "./IconsPlugin";
 export { JavascriptIndexPlugin } from "./JavascriptIndexPlugin";
 export { NavigationPlugin } from "./NavigationPlugin";
 export { SitemapPlugin } from "./SitemapPlugin";

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

@@ -17,6 +17,7 @@ import type { MarkedPlugin } from "../../plugins";
 import { DefaultThemeRenderContext } from "./DefaultThemeRenderContext";
 import { JSX } from "../../../utils";
 import { classNames, getDisplayName, getHierarchyRoots, toStyleClass } from "../lib";
+import { icons } from "./partials/icon";
 
 /**
  * Defines a mapping of a {@link Models.Kind} to a template file.
@@ -56,6 +57,21 @@ export class DefaultTheme extends Theme {
     /** @internal */
     markedPlugin: MarkedPlugin;
 
+    /**
+     * The icons which will actually be rendered. The source of truth lives on the theme, and
+     * the {@link DefaultThemeRenderContext.icons} member will produce references to these.
+     *
+     * These icons will be written twice. Once to an `icons.svg` file in the assets directory
+     * which will be referenced by icons on the context, and once to an `icons.js` file so that
+     * references to the icons can be dynamically embedded within the page for use by the search
+     * dropdown and when loading the page on `file://` urls.
+     *
+     * Custom themes may overwrite this entire object or individual properties on it to customize
+     * the icons used within the page, however TypeDoc currently assumes that all icons are svg
+     * elements, so custom themes must also use svg elements.
+     */
+    icons = { ...icons };
+
     getRenderContext(pageEvent: PageEvent<Reflection>) {
         return new DefaultThemeRenderContext(this, pageEvent, this.application.options);
     }

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

@@ -5,7 +5,7 @@ import {
     DeclarationReflection,
     Reflection,
 } from "../../../models";
-import type { JSX, NeverIfInternal, Options } from "../../../utils";
+import { JSX, NeverIfInternal, Options } from "../../../utils";
 import type { DefaultTheme } from "./DefaultTheme";
 import { defaultLayout } from "./layouts/default";
 import { index } from "./partials";
@@ -53,7 +53,6 @@ function bind<F, L extends any[], R>(fn: (f: F, ...a: L) => R, first: F) {
 }
 
 export class DefaultThemeRenderContext {
-    private _iconsCache: JSX.Element;
     private _refIcons: typeof icons;
     options: Options;
 
@@ -63,24 +62,25 @@ export class DefaultThemeRenderContext {
         options: Options,
     ) {
         this.options = options;
-
-        const { refs, cache } = buildRefIcons(icons);
-        this._refIcons = refs;
-        this._iconsCache = cache;
+        this._refIcons = buildRefIcons(icons, this);
     }
 
+    /**
+     * @deprecated Will be removed in 0.26, no longer required.
+     */
     iconsCache(): JSX.Element {
-        return this._iconsCache;
+        return JSX.createElement(JSX.Fragment, null);
     }
 
+    /**
+     * Icons available for use within the page.
+     *
+     * Note: This creates a reference to icons declared by {@link DefaultTheme.icons},
+     * to customize icons, that object must be modified instead.
+     */
     get icons(): Readonly<typeof icons> {
         return this._refIcons;
     }
-    set icons(value: Readonly<typeof icons>) {
-        const { refs, cache } = buildRefIcons(value);
-        this._refIcons = refs;
-        this._iconsCache = cache;
-    }
 
     hook = (name: keyof RendererHooks) =>
         this.theme.owner.hooks.emit(name, this);

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

@@ -31,18 +31,18 @@ export function registerComponent(
  */
 export class Application {
     alwaysVisibleMember: HTMLElement | null = null;
-
-    /**
-     * Create a new Application instance.
-     */
     constructor() {
         this.createComponents(document.body);
-        this.ensureActivePageVisible();
         this.ensureFocusedElementVisible();
         this.listenForCodeCopies();
         window.addEventListener("hashchange", () =>
             this.ensureFocusedElementVisible(),
         );
+
+        // We're on a *really* slow network connection.
+        if (!document.body.style.display) {
+            this.scrollToHash();
+        }
     }
 
     /**
@@ -63,6 +63,24 @@ export class Application {
         this.ensureFocusedElementVisible();
     }
 
+    public showPage() {
+        if (!document.body.style.display) return;
+        document.body.style.removeProperty("display");
+        this.scrollToHash();
+    }
+
+    public scrollToHash() {
+        // Because we hid the entire page until the navigation loaded or we hit a timeout,
+        // we have to manually resolve the url hash here.
+        if (location.hash) {
+            const reflAnchor = document.getElementById(
+                location.hash.substring(1),
+            );
+            if (!reflAnchor) return;
+            reflAnchor.scrollIntoView({ behavior: "instant", block: "start" });
+        }
+    }
+
     public ensureActivePageVisible() {
         const pageLink = document.querySelector(".tsd-navigation .current");
         let iter = pageLink?.parentElement;
@@ -74,7 +92,7 @@ export class Application {
             iter = iter.parentElement;
         }
 
-        if (pageLink) {
+        if (pageLink && !pageLink.checkVisibility()) {
             const top =
                 pageLink.getBoundingClientRect().top -
                 document.documentElement.clientHeight / 4;

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

@@ -41,6 +41,7 @@ async function buildNav() {
     }
 
     window.app.createComponents(container);
+    window.app.showPage();
     window.app.ensureActivePageVisible();
 }
 
@@ -93,7 +94,7 @@ function addNavText(
         if (classes) {
             a.className = classes;
         }
-        if (location.href === a.href) {
+        if (location.pathname === a.pathname) {
             a.classList.add("current");
         }
         if (el.kind) {

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

@@ -29,14 +29,22 @@ export const defaultLayout = (
                 <link rel="stylesheet" href={context.relativeURL("assets/custom.css", true)} />
             )}
             <script defer src={context.relativeURL("assets/main.js", true)}></script>
+            <script async src={context.relativeURL("assets/icons.js", true)} id="tsd-icons-script"></script>
             <script async src={context.relativeURL("assets/search.js", true)} id="tsd-search-script"></script>
             <script async src={context.relativeURL("assets/navigation.js", true)} id="tsd-nav-script"></script>
             {context.hook("head.end")}
         </head>
         <body>
             {context.hook("body.begin")}
             <script>
-                <Raw html='document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os"' />
+                <Raw html='document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";' />
+                {/* Hide the entire page for up to 0.5 seconds so that if navigating between pages on a fast */}
+                {/* device the navigation pane doesn't appear to flash if it loads just after the page displays. */}
+                {/* This could still happen if we're unlucky, but from experimenting with Firefox's throttling */}
+                {/* settings, this appears to be a reasonable tradeoff between displaying page content without the */}
+                {/* navigation on exceptionally slow connections and not having the navigation obviously repaint. */}
+                <Raw html='document.body.style.display="none";' />
+                <Raw html='setTimeout(() => document.body.style.removeProperty("display"),500)' />
             </script>
             {context.toolbar(props)}
 
@@ -66,7 +74,6 @@ export const defaultLayout = (
             <div class="overlay"></div>
 
             {context.analytics()}
-            {context.iconsCache()}
             {context.hook("body.end")}
         </body>
     </html>

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

@@ -1,6 +1,7 @@
 import assert from "assert";
 import { ReflectionKind } from "../../../../models";
 import { JSX } from "../../../../utils";
+import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 
 const kindIcon = (letterPath: JSX.Element, color: string, circular = false) => (
     <svg class="tsd-kind-icon" viewBox="0 0 24 24">
@@ -18,9 +19,11 @@ const kindIcon = (letterPath: JSX.Element, color: string, circular = false) => (
     </svg>
 );
 
-export function buildRefIcons<T extends Record<string, () => JSX.Element>>(icons: T): { refs: T; cache: JSX.Element } {
+export function buildRefIcons<T extends Record<string, () => JSX.Element>>(
+    icons: T,
+    context: DefaultThemeRenderContext,
+): T {
     const refs: Record<string, () => JSX.Element> = {};
-    const children: JSX.Element[] = [];
 
     for (const [name, builder] of Object.entries(icons)) {
         const jsx = builder.call(icons);
@@ -32,19 +35,15 @@ export function buildRefIcons<T extends Record<string, () => JSX.Element>>(icons
             continue;
         }
 
-        children.push(<g id={`icon-${name}`}>{jsx.children}</g>);
         const ref = (
             <svg {...jsx.props} id={undefined}>
-                <use href={`#icon-${name}`} />
+                <use href={`${context.relativeURL("assets/icons.svg")}#icon-${name}`} />
             </svg>
         );
         refs[name] = () => ref;
     }
 
-    return {
-        refs: refs as T,
-        cache: <svg style={"display: none"}>{children}</svg>,
-    };
+    return refs as T;
 }
 
 export const icons: Record<

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

@@ -2,11 +2,8 @@ import { Reflection, ReflectionKind } from "../../../../models";
 import { JSX } from "../../../../utils";
 import type { PageEvent } from "../../../events";
 import { camelToTitleCase, classNames, getDisplayName, wbr } from "../../lib";
-import type { NavigationElement } from "../DefaultTheme";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 
-const MAX_EMBEDDED_NAV_SIZE = 20;
-
 export function sidebar(context: DefaultThemeRenderContext, props: PageEvent<Reflection>) {
     return (
         <>
@@ -100,66 +97,14 @@ export function settings(context: DefaultThemeRenderContext) {
 }
 
 export const navigation = function navigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>) {
-    const nav = context.getNavigation();
-
-    let elements = 0;
-    function link(el: NavigationElement, path: string[] = []) {
-        if (elements > MAX_EMBEDDED_NAV_SIZE) {
-            return <></>;
-        }
-
-        if (el.path) {
-            ++elements;
-            return (
-                <li>
-                    <a
-                        href={context.relativeURL(el.path)}
-                        class={classNames({ current: props.model.url === el.path }, el.class)}
-                    >
-                        {el.kind && context.icons[el.kind]()}
-                        {el.text}
-                    </a>
-                </li>
-            );
-        }
-
-        // Top level element is a group/category, recurse so that we don't have a half-broken
-        // navigation tree for people with JS turned off.
-        if (el.children) {
-            ++elements;
-            const fullPath = [...path, el.text];
-
-            return (
-                <details class={classNames({ "tsd-index-accordion": true }, el.class)} data-key={fullPath.join("$")}>
-                    <summary class="tsd-accordion-summary">
-                        {context.icons.chevronDown()}
-                        <span>{el.text}</span>
-                    </summary>
-                    <div class="tsd-accordion-details">
-                        <ul class="tsd-nested-navigation">{el.children.map((c) => link(c, fullPath))}</ul>
-                    </div>
-                </details>
-            );
-        }
-
-        return (
-            <li>
-                <span>{el.text}</span>
-            </li>
-        );
-    }
-
-    const navEl = nav.map((el) => link(el));
-
     return (
         <nav class="tsd-navigation">
             <a href={context.urlTo(props.project)} class={classNames({ current: props.project === props.model })}>
                 {context.icons[ReflectionKind.Project]()}
                 <span>{getDisplayName(props.project)}</span>
             </a>
             <ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base={context.relativeURL("./")}>
-                {navEl}
-                {elements < MAX_EMBEDDED_NAV_SIZE || <li>Loading...</li>}
+                <li>Loading...</li>
             </ul>
         </nav>
     );