@wrikka/create-docs 0.1.0

package/src/runtime/components/ApiPlayground.tsx

@@ -0,0 +1,332 @@
+import { createSignal, For, Show } from "solid-js";
+import type { ApiEndpoint } from "../types";
+
+const METHOD_COLOR: Record<string, string> = {
+	GET: "text-accent",
+	POST: "text-success",
+	PUT: "text-warning",
+	PATCH: "text-warning",
+	DELETE: "text-destructive",
+};
+
+function buildCurl(ep: ApiEndpoint, url: string, body: string): string {
+	const lines = [`curl -X ${ep.method} '${url}'`];
+	if (body.trim()) {
+		lines.push(`  -H 'Content-Type: application/json'`, `  -d '${body}'`);
+	}
+	return lines.join(" \\\n");
+}
+
+function buildCommand(
+	ep: ApiEndpoint,
+	argValues: Record<string, string>,
+): string {
+	if (!ep.cli) return `${ep.method} ${ep.path}`;
+	const parts = [ep.cli.command];
+	if (ep.cli.subcommand) parts.push(ep.cli.subcommand);
+	for (const a of ep.cli.args ?? []) {
+		const v = argValues[a.name] ?? "";
+		if (v) parts.push(`--${a.name}`, v);
+	}
+	return parts.join(" ");
+}
+
+export function ApiPlayground(props: {
+	endpoint: ApiEndpoint;
+	style?: string;
+}) {
+	const ep = () => props.endpoint;
+	const style = () => props.style ?? "rest";
+
+	const [paramValues, setParamValues] = createSignal<Record<string, string>>(
+		{},
+	);
+	const [argValues, setArgValues] = createSignal<Record<string, string>>({});
+	const [body, setBody] = createSignal(
+		ep().requestBody?.example != null
+			? JSON.stringify(ep().requestBody?.example, null, 2)
+			: "",
+	);
+	const [query, setQuery] = createSignal(ep().graphql?.query ?? "");
+	const [variables, setVariables] = createSignal(
+		ep().graphql?.variables != null
+			? JSON.stringify(ep().graphql?.variables, null, 2)
+			: "",
+	);
+	const [sending, setSending] = createSignal(false);
+	const [result, setResult] = createSignal<{
+		status: number;
+		ms: number;
+		body: string;
+	} | null>(null);
+	const [error, setError] = createSignal("");
+	const [copied, setCopied] = createSignal(false);
+
+	const setParam = (name: string, value: string) =>
+		setParamValues((p) => ({ ...p, [name]: value }));
+	const setArg = (name: string, value: string) =>
+		setArgValues((p) => ({ ...p, [name]: value }));
+
+	const resolvedUrl = () => {
+		let path = ep().path;
+		const queryParams = new URLSearchParams();
+		for (const p of ep().parameters) {
+			const v = paramValues()[p.name] ?? "";
+			if (p.in === "path")
+				path = path.replace(`{${p.name}}`, v || `{${p.name}}`);
+			else if (p.in === "query" && v) queryParams.set(p.name, v);
+		}
+		const base = ep().server ?? "";
+		const qs = queryParams.toString();
+		return `${base}${path}${qs ? `?${qs}` : ""}`;
+	};
+
+	const send = async () => {
+		setSending(true);
+		setError("");
+		setResult(null);
+		const t0 = performance.now();
+		try {
+			let requestBody: string | undefined;
+			let headers: Record<string, string> | undefined;
+
+			if (style() === "graphql") {
+				const vars = variables().trim()
+					? (JSON.parse(variables()) as Record<string, unknown>)
+					: {};
+				requestBody = JSON.stringify({ query: query(), variables: vars });
+				headers = { "Content-Type": "application/json" };
+			} else if (body().trim()) {
+				requestBody = body();
+				headers = { "Content-Type": "application/json" };
+			}
+
+			const res = await fetch(resolvedUrl(), {
+				method: ep().method,
+				headers,
+				body: ep().method === "GET" || !requestBody ? undefined : requestBody,
+			});
+			const text = await res.text();
+			setResult({
+				status: res.status,
+				ms: Math.round(performance.now() - t0),
+				body: text,
+			});
+		} catch (e) {
+			setError(e instanceof Error ? e.message : String(e));
+		} finally {
+			setSending(false);
+		}
+	};
+
+	const prettyResult = () => {
+		const r = result();
+		if (!r) return "";
+		try {
+			return JSON.stringify(JSON.parse(r.body), null, 2);
+		} catch {
+			return r.body;
+		}
+	};
+
+	const copyCommand = () => {
+		const text = buildCommand(ep(), argValues());
+		navigator.clipboard.writeText(text).catch(() => {});
+		setCopied(true);
+		setTimeout(() => setCopied(false), 1500);
+	};
+
+	return (
+		<div class="rounded-lg border border-border bg-surface overflow-hidden">
+			<Show when={style() !== "cli"}>
+				<div class="flex items-center gap-2 px-3 py-2 border-b border-border">
+					<span
+						class={`text-xs font-bold ${METHOD_COLOR[ep().method] ?? "text-foreground"}`}
+					>
+						{ep().method}
+					</span>
+					<code class="text-xs text-muted font-mono truncate flex-1">
+						{resolvedUrl() || ep().path}
+					</code>
+				</div>
+			</Show>
+
+			<div class="p-3 flex flex-col gap-3">
+				<Show when={style() === "graphql"}>
+					<div>
+						<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+							Query
+						</p>
+						<textarea
+							value={query()}
+							onInput={(e) => setQuery(e.currentTarget.value)}
+							rows={8}
+							spellcheck={false}
+							class="w-full px-2 py-1.5 rounded border border-border bg-background text-xs font-mono text-foreground outline-none focus:border-focus resize-y"
+						/>
+					</div>
+					<div>
+						<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+							Variables
+						</p>
+						<textarea
+							value={variables()}
+							onInput={(e) => setVariables(e.currentTarget.value)}
+							rows={4}
+							spellcheck={false}
+							class="w-full px-2 py-1.5 rounded border border-border bg-background text-xs font-mono text-foreground outline-none focus:border-focus resize-y"
+						/>
+					</div>
+				</Show>
+
+				<Show when={style() === "cli"}>
+					<div>
+						<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+							Command
+						</p>
+						<pre class="m-0 p-2 rounded border border-border bg-background text-xs font-mono text-foreground overflow-auto whitespace-pre-wrap">
+							{buildCommand(ep(), argValues())}
+						</pre>
+					</div>
+					<Show when={ep().cli?.args?.length}>
+						<div>
+							<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+								Arguments
+							</p>
+							<For each={ep().cli?.args ?? []}>
+								{(a) => (
+									<label class="flex items-center gap-2 mb-1.5">
+										<span class="text-xs font-mono text-foreground w-28 truncate shrink-0">
+											{a.name}
+											<Show when={a.required}>
+												<span class="text-destructive">*</span>
+											</Show>
+										</span>
+										<input
+											type="text"
+											value={argValues()[a.name] ?? ""}
+											onInput={(e) => setArg(a.name, e.currentTarget.value)}
+											placeholder={a.example ?? ""}
+											class="flex-1 min-w-0 h-7 px-2 rounded border border-border bg-background text-xs font-mono text-foreground outline-none focus:border-focus"
+										/>
+									</label>
+								)}
+							</For>
+						</div>
+					</Show>
+					<button
+						type="button"
+						onClick={copyCommand}
+						class="inline-flex items-center justify-center gap-1.5 h-9 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary-hover transition-colors cursor-pointer border-none"
+					>
+						<span
+							class={copied() ? "i-mdi:check" : "i-mdi:content-copy"}
+							aria-hidden="true"
+						/>
+						{copied() ? "Copied!" : "Copy command"}
+					</button>
+				</Show>
+
+				<Show
+					when={
+						ep().parameters.length > 0 &&
+						style() !== "graphql" &&
+						style() !== "cli"
+					}
+				>
+					<div>
+						<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+							Parameters
+						</p>
+						<For each={ep().parameters}>
+							{(p) => (
+								<label class="flex items-center gap-2 mb-1.5">
+									<span class="text-xs font-mono text-foreground w-28 truncate shrink-0">
+										{p.name}
+										<Show when={p.required}>
+											<span class="text-destructive">*</span>
+										</Show>
+									</span>
+									<input
+										type="text"
+										value={paramValues()[p.name] ?? ""}
+										onInput={(e) => setParam(p.name, e.currentTarget.value)}
+										placeholder={p.in}
+										class="flex-1 min-w-0 h-7 px-2 rounded border border-border bg-background text-xs font-mono text-foreground outline-none focus:border-focus"
+									/>
+								</label>
+							)}
+						</For>
+					</div>
+				</Show>
+
+				<Show
+					when={ep().requestBody && style() !== "graphql" && style() !== "cli"}
+				>
+					<div>
+						<p class="text-[11px] font-semibold uppercase tracking-wide text-muted m-0 mb-1.5">
+							Body
+						</p>
+						<textarea
+							value={body()}
+							onInput={(e) => setBody(e.currentTarget.value)}
+							rows={6}
+							spellcheck={false}
+							class="w-full px-2 py-1.5 rounded border border-border bg-background text-xs font-mono text-foreground outline-none focus:border-focus resize-y"
+						/>
+					</div>
+				</Show>
+
+				<Show when={style() !== "cli"}>
+					<button
+						type="button"
+						onClick={send}
+						disabled={sending()}
+						class="inline-flex items-center justify-center gap-1.5 h-9 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary-hover transition-colors cursor-pointer border-none disabled:opacity-50"
+					>
+						<span
+							class={sending() ? "i-mdi:loading animate-spin" : "i-mdi:send"}
+							aria-hidden="true"
+						/>
+						{sending()
+							? "Sending…"
+							: style() === "graphql"
+								? "Run query"
+								: "Send request"}
+					</button>
+				</Show>
+
+				<Show when={error()}>
+					<p class="text-xs text-destructive m-0">{error()}</p>
+				</Show>
+
+				<Show when={result()}>
+					{(r) => (
+						<div>
+							<div class="flex items-center gap-2 mb-1.5">
+								<span
+									class={`text-xs font-bold ${r().status < 400 ? "text-success" : "text-destructive"}`}
+								>
+									{r().status}
+								</span>
+								<span class="text-[11px] text-muted">{r().ms}ms</span>
+							</div>
+							<pre class="m-0 p-2 rounded border border-border bg-background text-xs font-mono text-foreground overflow-auto max-h-64 whitespace-pre-wrap">
+								{prettyResult()}
+							</pre>
+						</div>
+					)}
+				</Show>
+
+				<Show when={style() !== "cli" && style() !== "graphql"}>
+					<details class="text-xs text-muted">
+						<summary class="cursor-pointer select-none">cURL</summary>
+						<pre class="m-0 mt-1.5 p-2 rounded border border-border bg-background font-mono text-foreground overflow-auto whitespace-pre-wrap">
+							{buildCurl(ep(), resolvedUrl(), body())}
+						</pre>
+					</details>
+				</Show>
+			</div>
+		</div>
+	);
+}

package/src/runtime/components/AskAiDialog.tsx

@@ -0,0 +1,127 @@
+import { createSignal, Show } from "solid-js";
+import { useDocs } from "../context";
+import { DocMarkdown } from "./DocMarkdown";
+
+async function suggest(prompt: string): Promise<string> {
+	const res = await fetch("/api/ai/suggest", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ prompt }),
+	});
+	const data = (await res.json()) as { suggestion?: string; error?: string };
+	if (!res.ok) throw new Error(data.error ?? "AI request failed");
+	return data.suggestion ?? "";
+}
+
+export function AskAiDialog(props: {
+	open: boolean;
+	onClose: () => void;
+	collection: string;
+	docId: string;
+	docTitle: string;
+}) {
+	const [question, setQuestion] = createSignal("");
+	const [answer, setAnswer] = createSignal("");
+	const [loading, setLoading] = createSignal(false);
+	const [error, setError] = createSignal("");
+	const dataSource = useDocs().dataSource;
+
+	const ask = async () => {
+		const q = question().trim();
+		if (!q || loading()) return;
+		setLoading(true);
+		setError("");
+		setAnswer("");
+		try {
+			let answer = "";
+			if (dataSource.ask) {
+				const res = await dataSource.ask({
+					collection: props.collection,
+					id: props.docId,
+					question: q,
+				});
+				answer = res.answer;
+			} else {
+				answer = await suggest(`Document: ${props.docTitle}\nQuestion: ${q}`);
+			}
+			setAnswer(answer);
+		} catch (e) {
+			setError(e instanceof Error ? e.message : "Failed to get answer");
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	return (
+		<Show when={props.open}>
+			<div
+				class="fixed inset-0 z-50 bg-overlay flex items-start justify-center pt-20 px-4"
+				onClick={(e) => {
+					if (e.target === e.currentTarget) props.onClose();
+				}}
+				role="presentation"
+			>
+				<div class="w-full max-w-2xl rounded-lg border border-border bg-surface shadow-2xl overflow-hidden">
+					<div class="flex items-center gap-2 px-4 py-3 border-b border-border">
+						<span
+							class="i-mdi:robot-happy-outline text-primary"
+							aria-hidden="true"
+						/>
+						<span class="text-sm font-semibold text-foreground">
+							Ask AI about this page
+						</span>
+						<span class="text-xs text-muted truncate">— {props.docTitle}</span>
+						<button
+							type="button"
+							onClick={props.onClose}
+							aria-label="Close"
+							class="ml-auto w-8 h-8 inline-flex items-center justify-center rounded-md text-muted hover:text-foreground hover:bg-background transition-colors cursor-pointer border-none bg-transparent"
+						>
+							<span class="i-mdi:close" aria-hidden="true" />
+						</button>
+					</div>
+					<div class="p-4">
+						<div class="flex gap-2">
+							<textarea
+								value={question()}
+								onInput={(e) => setQuestion(e.currentTarget.value)}
+								onKeyDown={(e) => {
+									if (e.key === "Enter" && !e.shiftKey) {
+										e.preventDefault();
+										ask();
+									}
+								}}
+								placeholder="Ask a question about this document..."
+								aria-label="Question"
+								rows={2}
+								class="flex-1 px-3 py-2 rounded-md border border-border bg-background text-sm text-foreground placeholder:text-muted resize-none outline-none focus:border-focus"
+							/>
+							<button
+								type="button"
+								onClick={ask}
+								disabled={loading() || !question().trim()}
+								class="self-end inline-flex items-center gap-1.5 px-4 h-9 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary-hover transition-colors cursor-pointer border-none disabled:opacity-50 disabled:cursor-not-allowed"
+							>
+								<span
+									class={
+										loading() ? "i-mdi:loading animate-spin" : "i-mdi:send"
+									}
+									aria-hidden="true"
+								/>
+								{loading() ? "Asking…" : "Ask"}
+							</button>
+						</div>
+						<Show when={error()}>
+							<p class="mt-3 text-sm text-destructive">{error()}</p>
+						</Show>
+						<Show when={answer()}>
+							<div class="mt-4 pt-3 border-t border-border">
+								<DocMarkdown source={answer()} />
+							</div>
+						</Show>
+					</div>
+				</div>
+			</div>
+		</Show>
+	);
+}

package/src/runtime/components/BackToTop.tsx

@@ -0,0 +1,38 @@
+import { createEffect, createSignal, onCleanup, Show } from "solid-js";
+
+export function BackToTop() {
+	const [visible, setVisible] = createSignal(false);
+
+	createEffect(() => {
+		const onScroll = () => {
+			setVisible(window.scrollY > 400);
+		};
+
+		onScroll();
+		window.addEventListener("scroll", onScroll, { passive: true });
+		onCleanup(() => window.removeEventListener("scroll", onScroll));
+	});
+
+	const scrollToTop = () =>
+		window.scrollTo({
+			top: 0,
+			behavior: prefersReducedMotion() ? "auto" : "smooth",
+		});
+
+	return (
+		<Show when={visible()}>
+			<button
+				type="button"
+				onClick={scrollToTop}
+				class="fixed bottom-6 right-6 z-50 flex items-center justify-center w-10 h-10 rounded-full border border-border bg-surface text-foreground shadow-md hover:bg-primary hover:text-primary-foreground transition-colors"
+				aria-label="Back to top"
+			>
+				<span class="i-mdi:chevron-up" aria-hidden="true" />
+			</button>
+		</Show>
+	);
+}
+
+function prefersReducedMotion() {
+	return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}

package/src/runtime/components/Banner.tsx

@@ -0,0 +1,75 @@
+import { createSignal, onMount, Show } from "solid-js";
+import { useDocs } from "../context";
+
+const BANNER_HEIGHT_VAR = "--docs-banner-height";
+
+function setBannerHeight(height: number) {
+	document.documentElement.style.setProperty(BANNER_HEIGHT_VAR, `${height}px`);
+}
+
+export function Banner() {
+	const config = useDocs();
+	const banner = () => config.announcement;
+	const storageKey = "docs-banner-dismissed";
+	const [dismissed, setDismissed] = createSignal(false);
+
+	const isVisible = () => {
+		if (!banner()?.text) return false;
+		if (dismissed()) return false;
+		if (
+			banner()?.closable !== false &&
+			localStorage.getItem(storageKey) === "1"
+		) {
+			return false;
+		}
+		return true;
+	};
+
+	const dismiss = () => {
+		setDismissed(true);
+		setBannerHeight(0);
+		if (banner()?.closable !== false) {
+			localStorage.setItem(storageKey, "1");
+		}
+	};
+
+	onMount(() => {
+		if (!isVisible()) setBannerHeight(0);
+	});
+
+	return (
+		<Show when={isVisible()}>
+			<div
+				class="sticky top-0 z-50 w-full bg-primary text-primary-foreground text-sm"
+				ref={(el) => {
+					queueMicrotask(() => {
+						if (isVisible()) setBannerHeight(el.getBoundingClientRect().height);
+					});
+				}}
+			>
+				<div class="max-w-6xl mx-auto px-4 py-2 flex items-center justify-center gap-2">
+					<Show when={banner()?.to} fallback={<span>{banner()?.text}</span>}>
+						{(to) => (
+							<a
+								href={to()}
+								class="underline hover:no-underline text-primary-foreground"
+							>
+								{banner()?.text}
+							</a>
+						)}
+					</Show>
+					<Show when={banner()?.closable !== false}>
+						<button
+							type="button"
+							onClick={dismiss}
+							class="ml-2 inline-flex items-center justify-center w-6 h-6 rounded-full hover:bg-primary-foreground/20"
+							aria-label="Dismiss announcement"
+						>
+							<span class="i-mdi:close" aria-hidden="true" />
+						</button>
+					</Show>
+				</div>
+			</div>
+		</Show>
+	);
+}

package/src/runtime/components/Breadcrumbs.tsx

@@ -0,0 +1,42 @@
+import { Link } from "@tanstack/solid-router";
+import { useDocs } from "../context";
+import { useCollections } from "../data";
+
+export function Breadcrumbs(props: {
+	collection: string;
+	category: string;
+	label: string;
+}) {
+	const collections = useCollections();
+	const config = useDocs();
+	const collectionMeta = () =>
+		collections()?.find((c) => c.id === props.collection);
+
+	return (
+		<nav
+			aria-label="Breadcrumbs"
+			class="flex items-center gap-1.5 text-xs text-muted pb-3"
+		>
+			<Link to="/" class="hover:text-foreground transition-colors">
+				{config.site.title}
+			</Link>
+			<span class="i-mdi:chevron-right" aria-hidden="true" />
+			<Link
+				to={`/${props.collection}`}
+				class="hover:text-foreground transition-colors inline-flex items-center gap-1"
+			>
+				<span
+					class={collectionMeta()?.icon ?? "i-mdi:folder-outline"}
+					aria-hidden="true"
+				/>
+				<span>{collectionMeta()?.label ?? props.collection}</span>
+			</Link>
+			<span class="i-mdi:chevron-right" aria-hidden="true" />
+			<span>{props.category}</span>
+			<span class="i-mdi:chevron-right" aria-hidden="true" />
+			<span class="text-foreground font-medium truncate max-w-[16rem]">
+				{props.label}
+			</span>
+		</nav>
+	);
+}

package/src/runtime/components/CollectionDropdown.tsx

@@ -0,0 +1,85 @@
+import { Link } from "@tanstack/solid-router";
+import { createSignal, For, onCleanup, onMount, Show } from "solid-js";
+import { useCollections } from "../data";
+
+export function CollectionDropdown(props: { current: string | undefined }) {
+	const [open, setOpen] = createSignal(false);
+	const collections = useCollections();
+	let rootEl: HTMLDivElement | undefined;
+
+	const currentMeta = () => collections()?.find((c) => c.id === props.current);
+
+	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"
+				class="inline-flex items-center gap-2 px-3 h-9 rounded-md border border-border bg-surface text-sm text-foreground hover:border-focus transition-colors cursor-pointer"
+			>
+				<Show when={currentMeta()}>
+					<span class={currentMeta()!.icon} aria-hidden="true" />
+				</Show>
+				<span class="font-medium">
+					{currentMeta()?.label ?? "Select collection"}
+				</span>
+				<span
+					class={`i-mdi:chevron-down text-muted transition-transform ${open() ? "rotate-180" : ""}`}
+					aria-hidden="true"
+				/>
+			</button>
+			<Show when={open()}>
+				<ul
+					role="listbox"
+					aria-label="Documentation collections"
+					class="absolute left-0 top-full mt-2 min-w-56 rounded-lg border border-border bg-surface shadow-lg py-1 z-50 list-none m-0"
+				>
+					<For each={collections()}>
+						{(c) => (
+							<li role="option" aria-selected={c.id === props.current}>
+								<Link
+									to="/$collection"
+									params={{ collection: c.id }}
+									onClick={() => setOpen(false)}
+									class="flex items-start gap-3 px-3 py-2 text-sm no-underline transition-colors hover:bg-background"
+								>
+									<span
+										class={`${c.icon} mt-0.5 text-primary`}
+										aria-hidden="true"
+									/>
+									<span class="min-w-0">
+										<span
+											class={`block font-medium ${c.id === props.current ? "text-primary" : "text-foreground"}`}
+										>
+											{c.label}
+										</span>
+										<span class="block text-xs text-muted leading-snug">
+											{c.description}
+										</span>
+									</span>
+								</Link>
+							</li>
+						)}
+					</For>
+				</ul>
+			</Show>
+		</div>
+	);
+}