design-embed 0.1.1 → 0.2.1

package/dist/index.d.mts

@@ -1,197 +1,75 @@
-//#region packages/config/src/index.d.ts
+//#region packages/design-embed/src/core/nodes.d.ts
 /**
- * Minimal interface every source plugin instance must satisfy.
- * Keep this interface in the config package so plugin packages can implement
- * it without pulling in the heavier core package.
- */
-interface PluginDefinition {
-  readonly name: string;
-}
-/**
- * External target adapter instance supplied by packages like
- * `@design-embed/target-react`.
- */
-interface TargetAdapterDefinition {
-  readonly name?: string;
-  emit(input: unknown): unknown;
-  generateTests?(input: unknown): unknown;
-}
-/**
- * A diagnostic reported during configuration loading or validation.
- */
-interface ConfigDiagnostic {
-  /** Unique error code. */
-  code: string;
-  /** Human-readable message. */
-  message: string;
-  /** Severity of the issue. */
-  severity: "error" | "warning" | "info";
-}
-/**
- * The root configuration object for design-embed.
- */
-interface DesignEmbedConfig {
-  /** Output settings for the generated code. */
-  output?: {
-    /** Directory where generated views will be written. */viewsDir?: string; /** Directory for page-level assemblies. */
-    assembliesDir?: string; /** Target adapter instance. Omit to use built-in HTML output. */
-    target?: "html" | TargetAdapterDefinition; /** Name of the generated component/view. */
-    viewName?: string; /** How to handle styles: inline, Tailwind, or CSS Modules. */
-    styleMode?: StyleMode;
-  };
-  /** Mappings from HTML selectors to project components. */
-  components?: ComponentMapping[];
-  /** Design token scales for style snapping. */
-  tokens?: TokenConfig;
-  /** Mappings for Tailwind utility classes. */
-  styleMappings?: StyleMappings;
-  /** Source plugin instances to run when fetching HTML with `design-embed --out`. */
-  plugins?: PluginDefinition[];
-  /** Visual and layout test generation settings. */
-  tests?: TestGenerationConfig;
-}
-/**
- * Configuration for generated regression tests.
+ * Location in the source HTML file.
  */
-interface TestGenerationConfig {
-  /** Directory where generated test files and reference fixtures are written. */
-  outputDir?: string;
-  /** Test runner emitted by the generator. */
-  runner?: "playwright";
-  /** Source artifact paths used as the visual/layout reference. */
-  source?: {
-    /** Path to the reference design HTML, relative to the config directory or cwd. */html?: string; /** Optional path to external reference CSS, relative to the config directory or cwd. */
-    css?: string;
-  };
-  /** Viewports to verify. */
-  viewports?: TestViewport[];
-  /** Interaction states to verify for every viewport. */
-  states?: TestState[];
-  /** Assertion settings. */
-  assertions?: TestAssertions;
-}
-interface TestViewport {
-  /** Stable viewport name used in test titles. */
-  name?: string;
-  width: number;
-  height: number;
-}
-interface TestState {
-  /** Stable state name used in test titles. */
-  name: string;
-  /** Selector to hover before assertions. */
-  hover?: string;
-  /** Selector to focus before assertions. */
-  focus?: string;
-  /** Selector to click before assertions. */
-  click?: string;
-  /** Selector to wait for before assertions. */
-  waitFor?: string;
-}
-interface TestAssertions {
-  /** Whether to compare full-page screenshots. Defaults to true. */
-  screenshot?: boolean;
-  /** Whether to compare element bounding boxes. Defaults to true. */
-  layout?: boolean;
-  /** Maximum x/y/width/height drift in CSS pixels. Defaults to 0. */
-  layoutTolerance?: number;
-  /** Selectors to collect for layout comparison. Defaults to [":scope", ":scope *"]. */
-  selectors?: string[];
+interface SourceLocation {
+  /** Absolute offset in characters. */
+  offset: number;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column number. */
+  column: number;
 }
 /**
- * Available styling modes.
- */
-type StyleMode = "inline" | "css-modules" | "tailwind";
-/**
- * Defines how to map a design element to a project component.
+ * A normalized node in the design AST.
  */
-interface ComponentMapping {
-  /** CSS selector to match the element in the design HTML. */
-  selector: string;
-  /** Import path of the project component. */
-  component: string;
+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;
-  /** Prop values to pass, supports $text, $children, and $attr expressions. */
-  props?: Record<string, string>;
-}
-/**
- * Configuration for design tokens.
- */
-interface TokenConfig {
-  /** Spacing scale (e.g. padding, margin, gap). */
-  spacing?: {
-    /** Unit to use in generated styles. */unit?: "px" | "rem"; /** Max distance for value snapping. */
-    threshold?: number; /** The token scale mapping names to values. */
-    values?: Record<string, number>;
-  };
-  /** Sizing scale (e.g. width, height). */
-  sizing?: NumericTokenGroup;
-  /** Typography scale (e.g. font-size, line-height). */
-  typography?: NumericTokenGroup;
-  /** Border radius scale. */
-  radius?: Record<string, number>;
-  /** Border width scale. */
-  borderWidth?: Record<string, number>;
-  /** Box shadow scale. */
-  shadow?: Record<string, string>;
-  /** Color palette. */
-  colors?: Record<string, string>;
-  /** Color matching threshold (CIE76). */
-  colorThreshold?: number;
-}
-interface NumericTokenGroup {
-  unit?: "px" | "rem";
-  threshold?: number;
-  values?: Record<string, number>;
-}
-type StyleMappings = Record<string, Record<string, string>>;
-/**
- * Result of loading a configuration file.
- */
-interface LoadConfigResult {
-  /** The loaded and validated config, if successful. */
-  config?: DesignEmbedConfig;
-  /** Any errors or warnings encountered during loading. */
-  diagnostics: ConfigDiagnostic[];
+  /** 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;
 }
 /**
- * Helper to define configuration with type safety.
- *
- * @param config - The configuration object.
- * @returns The same configuration object.
- *
- * @example
- * export default defineConfig({
- *   output: { target: reactTarget }
- * });
+ * A value passed to a component prop.
  */
-declare function defineConfig(config: DesignEmbedConfig): DesignEmbedConfig;
+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[];
+};
+//#endregion
+//#region packages/design-embed/src/core/plugins/pluginApi.d.ts
 /**
- * Asynchronously loads a configuration file from disk.
- * Supports .ts, .js, and .mjs files via dynamic import.
- *
- * @param configPath - Path to the config file.
- * @param cwd - Current working directory.
- * @returns A promise resolving to the load result.
+ * Represents a file generated by the compiler.
  */
-declare function loadConfig(configPath: string, cwd?: string): Promise<LoadConfigResult>;
-declare function validateConfig(config: DesignEmbedConfig): ConfigDiagnostic[];
-//#endregion
-//#region packages/core/src/diagnostics/diagnostic.d.ts
-type DiagnosticSeverity = "error" | "warning" | "info";
-interface Diagnostic {
-  code: string;
-  message: string;
-  severity: DiagnosticSeverity;
-  file?: string;
-  source?: SourceLocation;
-  selector?: string;
-  property?: string;
-  details?: Record<string, unknown>;
+interface GeneratedFile {
+  /** Relative path from the output directory. */
+  path: string;
+  /** File content. */
+  contents: string;
 }
-//#endregion
-//#region packages/core/src/plugins/pluginApi.d.ts
 interface GeneratedAsset {
   path: string;
   contents?: string | Uint8Array;
@@ -203,7 +81,6 @@ interface SourcePlugin {
 }
 interface SourcePluginInput {
   cwd: string;
-  args: Record<string, string | boolean>;
   config?: unknown;
 }
 interface SourcePluginResult {
@@ -213,164 +90,129 @@ interface SourcePluginResult {
   files?: GeneratedFile[];
   diagnostics: Diagnostic[];
 }
+interface TargetEmitResult {
+  files: GeneratedFile[];
+}
+interface TargetTestGenerateResult {
+  files: GeneratedFile[];
+  diagnostics: Diagnostic[];
+}
+//#endregion
+//#region packages/design-embed/src/core/types.d.ts
 interface TargetEmitInput {
   nodes: DesignNode[];
   css?: string;
   config?: DesignEmbedConfig;
   diagnostics: Diagnostic[];
 }
-interface TargetEmitResult {
-  files: GeneratedFile[];
-}
 interface TargetEmitter {
-  name?: string;
   emit(input: TargetEmitInput): TargetEmitResult;
 }
 interface TargetTestGenerateInput {
   html: string;
   css?: string;
   config: DesignEmbedConfig;
-  diagnostics: Diagnostic[];
-  generatedFiles?: GeneratedFile[];
-}
-interface TargetTestGenerateResult {
-  files: GeneratedFile[];
 }
 interface TargetTestGenerator {
   generateTests(input: TargetTestGenerateInput): TargetTestGenerateResult;
 }
-//#endregion
-//#region packages/core/src/diagnostics/jsonDiagnostic.d.ts
-interface JsonDiagnostic {
-  code: string;
-  severity: "error" | "warning" | "info";
-  message: string;
-  file?: string;
-  line?: number;
-  column?: number;
-  details?: Record<string, unknown>;
+type StyleMode = "inline" | "css-modules" | "tailwind";
+interface ComponentMapping {
+  selector: string;
+  component: string;
+  props?: Record<string, string>;
 }
-declare function toJsonDiagnostic(diagnostic: Diagnostic): JsonDiagnostic;
-declare function toJsonDiagnostics(diagnostics: Diagnostic[]): JsonDiagnostic[];
-declare function formatDiagnosticText(diagnostic: Diagnostic): string;
-//#endregion
-//#region packages/core/src/pipeline/checkMode.d.ts
-interface CheckModeInput {
-  files: GeneratedFile[];
-  cwd: string;
-  readFile(path: string): string | undefined;
+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;
 }
-interface CheckModeResult {
-  ok: boolean;
-  diagnostics: Diagnostic[];
+interface NumericTokenGroup {
+  unit?: "px" | "rem";
+  threshold?: number;
+  values?: Record<string, number>;
 }
-declare function checkGeneratedFiles(input: CheckModeInput): CheckModeResult;
-//#endregion
-//#region packages/core/src/plugins/pluginRegistry.d.ts
-declare class PluginRegistry {
-  #private;
-  registerSource(plugin: SourcePlugin): void;
-  getSource(name: string): SourcePlugin | undefined;
-  listSources(): SourcePlugin[];
+type StyleMappings = Record<string, Record<string, string>>;
+interface TestGenerationConfig {
+  outputDir?: string;
+  runner?: "playwright";
+  viewports?: TestViewport[];
+  states?: TestState[];
+  assertions?: TestAssertions;
 }
-//#endregion
-//#region packages/core/src/index.d.ts
-/**
- * Represents a file generated by the compiler.
- */
-interface GeneratedFile {
-  /** Relative path from the output directory. */
-  path: string;
-  /** File content. */
-  contents: string;
+interface TestViewport {
+  name?: string;
+  width: number;
+  height: number;
 }
-/**
- * Location in the source HTML file.
- */
-interface SourceLocation {
-  /** Absolute offset in characters. */
-  offset: number;
-  /** 1-based line number. */
-  line: number;
-  /** 1-based column number. */
-  column: number;
+interface TestState {
+  name: string;
+  hover?: string;
+  focus?: string;
+  click?: string;
+  waitFor?: string;
 }
-/**
- * A normalized node in the design AST.
- */
-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;
+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;
 }
-/**
- * A value passed to a component prop.
- */
-type PropValue = {
-  kind: "literal";
-  value: string | number | boolean;
-} | {
-  kind: "text";
-  value: string;
-} | {
-  kind: "children";
-  value: DesignNode[];
-};
-/**
- * A parsed CSS selector.
- */
-interface ParsedSelector {
-  /** Optional tag name. */
-  tagName?: string;
-  /** Optional ID selector. */
-  id?: string;
-  /** List of class names. */
-  classes: string[];
-  /** Attribute selectors. */
-  attributes: Record<string, string>;
+interface DesignEmbedConfig {
+  output?: {
+    viewsDir?: string | URL;
+    target?: "html" | TargetEmitter;
+    viewName?: string;
+    styleMode?: StyleMode;
+  };
+  components?: ComponentMapping[];
+  tokens?: TokenConfig;
+  styleMappings?: StyleMappings;
+  source?: SourcePlugin;
+  tests?: TestGenerationConfig;
 }
+//#endregion
+//#region packages/design-embed/src/core/index.d.ts
 /**
  * Input for the core embed function.
  */
 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;
-  /** 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.
  */
 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. */
@@ -383,18 +225,49 @@ interface DesignEmbedResult {
  * @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
- * });
  */
 declare function embed(input: DesignEmbedInput): Promise<DesignEmbedResult>;
 declare function applyComponentMappings(nodes: DesignNode[], mappings: ComponentMapping[], diagnostics?: Diagnostic[]): DesignNode[];
-declare function parseSelector(selector: string): ParsedSelector | undefined;
-declare function matchesSelector(node: DesignNode, selector: ParsedSelector): boolean;
 declare function parseHtml(html: string): DesignNode[];
-declare function parseInlineStyle(style: string | undefined): Record<string, string>;
 //#endregion
-export { type CheckModeInput, type CheckModeResult, ComponentMapping, ConfigDiagnostic, DesignEmbedConfig, DesignEmbedInput, DesignEmbedResult, DesignNode, type Diagnostic, type DiagnosticSeverity, type GeneratedAsset, GeneratedFile, type JsonDiagnostic, LoadConfigResult, NumericTokenGroup, ParsedSelector, PluginDefinition, PluginRegistry, PropValue, SourceLocation, type SourcePlugin, type SourcePluginInput, type SourcePluginResult, StyleMappings, StyleMode, TargetAdapterDefinition, type TargetEmitInput, type TargetEmitResult, type TargetEmitter, type TargetTestGenerateInput, type TargetTestGenerateResult, type TargetTestGenerator, TestAssertions, TestGenerationConfig, TestState, TestViewport, TokenConfig, applyComponentMappings, checkGeneratedFiles, defineConfig, embed, formatDiagnosticText, loadConfig, matchesSelector, parseHtml, parseInlineStyle, parseSelector, toJsonDiagnostic, toJsonDiagnostics, validateConfig };
+//#region packages/design-embed/src/core/diagnostics/diagnostic.d.ts
+type DiagnosticSeverity = "error" | "warning" | "info";
+interface Diagnostic {
+  code: string;
+  message: string;
+  severity: DiagnosticSeverity;
+  file?: string;
+  source?: SourceLocation;
+  selector?: string;
+  property?: string;
+  details?: Record<string, unknown>;
+}
+//#endregion
+//#region packages/design-embed/src/config/index.d.ts
+interface LoadConfigResult {
+  config?: DesignEmbedConfig;
+  configPath?: string;
+  diagnostics: Diagnostic[];
+}
+declare function defineConfig(config: DesignEmbedConfig): DesignEmbedConfig;
+declare function fromFile(htmlPath: string | URL, cssPath?: string | URL): SourcePlugin;
+declare function loadConfig(configPath: string, cwd?: string): Promise<LoadConfigResult>;
+declare function validateConfig(config: DesignEmbedConfig): Diagnostic[];
+//#endregion
+//#region packages/design-embed/src/targets/html.d.ts
+interface HtmlTargetOptions {
+  domModel?: "light" | "shadow";
+}
+declare class HtmlTarget implements TargetEmitter, TargetTestGenerator {
+  private readonly domModel;
+  constructor(options?: HtmlTargetOptions);
+  emit({
+    nodes,
+    css,
+    config
+  }: TargetEmitInput): TargetEmitResult;
+  generateTests(input: TargetTestGenerateInput): TargetTestGenerateResult;
+}
+declare const htmlTarget: TargetEmitter & TargetTestGenerator;
+//#endregion
+export { type ComponentMapping, type DesignEmbedConfig, type DesignEmbedInput, type DesignEmbedResult, type DesignNode, type Diagnostic, type DiagnosticSeverity, type GeneratedAsset, type GeneratedFile, HtmlTarget, type HtmlTargetOptions, type LoadConfigResult, type NumericTokenGroup, type PropValue, type SourceLocation, type SourcePlugin, type SourcePluginInput, type SourcePluginResult, type StyleMappings, type StyleMode, type TargetEmitInput, type TargetEmitResult, type TargetEmitter, type TargetTestGenerateInput, type TargetTestGenerateResult, type TargetTestGenerator, type TestAssertions, type TestGenerationConfig, type TestState, type TestViewport, type TokenConfig, applyComponentMappings, defineConfig, embed, fromFile, htmlTarget, loadConfig, parseHtml, validateConfig };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as parseInlineStyle, c as checkGeneratedFiles, d as toJsonDiagnostics, f as defineConfig, i as parseHtml, l as formatDiagnosticText, m as validateConfig, n as embed, o as parseSelector, p as loadConfig, r as matchesSelector, s as PluginRegistry, t as applyComponentMappings, u as toJsonDiagnostic } from "./src-D3fnqGCq.mjs";
-export { PluginRegistry, applyComponentMappings, checkGeneratedFiles, defineConfig, embed, formatDiagnosticText, loadConfig, matchesSelector, parseHtml, parseInlineStyle, parseSelector, toJsonDiagnostic, toJsonDiagnostics, validateConfig };
+import { c as htmlTarget, d as loadConfig, f as validateConfig, l as defineConfig, n as embed, r as parseHtml, s as HtmlTarget, t as applyComponentMappings, u as fromFile } from "./core-DSlWqRBj.mjs";
+export { HtmlTarget, applyComponentMappings, defineConfig, embed, fromFile, htmlTarget, loadConfig, parseHtml, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-embed",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "private": false,
   "publishConfig": {
@@ -23,15 +23,7 @@
   "bin": {
     "design-embed": "./dist/cli.mjs"
   },
-  "devDependencies": {
-    "@design-embed/config": "0.1.1",
-    "@design-embed/core": "0.1.1"
-  },
   "scripts": {
-    "dev": "node src/cli.ts",
-    "compile:react": "node src/cli.ts react",
-    "compile:html": "node src/cli.ts html",
-    "compile:vanjs": "node src/cli.ts vanjs",
-    "get-raw": "node src/cli.ts raw"
+    "test": "node --conditions=development --test src/**/*.test.ts"
   }
 }

package/src/cli.ts

@@ -4,48 +4,23 @@ import { runCheckCommand } from "./commands/check.ts";
 import { runCompileCommand } from "./commands/compile.ts";
 import { runGenerateTestsCommand } from "./commands/generateTests.ts";
 import { runInitCommand } from "./commands/init.ts";
-import { runPluginCommand } from "./commands/plugin.ts";
 
 async function main(): Promise<number> {
-	const args = process.argv.slice(2);
-	const parsed = parseArgs(args);
+	const { command, flags } = parseArgs(process.argv.slice(2));
 
-	if (args[0] === "check") {
-		return runCheckCommand(parsed.flags);
+	if (command === "check") {
+		return runCheckCommand(flags);
 	}
-
-	if (args[0] === "plugin") {
-		return runPluginCommand(parsed.positionals[0], parsed.flags);
+	if (command === "generate-tests") {
+		return runGenerateTestsCommand(flags);
 	}
-
-	if (args[0] === "generate-tests") {
-		return runGenerateTestsCommand(parsed.flags);
+	if (command === "init") {
+		return runInitCommand(flags);
 	}
 
-	if (args[0] === "init") {
-		return runInitCommand(parsed.flags);
-	}
-
-	const flags =
-		args[0] && !args[0].startsWith("--")
-			? { ...parsed.flags, "--": args[0] }
-			: parsed.flags;
-	if (getOutPath(flags) && !hasInput(flags)) {
-		return runPluginCommand(undefined, flags);
-	}
 	return runCompileCommand(flags);
 }
 
-function getOutPath(flags: Record<string, string | boolean>): boolean {
-	return typeof flags["--out"] === "string";
-}
-
-function hasInput(flags: Record<string, string | boolean>): boolean {
-	return (
-		typeof flags["--input"] === "string" || typeof flags["--"] === "string"
-	);
-}
-
 main()
 	.then((code) => {
 		if (code !== 0) {