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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ts-for-gir/typedoc-theme",
+  "version": "4.0.0-beta.41",
+  "description": "Custom TypeDoc theme inspired by gi-docgen for ts-for-gir",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gjsify/ts-for-gir.git"
+  },
+  "author": "Pascal Garber <pascal@mailfreun.de>",
+  "files": [
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/gjsify/ts-for-gir/issues"
+  },
+  "homepage": "https://github.com/gjsify/ts-for-gir#readme",
+  "keywords": [
+    "typedoc",
+    "theme",
+    "gi-docgen",
+    "gir",
+    "documentation"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
+    "@types/node": "^24.12.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "typedoc": "^0.28.17"
+  }
+}

package/src/context.ts

@@ -0,0 +1,78 @@
+import type { Options, PageEvent, ProjectReflection, Reflection, Router } from "typedoc";
+import { DefaultThemeRenderContext, JSX } from "typedoc";
+import { giDocgenFooter } from "./partials/footer.ts";
+import { giDocgenHeader } from "./partials/header.ts";
+import { giDocgenLayout } from "./partials/layout.ts";
+import {
+	giDocgenModuleMemberSummary,
+	giDocgenModuleReflection,
+	renderCategorizedProject,
+} from "./partials/module-reflection.ts";
+import { giDocgenNavigation } from "./partials/navigation.ts";
+import { giDocgenPageNavigation } from "./partials/page-navigation.ts";
+import { giDocgenPageSidebar } from "./partials/page-sidebar.ts";
+import { giDocgenSidebar } from "./partials/sidebar.ts";
+import { giDocgenToolbar } from "./partials/toolbar.ts";
+import { giDocgenReflectionTemplate } from "./templates/reflection.ts";
+import type { GiDocgenTheme } from "./theme.ts";
+import { girMemberBadgesFromReflection } from "./utils.ts";
+
+function bind<F, L extends unknown[], R>(fn: (f: F, ...a: L) => R, first: F) {
+	return (...r: L) => fn(first, ...r);
+}
+
+export class GiDocgenThemeRenderContext extends DefaultThemeRenderContext {
+	constructor(router: Router, theme: GiDocgenTheme, page: PageEvent<Reflection>, options: Options) {
+		super(router, theme, page, options);
+
+		this.defaultLayout = bind(giDocgenLayout, this);
+		this.navigation = bind(giDocgenNavigation, this);
+		this.sidebar = bind(giDocgenSidebar, this);
+		this.toolbar = bind(giDocgenToolbar, this);
+		this.footer = bind(giDocgenFooter, this);
+		this.header = bind(giDocgenHeader, this);
+		this.pageNavigation = bind(giDocgenPageNavigation, this);
+		this.pageSidebar = bind(giDocgenPageSidebar, this);
+		this.moduleReflection = bind(giDocgenModuleReflection, this);
+		this.moduleMemberSummary = bind(giDocgenModuleMemberSummary, this);
+		this.reflectionTemplate = bind(giDocgenReflectionTemplate, this);
+
+		// Override indexTemplate to render README + categorized module list on index.html
+		this.indexTemplate = (props: PageEvent<ProjectReflection>) => {
+			const children = props.model.children ?? [];
+			return JSX.createElement(
+				JSX.Fragment,
+				null,
+				// README content
+				JSX.createElement(
+					"div",
+					{ class: "tsd-panel tsd-typography" },
+					JSX.createElement(JSX.Raw, { html: this.markdown(props.model.readme || []) }),
+				),
+				// Categorized module sections
+				renderCategorizedProject(this, props.model, children),
+			);
+		};
+
+		// Remove kind icons (V, F, C, T, etc.) — not needed in the gi-docgen theme.
+		this.reflectionIcon = () => JSX.createElement(JSX.Fragment, null);
+
+		// Extend reflectionFlags to add GIR badges (signal, virtual, property flags, deprecated, since).
+		// Only on the member heading, not on its signature (avoids duplicate badges).
+		const parentFlags = this.reflectionFlags.bind(this);
+		this.reflectionFlags = (props: Reflection) => {
+			const base = parentFlags(props);
+			if (props.isSignature()) return base;
+			const badges = girMemberBadgesFromReflection(props);
+			if (badges.length === 0) return base;
+			return JSX.createElement(
+				JSX.Fragment,
+				null,
+				base,
+				...badges.map((b) =>
+					JSX.createElement("code", { class: `tsd-tag tsd-tag-gir tsd-tag-gir-${b.cssModifier}` }, b.label),
+				),
+			);
+		};
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import type { Application } from "typedoc";
+import { GiDocgenTheme } from "./theme.ts";
+
+export function load(app: Application): void {
+	app.renderer.defineTheme("gi-docgen", GiDocgenTheme);
+}

package/src/partials/footer.ts

@@ -0,0 +1,4 @@
+import { JSX } from "typedoc";
+import type { GiDocgenThemeRenderContext } from "../context.ts";
+
+export const giDocgenFooter = (_context: GiDocgenThemeRenderContext) => JSX.createElement(JSX.Fragment, null);

package/src/partials/header.ts

@@ -0,0 +1,153 @@
+import type { PageEvent, Reflection } from "typedoc";
+import { JSX, ReflectionKind } from "typedoc";
+import type { GiDocgenThemeRenderContext } from "../context.ts";
+import {
+	type GirNamespaceMetadata,
+	getGirNamespaceMetadata,
+	getGirTypeFromComment,
+	girKindInfoFromTag,
+} from "../utils.ts";
+
+/** Helper: create a table row with label and value. */
+function metaRow(label: string, value: JSX.Element | string): JSX.Element {
+	return JSX.createElement(
+		"tr",
+		null,
+		JSX.createElement("td", null, JSX.createElement("em", null, label)),
+		JSX.createElement("td", null, value),
+	);
+}
+
+/** Helper: create a linked table row. */
+function metaLinkRow(label: string, url: string): JSX.Element {
+	return metaRow(label, JSX.createElement("a", { href: url, target: "_blank" }, url));
+}
+
+/** Render metadata info block for module pages, consistent with sidebar and gi-docgen style. */
+function renderModuleMetadata(
+	context: GiDocgenThemeRenderContext,
+	nsMeta: GirNamespaceMetadata,
+	packageVersion?: string,
+): JSX.Element {
+	const tableRows: JSX.Element[] = [];
+	if (nsMeta.version) tableRows.push(metaRow("API Version", nsMeta.version));
+	if (nsMeta.libraryVersion) tableRows.push(metaRow("Library Version", nsMeta.libraryVersion));
+	if (packageVersion && packageVersion !== nsMeta.libraryVersion) {
+		tableRows.push(metaRow("Package Version", packageVersion));
+	}
+
+	if (nsMeta.license) tableRows.push(metaRow("License", nsMeta.license));
+	if (nsMeta.websiteUrl) tableRows.push(metaLinkRow("Website", nsMeta.websiteUrl));
+	if (nsMeta.cDocsUrl) tableRows.push(metaLinkRow("Original Docs", nsMeta.cDocsUrl));
+
+	// Dependencies — as comma-separated links in a single table row
+	if (nsMeta.dependencies.length > 0) {
+		const depElements = nsMeta.dependencies.map((dep, i) => {
+			const depName = `${dep.namespace}-${dep.version}`;
+			const depMod = context.page.project.children?.find(
+				(c) => c.name === depName || c.name === `@girs/${depName.toLowerCase()}`,
+			);
+			const link = depMod
+				? JSX.createElement("a", { href: context.urlTo(depMod) }, `${dep.namespace} ${dep.version}`)
+				: JSX.createElement(JSX.Fragment, null, `${dep.namespace} ${dep.version}`);
+			return JSX.createElement(JSX.Fragment, null, i > 0 && ", ", link);
+		});
+		tableRows.push(metaRow("Dependencies", JSX.createElement(JSX.Fragment, null, ...depElements)));
+	}
+
+	return JSX.createElement(
+		"div",
+		{ class: "gi-docgen-module-metadata" },
+		nsMeta.description && JSX.createElement("p", { class: "gi-docgen-meta-description" }, nsMeta.description),
+		JSX.createElement("table", null, JSX.createElement("tbody", null, ...tableRows)),
+	);
+}
+
+/** Strip NPM scope prefix from a package name, e.g. "@girs/glib-2.0" → "glib-2.0". */
+function stripScope(name: string): string {
+	return name.replace(/^@[^/]+\//, "");
+}
+
+/** Render a reflection's display name (scope prefix stripped if requested). */
+function renderReflName(refl: Reflection, stripScopePrefix = false): JSX.Element {
+	let name = refl.name === "default" ? "default" : refl.name;
+	if (stripScopePrefix && name.startsWith("@")) name = stripScope(name);
+	return JSX.createElement(JSX.Fragment, null, name);
+}
+
+export const giDocgenHeader = (context: GiDocgenThemeRenderContext, props: PageEvent<Reflection>) => {
+	const isSpecialPage = props.url === "index.html" || props.url === "hierarchy.html";
+
+	let kindString = "";
+	let renderTitle = true;
+
+	const headings = context.options.getValue("headings") as { readme: boolean; document: boolean };
+
+	if (props.model.isProject()) {
+		if (props.url === "index.html" && "readme" in props.model && props.model.readme) {
+			renderTitle = headings.readme;
+		}
+	} else if (props.model.isDocument()) {
+		renderTitle = headings.document;
+	} else {
+		kindString = ReflectionKind.singularString(props.model.kind);
+	}
+
+	// Append GIR kind in parentheses, e.g. "Class (GI Struct)" or "Namespace (GI Enum)".
+	// Always shown when a @gir-type tag is present.
+	if (kindString) {
+		const girType = getGirTypeFromComment(props.model);
+		if (girType) {
+			const girInfo = girKindInfoFromTag(girType);
+			if (girInfo) {
+				kindString = `${kindString} (GI ${girInfo.label})`;
+			}
+		}
+	}
+
+	// Build full breadcrumb path (same as TypeDoc's breadcrumb: walk up until no parent, exclude root project)
+	const path: Reflection[] = [];
+	let refl: Reflection = props.model;
+	while (refl.parent) {
+		path.push(refl);
+		refl = refl.parent;
+	}
+	path.reverse(); // now [topModule, ..., currentItem]
+
+	// Show metadata info block on module pages (between header and README)
+	const isModulePage =
+		!props.model.isProject() && props.model.kindOf(ReflectionKind.Module) && !props.model.parent?.parent;
+	const nsMeta = isModulePage ? getGirNamespaceMetadata(props.model) : undefined;
+
+	return JSX.createElement(
+		"div",
+		{ class: "gi-docgen-page-title" },
+		kindString && JSX.createElement("span", { class: "gi-docgen-object-type" }, kindString),
+		renderTitle &&
+			JSX.createElement(
+				"h1",
+				null,
+				!isSpecialPage && path.length > 1
+					? path.map((r, i) => {
+							const isLast = i === path.length - 1;
+							const url = context.urlTo(r);
+							return JSX.createElement(
+								JSX.Fragment,
+								null,
+								i > 0 && JSX.createElement("span", { class: "gi-docgen-breadcrumb-sep" }, " ▶ "),
+								isLast || !url
+									? renderReflName(r, true)
+									: JSX.createElement("a", { href: url }, renderReflName(r, true)),
+							);
+						})
+					: renderReflName(props.model),
+				context.reflectionFlags(props.model),
+			),
+		nsMeta &&
+			renderModuleMetadata(
+				context,
+				nsMeta,
+				(props.model as unknown as { packageVersion?: string }).packageVersion || nsMeta.packageVersion,
+			),
+	);
+};

package/src/partials/layout.ts

@@ -0,0 +1,123 @@
+import type { PageEvent, Reflection, RenderTemplate } from "typedoc";
+import { JSX } from "typedoc";
+import type { GiDocgenThemeRenderContext } from "../context.ts";
+import { getDisplayName, getHierarchyRoots } from "../utils.ts";
+
+export const giDocgenLayout = (
+	context: GiDocgenThemeRenderContext,
+	template: RenderTemplate<PageEvent<Reflection>>,
+	props: PageEvent<Reflection>,
+) =>
+	JSX.createElement(
+		"html",
+		{ class: "default", lang: context.options.getValue("lang"), "data-base": context.relativeURL("./") },
+		JSX.createElement(
+			"head",
+			null,
+			JSX.createElement("meta", { charset: "utf-8" }),
+			context.hook("head.begin", context),
+			JSX.createElement("meta", { "http-equiv": "x-ua-compatible", content: "IE=edge" }),
+			JSX.createElement(
+				"title",
+				null,
+				props.model.isProject()
+					? getDisplayName(props.model)
+					: `${getDisplayName(props.model)} | ${getDisplayName(props.project)}`,
+			),
+			JSX.createElement("meta", { name: "description", content: `Documentation for ${props.project.name}` }),
+			JSX.createElement("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
+
+			JSX.createElement("link", {
+				rel: "icon",
+				type: "image/png",
+				href: context.relativeURL("assets/favicon-96x96.png", true),
+				sizes: "96x96",
+			}),
+			JSX.createElement("link", {
+				rel: "shortcut icon",
+				href: context.relativeURL("assets/favicon.ico", true),
+			}),
+			JSX.createElement("link", {
+				rel: "apple-touch-icon",
+				sizes: "180x180",
+				href: context.relativeURL("assets/apple-touch-icon.png", true),
+			}),
+			JSX.createElement("meta", { name: "apple-mobile-web-app-title", content: props.project.name || "TS for GIR" }),
+			JSX.createElement("link", {
+				rel: "manifest",
+				href: context.relativeURL("assets/site.webmanifest", true),
+			}),
+
+			JSX.createElement("link", { rel: "stylesheet", href: context.relativeURL("assets/style.css", true) }),
+			JSX.createElement("link", { rel: "stylesheet", href: context.relativeURL("assets/highlight.css", true) }),
+			JSX.createElement("link", { rel: "stylesheet", href: context.relativeURL("assets/gi-docgen.css", true) }),
+			context.options.getValue("customCss") &&
+				JSX.createElement("link", { rel: "stylesheet", href: context.relativeURL("assets/custom.css", true) }),
+			JSX.createElement("script", { defer: true, src: context.relativeURL("assets/main.js", true) }),
+			JSX.createElement("script", { defer: true, src: context.relativeURL("assets/gi-docgen-inherited.js", true) }),
+			context.options.getValue("customJs") &&
+				JSX.createElement("script", { defer: true, src: context.relativeURL("assets/custom.js", true) }),
+			JSX.createElement("script", {
+				async: true,
+				src: context.relativeURL("assets/icons.js", true),
+				id: "tsd-icons-script",
+			}),
+			JSX.createElement("script", {
+				async: true,
+				src: context.relativeURL("assets/search.js", true),
+				id: "tsd-search-script",
+			}),
+			JSX.createElement("script", {
+				async: true,
+				src: context.relativeURL("assets/navigation.js", true),
+				id: "tsd-nav-script",
+			}),
+			!!getHierarchyRoots(props.project).length &&
+				JSX.createElement("script", {
+					async: true,
+					src: context.relativeURL("assets/hierarchy.js", true),
+					id: "tsd-hierarchy-script",
+				}),
+			context.hook("head.end", context),
+		),
+		JSX.createElement(
+			"body",
+			null,
+			context.hook("body.begin", context),
+			JSX.createElement(
+				"script",
+				null,
+				JSX.createElement(JSX.Raw, {
+					html: 'document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";',
+				}),
+				JSX.createElement(JSX.Raw, { html: 'document.body.style.display="none";' }),
+				JSX.createElement(JSX.Raw, {
+					html: 'setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)',
+				}),
+			),
+
+			JSX.createElement(
+				"div",
+				{ id: "gi-docgen-body-wrapper" },
+				JSX.createElement("nav", { id: "gi-docgen-sidebar" }, context.sidebar(props)),
+				JSX.createElement(
+					"section",
+					{ id: "gi-docgen-main" },
+					JSX.createElement(
+						"div",
+						{ class: "gi-docgen-content" },
+						context.toolbar(props),
+						context.hook("content.begin", context),
+						context.header(props),
+						template(props),
+						context.hook("content.end", context),
+						context.footer(),
+					),
+				),
+				JSX.createElement("nav", { id: "gi-docgen-toc" }, context.pageSidebar(props)),
+			),
+
+			JSX.createElement("div", { class: "overlay" }),
+			context.hook("body.end", context),
+		),
+	);