sdocs 0.0.59 → 0.0.61

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.',

package/dist/server/app-gen.js

@@ -116,8 +116,11 @@ mount(Explorer, {
 		docs,
 		cssNames,
 		pageModules,
+		title: ${JSON.stringify(config.title)},
 		logo: ${JSON.stringify(config.logo)},
-		icon: ${JSON.stringify(config.icon)},
+		sections: ${JSON.stringify(config.sections)},
+		defaultSection: ${JSON.stringify(config.defaultSection)},
+		routing: ${JSON.stringify(config.routing ?? 'history')},
 		sidebarConfig: ${JSON.stringify(config.sidebar)},
 	}
 });`;
@@ -192,7 +195,7 @@ export async function generateDevFiles(config, cwd) {
     // Copy Explorer components into the staging dir so they're compiled outside node_modules
     await copyExplorerApp(sdocsDir);
     await linkStagedDeps(sdocsDir, cwd);
-    await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
+    await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.title));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     return sdocsDir;
 }
@@ -205,7 +208,7 @@ export async function generateBuildFiles(config, cwd) {
     // Copy Explorer components into the staging dir
     await copyExplorerApp(sdocsDir);
     await linkStagedDeps(sdocsDir, cwd);
-    await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
+    await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.title));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     const inputs = {
         main: resolve(sdocsDir, 'index.html'),

package/dist/server/config.js

@@ -8,8 +8,11 @@ const DEFAULTS = {
     open: false,
     css: null,
     static: null,
+    title: 'sdocs',
     logo: 'sdocs',
-    icon: 'sdocs',
+    sections: [],
+    defaultSection: 'Docs',
+    routing: null,
     sidebar: {
         order: {},
         open: [],
@@ -87,14 +90,26 @@ export function resolveConfig(userConfig) {
             ? userConfig.include
             : [userConfig.include]
         : DEFAULTS.include;
+    // Pre-0.0.61 configs: `logo` was the header text and `icon` the image.
+    // An `icon` key marks the old shape — map it onto the new keys and warn.
+    const legacy = userConfig;
+    const isLegacy = 'icon' in legacy;
+    if (isLegacy) {
+        console.warn("[sdocs] config `icon` was renamed: use `logo` for the image and `title` for the header text.");
+    }
+    const title = userConfig.title ?? (isLegacy && typeof legacy.logo === 'string' ? legacy.logo : undefined);
+    const logo = isLegacy ? legacy.icon : userConfig.logo;
     return {
         include,
         port: userConfig.port ?? DEFAULTS.port,
         open: userConfig.open ?? DEFAULTS.open,
         css: userConfig.css ?? DEFAULTS.css,
         static: userConfig.static ?? DEFAULTS.static,
-        logo: userConfig.logo ?? DEFAULTS.logo,
-        icon: userConfig.icon ?? DEFAULTS.icon,
+        title: title ?? DEFAULTS.title,
+        logo: logo ?? DEFAULTS.logo,
+        sections: userConfig.sections ?? DEFAULTS.sections,
+        defaultSection: userConfig.defaultSection ?? DEFAULTS.defaultSection,
+        routing: userConfig.routing ?? DEFAULTS.routing,
         sidebar: {
             order: userConfig.sidebar?.order ?? DEFAULTS.sidebar.order,
             open: userConfig.sidebar?.open ?? DEFAULTS.sidebar.open,

package/dist/types.d.ts

@@ -12,10 +12,21 @@ export interface SdocsConfig {
      * files for previews. Standalone CLI flows (`sdocs dev`/`build`); when
      * embedding the Vite plugin, use the host app's own public directory. */
     static?: string;
-    /** Sidebar logo text. Default: 'sdocs' */
-    logo?: string;
-    /** Sidebar logo icon: 'sdocs' for the built-in mascot, an image URL, or false to hide. Default: 'sdocs' */
-    icon?: string | false;
+    /** Header title text. Default: 'sdocs' */
+    title?: string;
+    /** Header logo: 'sdocs' for the built-in mascot, an image URL, or false to hide. Default: 'sdocs' */
+    logo?: string | false;
+    /** Top-bar section order. Sections come from `@Section/...` title prefixes;
+     * unlisted sections follow alphabetically. Default: default section first,
+     * rest alphabetical. */
+    sections?: string[];
+    /** Name of the section that docs without an `@Section/` prefix belong to.
+     * Default: 'Docs' */
+    defaultSection?: string;
+    /** URL style: 'history' for real paths (default in the standalone CLI,
+     * needs the server to fall back to the shell), 'hash' for #/ URLs
+     * (default when embedding — works under any host routing). */
+    routing?: 'history' | 'hash';
     /** Sidebar configuration */
     sidebar?: {
         /** Per-folder sort overrides. Keys are folder paths, 'root' for top level. '*' = unlisted items. */
@@ -74,8 +85,12 @@ export interface ResolvedSdocsConfig {
     open: boolean;
     css: string | Record<string, string> | null;
     static: string | null;
-    logo: string;
-    icon: string | false;
+    title: string;
+    logo: string | false;
+    sections: string[];
+    defaultSection: string;
+    /** null = per-mode default (standalone: history, embedded: hash) */
+    routing: 'history' | 'hash' | null;
     sidebar: {
         order: Record<string, string[]>;
         open: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sdocs",
-	"version": "0.0.59",
+	"version": "0.0.61",
 	"description": "A lightweight documentation tool for Svelte 5 components",
 	"type": "module",
 	"license": "MIT",