@ts-for-gir/typedoc-theme 4.0.0-beta.41 → 4.0.0-beta.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/typedoc-theme",
-  "version": "4.0.0-beta.41",
+  "version": "4.0.0-beta.42",
   "description": "Custom TypeDoc theme inspired by gi-docgen for ts-for-gir",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -35,11 +35,13 @@
     ".": "./src/index.ts"
   },
   "devDependencies": {
-    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.42",
+    "@types/lunr": "^2.3.7",
     "@types/node": "^24.12.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "lunr": "^2.3.9",
     "typedoc": "^0.28.17"
   }
 }

package/src/partials/layout.ts

@@ -1,7 +1,17 @@
 import type { PageEvent, Reflection, RenderTemplate } from "typedoc";
 import { JSX } from "typedoc";
 import type { GiDocgenThemeRenderContext } from "../context.ts";
-import { getDisplayName, getHierarchyRoots } from "../utils.ts";
+import { sanitizeModuleName } from "../search-splitter.ts";
+import { findOwningModule, getDisplayName, getHierarchyRoots } from "../utils.ts";
+
+/** Determine which search chunk file to load for this page. */
+function getSearchScript(props: PageEvent<Reflection>): string {
+	const owningModule = findOwningModule(props.model);
+	if (owningModule) {
+		return `assets/search-${sanitizeModuleName(owningModule.name)}.js`;
+	}
+	return "assets/search-modules.js";
+}
 
 export const giDocgenLayout = (
 	context: GiDocgenThemeRenderContext,
@@ -64,7 +74,7 @@ export const giDocgenLayout = (
 			}),
 			JSX.createElement("script", {
 				async: true,
-				src: context.relativeURL("assets/search.js", true),
+				src: context.relativeURL(getSearchScript(props), true),
 				id: "tsd-search-script",
 			}),
 			JSX.createElement("script", {

package/src/partials/module-reflection.ts

@@ -161,11 +161,19 @@ export function giDocgenModuleReflection(
 	if (mod.isDeclaration() && isCompanionNamespace(mod as DeclarationReflection)) {
 		const parent = mod.parent;
 		const siblings = parent && "children" in parent ? (parent as DeclarationReflection).children : undefined;
-		const companionClass = siblings?.find(
-			(child) => child !== mod && child.kindOf(ReflectionKind.Class) && child.name === mod.name,
+		const companionOwner = siblings?.find(
+			(child) =>
+				child !== mod &&
+				child.kindOf(ReflectionKind.Class | ReflectionKind.Interface | ReflectionKind.Enum) &&
+				child.name === mod.name,
 		);
-		if (companionClass) {
-			const classUrl = context.urlTo(companionClass);
+		if (companionOwner) {
+			const ownerUrl = context.urlTo(companionOwner);
+			const kindName = companionOwner.kindOf(ReflectionKind.Enum)
+				? "enum"
+				: companionOwner.kindOf(ReflectionKind.Interface)
+					? "interface"
+					: "class";
 			return JSX.createElement(
 				JSX.Fragment,
 				null,
@@ -173,13 +181,13 @@ export function giDocgenModuleReflection(
 					"p",
 					null,
 					"This namespace is a companion to the ",
-					JSX.createElement("a", { href: classUrl }, companionClass.name),
-					" class. See the class page for full documentation.",
+					JSX.createElement("a", { href: ownerUrl }, companionOwner.name),
+					` ${kindName}. See the ${kindName} page for full documentation.`,
 				),
 				JSX.createElement(
 					"script",
 					null,
-					JSX.createElement(JSX.Raw, { html: `window.location.replace("${classUrl}");` }),
+					JSX.createElement(JSX.Raw, { html: `window.location.replace("${ownerUrl}");` }),
 				),
 			);
 		}

package/src/partials/sidebar.ts

@@ -11,9 +11,17 @@ import {
 	isCompanionNamespace,
 } from "../utils.ts";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TSFOR_GIR_VERSION = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf8"))
-	.version as string;
+declare const __TS_FOR_GIR_VERSION__: string;
+
+function getTsForGirVersion(): string {
+	if (typeof __TS_FOR_GIR_VERSION__ !== "undefined") {
+		return __TS_FOR_GIR_VERSION__;
+	}
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	return JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf8")).version as string;
+}
+
+const TSFOR_GIR_VERSION = getTsForGirVersion();
 
 /** Render the module info section (namespace name, versions, dependencies). */
 function giDocgenModuleInfo(

package/src/search-splitter.ts

@@ -0,0 +1,163 @@
+/**
+ * Post-processes TypeDoc's monolithic search.js into per-module chunks.
+ *
+ * TypeDoc generates a single search.js containing all 460k+ entries (16 MB compressed).
+ * This module splits it into one file per GIR module so each page only loads the
+ * search data it needs.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { deflateSync, inflateSync } from "node:zlib";
+import lunr from "lunr";
+
+// TypeDoc ReflectionKind.Module = 2
+const KIND_MODULE = 2;
+
+interface SearchDocument {
+	kind: number;
+	name: string;
+	url: string;
+	classes?: string;
+	parent?: string;
+	icon?: string | number;
+}
+
+interface SearchData {
+	rows: SearchDocument[];
+	index: object; // serialized lunr index — we don't need to load it
+}
+
+/**
+ * Sanitize a module name for use as a filename.
+ * e.g. "Gtk-4.0" → "gtk-4.0", "gjs/cairo" → "gjs_cairo"
+ */
+export function sanitizeModuleName(name: string): string {
+	return name.toLowerCase().replace(/[/\\]/g, "_");
+}
+
+/**
+ * Extract the top-level module name from a search row.
+ * - Module entries (kind=2): module = row.name
+ * - Everything else: match the parent prefix against known module names
+ *
+ * We can't simply split on "." because module names themselves contain dots
+ * (e.g. "AppStream-1.0" has parent "AppStream-1.0.AppStream.Component").
+ */
+function getModuleName(row: SearchDocument, moduleNames: Set<string>): string | undefined {
+	if (row.kind === KIND_MODULE) return row.name;
+	if (!row.parent) return undefined;
+
+	// Try to match the parent prefix against known module names
+	for (const mod of moduleNames) {
+		if (row.parent === mod || row.parent.startsWith(`${mod}.`)) {
+			return mod;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Build a compressed search chunk (same format as TypeDoc's search.js)
+ * from a subset of rows.
+ */
+function buildChunk(rows: SearchDocument[]): string {
+	const builder = new lunr.Builder();
+	builder.pipeline.add(lunr.trimmer);
+	builder.ref("id");
+	builder.field("name", { boost: 10 });
+
+	for (let i = 0; i < rows.length; i++) {
+		builder.add({ id: i, name: rows[i].name });
+	}
+
+	const index = builder.build();
+	const data = { rows, index };
+	const compressed = deflateSync(Buffer.from(JSON.stringify(data)));
+	return compressed.toString("base64");
+}
+
+/**
+ * Read and decompress TypeDoc's search.js, returning the parsed search data.
+ */
+function readSearchData(assetsDir: string): SearchData {
+	const raw = readFileSync(join(assetsDir, "search.js"), "utf-8");
+
+	// Extract base64 payload from: window.searchData = "...";
+	const match = raw.match(/window\.searchData\s*=\s*"([^"]+)"/);
+	if (!match?.[1]) {
+		throw new Error("Could not extract searchData from search.js");
+	}
+
+	const decoded = Buffer.from(match[1], "base64");
+	const decompressed = inflateSync(decoded);
+	return JSON.parse(decompressed.toString("utf-8")) as SearchData;
+}
+
+/**
+ * Split the monolithic search.js into per-module chunks.
+ *
+ * Produces:
+ * - `search-modules.js` — module-level entries only (for the homepage)
+ * - `search-{module}.js` — per-module entries (for module pages)
+ * - Replaces `search.js` with a null stub
+ */
+export async function splitSearchIndex(outputDir: string): Promise<void> {
+	const assetsDir = join(outputDir, "assets");
+
+	let searchData: SearchData;
+	try {
+		searchData = readSearchData(assetsDir);
+	} catch {
+		// No search.js or unparseable — nothing to split
+		return;
+	}
+
+	const { rows } = searchData;
+
+	// Collect known module names first (kind=2 entries)
+	const moduleNames = new Set<string>();
+	for (const row of rows) {
+		if (row.kind === KIND_MODULE) {
+			moduleNames.add(row.name);
+		}
+	}
+
+	// Group rows by module
+	const moduleMap = new Map<string, SearchDocument[]>();
+	const moduleEntries: SearchDocument[] = [];
+
+	for (const row of rows) {
+		if (row.kind === KIND_MODULE) {
+			moduleEntries.push(row);
+		}
+
+		const mod = getModuleName(row, moduleNames);
+		if (!mod) continue;
+
+		let bucket = moduleMap.get(mod);
+		if (!bucket) {
+			bucket = [];
+			moduleMap.set(mod, bucket);
+		}
+		bucket.push(row);
+	}
+
+	// Write per-module chunks
+	for (const [moduleName, moduleRows] of moduleMap) {
+		const chunk = buildChunk(moduleRows);
+		const filename = `search-${sanitizeModuleName(moduleName)}.js`;
+		writeFileSync(join(assetsDir, filename), `window.searchData = "${chunk}";`);
+	}
+
+	// Write module index for homepage
+	const modulesChunk = buildChunk(moduleEntries);
+	writeFileSync(join(assetsDir, "search-modules.js"), `window.searchData = "${modulesChunk}";`);
+
+	// Replace original search.js with a null stub
+	writeFileSync(join(assetsDir, "search.js"), "window.searchData = null;");
+
+	const totalChunks = moduleMap.size + 1; // +1 for modules index
+	console.log(`[search-splitter] Split ${rows.length} entries into ${totalChunks} chunks (${moduleMap.size} modules)`);
+}

package/src/theme.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { NavigationElement, ProjectReflection, Renderer } from "typedoc";
 import { DefaultTheme, RendererEvent } from "typedoc";
 import { GiDocgenThemeRenderContext } from "./context.ts";
+import { splitSearchIndex } from "./search-splitter.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -79,4 +80,8 @@ export class GiDocgenTheme extends DefaultTheme {
 	override getNavigation(project: ProjectReflection): NavigationElement[] {
 		return buildShallowNavigation(super.getNavigation(project));
 	}
+
+	override async postRender(event: RendererEvent): Promise<void> {
+		await splitSearchIndex(event.outputDirectory);
+	}
 }

package/src/utils.ts

@@ -202,7 +202,7 @@ export function getGirNamespaceMetadata(reflection: Reflection): GirNamespaceMet
 // Companion namespace detection
 // ---------------------------------------------------------------------------
 
-const COMPANION_OWNER_KINDS = ReflectionKind.Class | ReflectionKind.Interface;
+const COMPANION_OWNER_KINDS = ReflectionKind.Class | ReflectionKind.Interface | ReflectionKind.Enum;
 
 /**
  * Find the companion namespace for a class or interface reflection.