@honeydeck/honeydeck 0.1.0

package/src/vite-plugin/SPEC.md

@@ -0,0 +1,114 @@
+# Honeydeck Deck Loading Specification
+
+> Observable behavior for deck entry files, slide splitting, imports, assets, Markdown features, and frontmatter.
+
+## Slide Authoring
+
+### Entry Point
+
+The CLI deck entry point defaults to `deck.mdx` in the current working directory. Users may pass `--deck <file.mdx>` to `honeydeck dev`, `honeydeck build`, or `honeydeck pdf` to use any `.mdx` file as the deck entry point.
+
+Honeydeck starts relative to the selected deck file: the file's directory becomes the project root for local CSS, component, layout, and asset resolution, and that file is treated as the root document that defines deck-level settings and the top-level slide order.
+
+### Slide Separation
+
+Slides are separated by a line that is exactly `---`. CRLF line endings are treated the same as LF when detecting separators and frontmatter markers. A `---` line inside a fenced code block is literal code text and must not create a slide boundary. Empty blocks between separators are ignored:
+
+```mdx
+---
+title: My Deck
+---
+
+# First Slide
+
+Content here.
+
+---
+
+# Second Slide
+
+More content.
+```
+
+### Multiple MDX Files
+
+Additional MDX files can be imported explicitly as slide groups:
+
+```mdx
+import DemoSlides from './slides/demo.mdx'
+
+# Intro
+
+---
+
+<DemoSlides />
+
+---
+
+# Conclusion
+```
+
+Rules:
+
+- Default imports from relative `.mdx` files are slide-structural imports
+- Rendering an imported MDX component as a standalone usage (`<DemoSlides />`) expands that file's slides at that exact location in the parent deck
+- Imported `.mdx` files may contain multiple slides separated by `---`; those separators become Honeydeck slide boundaries in the parent timeline
+- Frontmatter in imported `.mdx` files is slide-level only and cannot define deck-level settings
+- Components imported from `.tsx`/`.ts`/`.jsx`/`.js` or packages are normal inline components
+- Single-line imports at the top of the first content block are extracted as shared imports and prepended to generated slide modules
+
+### Assets
+
+Static files live in the project `public/` directory and are served from the web root:
+
+```mdx
+<img src="/cover.jpg" />
+```
+
+React components and built-in layouts may also import image assets through Vite (`webp`, `png`, `jpg`, `jpeg`, `svg`, `gif`). The built-in `Image` layout uses this for its bundled placeholder image.
+
+### Markdown Features
+
+Slide MDX supports GitHub-flavored Markdown pipe tables. Pipe tables render as real HTML tables in slides. The base theme styles slide tables with compact, full-width, token-based horizontal rules, bold headers, and light horizontal cell spacing so table Markdown is presentation-ready without custom CSS.
+
+Slide Markdown lists render with visible markers in the base theme: unordered lists show bullet markers and ordered lists show decimal markers, even when Tailwind preflight resets browser list styles.
+
+Honeydeck does not include Mermaid as a built-in Markdown feature. Fenced `mermaid` blocks are treated like normal code blocks unless the deck imports and renders its own user-space component.
+
+---
+
+---
+
+## Frontmatter
+
+All settings use **camelCase**. No separate config file exists. Frontmatter parsing is a limited flat YAML subset: `key: value` pairs with strings, booleans, numbers, and quoted strings. Nested objects, arrays, and multiline YAML are not supported.
+
+### Deck-Level (deck entry file, first block only)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | `""` | Deck title stored in deck config |
+| `description` | `string` | `""` | Deck description stored in deck config |
+| `aspectRatio` | `"n:n"` | `"16:9"` | Slide canvas aspect ratio |
+| `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
+| `pdfColorMode` | `"light" \| "dark"` | unset | Optional explicit PDF color mode; when unset, PDF falls back to pinned deck `colorMode`, then `light` |
+| `pdfSteps` | `"final" \| "all"` | `"final"` | Whether PDF includes all steps or final state |
+| `transition` | `boolean` | `true` | Enable crossfade transition between slides |
+| `layouts` | `string` | built-in `@honeydeck/honeydeck/layouts` | Layout map module path |
+| `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
+| `showSlideNumbers` | `boolean` | `false` | Show the current slide number in the bottom-right corner of slides |
+
+### Slide-Level (per-slide, after `---`)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `layout` | `string` | (uses `defaultLayout`) | Layout map key to use (PascalCase by convention, not validated) |
+| ...layout-specific props | varies | — | Any additional props the layout accepts |
+
+### Root frontmatter semantics
+
+The first frontmatter block in the deck entry file is parsed as deck config. Deck-level keys are not copied into slide frontmatter. If that block also contains `layout:` plus layout-specific keys, those non-deck keys are emitted as first-slide frontmatter.
+
+Slide-level frontmatter is a frontmatter-only block after a slide separator and applies to the following slide. Imported MDX files are normal MDX modules and cannot set deck-level properties.
+
+Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; `transition` is enabled unless literal `false`.

package/src/vite-plugin/component-doc-crawler.ts

@@ -0,0 +1,350 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+import ts from "typescript";
+import type { ComponentPropDoc } from "../runtime/types.ts";
+
+const SOURCE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+const COMPONENT_DOC_EXPORT_EXCLUSIONS = new Set([
+	"Button",
+	"COLOR_MODES",
+	"ColorModeCycleButton",
+]);
+
+export type DiscoveredComponentDoc = {
+	componentName: string;
+	modulePath: string;
+	publicModuleSpecifier: string;
+	markdown: string;
+	props: ComponentPropDoc[];
+};
+
+export type ComponentDocCrawlResult = {
+	barrelPath: string;
+	docs: DiscoveredComponentDoc[];
+	watchedFiles: string[];
+	warnings: string[];
+};
+
+export type CrawlComponentDocsOptions = {
+	packageRoot: string;
+};
+
+export function crawlComponentDocs({
+	packageRoot,
+}: CrawlComponentDocsOptions): ComponentDocCrawlResult {
+	const barrelPath = resolve(packageRoot, "src/runtime/components/index.ts");
+	const watchedFiles = new Set<string>([barrelPath]);
+	const warnings: string[] = [];
+
+	let sourceFile: ts.SourceFile;
+	try {
+		sourceFile = parseFile(barrelPath);
+	} catch (error) {
+		warnings.push(
+			`Could not read component barrel "${barrelPath}": ${String(error)}`,
+		);
+		return { barrelPath, docs: [], watchedFiles: [...watchedFiles], warnings };
+	}
+
+	const docs: DiscoveredComponentDoc[] = [];
+
+	for (const statement of sourceFile.statements) {
+		if (!ts.isExportDeclaration(statement)) continue;
+		if (statement.isTypeOnly) continue;
+		if (!statement.exportClause || !ts.isNamedExports(statement.exportClause))
+			continue;
+		if (
+			!statement.moduleSpecifier ||
+			!ts.isStringLiteral(statement.moduleSpecifier)
+		)
+			continue;
+
+		const moduleSpecifier = statement.moduleSpecifier.text;
+		const modulePath = resolveSourceFile(
+			resolve(dirname(barrelPath), moduleSpecifier),
+		);
+		if (!modulePath) {
+			warnings.push(
+				`Could not resolve component module "${moduleSpecifier}" from "${barrelPath}".`,
+			);
+			continue;
+		}
+
+		watchedFiles.add(modulePath);
+
+		for (const element of statement.exportClause.elements) {
+			if (element.isTypeOnly) continue;
+			const exportedName = element.name.text;
+			if (!isPublicComponentName(exportedName)) continue;
+
+			try {
+				const doc = extractComponentDoc({
+					modulePath,
+					componentName: exportedName,
+					localName: element.propertyName?.text ?? exportedName,
+				});
+				docs.push({
+					componentName: exportedName,
+					modulePath,
+					publicModuleSpecifier: "@honeydeck/honeydeck/components",
+					...doc,
+				});
+			} catch (error) {
+				warnings.push(
+					`Could not inspect docs for component "${exportedName}": ${String(error)}`,
+				);
+			}
+		}
+	}
+
+	return {
+		barrelPath,
+		docs,
+		watchedFiles: [...watchedFiles],
+		warnings,
+	};
+}
+
+function isPublicComponentName(name: string): boolean {
+	if (COMPONENT_DOC_EXPORT_EXCLUSIONS.has(name)) return false;
+	return /^[A-Z]/.test(name);
+}
+
+function parseFile(path: string): ts.SourceFile {
+	const source = readFileSync(path, "utf-8");
+	const kind =
+		path.endsWith(".tsx") || path.endsWith(".jsx")
+			? ts.ScriptKind.TSX
+			: ts.ScriptKind.TS;
+	return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);
+}
+
+function resolveSourceFile(basePath: string): string | null {
+	if (existsSync(basePath) && extname(basePath)) return basePath;
+
+	for (const extension of SOURCE_EXTENSIONS) {
+		const candidate = `${basePath}${extension}`;
+		if (existsSync(candidate)) return candidate;
+	}
+
+	if (existsSync(basePath) && !extname(basePath)) {
+		for (const extension of SOURCE_EXTENSIONS) {
+			const candidate = resolve(basePath, `index${extension}`);
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+
+	return existsSync(basePath) ? basePath : null;
+}
+
+function extractComponentDoc({
+	modulePath,
+	componentName,
+	localName,
+}: {
+	modulePath: string;
+	componentName: string;
+	localName: string;
+}): { markdown: string; props: ComponentPropDoc[] } {
+	const sourceFile = parseFile(modulePath);
+	const component = findComponentDeclaration(sourceFile, localName);
+	if (!component)
+		throw new Error(`exported component "${localName}" not found`);
+
+	const markdown =
+		getJSDocMarkdown(component) ||
+		`Public docs for \`${componentName}\` have not been written yet.`;
+	const propTypeName =
+		getComponentPropTypeName(component) ?? `${componentName}Props`;
+	const defaults = collectParameterDefaults(component);
+	const props = propTypeName
+		? extractProps(sourceFile, propTypeName, defaults)
+		: [];
+
+	return { markdown, props };
+}
+
+type ComponentDeclaration =
+	| ts.FunctionDeclaration
+	| ts.VariableDeclaration
+	| ts.ArrowFunction
+	| ts.FunctionExpression;
+
+function findComponentDeclaration(
+	sourceFile: ts.SourceFile,
+	name: string,
+): ComponentDeclaration | null {
+	for (const statement of sourceFile.statements) {
+		if (
+			ts.isFunctionDeclaration(statement) &&
+			statement.name?.text === name &&
+			hasExportModifier(statement)
+		) {
+			return statement;
+		}
+
+		if (!ts.isVariableStatement(statement) || !hasExportModifier(statement))
+			continue;
+
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+				continue;
+			const initializer = declaration.initializer;
+			if (
+				initializer &&
+				(ts.isArrowFunction(initializer) ||
+					ts.isFunctionExpression(initializer))
+			) {
+				return initializer;
+			}
+			return declaration;
+		}
+	}
+
+	return null;
+}
+
+function hasExportModifier(node: ts.HasModifiers): boolean {
+	return !!ts
+		.getModifiers(node)
+		?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+
+function getJSDocMarkdown(node: ts.Node): string {
+	const docs = ts
+		.getJSDocCommentsAndTags(node)
+		.filter((doc): doc is ts.JSDoc => ts.isJSDoc(doc));
+	const latest = docs.at(-1);
+	const comment = latest?.comment;
+	if (typeof comment === "string") return comment.trim();
+	return "";
+}
+
+function getComponentPropTypeName(
+	component: ComponentDeclaration,
+): string | null {
+	const parameters =
+		ts.isFunctionDeclaration(component) ||
+		ts.isArrowFunction(component) ||
+		ts.isFunctionExpression(component)
+			? component.parameters
+			: [];
+	const firstParam = parameters[0];
+	const type = firstParam?.type;
+	if (type && ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName)) {
+		return type.typeName.text;
+	}
+	return null;
+}
+
+function collectParameterDefaults(
+	component: ComponentDeclaration,
+): Map<string, string> {
+	const defaults = new Map<string, string>();
+	const parameters =
+		ts.isFunctionDeclaration(component) ||
+		ts.isArrowFunction(component) ||
+		ts.isFunctionExpression(component)
+			? component.parameters
+			: [];
+	const firstParam = parameters[0];
+	if (!firstParam || !ts.isObjectBindingPattern(firstParam.name))
+		return defaults;
+
+	for (const element of firstParam.name.elements) {
+		if (!element.initializer) continue;
+		const name = bindingElementName(element);
+		if (!name) continue;
+		defaults.set(name, element.initializer.getText());
+	}
+
+	return defaults;
+}
+
+function bindingElementName(element: ts.BindingElement): string | null {
+	if (element.propertyName) return propertyNameText(element.propertyName);
+	return ts.isIdentifier(element.name) ? element.name.text : null;
+}
+
+function extractProps(
+	sourceFile: ts.SourceFile,
+	typeName: string,
+	defaults: Map<string, string>,
+): ComponentPropDoc[] {
+	const declaration = findTypeDeclaration(sourceFile, typeName);
+	if (!declaration) return [];
+
+	const members = ts.isInterfaceDeclaration(declaration)
+		? [...declaration.members]
+		: typeAliasMembers(sourceFile, declaration);
+
+	return members.flatMap((member) => {
+		if (!ts.isPropertySignature(member)) return [];
+		const name = propertyNameText(member.name);
+		if (!name) return [];
+
+		const doc: ComponentPropDoc = {
+			name,
+			type: member.type?.getText(sourceFile) ?? "unknown",
+			required: !member.questionToken,
+			description: getJSDocMarkdown(member),
+		};
+		const defaultValue = defaults.get(name);
+		if (defaultValue !== undefined) doc.defaultValue = defaultValue;
+		return [doc];
+	});
+}
+
+function typeAliasMembers(
+	sourceFile: ts.SourceFile,
+	declaration: ts.TypeAliasDeclaration,
+): ts.TypeElement[] {
+	if (ts.isTypeLiteralNode(declaration.type))
+		return [...declaration.type.members];
+	if (!ts.isIntersectionTypeNode(declaration.type)) return [];
+
+	return declaration.type.types.flatMap((type) => {
+		if (ts.isTypeLiteralNode(type)) return [...type.members];
+		if (!ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName))
+			return [];
+
+		const referencedDeclaration = findTypeDeclaration(
+			sourceFile,
+			type.typeName.text,
+		);
+		if (!referencedDeclaration) return [];
+		if (ts.isInterfaceDeclaration(referencedDeclaration)) {
+			return [...referencedDeclaration.members];
+		}
+		return typeAliasMembers(sourceFile, referencedDeclaration);
+	});
+}
+
+function findTypeDeclaration(
+	sourceFile: ts.SourceFile,
+	typeName: string,
+): ts.InterfaceDeclaration | ts.TypeAliasDeclaration | null {
+	for (const statement of sourceFile.statements) {
+		if (
+			ts.isInterfaceDeclaration(statement) &&
+			statement.name.text === typeName
+		)
+			return statement;
+		if (
+			ts.isTypeAliasDeclaration(statement) &&
+			statement.name.text === typeName
+		)
+			return statement;
+	}
+	return null;
+}
+
+function propertyNameText(name: ts.PropertyName): string | null {
+	if (
+		ts.isIdentifier(name) ||
+		ts.isStringLiteral(name) ||
+		ts.isNumericLiteral(name)
+	)
+		return name.text;
+	return null;
+}

package/src/vite-plugin/deck-loader.ts

@@ -0,0 +1,148 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { type SplitResult, splitSlides } from "./splitter.ts";
+
+export type LoadedDeck = SplitResult & {
+	watchedFiles: string[];
+};
+
+type ExpandContext = {
+	watchedFiles: Set<string>;
+	stack: string[];
+};
+
+type MdxImport = {
+	localName: string;
+	source: string;
+};
+
+const DEFAULT_MDX_IMPORT_RE =
+	/^import\s+([A-Za-z_$][\w$]*)\s+from\s+(['"])([^'"]+\.mdx)\2\s*;?\s*$/;
+
+const RELATIVE_IMPORT_RE =
+	/^(?<prefix>\s*import\s+(?:(?:[^'"]+?)\s+from\s+)?)(?<quote>['"])(?<specifier>\.{1,2}\/[^'"]+)(?<suffix>\k<quote>\s*;?\s*)$/;
+
+export function loadDeck(entryPath: string): LoadedDeck {
+	const watchedFiles = new Set<string>();
+	const source = expandMdxFile(resolve(entryPath), {
+		watchedFiles,
+		stack: [],
+	});
+	const result = splitSlides(source, { trimLeadingEmptyBlocks: false });
+
+	return {
+		...result,
+		watchedFiles: Array.from(watchedFiles),
+	};
+}
+
+function expandMdxFile(filePath: string, context: ExpandContext): string {
+	const absolutePath = resolve(filePath);
+
+	if (context.stack.includes(absolutePath)) {
+		throw new Error(
+			`Honeydeck: circular MDX import detected: ${[...context.stack, absolutePath].join(" -> ")}`,
+		);
+	}
+
+	context.watchedFiles.add(absolutePath);
+
+	const rawSource = readFileSync(absolutePath, "utf-8");
+	const baseDir = dirname(absolutePath);
+	const imports = new Map<string, MdxImport>();
+	const nextContext = {
+		...context,
+		stack: [...context.stack, absolutePath],
+	};
+
+	const withoutMdxImports = mapMdxLines(rawSource, (line) => {
+		const match = line.match(DEFAULT_MDX_IMPORT_RE);
+		if (!match) return line;
+
+		const [, localName, , importPath] = match;
+		if (!localName || !importPath) return line;
+
+		const importedPath = resolve(baseDir, importPath);
+		const importedSource = expandMdxFile(importedPath, nextContext);
+		const importedSlides = splitSlides(importedSource, {
+			frontmatterMode: "slide",
+		}).slides;
+
+		imports.set(localName, {
+			localName,
+			source: importedSlides.map((slide) => slide.rawMdx).join("\n\n---\n\n"),
+		});
+
+		return "";
+	});
+
+	const withFileAnchoredImports =
+		context.stack.length > 0
+			? rewriteRelativeImports(withoutMdxImports, baseDir)
+			: withoutMdxImports;
+
+	return expandMdxUsages(withFileAnchoredImports, imports);
+}
+
+function expandMdxUsages(
+	source: string,
+	imports: Map<string, MdxImport>,
+): string {
+	return mapMdxLines(source, (line) => {
+		for (const imported of imports.values()) {
+			if (isStandaloneMdxUsage(line, imported.localName)) {
+				return ["---", imported.source.trim(), "---"].join("\n");
+			}
+		}
+
+		return line;
+	});
+}
+
+function isStandaloneMdxUsage(line: string, localName: string): boolean {
+	const escapedName = escapeRegExp(localName);
+	return (
+		new RegExp(`^\\s*<${escapedName}\\s*/>\\s*$`).test(line) ||
+		new RegExp(`^\\s*<${escapedName}\\s*>\\s*</${escapedName}>\\s*$`).test(line)
+	);
+}
+
+function rewriteRelativeImports(source: string, baseDir: string): string {
+	return mapMdxLines(source, (line) => {
+		const match = line.match(RELATIVE_IMPORT_RE);
+		const groups = match?.groups;
+		if (!groups) return line;
+
+		const specifier = groups.specifier;
+		if (!specifier || specifier.endsWith(".mdx")) return line;
+
+		return `${groups.prefix}${groups.quote}${toFsImportSpecifier(resolve(baseDir, specifier))}${groups.suffix}`;
+	});
+}
+
+function mapMdxLines(
+	source: string,
+	mapLine: (line: string) => string,
+): string {
+	let inFence = false;
+
+	return source
+		.split("\n")
+		.map((line) => {
+			if (/^\s*```/.test(line)) {
+				inFence = !inFence;
+				return line;
+			}
+
+			return inFence ? line : mapLine(line);
+		})
+		.join("\n");
+}
+
+function toFsImportSpecifier(path: string): string {
+	return `/@fs/${path.replace(/\\/g, "/")}`;
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}