@wrikka/create-docs 0.1.0

package/src/runtime/components/VersionDropdown.tsx

@@ -0,0 +1,189 @@
+import {
+	createMemo,
+	createSignal,
+	For,
+	onCleanup,
+	onMount,
+	Show,
+} from "solid-js";
+import { useDocs } from "../context";
+import {
+	type BranchInfo,
+	type CommitInfo,
+	fetchBranches,
+	fetchLatestCommit,
+	fetchTags,
+	type TagInfo,
+} from "../github";
+
+interface VersionItem {
+	id: string;
+	label: string;
+	url?: string;
+	html_url?: string;
+	type: "tag" | "branch" | "commit" | "version";
+}
+
+export function VersionDropdown() {
+	const [open, setOpen] = createSignal(false);
+	const config = useDocs();
+	let rootEl: HTMLDivElement | undefined;
+
+	const [tags, setTags] = createSignal<TagInfo[]>([]);
+	const [branches, setBranches] = createSignal<BranchInfo[]>([]);
+	const [latest, setLatest] = createSignal<CommitInfo | null>(null);
+	const [loading, setLoading] = createSignal(false);
+	const [errored, setErrored] = createSignal(false);
+
+	onMount(async () => {
+		if (!config.github || config.versions) return;
+		setLoading(true);
+		try {
+			const [t, b, c] = await Promise.all([
+				fetchTags(config.github),
+				fetchBranches(config.github),
+				fetchLatestCommit(config.github, config.github.branch),
+			]);
+			setTags(t);
+			setBranches(b);
+			setLatest(c);
+		} catch {
+			setErrored(true);
+		} finally {
+			setLoading(false);
+		}
+	});
+
+	const currentLabel = () =>
+		config.versions?.current ??
+		config.github?.branch ??
+		latest()?.sha ??
+		"main";
+
+	const items = createMemo<VersionItem[]>(() => {
+		if (config.versions?.list.length) {
+			return config.versions.list.map((v) => ({
+				...v,
+				type: "version" as const,
+			}));
+		}
+		const github = config.github;
+		if (!github) return [];
+
+		const list: VersionItem[] = [];
+		if (latest()) {
+			list.push({
+				id: latest()!.sha,
+				label: `${latest()!.sha} — ${latest()!.message}`,
+				html_url: latest()!.html_url,
+				type: "commit",
+			});
+		}
+		for (const b of branches()) {
+			list.push({
+				id: b.name,
+				label: b.name,
+				html_url: `https://github.com/${github.owner}/${github.repo}/tree/${b.name}`,
+				type: "branch",
+			});
+		}
+		for (const t of tags()) {
+			list.push({
+				id: t.name,
+				label: t.name,
+				html_url: `https://github.com/${github.owner}/${github.repo}/releases/tag/${t.name}`,
+				type: "tag",
+			});
+		}
+		return list;
+	});
+
+	const hasData = () =>
+		(config.versions?.list.length ?? 0) > 1 || items().length > 0 || loading();
+
+	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 (
+		<Show when={hasData()}>
+			<div ref={rootEl} class="relative">
+				<button
+					type="button"
+					onClick={() => setOpen(!open())}
+					aria-expanded={open()}
+					aria-haspopup="listbox"
+					class="inline-flex items-center gap-1.5 px-2.5 h-9 rounded-md border border-border bg-surface text-xs font-medium text-foreground hover:border-focus transition-colors cursor-pointer"
+				>
+					<span class="i-mdi:tag-outline text-muted" aria-hidden="true" />
+					<span class="max-w-32 truncate">{currentLabel()}</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="Versions"
+						class="absolute right-0 top-full mt-2 min-w-52 max-h-72 overflow-auto rounded-lg border border-border bg-surface shadow-lg py-1 z-50 list-none m-0"
+					>
+						<Show when={loading()}>
+							<li class="px-3 py-2 text-xs text-muted">Loading…</li>
+						</Show>
+						<Show when={errored() && !loading()}>
+							<li class="px-3 py-2 text-xs text-destructive">
+								Could not load versions.
+							</li>
+						</Show>
+						<For each={items()}>
+							{(v) => (
+								<li role="option" aria-selected={v.id === currentLabel()}>
+									<a
+										href={v.url ?? v.html_url ?? "/"}
+										target={v.html_url ? "_blank" : undefined}
+										rel={v.html_url ? "noreferrer" : undefined}
+										onClick={() => setOpen(false)}
+										class={`block px-3 py-2 text-sm no-underline transition-colors hover:bg-background ${
+											v.id === currentLabel()
+												? "text-primary font-medium"
+												: "text-foreground"
+										}`}
+									>
+										<div class="flex items-center gap-2">
+											<span
+												class={`${
+													v.type === "commit"
+														? "i-mdi:source-commit"
+														: v.type === "tag"
+															? "i-mdi:tag"
+															: v.type === "branch"
+																? "i-mdi:source-branch"
+																: "i-mdi:source-branch"
+												} text-muted`}
+												aria-hidden="true"
+											/>
+											<span class="truncate">{v.label}</span>
+										</div>
+									</a>
+								</li>
+							)}
+						</For>
+					</ul>
+				</Show>
+			</div>
+		</Show>
+	);
+}

package/src/runtime/components/markdown/components.ts

@@ -0,0 +1,280 @@
+import type { ElementNode, NodeHandler } from "comark";
+
+const rand = () => Math.random().toString(36).slice(2, 8);
+
+function getAttr(
+	attrs: Record<string, unknown>,
+	key: string,
+): string | undefined {
+	return (attrs[key] as string) ?? undefined;
+}
+
+export const cardComponent: NodeHandler = async (node, state) => {
+	const [, attrs, ...children] = node;
+	const title = getAttr(attrs, "title");
+	const icon = getAttr(attrs, "icon");
+	const to = getAttr(attrs, "to");
+	const id = `card-${rand()}`;
+	const body = await state.render(children);
+
+	const inner = `
+		<div class="rt-card__header">
+			${icon ? `<span class="${icon} rt-card__icon" aria-hidden="true"></span>` : ""}
+			${title ? `<div class="rt-card__title">${title}</div>` : ""}
+		</div>
+		<div class="rt-card__body">${body}</div>
+	`;
+
+	if (to) {
+		return `<a href="${to}" class="rt-card rt-card--link" id="${id}">${inner}</a>`;
+	}
+	return `<div class="rt-card" id="${id}">${inner}</div>`;
+};
+
+export const cardGridComponent: NodeHandler = async (node, state) => {
+	const [, , ...children] = node;
+	const rendered = await state.render(children);
+	return `<div class="rt-card-grid">${rendered}</div>`;
+};
+
+export const tabsComponent: NodeHandler = async (node, state) => {
+	const [, , ...children] = node;
+	const tabs: { id: string; label: string; body: string }[] = [];
+
+	for (const child of children) {
+		const el = child as ElementNode;
+		if (el[0] !== "tab") continue;
+		const [, cAttrs, ...cChildren] = el;
+		const label = getAttr(cAttrs, "label") ?? "Tab";
+		const id = `tab-${rand()}`;
+		const body = await state.render(cChildren);
+		tabs.push({ id, label, body });
+	}
+
+	if (!tabs.length) return "";
+
+	const tabList = tabs
+		.map(
+			(t, i) =>
+				`<button type="button" class="rt-tabs__tab${i === 0 ? " rt-tabs__tab--active" : ""}" data-tab="${t.id}" role="tab" aria-selected="${i === 0 ? "true" : "false"}">${t.label}</button>`,
+		)
+		.join("");
+
+	const panels = tabs
+		.map(
+			(t, i) =>
+				`<div class="rt-tabs__panel${i === 0 ? " rt-tabs__panel--active" : ""}" id="${t.id}" role="tabpanel">${t.body}</div>`,
+		)
+		.join("");
+
+	return `<div class="rt-tabs">
+		<div class="rt-tabs__list" role="tablist">${tabList}</div>
+		${panels}
+	</div>`;
+};
+
+export const fileTreeComponent: NodeHandler = async (node) => {
+	const [, , ...children] = node;
+
+	async function renderTree(items: ElementNode[], depth = 0): Promise<string> {
+		const out: string[] = [];
+		for (const item of items) {
+			const tag = item[0] as string;
+			const attrs = item[1] as Record<string, unknown>;
+			const cChildren = item.slice(2) as ElementNode[];
+			const name = getAttr(attrs, "name") ?? "unknown";
+
+			if (tag === "folder") {
+				const nested = cChildren.length
+					? `<ul class="rt-file-tree__nested">${await renderTree(cChildren, depth + 1)}</ul>`
+					: "";
+				out.push(`
+					<li class="rt-file-tree__item rt-file-tree__item--folder" style="--rt-ft-depth: ${depth}">
+						<span class="rt-file-tree__label">
+							<span class="i-mdi:folder-outline rt-file-tree__icon" aria-hidden="true"></span>
+							${name}
+						</span>
+						${nested}
+					</li>
+				`);
+			} else if (tag === "file") {
+				out.push(`
+					<li class="rt-file-tree__item rt-file-tree__item--file" style="--rt-ft-depth: ${depth}">
+						<span class="rt-file-tree__label">
+							<span class="i-mdi:file-document-outline rt-file-tree__icon" aria-hidden="true"></span>
+							${name}
+						</span>
+					</li>
+				`);
+			}
+		}
+		return out.join("");
+	}
+
+	const valid = children.filter(
+		(c) =>
+			(c as ElementNode)[0] === "folder" || (c as ElementNode)[0] === "file",
+	) as ElementNode[];
+	if (!valid.length) return "";
+
+	return `<ul class="rt-file-tree">${await renderTree(valid)}</ul>`;
+};
+
+export const kbdComponent: NodeHandler = async (node, state) => {
+	const [, , ...children] = node;
+	const text = (await state.render(children)).replace(/<[^>]+>/g, "");
+	return `<kbd class="rt-kbd">${text}</kbd>`;
+};
+
+export const badgeComponent: NodeHandler = async (node, state) => {
+	const [, attrs, ...children] = node;
+	const text = getAttr(attrs, "text") ?? (await state.render(children));
+	const type = getAttr(attrs, "type") ?? "default";
+	return `<span class="rt-badge rt-badge--${type}">${text}</span>`;
+};
+
+export const accordionComponent: NodeHandler = async (node, state) => {
+	const [, attrs, ...children] = node;
+	const title = getAttr(attrs, "title");
+	const id = `acc-${rand()}`;
+
+	// <accordion title="..."> ... content ... </accordion>
+	if (title) {
+		const body = await state.render(children);
+		return `<details class="rt-accordion" id="${id}">
+			<summary class="rt-accordion__summary">${title}</summary>
+			<div class="rt-accordion__body">${body}</div>
+		</details>`;
+	}
+
+	// <accordion> <item title="...">...</item> ... </accordion>
+	const items: { title: string; body: string }[] = [];
+	for (const child of children) {
+		const el = child as ElementNode;
+		if (el[0] !== "item") continue;
+		const [, cAttrs, ...cChildren] = el;
+		const itemTitle = getAttr(cAttrs, "title") ?? "Item";
+		const body = await state.render(cChildren);
+		items.push({ title: itemTitle, body });
+	}
+
+	if (!items.length) return await state.render(children);
+
+	return `<div class="rt-accordion-group">
+		${items
+			.map(
+				(item, i) => `
+				<details class="rt-accordion" id="${id}-${i}">
+					<summary class="rt-accordion__summary">${item.title}</summary>
+					<div class="rt-accordion__body">${item.body}</div>
+				</details>
+			`,
+			)
+			.join("")}
+	</div>`;
+};
+
+const videoHosts = new Set([
+	"youtube.com",
+	"www.youtube.com",
+	"youtu.be",
+	"vimeo.com",
+]);
+
+export const youtubeComponent: NodeHandler = async (node) => {
+	const [, attrs] = node;
+	const id = getAttr(attrs, "id");
+	if (!id) return "";
+	return `<div class="rt-youtube" data-id="${id}" role="img" aria-label="YouTube video">
+		<button type="button" class="rt-youtube__play" aria-label="Play video">
+			<span class="i-mdi:play-circle text-5xl" aria-hidden="true"></span>
+		</button>
+	</div>`;
+};
+
+export const videoComponent: NodeHandler = async (node) => {
+	const [, attrs] = node;
+	const src = getAttr(attrs, "src");
+	if (!src) return "";
+
+	try {
+		const url = new URL(src);
+		if (!videoHosts.has(url.hostname)) {
+			return `<p class="rt-markdown__error">Unsupported video host: ${url.hostname}</p>`;
+		}
+	} catch {
+		return `<p class="rt-markdown__error">Invalid video URL</p>`;
+	}
+
+	return `<div class="rt-video" data-src="${src}">
+		<a href="${src}" target="_blank" rel="noreferrer" class="rt-video__link">Watch video</a>
+	</div>`;
+};
+
+export const timelineComponent: NodeHandler = async (node, state) => {
+	const [, , ...children] = node;
+	const events: { date?: string; title?: string; body: string }[] = [];
+
+	for (const child of children) {
+		const el = child as ElementNode;
+		if (el[0] !== "event") continue;
+		const [, cAttrs, ...cChildren] = el;
+		const body = await state.render(cChildren);
+		events.push({
+			date: getAttr(cAttrs, "date"),
+			title: getAttr(cAttrs, "title"),
+			body,
+		});
+	}
+
+	if (!events.length) return await state.render(children);
+
+	return `<ol class="rt-timeline">
+		${events
+			.map(
+				(e) => `
+				<li class="rt-timeline__item">
+					<div class="rt-timeline__dot" aria-hidden="true"></div>
+					<div class="rt-timeline__content">
+						${e.date ? `<time class="rt-timeline__date">${e.date}</time>` : ""}
+						${e.title ? `<div class="rt-timeline__title">${e.title}</div>` : ""}
+						<div class="rt-timeline__body">${e.body}</div>
+					</div>
+				</li>
+			`,
+			)
+			.join("")}
+	</ol>`;
+};
+
+export const tooltipComponent: NodeHandler = async (node, state) => {
+	const [, attrs, ...children] = node;
+	const text = getAttr(attrs, "text") ?? (await state.render(children));
+	const tip = getAttr(attrs, "tip") ?? "";
+	const id = `tt-${rand()}`;
+	return `<span class="rt-tooltip" id="${id}" data-tip="${tip}" tabindex="0">${text}</span>`;
+};
+
+export const copyComponent: NodeHandler = async (node, state) => {
+	const [, attrs, ...children] = node;
+	const value = getAttr(attrs, "value");
+	if (!value) return await state.render(children);
+	const id = `cp-${rand()}`;
+	return `<button type="button" class="rt-copy" id="${id}" data-copy="${value}" aria-label="Copy to clipboard">${getAttr(attrs, "label") ?? value}</button>`;
+};
+
+export const codePreviewComponent: NodeHandler = async (node, state) => {
+	const [, , ...children] = node;
+	const rendered = await state.render(children);
+	const code = rendered
+		.replace(/<[^>]+>/g, "")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&amp;/g, "&")
+		.trim();
+	const id = `preview-${rand()}`;
+	return `<div class="rt-code-preview" id="${id}" data-code="${code.replace(/"/g, "&quot;")}">
+		<div class="rt-code-preview__result" aria-live="polite"></div>
+		<pre class="rt-code-preview__code"><code>${rendered}</code></pre>
+	</div>`;
+};

package/src/runtime/config.ts

@@ -0,0 +1,225 @@
+import type { ApiEndpoint, CollectionMeta } from "./types";
+
+export interface HomeFeature {
+	icon?: string;
+	title: string;
+	details?: string;
+	link?: string;
+}
+
+export interface HomeConfig {
+	hero?: {
+		name?: string;
+		text?: string;
+		tagline?: string;
+		/** Small pill badge above the headline. */
+		badge?: string;
+		actions?: { text: string; link: string; theme?: "brand" | "alt" }[];
+	};
+	features?: HomeFeature[];
+	/** Items for the horizontal feature slider. Defaults to `features`. */
+	slides?: HomeFeature[];
+}
+
+/** A static API collection — endpoints parsed up front (OpenAPI/oRPC adapters). */
+export interface ApiCollection extends CollectionMeta {
+	type: "api";
+	/** API style — shown as a badge on the reference pages. */
+	style?: "rest" | "graphql" | "cli" | "rpc";
+	endpoints: ApiEndpoint[];
+}
+
+export interface DocsAppFeatures {
+	search?: boolean;
+	askAi?: boolean;
+	editLink?: boolean;
+	lastUpdated?: boolean;
+	toc?: boolean;
+	aside?: boolean;
+	themeToggle?: boolean;
+	breadcrumbs?: boolean;
+	reportIssue?: boolean;
+	openPR?: boolean;
+	rss?: boolean;
+	sitemap?: boolean;
+	pwa?: boolean;
+	/** Local page-view analytics + /analytics dashboard. */
+	analytics?: boolean;
+	/** Show a toggle to reveal/hide the document frontmatter on doc pages. */
+	frontmatterToggle?: boolean;
+	/** Show an "MCP available" badge linking to the JSON-RPC endpoint. */
+	mcp?: boolean;
+}
+
+export interface MarkdownConfig {
+	engine?: "comark" | "marked";
+}
+
+/** A documentation version entry for the version switcher. */
+export interface DocsVersion {
+	/** Unique version id, e.g. "v2". */
+	id: string;
+	/** Display label, e.g. "v2 (latest)". */
+	label: string;
+	/** URL where this version is hosted — absolute URL or site path. Omit for the current site. */
+	url?: string;
+}
+
+export interface VersionsConfig {
+	/** Id of the version currently rendered. */
+	current: string;
+	list: DocsVersion[];
+}
+
+/** A locale entry for the language switcher. */
+export interface LocaleInfo {
+	/** BCP 47 language tag, e.g. "en", "th". */
+	id: string;
+	/** Display label, e.g. "English", "ไทย". */
+	label: string;
+	/** URL of the localized site (absolute or path). Omit for the current site. */
+	url?: string;
+}
+
+export interface I18nConfig {
+	/** BCP 47 tag of the current locale — also applied to `<html lang>`. */
+	current: string;
+	list: LocaleInfo[];
+}
+
+/** A plugin/integration entry shown on the `/plugins` marketplace page. */
+export interface PluginInfo {
+	/** Package name, e.g. "@wrikka/create-docs-openapi". */
+	name: string;
+	/** Short description of what the plugin provides. */
+	description: string;
+	/** Optional Iconify icon class, e.g. "i-mdi:api". */
+	icon?: string;
+	/** Optional link to docs or repository. */
+	url?: string;
+	/** Optional version/tag badge. */
+	version?: string;
+	/** Install command shown on the card, e.g. "bun add @wrikka/x". Omit for built-in integrations. */
+	install?: string;
+}
+
+export interface ShowcaseInfo {
+	/** Unique id for the showcase item. */
+	id: string;
+	/** Display label. */
+	label: string;
+	/** Short description. */
+	description: string;
+	/** Optional cover image URL. */
+	image?: string;
+	/** Optional Iconify icon class used as fallback. */
+	icon?: string;
+	/** Optional link to the project/case. */
+	link?: string;
+	/** Optional tags. */
+	tags?: string[];
+	/** Optional badge. */
+	badge?: string;
+	/** Optional gradient cover color (hex) when no image is provided. */
+	coverColor?: string;
+}
+
+export interface GitHubOAuthConfig {
+	/** Set to false to hide the "Authorize with GitHub" flow. Defaults to true. */
+	enabled?: boolean;
+	/**
+	 * Optional public OAuth client id. The real client id/secret are resolved
+	 * server-side via `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` secrets, so
+	 * this is not required by the client.
+	 */
+	clientId?: string;
+	/** OAuth callback URL. Defaults to `${location.origin}/auth/github/callback`. */
+	redirectUri?: string;
+	/** Requested OAuth scopes. Defaults to "repo". */
+	scope?: string;
+}
+
+export interface GitHubConfig {
+	owner: string;
+	repo: string;
+	branch?: string;
+	stats?: boolean;
+	releases?: boolean;
+	contributors?: boolean;
+	issues?: boolean;
+	oauth?: GitHubOAuthConfig;
+}
+
+export interface SiteLink {
+	label: string;
+	to: string;
+	icon?: string;
+}
+
+export interface FooterConfig {
+	copyright?: string;
+	links?: SiteLink[];
+}
+
+export interface AnnouncementConfig {
+	text: string;
+	to?: string;
+	closable?: boolean;
+}
+
+export interface SiteConfig {
+	title: string;
+	description?: string;
+	repoUrl?: string;
+	url?: string;
+	ogImage?: string;
+	/** Optional logo icon class. */
+	logo?: string;
+	/** Optional social / external links. */
+	social?: {
+		npm?: string;
+		twitter?: string;
+		discord?: string;
+		youtube?: string;
+		mastodon?: string;
+	};
+}
+
+export interface DocsAppConfig {
+	site: SiteConfig;
+	/** GitHub integration options. */
+	github?: GitHubConfig;
+	/** Injected data source for markdown doc collections. */
+	dataSource: import("./types").DocsDataSource;
+	/** Default collection used for "/" redirect when no home config. */
+	defaultCollection?: string;
+	/** VitePress-style home page. When set, "/" renders the home layout. */
+	home?: HomeConfig;
+	/** API reference collections (Scalar-style). */
+	apiCollections?: ApiCollection[];
+	/**
+	 * API diff/changelog: a snapshot of previous API collections to compare
+	 * against `apiCollections`. Enables the `/api-diff` page.
+	 */
+	apiDiff?: { previous: ApiCollection[] };
+	features?: DocsAppFeatures;
+	/** Markdown rendering engine configuration. */
+	markdown?: MarkdownConfig;
+	/** Versioned docs: shows a version switcher when more than one entry is listed. */
+	versions?: VersionsConfig;
+	/** Multi-language docs: shows a language switcher and sets `<html lang>`. */
+	i18n?: I18nConfig;
+	/** Optional analytics sink: page views are beaconed to this endpoint. */
+	analytics?: { endpoint?: string };
+	/** Plugin marketplace: entries listed on the `/plugins` page. */
+	plugins?: PluginInfo[];
+	/** Showcase / featured-work grid used by the `/showcase` page. */
+	showcase?: ShowcaseInfo[];
+	theme?: { defaultMode?: "dark" | "light" };
+	/** Optional fixed announcement banner. */
+	announcement?: AnnouncementConfig;
+	/** Optional footer configuration. */
+	footer?: FooterConfig;
+	/** Optional top navigation links. */
+	topNav?: SiteLink[];
+}