/internal/page_builder/default_theme/mod.ts at ffebdffde1291fe4447bde991ef82a7864b97f74

// SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com>
//
// SPDX-License-Identifier: Apache-2.0

/**
 * Macana's default page builder.
 *
 * Files in this directory other than `mod.ts` are for internal use.
 * You should not use those: changes to those files are outside scope of
 * semantic versioning.
 *
 * @module
 */

import type * as Hast from "../../../deps/esm.sh/hast/types.ts";
import type * as Mdast from "../../../deps/esm.sh/mdast/types.ts";
import { headingRange } from "../../../deps/esm.sh/mdast-util-heading-range/mod.ts";
import { toHtml } from "../../../deps/esm.sh/hast-util-to-html/mod.ts";
import * as csso from "../../../deps/esm.sh/csso/mod.ts";

import { tocMut } from "../../../lib/hast_util_toc/mod.ts";
import { deleteId } from "../../../lib/mdast_util_delete_id/mod.ts";

import { logger } from "../../logger.ts";

import type { BuildParameters, PageBuilder } from "../interface.ts";
import {
	type ObsidianMarkdownDocument,
} from "../../content_parser/obsidian_markdown.ts";
import type { JSONCanvasDocument } from "../../content_parser/json_canvas.ts";
import * as jsonCanvas from "../../content_parser/json_canvas/utils.ts";
import type { FileSystemWriter } from "../../filesystem_writer/interface.ts";
import type {
	AssetToken,
	Document,
	DocumentDirectory,
	DocumentToken,
	DocumentTree,
	RootDirectoryReader,
} from "../../types.ts";

import * as css from "./css.ts";
import { globalStyles } from "./global_styles.ts";
import type { Assets, DocumentBuildContext } from "./context.ts";

import {
	fromMdast,
	fromMdastStyles,
	style as styleMarkdownContent,
} from "./from_mdast/mod.ts";
import {
	jsonCanvas as jsonCanvasRenderer,
	jsonCanvasStyles as jsonCanvasRendererStyles,
} from "./json_canvas/mod.tsx";
import { indexRedirect } from "./pages/index_redirect.tsx";
import { markdownPage, markdownPageStyles } from "./pages/markdown.tsx";
import { notFoundPage, notFoundPageStyles } from "./pages/not_found.tsx";
import { jsonCanvasPage, jsonCanvasPageStyles } from "./pages/json_canvas.tsx";
import { thirdPartyNoticeTxt } from "./pages/third_party_notice.ts";

export type { BuildContext } from "./context.ts";

function isAssetToken(token: unknown): token is AssetToken {
	return typeof token === "string" && token.startsWith("mxa_");
}

function isDocumentToken(token: unknown): token is DocumentToken {
	return typeof token === "string" && token.startsWith("mxt_");
}

function isObsidianMarkdown(
	x: Document,
): x is Document<ObsidianMarkdownDocument> {
	return x.content.kind === "obsidian_markdown";
}

function isJSONCanvas(
	x: Document,
): x is Document<JSONCanvasDocument<Mdast.Nodes>> {
	return x.content.kind === "json_canvas";
}

interface InnerBuildParameters {
	item: DocumentDirectory | Document;

	tree: DocumentTree;

	parentLanguage: string;

	pathPrefix?: readonly string[];

	buildParameters: Omit<BuildParameters, "documentTree">;

	assets: Assets;
}

export interface DefaultThemeBuilderConstructorParameters {
	/**
	 * Website's name, title.
	 *
	 * The default theme display this text inside <title> tag.
	 */
	siteName: string;

	/**
	 * Copyright text to display at website footer.
	 * The page buidler does not add/subtract to the text: do not forget to
	 * include "Copyright" or "©".
	 */
	copyright: string;

	/**
	 * Path to the SVG file to use as a favicon from the root directory (FileSystem Reader).
	 */
	faviconSvg?: readonly string[] | Uint8Array;

	/**
	 * Path to the PNG file to use as a favicon from the root directory (FileSystem Reader).
	 */
	faviconPng?: readonly string[] | Uint8Array;

	/**
	 * Path to the website's logo or icon image from the root directory (FileSystem Reader).
	 */
	siteLogo?: readonly string[] | {
		ext: string;
		binary: Uint8Array;
	};

	/**
	 * Path to the user provided CSS file.
	 */
	userCSS?: readonly string[];

	/**
	 * URL or path to base at.
	 */
	baseURL?: URL | string;

	openGraph?: {
		image: {
			ext: string;
			data: Uint8Array;
		};
	};

	notFoundPage?: {
		filename: string;
	};

	additionalNoticeFiles?: readonly (readonly string[])[];
}

/**
 * Macana's default page builder.
 *
 * This takes a document tree generated by Tree Builder then writes converted
 * HTML using FileSystem Writer. It would also read non-document files using
 * FileSystem Reader.
 */
export class DefaultThemeBuilder implements PageBuilder {
	#copyright: string;
	#faviconSvg?: readonly string[] | Uint8Array;
	#faviconPng?: readonly string[] | Uint8Array;
	#siteLogo?: readonly string[] | {
		ext: string;
		binary: Uint8Array;
	};
	#siteName: string;
	#baseURL?: URL | string;
	#openGraph: DefaultThemeBuilderConstructorParameters["openGraph"];
	#userCSS?: readonly string[];
	#notFoundPage: DefaultThemeBuilderConstructorParameters["notFoundPage"];
	#additionalNoticeFiles: readonly (readonly string[])[];

	constructor(
		{
			copyright,
			faviconSvg,
			faviconPng,
			siteLogo,
			siteName,
			baseURL,
			openGraph,
			userCSS,
			notFoundPage,
			additionalNoticeFiles,
		}: DefaultThemeBuilderConstructorParameters,
	) {
		this.#copyright = copyright;
		this.#faviconPng = faviconPng;
		this.#faviconSvg = faviconSvg;
		this.#siteLogo = siteLogo;
		this.#siteName = siteName;
		this.#baseURL = baseURL;
		this.#openGraph = openGraph;
		this.#userCSS = userCSS;
		this.#notFoundPage = notFoundPage;
		this.#additionalNoticeFiles = additionalNoticeFiles ?? [];
	}

	async build(
		{ documentTree, fileSystemReader, fileSystemWriter }: BuildParameters,
	) {
		const start = performance.now();

		const root = await fileSystemReader.getRootDirectory();

		const baseStyles = css.join(
			globalStyles,
			fromMdastStyles,
			markdownPageStyles,
			jsonCanvasPageStyles,
			jsonCanvasRendererStyles,
			notFoundPageStyles,
		);

		const userCss = await this.#loadUserCSSAndCopyAssets(
			root,
			fileSystemWriter,
		);

		const styles = css.serialize(
			userCss ? css.join(baseStyles, userCss) : baseStyles,
		);

		const minCss = csso.minify(styles);

		const assets: Assets = {
			globalCss: ["_assets", "global.css"],
			thirdPartyNotices: ["third-party-notices.txt"],
		};

		await fileSystemWriter.write(
			assets.globalCss,
			new TextEncoder().encode(minCss.css),
		);

		if (this.#faviconSvg) {
			if (this.#faviconSvg instanceof Uint8Array) {
				assets.faviconSvg = ["_assets", "favicon.svg"];
				await fileSystemWriter.write(
					assets.faviconSvg,
					this.#faviconSvg,
				);
			} else {
				assets.faviconSvg = this.#faviconSvg;
				await fileSystemWriter.write(
					assets.faviconSvg,
					await (await root.openFile(this.#faviconSvg)).read(),
				);
			}
		}

		if (this.#faviconPng) {
			if (this.#faviconPng instanceof Uint8Array) {
				assets.faviconPng = ["_assets", "favicon.png"];
				await fileSystemWriter.write(
					assets.faviconPng,
					this.#faviconPng,
				);
			} else {
				assets.faviconPng = this.#faviconPng;
				await fileSystemWriter.write(
					assets.faviconPng,
					await (await root.openFile(this.#faviconPng)).read(),
				);
			}
		}

		if (this.#siteLogo) {
			if (this.#siteLogo instanceof Array) {
				assets.siteLogo = this.#siteLogo;
				await fileSystemWriter.write(
					assets.siteLogo,
					await (await root.openFile(this.#siteLogo)).read(),
				);
			} else {
				assets.siteLogo = ["_assets", `logo${this.#siteLogo.ext}`];
				await fileSystemWriter.write(
					assets.siteLogo,
					this.#siteLogo.binary,
				);
			}
		}

		const baseURL = this.#baseURL &&
			new URL(this.#baseURL, "macana://placeholder");
		const isOpenGraphReady = baseURL && baseURL.protocol !== "macana:";

		if (isOpenGraphReady && this.#openGraph) {
			assets.openGraphImage = [
				"_assets",
				`opengraph${this.#openGraph.image.ext}`,
			];
			await fileSystemWriter.write(
				assets.openGraphImage,
				this.#openGraph.image.data,
			);
		}

		const textEncoder = new TextEncoder();

		const defaultPage = this.#resolveURL([
			...documentTree.defaultDocument.path,
			"",
		], []);
		const redirectHtml = toHtml(indexRedirect({ redirectTo: defaultPage }));
		await fileSystemWriter.write(
			["index.html"],
			textEncoder.encode(redirectHtml),
		);

		const additionalNotices = await Promise.all(
			this.#additionalNoticeFiles.map(async (path) => {
				const file = await root.openFile(path);

				return new TextDecoder().decode(await file.read());
			}),
		);

		await fileSystemWriter.write(
			assets.thirdPartyNotices,
			textEncoder.encode(thirdPartyNoticeTxt(additionalNotices)),
		);

		if (this.#notFoundPage) {
			if (this.#baseURL) {
				const resolveURL = this.#resolveURL;

				const writeTasks: Promise<unknown>[] = [];

				const html = toHtml(
					notFoundPage({
						context: {
							documentTree,
							language: documentTree.defaultLanguage,
							assets,
							websiteTitle: this.#siteName,
							copyright: this.#copyright,
							resolveURL(to) {
								return resolveURL(to, []);
							},
							copyFile(file) {
								writeTasks.push(
									file.read().then((bytes) => {
										fileSystemWriter.write(file.path, bytes);
									}),
								);
							},
							writeFile(path, contents) {
								writeTasks.push(
									fileSystemWriter.write(path, contents),
								);
							},
						},
					}),
				);

				await Promise.all(writeTasks);

				await fileSystemWriter.write(
					[this.#notFoundPage.filename],
					textEncoder.encode(html),
				);
			} else {
				logger().warn(
					"Skipping Not Found page generation due to base URL not specified",
					{
						filename: this.#notFoundPage.filename,
					},
				);
			}
		}

		await Promise.all(documentTree.nodes.map((item) =>
			this.#build({
				item,
				tree: documentTree,
				parentLanguage: documentTree.defaultLanguage,
				pathPrefix: [],
				buildParameters: { fileSystemWriter, fileSystemReader },
				assets,
			})
		));

		const duration = performance.now() - start;
		logger().info(`Built with default theme in ${duration}ms`, {
			duration,
		});
	}

	#buildEmbed(
		context: DocumentBuildContext,
		target: Document,
		fragments: readonly string[] = [],
	): Hast.Nodes {
		if (isJSONCanvas(target)) {
			if (fragments.length > 0) {
				logger().warn(
					"JSONCanvas embeds does not support partial embed using hash",
					{
						embedder: context.document.path.join(" > "),
						target: target.path.join(" > "),
						fragments,
					},
				);
			}

			const content = jsonCanvas.mapNode(
				target.content.content,
				(node) => {
					switch (node.type) {
						case "text": {
							const nodes = structuredClone(node.text);

							deleteId(nodes);

							return {
								...node,
								text: fromMdast(nodes, {
									context,
									buildDocumentContent: (document, fragments) => {
										return this.#buildEmbed(
											context,
											document,
											fragments,
										);
									},
								}),
							};
						}
						case "file": {
							if (isAssetToken(node.file)) {
								const file = context.documentTree.exchangeToken(node.file);

								context.copyFile(file);

								return {
									...node,
									file: context.resolveURL(file.path),
								};
							}

							if (isDocumentToken(node.file)) {
								const { document, fragments } = context.documentTree
									.exchangeToken(
										node.file,
										target,
									);

								return {
									...node,
									type: "text",
									text: this.#buildEmbed(
										context,
										document,
										fragments,
									),
								};
							}

							return node;
						}
						default: {
							return node;
						}
					}
				},
			);

			return jsonCanvasRenderer({
				data: content,
			});
		}

		if (isObsidianMarkdown(target)) {
			let nodes: Mdast.Nodes = structuredClone(target.content.content);

			if (fragments.length > 0) {
				const id = target.content.getHash(fragments);

				headingRange(
					nodes as Mdast.Root,
					id,
					(start, content) => {
						nodes = {
							type: "root",
							children: [
								start,
								...content,
							],
						};
					},
				);
			}

			deleteId(nodes);

			return fromMdast(nodes, {
				context,
				buildDocumentContent: (document, fragments) => {
					return this.#buildEmbed(context, document, fragments);
				},
			});
		}

		throw new Error(
			`Can't embed document "${
				target.path.join("/")
			}": unknown content kind (${target.content.kind})`,
		);
	}

	async #build(
		{ item, tree, parentLanguage, pathPrefix = [], buildParameters, assets }:
			InnerBuildParameters,
	): Promise<void> {
		const resolveURL = this.#resolveURL;

		const { fileSystemWriter } = buildParameters;

		if ("file" in item) {
			const writeTasks: Promise<unknown>[] = [];

			const context: DocumentBuildContext = {
				document: item,
				documentTree: tree,
				language: item.metadata.language || parentLanguage,
				assets,
				websiteTitle: this.#siteName,
				copyright: this.#copyright,
				resolveURL(to) {
					return resolveURL(to, item.path);
				},
				copyFile(file) {
					writeTasks.push(
						file.read().then((bytes) => {
							fileSystemWriter.write(file.path, bytes);
						}),
					);
				},
				writeFile(path, contents) {
					writeTasks.push(
						fileSystemWriter.write(path, contents),
					);
				},
			};

			if (isObsidianMarkdown(item) || isJSONCanvas(item)) {
				const enc = new TextEncoder();

				const basePath = [
					...pathPrefix,
					item.metadata.name,
				];

				switch (item.content.kind) {
					case "json_canvas": {
						const content = jsonCanvas.mapNode(
							item.content.content,
							(node) => {
								switch (node.type) {
									case "text": {
										return {
											...node,
											text: fromMdast(node.text, {
												context,
												buildDocumentContent: (document, fragments) => {
													return this.#buildEmbed(
														context,
														document,
														fragments,
													);
												},
											}),
										};
									}
									case "file": {
										if (isAssetToken(node.file)) {
											const file = tree.exchangeToken(node.file);

											writeTasks.push(
												file.read().then((bytes) =>
													fileSystemWriter.write(file.path, bytes)
												),
											);

											return {
												...node,
												file: context.resolveURL(file.path),
											};
										}

										if (isDocumentToken(node.file)) {
											const { document, fragments } = tree.exchangeToken(
												node.file,
												item,
											);

											return {
												...node,
												type: "text",
												text: this.#buildEmbed(context, document, fragments),
											};
										}

										return node;
									}
									default: {
										return node;
									}
								}
							},
						);

						const html = toHtml(
							jsonCanvasPage({
								content,
								context,
							}),
						);

						writeTasks.push(
							fileSystemWriter.write([
								...basePath,
								"index.html",
							], enc.encode(html)),
						);

						await Promise.all(writeTasks);
						return;
					}
					case "obsidian_markdown": {
						const hast = fromMdast(item.content.content, {
							context,
							buildDocumentContent: (document, fragments) => {
								return this.#buildEmbed(
									context,
									document,
									fragments,
								);
							},
						});
						const toc = tocMut(hast);

						const html = toHtml(
							markdownPage({
								context,
								content: styleMarkdownContent(hast),
								tocItems: toc,
							}),
						);

						writeTasks.push(
							fileSystemWriter.write([
								...basePath,
								"index.html",
							], enc.encode(html)),
						);

						await Promise.all(writeTasks);
						return;
					}
				}
			}

			throw new Error(`Unsupported content type: ${item.content.kind}`);
		}

		await Promise.all(item.entries.map((entry) =>
			this.#build({
				item: entry,
				tree,
				parentLanguage: item.metadata.language || parentLanguage,
				pathPrefix: [...pathPrefix, item.metadata.name],
				buildParameters,
				assets,
			})
		));
	}

	#loadUserCSSAndCopyAssets = async (
		root: RootDirectoryReader,
		writer: FileSystemWriter,
	): Promise<css.Css | null> => {
		if (!this.#userCSS) {
			return null;
		}

		const userCSS = this.#userCSS;

		const file = await root.openFile(userCSS);
		const code = new TextDecoder().decode(await file.read());

		const assets = css.getAssets(code);

		const convertPath = (from: string) => {
			return [
				...userCSS.slice(0, -1),
				...from.split("/").filter((segment) => segment !== "."),
			];
		};

		for (const asset of assets.paths) {
			const path = convertPath(asset);

			await writer.write(
				path,
				await (await root.openFile(path)).read(),
			);
		}

		return css.fromString(
			assets.replace((path) =>
				this.#resolveURL(convertPath(path), ["_assets"])
			),
		);
	};

	#resolveURL = (to: readonly string[], from: readonly string[]): string => {
		if (!this.#baseURL) {
			return [
				...Array.from({ length: from.length }, () => ".."),
				...to,
			].join("/");
		}

		if (this.#baseURL instanceof URL) {
			return new URL(to.join("/"), this.#baseURL).toString();
		}

		const url = new URL(
			to.join("/"),
			new URL(this.#baseURL, "macana://placeholder"),
		);
		if (url.protocol === "macana:") {
			return url.pathname;
		}

		return url.toString();
	};
}