svelte-docsmith 0.9.0 → 0.10.0

package/dist/components/chrome/copy-button.svelte

@@ -16,7 +16,7 @@
 	} = $props();
 </script>
 
-<Button {onclick} variant="ghost" size="icon" class="size-8 {className ?? ''}">
+<Button {onclick} variant="ghost" size="icon" aria-label="Copy" class="size-8 {className ?? ''}">
 	{#if copied}
 		<div in:fade={{ duration: 80 }}>
 			<Check class="text-emerald-500" />
@@ -26,5 +26,6 @@
 			<Copy />
 		</div>
 	{/if}
-	<span class="sr-only">Copy</span>
+	<!-- Announce success to screen readers without altering the button's name. -->
+	<span class="sr-only" aria-live="polite">{copied ? 'Copied to clipboard' : ''}</span>
 </Button>

package/dist/components/chrome/search.svelte

@@ -17,8 +17,11 @@
 		 * Lazily provide the generated search records. Wired by the consumer so the
 		 * index is code-split and only fetched when the palette first opens, e.g.
 		 * `() => import('svelte-docsmith/search').then((m) => m.docs)`.
+		 *
+		 * Receives the active version id on a versioned site, so a loader may
+		 * return just that version's records; results are scoped either way.
 		 */
-		load: () => Promise<SearchDoc[]>;
+		load: (versionId?: string) => Promise<SearchDoc[]>;
 		placeholder?: string;
 	} = $props();
 
@@ -27,20 +30,29 @@
 	let query = $state('');
 	let engine = $state<SearchEngine | null>(null);
 	let status = $state<'idle' | 'loading' | 'error'>('idle');
+	// The version the cached engine was built for, so a loader that returns only
+	// one version's records is rebuilt when the reader switches versions. Stays
+	// constant (and the engine cached) on unversioned and single-version sites.
+	let engineVersion: string | undefined;
 
 	const trimmed = $derived(query.trim());
-	const results = $derived(engine && trimmed ? engine.search(query) : []);
+	// Scope to the active version when the shell set one (versioned sites).
+	const results = $derived(
+		engine && trimmed ? engine.search(query, undefined, search?.version) : []
+	);
 
 	// Build the index the first time the palette opens; keep it for later opens.
 	async function ensureEngine() {
-		if (engine || status === 'loading') return;
+		const version = search?.version;
+		if ((engine && engineVersion === version) || status === 'loading') return;
 		status = 'loading';
 		try {
 			const [{ createSearchEngine }, docs] = await Promise.all([
 				import('../../search/create-search.js'),
-				load()
+				load(version)
 			]);
 			engine = createSearchEngine(docs);
+			engineVersion = version;
 			status = 'idle';
 		} catch (error) {
 			console.error('[svelte-docsmith] failed to load the search index', error);

package/dist/components/chrome/search.svelte.d.ts

@@ -4,8 +4,11 @@ type $$ComponentProps = {
      * Lazily provide the generated search records. Wired by the consumer so the
      * index is code-split and only fetched when the palette first opens, e.g.
      * `() => import('svelte-docsmith/search').then((m) => m.docs)`.
+     *
+     * Receives the active version id on a versioned site, so a loader may
+     * return just that version's records; results are scoped either way.
      */
-    load: () => Promise<SearchDoc[]>;
+    load: (versionId?: string) => Promise<SearchDoc[]>;
     placeholder?: string;
 };
 declare const Search: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/chrome/version-banner.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
+	import ArrowRight from '@lucide/svelte/icons/arrow-right';
+	import {
+		mapPathToVersion,
+		scopeContent,
+		type ResolvedVersion,
+		type DocsContentItem
+	} from '../../core/index.js';
+
+	// Rendered by DocsShell only on an archived version, to warn a reader who
+	// landed there (usually from a search engine) and give them a one-click path
+	// to the current equivalent. A real <a> (not client nav) so it works without
+	// JS and stays crawlable.
+	const {
+		active,
+		current,
+		pathname,
+		content
+	}: {
+		active: ResolvedVersion;
+		current: ResolvedVersion;
+		pathname: string;
+		content: DocsContentItem[];
+	} = $props();
+
+	const currentHref = $derived(
+		mapPathToVersion(
+			pathname,
+			active,
+			current,
+			scopeContent(content, current.id).map((c) => c.path)
+		)
+	);
+</script>
+
+<div class="docsmith-version-banner" role="note">
+	<TriangleAlert class="banner-icon" size={18} aria-hidden="true" />
+	<p>
+		You're reading the <strong>{active.label}</strong> docs. The current version is
+		<strong>{current.label}</strong>.
+		<a href={currentHref}>View this page in {current.label} <ArrowRight size={14} /></a>
+	</p>
+</div>
+
+<style>
+	.docsmith-version-banner {
+		display: flex;
+		gap: 0.6rem;
+		align-items: flex-start;
+		margin-bottom: 1.75rem;
+		padding: 0.75rem 1rem;
+		border: 1px solid;
+		border-radius: var(--radius);
+		font-size: 0.9rem;
+		line-height: 1.5;
+		color: var(--foreground);
+		border-color: oklch(0.62 0.14 75 / 0.3);
+		background: oklch(0.62 0.14 75 / 0.1);
+	}
+	:global(.docsmith-version-banner .banner-icon) {
+		margin-top: 0.1rem;
+		flex-shrink: 0;
+		color: oklch(0.62 0.14 75);
+	}
+	:global(.dark) .docsmith-version-banner :global(.banner-icon) {
+		color: oklch(0.82 0.13 80);
+	}
+	.docsmith-version-banner p {
+		margin: 0;
+	}
+	.docsmith-version-banner a {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.2rem;
+		font-weight: 600;
+		color: var(--primary);
+		white-space: nowrap;
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+</style>

package/dist/components/chrome/version-banner.svelte.d.ts

@@ -0,0 +1,10 @@
+import { type ResolvedVersion, type DocsContentItem } from '../../core/index.js';
+type $$ComponentProps = {
+    active: ResolvedVersion;
+    current: ResolvedVersion;
+    pathname: string;
+    content: DocsContentItem[];
+};
+declare const VersionBanner: import("svelte").Component<$$ComponentProps, {}, "">;
+type VersionBanner = ReturnType<typeof VersionBanner>;
+export default VersionBanner;

package/dist/components/chrome/version-switcher.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { Button } from '../shadcn/button/index.js';
+	import * as DropdownMenu from '../shadcn/dropdown-menu/index.js';
+	import Check from '@lucide/svelte/icons/check';
+	import ChevronsUpDown from '@lucide/svelte/icons/chevrons-up-down';
+	import {
+		mapPathToVersion,
+		scopeContent,
+		type ResolvedVersion,
+		type DocsContentItem
+	} from '../../core/index.js';
+
+	const {
+		versions,
+		active,
+		pathname,
+		content
+	}: {
+		/** All declared versions, in switcher order. */
+		versions: ResolvedVersion[];
+		/** The version the current page belongs to. */
+		active: ResolvedVersion;
+		/** The current normalized pathname, e.g. `/docs/v2/intro`. */
+		pathname: string;
+		/** Full content index, to map the current page into the chosen version. */
+		content: DocsContentItem[];
+	} = $props();
+
+	function select(target: ResolvedVersion) {
+		if (target.id === active.id) return;
+		const paths = scopeContent(content, target.id).map((c) => c.path);
+		goto(mapPathToVersion(pathname, active, target, paths));
+	}
+</script>
+
+<DropdownMenu.Root>
+	<DropdownMenu.Trigger>
+		{#snippet child({ props })}
+			<Button
+				variant="outline"
+				size="sm"
+				class="h-8 gap-1.5 px-2.5 font-medium"
+				aria-label={`Documentation version: ${active.label}. Change version`}
+				{...props}
+			>
+				<span class="truncate">{active.label}</span>
+				<ChevronsUpDown class="size-3.5 shrink-0 opacity-60" aria-hidden="true" />
+			</Button>
+		{/snippet}
+	</DropdownMenu.Trigger>
+	<DropdownMenu.Content align="start" class="w-44">
+		{#each versions as version (version.id)}
+			<DropdownMenu.Item onSelect={() => select(version)} class="gap-2">
+				<Check
+					class="size-4 {version.id === active.id ? 'opacity-100' : 'opacity-0'}"
+					aria-hidden="true"
+				/>
+				<span class="flex-1 truncate">{version.label}</span>
+			</DropdownMenu.Item>
+		{/each}
+	</DropdownMenu.Content>
+</DropdownMenu.Root>

package/dist/components/chrome/version-switcher.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedVersion, type DocsContentItem } from '../../core/index.js';
+type $$ComponentProps = {
+    /** All declared versions, in switcher order. */
+    versions: ResolvedVersion[];
+    /** The version the current page belongs to. */
+    active: ResolvedVersion;
+    /** The current normalized pathname, e.g. `/docs/v2/intro`. */
+    pathname: string;
+    /** Full content index, to map the current page into the chosen version. */
+    content: DocsContentItem[];
+};
+declare const VersionSwitcher: import("svelte").Component<$$ComponentProps, {}, "">;
+type VersionSwitcher = ReturnType<typeof VersionSwitcher>;
+export default VersionSwitcher;

package/dist/components/layouts/docs-header.svelte

@@ -6,7 +6,13 @@
 	import SearchTrigger from '../chrome/search-trigger.svelte';
 	import { useSearch } from '../../search/context.svelte.js';
 	import ThemeToggle from '../chrome/theme-toggle.svelte';
-	import type { DocsmithConfig, DocsmithLink } from '../../core/index.js';
+	import VersionSwitcher from '../chrome/version-switcher.svelte';
+	import type {
+		DocsmithConfig,
+		DocsmithLink,
+		DocsContentItem,
+		ResolvedVersion
+	} from '../../core/index.js';
 	import BookOpenText from '@lucide/svelte/icons/book-open-text';
 	import type { Snippet } from 'svelte';
 	import { page } from '$app/state';
@@ -16,13 +22,25 @@
 	const {
 		config,
 		logo,
-		actions
+		actions,
+		versions = [],
+		active,
+		content = [],
+		pathname = ''
 	}: {
 		config: DocsmithConfig;
 		/** Custom logo mark; defaults to a book icon in a primary-tinted chip. */
 		logo?: Snippet;
 		/** Extra header controls, rendered before the theme toggle. */
 		actions?: Snippet;
+		/** Declared versions; renders the switcher once there's more than one. */
+		versions?: ResolvedVersion[];
+		/** The active version, for the switcher's current selection. */
+		active?: ResolvedVersion;
+		/** Content index, so the switcher can map the current page across versions. */
+		content?: DocsContentItem[];
+		/** Current normalized pathname, for the switcher's page mapping. */
+		pathname?: string;
 	} = $props();
 
 	// Present only when the consumer passed a `search` loader to DocsShell.
@@ -91,7 +109,11 @@
 				</nav>
 			{/if}
 
-			{#if config.version}
+			{#if versions.length > 1 && active}
+				<div class="px-1">
+					<VersionSwitcher {versions} {active} {content} {pathname} />
+				</div>
+			{:else if config.version}
 				<div class="px-2">
 					<Badge
 						variant="outline"
@@ -121,6 +143,7 @@
 						size="icon"
 						variant="ghost"
 						target="_blank"
+						rel="noopener noreferrer"
 						href={config.github}
 						class="text-muted-foreground hover:text-foreground size-8"
 					>

package/dist/components/layouts/docs-header.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { DocsmithConfig } from '../../core/index.js';
+import type { DocsmithConfig, DocsContentItem, ResolvedVersion } from '../../core/index.js';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     config: DocsmithConfig;
@@ -6,6 +6,14 @@ type $$ComponentProps = {
     logo?: Snippet;
     /** Extra header controls, rendered before the theme toggle. */
     actions?: Snippet;
+    /** Declared versions; renders the switcher once there's more than one. */
+    versions?: ResolvedVersion[];
+    /** The active version, for the switcher's current selection. */
+    active?: ResolvedVersion;
+    /** Content index, so the switcher can map the current page across versions. */
+    content?: DocsContentItem[];
+    /** Current normalized pathname, for the switcher's page mapping. */
+    pathname?: string;
 };
 declare const DocsHeader: import("svelte").Component<$$ComponentProps, {}, "">;
 type DocsHeader = ReturnType<typeof DocsHeader>;

package/dist/components/layouts/docs-mobile-header.svelte

@@ -1,10 +1,16 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import type { DocsmithConfig, NavGroup } from '../../core/index.js';
+	import type {
+		DocsmithConfig,
+		NavGroup,
+		DocsContentItem,
+		ResolvedVersion
+	} from '../../core/index.js';
 	import type { TocItem } from '../../toc/index.js';
 	import DocsSidebar from './docs-sidebar.svelte';
 	import TableOfContents from '../chrome/table-of-contents.svelte';
 	import ThemeToggle from '../chrome/theme-toggle.svelte';
+	import VersionSwitcher from '../chrome/version-switcher.svelte';
 	import { Button } from '../shadcn/button/index.js';
 	import * as Popover from '../shadcn/popover/index.js';
 	import { ScrollArea } from '../shadcn/scroll-area/index.js';
@@ -24,7 +30,11 @@
 		tocItems = [],
 		tocActiveId = null,
 		logo,
-		actions
+		actions,
+		versions = [],
+		active,
+		content = [],
+		pathname = ''
 	}: {
 		config: DocsmithConfig;
 		/** Sidebar groups; omit on non-doc pages (the landing/`page` layout). */
@@ -37,6 +47,14 @@
 		tocActiveId?: string | null;
 		logo?: Snippet;
 		actions?: Snippet;
+		/** Declared versions; renders the switcher in the drawer once there's more than one. */
+		versions?: ResolvedVersion[];
+		/** The active version, for the switcher's current selection. */
+		active?: ResolvedVersion;
+		/** Content index, so the switcher can map the current page across versions. */
+		content?: DocsContentItem[];
+		/** Current normalized pathname, for the switcher's page mapping. */
+		pathname?: string;
 	} = $props();
 
 	const search = useSearch();
@@ -77,6 +95,11 @@
 						<span class="inline-block">{config.title}</span>
 					</a>
 				</div>
+				{#if versions.length > 1 && active}
+					<div class="px-7 pb-3">
+						<VersionSwitcher {versions} {active} {content} {pathname} />
+					</div>
+				{/if}
 				<ScrollArea class="my-4 h-[calc(100vh-8rem)] pb-10 pl-2">
 					{#if config.nav?.length}
 						<nav aria-label="Main" class="flex flex-col gap-0.5 px-5 pb-1">

package/dist/components/layouts/docs-mobile-header.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { DocsmithConfig, NavGroup } from '../../core/index.js';
+import type { DocsmithConfig, NavGroup, DocsContentItem, ResolvedVersion } from '../../core/index.js';
 import type { TocItem } from '../../toc/index.js';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
@@ -13,6 +13,14 @@ type $$ComponentProps = {
     tocActiveId?: string | null;
     logo?: Snippet;
     actions?: Snippet;
+    /** Declared versions; renders the switcher in the drawer once there's more than one. */
+    versions?: ResolvedVersion[];
+    /** The active version, for the switcher's current selection. */
+    active?: ResolvedVersion;
+    /** Content index, so the switcher can map the current page across versions. */
+    content?: DocsContentItem[];
+    /** Current normalized pathname, for the switcher's page mapping. */
+    pathname?: string;
 };
 declare const DocsMobileHeader: import("svelte").Component<$$ComponentProps, {}, "">;
 type DocsMobileHeader = ReturnType<typeof DocsMobileHeader>;