sdocs 0.0.18 → 0.0.20

package/README.md

@@ -0,0 +1,281 @@
+# sdocs
+
+A lightweight documentation tool for Svelte 5 components. Discover `.sdoc` files in your project and get an interactive component explorer with live previews, prop controls, and code highlighting.
+
+## Quick Start
+
+```bash
+# Initialize config
+npx sdocs init
+
+# Start dev server
+npx sdocs dev
+```
+
+## Installation
+
+```bash
+npm install sdocs
+```
+
+**Requirements:** Svelte 5, Vite 6+, `@sveltejs/vite-plugin-svelte` 5+
+
+## Usage
+
+sdocs can be used in two ways: as a **standalone CLI tool** or **embedded in your existing project**.
+
+### Standalone (CLI)
+
+Run sdocs as its own dev server:
+
+```bash
+npx sdocs dev      # Start dev server with HMR
+npx sdocs build    # Build static documentation site
+npx sdocs preview  # Preview the built site locally
+npx sdocs init     # Scaffold a sdocs.config.js file
+```
+
+### Embedded in a SvelteKit / Vite Project
+
+Use sdocs as a Vite plugin inside your existing project. This way sdocs runs alongside your app without needing a separate server.
+
+**1. Add the Vite plugin**
+
+```js
+// vite.config.js
+import { sveltekit } from '@sveltejs/kit/vite';
+import { sdocsPlugin } from 'sdocs/vite';
+
+export default {
+  plugins: [
+    sveltekit(),
+    sdocsPlugin({
+      include: ['./src/lib/**/*.sdoc'],
+      css: './src/styles/global.css',
+      logo: 'My Design System',
+    })
+  ],
+};
+```
+
+The plugin discovers `.sdoc` files and exposes them via a `virtual:sdocs` module.
+
+**2. Create a page that mounts the sdocs app**
+
+```svelte
+<!-- src/routes/docs/+page.svelte -->
+<script>
+  import App from 'sdocs/client';
+  import { docs, cssNames } from 'virtual:sdocs';
+</script>
+
+<App
+  {docs}
+  {cssNames}
+  logo="My Design System"
+  sidebarConfig={{
+    order: { root: ['Components', '*'] },
+    open: ['Components'],
+  }}
+/>
+```
+
+**3. Add the virtual module type declaration** (optional, for TypeScript)
+
+```ts
+// src/app.d.ts or any .d.ts file
+declare module 'virtual:sdocs' {
+  import type { DocEntry } from 'sdocs';
+  export const docs: DocEntry[];
+  export const cssNames: string[];
+  export default docs;
+}
+```
+
+That's it — your docs page lives at `/docs` inside your existing app.
+
+## Writing Docs
+
+sdocs supports three types of doc files:
+
+### Component Docs (`.sdoc`)
+
+Document a Svelte component with interactive controls and examples.
+
+```svelte
+<!-- Button.sdoc -->
+<script lang="ts">
+  import Button from './Button.svelte';
+
+  export const meta = {
+    component: Button,
+    title: 'Components / Button',
+    description: 'A flexible button component.',
+    args: {
+      label: 'Click me',
+      size: 'md',
+      disabled: false,
+    },
+  };
+</script>
+
+{#snippet Default()}
+  <Button {...args} />
+{/snippet}
+
+{#snippet WithIcon()}
+  <Button>
+    <Icon name="settings" /> Settings
+  </Button>
+{/snippet}
+```
+
+- **`component`** — the Svelte component to document (auto-extracts props, events, snippets, methods, state, CSS custom properties)
+- **`title`** — slash-separated path for sidebar navigation (e.g. `'Components / Button'`)
+- **`args`** — default prop values, used as initial values for interactive controls
+- **`Default` snippet** — gets live interactive controls. Auto-generated as `<Component {...args} />` if omitted.
+- **Named snippets** — static examples listed in the sidebar
+
+### Page Docs (`.page.sdoc`)
+
+Freeform content pages with auto-generated table of contents.
+
+```svelte
+<!-- GettingStarted.page.sdoc -->
+<script lang="ts">
+  export const meta = {
+    title: 'Docs / Getting Started',
+    description: 'How to set up sdocs.',
+  };
+</script>
+
+<h1>Getting Started</h1>
+<p>Install sdocs and create your first doc file.</p>
+
+<h2>Installation</h2>
+<p>Run <code>npm install sdocs</code>...</p>
+```
+
+Table of contents is auto-generated from `<h2>`, `<h3>`, and `<h4>` headings.
+
+### Layout Docs (`.layout.sdoc`)
+
+Component compositions rendered in an isolated iframe.
+
+```svelte
+<!-- LoginForm.layout.sdoc -->
+<script lang="ts">
+  import Card from './Card.svelte';
+  import Input from './Input.svelte';
+  import Button from './Button.svelte';
+
+  export const meta = {
+    title: 'Patterns / Login Form',
+    description: 'A login form combining multiple components.',
+    settings: { padding: '24px' },
+  };
+</script>
+
+<Card padding="24px">
+  <Input label="Email" type="email" />
+  <Input label="Password" type="password" />
+  <Button>Sign in</Button>
+</Card>
+```
+
+## Prop Extraction
+
+sdocs automatically extracts from your Svelte components:
+
+| What | Source |
+|------|--------|
+| **Props** | `$props()` destructuring + `interface Props {}` |
+| **Events** | Callback props (`onclick`, `onchange`, etc.) |
+| **Snippets** | Props typed as `Snippet` or `Snippet<[...]>` |
+| **Methods** | Exported functions |
+| **State** | Exported `$state` / `$derived` values |
+| **CSS Custom Properties** | `var(--name)` usages in `<style>` |
+
+JSDoc comments on props are picked up as descriptions.
+
+## Interactive Controls
+
+The Default snippet gets live controls based on prop types:
+
+| Prop Type | Control |
+|-----------|---------|
+| `string` | Text input |
+| `number` | Number input |
+| `boolean` | Checkbox |
+| Color (`#hex`) | Color picker |
+| Dimension (`16px`) | Number + unit |
+
+## Configuration
+
+Create `sdocs.config.js` in your project root (or run `npx sdocs init`):
+
+```js
+/** @type {import('sdocs').SdocsConfig} */
+export default {
+  // Glob pattern(s) to find .sdoc files
+  include: ['./src/**/*.sdoc'],
+
+  // Dev server port
+  port: 3000,
+
+  // Open browser on start
+  open: true,
+
+  // Sidebar logo text
+  logo: 'My Design System',
+
+  // CSS loaded in preview iframes
+  css: './src/styles/global.css',
+
+  // Sidebar ordering
+  sidebar: {
+    order: {
+      root: ['Components', '*', 'Documentation'],
+    },
+    open: ['Components'],
+  },
+};
+```
+
+### CSS Stylesheet Switching
+
+Provide named stylesheets to let users switch between them (e.g. light/dark themes):
+
+```js
+css: {
+  light: './src/styles/light.css',
+  dark: './src/styles/dark.css',
+}
+```
+
+### Sidebar Ordering
+
+Control the order of items in the sidebar with `sidebar.order`. Use `'*'` as a wildcard for remaining items in alphabetical order:
+
+```js
+sidebar: {
+  order: {
+    root: ['Getting Started', 'Components', '*'],
+    Components: ['Button', 'Input', '*'],
+  },
+  open: ['Components'],
+}
+```
+
+## Package Exports
+
+| Export | Description |
+|--------|-------------|
+| `sdocs` | Main entry — `sdocsPlugin` + types |
+| `sdocs/vite` | Vite plugin function |
+| `sdocs/client` | App.svelte UI component |
+| `sdocs/ui` | Reusable UI components (Button, Frame, Icon, Control, NavTree, Stack) |
+
+## License
+
+MIT

package/dist/client/App.svelte

@@ -8,7 +8,7 @@
 	import LayoutView from './views/LayoutView.svelte';
 	import HomePage from './views/HomePage.svelte';
 	import { onMount } from 'svelte';
-	import '../ui/styles/theme.css';
+	import '../ui/styles/sdocs.css';
 
 	type ThemeMode = 'light' | 'dark';
 

package/dist/client/App.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { DocEntry } from '../types.js';
-import '../ui/styles/theme.css';
+import '../ui/styles/sdocs.css';
 interface Props {
     docs: DocEntry[];
     logo?: string;

package/dist/client/views/CollapsiblePanel.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
+	import { Icon } from '../../ui/Icon/index.js';
 
 	interface Props {
 		title: string;
@@ -12,9 +13,11 @@
 </script>
 
 <div class="sdocs-panel">
-	<button class="sdocs-panel-header" onclick={() => expanded = !expanded}>
-		<span class="sdocs-panel-arrow" class:expanded>&#9654;</span>
+	<button class="sdocs-panel-header" onclick={() => (expanded = !expanded)}>
 		<span class="sdocs-panel-title">{title}</span>
+		<span class="sdocs-panel-chevron">
+			<Icon name={expanded ? 'chevron-down' : 'chevron-right'} --w="14px" --h="14px" />
+		</span>
 	</button>
 	{#if expanded}
 		<div class="sdocs-panel-body">
@@ -25,39 +28,36 @@
 
 <style>
 	.sdocs-panel {
-		border: 1px solid var(--color-base-200);
-		border-radius: 8px;
+		/* border: 1px solid var(--color-base-200); */
+		/* border-radius: 8px; */
 		overflow: hidden;
+		background: var(--color-base-0);
 	}
 	.sdocs-panel-header {
 		display: flex;
 		align-items: center;
 		gap: 8px;
 		width: 100%;
-		padding: 10px 14px;
+		padding: 6px 8px 6px 12px;
 		border: none;
 		background: var(--color-base-50);
 		font: inherit;
 		font-size: 13px;
 		font-weight: 600;
-		color: var(--color-base-900);
+		color: var(--color-base-700);
 		cursor: pointer;
 		text-align: left;
 	}
 	.sdocs-panel-header:hover {
 		background: var(--color-base-100);
 	}
-	.sdocs-panel-arrow {
-		font-size: 8px;
-		transition: transform 0.15s;
-		display: inline-block;
-		width: 10px;
-	}
-	.sdocs-panel-arrow.expanded {
-		transform: rotate(90deg);
+	.sdocs-panel-chevron {
+		margin-left: auto;
+		display: flex;
+		align-items: center;
 	}
 	.sdocs-panel-body {
 		padding: 14px;
-		border-top: 1px solid var(--color-base-200);
+		border-top: 1px solid var(--color-base-100);
 	}
 </style>

package/dist/client/views/ComponentView.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { DocEntry } from '../../types.js';
+	import { Icon } from '../../ui/Icon/index.js';
 	import CollapsiblePanel from './CollapsiblePanel.svelte';
 	import PreviewFrame from './PreviewFrame.svelte';
 	import ControlsPanel from './ControlsPanel.svelte';
@@ -50,17 +51,17 @@
 		cssValues = { ...cssValues, [name]: value };
 	}
 
-	function generateUsageCode(name: string, props: Record<string, unknown>, css: Record<string, string>): string {
+	function formatAttr(name: string, value: unknown): string {
+		if (typeof value === 'string') return `${name}="${value}"`;
+		if (typeof value === 'boolean') return value ? name : `${name}={false}`;
+		return `${name}={${JSON.stringify(value)}}`;
+	}
+
+	function generateFallbackCode(name: string, props: Record<string, unknown>, css: Record<string, string>): string {
 		const attrs: string[] = [];
 		for (const [key, value] of Object.entries(props)) {
 			if (value === undefined || value === null || value === '') continue;
-			if (typeof value === 'string') {
-				attrs.push(`${key}="${value}"`);
-			} else if (typeof value === 'boolean') {
-				attrs.push(value ? key : `${key}={false}`);
-			} else {
-				attrs.push(`${key}={${JSON.stringify(value)}}`);
-			}
+			attrs.push(formatAttr(key, value));
 		}
 		for (const [key, value] of Object.entries(css)) {
 			if (value === undefined || value === '') continue;
@@ -71,7 +72,126 @@
 		return `<${name}\n  ${attrs.join('\n  ')}\n/>`;
 	}
 
-	const usageCode = $derived(generateUsageCode(componentName, propValues, cssValues));
+	/**
+	 * Patch the Default snippet body with prop/CSS changes from Controls.
+	 * Finds the root component opening tag and updates/adds changed attributes.
+	 */
+	function patchSnippetCode(
+		snippetBody: string,
+		name: string,
+		currentProps: Record<string, unknown>,
+		currentCss: Record<string, string>,
+		initialProps: Record<string, unknown>,
+		initialCss: Record<string, string>,
+	): string {
+		// Collect only changed props/css
+		const changes: [string, unknown][] = [];
+		for (const [key, value] of Object.entries(currentProps)) {
+			if (JSON.stringify(value) !== JSON.stringify(initialProps[key])) {
+				changes.push([key, value]);
+			}
+		}
+		for (const [key, value] of Object.entries(currentCss)) {
+			if (value !== (initialCss[key] ?? '')) {
+				changes.push([key, value]);
+			}
+		}
+
+		if (changes.length === 0) return snippetBody;
+
+		// Find the opening tag: <ComponentName ...> or <ComponentName ... />
+		const tagStart = snippetBody.indexOf(`<${name}`);
+		if (tagStart === -1) return snippetBody;
+
+		// Find the end of the opening tag, respecting {} expressions
+		let braceDepth = 0;
+		let tagEnd = -1;
+		for (let i = tagStart + name.length + 1; i < snippetBody.length; i++) {
+			if (snippetBody[i] === '{') braceDepth++;
+			else if (snippetBody[i] === '}') braceDepth--;
+			else if (braceDepth === 0 && snippetBody[i] === '>') {
+				tagEnd = i;
+				break;
+			}
+		}
+		if (tagEnd === -1) return snippetBody;
+
+		const isSelfClosing = snippetBody[tagEnd - 1] === '/';
+		const attrsStart = tagStart + `<${name}`.length;
+		const attrsEnd = isSelfClosing ? tagEnd - 1 : tagEnd;
+		let attrs = snippetBody.slice(attrsStart, attrsEnd);
+
+		for (const [attrName, value] of changes) {
+			const formatted = formatAttr(attrName, value);
+			const escaped = attrName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+
+			// Try replacing existing: name="...", name={...}, or bare name
+			const patterns = [
+				new RegExp(`(\\s)${escaped}="[^"]*"`),
+				new RegExp(`(\\s)${escaped}=\\{[^}]*\\}`),
+				new RegExp(`(\\s)${escaped}(?=\\s|$)`),
+			];
+
+			let replaced = false;
+			for (const pattern of patterns) {
+				if (pattern.test(attrs)) {
+					attrs = attrs.replace(pattern, `$1${formatted}`);
+					replaced = true;
+					break;
+				}
+			}
+
+			if (!replaced) {
+				attrs += ` ${formatted}`;
+			}
+		}
+
+		const closing = isSelfClosing ? '/>' : '>';
+		return snippetBody.slice(0, attrsStart) + attrs + closing + snippetBody.slice(tagEnd + 1);
+	}
+
+	// Initial values for diffing (computed once per doc change)
+	const initialProps = $derived(meta.args ?? {});
+	const initialCss = $derived.by(() => {
+		const css: Record<string, string> = {};
+		if (cd?.cssProps) {
+			for (const cp of cd.cssProps) {
+				if (cp.default) css[cp.name] = cp.default;
+			}
+		}
+		return css;
+	});
+
+	const usageCode = $derived.by(() => {
+		if (defaultSnippet?.body) {
+			return patchSnippetCode(defaultSnippet.body, componentName, propValues, cssValues, initialProps, initialCss);
+		}
+		return generateFallbackCode(componentName, propValues, cssValues);
+	});
+
+	// Highlighted usage code via server-side Shiki
+	let highlightedUsageHtml = $state('');
+	let highlightTimer: ReturnType<typeof setTimeout> | undefined;
+
+	$effect(() => {
+		const code = usageCode;
+		clearTimeout(highlightTimer);
+		highlightTimer = setTimeout(async () => {
+			try {
+				const res = await fetch('/__sdocs/highlight', {
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					body: JSON.stringify({ code, lang: 'svelte' }),
+				});
+				if (res.ok) {
+					const { html } = await res.json();
+					highlightedUsageHtml = html;
+				}
+			} catch {
+				// Fallback: leave previous value
+			}
+		}, 150);
+	});
 
 	function handleReset() {
 		propValues = { ...(meta.args ?? {}) };
@@ -146,7 +266,7 @@
 		</div>
 		<div class="sdocs-panels">
 			<CollapsiblePanel title="Preview">
-				<PreviewFrame src={focusedSnippet.previewUrl} {activeStylesheet} />
+				<PreviewFrame src={focusedSnippet.previewUrl ?? ''} {activeStylesheet} />
 			</CollapsiblePanel>
 			<CollapsiblePanel title="Code" defaultExpanded={false}>
 				<div class="sdocs-code-block">{@html focusedSnippet.highlightedHtml ?? ''}</div>
@@ -164,17 +284,23 @@
 		<div class="sdocs-panels">
 			<!-- Showcase -->
 			{#if defaultSnippet}
-				<CollapsiblePanel title="Preview">
+				<div class="sdocs-preview-wrapper">
 					<PreviewFrame
-						src={defaultSnippet.previewUrl}
+						src={defaultSnippet.previewUrl ?? ''}
 						props={propValues}
 						cssVars={cssValues}
 						{activeStylesheet}
 					/>
-				</CollapsiblePanel>
+				</div>
 
-				<CollapsiblePanel title="Preview Code">
-					<div class="sdocs-code-block"><pre><code>{usageCode}</code></pre></div>
+				<CollapsiblePanel title="Preview Code" defaultExpanded={false}>
+					<div class="sdocs-code-block">
+						{#if highlightedUsageHtml}
+							{@html highlightedUsageHtml}
+						{:else}
+							<pre><code>{usageCode}</code></pre>
+						{/if}
+					</div>
 				</CollapsiblePanel>
 			{/if}
 
@@ -262,29 +388,37 @@
 				/>
 			</CollapsiblePanel>
 
-			<!-- Examples -->
-			{#if exampleSnippets.length > 0}
-				<h2 class="sdocs-section-title">Examples</h2>
-				{#each exampleSnippets as example (example.name)}
-					<div class="sdocs-example">
-						<h3 class="sdocs-example-title">{example.name}</h3>
-						<CollapsiblePanel title="Preview">
-							<PreviewFrame src={example.previewUrl} {activeStylesheet} />
-						</CollapsiblePanel>
+		</div>
+
+		{#if exampleSnippets.length > 0}
+			<hr class="sdocs-divider" />
+			<h2 class="sdocs-section-title">Examples</h2>
+			{#each exampleSnippets as example (example.name)}
+				<div class="sdocs-example">
+					<h3 class="sdocs-example-title">
+						<Icon name="bookmark" --w="14px" --h="14px" --fill="var(--color-example-500)" />
+						{example.name}
+					</h3>
+					<div class="sdocs-panels">
+						<div class="sdocs-preview-wrapper">
+							<PreviewFrame src={example.previewUrl ?? ''} {activeStylesheet} />
+						</div>
 						<CollapsiblePanel title="Code" defaultExpanded={false}>
 							<div class="sdocs-code-block">{@html example.highlightedHtml ?? ''}</div>
 						</CollapsiblePanel>
 					</div>
-				{/each}
-			{/if}
+				</div>
+			{/each}
+		{/if}
 
-			<!-- Source -->
-			{#if doc.highlightedSource}
+		{#if doc.highlightedSource}
+			<hr class="sdocs-divider" />
+			<div class="sdocs-panels">
 				<CollapsiblePanel title="Component Source" defaultExpanded={false}>
 					<div class="sdocs-code-block">{@html doc.highlightedSource}</div>
 				</CollapsiblePanel>
-			{/if}
-		</div>
+			</div>
+		{/if}
 	{/if}
 </div>
 
@@ -311,13 +445,29 @@
 	.sdocs-panels {
 		display: flex;
 		flex-direction: column;
-		gap: 12px;
+		gap: 1px;
+		border: 1px solid var(--color-base-200);
+		background: var(--color-base-200);
+		border-radius: 8px;
+		overflow: hidden;
+	}
+	.sdocs-preview-wrapper {
+		background: var(--color-base-0);
+		padding: 16px;
+	}
+	.sdocs-divider {
+		border: none;
+		border-top: 1px solid var(--color-base-200);
+		margin: 24px 0;
 	}
 	.sdocs-section-title {
 		font-size: 18px;
 		font-weight: 600;
 		color: var(--color-base-900);
-		margin: 24px 0 8px;
+		margin: 24px 0 16px;
+	}
+	.sdocs-example + .sdocs-example {
+		margin-top: 16px;
 	}
 	.sdocs-example {
 		display: flex;
@@ -325,6 +475,9 @@
 		gap: 8px;
 	}
 	.sdocs-example-title {
+		display: flex;
+		align-items: center;
+		gap: 6px;
 		font-size: 15px;
 		font-weight: 600;
 		color: var(--color-base-800);
@@ -334,6 +487,7 @@
 		overflow-x: auto;
 		font-size: 13px;
 		line-height: 1.5;
+		tab-size: 4;
 	}
 	.sdocs-code-block :global(pre) {
 		margin: 0;

package/dist/client/views/DataTable.svelte

@@ -74,5 +74,6 @@
 		color: var(--color-base-400);
 		font-size: 13px;
 		font-style: italic;
+		margin: 0;
 	}
 </style>

package/dist/client/views/PreviewFrame.svelte

@@ -83,15 +83,11 @@
 
 <style>
 	.sdocs-preview-frame {
-		border: 1px solid var(--color-base-200);
-		border-radius: 6px;
 		overflow: hidden;
 		background: var(--color-base-0);
 	}
 	.sdocs-preview-frame.full-height {
 		flex: 1;
-		border: none;
-		border-radius: 0;
 	}
 	.sdocs-iframe {
 		width: 100%;

package/dist/server/app-gen.js

@@ -33,6 +33,7 @@ function generateIndexHtml(title) {
 	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 	<link rel="icon" type="image/png" href="./client/favicon.png">
 	<title>${title}</title>
+	<style>body { margin: 0; }</style>
 </head>
 <body>
 	<div id="app"></div>