sdocs 0.0.40 → 0.0.42

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.42] - 2026-07-04
+
+### Changed
+
+- **Breaking: `.sdoc` files are the block format.** A doc file is now
+  `<script>` on top, `[DOCS]`/`[PAGE]`/`[LAYOUT]` entity blocks in the
+  middle, `<style>` at the bottom — the language documented in the site's
+  Language section. Each entity is its own sidebar entry, so one file can
+  hold several. The `export const meta` convention, `{#snippet}` extraction,
+  auto-generated `Default` previews, and the `.page.sdoc`/`.layout.sdoc`
+  filename kinds are gone.
+- **`[DOCS]` holds any number of previews.** Each
+  `[preview component={X} args={{…}}]` is self-contained; several render as
+  tabs, each a fully live panel with its own controls, extracted API tables,
+  and component source. `[example title="…"]` blocks are frozen and render
+  page-level below the tabs.
+- **`[PAGE]` bodies are markdown** — GFM with `{expression}` interpolation
+  and Svelte component islands; code fences and inline code are inert. The
+  table of contents comes from the markdown headings.
+- **Parsing never crashes the dev server.** Doc files parse through the
+  `sdocs/language` scanner; mistakes surface as file:line warnings and the
+  rest of the file keeps working.
+- **Breaking for embedders:** `DocEntry` is reshaped (`previews`/`examples`/
+  `content` replace `snippets`/`componentData`), and preview URLs address
+  entities as `path#slug`.
+
+## [0.0.41] - 2026-07-04
+
+### Added
+
+- **`sdocs/language`** — a scanner and parser for the block-based sdoc
+  format: line-anchored `[DOCS]`/`[PAGE]`/`[LAYOUT]` entities with
+  `[preview]`/`[example]` sub-blocks, Svelte-style attributes, precise
+  source spans, and recoverable diagnostics (it never throws, and keeps
+  scanning past mistakes). Groundwork for the format switch — the runtime
+  still reads the current `.sdoc` format.
+- **A TextMate grammar for sdoc** at `sdocs/grammar/sdoc.tmLanguage.json`,
+  usable by any TextMate-compatible highlighter; the documentation site
+  uses it to highlight ```` ```sdoc ```` fences.
+
 ## [0.0.40] - 2026-07-04
 
 ### Fixed

package/dist/explorer/tree-builder.js

@@ -44,9 +44,7 @@ export function buildTree(docs, sidebar) {
         // Create the item node
         const itemPath = [...currentPath, itemName];
         if (kind === 'component') {
-            const examples = doc.snippets
-                ?.filter((s) => s.name !== 'Default')
-                .map((s) => s.name) ?? [];
+            const examples = doc.examples?.map((s) => s.name) ?? [];
             // Check if a folder node with this name already exists (created by a child doc)
             const existing = parent.find((n) => n.name === itemName);
             const componentNode = existing ?? {
@@ -195,7 +193,7 @@ export function findDocByPath(docs, path) {
         // One extra segment → example
         if (segments.length === path.length - 1 && segments.every((s, i) => s === path[i])) {
             const snippetName = path[path.length - 1];
-            const hasSnippet = doc.snippets?.some((s) => s.name === snippetName);
+            const hasSnippet = doc.examples?.some((s) => s.name === snippetName);
             if (hasSnippet) {
                 return { doc, snippetName };
             }

package/dist/explorer/views/ComponentView.svelte

@@ -18,28 +18,40 @@
 	let { doc, snippetName, activeStylesheet }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const cd = $derived(doc.componentData);
+	const previews = $derived(doc.previews ?? []);
+
+	// Active preview tab (one full live panel per preview)
+	let activeIndex = $state(0);
+	$effect(() => {
+		doc;
+		activeIndex = 0;
+	});
+	const activePreview = $derived(
+		previews.length > 0 ? previews[Math.min(activeIndex, previews.length - 1)] : undefined,
+	);
+
+	const cd = $derived(activePreview?.componentData ?? null);
 	const componentName = $derived(
-		typeof meta.component === 'string'
-			? meta.component
-			: (meta.title ?? '').split('/').pop()?.trim() ?? 'Component',
+		activePreview?.componentName ??
+			((meta.title ?? '').split('/').pop()?.trim() || 'Component'),
+	);
+	const exampleSnippets = $derived(doc.examples ?? []);
+	const focusedSnippet = $derived(
+		snippetName ? exampleSnippets.find((s) => s.name === snippetName) : null,
 	);
-	const snippets = $derived(doc.snippets ?? []);
-	const defaultSnippet = $derived(snippets.find((s) => s.name === 'Default'));
-	const exampleSnippets = $derived(snippets.filter((s) => s.name !== 'Default'));
-	const focusedSnippet = $derived(snippetName ? snippets.find((s) => s.name === snippetName) : null);
 
 	// Props/CSS controls state
 	let propValues = $state<Record<string, unknown>>({});
 	let cssValues = $state<Record<string, string>>({});
 
-	// Live wiring to the default preview: method invocation + exported state values
+	// Live wiring to the active 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)
+	// Initialize from the active preview's args (build new objects to avoid
+	// read+write loop); re-runs on doc and tab change.
 	$effect(() => {
-		propValues = { ...(meta.args ?? {}) };
+		propValues = { ...(activePreview?.args ?? {}) };
 		const newCss: Record<string, string> = {};
 		if (cd?.cssProps) {
 			for (const cp of cd.cssProps) {
@@ -47,6 +59,7 @@
 			}
 		}
 		cssValues = newCss;
+		liveStateValues = {};
 	});
 
 	function handlePropChange(name: string, value: unknown) {
@@ -159,8 +172,8 @@
 		return snippetBody.slice(0, attrsStart) + attrs + closing + snippetBody.slice(tagEnd + 1);
 	}
 
-	// Initial values for diffing (computed once per doc change)
-	const initialProps = $derived(meta.args ?? {});
+	// Initial values for diffing (computed once per doc/tab change)
+	const initialProps = $derived(activePreview?.args ?? {});
 	const initialCss = $derived.by(() => {
 		const css: Record<string, string> = {};
 		if (cd?.cssProps) {
@@ -172,8 +185,8 @@
 	});
 
 	const usageCode = $derived.by(() => {
-		if (defaultSnippet?.body) {
-			return patchSnippetCode(defaultSnippet.body, componentName, propValues, cssValues, initialProps, initialCss);
+		if (activePreview?.snippet.body) {
+			return patchSnippetCode(activePreview.snippet.body, componentName, propValues, cssValues, initialProps, initialCss);
 		}
 		return generateFallbackCode(componentName, propValues, cssValues);
 	});
@@ -198,7 +211,7 @@
 	});
 
 	function handleReset() {
-		propValues = { ...(meta.args ?? {}) };
+		propValues = { ...(activePreview?.args ?? {}) };
 		const newCss: Record<string, string> = {};
 		if (cd?.cssProps) {
 			for (const cp of cd.cssProps) {
@@ -290,19 +303,37 @@
 			{/if}
 		</div>
 
+		{#if previews.length > 1}
+			<div class="sdocs-preview-tabs" role="tablist">
+				{#each previews as preview, i (preview.snippet.slug)}
+					<button
+						class="sdocs-preview-tab"
+						class:active={i === activeIndex}
+						role="tab"
+						aria-selected={i === activeIndex}
+						onclick={() => (activeIndex = i)}
+					>
+						{preview.label}
+					</button>
+				{/each}
+			</div>
+		{/if}
+
 		<div class="sdocs-panels">
 			<!-- Showcase -->
-			{#if defaultSnippet}
-				<div class="sdocs-preview-wrapper">
-					<PreviewFrame
-						bind:this={defaultPreview}
-						src={defaultSnippet.previewUrl ?? ''}
-						props={propValues}
-						cssVars={cssValues}
-						{activeStylesheet}
-						onStateValues={(values) => (liveStateValues = values)}
-					/>
-				</div>
+			{#if activePreview}
+				{#key activePreview.snippet.slug}
+					<div class="sdocs-preview-wrapper">
+						<PreviewFrame
+							bind:this={defaultPreview}
+							src={activePreview.snippet.previewUrl ?? ''}
+							props={propValues}
+							cssVars={cssValues}
+							{activeStylesheet}
+							onStateValues={(values) => (liveStateValues = values)}
+						/>
+					</div>
+				{/key}
 
 				<CollapsiblePanel title="Preview Code" defaultExpanded={false}>
 					<div class="sdocs-code-block">
@@ -414,11 +445,11 @@
 			{/each}
 		{/if}
 
-		{#if doc.highlightedSource}
+		{#if activePreview?.highlightedSource}
 			<hr class="sdocs-divider" />
 			<div class="sdocs-panels">
 				<CollapsiblePanel title="Component Source" defaultExpanded={false}>
-					<div class="sdocs-code-block">{@html doc.highlightedSource}</div>
+					<div class="sdocs-code-block">{@html activePreview.highlightedSource}</div>
 				</CollapsiblePanel>
 			</div>
 		{/if}
@@ -476,6 +507,31 @@
 		opacity: 0.4;
 		cursor: default;
 	}
+	.sdocs-preview-tabs {
+		display: flex;
+		gap: 4px;
+		margin-bottom: 12px;
+		border-bottom: 1px solid var(--color-base-200);
+	}
+	.sdocs-preview-tab {
+		padding: 7px 14px;
+		border: none;
+		border-bottom: 2px solid transparent;
+		background: none;
+		font: inherit;
+		font-size: 13px;
+		font-weight: 500;
+		color: var(--color-base-500);
+		cursor: pointer;
+	}
+	.sdocs-preview-tab:hover {
+		color: var(--color-base-800);
+	}
+	.sdocs-preview-tab.active {
+		color: var(--color-base-900);
+		border-bottom-color: var(--color-accent-500, var(--color-base-900));
+		font-weight: 600;
+	}
 	.sdocs-view-header {
 		margin-bottom: 24px;
 	}

package/dist/explorer/views/LayoutView.svelte

@@ -9,7 +9,7 @@
 
 	let { doc, activeStylesheet }: Props = $props();
 
-	const contentSnippet = $derived(doc.snippets?.[0]);
+	const contentSnippet = $derived(doc.content);
 </script>
 
 <div class="sdocs-layout-view">

package/dist/explorer/views/PageView.svelte

@@ -10,7 +10,7 @@
 	let { doc, activeStylesheet }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const contentSnippet = $derived(doc.snippets?.[0]);
+	const contentSnippet = $derived(doc.content);
 	const toc = $derived(doc.toc ?? []);
 
 	function scrollToHeading(id: string) {

package/dist/grammar/sdoc.tmLanguage.json

@@ -0,0 +1,245 @@
+{
+	"$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+	"name": "sdoc",
+	"scopeName": "source.sdoc",
+	"fileTypes": ["sdoc"],
+	"patterns": [
+		{ "include": "#comment" },
+		{ "include": "#script-ts" },
+		{ "include": "#script-js" },
+		{ "include": "#style" },
+		{ "include": "#docs" },
+		{ "include": "#page" },
+		{ "include": "#layout" }
+	],
+	"repository": {
+		"comment": {
+			"name": "comment.block.html.sdoc",
+			"begin": "<!--",
+			"end": "-->"
+		},
+		"script-ts": {
+			"begin": "^\\s*(<)(script)(?=[^>]*lang=([\"'])ts\\3)",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.script.sdoc" }
+			},
+			"end": "(</)(script)\\s*(>)",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.script.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#tag-rest" },
+				{
+					"begin": "(?<=>)",
+					"end": "(?=</script)",
+					"contentName": "source.ts",
+					"patterns": [{ "include": "source.ts" }]
+				}
+			]
+		},
+		"script-js": {
+			"begin": "^\\s*(<)(script)(?![^>]*lang=([\"'])ts\\3)(?=[\\s>])",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.script.sdoc" }
+			},
+			"end": "(</)(script)\\s*(>)",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.script.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#tag-rest" },
+				{
+					"begin": "(?<=>)",
+					"end": "(?=</script)",
+					"contentName": "source.js",
+					"patterns": [{ "include": "source.js" }]
+				}
+			]
+		},
+		"style": {
+			"begin": "^\\s*(<)(style)(?=[\\s>])",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.style.sdoc" }
+			},
+			"end": "(</)(style)\\s*(>)",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.style.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#tag-rest" },
+				{
+					"begin": "(?<=>)",
+					"end": "(?=</style)",
+					"contentName": "source.css",
+					"patterns": [{ "include": "source.css" }]
+				}
+			]
+		},
+		"tag-rest": {
+			"begin": "\\G",
+			"end": "(>)",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [{ "include": "#attributes" }]
+		},
+		"docs": {
+			"name": "meta.block.docs.sdoc",
+			"begin": "^\\s*(\\[)(DOCS)\\b",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" }
+			},
+			"end": "^\\s*(\\[/)(DOCS)(\\])\\s*$",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#opener-attrs" },
+				{ "include": "#comment" },
+				{ "include": "#preview" },
+				{ "include": "#example" }
+			]
+		},
+		"page": {
+			"name": "meta.block.page.sdoc",
+			"begin": "^\\s*(\\[)(PAGE)\\b",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" }
+			},
+			"end": "^\\s*(\\[/)(PAGE)(\\])\\s*$",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#opener-attrs" },
+				{ "include": "source.svelte" }
+			]
+		},
+		"layout": {
+			"name": "meta.block.layout.sdoc",
+			"begin": "^\\s*(\\[)(LAYOUT)\\b",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" }
+			},
+			"end": "^\\s*(\\[/)(LAYOUT)(\\])\\s*$",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "keyword.control.entity.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#opener-attrs" },
+				{ "include": "source.svelte" }
+			]
+		},
+		"preview": {
+			"name": "meta.block.preview.sdoc",
+			"begin": "^\\s*(\\[)(preview)\\b",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.sdoc" }
+			},
+			"end": "^\\s*(\\[/)(preview)(\\])\\s*$",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#opener-attrs" },
+				{ "include": "source.svelte" }
+			]
+		},
+		"example": {
+			"name": "meta.block.example.sdoc",
+			"begin": "^\\s*(\\[)(example)\\b",
+			"beginCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.sdoc" }
+			},
+			"end": "^\\s*(\\[/)(example)(\\])\\s*$",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
+				"2": { "name": "entity.name.tag.sdoc" },
+				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [
+				{ "include": "#opener-attrs" },
+				{ "include": "source.svelte" }
+			]
+		},
+		"opener-attrs": {
+			"begin": "\\G",
+			"end": "(\\])",
+			"endCaptures": {
+				"1": { "name": "punctuation.definition.tag.end.sdoc" }
+			},
+			"patterns": [{ "include": "#attributes" }]
+		},
+		"attributes": {
+			"patterns": [
+				{
+					"match": "([A-Za-z_][\\w-]*)\\s*(=)",
+					"captures": {
+						"1": { "name": "entity.other.attribute-name.sdoc" },
+						"2": { "name": "punctuation.separator.key-value.sdoc" }
+					}
+				},
+				{
+					"match": "([A-Za-z_][\\w-]*)",
+					"name": "entity.other.attribute-name.sdoc"
+				},
+				{
+					"name": "string.quoted.double.sdoc",
+					"begin": "\"",
+					"end": "\"",
+					"beginCaptures": {
+						"0": { "name": "punctuation.definition.string.begin.sdoc" }
+					},
+					"endCaptures": {
+						"0": { "name": "punctuation.definition.string.end.sdoc" }
+					}
+				},
+				{ "include": "#expression" }
+			]
+		},
+		"expression": {
+			"name": "meta.embedded.expression.sdoc",
+			"begin": "\\{",
+			"end": "\\}",
+			"beginCaptures": {
+				"0": { "name": "punctuation.section.embedded.begin.sdoc" }
+			},
+			"endCaptures": {
+				"0": { "name": "punctuation.section.embedded.end.sdoc" }
+			},
+			"patterns": [{ "include": "#expression-inner" }]
+		},
+		"expression-inner": {
+			"patterns": [
+				{
+					"begin": "\\{",
+					"end": "\\}",
+					"patterns": [{ "include": "#expression-inner" }]
+				},
+				{ "include": "source.ts" }
+			]
+		}
+	}
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { sdocsPlugin } from './vite.js';
-export type { SdocsConfig, ResolvedSdocsConfig, SdocMeta, DocEntry, ParsedProp, ParsedMethod, ParsedState, ParsedCssProp, ComponentData, ExtractedSnippet, } from './types.js';
+export type { SdocsConfig, ResolvedSdocsConfig, SdocMeta, DocEntry, ParsedProp, ParsedMethod, ParsedState, ParsedCssProp, ComponentData, ExtractedSnippet, PreviewEntry, TocHeading, } from './types.js';

package/dist/language/index.d.ts

@@ -0,0 +1,2 @@
+export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, type Span, type EntityKind, type SubBlockKind, type AttrValue, type Attrs, type SubBlock, type Entity, type TagBlock, type ScanError, type SdocFile, } from './scanner.js';
+export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';

package/dist/language/index.js

@@ -0,0 +1,2 @@
+export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
+export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';

package/dist/language/parser.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Semantic layer over the syntactic scanner: validates attributes against
+ * the sdoc language rules and produces typed entities ready for the Vite
+ * plugin, the CLI app-gen, and the editor tooling.
+ */
+import { type ScanError, type Span, type TagBlock } from './scanner.js';
+export type ArgValue = string | number | boolean;
+export interface PreviewBlock {
+    /** The identifier from component={X}; null when invalid/missing (already reported) */
+    componentName: string | null;
+    /** Parsed args literal; null when absent or invalid */
+    args: Record<string, ArgValue> | null;
+    /** Exact source of the args expression (inner object), for code display */
+    argsRaw: string | null;
+    /** Explicit title="…" override, when present */
+    title: string | null;
+    /** Tab label: the title override or the component name */
+    label: string;
+    body: string;
+    bodySpan: Span;
+    span: Span;
+}
+export interface ExampleBlock {
+    title: string;
+    body: string;
+    bodySpan: Span;
+    span: Span;
+}
+export interface DocsEntity {
+    kind: 'DOCS';
+    title: string;
+    slug: string;
+    description: string | null;
+    previews: PreviewBlock[];
+    examples: ExampleBlock[];
+    openerSpan: Span;
+    span: Span;
+}
+export interface PageEntity {
+    kind: 'PAGE';
+    title: string;
+    slug: string;
+    body: string;
+    bodySpan: Span;
+    openerSpan: Span;
+    span: Span;
+}
+export interface LayoutEntity {
+    kind: 'LAYOUT';
+    title: string;
+    slug: string;
+    padding: string | null;
+    body: string;
+    bodySpan: Span;
+    openerSpan: Span;
+    span: Span;
+}
+export type SdocEntity = DocsEntity | PageEntity | LayoutEntity;
+export interface SdocDocument {
+    script: TagBlock | null;
+    style: TagBlock | null;
+    entities: SdocEntity[];
+    diagnostics: ScanError[];
+    source: string;
+}
+/**
+ * Normalize a raw block body for consumption: strip the common leading
+ * indentation (bodies sit one level deep inside their block), drop a
+ * trailing carriage return per line, and unescape lines that start with
+ * `\[` (the escape for body lines that would otherwise read as tags).
+ * The scanner keeps the raw text and spans; this is the display/runtime form.
+ */
+export declare function normalizeBody(raw: string): string;
+/** Slug used for entity addressing: relPath + '#' + slug. */
+export declare function slugifyTitle(title: string): string;
+/**
+ * Parse a preview args expression: a flat object literal whose values are
+ * plain literals (strings, numbers, booleans). Anything richer belongs in
+ * the block body, so it is rejected here.
+ */
+export declare function parseArgsLiteral(raw: string, span: Span, diagnostics: ScanError[]): Record<string, ArgValue> | null;
+export declare function parseSdoc(source: string): SdocDocument;