@axerity/cli 0.1.0

package/src/lib/components/docs/SearchDialog.svelte

@@ -0,0 +1,182 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { fade, scale } from 'svelte/transition';
+	import { create, insertMultiple, search } from '@orama/orama';
+	import SearchIcon from '@lucide/svelte/icons/search';
+	import FileText from '@lucide/svelte/icons/file-text';
+	import CornerDownLeft from '@lucide/svelte/icons/corner-down-left';
+	import { searchState } from '$lib/state/search.svelte';
+
+	interface Doc {
+		title: string;
+		section: string;
+		description: string;
+		href: string;
+	}
+
+	let term = $state('');
+	let results = $state<Doc[]>([]);
+	let activeIndex = $state(0);
+	let loaded = $state(false);
+	let input = $state<HTMLInputElement>();
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const orama: { db: any } = { db: null };
+
+	const schema = {
+		title: 'string',
+		section: 'string',
+		description: 'string',
+		content: 'string',
+		href: 'string'
+	} as const;
+
+	async function ensureLoaded() {
+		if (orama.db) return;
+		const docs = await (await fetch('/search.json')).json();
+		orama.db = create({ schema });
+		await insertMultiple(orama.db, docs);
+		loaded = true;
+	}
+
+	$effect(() => {
+		function onKey(event: KeyboardEvent) {
+			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+				event.preventDefault();
+				searchState.toggle();
+			} else if (event.key === 'Escape' && searchState.open) {
+				searchState.open = false;
+			}
+		}
+		window.addEventListener('keydown', onKey);
+		return () => window.removeEventListener('keydown', onKey);
+	});
+
+	$effect(() => {
+		if (searchState.open) {
+			ensureLoaded();
+			setTimeout(() => input?.focus(), 0);
+		} else {
+			term = '';
+			results = [];
+			activeIndex = 0;
+		}
+	});
+
+	$effect(() => {
+		const query = term.trim();
+		if (!query || !loaded || !orama.db) {
+			results = [];
+			return;
+		}
+		Promise.resolve(
+			search(orama.db, {
+				term: query,
+				properties: ['title', 'description', 'content', 'section'],
+				boost: { title: 4, description: 2 },
+				tolerance: 1,
+				limit: 8
+			})
+		).then((response) => {
+			results = response.hits.map((hit: { document: Doc }) => hit.document);
+			activeIndex = 0;
+		});
+	});
+
+	function go(href: string) {
+		searchState.open = false;
+		goto(href);
+	}
+
+	function onInputKey(event: KeyboardEvent) {
+		if (event.key === 'ArrowDown') {
+			event.preventDefault();
+			activeIndex = Math.min(activeIndex + 1, results.length - 1);
+		} else if (event.key === 'ArrowUp') {
+			event.preventDefault();
+			activeIndex = Math.max(activeIndex - 1, 0);
+		} else if (event.key === 'Enter' && results[activeIndex]) {
+			event.preventDefault();
+			go(results[activeIndex].href);
+		}
+	}
+</script>
+
+{#if searchState.open}
+	<div class="fixed inset-0 z-60 flex items-start justify-center px-4 pt-[12vh]">
+		<button
+			type="button"
+			class="absolute inset-0 cursor-default bg-black/50 backdrop-blur-sm"
+			aria-label="Close search"
+			onclick={() => (searchState.open = false)}
+			transition:fade={{ duration: 120 }}
+		></button>
+
+		<div
+			class="relative w-full max-w-xl overflow-hidden rounded-xl border border-border bg-surface shadow-2xl"
+			transition:scale={{ duration: 130, start: 0.97 }}
+		>
+			<div class="flex items-center gap-3 border-b border-border px-4">
+				<SearchIcon size={18} class="shrink-0 text-fg-subtle" />
+				<input
+					bind:this={input}
+					bind:value={term}
+					onkeydown={onInputKey}
+					type="text"
+					placeholder="Search documentation…"
+					class="w-full border-0 bg-transparent py-3.5 text-sm text-fg shadow-none outline-none placeholder:text-fg-subtle focus:border-0 focus:ring-0 focus:outline-none"
+				/>
+				<kbd
+					class="rounded border border-border bg-bg-subtle px-1.5 py-0.5 font-mono text-[10px] text-fg-subtle"
+				>
+					Esc
+				</kbd>
+			</div>
+
+			<div class="max-h-[60vh] overflow-y-auto p-2">
+				{#if term.trim() && results.length === 0}
+					<p class="px-3 py-8 text-center text-sm text-fg-subtle">
+						No results for “{term.trim()}”.
+					</p>
+				{:else if !term.trim()}
+					<p class="px-3 py-8 text-center text-sm text-fg-subtle">
+						Start typing to search the docs.
+					</p>
+				{:else}
+					<ul class="flex flex-col gap-0.5">
+						{#each results as result, index (result.href)}
+							<li>
+								<button
+									type="button"
+									onmouseenter={() => (activeIndex = index)}
+									onclick={() => go(result.href)}
+									class="flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition
+										{activeIndex === index ? 'bg-accent/10' : ''}"
+								>
+									<FileText size={16} class="shrink-0 text-fg-subtle" />
+									<span class="min-w-0 flex-1">
+										<span class="block truncate text-sm font-medium text-fg">{result.title}</span>
+										<span class="block truncate text-xs text-fg-subtle">
+											{result.section}{result.description ? ` · ${result.description}` : ''}
+										</span>
+									</span>
+									{#if activeIndex === index}
+										<CornerDownLeft size={14} class="shrink-0 text-fg-subtle" />
+									{/if}
+								</button>
+							</li>
+						{/each}
+					</ul>
+				{/if}
+			</div>
+
+			<div
+				class="flex items-center gap-3 border-t border-border px-4 py-2 text-[11px] text-fg-subtle"
+			>
+				<span><kbd class="font-mono">↑↓</kbd> navigate</span>
+				<span><kbd class="font-mono">↵</kbd> select</span>
+				<span class="ml-auto">Search by Orama</span>
+			</div>
+		</div>
+	</div>
+{/if}

package/src/lib/components/docs/Sidebar.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import type { Dropdown, NavEntry, NavSection, TopNavLink } from '$lib/types';
+	import { activeFor } from '$lib/nav-match';
+	import DynamicIcon from '$lib/components/DynamicIcon.svelte';
+	import SidebarLink from './SidebarLink.svelte';
+	import SidebarGroup from './SidebarGroup.svelte';
+	import SidebarDropdown from './SidebarDropdown.svelte';
+
+	let { sections, dropdowns }: { sections: NavSection[]; dropdowns?: Dropdown[] } = $props();
+
+	const activeDropdown = $derived(
+		dropdowns && dropdowns.length
+			? (activeFor(page.url.pathname, dropdowns) ?? dropdowns[0])
+			: undefined
+	);
+
+	const tabs = $derived(activeDropdown?.tabs ?? []);
+	const activeTab = $derived(
+		tabs.length ? (activeFor(page.url.pathname, tabs) ?? tabs[0]) : undefined
+	);
+
+	function firstHref(entries: NavEntry[]): string | undefined {
+		for (const entry of entries) {
+			const href = 'href' in entry ? entry.href : firstHref(entry.items);
+			if (href) return href;
+		}
+		return undefined;
+	}
+
+	function pruneByTab(entries: NavEntry[], tabList: TopNavLink[], target: TopNavLink): NavEntry[] {
+		const result: NavEntry[] = [];
+		for (const entry of entries) {
+			if ('href' in entry) {
+				if (activeFor(entry.href, tabList) === target) result.push(entry);
+			} else {
+				const items = pruneByTab(entry.items, tabList, target);
+				if (items.length) result.push({ ...entry, items });
+			}
+		}
+		return result;
+	}
+
+	const visibleSections = $derived.by(() => {
+		let result = sections;
+		if (dropdowns && activeDropdown) {
+			result = result.filter((section) => {
+				const href = firstHref(section.items);
+				return !href || activeFor(href, dropdowns) === activeDropdown;
+			});
+		}
+		if (tabs.length && activeTab) {
+			result = result
+				.map((section) => ({ ...section, items: pruneByTab(section.items, tabs, activeTab) }))
+				.filter((section) => section.items.length);
+		}
+		return result;
+	});
+</script>
+
+<nav class="flex flex-col gap-6" aria-label="Documentation">
+	{#if dropdowns && dropdowns.length && activeDropdown}
+		<SidebarDropdown {dropdowns} active={activeDropdown} />
+	{/if}
+
+	{#each visibleSections as section (section.title)}
+		<div class="flex flex-col gap-0.5">
+			<h2
+				class="mb-1 flex items-center gap-2 px-3 text-xs font-semibold tracking-wide text-fg-subtle uppercase"
+			>
+				{#if section.icon}
+					<DynamicIcon name={section.icon} size={14} />
+				{/if}
+				{section.title}
+			</h2>
+			{#each section.items as entry ('href' in entry ? entry.href : entry.title)}
+				{#if 'href' in entry}
+					<SidebarLink item={entry} />
+				{:else}
+					<SidebarGroup group={entry} />
+				{/if}
+			{/each}
+		</div>
+	{/each}
+</nav>

package/src/lib/components/docs/SidebarDropdown.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import { fade } from 'svelte/transition';
+	import ChevronDown from '@lucide/svelte/icons/chevron-down';
+	import Check from '@lucide/svelte/icons/check';
+	import DynamicIcon from '$lib/components/DynamicIcon.svelte';
+	import type { Dropdown } from '$lib/types';
+
+	let { dropdowns, active }: { dropdowns: Dropdown[]; active: Dropdown } = $props();
+
+	let open = $state(false);
+</script>
+
+<div class="relative mb-5">
+	<button
+		type="button"
+		onclick={() => (open = !open)}
+		aria-expanded={open}
+		class="flex w-full items-center gap-2.5 rounded-lg border border-border bg-surface px-3 py-2.5 text-sm font-medium text-fg transition hover:border-border-strong"
+	>
+		{#if active.icon}
+			<DynamicIcon name={active.icon} size={16} class="text-fg-muted" />
+		{/if}
+		<span class="flex-1 text-left">{active.label}</span>
+		<ChevronDown size={15} class="text-fg-subtle transition-transform {open ? 'rotate-180' : ''}" />
+	</button>
+
+	{#if open}
+		<button
+			type="button"
+			class="fixed inset-0 z-40 cursor-default"
+			aria-label="Close"
+			onclick={() => (open = false)}
+		></button>
+		<div
+			class="absolute right-0 left-0 z-50 mt-1.5 overflow-hidden rounded-lg border border-border bg-surface-raised p-1 shadow-lg"
+			transition:fade={{ duration: 100 }}
+		>
+			{#each dropdowns as dropdown (dropdown.label)}
+				<a
+					href={dropdown.href}
+					onclick={() => (open = false)}
+					class="flex items-center gap-2.5 rounded-md px-2.5 py-2 text-sm transition hover:bg-bg-subtle
+						{dropdown === active ? 'font-medium text-fg' : 'text-fg-muted'}"
+				>
+					{#if dropdown.icon}
+						<DynamicIcon name={dropdown.icon} size={16} />
+					{/if}
+					<span class="flex-1">{dropdown.label}</span>
+					{#if dropdown === active}
+						<Check size={15} class="text-fg-subtle" />
+					{/if}
+				</a>
+			{/each}
+		</div>
+	{/if}
+</div>

package/src/lib/components/docs/SidebarFooterLinks.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import ArrowUpRight from '@lucide/svelte/icons/arrow-up-right';
+
+	let { links }: { links: { title: string; href: string }[] } = $props();
+</script>
+
+<div class="flex flex-col gap-0.5 border-t border-border pt-3">
+	{#each links as link (link.href)}
+		<a
+			href={link.href}
+			target="_blank"
+			rel="noreferrer"
+			class="group flex items-center justify-between gap-2 rounded-md px-3 py-1.5 text-sm text-fg-muted transition hover:bg-bg-subtle hover:text-fg"
+		>
+			<span>{link.title}</span>
+			<ArrowUpRight size={14} class="text-fg-subtle transition group-hover:text-fg-muted" />
+		</a>
+	{/each}
+</div>

package/src/lib/components/docs/SidebarGroup.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { slide } from 'svelte/transition';
+	import { page } from '$app/state';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import type { NavEntry, NavGroup } from '$lib/types';
+	import DynamicIcon from '$lib/components/DynamicIcon.svelte';
+	import SidebarLink from './SidebarLink.svelte';
+	import Self from './SidebarGroup.svelte';
+
+	let { group, depth = 0 }: { group: NavGroup; depth?: number } = $props();
+
+	function containsActive(items: NavEntry[], path: string): boolean {
+		return items.some((entry) =>
+			'href' in entry ? entry.href === path : containsActive(entry.items, path)
+		);
+	}
+
+	// Open when the meta sets `defaultOpen`, or when a descendant is the current
+	// page (so the active page is never hidden).
+	let open = $state(
+		untrack(() => group.defaultOpen === true || containsActive(group.items, page.url.pathname))
+	);
+
+	const key = (entry: NavEntry) => ('href' in entry ? entry.href : entry.title);
+</script>
+
+<div>
+	<button
+		type="button"
+		onclick={() => (open = !open)}
+		aria-expanded={open}
+		style="padding-left: {0.75 + depth * 0.75}rem"
+		class="group flex w-full items-center gap-2.5 rounded-md py-1.5 pr-3 text-sm font-medium text-fg-muted transition hover:bg-bg-subtle hover:text-fg"
+	>
+		{#if group.icon}
+			<DynamicIcon name={group.icon} size={16} class="text-fg-subtle" />
+		{/if}
+		<span class="flex-1 text-left">{group.title}</span>
+		<ChevronRight size={14} class="text-fg-subtle transition-transform {open ? 'rotate-90' : ''}" />
+	</button>
+
+	{#if open}
+		<div transition:slide={{ duration: 150 }} class="mt-0.5 flex flex-col gap-0.5">
+			{#each group.items as entry (key(entry))}
+				{#if 'href' in entry}
+					<SidebarLink item={entry} depth={depth + 1} />
+				{:else}
+					<Self group={entry} depth={depth + 1} />
+				{/if}
+			{/each}
+		</div>
+	{/if}
+</div>

package/src/lib/components/docs/SidebarLink.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import type { NavLink } from '$lib/types';
+	import DynamicIcon from '$lib/components/DynamicIcon.svelte';
+
+	let { item, depth = 0 }: { item: NavLink; depth?: number } = $props();
+
+	const active = $derived(page.url.pathname === item.href);
+</script>
+
+<a
+	href={item.href}
+	aria-current={active ? 'page' : undefined}
+	style="padding-left: {0.75 + depth * 0.75}rem"
+	class="group flex items-center gap-2.5 rounded-md py-1.5 pr-3 text-sm transition
+		{active
+		? 'bg-accent/10 font-medium text-accent'
+		: 'text-fg-muted hover:bg-bg-subtle hover:text-fg'}"
+>
+	{#if item.method}
+		<span class="method-badge" data-method={item.method.toUpperCase()}>
+			{item.method.toUpperCase()}
+		</span>
+	{:else if item.icon}
+		<DynamicIcon
+			name={item.icon}
+			size={16}
+			class={active ? 'text-accent' : 'text-fg-subtle group-hover:text-fg-muted'}
+		/>
+	{/if}
+	<span class="flex-1">{item.title}</span>
+	{#if item.badge}
+		<span
+			class="rounded-full bg-accent/15 px-1.5 py-0.5 text-[10px] font-semibold tracking-wide text-accent uppercase"
+		>
+			{item.badge}
+		</span>
+	{/if}
+</a>
+
+<style>
+	/* Color-coded HTTP method label, mirroring the <Endpoint> badge. */
+	.method-badge {
+		flex-shrink: 0;
+		width: 2.75rem;
+		font-family: var(--font-mono);
+		font-size: 0.6rem;
+		font-weight: 700;
+		letter-spacing: 0.02em;
+		color: var(--m);
+	}
+	.method-badge[data-method='GET'] {
+		--m: oklch(0.6 0.15 155);
+	}
+	.method-badge[data-method='POST'] {
+		--m: oklch(0.6 0.16 250);
+	}
+	.method-badge[data-method='PUT'] {
+		--m: oklch(0.68 0.15 75);
+	}
+	.method-badge[data-method='PATCH'] {
+		--m: oklch(0.62 0.19 300);
+	}
+	.method-badge[data-method='DELETE'] {
+		--m: oklch(0.62 0.21 25);
+	}
+</style>

package/src/lib/components/docs/TableOfContents.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { SvelteSet } from 'svelte/reactivity';
+	import type { TocEntry } from '$lib/types';
+
+	// Where to read headings from — the rendered markdown container.
+	let { containerId = 'doc-content' }: { containerId?: string } = $props();
+
+	let entries = $state<TocEntry[]>([]);
+	let activeId = $state<string | null>(null);
+
+	// Extract h2/h3 headings from the rendered content, re-running on navigation.
+	$effect(() => {
+		// Reading the pathname makes this effect re-run (re-extract) on navigation.
+		const pathname = page.url.pathname;
+		const container = document.getElementById(containerId);
+		if (!container || !pathname) {
+			entries = [];
+			return;
+		}
+		const headings = container.querySelectorAll<HTMLElement>('h2[id], h3[id]');
+		entries = Array.from(headings).map((h) => ({
+			id: h.id,
+			title: h.textContent?.trim() ?? '',
+			depth: h.tagName === 'H3' ? 3 : 2
+		}));
+	});
+
+	// Scroll-spy: highlight the heading nearest the top of the viewport.
+	$effect(() => {
+		if (entries.length === 0) return;
+
+		const elements = entries
+			.map((e) => document.getElementById(e.id))
+			.filter((el): el is HTMLElement => el !== null);
+
+		const visible = new SvelteSet<string>();
+		const observer = new IntersectionObserver(
+			(records) => {
+				for (const record of records) {
+					if (record.isIntersecting) visible.add(record.target.id);
+					else visible.delete(record.target.id);
+				}
+				const firstVisible = entries.find((e) => visible.has(e.id));
+				if (firstVisible) activeId = firstVisible.id;
+			},
+			{ rootMargin: '0px 0px -70% 0px', threshold: 0 }
+		);
+
+		for (const el of elements) observer.observe(el);
+		return () => observer.disconnect();
+	});
+</script>
+
+{#if entries.length > 0}
+	<nav class="flex flex-col gap-2 text-sm" aria-label="On this page">
+		<p class="px-3 text-xs font-semibold tracking-wide text-fg-subtle uppercase">On this page</p>
+		<ul class="flex flex-col gap-0.5">
+			{#each entries as entry (entry.id)}
+				{@const active = activeId === entry.id}
+				<li>
+					<a
+						href="#{entry.id}"
+						aria-current={active ? 'location' : undefined}
+						class="block border-l-2 py-1 pr-3 transition
+							{entry.depth === 3 ? 'pl-6' : 'pl-3'}
+							{active
+							? 'border-accent font-medium text-accent'
+							: 'border-transparent text-fg-subtle hover:text-fg'}"
+					>
+						{entry.title}
+					</a>
+				</li>
+			{/each}
+		</ul>
+	</nav>
+{/if}

package/src/lib/components/docs/ThemeToggle.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import Sun from '@lucide/svelte/icons/sun';
+	import Moon from '@lucide/svelte/icons/moon';
+	import { theme } from '$lib/state/theme.svelte';
+</script>
+
+<button
+	type="button"
+	onclick={() => theme.toggle()}
+	class="inline-flex h-9 w-9 items-center justify-center rounded-lg border border-border text-fg-muted transition hover:border-border-strong hover:bg-bg-subtle hover:text-fg"
+	aria-label="Toggle theme"
+	title={theme.resolved === 'dark' ? 'Switch to light' : 'Switch to dark'}
+>
+	{#if theme.resolved === 'dark'}
+		<Moon size={17} />
+	{:else}
+		<Sun size={17} />
+	{/if}
+</button>

package/src/lib/components/docs/VersionSwitcher.svelte

@@ -0,0 +1,80 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { base } from '$app/paths';
+	import { fade } from 'svelte/transition';
+	import ChevronDown from '@lucide/svelte/icons/chevron-down';
+	import Check from '@lucide/svelte/icons/check';
+	import type { Version } from '$lib/types';
+
+	let {
+		versions,
+		resolveVersion
+	}: {
+		versions: Version[];
+		resolveVersion?: (pathname: string, versionPath: string) => string;
+	} = $props();
+
+	let open = $state(false);
+
+	const stripBase = (path: string): string =>
+		base && path.startsWith(base) ? path.slice(base.length) : path;
+
+	const sorted = $derived(
+		[...versions].sort((a, b) => stripBase(b.href).length - stripBase(a.href).length)
+	);
+
+	const current = $derived(
+		sorted.find((version) => {
+			const vp = stripBase(version.href);
+			const path = stripBase(page.url.pathname);
+			return vp === '/' ? true : path === vp || path.startsWith(`${vp}/`);
+		}) ?? versions[0]
+	);
+
+	const hrefFor = (version: Version): string => {
+		const vp = stripBase(version.href);
+		if (resolveVersion) return resolveVersion(page.url.pathname, vp);
+		const cur = stripBase(current.href);
+		const rest = vp === '/' || cur === '/' ? '' : stripBase(page.url.pathname).slice(cur.length);
+		return base + (vp === '/' ? rest || '/' : vp + rest);
+	};
+</script>
+
+<div class="relative">
+	<button
+		type="button"
+		onclick={() => (open = !open)}
+		aria-expanded={open}
+		class="flex items-center gap-1.5 rounded-md border border-border bg-surface px-2.5 py-1.5 text-xs font-medium text-fg-muted transition hover:border-border-strong hover:text-fg"
+	>
+		{current.label}
+		<ChevronDown size={13} class="text-fg-subtle transition-transform {open ? 'rotate-180' : ''}" />
+	</button>
+
+	{#if open}
+		<button
+			type="button"
+			class="fixed inset-0 z-40 cursor-default"
+			aria-label="Close versions"
+			onclick={() => (open = false)}
+		></button>
+		<div
+			class="absolute left-0 z-50 mt-1.5 w-36 overflow-hidden rounded-lg border border-border bg-surface-raised p-1 shadow-lg"
+			transition:fade={{ duration: 100 }}
+		>
+			{#each versions as version (version.label)}
+				<a
+					href={hrefFor(version)}
+					onclick={() => (open = false)}
+					class="flex items-center justify-between rounded-md px-2.5 py-1.5 text-sm transition hover:bg-bg-subtle
+						{version === current ? 'text-fg' : 'text-fg-muted'}"
+				>
+					{version.label}
+					{#if version === current}
+						<Check size={14} class="text-fg-subtle" />
+					{/if}
+				</a>
+			{/each}
+		</div>
+	{/if}
+</div>