sdocs 0.0.35 → 0.0.37

package/CHANGELOG.md

@@ -7,6 +7,48 @@ 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
+
+- **Usage code is syntax-highlighted in static builds.** The usage snippet
+  regenerates in the browser as controls change and used to be highlighted
+  through a dev-server endpoint — deployed builds fell back to plain text.
+  Highlighting now runs client-side (lazy-loaded Shiki with the JavaScript
+  regex engine), identical on the dev server and any static host; the
+  dev-server endpoint is gone.
+
 ## [0.0.35] - 2026-07-03
 
 ### Fixed

package/dist/explorer/highlighter.d.ts

@@ -0,0 +1,2 @@
+/** Highlight Svelte code, matching the build-time highlighter's output shape */
+export declare function highlightSvelte(code: string): Promise<string>;

package/dist/explorer/highlighter.js

@@ -0,0 +1,33 @@
+// Client-side Shiki for code that's generated in the browser (the usage
+// snippet re-renders as controls change). Everything loads lazily on first
+// use so the Explorer bundle stays lean, and the JavaScript regex engine
+// avoids shipping wasm — highlighting works the same on the dev server and
+// in static builds.
+let highlighterPromise;
+async function getHighlighter() {
+    highlighterPromise ??= (async () => {
+        const [{ createHighlighterCore }, { createJavaScriptRegexEngine }, { bundledLanguages }, { bundledThemes }] = await Promise.all([
+            import('shiki/core'),
+            import('shiki/engine/javascript'),
+            import('shiki/langs'),
+            import('shiki/themes'),
+        ]);
+        return createHighlighterCore({
+            langs: [bundledLanguages.svelte],
+            themes: [bundledThemes['github-light'], bundledThemes['github-dark']],
+            engine: createJavaScriptRegexEngine({ forgiving: true }),
+        });
+    })();
+    return highlighterPromise;
+}
+/** Highlight Svelte code, matching the build-time highlighter's output shape */
+export async function highlightSvelte(code) {
+    const highlighter = await getHighlighter();
+    return highlighter.codeToHtml(code, {
+        lang: 'svelte',
+        themes: {
+            light: 'github-light',
+            dark: 'github-dark',
+        },
+    });
+}

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

@@ -1,10 +1,13 @@
 <script lang="ts">
 	import type { DocEntry } from '../../types.js';
 	import { Icon } from '../../ui/Icon/index.js';
+	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;
@@ -31,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 ?? {}) };
@@ -169,36 +176,20 @@
 		return generateFallbackCode(componentName, propValues, cssValues);
 	});
 
-	// Highlighted usage code via server-side Shiki. The endpoint is dev-server
-	// middleware; in a production build it doesn't exist, so after the first
-	// failure stop asking and fall back to plain code.
+	// Usage code is generated in the browser, so it's highlighted client-side
+	// (lazy Shiki — see ../highlighter.ts). Debounced while controls change;
+	// stale results are dropped.
 	let highlightedUsageHtml = $state('');
 	let highlightTimer: ReturnType<typeof setTimeout> | undefined;
-	let highlightAvailable = true;
 
 	$effect(() => {
 		const code = usageCode;
 		clearTimeout(highlightTimer);
-		if (!highlightAvailable) {
-			highlightedUsageHtml = '';
-			return;
-		}
 		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;
-				} else {
-					highlightAvailable = false;
-					highlightedUsageHtml = '';
-				}
+				const html = await highlightSvelte(code);
+				if (code === usageCode) highlightedUsageHtml = html;
 			} catch {
-				highlightAvailable = false;
 				highlightedUsageHtml = '';
 			}
 		}, 150);
@@ -215,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,
 		})),
 	);
@@ -262,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,
@@ -297,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>
 
@@ -314,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" />
@@ -436,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 {};