sdocs 0.0.1

package/dist/internal/PropsTable.svelte

@@ -0,0 +1,342 @@
+<script lang="ts">
+	import type { ArgType, ArgTypes } from '../types.js';
+	import { Checkbox, SegmentControl, InputText, InputNumber, Placeholder, Table } from '../ui/index.js';
+	import type { default as PlaceholderType } from '../ui/Placeholder/Placeholder.svelte';
+
+	interface Props {
+		argTypes: ArgTypes;
+		args: Record<string, unknown>;
+		/** Callback when args change (enables interactive controls) */
+		onchange?: (args: Record<string, unknown>) => void;
+	}
+
+	let { argTypes, args, onchange }: Props = $props();
+
+	let isInteractive = $derived(!!onchange);
+
+	let bangRefs: Record<string, PlaceholderType> = {};
+
+	// Get sorted prop names
+	let propNames = $derived(Object.keys(argTypes).sort());
+
+	function getTypeName(argType: ArgTypes[string]): string {
+		if (argType.type) {
+			if (typeof argType.type === 'string') return argType.type;
+			if (argType.type.name) return argType.type.name;
+		}
+		if (argType.control) {
+			if (typeof argType.control === 'string') return argType.control;
+			if (argType.control.type) return argType.control.type;
+		}
+		return '-';
+	}
+
+	function getDefaultValue(name: string, argType: ArgTypes[string]): string {
+		if (argType.defaultValue !== undefined) {
+			return formatValue(argType.defaultValue);
+		}
+		if (args[name] !== undefined) {
+			return formatValue(args[name]);
+		}
+		return '-';
+	}
+
+	function formatValue(value: unknown): string {
+		if (value === null) return 'null';
+		if (value === undefined) return 'undefined';
+		if (typeof value === 'string') return value;
+		if (typeof value === 'boolean') return value ? 'true' : 'false';
+		if (typeof value === 'number') return String(value);
+		if (typeof value === 'function') return 'Function';
+		if (Array.isArray(value)) return JSON.stringify(value);
+		if (typeof value === 'object') return JSON.stringify(value);
+		return String(value);
+	}
+
+	function getDescription(argType: ArgTypes[string]): string {
+		return argType.description ?? '-';
+	}
+
+	function isRequired(argType: ArgTypes[string]): boolean {
+		return argType.required === true;
+	}
+
+	// Control helpers
+	function getControlType(key: string, argType: ArgType): string | false {
+		if (argType.control === false) return false;
+		if (typeof argType.control === 'string') return argType.control;
+		if (typeof argType.control === 'object') return argType.control.type;
+		// Infer from value
+		const value = args[key];
+		if (typeof value === 'boolean') return 'boolean';
+		if (typeof value === 'number') return 'number';
+		return 'text';
+	}
+
+	function getControlOptions(argType: ArgType): string[] | undefined {
+		if (argType && typeof argType.control === 'object') {
+			return argType.control.options;
+		}
+		return undefined;
+	}
+
+	function getControlConfig(argType: ArgType): { min?: number; max?: number; step?: number } {
+		if (argType && typeof argType.control === 'object') {
+			return { min: argType.control.min, max: argType.control.max, step: argType.control.step };
+		}
+		return {};
+	}
+
+	function isFunctionType(argType: ArgType): boolean {
+		const typeName = typeof argType.type === 'string' ? argType.type : argType.type?.name ?? '';
+		return typeName.includes('=>') || typeName.toLowerCase() === 'function' || typeName.startsWith('(');
+	}
+
+	export function bangProp(name: string) {
+		bangRefs[name]?.bang();
+	}
+
+	function updateArg(key: string, value: unknown) {
+		onchange?.({ ...args, [key]: value });
+	}
+
+	function handleInput(key: string, event: Event) {
+		const target = event.target as HTMLInputElement;
+		const argType = argTypes[key];
+		const controlType = getControlType(key, argType);
+		const currentValue = args[key];
+
+		if (controlType === 'boolean') {
+			updateArg(key, target.checked);
+		} else if (controlType === 'number' || controlType === 'range') {
+			updateArg(key, Number(target.value));
+		} else if ((controlType === 'radio' || controlType === 'select') && typeof currentValue === 'number') {
+			updateArg(key, Number(target.value));
+		} else {
+			updateArg(key, target.value);
+		}
+	}
+</script>
+
+{#if propNames.length > 0}
+	<Table compact fixed borderless>
+		<Table.Head>
+			<Table.Row>
+				<Table.Header width="15%">Name</Table.Header>
+				<Table.Header width="18%">Type</Table.Header>
+				<Table.Header width="12%">Default</Table.Header>
+				<Table.Header width={isInteractive ? '25%' : '55%'}>Description</Table.Header>
+				{#if isInteractive}
+					<Table.Header width="30%">Control</Table.Header>
+				{/if}
+			</Table.Row>
+		</Table.Head>
+		<Table.Body>
+			{#each propNames as name (name)}
+				{@const argType = argTypes[name]}
+				{@const controlType = getControlType(name, argType)}
+				{@const options = getControlOptions(argType)}
+				{@const config = getControlConfig(argType)}
+				<Table.Row>
+					<Table.Cell>
+						<span class="prop-name">
+							<code>{name}</code>
+							{#if isRequired(argType)}
+								<span class="required">*</span>
+							{/if}
+						</span>
+					</Table.Cell>
+					<Table.Cell>
+						<code class="prop-type">{getTypeName(argType)}</code>
+					</Table.Cell>
+					<Table.Cell>
+						<code class="prop-default">{getDefaultValue(name, argType)}</code>
+					</Table.Cell>
+					<Table.Cell>
+						<span class="prop-description">{getDescription(argType)}</span>
+					</Table.Cell>
+					{#if isInteractive}
+						<Table.Cell>
+							<div class="prop-control">
+								{#if controlType === false && isFunctionType(argType)}
+									<Placeholder bind:this={bangRefs[name]} height="28px" radius={6} />
+								{:else if controlType === false}
+									<span class="no-control">-</span>
+								{:else if controlType === 'boolean'}
+									<Checkbox
+										checked={Boolean(args[name])}
+										size="s"
+										onchange={(v) => updateArg(name, v)}
+									/>
+								{:else if controlType === 'select' && options}
+									<select
+										value={String(args[name])}
+										onchange={(e) => handleInput(name, e)}
+									>
+										{#each options as option (option)}
+											<option value={option} selected={String(args[name]) === option}>{option}</option>
+										{/each}
+									</select>
+								{:else if controlType === 'radio' && options}
+									<SegmentControl
+										{options}
+										value={String(args[name])}
+										size="s"
+										onchange={(v) => updateArg(name, typeof args[name] === 'number' ? Number(v) : v)}
+									/>
+								{:else if controlType === 'number'}
+									<InputNumber
+										value={Number(args[name])}
+										min={config.min}
+										max={config.max}
+										step={config.step}
+										size="s"
+										oninput={(v) => updateArg(name, v)}
+									/>
+								{:else if controlType === 'range'}
+									<div class="range-control">
+										<input
+											type="range"
+											value={Number(args[name])}
+											min={config.min ?? 0}
+											max={config.max ?? 100}
+											step={config.step ?? 1}
+											oninput={(e) => handleInput(name, e)}
+										/>
+										<span class="range-value">{args[name]}</span>
+									</div>
+								{:else if controlType === 'color'}
+									<input
+										type="color"
+										value={String(args[name])}
+										oninput={(e) => handleInput(name, e)}
+									/>
+								{:else}
+									<InputText
+										value={String(args[name])}
+										size="s"
+										oninput={(v: string) => updateArg(name, v)}
+									/>
+								{/if}
+							</div>
+						</Table.Cell>
+					{/if}
+				</Table.Row>
+			{/each}
+		</Table.Body>
+	</Table>
+{:else}
+	<p class="no-props">No props defined</p>
+{/if}
+
+<style>
+	.prop-name {
+		white-space: nowrap;
+	}
+
+	.prop-name code {
+		font-family: var(--font-mono);
+		font-weight: 600;
+		color: var(--color-text);
+		background: none;
+		padding: 0;
+	}
+
+	.required {
+		color: var(--danger-500);
+		margin-left: 2px;
+	}
+
+	.prop-type {
+		font-family: var(--font-mono);
+		color: var(--pink-600);
+		background: var(--pink-50);
+		padding: 2px 6px;
+		border-radius: 4px;
+		font-size: 12px;
+		white-space: nowrap;
+	}
+
+	.prop-default {
+		font-family: var(--font-mono);
+		color: var(--color-text-secondary);
+		background: var(--color-bg-hover);
+		padding: 2px 6px;
+		border-radius: 4px;
+		font-size: 12px;
+		white-space: nowrap;
+	}
+
+	.prop-description {
+		color: var(--color-text-secondary);
+		line-height: 1.5;
+	}
+
+	.no-props {
+		color: var(--color-text-muted);
+		font-style: italic;
+		margin: 0;
+	}
+
+	/* Control column */
+	.prop-control {
+		overflow: hidden;
+	}
+
+	.prop-control :global(input.InputText) {
+		width: 100%;
+		max-width: 100%;
+		box-sizing: border-box;
+	}
+
+	.prop-control input[type='color'] {
+		width: 32px;
+		height: 28px;
+		border: 1px solid var(--color-border);
+		border-radius: 4px;
+		cursor: pointer;
+		padding: 2px;
+	}
+
+	.prop-control select {
+		width: 100%;
+		max-width: 160px;
+		height: 28px;
+		padding: 0 8px;
+		border: 1px solid var(--color-border);
+		border-radius: 4px;
+		font-size: 12px;
+		font-family: var(--font-mono);
+		background: var(--color-bg-elevated);
+		color: var(--color-text);
+		cursor: pointer;
+	}
+
+	.prop-control select:focus {
+		outline: none;
+		border-color: var(--color-primary);
+	}
+
+	.range-control {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+	}
+
+	.range-control input[type='range'] {
+		flex: 1;
+		accent-color: var(--action-500);
+	}
+
+	.range-value {
+		min-width: 32px;
+		font-size: 12px;
+		color: var(--color-text-secondary);
+		font-weight: 500;
+		text-align: right;
+	}
+
+	.no-control {
+		color: var(--color-text-muted);
+	}
+</style>

package/dist/internal/PropsTable.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { ArgTypes } from '../types.js';
+interface Props {
+    argTypes: ArgTypes;
+    args: Record<string, unknown>;
+    /** Callback when args change (enables interactive controls) */
+    onchange?: (args: Record<string, unknown>) => void;
+}
+declare const PropsTable: import("svelte").Component<Props, {
+    bangProp: (name: string) => void;
+}, "">;
+type PropsTable = ReturnType<typeof PropsTable>;
+export default PropsTable;

package/dist/internal/Showcase.svelte

@@ -0,0 +1,130 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { ArgType, CssProps, MethodType } from '../types.js';
+	import PropsTable from './PropsTable.svelte';
+	import CssPropsTable from './CssPropsTable.svelte';
+	import MethodsTable from './MethodsTable.svelte';
+	import { CodeBlock, CollapsiblePanel } from '../ui/index.js';
+	import ComponentPreview from './ComponentPreview.svelte';
+
+	interface Props {
+		/** The render function for the component preview */
+		render: Snippet<[Record<string, unknown>]>;
+		/** Current args values */
+		args: Record<string, unknown>;
+		/** Arg type definitions for controls and props table */
+		argTypes?: Record<string, ArgType>;
+		/** CSS custom properties that can be set on the component */
+		cssProps?: CssProps;
+		/** Exported component methods */
+		methods?: MethodType[];
+		/** Callback when args change */
+		onchange?: (args: Record<string, unknown>) => void;
+		/** Optional source code to display */
+		source?: string;
+	}
+
+	let {
+		render,
+		args,
+		argTypes = {},
+		cssProps,
+		methods,
+		onchange,
+		source
+	}: Props = $props();
+
+	// State for CSS prop values
+	let cssValues = $state<Record<string, string>>({});
+
+	// Expand source to include CSS props when they're set
+	let expandedSource = $derived.by(() => {
+		if (!source) return source;
+
+		const activeCssProps = Object.entries(cssValues).filter(([_, v]) => v);
+		if (activeCssProps.length === 0) return source;
+
+		// Build CSS props string with proper indentation
+		const cssPropsStr = activeCssProps
+			.map(([k, v]) => `\t${k}="${v}"`)
+			.join('\n');
+
+		// Insert before the closing /> (self-closing tag)
+		return source.replace(/(\n?\t*)(\/>)/, `\n${cssPropsStr}$1$2`);
+	});
+
+	let propsTableRef: PropsTable | undefined;
+
+	function isFunctionType(argType: ArgType): boolean {
+		const typeName = typeof argType.type === 'string' ? argType.type : argType.type?.name ?? '';
+		return typeName.includes('=>') || typeName.toLowerCase() === 'function' || typeName.startsWith('(');
+	}
+
+	// Create wrapper functions for function-type props that trigger bang in PropsTable
+	let renderArgs = $derived.by(() => {
+		const result = { ...args };
+		for (const [name, argType] of Object.entries(argTypes)) {
+			if (argType.control === false && isFunctionType(argType)) {
+				result[name] = (...fnArgs: unknown[]) => {
+					propsTableRef?.bangProp(name);
+				};
+			}
+		}
+		return result;
+	});
+
+	function handleArgsChange(newArgs: Record<string, unknown>) {
+		onchange?.(newArgs);
+	}
+
+	function handleCssChange(newValues: Record<string, string>) {
+		cssValues = newValues;
+	}
+
+	let hasProps = $derived(Object.keys(argTypes).length > 0);
+	let hasCssProps = $derived(cssProps && Object.keys(cssProps).length > 0);
+	let hasMethods = $derived(methods && methods.length > 0);
+</script>
+
+<div class="Showcase">
+	<ComponentPreview cssVars={cssValues}>
+		{@render render(renderArgs)}
+	</ComponentPreview>
+
+	{#if hasProps}
+		<CollapsiblePanel title="Props" no_content_padding>
+			<PropsTable bind:this={propsTableRef} {argTypes} {args} onchange={onchange ? handleArgsChange : undefined} />
+		</CollapsiblePanel>
+	{/if}
+
+	{#if hasCssProps && cssProps}
+		<CollapsiblePanel title="CSS Props" no_content_padding>
+			<CssPropsTable {cssProps} values={cssValues} onchange={handleCssChange} />
+		</CollapsiblePanel>
+	{/if}
+
+	{#if hasMethods && methods}
+		<CollapsiblePanel title="Methods" no_content_padding>
+			<MethodsTable {methods} />
+		</CollapsiblePanel>
+	{/if}
+
+	{#if expandedSource}
+		<CollapsiblePanel title="Code" open={false} no_content_padding>
+			<CodeBlock code={expandedSource} />
+		</CollapsiblePanel>
+	{/if}
+</div>
+
+<style>
+	.Showcase {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		background: var(--color-border);
+		border: 1px solid var(--color-border);
+		border-radius: 8px;
+		box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
+		overflow: hidden;
+	}
+</style>

package/dist/internal/Showcase.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+import type { ArgType, CssProps, MethodType } from '../types.js';
+interface Props {
+    /** The render function for the component preview */
+    render: Snippet<[Record<string, unknown>]>;
+    /** Current args values */
+    args: Record<string, unknown>;
+    /** Arg type definitions for controls and props table */
+    argTypes?: Record<string, ArgType>;
+    /** CSS custom properties that can be set on the component */
+    cssProps?: CssProps;
+    /** Exported component methods */
+    methods?: MethodType[];
+    /** Callback when args change */
+    onchange?: (args: Record<string, unknown>) => void;
+    /** Optional source code to display */
+    source?: string;
+}
+declare const Showcase: import("svelte").Component<Props, {}, "">;
+type Showcase = ReturnType<typeof Showcase>;
+export default Showcase;

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+import type { Component, Snippet } from 'svelte';
+/**
+ * Control types for the props panel
+ */
+export type ControlType = 'text' | 'number' | 'boolean' | 'select' | 'radio' | 'color' | 'range';
+/**
+ * Control configuration for a single arg
+ */
+export interface ArgType {
+    /** Control type or false to disable control (prop still shows in table) */
+    control: ControlType | {
+        type: ControlType;
+        options?: string[];
+        min?: number;
+        max?: number;
+        step?: number;
+    } | false;
+    /** Description of the prop */
+    description?: string;
+    /** Type information for the props table */
+    type?: {
+        name: string;
+        summary?: string;
+    };
+    /** Whether this prop is required */
+    required?: boolean;
+    /** Default value for display in props table */
+    defaultValue?: unknown;
+}
+/**
+ * Map of prop names to their ArgType configuration
+ */
+export type ArgTypes = Record<string, ArgType>;
+/**
+ * Control types for CSS custom properties
+ */
+export type CssControlType = 'color' | 'text' | 'length' | 'number' | 'select';
+/**
+ * Configuration for a CSS custom property
+ */
+export interface CssPropType {
+    /** Description of the CSS prop */
+    description?: string;
+    /** Default value */
+    default?: string;
+    /** Control type or config. Use false to disable control. */
+    control?: CssControlType | {
+        type: CssControlType;
+        options?: string[];
+    } | false;
+}
+/**
+ * Map of CSS prop names to their configuration
+ */
+export type CssProps = Record<string, CssPropType>;
+/**
+ * Exported component method
+ */
+export interface MethodType {
+    name: string;
+    params?: string;
+    returnType?: string;
+    description?: string;
+}
+/**
+ * Metadata exported from a .docs.svelte or .docs.svx file
+ */
+export interface DocMeta {
+    title?: string;
+    /** Component description (extracted from JSDoc) */
+    description?: string;
+    /** Component to document (if this is a component doc) */
+    component?: Component<any>;
+    /** Initial values for props (only for props that exist in the component) */
+    args?: Record<string, unknown>;
+}
+/**
+ * Parsed metadata with auto-generated fields (internal use)
+ */
+export interface ParsedDocMeta extends DocMeta {
+    /** Auto-generated from component props */
+    args?: Record<string, unknown>;
+    /** Auto-generated from component interface Props */
+    argTypes?: Record<string, ArgType>;
+    /** Auto-generated from @cssvar JSDoc tags */
+    cssProps?: CssProps;
+    /** Auto-generated from exported functions */
+    methods?: MethodType[];
+}
+/**
+ * A single example extracted from a doc file
+ */
+export interface Example {
+    name: string;
+    render: Snippet<[args: Record<string, unknown>]> | Snippet<[]>;
+    /** Source code of the snippet (extracted by vite plugin) */
+    source?: string;
+}
+/**
+ * Parsed doc file with metadata and examples
+ */
+export interface DocFile {
+    path: string;
+    meta: ParsedDocMeta;
+    examples: Example[];
+    module: Record<string, unknown>;
+    /** Type of doc: 'component' has a component in meta, 'page' is standalone documentation */
+    type: 'component' | 'page';
+    /** Whether this file is a markdown (.svx) file */
+    isMarkdown?: boolean;
+}
+/**
+ * Sidebar configuration options
+ */
+export interface SidebarOptions {
+    /**
+     * Custom order for sidebar items. Use '*' for "everything else" (alphabetically).
+     *
+     * Can be an array for top-level ordering, or an object for nested folder ordering.
+     * Use path keys (e.g., 'Components/Forms') for deep nesting.
+     * @example
+     * // Top-level only
+     * order: ['Specs', 'Components', '*']
+     *
+     * // With nested folder ordering
+     * order: {
+     *   root: ['Specs', '*'],
+     *   Specs: ['Sidebar', 'Doc Files', '*'],
+     *   'Components/Forms': ['Input', 'Select', '*']
+     * }
+     */
+    order?: string[] | Record<string, string[]>;
+    /**
+     * Paths to expand by default in the sidebar.
+     * @example
+     * open: ['Layout', 'Layout/Frame', 'Components']
+     */
+    open?: string[];
+}
+/**
+ * Sdocs configuration options
+ */
+export interface SdocsOptions {
+    /** Sidebar configuration */
+    sidebar?: SidebarOptions;
+}
+/**
+ * Props for the main Sdocs component
+ */
+export interface SdocsProps {
+    /**
+     * Configuration options for Sdocs.
+     * @example
+     * options: {
+     *   sidebar: {
+     *     order: { root: ['Layout', '*'] },
+     *     open: ['Layout']
+     *   }
+     * }
+     */
+    options?: SdocsOptions;
+}

package/dist/types.js

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