sdocs 0.0.22 → 0.0.25

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to the `sdocs` package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.25] - 2026-07-02
+
+### Added
+
+- **JSDoc prop extraction for plain-JS components.** Both `@type {{ ... }}`
+  object annotations and `@typedef {Object} Props` with `@property` tags on
+  the `$props()` declaration are parsed — types, optionality (bracketed
+  names), and descriptions all flow into the docs and interactive controls.
+- A prop-parser test suite; `npm test` now runs it.
+
+### Fixed
+
+- Props typed as `import('svelte').Snippet` are classified as snippets.
+
+## [0.0.24] - 2026-07-02
+
+### Changed
+
+- Snippets receive `args` as a real snippet parameter: write
+  `{#snippet Default(args)}`. Previews render snippets through `{@render}`,
+  so `args` is an explicit, editor-visible binding instead of a value injected
+  into scope. Parameterless snippets keep working unchanged.
+
+## [0.0.23] - 2026-04-16
+
+First documented release. `sdocs` is a lightweight documentation tool for Svelte 5
+components; this entry describes its capabilities as of 0.0.23.
+
+### Added
+
+- **CLI** — `sdocs dev`, `sdocs build`, `sdocs preview`, and `sdocs init`.
+- **Vite plugin** (`sdocs/vite`) for embedding the explorer in an existing Vite or
+  SvelteKit app, exposing discovered docs through the `virtual:sdocs` module.
+- **Three `.sdoc` kinds** — component docs (`.sdoc`), standalone pages
+  (`.page.sdoc`), and full-page layouts (`.layout.sdoc`).
+- **Prop extraction** from component types, rendered as a props table.
+- **Interactive controls** for live-editing component props and CSS custom
+  properties.
+- **Theming** with light and dark modes and named-stylesheet switching.
+- **Configurable sidebar** ordering and hash-based routing.
+- **Syntax highlighting** via Shiki.
+- Package entry points: `sdocs`, `sdocs/vite`, `sdocs/client`, and `sdocs/ui`.
+
+## [0.0.20] - 2026-04-15
+
+### Changed
+
+- Redesigned the component view and added snippet-based preview code.
+
+## [0.0.18] - 2026-02-27
+
+### Changed
+
+- Scoped the explorer's CSS under `.sdocs-app` to keep its styles from leaking
+  into component previews.
+
+## [0.0.17] - 2026-02-27
+
+### Fixed
+
+- Corrected the `Icon` component imports.
+
+## [0.0.16] - 2026-02-27
+
+### Added
+
+- Rewritten codebase: the current architecture for `.sdoc` discovery, preview
+  rendering, and the component explorer UI.

package/dist/server/config.d.ts

@@ -1,7 +1,11 @@
 import type { SdocsConfig, ResolvedSdocsConfig } from '../types.js';
 /** Find the config file path in the given directory */
 export declare function findConfigFile(root: string): string | null;
+/** Load the raw config from file (unresolved) */
+export declare function loadRawConfig(root: string): Promise<SdocsConfig>;
 /** Load and resolve the sdocs config with defaults */
 export declare function loadConfig(root: string): Promise<ResolvedSdocsConfig>;
+/** Resolve config and finalize paths */
+export declare function resolveAndFinalize(userConfig: SdocsConfig, root: string): ResolvedSdocsConfig;
 /** Merge user config with defaults */
 export declare function resolveConfig(userConfig: SdocsConfig): ResolvedSdocsConfig;

package/dist/server/config.js

@@ -39,18 +39,26 @@ function resolveCssPaths(css, root) {
     }
     return resolved;
 }
-/** Load and resolve the sdocs config with defaults */
-export async function loadConfig(root) {
+/** Load the raw config from file (unresolved) */
+export async function loadRawConfig(root) {
     const configPath = findConfigFile(root);
     if (!configPath)
-        return { ...DEFAULTS };
-    const userConfig = await importConfig(configPath);
+        return {};
+    return importConfig(configPath);
+}
+/** Load and resolve the sdocs config with defaults */
+export async function loadConfig(root) {
+    const rawConfig = await loadRawConfig(root);
+    return resolveAndFinalize(rawConfig, root);
+}
+/** Resolve config and finalize paths */
+export function resolveAndFinalize(userConfig, root) {
     const resolved = resolveConfig(userConfig);
     resolved.include = resolveIncludePatterns(resolved.include, root);
     resolved.css = resolveCssPaths(resolved.css, root);
     return resolved;
 }
-/** Import a config file (supports .js, .mjs, .ts via Vite) */
+/** Import a config file (.js/.mjs; .ts only on Node with native type stripping) */
 async function importConfig(configPath) {
     // Use dynamic import with file:// URL for ESM compatibility
     const mod = await import(pathToFileURL(configPath).href);

package/dist/server/prop-parser.js

@@ -15,9 +15,16 @@ export function parseComponentSource(source) {
     if (scriptContent) {
         const tsAst = ts.createSourceFile('component.ts', scriptContent, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
         const interfaceProps = parseInterfaceProps(tsAst);
+        const jsdocTypeProps = parseJsdocTypeProps(tsAst);
         const destructuredProps = parsePropsDestructuring(tsAst);
         const jsdocData = parseJsdocComments(tsAst);
-        props = mergeProps(interfaceProps, destructuredProps, jsdocData);
+        // TS interface wins over JSDoc types when both exist (they shouldn't).
+        const interfaceNames = new Set(interfaceProps.map((p) => p.name));
+        const typedProps = [
+            ...interfaceProps,
+            ...jsdocTypeProps.filter((p) => !interfaceNames.has(p.name)),
+        ];
+        props = mergeProps(typedProps, destructuredProps, jsdocData);
         methods = parseExportedFunctions(tsAst);
         state = parseExportedState(tsAst);
     }
@@ -52,6 +59,71 @@ function parseInterfaceProps(sourceFile) {
     });
     return props;
 }
+// ─── JSDoc-typed props (plain JS components) ───
+/** Props typed via JSDoc: `@type {{ ... }}` on the $props() declaration, or
+ * `@type {Props}` referencing a `@typedef {Object} Props` with `@property` tags. */
+function parseJsdocTypeProps(sourceFile) {
+    const props = [];
+    function fromTypeLiteral(literal) {
+        for (const member of literal.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+                props.push({
+                    name: member.name.getText(sourceFile),
+                    type: member.type ? member.type.getText(sourceFile) : 'unknown',
+                    optional: !!member.questionToken,
+                    description: null,
+                });
+            }
+        }
+    }
+    function fromTypedef(name) {
+        function visit(node) {
+            // ts.getJSDocTags only surfaces the last JSDoc comment on a node;
+            // a standalone @typedef block above the @type one needs the raw list.
+            const jsDocs = node.jsDoc ?? [];
+            for (const tag of jsDocs.flatMap((jd) => [...(jd.tags ?? [])])) {
+                if (ts.isJSDocTypedefTag(tag) &&
+                    tag.name?.getText(sourceFile) === name &&
+                    tag.typeExpression &&
+                    ts.isJSDocTypeLiteral(tag.typeExpression)) {
+                    for (const propTag of tag.typeExpression.jsDocPropertyTags ?? []) {
+                        const comment = ts.getTextOfJSDocComment(propTag.comment);
+                        props.push({
+                            name: propTag.name.getText(sourceFile),
+                            type: propTag.typeExpression
+                                ? propTag.typeExpression.type.getText(sourceFile)
+                                : 'unknown',
+                            optional: propTag.isBracketed,
+                            description: comment ? comment.replace(/^-\s*/, '').trim() : null,
+                        });
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+    }
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            node.initializer.expression.getText(sourceFile) === '$props' &&
+            ts.isObjectBindingPattern(node.name)) {
+            // The @type tag sits on the enclosing statement; getJSDocType finds it.
+            const typeNode = ts.getJSDocType(node) ?? ts.getJSDocType(node.parent?.parent ?? node);
+            if (typeNode) {
+                if (ts.isTypeLiteralNode(typeNode))
+                    fromTypeLiteral(typeNode);
+                else if (ts.isTypeReferenceNode(typeNode)) {
+                    fromTypedef(typeNode.typeName.getText(sourceFile));
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return props;
+}
 function parsePropsDestructuring(sourceFile) {
     const props = [];
     function visit(node) {
@@ -159,7 +231,8 @@ function mergeProps(interfaceProps, destructuredProps, jsdocData) {
 function classifyProp(name, type) {
     if (name.startsWith('on') && type?.includes('=>'))
         return 'event';
-    if (type?.startsWith('Snippet'))
+    // Matches `Snippet`, `Snippet<[...]>`, and `import('svelte').Snippet`
+    if (type && /(^|\.)Snippet\b/.test(type))
         return 'snippet';
     return 'prop';
 }

package/dist/server/prop-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/prop-parser.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { parseComponentSource } from './prop-parser.js';
+function byName(list, name) {
+    const found = list.find((item) => item.name === name);
+    expect(found, `expected to find "${name}"`).toBeDefined();
+    return found;
+}
+describe('TypeScript components (interface Props)', () => {
+    const source = `<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** The button label text */
+		label?: string;
+		/** Visual style variant */
+		variant?: 'primary' | 'secondary';
+		count: number;
+		/** Click handler */
+		onclick?: (e: MouseEvent) => void;
+		oneTime?: boolean;
+		children?: Snippet;
+		item?: Snippet<[value: string]>;
+	}
+
+	let { label = 'Button', variant = 'primary', count, onclick, oneTime, children, item }: Props = $props();
+</script>
+
+<button>{label}</button>`;
+    const data = parseComponentSource(source);
+    it('extracts types, defaults, descriptions, and requiredness', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.default).toBe('Button');
+        expect(label.description).toBe('The button label text');
+        expect(label.required).toBe(false);
+        const count = byName(data.props, 'count');
+        expect(count.type).toBe('number');
+        expect(count.default).toBe(null);
+        expect(count.required).toBe(true);
+    });
+    it('classifies events, snippets, and on-prefixed non-functions', () => {
+        expect(byName(data.props, 'onclick').category).toBe('event');
+        expect(byName(data.props, 'oneTime').category).toBe('prop');
+        expect(byName(data.props, 'children').category).toBe('snippet');
+        expect(byName(data.props, 'item').category).toBe('snippet');
+    });
+});
+describe('JS components with @type {{ ... }} annotation', () => {
+    const source = `<script>
+	/** @type {{ label?: string, size?: 'sm' | 'lg', onclick?: (e: MouseEvent) => void }} */
+	let { label = 'Badge', size = 'sm', onclick } = $props();
+</script>
+
+<span>{label}</span>`;
+    const data = parseComponentSource(source);
+    it('extracts types and optionality from the annotation', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.default).toBe('Badge');
+        expect(label.required).toBe(false);
+        expect(byName(data.props, 'size').type).toBe("'sm' | 'lg'");
+    });
+    it('classifies events from JSDoc function types', () => {
+        expect(byName(data.props, 'onclick').category).toBe('event');
+    });
+});
+describe('JS components with @typedef/@property', () => {
+    const source = `<script>
+	/**
+	 * @typedef {Object} Props
+	 * @property {string} [label] - The badge label
+	 * @property {number} count - How many
+	 * @property {() => void} [ondismiss] - Called when dismissed
+	 * @property {import('svelte').Snippet} [children] - Body content
+	 */
+
+	/** @type {Props} */
+	let { label = 'Badge', count, ondismiss, children } = $props();
+</script>
+
+<span>{label}{count}</span>`;
+    const data = parseComponentSource(source);
+    it('extracts types, descriptions, and optionality from @property tags', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.description).toBe('The badge label');
+        expect(label.required).toBe(false);
+        expect(label.default).toBe('Badge');
+        const count = byName(data.props, 'count');
+        expect(count.type).toBe('number');
+        expect(count.description).toBe('How many');
+        expect(count.required).toBe(true);
+    });
+    it('classifies events and imported Snippet types', () => {
+        expect(byName(data.props, 'ondismiss').category).toBe('event');
+        expect(byName(data.props, 'children').category).toBe('snippet');
+    });
+});
+describe('untyped JS components', () => {
+    it('still extracts names and defaults from destructuring', () => {
+        const data = parseComponentSource(`<script>
+	let { label = 'x', flag } = $props();
+</script>`);
+        expect(byName(data.props, 'label').default).toBe('x');
+        expect(byName(data.props, 'label').type).toBe(null);
+        expect(byName(data.props, 'flag').required).toBe(true);
+    });
+});
+describe('methods, state, and CSS custom properties', () => {
+    const source = `<script lang="ts">
+	/** Clears the value */
+	export function clear(): void {}
+
+	/** Current count */
+	export const count = $state(0);
+
+	/**
+	 * @cssvar {color} --bg - Background color
+	 * @cssvar {dimension} --radius - Corner radius
+	 */
+</script>
+
+<style>
+	.x {
+		background: var(--bg, #333);
+		border-radius: var(--radius, 4px);
+		padding: var(--pad, 8px);
+	}
+</style>`;
+    const data = parseComponentSource(source);
+    it('extracts exported functions with descriptions', () => {
+        const clear = byName(data.methods, 'clear');
+        expect(clear.returnType).toBe('void');
+        expect(clear.description).toBe('Clears the value');
+    });
+    it('extracts exported state', () => {
+        expect(byName(data.state, 'count').description).toBe('Current count');
+    });
+    it('extracts CSS vars, merging @cssvar type/description with var() defaults', () => {
+        const bg = byName(data.cssProps, '--bg');
+        expect(bg.type).toBe('color');
+        expect(bg.default).toBe('#333');
+        expect(bg.description).toBe('Background color');
+        const pad = byName(data.cssProps, '--pad');
+        expect(pad.type).toBe(null);
+        expect(pad.default).toBe('8px');
+    });
+});

package/dist/server/snippet-compiler.js

@@ -25,7 +25,8 @@ export function generateIframeComponent(absoluteImports, snippetBody) {
     const importBlock = absoluteImports.length > 0
         ? absoluteImports.join('\n') + '\n'
         : '';
-    return `<script>
+    // lang="ts" so lifted imports may carry type-only syntax (Svelte 5 erases it natively)
+    return `<script lang="ts">
 	${importBlock}import { onMount } from 'svelte';
 
 	let args = $state({});
@@ -68,7 +69,10 @@ export function generateIframeComponent(absoluteImports, snippetBody) {
 </script>
 
 <div id="sdocs-preview">
-	${snippetBody}
+	{#snippet SdocsPreview(args)}
+		${snippetBody}
+	{/snippet}
+	{@render SdocsPreview(args)}
 </div>`;
 }
 /** Convert a CSS path to a Vite-servable URL */

package/dist/ui/Button/Button.sdoc

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { ComponentProps } from 'svelte';
 	import Button from './Button.svelte';
 	import { Icon } from '../Icon/index.js';
 
@@ -9,8 +10,8 @@
 	};
 </script>
 
-{#snippet Default()}
-	<Button>Click me</Button>
+{#snippet Default(args: ComponentProps<typeof Button>)}
+	<Button {...args}>Click me</Button>
 {/snippet}
 
 {#snippet WithLeftIcon()}

package/dist/vite.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { loadConfig, resolveConfig } from './server/config.js';
+import { loadRawConfig, resolveAndFinalize } from './server/config.js';
 import { discoverDocFiles, getSdocKind } from './server/discovery.js';
 import { parseDocSource } from './server/meta-parser.js';
 import { parseComponent } from './server/prop-parser.js';
@@ -22,12 +22,9 @@ export function sdocsPlugin(userConfig) {
         name: 'sdocs',
         async configResolved(resolvedConfig) {
             root = resolvedConfig.root;
-            if (userConfig) {
-                config = resolveConfig(userConfig);
-            }
-            else {
-                config = await loadConfig(root);
-            }
+            const fileConfig = await loadRawConfig(root);
+            const merged = { ...fileConfig, ...userConfig };
+            config = resolveAndFinalize(merged, root);
         },
         configureServer(devServer) {
             server = devServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs",
-  "version": "0.0.22",
+  "version": "0.0.25",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "*",