@octanejs/docusaurus 0.0.2 → 0.0.4

package/src/theme-components.tsrx

@@ -0,0 +1,462 @@
+import { createContext, useContext, type ComponentBody, type OctaneNode } from 'octane';
+import { Link as RouterLink, type Location } from '@octanejs/remix-router';
+import { Head, Seo } from '@octanejs/seo';
+import { useDocusaurusManifest } from './client-components.tsrx';
+
+type NavigationItem = {
+	label: string;
+	href?: string;
+	to?: string;
+	position?: 'left' | 'right';
+};
+
+type NavbarConfig = {
+	title?: string;
+	logo?: {
+		alt?: string;
+		href?: string;
+		src: string;
+	};
+	items?: NavigationItem[];
+};
+
+type FooterItem = {
+	label: string;
+	href?: string;
+	to?: string;
+};
+
+type FooterConfig = {
+	copyright?: string;
+	links?: Array<{
+		title: string;
+		items: FooterItem[];
+	}>;
+};
+
+type ClassicThemeConfig = {
+	navbar?: NavbarConfig;
+	footer?: FooterConfig;
+};
+
+type SidebarItem = {
+	type: string;
+	label: string;
+	href?: string;
+	key?: string;
+	items?: SidebarItem[];
+};
+
+type DocLink = {
+	title: string;
+	permalink: string;
+	description?: string;
+};
+
+type DocsVersion = {
+	label: string;
+	noIndex?: boolean;
+	docsSidebars: Record<string, SidebarItem[]>;
+};
+
+type DocMetadata = {
+	title?: string;
+	description?: string;
+	permalink?: string;
+	previous?: DocLink;
+	next?: DocLink;
+};
+
+type DocContent =
+	ComponentBody<Record<string, unknown>> & {
+		contentTitle?: string;
+		frontMatter?: {
+			title?: string;
+			description?: string;
+			noIndex?: boolean;
+		};
+		metadata?: DocMetadata;
+	};
+
+type RouteProps = {
+	attributes?: Record<string, unknown>;
+	routes?: RouteProps[];
+	path?: string;
+};
+
+const VersionContext = createContext<DocsVersion | null>(null);
+
+function isExternal(href: string): boolean {
+	return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href);
+}
+
+function resolvedHref(item: { href?: string; to?: string }): string | null {
+	return item.to ?? item.href ?? null;
+}
+
+function withBaseUrl(baseUrl: string, href: string): string {
+	if (href === '' || isExternal(href) || href.startsWith('#')) return href;
+	if (href === baseUrl.replace(/\/$/, '')) return baseUrl;
+	if (href.startsWith(baseUrl)) return href;
+	return `${baseUrl}${href.replace(/^(?:\.\/|\/)/, '')}`;
+}
+
+function absoluteUrl(siteUrl: string, href: string): string {
+	try {
+		return new URL(href, siteUrl).href;
+	} catch {
+		return href;
+	}
+}
+
+function sidebarKey(item: SidebarItem): string {
+	return item.key ?? item.href ?? `${item.type}:${item.label}`;
+}
+
+function navigationKey(item: NavigationItem | FooterItem): string {
+	return resolvedHref(item) ?? item.label;
+}
+
+function findSidebarCategory(items: SidebarItem[], href: string): SidebarItem | null {
+	for (const item of items) {
+		if (item.type !== 'category') continue;
+		if (item.href === href) return item;
+		const nested = findSidebarCategory(item.items ?? [], href);
+		if (nested !== null) return nested;
+	}
+	return null;
+}
+
+function categoryItems(version: DocsVersion, href: string): DocLink[] {
+	for (const sidebar of Object.values(version.docsSidebars)) {
+		const category = findSidebarCategory(sidebar, href);
+		if (category === null) continue;
+		return (category.items ?? []).flatMap(
+			(item) => item.href === undefined
+				? []
+				: [
+						{
+							title: item.label,
+							permalink: item.href,
+						},
+					],
+		);
+	}
+	return [];
+}
+
+function useDocsVersion(): DocsVersion {
+	const version = useContext(VersionContext);
+	if (version === null) {
+		throw new Error('[@octanejs/docusaurus] The classic DocRoot requires DocVersionRoot.');
+	}
+	return version;
+}
+
+function ThemeLink(props: {
+	href: string;
+	class?: string;
+	'aria-current'?: 'page';
+	children?: OctaneNode;
+}) @{
+	@if (isExternal(props.href)) {
+		<a
+			href={props.href}
+			class={props.class}
+			aria-current={props['aria-current']}
+		>{props.children}</a>
+	} @else {
+		<RouterLink
+			to={props.href}
+			class={props.class}
+			aria-current={props['aria-current']}
+		>{props.children}</RouterLink>
+	}
+}
+
+function Navbar(props: { config?: NavbarConfig }) @{
+	const manifest = useDocusaurusManifest();
+	const title = props.config?.title ?? manifest.site.title;
+	const brandHref = withBaseUrl(manifest.baseUrl, props.config?.logo?.href ?? manifest.baseUrl);
+	const items = props.config?.items ?? [];
+
+	<header class="octane-docs-navbar">
+		<ThemeLink href={brandHref} class="octane-docs-navbar__brand">
+			@if (props.config?.logo !== undefined) {
+				<img
+					src={withBaseUrl(manifest.baseUrl, props.config.logo.src)}
+					alt={props.config.logo.alt ?? title}
+				/>
+			}
+			<span>{title}</span>
+		</ThemeLink>
+		@if (items.length > 0) {
+			<nav aria-label="Primary">
+				<ul class="octane-docs-navbar__items">
+					@for (const item of items; key navigationKey(item)) {
+						@if (resolvedHref(item) !== null) {
+							<li>
+								<ThemeLink
+									href={withBaseUrl(manifest.baseUrl, resolvedHref(item)!)}
+								>{item.label}</ThemeLink>
+							</li>
+						}
+					}
+				</ul>
+			</nav>
+		}
+	</header>
+}
+
+function Footer(props: { baseUrl: string; config?: FooterConfig }) @{
+	const groups = props.config?.links ?? [];
+	// Docusaurus treats the developer-provided copyright as trusted site HTML.
+	const copyright = props.config?.copyright;
+
+	@if (groups.length > 0 || copyright !== undefined) {
+		<footer class="octane-docs-footer">
+			@if (groups.length > 0) {
+				<ul class="octane-docs-footer__links">
+					@for (const group of groups; key group.title) {
+						<li>
+							<strong>{group.title}</strong>
+							<ul class="octane-docs-footer__items">
+								@for (const item of group.items; key navigationKey(item)) {
+									@if (resolvedHref(item) !== null) {
+										<li>
+											<ThemeLink
+												href={withBaseUrl(props.baseUrl, resolvedHref(item)!)}
+											>{item.label}</ThemeLink>
+										</li>
+									}
+								}
+							</ul>
+						</li>
+					}
+				</ul>
+			}
+			@if (copyright !== undefined) {
+				<div
+					class="octane-docs-footer__copyright"
+					dangerouslySetInnerHTML={{ __html: copyright }}
+				/>
+			}
+		</footer>
+	}
+}
+
+function SidebarItems(props: { items: SidebarItem[]; pathname: string }) @{
+	<ul>
+		@for (const item of props.items; key sidebarKey(item)) {
+			<li>
+				@if (item.type === 'category' && item.items !== undefined) {
+					<>
+						@if (item.href !== undefined) {
+							<ThemeLink
+								href={item.href}
+								class="octane-docs-sidebar__category"
+								aria-current={item.href === props.pathname ? 'page' : undefined}
+							>{item.label}</ThemeLink>
+						} @else {
+							<span class="octane-docs-sidebar__category">{item.label}</span>
+						}
+						<SidebarItems items={item.items} pathname={props.pathname} />
+					</>
+				} @else if (item.href !== undefined) {
+					<ThemeLink
+						href={item.href}
+						aria-current={item.href === props.pathname ? 'page' : undefined}
+					>{item.label}</ThemeLink>
+				} @else {
+					<span>{item.label}</span>
+				}
+			</li>
+		}
+	</ul>
+}
+
+function PageMetadata(props: {
+	title?: string;
+	description?: string;
+	permalink?: string;
+	noIndex?: boolean;
+}) @{
+	const manifest = useDocusaurusManifest();
+	const title =
+		props.title === undefined || props.title === manifest.site.title
+			? manifest.site.title
+			: `${props.title} | ${manifest.site.title}`;
+
+	<Head>
+		<Seo
+			title={title}
+			description={props.description}
+			canonical={props.permalink === undefined
+				? undefined
+				: absoluteUrl(manifest.site.url, props.permalink)}
+			openGraph={{ title, description: props.description }}
+			robots={props.noIndex === true ? { index: false, follow: false } : undefined}
+		/>
+	</Head>
+}
+
+function Paginator(props: { previous?: DocLink; next?: DocLink }) @{
+	@if (props.previous !== undefined || props.next !== undefined) {
+		<nav class="octane-docs-paginator" aria-label="Documentation pages">
+			<div>
+				@if (props.previous !== undefined) {
+					<ThemeLink href={props.previous.permalink}>← {props.previous.title}</ThemeLink>
+				}
+			</div>
+			<div class="octane-docs-paginator__next">
+				@if (props.next !== undefined) {
+					<ThemeLink href={props.next.permalink}>{props.next.title} →</ThemeLink>
+				}
+			</div>
+		</nav>
+	}
+}
+
+function CardList(props: { items: DocLink[] }) @{
+	<ul class="octane-docs-card-list">
+		@for (const item of props.items; key item.permalink) {
+			<li class="octane-docs-card">
+				<ThemeLink href={item.permalink}>{item.title}</ThemeLink>
+				@if (item.description !== undefined) {
+					<p>{item.description}</p>
+				}
+			</li>
+		}
+	</ul>
+}
+
+export function Root(props: { children?: OctaneNode }) @{
+	<>
+		{props.children}
+	</>
+}
+
+export function DocsRoot(props: { children?: OctaneNode }) @{
+	const manifest = useDocusaurusManifest();
+	const themeConfig = manifest.site.themeConfig as ClassicThemeConfig;
+
+	<div class="octane-docusaurus">
+		<Navbar config={themeConfig.navbar} />
+		{props.children}
+		<Footer baseUrl={manifest.baseUrl} config={themeConfig.footer} />
+	</div>
+}
+
+export function DocVersionRoot(props: { children?: OctaneNode; version: DocsVersion }) @{
+	<VersionContext.Provider value={props.version}>{props.children}</VersionContext.Provider>
+}
+
+export function DocRoot(props: {
+	children?: OctaneNode;
+	location: Location;
+	route: RouteProps;
+}) @{
+	const version = useDocsVersion();
+	const activeRoute = props.route.routes?.find((route) => route.path === props.location.pathname);
+	const sidebarId = activeRoute?.attributes?.sidebar;
+	const sidebar =
+		typeof sidebarId === 'string' ? version.docsSidebars[sidebarId] ?? [] : [];
+
+	<div class="octane-docs-layout">
+		@if (sidebar.length > 0) {
+			<aside class="octane-docs-sidebar" aria-label="Documentation sidebar">
+				<SidebarItems items={sidebar} pathname={props.location.pathname} />
+			</aside>
+		}
+		<main class="octane-docs-main">{props.children}</main>
+	</div>
+}
+
+export function DocItem(props: { content: DocContent }) @{
+	const manifest = useDocusaurusManifest();
+	const version = useDocsVersion();
+	const Content = props.content;
+	const metadata = Content.metadata ?? {};
+	const frontMatter = Content.frontMatter ?? {};
+	const title = frontMatter.title ?? metadata.title ?? Content.contentTitle;
+	const description = frontMatter.description ?? metadata.description;
+
+	<>
+		<PageMetadata
+			title={title}
+			description={description}
+			permalink={metadata.permalink}
+			noIndex={frontMatter.noIndex === true || version.noIndex === true || manifest.site.noIndex}
+		/>
+		<article class="octane-docs-article">
+			<Content />
+			<Paginator previous={metadata.previous} next={metadata.next} />
+		</article>
+	</>
+}
+
+export function DocCategoryGeneratedIndexPage(props: {
+	categoryGeneratedIndex: {
+		title: string;
+		description?: string;
+		permalink: string;
+		navigation?: {
+			previous?: DocLink;
+			next?: DocLink;
+		};
+	};
+}) @{
+	const version = useDocsVersion();
+	const page = props.categoryGeneratedIndex;
+	const items = categoryItems(version, page.permalink);
+	<div class="octane-docs-list-page">
+		<PageMetadata
+			title={page.title}
+			description={page.description}
+			permalink={page.permalink}
+			noIndex={version.noIndex}
+		/>
+		<h1>{page.title}</h1>
+		@if (page.description !== undefined) {
+			<p>{page.description}</p>
+		}
+		<CardList items={items} />
+		<Paginator previous={page.navigation?.previous} next={page.navigation?.next} />
+	</div>
+}
+
+export function DocTagsListPage(props: {
+	tags: Array<{ label: string; permalink: string; description?: string }>;
+	location: Location;
+}) @{
+	const version = useDocsVersion();
+	<div class="octane-docs-list-page">
+		<PageMetadata title="Tags" permalink={props.location.pathname} noIndex={version.noIndex} />
+		<h1>Tags</h1>
+		<CardList items={props.tags.map((tag) => ({ ...tag, title: tag.label }))} />
+	</div>
+}
+
+export function DocTagDocListPage(props: {
+	tag: {
+		label: string;
+		description?: string;
+		permalink: string;
+		items: DocLink[];
+	};
+}) @{
+	const version = useDocsVersion();
+	<div class="octane-docs-list-page">
+		<PageMetadata
+			title={props.tag.label}
+			description={props.tag.description}
+			permalink={props.tag.permalink}
+			noIndex={version.noIndex}
+		/>
+		<h1>{props.tag.label}</h1>
+		@if (props.tag.description !== undefined) {
+			<p>{props.tag.description}</p>
+		}
+		<CardList items={props.tag.items} />
+	</div>
+}

package/src/theme.js

@@ -0,0 +1,25 @@
+import { fileURLToPath } from 'node:url';
+
+const THEME_PATH = fileURLToPath(new URL('./theme', import.meta.url));
+const STYLES_PATH = fileURLToPath(new URL('./theme/styles.css', import.meta.url));
+
+/**
+ * Docusaurus theme plugin exposing Octane-authored docs route components.
+ *
+ * Add this function to `themes` in `docusaurus.config.*`. Docusaurus remains
+ * responsible for content/plugin loading; the Octane Vite bridge resolves the
+ * returned theme modules and imports the client stylesheet.
+ */
+export default function octaneClassicTheme() {
+	return {
+		name: '@octanejs/docusaurus-theme-classic',
+		getThemePath() {
+			return THEME_PATH;
+		},
+		getClientModules() {
+			return [STYLES_PATH];
+		},
+	};
+}
+
+export { octaneClassicTheme };

package/src/vite.js

@@ -3,9 +3,12 @@ import { createOctaneCompiler } from 'octane/compiler/bundler';
 import { compileDocusaurusMdx } from './mdx.js';
 import { loadDocusaurusSite } from './load-site.js';
 import { createDocusaurusManifest, resolveDocusaurusId } from './manifest.js';
+import { collectDocusaurusRouteModuleReferences } from './route-modules.js';
 
 export const DOCUSAURUS_MANIFEST_ID = 'virtual:octane-docusaurus-manifest';
+export const DOCUSAURUS_ROUTES_ID = 'virtual:octane-docusaurus-routes';
 const RESOLVED_DOCUSAURUS_MANIFEST_ID = `\0${DOCUSAURUS_MANIFEST_ID}`;
+const RESOLVED_DOCUSAURUS_ROUTES_ID = `\0${DOCUSAURUS_ROUTES_ID}`;
 
 function cleanId(id) {
 	return id.split(/[?#]/, 1)[0];
@@ -27,6 +30,27 @@ function serializableManifest(manifest) {
 		.replace(/</g, '\\u003c');
 }
 
+function clientRoutesModule(manifest) {
+	const clientModules = manifest.assets.clientModules
+		.map((specifier) => `import ${JSON.stringify(specifier)};\n`)
+		.join('');
+	const importers = [...collectDocusaurusRouteModuleReferences(manifest.routes)]
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(
+			([key, specifier]) => `\t${JSON.stringify(key)}: () => import(${JSON.stringify(specifier)}),`,
+		)
+		.join('\n');
+	return `${clientModules}import { createDocusaurusRoutes } from "@octanejs/docusaurus/client";
+import manifest from ${JSON.stringify(DOCUSAURUS_MANIFEST_ID)};
+
+export { manifest };
+export const routeModules = {
+${importers}
+};
+export const routes = createDocusaurusRoutes(manifest, routeModules);
+`;
+}
+
 function createSharedState(options) {
 	let loaded;
 	let manifest;
@@ -76,6 +100,17 @@ function createSharedState(options) {
 }
 
 export function docusaurusBridge(options = {}, shared = createSharedState(options)) {
+	let server;
+
+	function invalidateVirtualModules() {
+		if (server === undefined) return;
+		for (const id of [RESOLVED_DOCUSAURUS_MANIFEST_ID, RESOLVED_DOCUSAURUS_ROUTES_ID]) {
+			const module = server.moduleGraph.getModuleById(id);
+			if (module !== undefined) server.moduleGraph.invalidateModule(module);
+		}
+		server.ws.send({ type: 'full-reload' });
+	}
+
 	return {
 		name: 'octane-docusaurus-bridge',
 		enforce: 'pre',
@@ -83,6 +118,9 @@ export function docusaurusBridge(options = {}, shared = createSharedState(option
 			getManifest: () => shared.getManifest(),
 			reload: () => shared.refresh(),
 		},
+		configureServer(value) {
+			server = value;
+		},
 		async configResolved(config) {
 			shared.setRoot(config.root ?? process.cwd());
 			await shared.refresh();
@@ -102,18 +140,28 @@ export function docusaurusBridge(options = {}, shared = createSharedState(option
 				const resolved = path.isAbsolute(source) ? source : resolveDocusaurusId(source, manifest);
 				if (resolved !== null) this.addWatchFile?.(cleanId(resolved));
 			}
+			for (const clientModule of manifest.assets.clientModules) {
+				this.addWatchFile?.(cleanId(clientModule));
+			}
 		},
 		async watchChange() {
 			await shared.refresh();
+			invalidateVirtualModules();
 		},
 		async resolveId(id) {
 			if (id === DOCUSAURUS_MANIFEST_ID) return RESOLVED_DOCUSAURUS_MANIFEST_ID;
+			if (id === DOCUSAURUS_ROUTES_ID) return RESOLVED_DOCUSAURUS_ROUTES_ID;
 			const manifest = await shared.getManifest();
 			return resolveDocusaurusId(id, manifest);
 		},
 		async load(id) {
-			if (id !== RESOLVED_DOCUSAURUS_MANIFEST_ID) return null;
-			return `export default ${serializableManifest(await shared.getManifest())};\n`;
+			if (id === RESOLVED_DOCUSAURUS_MANIFEST_ID) {
+				return `export default ${serializableManifest(await shared.getManifest())};\n`;
+			}
+			if (id === RESOLVED_DOCUSAURUS_ROUTES_ID) {
+				return clientRoutesModule(await shared.getManifest());
+			}
+			return null;
 		},
 	};
 }

package/types/client.d.ts

@@ -0,0 +1,58 @@
+/// <reference path="./virtual.d.ts" />
+
+import type { ComponentBody, OctaneNode } from 'octane';
+import type {
+	DOMRouterOpts,
+	DataRouter,
+	Location,
+	MemoryRouterOpts,
+	NavigateFunction,
+	RouteObject,
+} from '@octanejs/remix-router';
+import type {
+	DocusaurusManifest,
+	DocusaurusManifestRoute,
+	DocusaurusPluginIdentifier,
+} from './index.js';
+
+export type DocusaurusRouteModuleNamespace = Record<string, unknown>;
+export type DocusaurusRouteModuleImporter = () => Promise<DocusaurusRouteModuleNamespace>;
+export type DocusaurusRouteModuleRegistry = Record<string, DocusaurusRouteModuleImporter>;
+
+export interface DocusaurusRouteContext {
+	plugin: DocusaurusPluginIdentifier;
+	data: Record<string, unknown>;
+}
+
+export interface DocusaurusRouteComponentProps extends Record<string, unknown> {
+	route: DocusaurusManifestRoute & { routes: DocusaurusManifestRoute[] };
+	location: Location;
+	params: Readonly<Record<string, string | undefined>>;
+	navigate: NavigateFunction;
+	children?: OctaneNode;
+}
+
+export declare function createDocusaurusRoutes(
+	manifest: DocusaurusManifest,
+	registry: DocusaurusRouteModuleRegistry,
+): RouteObject[];
+
+export declare function createDocusaurusBrowserRouter(
+	manifest: DocusaurusManifest,
+	registry: DocusaurusRouteModuleRegistry,
+	options?: DOMRouterOpts,
+): DataRouter;
+
+export declare function createDocusaurusMemoryRouter(
+	manifest: DocusaurusManifest,
+	registry: DocusaurusRouteModuleRegistry,
+	options?: MemoryRouterOpts,
+): DataRouter;
+
+export declare const DocusaurusRouterProvider: ComponentBody<{
+	manifest: DocusaurusManifest;
+	router: DataRouter;
+}>;
+
+export declare function useDocusaurusManifest(): DocusaurusManifest;
+export declare function useDocusaurusRouteContext(): DocusaurusRouteContext;

package/types/hydrate.d.ts

@@ -0,0 +1,21 @@
+import type { Root } from 'octane';
+import type { DataRouter, DOMRouterOpts } from '@octanejs/remix-router';
+import type { DocusaurusManifest } from './index.js';
+import type { DocusaurusRouteModuleRegistry } from './client.js';
+
+export interface DocusaurusHydrateOptions extends DOMRouterOpts {
+	identifierPrefix?: string;
+	signal?: AbortSignal;
+}
+
+export interface DocusaurusHydrationRoot {
+	root: Root;
+	router: DataRouter;
+}
+
+export declare function hydrateDocusaurusRoot(
+	container: Element,
+	manifest: DocusaurusManifest,
+	registry: DocusaurusRouteModuleRegistry,
+	options?: DocusaurusHydrateOptions,
+): Promise<DocusaurusHydrationRoot>;