svelte-docsmith 0.8.0 → 0.9.0

package/dist/components/changelog/changelog-entry.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+	import type { ChangelogRelease } from '../../core/changelog.js';
+
+	const { release }: { release: ChangelogRelease } = $props();
+
+	const formatted = $derived(
+		release.date
+			? new Date(release.date).toLocaleDateString('en-US', {
+					year: 'numeric',
+					month: 'long',
+					day: 'numeric'
+				})
+			: undefined
+	);
+</script>
+
+<!-- The version is the anchor the feed links to, so it carries the id. -->
+<section id={release.version} class="scroll-mt-24">
+	<div class="flex flex-wrap items-baseline gap-x-3 gap-y-1">
+		<h2 class="text-2xl font-semibold tracking-tight">
+			{#if release.path}
+				<a href={release.path} class="hover:text-primary transition-colors">{release.version}</a>
+			{:else}
+				{release.version}
+			{/if}
+		</h2>
+		{#if formatted}
+			<time datetime={release.date} class="text-muted-foreground text-sm">{formatted}</time>
+		{/if}
+	</div>
+
+	{#each release.groups as group (group.kind)}
+		<h3 class="text-muted-foreground mt-6 text-xs font-semibold tracking-wide uppercase">
+			{group.kind}
+		</h3>
+		<ul class="mt-3 space-y-4">
+			{#each group.items as item (item)}
+				<li class="border-border/70 border-l-2 pl-4">
+					<!-- Rendered at build time from your own repository's changelog. -->
+					<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+					<div class="changelog-prose">{@html item}</div>
+				</li>
+			{/each}
+		</ul>
+	{/each}
+</section>
+
+<style>
+	/* The entries arrive as HTML fragments rather than flowing through the
+	   markdown layout's prose styles, so they need their own small set. */
+	.changelog-prose :global(p) {
+		margin: 0 0 0.75rem;
+		line-height: 1.65;
+	}
+	.changelog-prose :global(p:last-child) {
+		margin-bottom: 0;
+	}
+	.changelog-prose :global(code) {
+		font-family: var(--font-mono, ui-monospace, monospace);
+		font-size: 0.85em;
+		padding: 0.05em 0.3em;
+		border-radius: 0.3rem;
+		background: color-mix(in oklch, var(--muted) 60%, transparent);
+	}
+	.changelog-prose :global(a) {
+		color: var(--primary);
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+	.changelog-prose :global(ul) {
+		margin: 0.5rem 0 0.75rem;
+		padding-left: 1.1rem;
+		list-style: disc;
+	}
+	.changelog-prose :global(li) {
+		margin: 0.25rem 0;
+	}
+	.changelog-prose :global(pre) {
+		margin: 0.75rem 0;
+		padding: 0.75rem 1rem;
+		border-radius: var(--radius, 0.5rem);
+		background: var(--muted);
+		overflow-x: auto;
+		font-size: 0.85em;
+	}
+	.changelog-prose :global(pre code) {
+		background: none;
+		padding: 0;
+	}
+</style>

package/dist/components/changelog/changelog-entry.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { ChangelogRelease } from '../../core/changelog.js';
+type $$ComponentProps = {
+    release: ChangelogRelease;
+};
+declare const ChangelogEntry: import("svelte").Component<$$ComponentProps, {}, "">;
+type ChangelogEntry = ReturnType<typeof ChangelogEntry>;
+export default ChangelogEntry;

package/dist/components/changelog/changelog.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import type { ChangelogRelease } from '../../core/changelog.js';
+	import ChangelogEntry from './changelog-entry.svelte';
+
+	const {
+		releases,
+		title = 'Changelog',
+		description,
+		feed = '/changelog.xml'
+	}: {
+		/** Releases from the generated `svelte-docsmith/changelog` index. */
+		releases: ChangelogRelease[];
+		/** Page heading. */
+		title?: string;
+		/** Line below the heading. */
+		description?: string;
+		/** Path to the Atom feed, or `false` to hide the subscribe link. */
+		feed?: string | false;
+	} = $props();
+</script>
+
+<div class="mx-auto max-w-3xl px-4 py-16 md:px-6 lg:py-20">
+	<header class="mb-12">
+		<h1 class="text-4xl font-semibold tracking-tight text-balance sm:text-5xl">{title}</h1>
+		{#if description}
+			<p class="text-muted-foreground mt-4 text-lg leading-relaxed text-pretty">{description}</p>
+		{/if}
+		{#if feed}
+			<a
+				href={feed}
+				class="text-muted-foreground hover:text-foreground mt-4 inline-flex items-center gap-2 text-sm transition-colors"
+			>
+				<svg viewBox="0 0 24 24" fill="currentColor" class="size-3.5" aria-hidden="true">
+					<path
+						d="M4 11a9 9 0 0 1 9 9M4 4a16 16 0 0 1 16 16M6 19a2 2 0 1 1-4 0 2 2 0 0 1 4 0z"
+						fill="none"
+						stroke="currentColor"
+						stroke-width="2"
+						stroke-linecap="round"
+					/>
+				</svg>
+				Subscribe via Atom
+			</a>
+		{/if}
+	</header>
+
+	{#if releases.length === 0}
+		<p class="text-muted-foreground">No releases yet.</p>
+	{:else}
+		<div class="space-y-14">
+			{#each releases as release (release.version)}
+				<ChangelogEntry {release} />
+			{/each}
+		</div>
+	{/if}
+</div>

package/dist/components/changelog/changelog.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { ChangelogRelease } from '../../core/changelog.js';
+type $$ComponentProps = {
+    /** Releases from the generated `svelte-docsmith/changelog` index. */
+    releases: ChangelogRelease[];
+    /** Page heading. */
+    title?: string;
+    /** Line below the heading. */
+    description?: string;
+    /** Path to the Atom feed, or `false` to hide the subscribe link. */
+    feed?: string | false;
+};
+declare const Changelog: import("svelte").Component<$$ComponentProps, {}, "">;
+type Changelog = ReturnType<typeof Changelog>;
+export default Changelog;

package/dist/components/docs/mermaid.svelte

@@ -0,0 +1,213 @@
+<script module lang="ts">
+	type Mermaid = (typeof import('mermaid'))['default'];
+
+	// One shared import; the bundler dedupes the chunk, this dedupes the promise.
+	let loaded: Promise<Mermaid> | undefined;
+	const loadMermaid = () => (loaded ??= import('mermaid').then((m) => m.default));
+
+	// `mermaid.initialize()` writes global config and `render()` is async, so two
+	// diagrams rendering concurrently can apply each other's theme — most visibly
+	// when one falls back to a built-in theme and reconfigures for everyone. Every
+	// initialize/render pair runs through this queue so they never interleave.
+	let chain: Promise<unknown> = Promise.resolve();
+
+	function serialize<T>(job: () => Promise<T>): Promise<T> {
+		const result = chain.then(job, job);
+		// Swallow rejections on the chain itself so one bad diagram doesn't stall
+		// the queue for the rest of the page.
+		chain = result.catch(() => {});
+		return result;
+	}
+</script>
+
+<script lang="ts">
+	import { onMount } from 'svelte';
+
+	// Rendered from a ```mermaid code fence: the preprocessor emits a lazy
+	// `import('svelte-docsmith/mermaid')` so `mermaid` (an optional peer dep) is
+	// only pulled into pages that actually contain a diagram. Rendering is
+	// client-side — mermaid needs a DOM — with a `<pre>` source fallback.
+	const { code }: { code: string } = $props();
+
+	// Graph ids must be unique among elements currently in the document: mermaid
+	// clears whatever already carries the id it's given, so a shared id silently
+	// wipes another diagram that's already on the page. `$props.id()` is unique per
+	// instance and stays unique even if two copies of this module end up loaded.
+	const uid = $props.id();
+	// Bumped per render, because the theme toggle re-renders while this instance's
+	// previous SVG is still mounted — reusing the id would delete it mid-swap.
+	let renders = 0;
+
+	let svg = $state('');
+	let failed = $state(false);
+	// Whether the last render targeted dark mode, so we only re-render when the
+	// site theme actually flips (not on every unrelated <html> class change).
+	let lastDark: boolean | undefined;
+
+	// Reused canvas for normalizing color tokens (see resolveColor); `null` once
+	// we've determined this browser gives us no 2d context to work with.
+	let colorCanvas: CanvasRenderingContext2D | null | undefined;
+
+	// Assigning an unparseable colour to `fillStyle` is silently ignored rather
+	// than throwing, so we set this first and check whether it survived. Any
+	// colour works as long as it's an unlikely design token, since an unchanged
+	// `fillStyle` is what tells us the assignment was rejected.
+	const SENTINEL = '#010203';
+
+	// Resolve a CSS color to a concrete `#rrggbb` string mermaid's color math
+	// (khroma) can parse. Our design tokens are `oklch(...)`, which khroma can't
+	// read. Reading `fillStyle` back is not enough to convert them: a browser
+	// serializes a wide-gamut colour unchanged, so Chrome hands back the same
+	// `oklch(...)` string it was given. Painting a pixel and reading its bytes
+	// forces the conversion to sRGB. Returns null when the value can't be
+	// resolved, which also covers an engine that doesn't understand oklch at all.
+	function resolveColor(value: string): string | null {
+		colorCanvas ??= document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+		const ctx = colorCanvas;
+		const input = value.trim();
+		if (!ctx || !input) return null;
+		ctx.fillStyle = SENTINEL;
+		ctx.fillStyle = input;
+		if (ctx.fillStyle === SENTINEL && input.toLowerCase() !== SENTINEL) return null;
+		ctx.clearRect(0, 0, 1, 1);
+		ctx.fillRect(0, 0, 1, 1);
+		const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+		return `#${[r, g, b].map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+	}
+
+	// Map the site's design tokens onto mermaid's documented theme variables, so a
+	// diagram reads as part of the site (its palette, borders, text) instead of
+	// mermaid's stock look. Read fresh each render so it follows the light/dark
+	// toggle. Returns null when the tokens can't be resolved — the caller then
+	// falls back to a built-in theme rather than shipping broken colors.
+	function themeVariables(dark: boolean): Record<string, string | boolean> | null {
+		const root = getComputedStyle(document.documentElement);
+		const background = resolveColor(root.getPropertyValue('--background'));
+		const foreground = resolveColor(root.getPropertyValue('--foreground'));
+		const muted = resolveColor(root.getPropertyValue('--muted'));
+		const mutedForeground = resolveColor(root.getPropertyValue('--muted-foreground'));
+		const border = resolveColor(root.getPropertyValue('--border'));
+		const accent = resolveColor(root.getPropertyValue('--accent'));
+		const card = resolveColor(root.getPropertyValue('--card'));
+		if (!background || !foreground || !muted || !mutedForeground || !border || !accent || !card) {
+			return null;
+		}
+		// Only mermaid's documented base variables — it derives node/cluster/edge
+		// colors from these, which keeps us off its more fragile internals.
+		return {
+			darkMode: dark,
+			background,
+			primaryColor: muted, // node fill
+			primaryTextColor: foreground,
+			primaryBorderColor: border,
+			lineColor: mutedForeground, // edges/arrows
+			secondaryColor: accent,
+			tertiaryColor: card
+		};
+	}
+
+	async function render() {
+		let mermaid: Mermaid;
+		try {
+			mermaid = await loadMermaid();
+		} catch {
+			// `mermaid` isn't installed — fall back to the source.
+			failed = true;
+			return;
+		}
+		const dark = document.documentElement.classList.contains('dark');
+		lastDark = dark;
+		const vars = themeVariables(dark);
+		// Try the token-themed `base` render first; if mermaid's color math rejects
+		// anything, retry with a built-in theme so a valid diagram never silently
+		// disappears. Only a genuine syntax error reaches the `<pre>` fallback.
+		const attempts = [
+			vars && { theme: 'base' as const, themeVariables: vars },
+			{ theme: dark ? ('dark' as const) : ('default' as const) }
+		];
+		for (const attempt of attempts) {
+			if (!attempt) continue;
+			try {
+				// Configure and render as one unit so a concurrent diagram can't
+				// re-initialize mermaid between the two calls.
+				const result = await serialize(() => {
+					mermaid.initialize({
+						startOnLoad: false,
+						securityLevel: 'strict',
+						fontFamily: 'inherit',
+						...attempt
+					});
+					return mermaid.render(`${uid}-${(renders += 1)}`, code);
+				});
+				svg = result.svg;
+				failed = false;
+				return;
+			} catch {
+				// Try the next (safer) config.
+			}
+		}
+		// Bad diagram syntax — fall back to source.
+		failed = true;
+	}
+
+	onMount(() => {
+		render();
+		// Re-render when the theme toggles so the diagram follows light/dark.
+		const observer = new MutationObserver(() => {
+			if (document.documentElement.classList.contains('dark') !== lastDark) render();
+		});
+		observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+		return () => observer.disconnect();
+	});
+</script>
+
+{#if failed}
+	<pre class="docsmith-mermaid-fallback not-prose"><code>{code}</code></pre>
+{:else if svg}
+	<!-- mermaid sanitizes its own output (securityLevel: strict) -->
+	<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+	<figure class="docsmith-mermaid not-prose">{@html svg}</figure>
+{:else}
+	<!-- Shares the global .docsmith-mermaid-skeleton with the server-rendered
+	     placeholder, so swapping to the diagram doesn't change the height. -->
+	<div class="docsmith-mermaid-skeleton not-prose" role="status" aria-label="Loading diagram"></div>
+{/if}
+
+<style>
+	/* The loading skeleton is global (theme.css), shared with the server-rendered
+	   placeholder. Here we only style the resolved diagram and the fallback. */
+	.docsmith-mermaid {
+		margin: 1.5rem 0;
+		display: flex;
+		justify-content: center;
+		animation: docsmith-mermaid-in 0.25s ease-out;
+	}
+	.docsmith-mermaid :global(svg) {
+		max-width: 100%;
+		height: auto;
+	}
+	@keyframes docsmith-mermaid-in {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.docsmith-mermaid {
+			animation: none;
+		}
+	}
+
+	.docsmith-mermaid-fallback {
+		margin: 1.5rem 0;
+		padding: 1rem;
+		border-radius: var(--radius, 0.75rem);
+		border: 1px solid var(--border);
+		background: var(--muted);
+		overflow-x: auto;
+		font-size: 0.85rem;
+		line-height: 1.5;
+	}
+</style>

package/dist/components/docs/mermaid.svelte.d.ts

@@ -0,0 +1,6 @@
+type Mermaid = (typeof import('mermaid'))['default'];
+type $$ComponentProps = {
+    code: string;
+};
+declare const Mermaid: import("svelte").Component<$$ComponentProps, {}, "">;
+export default Mermaid;

package/dist/components/landing/action.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	const {
+		href,
+		variant = 'primary',
+		external = false,
+		arrow = variant === 'primary',
+		children
+	}: {
+		href: string;
+		/** `primary` is the filled button, `secondary` the outlined one beside it. */
+		variant?: 'primary' | 'secondary';
+		external?: boolean;
+		/** Trailing arrow that nudges on hover. Defaults on for `primary`. */
+		arrow?: boolean;
+		children: Snippet;
+	} = $props();
+
+	const rel = $derived(external ? 'noopener noreferrer' : undefined);
+	const target = $derived(external ? '_blank' : undefined);
+</script>
+
+<!-- A call-to-action link for <Hero> and <CTA>. Deliberately small: anything more
+     elaborate is better written as a plain anchor in your own page. -->
+<a
+	{href}
+	{rel}
+	{target}
+	class="group inline-flex h-11 items-center gap-2 rounded-lg px-6 font-medium transition-all {variant ===
+	'primary'
+		? 'bg-primary text-primary-foreground hover:bg-primary/90 shadow-sm hover:shadow-md'
+		: 'border-border bg-background hover:bg-accent border'}"
+>
+	{@render children()}
+	{#if arrow}
+		<svg
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			class="size-4 transition-transform group-hover:translate-x-0.5"
+			aria-hidden="true"
+		>
+			<path d="M5 12h14M12 5l7 7-7 7" />
+		</svg>
+	{/if}
+</a>

package/dist/components/landing/action.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    href: string;
+    /** `primary` is the filled button, `secondary` the outlined one beside it. */
+    variant?: 'primary' | 'secondary';
+    external?: boolean;
+    /** Trailing arrow that nudges on hover. Defaults on for `primary`. */
+    arrow?: boolean;
+    children: Snippet;
+};
+declare const Action: import("svelte").Component<$$ComponentProps, {}, "">;
+type Action = ReturnType<typeof Action>;
+export default Action;

package/dist/components/landing/cta.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	const {
+		title,
+		description,
+		actions,
+		children
+	}: {
+		title: string;
+		/** Supporting line below the heading. */
+		description?: string;
+		/** Call-to-action buttons. */
+		actions?: Snippet;
+		/** Anything to sit below the actions, e.g. a note or a callout. */
+		children?: Snippet;
+	} = $props();
+</script>
+
+<!-- The closing panel of a landing page: a bordered card with a soft glow behind
+     the heading, so the page ends on the primary colour rather than trailing off. -->
+<section class="mx-auto max-w-7xl px-4 py-20 md:px-6 lg:px-8 lg:py-28">
+	<div
+		class="border-border bg-card relative isolate overflow-hidden rounded-2xl border px-6 py-16 text-center shadow-sm md:px-12"
+	>
+		<div class="pointer-events-none absolute inset-0 -z-10" aria-hidden="true">
+			<div
+				class="bg-primary/15 absolute top-0 left-1/2 h-75 w-150 -translate-x-1/2 rounded-full opacity-50 blur-[100px]"
+			></div>
+		</div>
+
+		<h2 class="mx-auto max-w-2xl text-3xl font-semibold tracking-tight text-balance sm:text-4xl">
+			{title}
+		</h2>
+
+		{#if description}
+			<p class="text-muted-foreground mx-auto mt-4 max-w-xl text-lg leading-relaxed text-pretty">
+				{description}
+			</p>
+		{/if}
+
+		{#if actions}
+			<div class="mt-8 flex flex-wrap items-center justify-center gap-3">
+				{@render actions()}
+			</div>
+		{/if}
+
+		{#if children}
+			<div class="mx-auto mt-10 max-w-xl text-left">{@render children()}</div>
+		{/if}
+	</div>
+</section>

package/dist/components/landing/cta.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    title: string;
+    /** Supporting line below the heading. */
+    description?: string;
+    /** Call-to-action buttons. */
+    actions?: Snippet;
+    /** Anything to sit below the actions, e.g. a note or a callout. */
+    children?: Snippet;
+};
+declare const Cta: import("svelte").Component<$$ComponentProps, {}, "">;
+type Cta = ReturnType<typeof Cta>;
+export default Cta;

package/dist/components/landing/feature-grid.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	const {
+		title,
+		description,
+		columns = 3,
+		background = 'default',
+		children
+	}: {
+		/** Section heading above the grid. */
+		title?: string;
+		/** Supporting line below the heading. */
+		description?: string;
+		/** Columns at the widest breakpoint; the grid steps down on smaller screens. */
+		columns?: 2 | 3;
+		/**
+		 * `muted` gives the section a tinted band with rules above and below, for
+		 * alternating against neighbouring sections.
+		 */
+		background?: 'default' | 'muted';
+		/** The `<Feature>` cells. */
+		children: Snippet;
+	} = $props();
+</script>
+
+<section class={background === 'muted' ? 'border-border/50 bg-muted/20 border-y' : ''}>
+	<div class="mx-auto max-w-7xl px-4 py-16 md:px-6 lg:px-8 lg:py-24">
+		{#if title || description}
+			<div class="mx-auto max-w-2xl text-center">
+				{#if title}
+					<h2 class="text-3xl font-semibold tracking-tight text-balance sm:text-4xl">{title}</h2>
+				{/if}
+				{#if description}
+					<p class="text-muted-foreground mt-4 text-lg leading-relaxed text-pretty">
+						{description}
+					</p>
+				{/if}
+			</div>
+		{/if}
+
+		<div
+			class="grid gap-x-10 gap-y-10 sm:grid-cols-2 {columns === 3 ? 'lg:grid-cols-3' : ''} {title ||
+			description
+				? 'mt-14'
+				: ''}"
+		>
+			{@render children()}
+		</div>
+	</div>
+</section>

package/dist/components/landing/feature-grid.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Section heading above the grid. */
+    title?: string;
+    /** Supporting line below the heading. */
+    description?: string;
+    /** Columns at the widest breakpoint; the grid steps down on smaller screens. */
+    columns?: 2 | 3;
+    /**
+     * `muted` gives the section a tinted band with rules above and below, for
+     * alternating against neighbouring sections.
+     */
+    background?: 'default' | 'muted';
+    /** The `<Feature>` cells. */
+    children: Snippet;
+};
+declare const FeatureGrid: import("svelte").Component<$$ComponentProps, {}, "">;
+type FeatureGrid = ReturnType<typeof FeatureGrid>;
+export default FeatureGrid;

package/dist/components/landing/feature.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	const {
+		title,
+		icon,
+		children
+	}: {
+		title: string;
+		/** Optional leading icon, rendered in a tinted square. */
+		icon?: Snippet;
+		/** The description. */
+		children?: Snippet;
+	} = $props();
+</script>
+
+<!-- One cell of a <FeatureGrid>. Icon beside the text rather than above it, so a
+     row of features stays compact as the column count grows. -->
+<div class="flex gap-4">
+	{#if icon}
+		<div
+			class="bg-primary/10 text-primary flex size-10 shrink-0 items-center justify-center rounded-lg"
+		>
+			{@render icon()}
+		</div>
+	{/if}
+	<div class="min-w-0">
+		<h3 class="font-semibold">{title}</h3>
+		{#if children}
+			<p class="text-muted-foreground mt-1 text-sm leading-relaxed">{@render children()}</p>
+		{/if}
+	</div>
+</div>

package/dist/components/landing/feature.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    title: string;
+    /** Optional leading icon, rendered in a tinted square. */
+    icon?: Snippet;
+    /** The description. */
+    children?: Snippet;
+};
+declare const Feature: import("svelte").Component<$$ComponentProps, {}, "">;
+type Feature = ReturnType<typeof Feature>;
+export default Feature;