sdocs 0.0.59 → 0.0.61

package/dist/explorer/tree-builder.js

@@ -1,9 +1,109 @@
-/** Build a tree from flat doc entries */
-export function buildTree(docs, sidebar) {
+/** Slug for one route segment — same rules as page heading anchors. */
+export function slugifySegment(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .trim()
+        .replace(/[\s_]+/g, '-') || 'item');
+}
+/** Split an optional `@Section` first segment off a title. */
+export function splitSection(title) {
+    const trimmed = (title ?? '').trim();
+    if (!trimmed.startsWith('@'))
+        return { section: null, rest: trimmed };
+    const slash = trimmed.indexOf('/');
+    if (slash === -1)
+        return { section: trimmed.slice(1).trim() || null, rest: '' };
+    return {
+        section: trimmed.slice(1, slash).trim() || null,
+        rest: trimmed.slice(slash + 1).trim(),
+    };
+}
+/**
+ * Group docs into sections (from `@Section/` title prefixes, the rest into the
+ * default section), build each section's tree, and register every navigable
+ * route. Section order: the config list first, unlisted after (default
+ * section first, then alphabetical).
+ */
+export function buildSections(docs, sidebar, opts) {
+    const defaultName = opts?.defaultSection ?? 'Docs';
+    const byName = new Map();
+    let active = false;
+    for (const doc of docs) {
+        const { section } = splitSection(doc.meta.title);
+        if (section)
+            active = true;
+        const name = section ?? defaultName;
+        const list = byName.get(name);
+        if (list)
+            list.push(doc);
+        else
+            byName.set(name, [doc]);
+    }
+    const configOrder = opts?.order ?? [];
+    const names = [...byName.keys()].sort((a, b) => {
+        const ai = configOrder.indexOf(a);
+        const bi = configOrder.indexOf(b);
+        if (ai !== -1 || bi !== -1)
+            return (ai === -1 ? Infinity : ai) - (bi === -1 ? Infinity : bi);
+        if (a === defaultName)
+            return -1;
+        if (b === defaultName)
+            return 1;
+        return a.localeCompare(b);
+    });
+    const routes = new Map();
+    const usedSectionSlugs = new Set();
+    const sections = names.map((name) => {
+        const slug = uniqueSlug(slugifySegment(name), usedSectionSlugs);
+        const prefix = active ? [slug] : [];
+        const tree = buildTree(byName.get(name), sidebar, prefix);
+        registerRoutes(tree, routes);
+        return {
+            name,
+            slug,
+            isDefault: name === defaultName,
+            tree,
+            firstRoute: firstDocRoute(tree),
+        };
+    });
+    return { sections, routes, active };
+}
+/**
+ * Resolve URL segments to a doc. Links that omit the section — bookmarks from
+ * before sections existed — fall back into the default section.
+ */
+export function resolveRoute(map, segments) {
+    if (segments.length === 0)
+        return null;
+    const hit = map.routes.get(segments.join('/'));
+    if (hit)
+        return hit;
+    if (map.active) {
+        const def = map.sections.find((s) => s.isDefault);
+        if (def && segments[0] !== def.slug) {
+            return map.routes.get([def.slug, ...segments].join('/')) ?? null;
+        }
+    }
+    return null;
+}
+/** Build a tree from flat doc entries; routes get `routePrefix` prepended. */
+export function buildTree(docs, sidebar, routePrefix = []) {
     const root = [];
     const folderMap = new Map();
+    // Slugs claimed per parent (keyed by display path) — collisions get -2, -3…
+    const claimed = new Map();
+    const childRoute = (parentPath, parentRoute, name) => {
+        const key = parentPath.join('/');
+        let used = claimed.get(key);
+        if (!used) {
+            used = new Set();
+            claimed.set(key, used);
+        }
+        return [...parentRoute, uniqueSlug(slugifySegment(name), used)];
+    };
     for (const doc of docs) {
-        const title = doc.meta.title ?? 'Untitled';
+        const title = splitSection(doc.meta.title).rest || 'Untitled';
         const segments = title.split('/').map((s) => s.trim()).filter(Boolean);
         if (segments.length === 0)
             continue;
@@ -12,12 +112,14 @@ export function buildTree(docs, sidebar) {
         const folderSegments = segments.slice(0, -1);
         // Ensure all parent folders exist
         let parent = root;
+        let parentRoute = routePrefix;
         const currentPath = [];
         for (let i = 0; i < folderSegments.length; i++) {
             let segName = folderSegments[i];
             const isGroup = i === 0 && segName.startsWith(':');
             if (isGroup)
-                segName = segName.slice(1);
+                segName = segName.slice(1).trim();
+            const parentPath = [...currentPath];
             currentPath.push(segName);
             const key = currentPath.join('/');
             let folder = folderMap.get(key);
@@ -32,6 +134,7 @@ export function buildTree(docs, sidebar) {
                         name: segName,
                         type: isGroup ? 'group' : 'folder',
                         path: [...currentPath],
+                        route: childRoute(parentPath, parentRoute, segName),
                         children: [],
                         defaultExpanded: isGroup || sidebar?.open?.includes(segName),
                     };
@@ -40,6 +143,7 @@ export function buildTree(docs, sidebar) {
                 folderMap.set(key, folder);
             }
             parent = folder.children;
+            parentRoute = folder.route;
         }
         // Create the item node
         const itemPath = [...currentPath, itemName];
@@ -51,28 +155,33 @@ export function buildTree(docs, sidebar) {
                 name: itemName,
                 type: 'component',
                 path: itemPath,
+                route: childRoute(currentPath, parentRoute, itemName),
                 children: [],
             };
             // Upgrade folder to component and attach doc data
             componentNode.type = 'component';
             componentNode.doc = doc;
             componentNode.examples = examples;
-            // Add "Docs" child
+            // Add "Docs" child — same doc, same route as the component itself
             componentNode.children.unshift({
                 name: 'Docs',
                 type: 'component',
                 path: itemPath,
+                route: componentNode.route,
                 children: [],
                 doc,
             });
             // Add example children
+            const usedExampleSlugs = new Set();
             for (const ex of examples) {
                 componentNode.children.push({
                     name: ex,
                     type: 'component',
                     path: [...itemPath, ex],
+                    route: [...componentNode.route, uniqueSlug(slugifySegment(ex), usedExampleSlugs)],
                     children: [],
                     doc,
+                    snippetName: ex,
                 });
             }
             if (!existing) {
@@ -84,6 +193,7 @@ export function buildTree(docs, sidebar) {
                 name: itemName,
                 type: kind,
                 path: itemPath,
+                route: childRoute(currentPath, parentRoute, itemName),
                 children: [],
                 doc,
             });
@@ -97,6 +207,39 @@ export function buildTree(docs, sidebar) {
     }
     return root;
 }
+/** Append -2, -3… until the slug is free within `used`; claims it. */
+function uniqueSlug(slug, used) {
+    let candidate = slug;
+    for (let n = 2; used.has(candidate); n++) {
+        candidate = `${slug}-${n}`;
+    }
+    used.add(candidate);
+    return candidate;
+}
+/** Register every doc-bearing node's route; example children carry the name. */
+function registerRoutes(nodes, routes) {
+    for (const node of nodes) {
+        if (node.doc) {
+            const key = node.route.join('/');
+            if (!routes.has(key)) {
+                routes.set(key, node.snippetName ? { doc: node.doc, snippetName: node.snippetName } : { doc: node.doc });
+            }
+        }
+        if (node.children.length > 0)
+            registerRoutes(node.children, routes);
+    }
+}
+/** The first document route in tree order (for section tab targets). */
+function firstDocRoute(nodes) {
+    for (const node of nodes) {
+        if (node.doc)
+            return node.route;
+        const inChildren = firstDocRoute(node.children);
+        if (inChildren)
+            return inChildren;
+    }
+    return null;
+}
 /** Reorder component children: Docs first, then examples, then sub-components sorted by name */
 function reorderComponentChildren(nodes) {
     for (const node of nodes) {
@@ -173,39 +316,10 @@ function sortByOrder(nodes, order) {
     }
 }
 /**
- * The title shown to users. A leading ':' on the first segment is a sidebar
- * grouping directive (see buildTree), not part of the displayed title, so it
- * is stripped for headings.
+ * The title shown to users. The `@Section/` prefix routes to a top-bar
+ * section and a leading ':' on the first segment is a sidebar grouping
+ * directive (see buildTree) — neither is part of the displayed title.
  */
 export function displayTitle(title) {
-    return (title ?? '').replace(/^:\s*/, '');
-}
-/** Check if a path matches a tree node (for active state) */
-export function pathMatchesNode(currentPath, node) {
-    if (node.path.length !== currentPath.length)
-        return false;
-    return node.path.every((seg, i) => seg === currentPath[i]);
-}
-/** Find the doc entry for a given path */
-export function findDocByPath(docs, path) {
-    if (path.length === 0)
-        return null;
-    for (const doc of docs) {
-        const title = doc.meta.title ?? '';
-        const segments = title.split('/').map((s) => s.trim()).filter(Boolean)
-            .map((s) => s.startsWith(':') ? s.slice(1) : s);
-        // Exact match → component docs view
-        if (segments.length === path.length && segments.every((s, i) => s === path[i])) {
-            return { doc };
-        }
-        // One extra segment → example
-        if (segments.length === path.length - 1 && segments.every((s, i) => s === path[i])) {
-            const snippetName = path[path.length - 1];
-            const hasSnippet = doc.examples?.some((s) => s.name === snippetName);
-            if (hasSnippet) {
-                return { doc, snippetName };
-            }
-        }
-    }
-    return null;
+    return splitSection(title).rest.replace(/^:\s*/, '');
 }

package/dist/explorer/views/HomePage.svelte

@@ -4,10 +4,11 @@
 
 	interface Props {
 		docs: DocEntry[];
-		logo: string;
+		title: string;
+		logo?: string | false;
 	}
 
-	let { docs, logo }: Props = $props();
+	let { docs, title, logo = 'sdocs' }: Props = $props();
 
 	const componentCount = $derived(docs.filter((d) => d.kind === 'component').length);
 	const pageCount = $derived(docs.filter((d) => d.kind === 'page').length);
@@ -16,8 +17,12 @@
 
 <div class="sdocs-home">
 	<div class="sdocs-home-brand">
-		<Icon name="sdocs" --w="160px" --h="160px" --fill="#FC1D29" />
-		<h1 class="sdocs-home-logo">{logo}</h1>
+		{#if logo === 'sdocs'}
+			<Icon name="sdocs" --w="160px" --h="160px" --fill="#FC1D29" />
+		{:else if logo}
+			<img class="sdocs-home-logo-img" src={logo} alt="" />
+		{/if}
+		<h1 class="sdocs-home-logo">{title}</h1>
 		<p class="sdocs-home-tagline">A lightweight documentation tool for Svelte 5 components.</p>
 	</div>
 
@@ -65,6 +70,11 @@
 		color: var(--color-base-900);
 		margin: 0;
 	}
+	.sdocs-home-logo-img {
+		width: 160px;
+		height: 160px;
+		object-fit: contain;
+	}
 	.sdocs-home-tagline {
 		font-size: 16px;
 		color: var(--color-base-500);

package/dist/explorer/views/PageView.svelte

@@ -37,7 +37,69 @@
 		};
 	});
 
+	// Scrollspy: the TOC highlights the section currently in view. The active
+	// heading is the last one above the threshold line near the viewport top.
+	// The scroll listener is capturing because the scrolling element is an
+	// ancestor container, not the window.
+	const SPY_OFFSET = 120;
+	let activeId = $state('');
+	let spyLockUntil = 0;
+
+	$effect(() => {
+		if (!container || toc.length === 0) return;
+		void PageComponent; // re-run once the page body has mounted
+		const ids = toc.map((h) => h.id);
+		let frame = 0;
+		const update = () => {
+			frame = 0;
+			if (performance.now() < spyLockUntil) return;
+			// At the bottom the last sections can never reach the threshold
+			// line — snap to the final entry so it is reachable at all.
+			let scroller: HTMLElement | null = container ?? null;
+			while (scroller) {
+				const o = getComputedStyle(scroller).overflowY;
+				if (
+					scroller.scrollHeight > scroller.clientHeight + 1 &&
+					(o === 'auto' || o === 'scroll')
+				) {
+					break;
+				}
+				scroller = scroller.parentElement;
+			}
+			const atBottom = scroller
+				? scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2
+				: window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+			if (atBottom) {
+				activeId = ids[ids.length - 1];
+				return;
+			}
+			let current = ids[0] ?? '';
+			for (const id of ids) {
+				const el = container?.querySelector(`#${CSS.escape(id)}`);
+				if (!el) continue;
+				if (el.getBoundingClientRect().top > SPY_OFFSET) break;
+				current = id;
+			}
+			activeId = current;
+		};
+		const onScroll = () => {
+			if (!frame) frame = requestAnimationFrame(update);
+		};
+		update();
+		document.addEventListener('scroll', onScroll, { capture: true, passive: true });
+		window.addEventListener('resize', onScroll);
+		return () => {
+			document.removeEventListener('scroll', onScroll, { capture: true });
+			window.removeEventListener('resize', onScroll);
+			if (frame) cancelAnimationFrame(frame);
+		};
+	});
+
 	function scrollToHeading(id: string) {
+		// Highlight the target right away and hold it while the smooth scroll
+		// passes intermediate sections.
+		activeId = id;
+		spyLockUntil = performance.now() + 800;
 		container?.querySelector(`#${CSS.escape(id)}`)?.scrollIntoView({ behavior: 'smooth' });
 	}
 
@@ -102,6 +164,8 @@
 							<li class="sdocs-toc-item" style:padding-left="{(heading.level - 2) * 12}px">
 								<button
 									class="sdocs-toc-link"
+									class:is-active={heading.id === activeId}
+									aria-current={heading.id === activeId ? 'true' : undefined}
 									onclick={() => scrollToHeading(heading.id)}
 								>
 									{heading.text}
@@ -372,8 +436,10 @@
 		cursor: pointer;
 		text-align: left;
 		width: 100%;
+		transition: color 0.15s;
 	}
-	.sdocs-toc-link:hover {
+	.sdocs-toc-link:hover,
+	.sdocs-toc-link.is-active {
 		color: var(--color-action-500);
 	}
 </style>

package/dist/explorer/views/Sidebar.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { SvelteSet } from 'svelte/reactivity';
 	import type { TreeNode } from '../tree-builder.js';
-	import { pathToHash } from '../router.svelte.js';
+	import { routeHref, navigate } from '../router.svelte.js';
 	import { Icon } from '../../ui/Icon/index.js';
 	import { NavTree } from '../../ui/index.js';
 
@@ -9,9 +9,11 @@
 
 	interface Props {
 		tree: TreeNode[];
-		currentPath: string[];
-		logo: string;
-		icon?: string | false;
+		currentRoute: string[];
+		title: string;
+		logo?: string | false;
+		/** Brand + actions render here unless a top bar already shows them */
+		showHeader?: boolean;
 		cssNames?: string[];
 		activeStylesheet?: string;
 		theme?: ThemeMode;
@@ -20,7 +22,7 @@
 		onThemeChange?: (theme: ThemeMode) => void;
 	}
 
-	let { tree, currentPath, logo, icon = 'sdocs', cssNames = [], activeStylesheet, theme = 'light', onToggleFullscreen, onStylesheetChange, onThemeChange }: Props = $props();
+	let { tree, currentRoute, title, logo = 'sdocs', showHeader = true, cssNames = [], activeStylesheet, theme = 'light', onToggleFullscreen, onStylesheetChange, onThemeChange }: Props = $props();
 
 	const themeIcons: Record<ThemeMode, string> = { light: '\u2600', dark: '\u263D' };
 	const themeLabels: Record<ThemeMode, string> = { light: 'Light', dark: 'Dark' };
@@ -85,13 +87,16 @@
 		return result;
 	}
 
-	function isActive(nodePath: string[]): boolean {
-		if (nodePath.length > currentPath.length) return false;
-		return nodePath.every((seg, i) => seg === currentPath[i]);
+	function isActive(nodeRoute: string[]): boolean {
+		if (nodeRoute.length > currentRoute.length) return false;
+		return nodeRoute.every((seg, i) => seg === currentRoute[i]);
 	}
 
-	function isExactActive(nodePath: string[]): boolean {
-		return nodePath.length === currentPath.length && nodePath.every((seg, i) => seg === currentPath[i]);
+	function isExactActive(nodeRoute: string[]): boolean {
+		return (
+			nodeRoute.length === currentRoute.length &&
+			nodeRoute.every((seg, i) => seg === currentRoute[i])
+		);
 	}
 
 	function iconName(node: TreeNode, expanded: boolean): string {
@@ -184,35 +189,37 @@
 </script>
 
 <aside class="sdocs-sidebar">
-	<div class="sdocs-sidebar-header">
-		<a href="#/" class="sdocs-logo">
-			{#if icon === 'sdocs'}
-				<Icon name="sdocs" --w="22px" --h="22px" --fill="#FC1D29" />
-			{:else if icon}
-				<img class="sdocs-logo-img" src={icon} alt="" />
-			{/if}
-			{logo}
-		</a>
-		<div class="sdocs-header-actions">
-			{#if cssNames.length > 1}
-				<select
-					class="sdocs-css-picker"
-					value={activeStylesheet}
-					onchange={(e) => onStylesheetChange?.(e.currentTarget.value)}
-				>
-					{#each cssNames as name (name)}
-						<option value={name}>{name}</option>
-					{/each}
-				</select>
-			{/if}
-			<button class="sdocs-theme-btn" onclick={toggleTheme} title="{themeLabels[theme]} theme">
-				{themeIcons[theme]}
-			</button>
-			<button class="sdocs-fullscreen-btn" onclick={() => onToggleFullscreen?.()} title="Fullscreen">
-				&#x26F6;
-			</button>
+	{#if showHeader}
+		<div class="sdocs-sidebar-header">
+			<a href={routeHref([])} class="sdocs-logo">
+				{#if logo === 'sdocs'}
+					<Icon name="sdocs" --w="22px" --h="22px" --fill="#FC1D29" />
+				{:else if logo}
+					<img class="sdocs-logo-img" src={logo} alt="" />
+				{/if}
+				{title}
+			</a>
+			<div class="sdocs-header-actions">
+				{#if cssNames.length > 1}
+					<select
+						class="sdocs-css-picker"
+						value={activeStylesheet}
+						onchange={(e) => onStylesheetChange?.(e.currentTarget.value)}
+					>
+						{#each cssNames as name (name)}
+							<option value={name}>{name}</option>
+						{/each}
+					</select>
+				{/if}
+				<button class="sdocs-theme-btn" onclick={toggleTheme} title="{themeLabels[theme]} theme">
+					{themeIcons[theme]}
+				</button>
+				<button class="sdocs-fullscreen-btn" onclick={() => onToggleFullscreen?.()} title="Fullscreen">
+					&#x26F6;
+				</button>
+			</div>
 		</div>
-	</div>
+	{/if}
 
 	<div class="sdocs-sidebar-search">
 		<input
@@ -244,12 +251,12 @@
 		<NavTree.Item
 			label={node.name}
 			{expanded}
-			active={isActive(node.path)}
+			active={isActive(node.route)}
 			onclick={() => {
 				const wasCollapsed = !expandedSet.has(pathKey);
 				toggleExpanded(pathKey);
 				if (wasCollapsed && node.type !== 'folder') {
-					window.location.hash = pathToHash(node.path);
+					navigate(node.route);
 				}
 			}}
 			--font-weight="500"
@@ -268,8 +275,8 @@
 	{:else}
 		<NavTree.Item
 			label={node.name}
-			href={pathToHash(node.path)}
-			active={isExactActive(node.path)}
+			href={routeHref(node.route)}
+			active={isExactActive(node.route)}
 			--font-weight={leafWeight(node)}
 			--bg-hover={hoverBg(node)}
 			--bg-active={activeBg(node)}
@@ -284,7 +291,7 @@
 <style>
 	.sdocs-sidebar {
 		width: 260px;
-		height: 100vh;
+		height: 100%;
 		overflow-y: auto;
 		border-right: 1px solid var(--color-base-200);
 		background: var(--color-base-0);