npm - @octanejs/docusaurus - Versions diffs - 0.0.3 → 0.0.4 - Mend

@octanejs/docusaurus 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/README.md +143 -5
package/package.json +26 -4
package/src/bin.js +1 -1
package/src/client-components.tsrx +134 -0
package/src/client.js +18 -0
package/src/document.js +153 -0
package/src/hydrate.js +52 -0
package/src/manifest.js +89 -8
package/src/route-modules.js +56 -0
package/src/routes.js +133 -0
package/src/server.js +64 -0
package/src/theme/DocCategoryGeneratedIndexPage.js +1 -0
package/src/theme/DocItem.js +1 -0
package/src/theme/DocRoot.js +1 -0
package/src/theme/DocTagDocListPage.js +1 -0
package/src/theme/DocTagsListPage.js +1 -0
package/src/theme/DocVersionRoot.js +1 -0
package/src/theme/DocsRoot.js +1 -0
package/src/theme/Root.js +1 -0
package/src/theme/styles.css +183 -0
package/src/theme-components.tsrx +462 -0
package/src/theme.js +25 -0
package/src/vite.js +50 -2
package/types/client.d.ts +58 -0
package/types/hydrate.d.ts +21 -0
package/types/index.d.ts +63 -4
package/types/server.d.ts +80 -0
package/types/theme.d.ts +8 -0
package/types/virtual.d.ts +10 -0
package/types/vite.d.ts +12 -0

package/README.md CHANGED Viewed

@@ -39,6 +39,8 @@ The manifest contains:
 - nested routes with `component`, `modules`, `props`, and plugin context;
 - generated global data and per-document metadata;
+- serializable site config, locale/document attributes, and plugin HTML tags;
+- client modules discovered through the Docusaurus plugin lifecycle;
 - `@site`, `@generated`, `~docs`, `@theme`, `@theme-original`, and
   `@theme-init` resolution;
 - the exact Docusaurus version and route-path inventory.
@@ -64,7 +66,141 @@ export default defineConfig({
 The bridge publishes `virtual:octane-docusaurus-manifest` and resolves
 Docusaurus aliases. Its MDX plugin chooses Octane client/server compilation per
-Vite environment and injects metadata discovered by the content plugins.
+Vite environment and injects metadata discovered by the content plugins. The
+route virtual module also imports plugin client modules, so theme CSS and other
+side-effect assets participate in the client and SSR build graphs.
+## Octane classic theme
+Add the first-party Octane theme beside the content plugins in
+`docusaurus.config.mjs`:
+```js
+import octaneClassicTheme from '@octanejs/docusaurus/theme';
+export default {
+	title: 'My documentation',
+	url: 'https://docs.example.com',
+	baseUrl: '/',
+	themes: [octaneClassicTheme],
+	plugins: ['@docusaurus/plugin-content-docs'],
+};
+```
+The theme supplies Octane-native `DocsRoot`, `DocVersionRoot`, `DocRoot`,
+`DocItem`, category-index, and tag-page route modules. Its initial classic shell
+renders configured navbar/footer links, recursive documentation sidebars,
+document metadata, canonical links, previous/next navigation, and responsive
+CSS. React-authored theme modules and swizzles still need Octane equivalents.
+## Client routing
+The route virtual module turns every component, content module, generated data
+module, and route-context module into a static dynamic import. Only the matched
+branch loads in the browser:
+```ts
+import { createDocusaurusBrowserRouter } from '@octanejs/docusaurus/client';
+import {
+	manifest,
+	routeModules,
+} from 'virtual:octane-docusaurus-routes';
+export const router = createDocusaurusBrowserRouter(manifest, routeModules);
+```
+Render it from an Octane component:
+```tsx
+import { DocusaurusRouterProvider } from '@octanejs/docusaurus/client';
+import { manifest } from 'virtual:octane-docusaurus-routes';
+import { router } from './router';
+export function App() @{
+	<DocusaurusRouterProvider manifest={manifest} router={router} />
+}
+```
+Nested Docusaurus routes render through `children`; route components also
+receive loaded `modules`, static `props`, `route`, `location`, `params`, and
+`navigate`. `useDocusaurusRouteContext()` exposes the inherited plugin identity
+and merged route data. Use `Link` from `@octanejs/remix-router` for client-side
+navigation.
+## Static rendering and hydration
+The server entry resolves the requested lazy route branch through Remix's
+static handler, then prerenders fully resolved Octane markup. Use the route API
+when a host owns the outer HTML, or the document API to compose Docusaurus
+plugin tags, metadata, scoped CSS, build assets, and the hydration entry into a
+complete page:
+```ts
+import { prerenderDocusaurusDocument } from '@octanejs/docusaurus/server';
+import {
+	manifest,
+	routeModules,
+} from 'virtual:octane-docusaurus-routes';
+const rendered = await prerenderDocusaurusDocument(
+	new Request('https://docs.example.com/guide/intro'),
+	manifest,
+	routeModules,
+	{
+		document: {
+			assets: {
+				stylesheets: ['assets/site.css'],
+				modulePreloads: ['assets/intro.js'],
+			},
+			hydrate: 'assets/hydrate.js',
+		},
+	},
+);
+if (rendered instanceof Response) {
+	return rendered;
+}
+const { html, bodyHtml, head, css, context } = rendered;
+```
+`html` is the complete `<!DOCTYPE html>` document. `bodyHtml` remains the
+prerendered router root for integrations that need both forms. Relative asset
+paths resolve against `manifest.baseUrl`; URL attributes are escaped, duplicate
+asset entries are removed without reordering, and `nonce` from the render
+options is carried onto module scripts. Docusaurus `injectHtmlTags` output is
+trusted site configuration and retains upstream ordering around the
+`#__docusaurus` root.
+`prerenderDocusaurusRoute()` remains available and returns hoisted metadata in
+`head` so an existing static-site host can place it in its own document head.
+`context.statusCode`, `loaderHeaders`, and `actionHeaders` preserve the static
+router result for the surrounding build or request handler. Generate a site by
+calling this function for the paths in `manifest.routesPaths`; each render
+imports only its matched route branch.
+Hydrate the same root after the browser receives that markup:
+```ts
+import { hydrateDocusaurusRoot } from '@octanejs/docusaurus/hydrate';
+import {
+	manifest,
+	routeModules,
+} from 'virtual:octane-docusaurus-routes';
+const container = document.getElementById('__docusaurus');
+if (container === null) throw new Error('Missing Docusaurus root.');
+const { root, router } = await hydrateDocusaurusRoot(
+	container,
+	manifest,
+	routeModules,
+);
+```
+Hydration capture starts before lazy imports, waits for the initial matched
+branch, and then adopts the prerendered nodes. Dispose both returned owners when
+the application is torn down with `root.unmount()` and `router.dispose()`.
 ## Docusaurus-aware MDX
@@ -94,7 +230,9 @@ remain composable.
 ## Current scope
-Phases 1–3 are implemented here: headless loading, manifest/Vite integration,
-and MDX compilation. Client routing, static generation, hydration, and an
-Octane classic theme are deliberately left to the renderer/theme phases; the
-CLI therefore does not present `start` or `build` as working commands yet.
+Phases 1–6 are implemented here: headless loading, manifest/Vite integration,
+MDX compilation, lazy client routing, static route rendering, hydration,
+document/asset orchestration, and the initial Octane classic documentation
+theme. A complete `start`/`build` CLI workflow and broader classic-theme feature
+parity remain later phases, so the CLI does not present those commands as
+working yet.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/docusaurus",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Docusaurus content and MDX integration for Octane",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,26 @@
       "import": "./src/mdx.js",
       "default": "./src/mdx.js"
     },
+    "./client": {
+      "types": "./types/client.d.ts",
+      "import": "./src/client.js",
+      "default": "./src/client.js"
+    },
+    "./hydrate": {
+      "types": "./types/hydrate.d.ts",
+      "import": "./src/hydrate.js",
+      "default": "./src/hydrate.js"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "import": "./src/server.js",
+      "default": "./src/server.js"
+    },
+    "./theme": {
+      "types": "./types/theme.d.ts",
+      "import": "./src/theme.js",
+      "default": "./src/theme.js"
+    },
     "./vite": {
       "types": "./types/vite.d.ts",
       "import": "./src/vite.js",
@@ -51,12 +71,14 @@
   },
   "dependencies": {
     "github-slugger": "1.5.0",
-    "@octanejs/mdx": "0.1.16"
+    "@octanejs/mdx": "0.1.17",
+    "@octanejs/remix-router": "0.1.16",
+    "@octanejs/seo": "0.0.5"
   },
   "peerDependencies": {
     "@docusaurus/core": "3.10.1",
     "vite": ">=7.0.0",
-    "octane": "0.1.19"
+    "octane": "0.1.20"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -69,7 +91,7 @@
     "@types/node": "^24.13.3",
     "vite": "^8.1.5",
     "vitest": "^4.1.10",
-    "octane": "0.1.19"
+    "octane": "0.1.20"
   },
   "scripts": {
     "test": "cd ../.. && vitest run --project docusaurus"

package/src/bin.js CHANGED Viewed

@@ -10,7 +10,7 @@ function usage() {
   octane-docusaurus clear [--site-dir DIR]
 The phase 1-3 command inspects Docusaurus's headless route/data graph. Static
-site build, hydration, and theme commands arrive with the renderer phases.
+site build and theme commands arrive with the document/theme phase.
 `;
 }

package/src/client-components.tsrx ADDED Viewed

@@ -0,0 +1,134 @@
+import { createContext, useContext, type ComponentBody, type OctaneNode } from 'octane';
+import {
+	Outlet,
+	RouterProvider,
+	type DataRouter,
+	useLocation,
+	useNavigate,
+	useParams,
+} from '@octanejs/remix-router';
+import { Head, Meta, Seo } from '@octanejs/seo';
+type DocusaurusPluginIdentifier = {
+	name: string;
+	id: string;
+};
+type DocusaurusRouteContextValue = {
+	plugin: DocusaurusPluginIdentifier;
+	data: Record<string, unknown>;
+};
+type DocusaurusManifestValue = {
+	baseUrl: string;
+	site: {
+		title: string;
+		url: string;
+		favicon?: string;
+		noIndex: boolean;
+		themeConfig: Record<string, unknown>;
+	};
+};
+type DocusaurusRoute = {
+	children: DocusaurusRoute[];
+	plugin?: DocusaurusPluginIdentifier;
+	props?: Record<string, unknown>;
+	[key: string]: unknown;
+};
+const ManifestContext = createContext<DocusaurusManifestValue | null>(null);
+const RouteContext = createContext<DocusaurusRouteContextValue | null>(null);
+function DocusaurusSiteMetadata(props: { manifest: DocusaurusManifestValue }) @{
+	const site = props.manifest.site;
+	<>
+		<Seo
+			title={site.title}
+			openGraph={{ title: site.title }}
+			robots={site.noIndex ? { index: false, follow: false } : undefined}
+		/>
+		<Meta name="viewport" content="width=device-width, initial-scale=1.0" />
+	</>
+}
+function mergeRouteContext(
+	parent: DocusaurusRouteContextValue | null,
+	route: DocusaurusRoute,
+	resolved: Record<string, unknown> | undefined,
+): DocusaurusRouteContextValue {
+	const { plugin: resolvedPlugin, data: explicitData, ...ownData } = resolved ?? {};
+	const ownPlugin = resolvedPlugin as DocusaurusPluginIdentifier | undefined;
+	const plugin = parent?.plugin ?? ownPlugin ?? route.plugin;
+	if (plugin === undefined) {
+		throw new Error(`[@octanejs/docusaurus] Route ${String(
+			route.path,
+		)} has no Docusaurus plugin context.`);
+	}
+	return {
+		plugin,
+		data: {
+			...parent?.data,
+			...ownData,
+			...(explicitData !== null && typeof explicitData === 'object'
+				? explicitData as Record<string, unknown>
+				: {}),
+		},
+	};
+}
+export function DocusaurusRouterProvider(props: {
+	manifest: DocusaurusManifestValue;
+	router: DataRouter;
+}) @{
+	<ManifestContext.Provider value={props.manifest}>
+		<Head>
+			<DocusaurusSiteMetadata manifest={props.manifest} />
+			<RouterProvider router={props.router} />
+		</Head>
+	</ManifestContext.Provider>
+}
+export function DocusaurusRouteRenderer(props: {
+	Component: ComponentBody<Record<string, unknown>>;
+	context?: Record<string, unknown>;
+	modules: Record<string, unknown>;
+	route: DocusaurusRoute;
+}) @{
+	const parentContext = useContext(RouteContext);
+	const location = useLocation();
+	const navigate = useNavigate();
+	const params = useParams();
+	const context = mergeRouteContext(parentContext, props.route, props.context);
+	const route = { ...props.route, routes: props.route.children };
+	const Component = props.Component;
+	<RouteContext.Provider value={context}>
+		<Component
+			{...props.modules}
+			{...props.route.props}
+			route={route}
+			location={location}
+			params={params}
+			navigate={navigate}
+		>
+			<Outlet />
+		</Component>
+	</RouteContext.Provider>
+}
+export function useDocusaurusManifest(): DocusaurusManifestValue {
+	const manifest = useContext(ManifestContext);
+	if (manifest === null) {
+		throw new Error('[@octanejs/docusaurus] useDocusaurusManifest() requires DocusaurusRouterProvider.');
+	}
+	return manifest;
+}
+export function useDocusaurusRouteContext(): DocusaurusRouteContextValue {
+	const context = useContext(RouteContext);
+	if (context === null) {
+		throw new Error('[@octanejs/docusaurus] useDocusaurusRouteContext() requires a matched Docusaurus route.');
+	}
+	return context;
+}

package/src/client.js ADDED Viewed

@@ -0,0 +1,18 @@
+import { createBrowserRouter, createMemoryRouter } from '@octanejs/remix-router';
+import {
+	DocusaurusRouterProvider,
+	useDocusaurusManifest,
+	useDocusaurusRouteContext,
+} from './client-components.tsrx';
+import { createDocusaurusRoutes } from './routes.js';
+export { DocusaurusRouterProvider, useDocusaurusManifest, useDocusaurusRouteContext };
+export { createDocusaurusRoutes };
+export function createDocusaurusBrowserRouter(manifest, registry, options) {
+	return createBrowserRouter(createDocusaurusRoutes(manifest, registry), options);
+}
+export function createDocusaurusMemoryRouter(manifest, registry, options) {
+	return createMemoryRouter(createDocusaurusRoutes(manifest, registry), options);
+}

package/src/document.js ADDED Viewed

@@ -0,0 +1,153 @@
+import { escapeAttr } from 'octane/server';
+const ATTRIBUTE_NAME = /^[A-Za-z_:][A-Za-z0-9_.:-]*$/;
+const ABSOLUTE_ASSET = /^(?:[a-z][a-z\d+.-]*:|\/\/|\/|#)/i;
+function escapeDocumentAttribute(value) {
+	const escaped = escapeAttr(value);
+	return /[<>]/.test(escaped) ? escaped.replace(/</g, '&lt;').replace(/>/g, '&gt;') : escaped;
+}
+function attributeString(attributes) {
+	let result = '';
+	for (const [name, value] of Object.entries(attributes ?? {})) {
+		if (!ATTRIBUTE_NAME.test(name)) {
+			throw new TypeError(`Invalid Docusaurus document attribute name: ${JSON.stringify(name)}.`);
+		}
+		if (value === undefined || value === null || value === false) continue;
+		result += value === true ? ` ${name}` : ` ${name}="${escapeDocumentAttribute(String(value))}"`;
+	}
+	return result;
+}
+function assetSource(asset, name) {
+	if (typeof asset === 'string') return asset;
+	if (asset !== null && typeof asset === 'object' && typeof asset[name] === 'string') {
+		return asset[name];
+	}
+	throw new TypeError(`Expected a Docusaurus ${name} asset.`);
+}
+function assetUrl(baseUrl, value) {
+	if (ABSOLUTE_ASSET.test(value)) return value;
+	return `${baseUrl}${value.replace(/^\.\//, '')}`;
+}
+function assetAttributes(asset, sourceName, baseUrl, baseAttributes) {
+	if (typeof asset === 'string') {
+		return {
+			...baseAttributes,
+			[sourceName]: assetUrl(baseUrl, asset),
+		};
+	}
+	const { integrity, crossOrigin, referrerPolicy, media, async, defer, type } = asset;
+	return {
+		...baseAttributes,
+		[sourceName]: assetUrl(baseUrl, assetSource(asset, sourceName)),
+		...(integrity === undefined ? {} : { integrity }),
+		...(crossOrigin === undefined ? {} : { crossorigin: crossOrigin }),
+		...(referrerPolicy === undefined ? {} : { referrerpolicy: referrerPolicy }),
+		...(media === undefined ? {} : { media }),
+		...(async === undefined ? {} : { async }),
+		...(defer === undefined ? {} : { defer }),
+		...(type === undefined ? {} : { type }),
+	};
+}
+function uniqueAssets(assets, sourceName) {
+	const result = [];
+	const seen = new Set();
+	for (const asset of assets ?? []) {
+		const source = assetSource(asset, sourceName);
+		if (seen.has(source)) continue;
+		seen.add(source);
+		result.push(asset);
+	}
+	return result;
+}
+function renderAssets(manifest, assets, nonce) {
+	const stylesheets = uniqueAssets(assets?.stylesheets, 'href').map((asset) => {
+		const attributes = assetAttributes(asset, 'href', manifest.baseUrl, {
+			rel: 'stylesheet',
+		});
+		return `<link${attributeString(attributes)}>`;
+	});
+	const modulePreloads = uniqueAssets(assets?.modulePreloads, 'href').map((asset) => {
+		const attributes = assetAttributes(asset, 'href', manifest.baseUrl, {
+			rel: 'modulepreload',
+		});
+		return `<link${attributeString(attributes)}>`;
+	});
+	const scripts = uniqueAssets(assets?.scripts, 'src').map((asset) => {
+		const attributes = assetAttributes(asset, 'src', manifest.baseUrl, {
+			type: 'module',
+			...(nonce === undefined ? {} : { nonce }),
+		});
+		return `<script${attributeString(attributes)}></script>`;
+	});
+	return [...stylesheets, ...modulePreloads, ...scripts];
+}
+function renderHydrationEntry(manifest, hydrate, nonce) {
+	if (hydrate === undefined) return '';
+	const attributes = assetAttributes(hydrate, 'src', manifest.baseUrl, {
+		type: 'module',
+		'data-octane-hydrate': true,
+		...(nonce === undefined ? {} : { nonce }),
+	});
+	return `<script${attributeString(attributes)}></script>`;
+}
+function renderFavicon(manifest) {
+	if (manifest.site.favicon === undefined) return '';
+	return `<link${attributeString({
+		rel: 'icon',
+		href: assetUrl(manifest.baseUrl, manifest.site.favicon),
+	})}>`;
+}
+/**
+ * Compose one route render into the real Docusaurus HTML document.
+ *
+ * Plugin-provided head/body tag strings were produced by Docusaurus's
+ * `injectHtmlTags` lifecycle and are intentionally treated as trusted site
+ * configuration. Attributes and build asset descriptors supplied here are
+ * escaped before insertion.
+ */
+export function renderDocusaurusDocument(rendered, manifest, options = {}) {
+	const htmlAttributes = {
+		...manifest.document.htmlAttributes,
+		...options.htmlAttributes,
+	};
+	const head = [
+		'<meta charset="UTF-8">',
+		`<meta name="generator" content="Docusaurus v${escapeDocumentAttribute(
+			manifest.docusaurusVersion,
+		)}">`,
+		renderFavicon(manifest),
+		manifest.document.headTags,
+		rendered.head,
+		rendered.css,
+		...renderAssets(manifest, options.assets, options.nonce),
+	].filter((value) => value !== '');
+	const hydration = renderHydrationEntry(manifest, options.hydrate, options.nonce);
+	const body = [
+		manifest.document.preBodyTags,
+		`<div id="${escapeDocumentAttribute(options.rootId ?? '__docusaurus')}">${rendered.html}</div>`,
+		manifest.document.postBodyTags,
+		hydration,
+	].filter((value) => value !== '');
+	return [
+		'<!DOCTYPE html>',
+		`<html${attributeString(htmlAttributes)}>`,
+		'<head>',
+		...head,
+		'</head>',
+		`<body${attributeString(options.bodyAttributes)}>`,
+		...body,
+		'</body>',
+		'</html>',
+	].join('\n');
+}

package/src/hydrate.js ADDED Viewed

@@ -0,0 +1,52 @@
+import { hydrateRoot, initializeHydrationEventCapture } from 'octane';
+import { createDocusaurusBrowserRouter, DocusaurusRouterProvider } from './client.js';
+function abortError(signal) {
+	return signal.reason ?? new DOMException('Docusaurus hydration was aborted.', 'AbortError');
+}
+function waitForRouter(router, signal) {
+	if (signal?.aborted) return Promise.reject(abortError(signal));
+	if (router.state.initialized) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let unsubscribe = () => {};
+		const finish = (error) => {
+			if (settled) return;
+			settled = true;
+			unsubscribe();
+			signal?.removeEventListener('abort', onAbort);
+			if (error === undefined) resolve();
+			else reject(error);
+		};
+		const onAbort = () => finish(abortError(signal));
+		unsubscribe = router.subscribe((state) => {
+			if (state.initialized) finish();
+		});
+		signal?.addEventListener('abort', onAbort, { once: true });
+		if (router.state.initialized) finish();
+	});
+}
+export async function hydrateDocusaurusRoot(container, manifest, registry, options = {}) {
+	const { identifierPrefix, signal, ...routerOptions } = options;
+	initializeHydrationEventCapture(container.ownerDocument);
+	const router = createDocusaurusBrowserRouter(manifest, registry, routerOptions);
+	try {
+		await waitForRouter(router, signal);
+		const root = hydrateRoot(
+			container,
+			DocusaurusRouterProvider,
+			{ manifest, router },
+			{ identifierPrefix },
+		);
+		return { root, router };
+	} catch (error) {
+		router.dispose();
+		throw error;
+	}
+}