sdocs 0.0.36 → 0.0.37

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.37] - 2026-07-03
+
+### Changed
+
+- **The component page is a live API reference.** The separate Controls
+  panel is gone — controls sit inside the API tables, on the row of the
+  prop or CSS custom property they drive. Props, CSS Props, Events, and
+  Snippets share a composite row layout: name (with a red `*` when
+  required), type and description stacked in the middle, an explicit
+  Default column (`—` when absent), and a fixed control rail. Reset moved
+  next to the Props title.
+- **Sections instead of collapsible panels.** The reference sections render
+  flat with icon titles; only the preview and its code stay in the bordered
+  card (Preview Code still collapses). "State" is now "States", matching
+  the plural sibling sections. The page grew to 1120px.
+- **Color-coded types and values.** Type chips are tinted by kind — strings
+  green, numbers and dimensions amber, booleans purple, callbacks blue,
+  snippets pink, colors cyan, `void` slate — union members render as
+  individual chips, and default/state literals are colored plain text.
+  Both themes are handled explicitly.
+
+### Added
+
+- **Run buttons for methods.** Zero-argument methods can be invoked
+  directly from the Methods table and act on the live preview; methods
+  with parameters show a disabled button.
+- **Live state values.** The States table shows each exported state's
+  current value, streamed from the preview as it changes.
+- Section icons (sliders, palette, zap, function, database) join the UI
+  icon set.
+
 ## [0.0.36] - 2026-07-03
 
 ### Fixed

package/dist/explorer/views/ApiTable.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { typeClass, typeParts, valueClass } from './format.js';
+
+	interface Row {
+		name: string;
+		type?: string | null;
+		default?: string | null;
+		description?: string | null;
+		required?: boolean;
+	}
+
+	interface Props {
+		rows: Row[];
+		/** Renders the per-row control in the fixed right rail */
+		control?: Snippet<[Row]>;
+		/** Show the Default column (rows without defaults, e.g. events, turn it off) */
+		showDefault?: boolean;
+	}
+
+	let { rows, control, showDefault = true }: Props = $props();
+
+	const gridColumns = $derived(
+		['200px', 'minmax(0, 1fr)', ...(showDefault ? ['120px'] : []), ...(control ? ['200px'] : [])].join(' '),
+	);
+</script>
+
+{#if rows.length > 0}
+	<div class="sdocs-api-list">
+		<div class="sdocs-api-header" style:grid-template-columns={gridColumns}>
+			<div>Name</div>
+			<div>Details</div>
+			{#if showDefault}<div>Default</div>{/if}
+			{#if control}<div>Control</div>{/if}
+		</div>
+		{#each rows as row (row.name)}
+			<div class="sdocs-api-row" style:grid-template-columns={gridColumns}>
+				<div class="sdocs-api-name">
+					{row.name}{#if row.required}<span class="sdocs-api-required" title="Required">*</span>{/if}
+				</div>
+				<div class="sdocs-api-middle">
+					{#if row.type}
+						<div class="sdocs-api-meta">
+							{#each typeParts(row.type) as part, i (i)}
+								{#if i > 0}<span class="sdocs-typesep">|</span>{/if}
+								<code class="sdocs-type-{typeClass(row.type)}">{part}</code>
+							{/each}
+						</div>
+					{/if}
+					{#if row.description}
+						<div class="sdocs-api-desc">{row.description}</div>
+					{/if}
+				</div>
+				{#if showDefault}
+					<div class="sdocs-api-default">
+						{#if row.default != null}
+							<span class="sdocs-value sdocs-value-{valueClass(row.default)}">{row.default}</span>
+						{:else}
+							<span class="sdocs-api-empty">—</span>
+						{/if}
+					</div>
+				{/if}
+				{#if control}
+					<div class="sdocs-api-control">
+						{@render control(row)}
+					</div>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{:else}
+	<p class="sdocs-api-none">None</p>
+{/if}
+
+<style>
+	.sdocs-api-list {
+		display: flex;
+		flex-direction: column;
+	}
+	.sdocs-api-header {
+		display: grid;
+		grid-template-columns: 200px minmax(0, 1fr) 120px 200px;
+		gap: 20px;
+		padding: 6px 12px;
+		border-bottom: 2px solid var(--color-base-200);
+		font-size: 12px;
+		font-weight: 600;
+		color: var(--color-base-600);
+	}
+	.sdocs-api-row {
+		display: grid;
+		grid-template-columns: 200px minmax(0, 1fr) 120px 200px;
+		gap: 20px;
+		align-items: start;
+		padding: 12px 12px;
+		border-bottom: 1px solid var(--color-base-100);
+		font-size: 13px;
+	}
+	.sdocs-api-name {
+		font-weight: 600;
+		color: var(--color-base-900);
+		overflow-wrap: break-word;
+	}
+	.sdocs-api-required {
+		color: var(--color-red-500);
+	}
+	.sdocs-api-middle {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		min-width: 0;
+	}
+	.sdocs-api-meta {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: baseline;
+		gap: 6px;
+	}
+	.sdocs-api-desc {
+		color: var(--color-base-500);
+	}
+	.sdocs-api-default {
+		overflow-wrap: break-word;
+		min-width: 0;
+	}
+	.sdocs-api-empty {
+		color: var(--color-base-300);
+	}
+	.sdocs-api-control {
+		min-width: 0;
+	}
+	.sdocs-api-none {
+		color: var(--color-base-400);
+		font-size: 13px;
+		font-style: italic;
+		margin: 0;
+	}
+</style>

package/dist/explorer/views/ApiTable.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 ApiTableProps = typeof __propDef.props;
+export type ApiTableEvents = typeof __propDef.events;
+export type ApiTableSlots = typeof __propDef.slots;
+export default class ApiTable extends SvelteComponentTyped<ApiTableProps, ApiTableEvents, ApiTableSlots> {
+}
+export {};

package/dist/explorer/views/ComponentView.svelte

@@ -4,8 +4,10 @@
 	import { highlightSvelte } from '../highlighter.js';
 	import CollapsiblePanel from './CollapsiblePanel.svelte';
 	import PreviewFrame from './PreviewFrame.svelte';
-	import ControlsPanel from './ControlsPanel.svelte';
 	import DataTable from './DataTable.svelte';
+	import ApiTable from './ApiTable.svelte';
+	import PropControl from './PropControl.svelte';
+	import CssPropControl from './CssPropControl.svelte';
 
 	interface Props {
 		doc: DocEntry;
@@ -32,6 +34,10 @@
 	let propValues = $state<Record<string, unknown>>({});
 	let cssValues = $state<Record<string, string>>({});
 
+	// Live wiring to the default preview: method invocation + exported state values
+	let defaultPreview = $state<{ callMethod: (name: string) => void }>();
+	let liveStateValues = $state<Record<string, unknown>>({});
+
 	// Initialize from meta.args (build new objects to avoid read+write loop)
 	$effect(() => {
 		propValues = { ...(meta.args ?? {}) };
@@ -200,13 +206,17 @@
 		cssValues = newCss;
 	}
 
+	const hasEditableControls = $derived(
+		!!cd && (cd.props.some((p) => p.category === 'prop') || cd.cssProps.length > 0),
+	);
+
 	// Table data builders
 	const propsRows = $derived(
 		(cd?.props ?? []).filter((p) => p.category === 'prop').map((p) => ({
 			name: p.name,
 			type: p.type,
 			default: p.default,
-			required: p.required ? 'Yes' : '',
+			required: p.required,
 			description: p.description,
 		})),
 	);
@@ -247,6 +257,7 @@
 
 	const stateRows = $derived(
 		(cd?.state ?? []).map((s) => ({
+			value: s.name in liveStateValues ? JSON.stringify(liveStateValues[s.name]) : undefined,
 			name: s.name,
 			type: s.type,
 			description: s.description,
@@ -282,10 +293,12 @@
 			{#if defaultSnippet}
 				<div class="sdocs-preview-wrapper">
 					<PreviewFrame
+						bind:this={defaultPreview}
 						src={defaultSnippet.previewUrl ?? ''}
 						props={propValues}
 						cssVars={cssValues}
 						{activeStylesheet}
+						onStateValues={(values) => (liveStateValues = values)}
 					/>
 				</div>
 
@@ -299,92 +312,101 @@
 					</div>
 				</CollapsiblePanel>
 			{/if}
+		</div>
 
-			{#if cd && ((cd.props.filter((p) => p.category === 'prop').length > 0) || cd.cssProps.length > 0)}
-				<CollapsiblePanel title="Controls">
-					<ControlsPanel
-						componentProps={cd.props}
-						cssProps={cd.cssProps}
-						{propValues}
-						{cssValues}
-						onPropChange={handlePropChange}
-						onCssChange={handleCssChange}
-						onReset={handleReset}
-					/>
-				</CollapsiblePanel>
+		{#snippet propControl(row: Record<string, unknown>)}
+			{@const prop = cd?.props.find((p) => p.name === row.name && p.category === 'prop')}
+			{#if prop}
+				<PropControl {prop} value={propValues[prop.name]} onchange={(v) => handlePropChange(prop.name, v)} />
 			{/if}
-
-			<CollapsiblePanel title="Props">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'type', label: 'Type' },
-						{ key: 'default', label: 'Default' },
-						{ key: 'required', label: 'Required' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={propsRows}
-				/>
-			</CollapsiblePanel>
-
-			<CollapsiblePanel title="CSS Props">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'type', label: 'Type' },
-						{ key: 'default', label: 'Default' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={cssPropsRows}
-				/>
-			</CollapsiblePanel>
-
-			<CollapsiblePanel title="Events">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'type', label: 'Type' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={eventsRows}
-				/>
-			</CollapsiblePanel>
-
-			<CollapsiblePanel title="Snippets">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'type', label: 'Type' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={snippetsRows}
-				/>
-			</CollapsiblePanel>
-
-			<CollapsiblePanel title="Methods">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'params', label: 'Parameters' },
-						{ key: 'returns', label: 'Returns' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={methodsRows}
-				/>
-			</CollapsiblePanel>
-
-			<CollapsiblePanel title="State">
-				<DataTable
-					columns={[
-						{ key: 'name', label: 'Name' },
-						{ key: 'type', label: 'Type' },
-						{ key: 'description', label: 'Description' },
-					]}
-					rows={stateRows}
-				/>
-			</CollapsiblePanel>
-
-		</div>
+		{/snippet}
+
+		{#snippet methodControl(row: Record<string, unknown>)}
+			{@const hasParams = String(row.params ?? '').trim().length > 0}
+			<button
+				class="sdocs-run-btn"
+				disabled={hasParams || !defaultPreview}
+				title={hasParams ? 'Only methods without parameters can be run here' : `Run ${row.name}() on the preview`}
+				onclick={() => defaultPreview?.callMethod(String(row.name))}
+			>
+				Run
+			</button>
+		{/snippet}
+
+		{#snippet cssPropControl(row: Record<string, unknown>)}
+			{@const cssProp = cd?.cssProps.find((p) => p.name === row.name)}
+			{#if cssProp}
+				<CssPropControl {cssProp} value={cssValues[cssProp.name]} onchange={(v) => handleCssChange(cssProp.name, v)} />
+			{/if}
+		{/snippet}
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<Icon name="sliders-horizontal" --w="15px" --h="15px" --fill="var(--color-base-500)" />
+				Props
+				{#if hasEditableControls}
+					<button class="sdocs-reset-btn" onclick={handleReset}>Reset</button>
+				{/if}
+			</h2>
+			<ApiTable rows={propsRows} control={propControl} />
+		</section>
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<Icon name="palette" --w="15px" --h="15px" --fill="var(--color-base-500)" />
+				CSS Props
+			</h2>
+			<ApiTable rows={cssPropsRows} control={cssPropControl} />
+		</section>
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<Icon name="zap" --w="15px" --h="15px" --fill="var(--color-base-500)" />
+				Events
+			</h2>
+			<ApiTable rows={eventsRows} showDefault={false} />
+		</section>
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<Icon name="code" --w="15px" --h="15px" --fill="var(--color-base-500)" />
+				Snippets
+			</h2>
+			<ApiTable rows={snippetsRows} showDefault={false} />
+		</section>
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<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}
+			/>
+		</section>
+
+		<section class="sdocs-doc-section">
+			<h2 class="sdocs-doc-section-title">
+				<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}
+			/>
+		</section>
 
 		{#if exampleSnippets.length > 0}
 			<hr class="sdocs-divider" />
@@ -421,9 +443,54 @@
 <style>
 	.sdocs-component-view {
 		padding: 24px 32px;
-		max-width: 960px;
+		max-width: 1120px;
 		font-family: var(--sans);
 	}
+	.sdocs-doc-section {
+		margin-top: 28px;
+	}
+	.sdocs-doc-section-title {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		margin: 0 0 10px;
+		font-size: 14px;
+		font-weight: 600;
+		color: var(--color-base-800);
+	}
+	.sdocs-doc-section-title .sdocs-reset-btn {
+		margin-left: auto;
+	}
+	.sdocs-reset-btn {
+		padding: 4px 12px;
+		border: 1px solid var(--color-base-200);
+		border-radius: 4px;
+		background: var(--color-base-0);
+		font: inherit;
+		font-size: 12px;
+		color: var(--color-base-600);
+		cursor: pointer;
+	}
+	.sdocs-reset-btn:hover {
+		background: var(--color-base-100);
+	}
+	.sdocs-run-btn {
+		padding: 3px 12px;
+		border: 1px solid var(--color-base-200);
+		border-radius: 4px;
+		background: var(--color-base-0);
+		font: inherit;
+		font-size: 12px;
+		color: var(--color-base-600);
+		cursor: pointer;
+	}
+	.sdocs-run-btn:hover:not(:disabled) {
+		background: var(--color-base-100);
+	}
+	.sdocs-run-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
+	}
 	.sdocs-view-header {
 		margin-bottom: 24px;
 	}

package/dist/explorer/views/CssPropControl.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import type { ParsedCssProp } from '../../types.js';
+	import { Text as TextControl, Color as ColorControl, Dimension as DimensionControl } from '../../ui/Control/index.js';
+
+	interface Props {
+		cssProp: ParsedCssProp;
+		value: string | undefined;
+		onchange: (value: string) => void;
+	}
+
+	let { cssProp, value, onchange }: Props = $props();
+
+	const controlType = $derived.by(() => {
+		const t = cssProp.type?.toLowerCase() ?? '';
+		if (t === 'color') return 'color';
+		if (t === 'dimension') return 'dimension';
+		return 'text';
+	});
+</script>
+
+{#if controlType === 'color'}
+	<ColorControl value={value ?? cssProp.default ?? '#000000'} {onchange} />
+{:else if controlType === 'dimension'}
+	<DimensionControl value={value ?? cssProp.default ?? '0px'} {onchange} />
+{:else}
+	<TextControl value={value ?? cssProp.default ?? ''} {onchange} />
+{/if}

package/dist/explorer/views/CssPropControl.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 CssPropControlProps = typeof __propDef.props;
+export type CssPropControlEvents = typeof __propDef.events;
+export type CssPropControlSlots = typeof __propDef.slots;
+export default class CssPropControl extends SvelteComponentTyped<CssPropControlProps, CssPropControlEvents, CssPropControlSlots> {
+}
+export {};

package/dist/explorer/views/DataTable.svelte

@@ -1,15 +1,26 @@
 <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 }: Props = $props();
+	let { columns, rows, control }: Props = $props();
+
+
 </script>
 
 {#if rows.length > 0}
@@ -19,6 +30,9 @@
 				{#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>
@@ -26,13 +40,31 @@
 				<tr>
 					{#each columns as col (col.key)}
 						<td>
-							{#if row[col.key] != null}
-								<code>{row[col.key]}</code>
-							{:else}
+							{#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>
@@ -67,6 +99,16 @@
 		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);
 	}

package/dist/explorer/views/PreviewFrame.svelte

@@ -7,9 +7,16 @@
 		cssVars?: Record<string, string>;
 		activeStylesheet?: string;
 		fullHeight?: boolean;
+		/** Called with the preview component's exported state values whenever they change */
+		onStateValues?: (values: Record<string, unknown>) => void;
 	}
 
-	let { src, props = {}, cssVars = {}, activeStylesheet, fullHeight = false }: Props = $props();
+	let { src, props = {}, cssVars = {}, activeStylesheet, fullHeight = false, onStateValues }: Props = $props();
+
+	/** Invoke a zero-argument method on the preview's root component */
+	export function callMethod(name: string): void {
+		iframe?.contentWindow?.postMessage({ type: 'sdocs:call-method', name }, '*');
+	}
 
 	// Preview URLs are root-absolute; hosts serving under a sub-path pass the
 	// prefix via the Explorer's previewBase prop (see Explorer.svelte).
@@ -30,6 +37,9 @@
 			if (e.data?.type === 'sdocs:resize' && e.source === iframe?.contentWindow) {
 				contentHeight = e.data.height;
 			}
+			if (e.data?.type === 'sdocs:state-values' && e.source === iframe?.contentWindow) {
+				onStateValues?.(e.data.values);
+			}
 		}
 		window.addEventListener('message', onMessage);
 		return () => window.removeEventListener('message', onMessage);

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

@@ -1,6 +1,8 @@
 import { SvelteComponentTyped } from "svelte";
 declare const __propDef: {
-    props: Record<string, never>;
+    props: {
+        callMethod?: (name: string) => void;
+    };
     events: {
         [evt: string]: CustomEvent<any>;
     };
@@ -10,5 +12,6 @@ export type PreviewFrameProps = typeof __propDef.props;
 export type PreviewFrameEvents = typeof __propDef.events;
 export type PreviewFrameSlots = typeof __propDef.slots;
 export default class PreviewFrame extends SvelteComponentTyped<PreviewFrameProps, PreviewFrameEvents, PreviewFrameSlots> {
+    get callMethod(): (name: string) => void;
 }
 export {};