design-embed 0.1.0 → 0.2.0

package/{node_modules/@design-embed/core/src → src/core}/index.ts

@@ -1,10 +1,21 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { htmlTarget } from "../targets/html.ts";
+import type { Diagnostic } from "./diagnostics/diagnostic.ts";
+import type {
+	DesignNode,
+	ParsedSelector,
+	PropValue,
+	SourceLocation,
+} from "./nodes.ts";
+import type { GeneratedFile } from "./plugins/pluginApi.ts";
 import type {
 	ComponentMapping,
 	DesignEmbedConfig,
-} from "../../config/src/index.ts";
-import type { Diagnostic } from "./diagnostics/diagnostic.ts";
-import type { TargetEmitter, TransformerPlugin } from "./plugins/pluginApi.ts";
-import { sortTransformers } from "./plugins/pluginRegistry.ts";
+	TargetEmitter,
+	TargetTestGenerator,
+} from "./types.ts";
 
 export type {
 	Diagnostic,
@@ -16,6 +27,12 @@ export {
 	toJsonDiagnostic,
 	toJsonDiagnostics,
 } from "./diagnostics/jsonDiagnostic.ts";
+export type {
+	DesignNode,
+	ParsedSelector,
+	PropValue,
+	SourceLocation,
+} from "./nodes.ts";
 export type {
 	CheckModeInput,
 	CheckModeResult,
@@ -23,122 +40,52 @@ export type {
 export { checkGeneratedFiles } from "./pipeline/checkMode.ts";
 export type {
 	GeneratedAsset,
+	GeneratedFile,
 	SourcePlugin,
 	SourcePluginInput,
 	SourcePluginResult,
-	TargetEmitInput,
 	TargetEmitResult,
+	TargetTestGenerateResult,
+} from "./plugins/pluginApi.ts";
+export type {
+	ComponentMapping,
+	DesignEmbedConfig,
+	NumericTokenGroup,
+	StyleMappings,
+	StyleMode,
+	TargetEmitInput,
 	TargetEmitter,
 	TargetTestGenerateInput,
-	TargetTestGenerateResult,
 	TargetTestGenerator,
-	TransformContext,
-	TransformerPlugin,
-	TransformResult,
-} from "./plugins/pluginApi.ts";
-export {
-	PluginRegistry,
-	sortTransformers,
-} from "./plugins/pluginRegistry.ts";
-
-/**
- * Represents a file generated by the compiler.
- */
-export interface GeneratedFile {
-	/** Relative path from the output directory. */
-	path: string;
-	/** File content. */
-	contents: string;
-}
-
-/**
- * Location in the source HTML file.
- */
-export interface SourceLocation {
-	/** Absolute offset in characters. */
-	offset: number;
-	/** 1-based line number. */
-	line: number;
-	/** 1-based column number. */
-	column: number;
-}
-
-/**
- * A normalized node in the design AST.
- */
-export interface DesignNode {
-	/** The type of node. */
-	kind: "element" | "text" | "component";
-	/** HTML tag name (for element kind). */
-	tagName?: string;
-	/** HTML attributes (for element kind). */
-	attributes?: Record<string, string>;
-	/** Parsed inline styles (for element kind). */
-	styles?: Record<string, string>;
-	/** Utility classes to apply. */
-	generatedClassNames?: string[];
-	/** Child nodes. */
-	children?: DesignNode[];
-	/** Inner text content (for text kind). */
-	text?: string;
-	/** Original location in the source HTML. */
-	source?: SourceLocation;
-	/** Component name (for component kind). */
-	component?: string;
-	/** Named export of the component. */
-	importName?: string;
-	/** Mapped prop values for the component. */
-	props?: Record<string, PropValue>;
-	/** Import path of the component. */
-	importPath?: string;
-}
-
-/**
- * A value passed to a component prop.
- */
-export type PropValue =
-	| { kind: "literal"; value: string | number | boolean }
-	| { kind: "text"; value: string }
-	| { kind: "children"; value: DesignNode[] };
-
-/**
- * A parsed CSS selector.
- */
-export interface ParsedSelector {
-	/** Optional tag name. */
-	tagName?: string;
-	/** Optional ID selector. */
-	id?: string;
-	/** List of class names. */
-	classes: string[];
-	/** Attribute selectors. */
-	attributes: Record<string, string>;
-}
+	TestAssertions,
+	TestGenerationConfig,
+	TestState,
+	TestViewport,
+	TokenConfig,
+} from "./types.ts";
 
 /**
  * Input for the core embed function.
  */
 export interface DesignEmbedInput {
-	/** The source design HTML. */
-	html: string;
-	/** Optional external CSS. */
-	css?: string;
-	/** Optional path to the config file (for resolution). */
-	configPath?: string;
 	/** The compiler configuration. */
 	config?: DesignEmbedConfig;
 	/** Working directory. */
 	cwd?: string;
-	/** List of transformer plugins to apply. */
-	transformers?: TransformerPlugin[];
-	/** The target emitter to use. */
-	targetEmitter: TargetEmitter;
+	/** When true, skips writing output files to disk. Defaults to false. */
+	dryRun?: boolean;
+	/** When true, generates test files alongside output files. Defaults to false. */
+	generateTests?: boolean;
 }
 
 /**
  * Result of the embedding process.
  */
 export interface DesignEmbedResult {
+	/** Source HTML resolved from the config's source plugin. */
+	html: string;
+	/** Source CSS resolved from the config's source plugin. */
+	css?: string;
 	/** Generated files. */
 	files: GeneratedFile[];
 	/** Diagnostics reported during compilation. */
@@ -147,83 +94,124 @@ export interface DesignEmbedResult {
 
 /**
  * The main compiler entry point.
- * Parses HTML, applies component mappings, runs transformers, and emits files.
+ * Parses HTML, applies component mappings, and emits files.
  *
  * @param input - The compilation input.
  * @returns A promise resolving to the compilation result.
  *
- * @example
- * const result = await embed({
- *   html: '<div class="btn">Click me</div>',
- *   config: myConfig,
- *   targetEmitter: reactEmitter
- * });
  */
 export async function embed(
 	input: DesignEmbedInput,
 ): Promise<DesignEmbedResult> {
-	let ast = parseHtml(input.html);
-	const diagnostics = validateComponentMappings(input.config?.components ?? []);
+	const cwd = input.cwd ?? process.cwd();
+
+	if (!input.config?.source) {
+		return {
+			html: "",
+			files: [],
+			diagnostics: [
+				{
+					code: "PLUGIN_REQUIRED",
+					message: "Config must include a source plugin.",
+					severity: "error",
+				},
+			],
+		};
+	}
+
+	const sourceResult = await input.config.source.run({ cwd });
+	const diagnostics = [...sourceResult.diagnostics];
 
 	if (diagnostics.some((d) => d.severity === "error")) {
-		return { files: [], diagnostics };
+		return { html: "", files: [], diagnostics };
 	}
 
-	if (input.transformers && input.transformers.length > 0) {
-		ast = await applyTransformers(
-			ast,
-			input.config ?? {},
-			input.transformers,
-			diagnostics,
-		);
-		if (diagnostics.some((d) => d.severity === "error")) {
-			return { files: [], diagnostics };
-		}
+	if (!sourceResult.html) {
+		return {
+			html: "",
+			files: [],
+			diagnostics: [
+				...diagnostics,
+				{
+					code: "PLUGIN_NO_HTML",
+					message: "Source plugin produced no HTML.",
+					severity: "error",
+				},
+			],
+		};
 	}
 
-	const { files } = input.targetEmitter.emit({
-		nodes: ast,
-		css: input.css,
-		config: input.config,
+	const html = sourceResult.html;
+	const css = sourceResult.css;
+
+	const config = patchOutputPaths(input.config as DesignEmbedConfig, cwd);
+
+	const target = config?.output?.target;
+	const targetObj =
+		!target || target === "html" ? htmlTarget : (target as TargetEmitter);
+
+	const mappingDiagnostics = validateComponentMappings(
+		config?.components ?? [],
+	);
+	diagnostics.push(...mappingDiagnostics);
+
+	if (diagnostics.some((d) => d.severity === "error")) {
+		return { html, files: [], diagnostics };
+	}
+
+	const ast = parseHtml(html);
+	const mappedNodes = applyComponentMappings(
+		ast,
+		config?.components ?? [],
+		diagnostics,
+	);
+
+	const { files } = targetObj.emit({
+		nodes: mappedNodes,
+		css,
+		config,
 		diagnostics,
 	});
 
-	return { files, diagnostics };
-}
+	if (input.generateTests && "generateTests" in targetObj) {
+		const testGen = targetObj as unknown as TargetTestGenerator;
+		const testResult = testGen.generateTests({ html, css, config });
+		diagnostics.push(...testResult.diagnostics);
+		if (!diagnostics.some((d) => d.severity === "error")) {
+			files.push(...testResult.files);
+		}
+	}
 
-async function applyTransformers(
-	ast: DesignNode[],
-	config: DesignEmbedConfig,
-	transformers: TransformerPlugin[],
-	diagnostics: Diagnostic[],
-): Promise<DesignNode[]> {
-	let nextAst = ast;
-
-	for (const transformer of sortTransformers(transformers)) {
-		try {
-			const result = await transformer.transform({
-				ast: nextAst,
-				config,
-				diagnostics,
-			});
-			if (result.diagnostics) {
-				diagnostics.push(...result.diagnostics);
-			}
-			if (result.ast) {
-				nextAst = result.ast;
-			}
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			diagnostics.push({
-				code: "TRANSFORMER_FAILED",
-				message: `Transformer ${transformer.name} failed: ${message}`,
-				severity: "error",
-				details: { transformer: transformer.name },
-			});
+	if (!input.dryRun) {
+		for (const file of files) {
+			const outPath = resolve(cwd, file.path);
+			mkdirSync(dirname(outPath), { recursive: true });
+			writeFileSync(outPath, file.contents, "utf-8");
 		}
 	}
 
-	return nextAst;
+	return { html, css, files, diagnostics };
+}
+
+function patchOutputPaths(
+	config: DesignEmbedConfig,
+	cwd: string,
+): DesignEmbedConfig {
+	const viewsDir = config.output?.viewsDir;
+	if (!viewsDir) return config;
+	return {
+		...config,
+		output: { ...config.output, viewsDir: resolveDir(viewsDir, cwd) },
+	};
+}
+
+function resolveDir(
+	dir: string | URL | undefined,
+	cwd: string,
+): string | undefined {
+	if (!dir) return undefined;
+	if (dir instanceof URL) return relative(cwd, fileURLToPath(dir));
+	return dir;
 }
 
 export function applyComponentMappings(
@@ -255,9 +243,9 @@ export function applyComponentMappings(
 			const props = extractProps(node, match.mapping, diagnostics);
 			return {
 				kind: "component",
-				component: match.mapping.importName ?? inferImportName(match.mapping),
-				importName: match.mapping.importName ?? inferImportName(match.mapping),
-				importPath: match.mapping.component,
+				component: match.mapping.component,
+				importName: match.mapping.component,
+				importPath: `./${match.mapping.component}.view`,
 				props,
 				children:
 					props.children?.kind === "children"
@@ -268,6 +256,7 @@ export function applyComponentMappings(
 								diagnostics,
 							),
 				source: node.source,
+				sourceElement: node,
 			};
 		}
 
@@ -537,7 +526,11 @@ function extractProps(
 				});
 				continue;
 			}
-			props[propName] = { kind: "literal", value };
+			props[propName] = {
+				kind: "literal",
+				value,
+				attribute: attributeName,
+			};
 			continue;
 		}
 
@@ -557,11 +550,6 @@ function collectText(node: DesignNode): string {
 		.trim();
 }
 
-function inferImportName(mapping: ComponentMapping): string {
-	const lastSegment = mapping.component.split("/").filter(Boolean).at(-1);
-	return mapping.importName ?? lastSegment ?? "Component";
-}
-
 function currentParent(stack: DesignNode[]): DesignNode {
 	const parent = stack[stack.length - 1];
 	if (!parent) {

package/src/core/nodes.ts

@@ -0,0 +1,74 @@
+/**
+ * Location in the source HTML file.
+ */
+export interface SourceLocation {
+	/** Absolute offset in characters. */
+	offset: number;
+	/** 1-based line number. */
+	line: number;
+	/** 1-based column number. */
+	column: number;
+}
+
+/**
+ * A normalized node in the design AST.
+ */
+export interface DesignNode {
+	/** The type of node. */
+	kind: "element" | "text" | "component";
+	/** HTML tag name (for element kind). */
+	tagName?: string;
+	/** HTML attributes (for element kind). */
+	attributes?: Record<string, string>;
+	/** Parsed inline styles (for element kind). */
+	styles?: Record<string, string>;
+	/** Utility classes to apply. */
+	generatedClassNames?: string[];
+	/** Child nodes. */
+	children?: DesignNode[];
+	/** Inner text content (for text kind). */
+	text?: string;
+	/** Original location in the source HTML. */
+	source?: SourceLocation;
+	/** Component name (for component kind). */
+	component?: string;
+	/** Named export of the component. */
+	importName?: string;
+	/** Mapped prop values for the component. */
+	props?: Record<string, PropValue>;
+	/** Import path of the component. */
+	importPath?: string;
+	/**
+	 * The original element node a component was mapped from. Retained so
+	 * targets can reconstruct the element's structure when emitting the
+	 * component implementation.
+	 */
+	sourceElement?: DesignNode;
+}
+
+/**
+ * A value passed to a component prop.
+ */
+export type PropValue =
+	| {
+			kind: "literal";
+			value: string | number | boolean;
+			/** Source attribute name when the prop is bound to `$attr.*`. */
+			attribute?: string;
+	  }
+	| { kind: "text"; value: string }
+	| { kind: "children"; value: DesignNode[] };
+
+/**
+ * A parsed CSS selector.
+ */
+export interface ParsedSelector {
+	/** Optional tag name. */
+	tagName?: string;
+	/** Optional ID selector. */
+	id?: string;
+	/** List of class names. */
+	classes: string[];
+	/** Attribute selectors. */
+	attributes: Record<string, string>;
+}

package/src/core/plugins/pluginApi.ts

@@ -0,0 +1,44 @@
+import type { Diagnostic } from "../diagnostics/diagnostic.ts";
+
+/**
+ * Represents a file generated by the compiler.
+ */
+export interface GeneratedFile {
+	/** Relative path from the output directory. */
+	path: string;
+	/** File content. */
+	contents: string;
+}
+
+export interface GeneratedAsset {
+	path: string;
+	contents?: string | Uint8Array;
+	sourceUrl?: string;
+}
+
+export interface SourcePlugin {
+	name: string;
+	run(input: SourcePluginInput): Promise<SourcePluginResult>;
+}
+
+export interface SourcePluginInput {
+	cwd: string;
+	config?: unknown;
+}
+
+export interface SourcePluginResult {
+	html?: string;
+	css?: string;
+	assets?: GeneratedAsset[];
+	files?: GeneratedFile[];
+	diagnostics: Diagnostic[];
+}
+
+export interface TargetEmitResult {
+	files: GeneratedFile[];
+}
+
+export interface TargetTestGenerateResult {
+	files: GeneratedFile[];
+	diagnostics: Diagnostic[];
+}

package/src/core/types.ts

@@ -0,0 +1,120 @@
+import type { Diagnostic } from "./diagnostics/diagnostic.ts";
+import type { DesignNode } from "./nodes.ts";
+import type {
+	SourcePlugin,
+	TargetEmitResult,
+	TargetTestGenerateResult,
+} from "./plugins/pluginApi.ts";
+
+// ---------------------------------------------------------------------------
+// Target adapter interfaces
+// ---------------------------------------------------------------------------
+
+export interface TargetEmitInput {
+	nodes: DesignNode[];
+	css?: string;
+	config?: DesignEmbedConfig;
+	diagnostics: Diagnostic[];
+}
+
+export interface TargetEmitter {
+	emit(input: TargetEmitInput): TargetEmitResult;
+}
+
+export interface TargetTestGenerateInput {
+	html: string;
+	css?: string;
+	config: DesignEmbedConfig;
+}
+
+export interface TargetTestGenerator {
+	generateTests(input: TargetTestGenerateInput): TargetTestGenerateResult;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration types
+// ---------------------------------------------------------------------------
+
+export type StyleMode = "inline" | "css-modules" | "tailwind";
+
+export interface ComponentMapping {
+	selector: string;
+	component: string;
+	props?: Record<string, string>;
+}
+
+export interface TokenConfig {
+	spacing?: {
+		unit?: "px" | "rem";
+		threshold?: number;
+		values?: Record<string, number>;
+	};
+	sizing?: NumericTokenGroup;
+	typography?: NumericTokenGroup;
+	radius?: Record<string, number>;
+	borderWidth?: Record<string, number>;
+	shadow?: Record<string, string>;
+	colors?: Record<string, string>;
+	colorThreshold?: number;
+}
+
+export interface NumericTokenGroup {
+	unit?: "px" | "rem";
+	threshold?: number;
+	values?: Record<string, number>;
+}
+
+export type StyleMappings = Record<string, Record<string, string>>;
+
+export interface TestGenerationConfig {
+	outputDir?: string;
+	runner?: "playwright";
+	viewports?: TestViewport[];
+	states?: TestState[];
+	assertions?: TestAssertions;
+}
+
+export interface TestViewport {
+	name?: string;
+	width: number;
+	height: number;
+}
+
+export interface TestState {
+	name: string;
+	hover?: string;
+	focus?: string;
+	click?: string;
+	waitFor?: string;
+}
+
+export interface TestAssertions {
+	screenshot?: boolean;
+	layout?: boolean;
+	layoutTolerance?: number;
+	selectors?: string[];
+	/**
+	 * Per-pixel color sensitivity (0-1) for the screenshot comparison. Smaller
+	 * is stricter. Defaults to 0.2.
+	 */
+	screenshotThreshold?: number;
+	/**
+	 * Maximum number of differing pixels tolerated in the screenshot
+	 * comparison. Defaults to 0 (byte-exact).
+	 */
+	screenshotMaxDiffPixels?: number;
+}
+
+export interface DesignEmbedConfig {
+	output?: {
+		viewsDir?: string | URL;
+		target?: "html" | TargetEmitter;
+		viewName?: string;
+		styleMode?: StyleMode;
+	};
+	components?: ComponentMapping[];
+	tokens?: TokenConfig;
+	styleMappings?: StyleMappings;
+	source?: SourcePlugin;
+	tests?: TestGenerationConfig;
+}

package/src/index.ts

@@ -1,2 +1,48 @@
-export * from "@design-embed/config";
-export * from "@design-embed/core";
+// Config
+
+export type { LoadConfigResult } from "./config/index.ts";
+export {
+	defineConfig,
+	fromFile,
+	loadConfig,
+	validateConfig,
+} from "./config/index.ts";
+// Config schema types
+// Diagnostics
+// Extension types — for authoring source plugins and custom targets
+export type {
+	ComponentMapping,
+	DesignEmbedConfig,
+	DesignEmbedInput,
+	DesignEmbedResult,
+	DesignNode,
+	Diagnostic,
+	DiagnosticSeverity,
+	GeneratedAsset,
+	GeneratedFile,
+	NumericTokenGroup,
+	PropValue,
+	SourceLocation,
+	SourcePlugin,
+	SourcePluginInput,
+	SourcePluginResult,
+	StyleMappings,
+	StyleMode,
+	TargetEmitInput,
+	TargetEmitResult,
+	TargetEmitter,
+	TargetTestGenerateInput,
+	TargetTestGenerateResult,
+	TargetTestGenerator,
+	TestAssertions,
+	TestGenerationConfig,
+	TestState,
+	TestViewport,
+	TokenConfig,
+} from "./core/index.ts";
+// Embed
+// AST utilities and types — for custom target authors
+export { applyComponentMappings, embed, parseHtml } from "./core/index.ts";
+export type { HtmlTargetOptions } from "./targets/html.ts";
+// Built-in HTML target
+export { HtmlTarget, htmlTarget } from "./targets/html.ts";