Implement a declaration import for typedoc output

Author: Gerrit0

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

@@ -36,6 +36,7 @@ import { hierarchyTemplate } from "./templates/hierarchy.js";
 import { reflectionTemplate } from "./templates/reflection.js";
 import { typeDeclaration, typeDetails, typeDetailsIfUseful } from "./partials/typeDetails.js";
 import { moduleMemberSummary, moduleReflection } from "./partials/moduleReflection.js";
+import { declarationImport } from "./partials/declarationImport.js";
 import type { Router } from "../../router.js";
 import type { JSX, NeverIfInternal } from "#utils";
 
@@ -159,6 +160,7 @@ export class DefaultThemeRenderContext {
     reflectionFlags = bind(reflectionFlags, this);
     footer = bind(footer, this);
     header = bind(header, this);
+    declarationImport = bind(declarationImport, this);
     hierarchy = bind(hierarchy, this);
     index = bind(index, this);
     member = bind(member, this);

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

@@ -0,0 +1,68 @@
+import { type Reflection, ReflectionKind } from "#models";
+import { JSX } from "#utils";
+import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext.js";
+
+function getValidIdentifier(name: string) {
+    const lastSlash = name.lastIndexOf("/");
+    if (lastSlash) {
+        return name.substring(lastSlash + 1).replace(/[^a-z0-9]/gi, "_");
+    }
+    return name.replace(/[^a-z0-9]/gi, "_");
+}
+
+interface ImportInfo {
+    packageName: string | undefined;
+    importSpecifier: string;
+    extra?: string;
+}
+
+function getImportInfo(refl: Reflection): ImportInfo | undefined {
+    if (refl.isDocument()) return;
+
+    // Reference is a module, produce a namespace import
+    if (refl.kindOf(ReflectionKind.Project | ReflectionKind.Module)) {
+        const packageName = refl.isProject() ? refl.packageName : refl.name;
+        return {
+            packageName,
+            importSpecifier: `* as ${getValidIdentifier(packageName || refl.name)}`,
+        };
+    }
+
+    // Simple case, directly within a module
+    if (refl.parent?.kindOf(ReflectionKind.Project | ReflectionKind.Module)) {
+        return {
+            packageName: refl.parent.isProject() ? refl.parent.packageName : refl.parent.name,
+            importSpecifier: `{ ${getValidIdentifier(refl.name)} }`,
+        };
+    }
+
+    // More obnoxious case, inside a namespace somewhere
+    const path: Reflection[] = [refl];
+    let iter = refl;
+    while (!iter.parent?.kindOf(ReflectionKind.Project | ReflectionKind.Project)) {
+        iter = iter.parent!;
+        path.push(iter);
+    }
+
+    return {
+        packageName: iter.parent.isProject() ? iter.parent.packageName : iter.parent.name,
+        importSpecifier: `{ ${getValidIdentifier(path[path.length - 1].name)} }`,
+        extra: "// " + path.reverse().map(r => r.name).join("."),
+    };
+}
+
+export function declarationImport(context: DefaultThemeRenderContext, refl: Reflection) {
+    const info = getImportInfo(refl);
+
+    if (info?.packageName) {
+        const code = [`import ${info.importSpecifier} from "${info.packageName}"`];
+        if (info.extra) {
+            code.push(info.extra);
+        }
+        const html = context.markdown([
+            { kind: "code", text: "```ts\n" + code.join("\n") + "\n```" },
+        ]);
+
+        return <JSX.Raw html={html} />;
+    }
+}

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

@@ -46,6 +46,7 @@ export const header = (context: DefaultThemeRenderContext, props: PageEvent<Refl
                     {context.reflectionFlags(props.model)}
                 </h1>
             )}
+            {renderTitle && context.declarationImport(props.model)}
         </div>
     );
 };