sdocs 0.0.60 → 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/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);

package/dist/explorer/views/TopBar.svelte

@@ -0,0 +1,159 @@
+<script lang="ts">
+	import type { SectionTree } from '../tree-builder.js';
+	import { routeHref } from '../router.svelte.js';
+	import { Icon } from '../../ui/Icon/index.js';
+
+	type ThemeMode = 'light' | 'dark';
+
+	interface Props {
+		title: string;
+		logo: string | false;
+		sections: SectionTree[];
+		activeSlug?: string;
+		cssNames?: string[];
+		activeStylesheet?: string;
+		theme?: ThemeMode;
+		onToggleFullscreen?: () => void;
+		onStylesheetChange?: (name: string) => void;
+		onThemeChange?: (theme: ThemeMode) => void;
+	}
+
+	let {
+		title,
+		logo,
+		sections,
+		activeSlug,
+		cssNames = [],
+		activeStylesheet,
+		theme = 'light',
+		onToggleFullscreen,
+		onStylesheetChange,
+		onThemeChange,
+	}: Props = $props();
+
+	const themeIcons: Record<ThemeMode, string> = { light: '☀', dark: '☽' };
+	const themeLabels: Record<ThemeMode, string> = { light: 'Light', dark: 'Dark' };
+</script>
+
+<header class="sdocs-topbar">
+	<a href={routeHref([])} class="sdocs-topbar-brand">
+		{#if logo === 'sdocs'}
+			<Icon name="sdocs" --w="22px" --h="22px" --fill="#FC1D29" />
+		{:else if logo}
+			<img class="sdocs-topbar-logo" src={logo} alt="" />
+		{/if}
+		{title}
+	</a>
+	<nav class="sdocs-topbar-sections">
+		{#each sections as section (section.slug)}
+			<a
+				class="sdocs-topbar-tab"
+				class:is-active={section.slug === activeSlug}
+				aria-current={section.slug === activeSlug ? 'page' : undefined}
+				href={routeHref(section.firstRoute ?? [section.slug])}
+			>
+				{section.name}
+			</a>
+		{/each}
+	</nav>
+	<div class="sdocs-topbar-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-topbar-btn" onclick={() => onThemeChange?.(theme === 'light' ? 'dark' : 'light')} title="{themeLabels[theme]} theme">
+			{themeIcons[theme]}
+		</button>
+		<button class="sdocs-topbar-btn" onclick={() => onToggleFullscreen?.()} title="Fullscreen">
+			&#x26F6;
+		</button>
+	</div>
+</header>
+
+<style>
+	.sdocs-topbar {
+		display: flex;
+		align-items: center;
+		gap: 24px;
+		padding: 0 16px;
+		height: 48px;
+		flex-shrink: 0;
+		border-bottom: 1px solid var(--color-base-200);
+		background: var(--color-base-0);
+		font-family: var(--sans);
+	}
+	.sdocs-topbar-brand {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		font-weight: 700;
+		font-size: 18px;
+		color: var(--color-base-900);
+		text-decoration: none;
+	}
+	.sdocs-topbar-logo {
+		width: 22px;
+		height: 22px;
+		object-fit: contain;
+	}
+	.sdocs-topbar-sections {
+		display: flex;
+		align-items: stretch;
+		gap: 4px;
+		height: 100%;
+		flex: 1;
+		min-width: 0;
+		overflow-x: auto;
+	}
+	.sdocs-topbar-tab {
+		display: flex;
+		align-items: center;
+		padding: 0 12px;
+		font-size: 13px;
+		font-weight: 500;
+		color: var(--color-base-500);
+		text-decoration: none;
+		border-bottom: 2px solid transparent;
+		white-space: nowrap;
+	}
+	.sdocs-topbar-tab:hover {
+		color: var(--color-base-900);
+	}
+	.sdocs-topbar-tab.is-active {
+		color: var(--color-action-500);
+		border-bottom-color: var(--color-action-500);
+	}
+	.sdocs-topbar-actions {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+	}
+	.sdocs-css-picker {
+		font-size: 12px;
+		padding: 2px 4px;
+		border: 1px solid var(--color-base-200);
+		border-radius: 4px;
+		background: var(--color-base-0);
+		color: var(--color-base-600);
+	}
+	.sdocs-topbar-btn {
+		padding: 2px 6px;
+		border: 1px solid var(--color-base-200);
+		border-radius: 4px;
+		background: var(--color-base-0);
+		color: var(--color-base-600);
+		cursor: pointer;
+		font-size: 14px;
+		line-height: 1;
+	}
+	.sdocs-topbar-btn:hover {
+		background: var(--color-base-100);
+	}
+</style>

package/dist/explorer/views/TopBar.svelte.d.ts

@@ -0,0 +1,14 @@
+import { SvelteComponentTyped } from "svelte";
+declare const __propDef: {
+    props: Record<string, never>;
+    events: {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {};
+};
+export type TopBarProps = typeof __propDef.props;
+export type TopBarEvents = typeof __propDef.events;
+export type TopBarSlots = typeof __propDef.slots;
+export default class TopBar extends SvelteComponentTyped<TopBarProps, TopBarEvents, TopBarSlots> {
+}
+export {};

package/dist/language/config-schema.js

@@ -70,18 +70,35 @@ export const configSchema = {
         doc: 'Folder of static assets served at the site root — images for pages, files for previews. Standalone CLI flows; embedded apps use the host\'s public directory.',
         insert: ": './${0:static}'",
     },
-    logo: {
+    title: {
         detail: 'string',
-        doc: 'Sidebar logo text. Default: `sdocs`.',
+        doc: 'Header title text. Default: `sdocs`.',
         insert: ": '${0:sdocs}'",
     },
-    icon: {
+    logo: {
         detail: 'string | false',
-        doc: "Sidebar logo icon: `'sdocs'` for the built-in mascot, an image URL, or `false` to hide it. Default: `'sdocs'`.",
+        doc: "Header logo: `'sdocs'` for the built-in mascot, an image URL, or `false` to hide it. Default: `'sdocs'`.",
         insert: ": '${0:sdocs}'",
         values: ['sdocs'],
         quoted: true,
     },
+    sections: {
+        detail: 'string[]',
+        doc: 'Top-bar section order. Sections come from `@Section/…` title prefixes; unlisted sections follow alphabetically.',
+        insert: ': [$0]',
+    },
+    defaultSection: {
+        detail: 'string',
+        doc: 'Section for docs without an `@Section/` title prefix. Default: `Docs`.',
+        insert: ": '${0:Docs}'",
+    },
+    routing: {
+        detail: "'history' | 'hash'",
+        doc: "URL style: `'history'` for real paths (standalone CLI default), `'hash'` for `#/` URLs (embedded default).",
+        insert: ": '${0:history}'",
+        values: ['history', 'hash'],
+        quoted: true,
+    },
     sidebar: {
         detail: 'object',
         doc: 'Sidebar ordering and default-expanded folders.',