@wrikka/create-docs 0.1.0

package/src/presentation/vite-plugin/docs-plugin.ts

@@ -0,0 +1,212 @@
+/**
+ * Imperative shell: assemble all the pieces into a Vite Plugin.
+ *
+ * The functional core (buildVirtualModules, etc.) lives in the plugin module.
+ * This file is the I/O boundary that talks to Vite's runtime API.
+ */
+
+import {
+	type DocsPluginOptions,
+	type ResolvedDocsConfig,
+	resolveConfig,
+	type UserConfig,
+} from "@create-docs/modules/config";
+import { type DocPage, ParseCache } from "@create-docs/modules/content";
+import { buildDocs, isMarkdownPath } from "@create-docs/modules/plugin";
+import {
+	DEFAULT_BASE_ROUTE,
+	DEFAULT_DOCS_DIR,
+	PLUGIN_NAME,
+	VIRTUAL_PREFIX,
+} from "@create-docs/shared/constants";
+import { isString } from "@create-docs/shared/utils/object";
+import { toPosixPath } from "@create-docs/shared/utils/string";
+import type { Plugin, ResolvedConfig, ViteDevServer } from "vite";
+import { createFsDocsLoader } from "../../adapters/fs/fs-docs-loader";
+import { buildVelite } from "../../adapters/velite";
+import {
+	createNodeDocsWatcher,
+	createPollingWatcher,
+} from "../../adapters/vite";
+
+export type WatchMode = "native" | "polling";
+
+export interface DocsPluginConfig extends Partial<UserConfig> {
+	/** Optional: explicit config object passed by the consumer. */
+	readonly userConfig?: UserConfig;
+	/** Optional: pre-resolved plugin options override. */
+	readonly options?: DocsPluginOptions;
+	/** Force a full browser reload on HMR (default: false, granular invalidation). */
+	readonly fullReload?: boolean;
+	/** Watcher mode. Default: 'native'. Use 'polling' for Linux subdir reliability. */
+	readonly watchMode?: WatchMode;
+	/** Polling interval in ms when watchMode='polling'. Default: 300. */
+	readonly pollingIntervalMs?: number;
+	/** Per-page transformation hook. Invoked after parse, before serialisation. */
+	readonly transformPage?: (page: DocPage) => DocPage | Promise<DocPage>;
+}
+
+export const docsPlugin = (cfg: DocsPluginConfig = {}): Plugin => {
+	const userConfig: UserConfig = cfg.userConfig ?? { ...cfg };
+	const options: DocsPluginOptions = cfg.options ?? {};
+	const fullReload = cfg.fullReload === true;
+	const watchMode: WatchMode = cfg.watchMode ?? "native";
+	const pollingIntervalMs = cfg.pollingIntervalMs ?? 300;
+	const transformPage = cfg.transformPage;
+
+	const docsDir = options.docsDir ?? DEFAULT_DOCS_DIR;
+	const baseRoute = options.baseRoute ?? DEFAULT_BASE_ROUTE;
+
+	let resolved: ResolvedDocsConfig | null = null;
+	let server: ViteDevServer | null = null;
+	let watcherHandle: { close: () => void } | null = null;
+	let lastModules: Readonly<Record<string, string>> = {};
+	const cache: ParseCache<DocPage> = new ParseCache<DocPage>();
+
+	const resolve = (): ResolvedDocsConfig => {
+		if (resolved) return resolved;
+		resolved = resolveConfig({ ...userConfig, docsDir, baseRoute });
+		return resolved;
+	};
+
+	const invalidateAndNotify = (now2: number = Date.now()): void => {
+		if (!server) return;
+		const invalidated: string[] = [];
+		for (const id of Object.keys(lastModules)) {
+			const mod = server.moduleGraph.getModuleById(id);
+			if (mod) {
+				server.moduleGraph.invalidateModule(mod);
+				invalidated.push(id);
+			}
+		}
+		if (fullReload) {
+			server.ws.send({ type: "full-reload" });
+			return;
+		}
+		// Granular HMR: send an update event referencing the virtual modules.
+		// Connected clients with `import.meta.hot.accept` on these virtuals
+		// will hot-swap; others will be re-evaluated via the standard
+		// module graph invalidation without a full page reload.
+		const now = now2;
+		server.ws.send({
+			type: "update",
+			updates: invalidated.map((id) => ({
+				type: "js-update" as const,
+				path: id,
+				acceptedPath: id,
+				timestamp: now,
+			})),
+		});
+	};
+
+	const reload = async (): Promise<void> => {
+		const config = resolve();
+
+		// Build content with Velite
+		const veliteResult = await buildVelite({
+			configPath: config.docsDir
+				? `${config.docsDir}/velite.config.ts`
+				: "velite.config.ts",
+			watch: true,
+		});
+
+		if (!veliteResult.success) {
+			console.error(
+				`[${PLUGIN_NAME}] Velite build failed:`,
+				veliteResult.error,
+			);
+			return;
+		}
+
+		// Build virtual modules from Velite output
+		const loader = createFsDocsLoader();
+		const result = await buildDocs({
+			config,
+			loader,
+			...(transformPage ? { transformPage } : {}),
+		});
+
+		if (result.ok) {
+			lastModules = result.value as unknown as Record<string, string>;
+			invalidateAndNotify();
+		}
+	};
+
+	return {
+		name: PLUGIN_NAME,
+
+		config() {
+			return {
+				optimizeDeps: {
+					include: ["comark", "@comark/svelte"],
+				},
+			};
+		},
+
+		async configResolved(config: ResolvedConfig) {
+			resolve();
+			// Initial build so the virtual modules are ready for the first request.
+			await reload();
+			// Watch docsDir for changes
+			try {
+				const docsDirAbs = toPosixPath(config.root).replace(/\/$/, "");
+				if (watchMode === "polling") {
+					const watcher = createPollingWatcher({
+						intervalMs: pollingIntervalMs,
+					});
+					watcherHandle = watcher.watch(docsDirAbs, (_filename) => {
+						void reload();
+					});
+				} else {
+					const watcher = createNodeDocsWatcher();
+					watcherHandle = watcher.watch(docsDirAbs, (_filename) => {
+						void reload();
+					});
+				}
+			} catch (e) {
+				console.warn(`[${PLUGIN_NAME}] Failed to start watcher:`, e);
+			}
+		},
+
+		configureServer(s: ViteDevServer) {
+			server = s;
+			s.httpServer?.on("close", () => {
+				watcherHandle?.close();
+				cache.clear();
+			});
+		},
+
+		resolveId(id: string) {
+			if (id.startsWith(VIRTUAL_PREFIX)) return id;
+			return null;
+		},
+
+		async load(id: string) {
+			if (!id.startsWith(VIRTUAL_PREFIX)) return null;
+			const mod = (lastModules as Record<string, string>)[id];
+			if (mod !== undefined) return mod;
+			await reload();
+			const m = (lastModules as Record<string, string>)[id];
+			return m ?? null;
+		},
+
+		async transform(code: string, id: string) {
+			if (!isMarkdownPath(id)) return null;
+			if (!isString(code)) return null;
+			try {
+				// Velite handles markdown parsing, skip transformation here
+				// Content is processed by Velite build and loaded from virtual modules
+				return null;
+			} catch (e) {
+				console.error(`[${PLUGIN_NAME}] Failed to transform ${id}:`, e);
+				return { code, map: null };
+			}
+		},
+
+		closeBundle() {
+			watcherHandle?.close();
+		},
+	};
+};
+
+export default docsPlugin;

package/src/presentation/vite-plugin/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Vite plugin presentation entry point.
+ * This is the ONLY file in `presentation/` that should be imported by the
+ * public API — it's the imperative shell that wires adapters to use cases.
+ */
+
+export type { DocsPluginConfig } from "./docs-plugin";
+export { default, docsPlugin } from "./docs-plugin";
+export { transformMarkdown } from "./transform-markdown";

package/src/presentation/vite-plugin/transform-markdown.ts

@@ -0,0 +1,26 @@
+/**
+ * Pure transformation: turn a markdown file path → Svelte source code.
+ * No I/O, no exceptions. The `parse` from comark is injected so this
+ * function is fully testable.
+ */
+import { parseFrontmatter } from "@create-docs/modules/content";
+
+export type MarkdownToSvelte = (
+	raw: string,
+	deps: {
+		readonly parse: (content: string) => Promise<unknown>;
+	},
+) => Promise<string>;
+
+export const transformMarkdown: MarkdownToSvelte = async (raw, { parse }) => {
+	const { frontmatter, content } = parseFrontmatter(raw);
+	const tree = await parse(content);
+	const fmJson = JSON.stringify(frontmatter);
+	const contentJson = JSON.stringify(content);
+	const treeJson = JSON.stringify(tree);
+	return `<script lang="ts">
+		export const frontmatter = ${fmJson};
+		export const content = ${contentJson};
+		export const tree = ${treeJson};
+	</script>`;
+};

package/src/runtime/analytics.ts

@@ -0,0 +1,59 @@
+/**
+ * Lightweight, privacy-friendly page-view analytics.
+ *
+ * Counts are stored in localStorage so the `/analytics` dashboard works
+ * with zero backend. When `config.analytics.endpoint` is set, each view is
+ * also beaconed to that URL for server-side aggregation.
+ */
+
+export interface PageViewRecord {
+	path: string;
+	views: number;
+	lastVisit: string;
+}
+
+const STORAGE_KEY = "create-docs:analytics";
+
+export function trackPageView(path: string, endpoint?: string): void {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		const data: PageViewRecord[] = raw ? JSON.parse(raw) : [];
+		const rec = data.find((r) => r.path === path);
+		if (rec) {
+			rec.views += 1;
+			rec.lastVisit = new Date().toISOString();
+		} else {
+			data.push({ path, views: 1, lastVisit: new Date().toISOString() });
+		}
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+	} catch {
+		// Storage unavailable (private mode, quota) — skip local tracking.
+	}
+
+	if (endpoint) {
+		try {
+			navigator.sendBeacon(endpoint, JSON.stringify({ path, t: Date.now() }));
+		} catch {
+			// Beacon unsupported — skip remote tracking.
+		}
+	}
+}
+
+export function getPageViews(): PageViewRecord[] {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (!raw) return [];
+		const data = JSON.parse(raw) as PageViewRecord[];
+		return Array.isArray(data) ? data : [];
+	} catch {
+		return [];
+	}
+}
+
+export function resetPageViews(): void {
+	try {
+		localStorage.removeItem(STORAGE_KEY);
+	} catch {
+		// ignore
+	}
+}

package/src/runtime/api-diff.ts

@@ -0,0 +1,115 @@
+import type { ApiCollection } from "./config";
+import type { ApiEndpoint } from "./types";
+
+export interface EndpointChange {
+	type: "added" | "removed" | "changed";
+	collection: string;
+	endpoint: ApiEndpoint;
+	/** Human-readable descriptions of what changed. */
+	changes: string[];
+}
+
+const key = (c: string, e: ApiEndpoint) => `${c}:${e.method} ${e.path}`;
+
+function describeChanges(prev: ApiEndpoint, next: ApiEndpoint): string[] {
+	const changes: string[] = [];
+
+	if (prev.summary !== next.summary) changes.push("Summary updated");
+	if (prev.description !== next.description)
+		changes.push("Description updated");
+	if (prev.tag !== next.tag) changes.push("Tag changed");
+
+	const prevParams = new Map(
+		(prev.parameters ?? []).map((p) => [`${p.in}:${p.name}`, p]),
+	);
+	const nextParams = new Map(
+		(next.parameters ?? []).map((p) => [`${p.in}:${p.name}`, p]),
+	);
+	for (const [k, p] of nextParams) {
+		const old = prevParams.get(k);
+		if (!old) changes.push(`Parameter added: ${p.name} (${p.in})`);
+		else if (old.required !== p.required)
+			changes.push(
+				`Parameter ${p.name} is now ${p.required ? "required" : "optional"}`,
+			);
+	}
+	for (const [k, p] of prevParams) {
+		if (!nextParams.has(k))
+			changes.push(`Parameter removed: ${p.name} (${p.in})`);
+	}
+
+	if (
+		(prev.requestBody?.required ?? false) !==
+		(next.requestBody?.required ?? false)
+	)
+		changes.push(
+			next.requestBody?.required
+				? "Request body is now required"
+				: "Request body is now optional",
+		);
+
+	const prevRes = new Set(Object.keys(prev.responses ?? {}));
+	const nextRes = new Set(Object.keys(next.responses ?? {}));
+	for (const s of nextRes) {
+		if (!prevRes.has(s)) changes.push(`Response added: ${s}`);
+	}
+	for (const s of prevRes) {
+		if (!nextRes.has(s)) changes.push(`Response removed: ${s}`);
+	}
+
+	return changes;
+}
+
+/**
+ * Diff two API collection sets (previous vs current) by method+path.
+ * Works uniformly for OpenAPI, oRPC, Elysia, and Nitro-derived collections
+ * since all adapters normalise to {@link ApiCollection}.
+ */
+export function diffApiCollections(
+	previous: ApiCollection[],
+	current: ApiCollection[],
+): EndpointChange[] {
+	const prev = new Map<string, ApiEndpoint>();
+	for (const c of previous) {
+		for (const e of c.endpoints) prev.set(key(c.id, e), e);
+	}
+	const next = new Map<string, ApiEndpoint>();
+	for (const c of current) {
+		for (const e of c.endpoints) next.set(key(c.id, e), e);
+	}
+
+	const changes: EndpointChange[] = [];
+	for (const [k, e] of next) {
+		const col = k.slice(0, k.indexOf(":"));
+		const old = prev.get(k);
+		if (!old) {
+			changes.push({
+				type: "added",
+				collection: col,
+				endpoint: e,
+				changes: [],
+			});
+			continue;
+		}
+		const diffs = describeChanges(old, e);
+		if (diffs.length) {
+			changes.push({
+				type: "changed",
+				collection: col,
+				endpoint: e,
+				changes: diffs,
+			});
+		}
+	}
+	for (const [k, e] of prev) {
+		if (!next.has(k)) {
+			changes.push({
+				type: "removed",
+				collection: k.slice(0, k.indexOf(":")),
+				endpoint: e,
+				changes: [],
+			});
+		}
+	}
+	return changes;
+}

package/src/runtime/app.tsx

@@ -0,0 +1,32 @@
+import { RouterProvider } from "@tanstack/solid-router";
+import type { JSX } from "solid-js";
+import { render } from "solid-js/web";
+import type { DocsAppConfig } from "./config";
+import { DocsProvider } from "./context";
+import { setupPwa } from "./pwa";
+import { createDocsRouter } from "./router";
+import { initTheme } from "./theme";
+import "./theme.css";
+import "./markdown-content.css";
+
+/** App root component factory — mount with your own render call. */
+export function createDocsApp(config: DocsAppConfig): () => JSX.Element {
+	if (typeof document !== "undefined") initTheme(config.theme?.defaultMode);
+	setupPwa(config);
+	const router = createDocsRouter(config);
+	return () => (
+		<DocsProvider config={config}>
+			<RouterProvider router={router} />
+		</DocsProvider>
+	);
+}
+
+/** One-call mount. Looks up `#root` when no element is given. */
+export function mountDocsApp(
+	config: DocsAppConfig,
+	el?: HTMLElement | null,
+): void {
+	const root = el ?? document.getElementById("root");
+	if (!root) throw new Error("create-docs: root element not found");
+	render(createDocsApp(config), root);
+}

package/src/runtime/components/AccentPicker.tsx

@@ -0,0 +1,114 @@
+import { createSignal, For, onCleanup, onMount, Show } from "solid-js";
+import { useAccent } from "../theme";
+
+export function AccentPicker() {
+	const { accent, accentIndex, accents, setAccent } = useAccent();
+	const [open, setOpen] = createSignal(false);
+	let rootEl: HTMLDivElement | undefined;
+
+	const onDocClick = (e: MouseEvent) => {
+		if (rootEl && !rootEl.contains(e.target as Node)) setOpen(false);
+	};
+	const onKey = (e: KeyboardEvent) => {
+		if (e.key === "Escape") setOpen(false);
+	};
+
+	onMount(() => {
+		document.addEventListener("click", onDocClick);
+		document.addEventListener("keydown", onKey);
+	});
+	onCleanup(() => {
+		document.removeEventListener("click", onDocClick);
+		document.removeEventListener("keydown", onKey);
+	});
+
+	return (
+		<div ref={rootEl} class="relative">
+			<button
+				type="button"
+				onClick={() => setOpen(!open())}
+				aria-expanded={open()}
+				aria-haspopup="listbox"
+				aria-label="Accent color"
+				title={`Accent: ${accents[accentIndex()].name}`}
+				class="w-9 h-9 inline-flex items-center justify-center rounded-md border border-border text-muted hover:text-foreground hover:bg-surface transition-colors cursor-pointer"
+			>
+				<span
+					class="w-4 h-4 rounded-full border border-border"
+					style={{
+						"background-color": accents[accentIndex()].swatch,
+					}}
+					aria-hidden="true"
+				/>
+			</button>
+			<Show when={open()}>
+				<div
+					role="listbox"
+					aria-label="Accent color"
+					class="absolute right-0 top-full mt-2 w-56 rounded-lg border border-border bg-surface shadow-lg p-2 z-50"
+				>
+					<div class="px-2 pb-1.5 text-[10px] uppercase tracking-wider font-semibold text-muted">
+						Daily accent
+					</div>
+					<button
+						type="button"
+						role="option"
+						aria-selected={accent() === "auto"}
+						onClick={() => {
+							setAccent("auto");
+							setOpen(false);
+						}}
+						class={`w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-sm transition-colors cursor-pointer border-none ${
+							accent() === "auto"
+								? "bg-primary/10 text-primary"
+								: "bg-transparent text-foreground hover:bg-background"
+						}`}
+					>
+						<span class="i-mdi:calendar-sync text-base" aria-hidden="true" />
+						<span class="flex-1 text-left">Auto — daily</span>
+						<Show when={accent() === "auto"}>
+							<span class="i-mdi:check text-primary" aria-hidden="true" />
+						</Show>
+					</button>
+					<div class="my-1.5 h-px bg-border" aria-hidden="true" />
+					<ul class="list-none m-0 p-0 grid grid-cols-1">
+						<For each={accents}>
+							{(a, i) => (
+								<li>
+									<button
+										type="button"
+										role="option"
+										aria-selected={accent() === i()}
+										onClick={() => {
+											setAccent(i());
+											setOpen(false);
+										}}
+										class={`w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-sm transition-colors cursor-pointer border-none ${
+											accent() === i()
+												? "bg-primary/10 text-primary"
+												: "bg-transparent text-foreground hover:bg-background"
+										}`}
+									>
+										<span
+											class="w-4 h-4 rounded-full border border-border shrink-0"
+											style={{ "background-color": a.swatch }}
+											aria-hidden="true"
+										/>
+										<span class="flex-1 text-left truncate">{a.name}</span>
+										<span class="text-[10px] text-muted">{a.day}</span>
+										<Show when={accent() === i()}>
+											<span
+												class="i-mdi:check text-primary"
+												aria-hidden="true"
+											/>
+										</Show>
+									</button>
+								</li>
+							)}
+						</For>
+					</ul>
+				</div>
+			</Show>
+		</div>
+	);
+}