sdocs 0.0.17 → 0.0.19

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

@@ -90,11 +90,9 @@
 </div>
 
 <style>
-	:global(body) {
+	.sdocs-app {
 		margin: 0;
 		padding: 0;
-	}
-	.sdocs-app {
 		display: flex;
 		height: 100vh;
 		overflow: hidden;

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/ui/styles/theme.css

@@ -6,7 +6,7 @@
  * Layer 2 — Semantic aliases (per-theme, use these in components)
  */
 
-:root {
+.sdocs-app {
 	/* zinc — Tailwind v4 zinc (oklch), 150-850 interpolated */
 	--color-zinc-0: #fff;
 	--color-zinc-50: oklch(0.985 0 0);
@@ -454,12 +454,12 @@
 	--mono: 'JetBrains Mono', 'SF Mono', Monaco, Consolas, monospace;
 }
 
-body {
+.sdocs-app {
 	font-family: var(--sans);
 }
 
-:root,
-[data-sdocs-theme="light"] {
+.sdocs-app,
+.sdocs-app[data-sdocs-theme="light"] {
 	/* base — layouts, backgrounds, surfaces, borders, text */
 	--color-base-0: var(--color-zinc-0);
 	--color-base-50: var(--color-zinc-50);
@@ -684,7 +684,7 @@ body {
 	--color-action-950: var(--color-blue-950);
 }
 
-[data-sdocs-theme="dark"] {
+.sdocs-app[data-sdocs-theme="dark"] {
 	/* base — layouts, backgrounds, surfaces, borders, text (inverted) */
 	--color-base-0: var(--color-zinc-1000);
 	--color-base-50: var(--color-zinc-950);

package/package.json

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