design-embed 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,400 @@
+//#region packages/config/src/index.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.
+ */
+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[];
+}
+/**
+ * Available styling modes.
+ */
+type StyleMode = "inline" | "css-modules" | "tailwind";
+/**
+ * Defines how to map a design element to a project component.
+ */
+interface ComponentMapping {
+  /** CSS selector to match the element in the design HTML. */
+  selector: string;
+  /** Import path of the project component. */
+  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[];
+}
+/**
+ * Helper to define configuration with type safety.
+ *
+ * @param config - The configuration object.
+ * @returns The same configuration object.
+ *
+ * @example
+ * export default defineConfig({
+ *   output: { target: reactTarget }
+ * });
+ */
+declare function defineConfig(config: DesignEmbedConfig): DesignEmbedConfig;
+/**
+ * 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.
+ */
+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>;
+}
+//#endregion
+//#region packages/core/src/plugins/pluginApi.d.ts
+interface GeneratedAsset {
+  path: string;
+  contents?: string | Uint8Array;
+  sourceUrl?: string;
+}
+interface SourcePlugin {
+  name: string;
+  run(input: SourcePluginInput): Promise<SourcePluginResult>;
+}
+interface SourcePluginInput {
+  cwd: string;
+  args: Record<string, string | boolean>;
+  config?: unknown;
+}
+interface SourcePluginResult {
+  html?: string;
+  css?: string;
+  assets?: GeneratedAsset[];
+  files?: GeneratedFile[];
+  diagnostics: Diagnostic[];
+}
+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>;
+}
+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 CheckModeResult {
+  ok: boolean;
+  diagnostics: Diagnostic[];
+}
+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[];
+}
+//#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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/**
+ * Result of the embedding process.
+ */
+interface DesignEmbedResult {
+  /** Generated files. */
+  files: GeneratedFile[];
+  /** Diagnostics reported during compilation. */
+  diagnostics: Diagnostic[];
+}
+/**
+ * The main compiler entry point.
+ * 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
+ * });
+ */
+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 };

package/dist/index.mjs

@@ -0,0 +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 };