sdocs 0.0.38 → 0.0.40

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.40] - 2026-07-04
+
+### Fixed
+
+- **Wrapped previews bind to the documented component.** When a preview
+  wraps the documented component in another one (a `<Tab>` shown inside
+  `<Tabs>`), method calls and live state used to attach to the outer
+  wrapper — the first capitalized tag in the snippet. The preview ref now
+  binds to the doc's own component wherever it appears in the snippet,
+  falling back to the first capitalized tag when it's absent.
+- **Usage-code patching matches the component name exactly.** Attribute
+  updates from the controls located the root tag with a prefix search, so
+  a component like `Tab` could patch a sibling `<Tabs>` tag instead of its
+  own. The tag search now requires a whole-name match.
+
+## [0.0.39] - 2026-07-04
+
+### Changed
+
+- **Methods and States join the unified section layout.** Methods render a
+  single signature chip (`(params) => returns`, colored like events) with
+  the Run button in the control rail; States show their live value in a
+  "Current value" rail. The value rail widens to align section right edges
+  when it's the last column. All six sections now share one table
+  implementation.
+- **JSDoc types display like TypeScript types.** `import('module').`
+  qualifiers are stripped for display and classification, so
+  `import('svelte').Snippet<[…]>` renders as the same pink `Snippet<[…]>`
+  chip as in TS components.
+
 ## [0.0.38] - 2026-07-04
 
 ### Changed

package/dist/explorer/views/ApiTable.svelte

@@ -16,12 +16,16 @@
 		control?: Snippet<[Row]>;
 		/** Show the Default column (rows without defaults, e.g. events, turn it off) */
 		showDefault?: boolean;
+		/** Header label of the Default column (e.g. "Current value" for states) */
+		defaultLabel?: string;
 	}
 
-	let { rows, control, showDefault = true }: Props = $props();
+	let { rows, control, showDefault = true, defaultLabel = 'Default' }: Props = $props();
 
+	// The default/value column widens to the control-rail width when it is the
+	// last column, so section right edges align.
 	const gridColumns = $derived(
-		['200px', 'minmax(0, 1fr)', ...(showDefault ? ['120px'] : []), ...(control ? ['200px'] : [])].join(' '),
+		['200px', 'minmax(0, 1fr)', ...(showDefault ? [control ? '120px' : '200px'] : []), ...(control ? ['200px'] : [])].join(' '),
 	);
 </script>
 
@@ -30,7 +34,7 @@
 		<div class="sdocs-api-header" style:grid-template-columns={gridColumns}>
 			<div>Name</div>
 			<div>Details</div>
-			{#if showDefault}<div>Default</div>{/if}
+			{#if showDefault}<div>{defaultLabel}</div>{/if}
 			{#if control}<div>Control</div>{/if}
 		</div>
 		{#each rows as row (row.name)}

package/dist/explorer/views/ComponentView.svelte

@@ -4,7 +4,6 @@
 	import { highlightSvelte } from '../highlighter.js';
 	import CollapsiblePanel from './CollapsiblePanel.svelte';
 	import PreviewFrame from './PreviewFrame.svelte';
-	import DataTable from './DataTable.svelte';
 	import ApiTable from './ApiTable.svelte';
 	import PropControl from './PropControl.svelte';
 	import CssPropControl from './CssPropControl.svelte';
@@ -107,8 +106,11 @@
 		if (changes.length === 0) return snippetBody;
 
 		// Find the opening tag: <ComponentName ...> or <ComponentName ... />
-		const tagStart = snippetBody.indexOf(`<${name}`);
-		if (tagStart === -1) return snippetBody;
+		// (whole-name match, so <Tab doesn't hit <Tabs)
+		const escapedName = name.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+		const tagMatch = snippetBody.match(new RegExp(`<${escapedName}(?=[\\s/>])`));
+		if (!tagMatch || tagMatch.index === undefined) return snippetBody;
+		const tagStart = tagMatch.index;
 
 		// Find the end of the opening tag, respecting {} expressions
 		let braceDepth = 0;
@@ -249,15 +251,15 @@
 	const methodsRows = $derived(
 		(cd?.methods ?? []).map((m) => ({
 			name: m.name,
+			type: `(${m.params ?? ''}) => ${m.returnType || 'void'}`,
 			params: m.params,
-			returns: m.returnType,
 			description: m.description,
 		})),
 	);
 
 	const stateRows = $derived(
 		(cd?.state ?? []).map((s) => ({
-			value: s.name in liveStateValues ? JSON.stringify(liveStateValues[s.name]) : undefined,
+			default: s.name in liveStateValues ? JSON.stringify(liveStateValues[s.name]) : undefined,
 			name: s.name,
 			type: s.type,
 			description: s.description,
@@ -380,16 +382,7 @@
 				<Icon name="square-function" --w="15px" --h="15px" --fill="var(--color-base-500)" />
 				Methods
 			</h2>
-			<DataTable
-				columns={[
-					{ key: 'name', label: 'Name', kind: 'name' },
-					{ key: 'params', label: 'Parameters' },
-					{ key: 'returns', label: 'Returns', kind: 'type' },
-					{ key: 'description', label: 'Description', kind: 'text' },
-				]}
-				rows={methodsRows}
-				control={methodsRows.length > 0 ? methodControl : undefined}
-			/>
+			<ApiTable rows={methodsRows} showDefault={false} control={methodControl} />
 		</section>
 
 		<section class="sdocs-doc-section">
@@ -397,15 +390,7 @@
 				<Icon name="database" --w="15px" --h="15px" --fill="var(--color-base-500)" />
 				States
 			</h2>
-			<DataTable
-				columns={[
-					{ key: 'name', label: 'Name', kind: 'name' },
-					{ key: 'type', label: 'Type', kind: 'type' },
-					{ key: 'value', label: 'Current value', kind: 'value' },
-					{ key: 'description', label: 'Description', kind: 'text' },
-				]}
-				rows={stateRows}
-			/>
+			<ApiTable rows={stateRows} defaultLabel="Current value" />
 		</section>
 
 		{#if exampleSnippets.length > 0}

package/dist/explorer/views/format.js

@@ -1,6 +1,12 @@
+/** Drop `import('module').` qualifiers — JSDoc types carry them, TS ones don't */
+function normalizeType(value) {
+    return String(value)
+        .trim()
+        .replace(/import\((['"])[^'"]*\1\)\./g, '');
+}
 /** Classify a type string for color coding (conventions, not a formal standard) */
 export function typeClass(value) {
-    const v = String(value).trim();
+    const v = normalizeType(value);
     if (v === 'string' || /^'[^']*'(\s*\|\s*'[^']*')*$/.test(v))
         return 'string';
     if (v === 'number' || /^\d+(\.\d+)?(\s*\|\s*\d+(\.\d+)?)*$/.test(v))
@@ -36,7 +42,7 @@ export function valueClass(value) {
 }
 /** Split a clean union type into its members; everything else stays whole */
 export function typeParts(value) {
-    const v = String(value).trim();
+    const v = normalizeType(value);
     if (/^'[^']*'(\s*\|\s*'[^']*')+$/.test(v) || /^\d+(\.\d+)?(\s*\|\s*\d+(\.\d+)?)+$/.test(v)) {
         return v.split('|').map((part) => part.trim());
     }

package/dist/server/snippet-compiler.d.ts

@@ -11,7 +11,7 @@ export declare function resolveImportsToAbsolute(imports: string[], docFilePath:
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
  * Includes $state for reactive prop updates via postMessage, invokes
  * component methods on request, and broadcasts exported state values. */
-export declare function generateIframeComponent(absoluteImports: string[], snippetBody: string, stateNames?: string[]): string;
+export declare function generateIframeComponent(absoluteImports: string[], snippetBody: string, stateNames?: string[], componentName?: string): string;
 /** The JS that boots a preview page: mount the wrapper + parent-frame messaging. */
 export declare function generateMountScript(iframeComponentId: string): string;
 /** Generate the HTML page served inside the iframe (dev / CLI-build inputs) */

package/dist/server/snippet-compiler.js

@@ -35,12 +35,21 @@ export function resolveImportsToAbsolute(imports, docFilePath) {
         return imp;
     });
 }
-/** Add bind:this to the snippet's root component so the wrapper can reach
- * its exported methods and state. Skipped when the author already binds. */
-function injectRootRef(snippetBody) {
+/** Add bind:this to the documented component in the snippet so the wrapper
+ * can reach its exported methods and state. Binds the first occurrence of
+ * the doc's component when named (so wrapped children like
+ * <Tabs><Tab/></Tabs> documenting Tab bind the right instance), otherwise
+ * the first capitalized tag. Skipped when the author already binds. */
+function injectRootRef(snippetBody, componentName) {
     if (snippetBody.includes('bind:this'))
         return snippetBody;
-    const match = snippetBody.match(/<([A-Z][A-Za-z0-9_]*)/);
+    let match = null;
+    if (componentName) {
+        const escaped = componentName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+        match = snippetBody.match(new RegExp(`<${escaped}(?=[\\s/>])`));
+    }
+    if (!match)
+        match = snippetBody.match(/<[A-Z][A-Za-z0-9_]*(?=[\s/>])/);
     if (!match || match.index === undefined)
         return snippetBody;
     const insertAt = match.index + match[0].length;
@@ -49,7 +58,7 @@ function injectRootRef(snippetBody) {
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
  * Includes $state for reactive prop updates via postMessage, invokes
  * component methods on request, and broadcasts exported state values. */
-export function generateIframeComponent(absoluteImports, snippetBody, stateNames = []) {
+export function generateIframeComponent(absoluteImports, snippetBody, stateNames = [], componentName) {
     const importBlock = absoluteImports.length > 0
         ? absoluteImports.join('\n') + '\n'
         : '';
@@ -118,7 +127,7 @@ ${stateBroadcast}
 
 <div id="sdocs-preview">
 	{#snippet SdocsPreview(args)}
-		${injectRootRef(snippetBody)}
+		${injectRootRef(snippetBody, componentName)}
 	{/snippet}
 	{@render SdocsPreview(args)}
 </div>`;

package/dist/server/snippet-compiler.test.d.ts

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

package/dist/server/snippet-compiler.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { generateIframeComponent } from './snippet-compiler.js';
+describe('root ref injection', () => {
+    it('binds the documented component, not the wrapper', () => {
+        const out = generateIframeComponent([], '<Tabs>\n\t<Tab {...args} />\n</Tabs>', [], 'Tab');
+        expect(out).toContain('<Tab bind:this={__sdocsRef} {...args} />');
+        expect(out).not.toContain('<Tabs bind:this');
+    });
+    it('binds the first capitalized tag when no component is named', () => {
+        const out = generateIframeComponent([], '<Card><Button /></Card>', []);
+        expect(out).toContain('<Card bind:this={__sdocsRef}>');
+    });
+    it('falls back to the first capitalized tag when the named component is absent', () => {
+        const out = generateIframeComponent([], '<Tabs active={0}>text</Tabs>', [], 'Tab');
+        expect(out).toContain('<Tabs bind:this={__sdocsRef} active={0}>');
+    });
+    it('leaves snippets with an author bind:this untouched', () => {
+        const body = '<Tab bind:this={mine} />';
+        const out = generateIframeComponent([], body, [], 'Tab');
+        expect(out).toContain(body);
+        expect(out).not.toContain('bind:this={__sdocsRef}');
+    });
+});

package/dist/vite.js

@@ -217,7 +217,8 @@ export function sdocsPlugin(userConfig) {
                     return null;
                 const absoluteImports = docImportsCache.get(parsed.docFilePath) ?? [];
                 const stateNames = (entry.componentData?.state ?? []).map((s) => s.name);
-                return generateIframeComponent(absoluteImports, snippet.body, stateNames);
+                const componentName = entry.componentPath?.split('/').pop()?.replace('.svelte', '');
+                return generateIframeComponent(absoluteImports, snippet.body, stateNames, componentName);
             }
             // Virtual mount script for an emitted preview page
             if (id.startsWith('\0' + MOUNT_PREFIX)) {

package/package.json

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

package/dist/explorer/views/DataTable.svelte

@@ -1,121 +0,0 @@
-<script lang="ts">
-	import type { Snippet } from 'svelte';
-	import { typeClass, typeParts, valueClass } from './format.js';
-
-	interface Column {
-		key: string;
-		label: string;
-		/** 'name' renders as bold plain text, 'text' as plain text,
-		 * 'type' as a code chip color-coded by the type,
-		 * 'value' as mono text color-coded by the literal; default is a code chip */
-		kind?: 'name' | 'text' | 'type' | 'value';
-	}
-
-	interface Props {
-		columns: Column[];
-		rows: Record<string, unknown>[];
-		/** When set, adds a Control column rendering this snippet per row */
-		control?: Snippet<[Record<string, unknown>]>;
-	}
-
-	let { columns, rows, control }: Props = $props();
-
-
-</script>
-
-{#if rows.length > 0}
-	<table class="sdocs-table">
-		<thead>
-			<tr>
-				{#each columns as col (col.key)}
-					<th>{col.label}</th>
-				{/each}
-				{#if control}
-					<th class="sdocs-table-control-col">Control</th>
-				{/if}
-			</tr>
-		</thead>
-		<tbody>
-			{#each rows as row, i (i)}
-				<tr>
-					{#each columns as col (col.key)}
-						<td>
-							{#if row[col.key] == null}
-								<span class="sdocs-table-empty">—</span>
-							{:else if col.kind === 'name'}
-								<span class="sdocs-table-name">
-									{row[col.key]}{#if row.required === true}<span class="sdocs-table-required" title="Required">*</span>{/if}
-								</span>
-							{:else if col.kind === 'text'}
-								{row[col.key]}
-							{:else if col.kind === 'type'}
-								{#each typeParts(row[col.key]) as part, i (i)}
-									{#if i > 0}<span class="sdocs-typesep">|</span>{/if}
-									<code class="sdocs-type-{typeClass(row[col.key])}">{part}</code>
-								{/each}
-							{:else if col.kind === 'value'}
-								<span class="sdocs-value sdocs-value-{valueClass(row[col.key])}">{row[col.key]}</span>
-							{:else}
-								<code>{row[col.key]}</code>
-							{/if}
-						</td>
-					{/each}
-					{#if control}
-						<td class="sdocs-table-control-col">
-							{@render control(row)}
-						</td>
-					{/if}
-				</tr>
-			{/each}
-		</tbody>
-	</table>
-{:else}
-	<p class="sdocs-table-none">None</p>
-{/if}
-
-<style>
-	.sdocs-table {
-		width: 100%;
-		border-collapse: collapse;
-		font-size: 13px;
-	}
-	.sdocs-table th {
-		text-align: left;
-		padding: 6px 12px;
-		border-bottom: 2px solid var(--color-base-200);
-		font-weight: 600;
-		color: var(--color-base-600);
-		font-size: 12px;
-	}
-	.sdocs-table td {
-		padding: 6px 12px;
-		border-bottom: 1px solid var(--color-base-100);
-		color: var(--color-base-800);
-	}
-	.sdocs-table code {
-		font-family: var(--mono);
-		font-size: 12px;
-		background: var(--color-base-100);
-		padding: 1px 4px;
-		border-radius: 3px;
-	}
-	.sdocs-table-name {
-		font-weight: 600;
-	}
-	.sdocs-table-required {
-		color: var(--color-red-500);
-	}
-	.sdocs-table-control-col {
-		width: 220px;
-		min-width: 180px;
-	}
-	.sdocs-table-empty {
-		color: var(--color-base-300);
-	}
-	.sdocs-table-none {
-		color: var(--color-base-400);
-		font-size: 13px;
-		font-style: italic;
-		margin: 0;
-	}
-</style>

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

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