@design-embed/target-react 0.1.0 → 1.0.1

package/dist/index.mjs

@@ -0,0 +1,964 @@
+import { applyComponentMappings, parseHtml } from "design-embed";
+//#region packages/target-react/src/index.ts
+var ReactTarget = class {
+	emit({ nodes, css, config, diagnostics }) {
+		const viewsDir = String(config?.output?.viewsDir ?? "src/generated/views");
+		const viewName = config?.output?.viewName ?? "DesignView";
+		const styleResult = transformStyles(nodes, css, config, diagnostics);
+		const contents = emitReactView(styleResult.nodes, viewName, { cssModulePath: styleResult.cssModulePath });
+		const files = [{
+			path: `${viewsDir}/${viewName}.view.tsx`,
+			contents
+		}];
+		if (styleResult.cssModule && styleResult.cssModulePath) files.push({
+			path: `${viewsDir}/${styleResult.cssModulePath}`,
+			contents: styleResult.cssModule
+		});
+		for (const split of emitComponentSplitViews(styleResult.nodes, viewsDir, styleResult.cssModulePath)) files.push(split);
+		return { files };
+	}
+	generateTests(input) {
+		return reactTestGenerator.generateTests(input);
+	}
+};
+const reactTestGenerator = { generateTests({ html, css, config }) {
+	const diagnostics = [];
+	const tests = config.tests;
+	if (tests?.runner && tests.runner !== "playwright") {
+		diagnostics.push({
+			code: "TEST_RUNNER_UNSUPPORTED",
+			message: `Unsupported test runner: ${tests.runner}`,
+			severity: "error"
+		});
+		return {
+			files: [],
+			diagnostics
+		};
+	}
+	const viewsDir = String(config.output?.viewsDir ?? "src/generated/views");
+	const viewName = config.output?.viewName ?? "DesignView";
+	const outputDir = tests?.outputDir ?? `${viewsDir}/tests`;
+	const fixturePath = `${outputDir}/${viewName}.reference.html`;
+	const specPath = `${outputDir}/${viewName}.visual.spec.tsx`;
+	const referenceHtml = `${css?.trim() ? `<style>\n${css}\n</style>\n` : ""}${html}`;
+	const assertionDefaults = {
+		screenshot: tests?.assertions?.screenshot ?? true,
+		layout: tests?.assertions?.layout ?? true,
+		layoutTolerance: tests?.assertions?.layoutTolerance ?? 1,
+		selectors: tests?.assertions?.selectors ?? [":scope", ":scope *"],
+		screenshotThreshold: tests?.assertions?.screenshotThreshold ?? .2,
+		screenshotMaxDiffPixels: tests?.assertions?.screenshotMaxDiffPixels ?? 500
+	};
+	const viewportDefaults = tests?.viewports ?? [{
+		name: "default",
+		width: 1440,
+		height: 900
+	}];
+	const stateDefaults = tests?.states ?? [{ name: "default" }];
+	const referenceHtmlFileName = `${viewName}.reference.html`;
+	const files = [{
+		path: fixturePath,
+		contents: referenceHtml.endsWith("\n") ? referenceHtml : `${referenceHtml}\n`
+	}, {
+		path: specPath,
+		contents: emitReactVisualSpec({
+			viewName,
+			viewImportPath: toRelativeImport(specPath, `${viewsDir}/${viewName}.view`),
+			fixtureFileName: referenceHtmlFileName,
+			viewports: viewportDefaults,
+			states: stateDefaults,
+			assertions: assertionDefaults
+		})
+	}];
+	const parsedHtmlNodes = parseHtml(html);
+	const componentNodes = collectComponentNodes(applyComponentMappings(parsedHtmlNodes, config.components ?? []));
+	for (const mapping of config.components ?? []) {
+		const componentName = mapping.component;
+		const componentSpecPath = `${outputDir}/${componentName}.visual.spec.tsx`;
+		const componentReferenceHtmlFileName = `${componentName}.reference.html`;
+		const componentFixturePath = `${outputDir}/${componentReferenceHtmlFileName}`;
+		const matchingNode = findNodeBySelector(parsedHtmlNodes, mapping.selector);
+		const elementHtml = matchingNode ? serializeNodeToHtml(matchingNode) : "";
+		const componentReferenceHtml = `${css?.trim() ? `<style>\n${css}\n</style>\n` : ""}${elementHtml}`;
+		const mountNode = componentNodes.get(componentName);
+		files.push({
+			path: componentFixturePath,
+			contents: componentReferenceHtml.endsWith("\n") ? componentReferenceHtml : `${componentReferenceHtml}\n`
+		});
+		files.push({
+			path: componentSpecPath,
+			contents: emitComponentVisualSpec({
+				componentName,
+				selector: mapping.selector,
+				mountJsx: emitComponentMount(componentName, mountNode),
+				componentImportPath: toRelativeImport(componentSpecPath, `${viewsDir}/${componentName}.view`),
+				referenceHtmlFileName: componentReferenceHtmlFileName,
+				viewports: viewportDefaults,
+				states: stateDefaults,
+				assertions: assertionDefaults
+			})
+		});
+	}
+	return {
+		diagnostics,
+		files
+	};
+} };
+function emitReactVisualSpec(input) {
+	const viewports = JSON.stringify(input.viewports, null, 2);
+	const states = JSON.stringify(input.states, null, 2);
+	const selectors = JSON.stringify(input.assertions.selectors, null, 2);
+	const screenshotEnabled = JSON.stringify(input.assertions.screenshot);
+	const layoutEnabled = JSON.stringify(input.assertions.layout);
+	const layoutTolerance = JSON.stringify(input.assertions.layoutTolerance);
+	const screenshotThreshold = JSON.stringify(input.assertions.screenshotThreshold);
+	const screenshotMaxDiffPixels = JSON.stringify(input.assertions.screenshotMaxDiffPixels);
+	return `import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "@playwright/experimental-ct-react";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { ${input.viewName} } from "${input.viewImportPath}";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const referenceHtml = readFileSync(resolve(currentDir, "./${input.fixtureFileName}"), "utf-8");
+const viewports = ${viewports};
+const states = ${states};
+const selectors = ${selectors};
+const screenshotEnabled = ${screenshotEnabled};
+const layoutEnabled = ${layoutEnabled};
+const layoutTolerance = ${layoutTolerance};
+const screenshotThreshold = ${screenshotThreshold};
+const screenshotMaxDiffPixels = ${screenshotMaxDiffPixels};
+
+for (const viewport of viewports) {
+\tfor (const state of states) {
+\t\tconst viewportName = viewport.name ?? String(viewport.width) + "x" + String(viewport.height);
+\t\ttest("${input.viewName} matches source at " + viewportName + " / " + state.name, async ({ mount, page }) => {
+\t\t\tawait page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+\t\t\tawait page.setContent(referenceHtml);
+\t\t\tawait applyState(page, state);
+\t\t\tconst expectedScreenshot = screenshotEnabled ? await page.screenshot({ fullPage: true }) : undefined;
+\t\t\tconst expectedLayout = layoutEnabled ? await readLayout(page.locator("body > *").first(), selectors) : [];
+
+\t\t\tawait page.setContent("");
+\t\t\tconst component = await mount(<${input.viewName} />);
+\t\t\tawait applyState(page, state);
+\t\t\tconst actualScreenshot = screenshotEnabled ? await page.screenshot({ fullPage: true }) : undefined;
+\t\t\tconst actualLayout = layoutEnabled ? await readLayout(component, selectors) : [];
+
+\t\t\tif (screenshotEnabled) {
+\t\t\t\tcompareScreenshots(actualScreenshot, expectedScreenshot, screenshotThreshold, screenshotMaxDiffPixels);
+\t\t\t}
+\t\t\tif (layoutEnabled) {
+\t\t\t\texpectLayoutToMatch(actualLayout, expectedLayout, layoutTolerance);
+\t\t\t}
+\t\t});
+\t}
+}
+
+async function applyState(page, state) {
+\tif (state.waitFor) {
+\t\tawait page.waitForSelector(state.waitFor);
+\t}
+\tif (state.hover) {
+\t\tawait page.hover(state.hover);
+\t}
+\tif (state.focus) {
+\t\tawait page.focus(state.focus);
+\t}
+\tif (state.click) {
+\t\tawait page.click(state.click);
+\t}
+}
+
+async function readLayout(root, selectorsToRead) {
+\treturn root.evaluate((element, values) => {
+\t\tconst origin = element.getBoundingClientRect();
+\t\treturn values.flatMap((selector) => {
+\t\t\tconst matches = selector === ":scope" ? [element] : Array.from(element.querySelectorAll(selector));
+\t\t\treturn matches.map((matchedElement, index) => {
+\t\t\t\tconst rect = matchedElement.getBoundingClientRect();
+\t\t\t\treturn {
+\t\t\t\t\tselector,
+\t\t\t\t\tindex,
+\t\t\t\t\ttagName: matchedElement.tagName.toLowerCase(),
+\t\t\t\t\tx: rect.x - origin.x,
+\t\t\t\t\ty: rect.y - origin.y,
+\t\t\t\t\twidth: rect.width,
+\t\t\t\t\theight: rect.height,
+\t\t\t\t};
+\t\t\t});
+\t\t});
+\t}, selectorsToRead);
+}
+
+function compareScreenshots(actual, expected, threshold, maxDiffPixels) {
+\tif (!actual || !expected) {
+\t\texpect(actual).toEqual(expected);
+\t\treturn;
+\t}
+\tconst actualPng = PNG.sync.read(actual);
+\tconst expectedPng = PNG.sync.read(expected);
+\texpect(actualPng.width, "screenshot width").toBe(expectedPng.width);
+\texpect(actualPng.height, "screenshot height").toBe(expectedPng.height);
+\tconst diffPixels = pixelmatch(actualPng.data, expectedPng.data, null, actualPng.width, actualPng.height, { threshold });
+\texpect(diffPixels, "screenshot pixels differing beyond threshold").toBeLessThanOrEqual(maxDiffPixels);
+}
+
+function expectLayoutToMatch(actual, expected, tolerance) {
+\texpect(actual.length).toBe(expected.length);
+\tfor (let index = 0; index < expected.length; index += 1) {
+\t\tconst actualRect = actual[index];
+\t\tconst expectedRect = expected[index];
+\t\texpect(actualRect.selector).toBe(expectedRect.selector);
+\t\texpect(actualRect.index).toBe(expectedRect.index);
+\t\texpect(actualRect.tagName).toBe(expectedRect.tagName);
+\t\tfor (const key of ["x", "y", "width", "height"]) {
+\t\t\tconst drift = Math.abs(actualRect[key] - expectedRect[key]);
+\t\t\texpect(drift, \`\${expectedRect.selector}[\${expectedRect.index}] \${key} drift\`).toBeLessThanOrEqual(tolerance);
+\t\t}
+\t}
+}
+`;
+}
+function emitComponentVisualSpec(input) {
+	const viewports = JSON.stringify(input.viewports, null, 2);
+	const states = JSON.stringify(input.states, null, 2);
+	const selectors = JSON.stringify(input.assertions.selectors, null, 2);
+	const screenshotEnabled = JSON.stringify(input.assertions.screenshot);
+	const layoutEnabled = JSON.stringify(input.assertions.layout);
+	const layoutTolerance = JSON.stringify(input.assertions.layoutTolerance);
+	const screenshotThreshold = JSON.stringify(input.assertions.screenshotThreshold);
+	const screenshotMaxDiffPixels = JSON.stringify(input.assertions.screenshotMaxDiffPixels);
+	const selector = JSON.stringify(input.selector);
+	return `import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "@playwright/experimental-ct-react";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { ${input.componentName} } from "${input.componentImportPath}";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const referenceHtml = readFileSync(resolve(currentDir, "./${input.referenceHtmlFileName}"), "utf-8");
+const selector = ${selector};
+const viewports = ${viewports};
+const states = ${states};
+const selectors = ${selectors};
+const screenshotEnabled = ${screenshotEnabled};
+const layoutEnabled = ${layoutEnabled};
+const layoutTolerance = ${layoutTolerance};
+const screenshotThreshold = ${screenshotThreshold};
+const screenshotMaxDiffPixels = ${screenshotMaxDiffPixels};
+
+for (const viewport of viewports) {
+\tfor (const state of states) {
+\t\tconst viewportName = viewport.name ?? String(viewport.width) + "x" + String(viewport.height);
+\t\ttest("${input.componentName} matches source at " + viewportName + " / " + state.name, async ({ mount, page }) => {
+\t\t\tawait page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+\t\t\tawait page.setContent(referenceHtml);
+\t\t\tawait applyState(page, state);
+\t\t\tconst expectedEl = page.locator(selector).first();
+\t\t\tconst expectedScreenshot = screenshotEnabled ? await expectedEl.screenshot() : undefined;
+\t\t\tconst expectedLayout = layoutEnabled ? await readLayout(expectedEl, selectors) : [];
+
+\t\t\tconst component = await mount(${input.mountJsx});
+\t\t\tawait applyState(page, state);
+\t\t\tconst actualScreenshot = screenshotEnabled ? await component.screenshot() : undefined;
+\t\t\tconst actualLayout = layoutEnabled ? await readLayout(component, selectors) : [];
+
+\t\t\tif (screenshotEnabled) {
+\t\t\t\tcompareScreenshots(actualScreenshot, expectedScreenshot, screenshotThreshold, screenshotMaxDiffPixels);
+\t\t\t}
+\t\t\tif (layoutEnabled) {
+\t\t\t\texpectLayoutToMatch(actualLayout, expectedLayout, layoutTolerance);
+\t\t\t}
+\t\t});
+\t}
+}
+
+async function applyState(page, state) {
+\tif (state.waitFor) {
+\t\tawait page.waitForSelector(state.waitFor);
+\t}
+\tif (state.hover) {
+\t\tawait page.hover(state.hover);
+\t}
+\tif (state.focus) {
+\t\tawait page.focus(state.focus);
+\t}
+\tif (state.click) {
+\t\tawait page.click(state.click);
+\t}
+}
+
+async function readLayout(root, selectorsToRead) {
+\treturn root.evaluate((element, values) => {
+\t\tconst origin = element.getBoundingClientRect();
+\t\treturn values.flatMap((selector) => {
+\t\t\tconst matches = selector === ":scope" ? [element] : Array.from(element.querySelectorAll(selector));
+\t\t\treturn matches.map((matchedElement, index) => {
+\t\t\t\tconst rect = matchedElement.getBoundingClientRect();
+\t\t\t\treturn {
+\t\t\t\t\tselector,
+\t\t\t\t\tindex,
+\t\t\t\t\ttagName: matchedElement.tagName.toLowerCase(),
+\t\t\t\t\tx: rect.x - origin.x,
+\t\t\t\t\ty: rect.y - origin.y,
+\t\t\t\t\twidth: rect.width,
+\t\t\t\t\theight: rect.height,
+\t\t\t\t};
+\t\t\t});
+\t\t});
+\t}, selectorsToRead);
+}
+
+function compareScreenshots(actual, expected, threshold, maxDiffPixels) {
+\tif (!actual || !expected) {
+\t\texpect(actual).toEqual(expected);
+\t\treturn;
+\t}
+\tconst actualPng = PNG.sync.read(actual);
+\tconst expectedPng = PNG.sync.read(expected);
+\texpect(actualPng.width, "screenshot width").toBe(expectedPng.width);
+\texpect(actualPng.height, "screenshot height").toBe(expectedPng.height);
+\tconst diffPixels = pixelmatch(actualPng.data, expectedPng.data, null, actualPng.width, actualPng.height, { threshold });
+\texpect(diffPixels, "screenshot pixels differing beyond threshold").toBeLessThanOrEqual(maxDiffPixels);
+}
+
+function expectLayoutToMatch(actual, expected, tolerance) {
+\texpect(actual.length).toBe(expected.length);
+\tfor (let index = 0; index < expected.length; index += 1) {
+\t\tconst actualRect = actual[index];
+\t\tconst expectedRect = expected[index];
+\t\texpect(actualRect.selector).toBe(expectedRect.selector);
+\t\texpect(actualRect.index).toBe(expectedRect.index);
+\t\texpect(actualRect.tagName).toBe(expectedRect.tagName);
+\t\tfor (const key of ["x", "y", "width", "height"]) {
+\t\t\tconst drift = Math.abs(actualRect[key] - expectedRect[key]);
+\t\t\texpect(drift, \`\${expectedRect.selector}[\${expectedRect.index}] \${key} drift\`).toBeLessThanOrEqual(tolerance);
+\t\t}
+\t}
+}
+`;
+}
+function emitComponentSplitViews(nodes, viewsDir, cssModulePath) {
+	const seen = /* @__PURE__ */ new Set();
+	const files = [];
+	function visit(node) {
+		if (node.kind === "component") {
+			const importName = node.importName ?? node.component ?? "";
+			const childrenProp = node.props?.children;
+			const innerChildren = childrenProp?.kind === "children" ? childrenProp.value : node.children ?? [];
+			if (importName && !seen.has(importName)) {
+				seen.add(importName);
+				const funcName = toPascalCase(importName);
+				files.push({
+					path: `${viewsDir}/${importName}.view.tsx`,
+					contents: emitComponentView(node, funcName, { cssModulePath })
+				});
+			}
+			for (const child of innerChildren) visit(child);
+		} else if (node.kind === "element") for (const child of node.children ?? []) visit(child);
+	}
+	for (const node of nodes) visit(node);
+	return files;
+}
+/**
+* Emits the implementation of a mapped component. The component reconstructs
+* the original element (tag, attributes, styles) captured in `sourceElement`,
+* exposes the mapping's props as a typed interface, and wires `children` and
+* `$attr.*` props into the rendered element.
+*/
+function emitComponentView(node, funcName, options = {}) {
+	const props = node.props ?? {};
+	const source = node.sourceElement;
+	const propEntries = Object.entries(props);
+	const attributeBindings = /* @__PURE__ */ new Map();
+	const interfaceLines = [];
+	const destructured = [];
+	let childrenPropName;
+	for (const [propName, prop] of propEntries) {
+		if (prop.kind === "text" || prop.kind === "children") {
+			childrenPropName = propName;
+			interfaceLines.push(`\t${propName}?: ReactNode;`);
+			destructured.push(propName);
+			continue;
+		}
+		interfaceLines.push(`\t${propName}?: string;`);
+		if (prop.kind === "literal" && prop.attribute) {
+			attributeBindings.set(prop.attribute, propName);
+			destructured.push(propName);
+		}
+	}
+	const body = emitComponentBody(node, source, attributeBindings, childrenPropName, 2);
+	const componentImports = collectImports(childrenPropName ? [] : node.children ?? []).map(({ importName, importPath }) => `import { ${importName} } from "${importPath}";`).join("\n");
+	const allImports = [
+		childrenPropName ? `import type { ReactNode } from "react";` : "",
+		componentImports,
+		options.cssModulePath ? `import styles from "./${options.cssModulePath}";` : ""
+	].filter(Boolean).join("\n");
+	const interfaceBlock = propEntries.length > 0 ? `interface ${funcName}Props {\n${interfaceLines.join("\n")}\n}\n\n` : "";
+	const params = destructured.length > 0 ? `{ ${destructured.join(", ")} }: ${funcName}Props` : "";
+	return `${allImports ? `${allImports}\n\n` : ""}${interfaceBlock}export function ${funcName}(${params}) {\n\treturn (\n${body}\t);\n}\n`;
+}
+function emitComponentBody(node, source, attributeBindings, childrenPropName, depth) {
+	const indent = "	".repeat(depth);
+	if (!source) return `${indent}<>\n${(node.children ?? []).map((child) => emitJsxNode(child, depth + 1)).join("")}${indent}</>\n`;
+	const tagName = source.tagName ?? "div";
+	const attributes = emitJsxAttributes(source.attributes ?? {}, source.styles ?? {}, source.generatedClassNames ?? [], attributeBindings);
+	const openTag = attributes ? `<${tagName} ${attributes}>` : `<${tagName}>`;
+	if (childrenPropName) return `${indent}${openTag}\n${`${"	".repeat(depth + 1)}{${childrenPropName}}\n`}${indent}</${tagName}>\n`;
+	const children = node.children ?? [];
+	if (children.length === 0) return `${indent}${attributes ? `<${tagName} ${attributes} />` : `<${tagName} />`}\n`;
+	return `${indent}${openTag}\n${children.map((child) => emitJsxNode(child, depth + 1)).join("")}${indent}</${tagName}>\n`;
+}
+/**
+* Walks a mapped AST and returns the first component node seen for each
+* component name, so the test generator can mount components with the same
+* props the design supplies.
+*/
+function collectComponentNodes(nodes) {
+	const map = /* @__PURE__ */ new Map();
+	function visit(list) {
+		for (const node of list) if (node.kind === "component") {
+			const name = node.component ?? node.importName;
+			if (name && !map.has(name)) map.set(name, node);
+			const childrenProp = node.props?.children;
+			visit(childrenProp?.kind === "children" ? childrenProp.value : node.children ?? []);
+		} else if (node.kind === "element") visit(node.children ?? []);
+	}
+	visit(nodes);
+	return map;
+}
+/**
+* Emits the JSX used to mount a component in its visual test, forwarding the
+* literal/attribute props as attributes and the text/children prop as the
+* element body so the rendered component matches the source design.
+*/
+function emitComponentMount(componentName, node) {
+	const attributeParts = [];
+	let childrenJsx = "";
+	for (const [propName, prop] of Object.entries(node?.props ?? {})) {
+		if (prop.kind === "text") {
+			childrenJsx = escapeJsxText(prop.value);
+			continue;
+		}
+		if (prop.kind === "children") {
+			childrenJsx = prop.value.map((child) => emitInlineJsx(child)).join("");
+			continue;
+		}
+		const attribute = emitProp(propName, prop);
+		if (attribute) attributeParts.push(attribute);
+	}
+	const attributes = attributeParts.length > 0 ? ` ${attributeParts.join(" ")}` : "";
+	return childrenJsx ? `<${componentName}${attributes}>${childrenJsx}</${componentName}>` : `<${componentName}${attributes} />`;
+}
+/** Renders a node as single-line JSX for use inside a mount expression. */
+function emitInlineJsx(node) {
+	if (node.kind === "text") return escapeJsxText(node.text ?? "");
+	if (node.kind === "component") return emitComponentMount(node.component ?? node.importName ?? "Component", node);
+	const tagName = node.tagName ?? "div";
+	const attributes = emitJsxAttributes(node.attributes ?? {}, node.styles ?? {}, node.generatedClassNames ?? []);
+	return `${attributes ? `<${tagName} ${attributes}>` : `<${tagName}>`}${(node.children ?? []).map((child) => emitInlineJsx(child)).join("")}</${tagName}>`;
+}
+function findNodeBySelector(nodes, selector) {
+	const parsedSelector = parseSelector(selector);
+	if (!parsedSelector) return void 0;
+	const ps = parsedSelector;
+	function search(list) {
+		for (const node of list) {
+			if (matchesSelector(node, ps)) return node;
+			const found = search(node.children ?? []);
+			if (found) return found;
+		}
+	}
+	return search(nodes);
+}
+const VOID_ELEMENTS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+function serializeNodeToHtml(node) {
+	if (node.kind === "text") return node.text ?? "";
+	if (node.kind !== "element") return "";
+	const tagName = node.tagName ?? "div";
+	const attrs = Object.entries(node.attributes ?? {}).map(([name, value]) => value === "" ? name : `${name}="${value.replace(/"/g, "&quot;")}"`).join(" ");
+	const openTag = attrs ? `<${tagName} ${attrs}>` : `<${tagName}>`;
+	if (VOID_ELEMENTS.has(tagName)) return openTag;
+	return `${openTag}${(node.children ?? []).map(serializeNodeToHtml).join("")}</${tagName}>`;
+}
+function toPascalCase(value) {
+	return value.split(/[-_\s]+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+function toRelativeImport(fromFile, toFile) {
+	const fromParts = fromFile.split("/").slice(0, -1);
+	const toParts = toFile.split("/");
+	while (fromParts.length > 0 && toParts.length > 0 && fromParts[0] === toParts[0]) {
+		fromParts.shift();
+		toParts.shift();
+	}
+	const relative = [...fromParts.map(() => ".."), ...toParts].join("/");
+	return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function emitReactView(nodes, viewName, options = {}) {
+	const allImports = [collectImports(nodes).map(({ importName, importPath }) => `import { ${importName} } from "${importPath}";`).join("\n"), options.cssModulePath ? `import styles from "./${options.cssModulePath}";` : ""].filter(Boolean).join("\n");
+	const body = nodes.length === 1 && nodes[0]?.kind !== "text" ? emitJsxNode(nodes[0], 2) : `${"	".repeat(2)}<>\n${nodes.map((node) => emitJsxNode(node, 3)).join("")}${"	".repeat(2)}</>\n`;
+	return `${allImports ? `${allImports}\n\n` : ""}export function ${viewName}() {\n\treturn (\n${body}\t);\n}\n`;
+}
+function transformStyles(nodes, css, config, diagnostics) {
+	const styleMode = config?.output?.styleMode ?? "inline";
+	const resolvedNodes = resolveCssStyles(nodes, parseCssRules(css, diagnostics));
+	if (styleMode === "inline") return { nodes: mapStyleNodes(resolvedNodes, (node) => ({
+		...node,
+		styles: snapStyleValues(node.styles ?? {}, config, diagnostics, node)
+	})) };
+	if (styleMode === "tailwind") return { nodes: mapStyleNodes(resolvedNodes, (node) => applyTailwindStyles(node, config, diagnostics)) };
+	if (styleMode === "css-modules") {
+		const rules = [];
+		let index = 0;
+		const moduleNodes = mapStyleNodes(resolvedNodes, (node) => {
+			const snapped = snapStyleValues(node.styles ?? {}, config, diagnostics, node);
+			if (Object.keys(snapped).length === 0) return {
+				...node,
+				styles: snapped
+			};
+			index += 1;
+			const className = `style${index}`;
+			rules.push(emitCssModuleRule(className, snapped));
+			return {
+				...node,
+				styles: {},
+				generatedClassNames: [...node.generatedClassNames ?? [], `module:${className}`]
+			};
+		});
+		const viewName = config?.output?.viewName ?? "DesignView";
+		return {
+			nodes: moduleNodes,
+			cssModule: rules.length > 0 ? `${rules.join("\n\n")}\n` : void 0,
+			cssModulePath: rules.length > 0 ? `${viewName}.module.css` : void 0
+		};
+	}
+	diagnostics.push({
+		code: "STYLE_MODE_UNSUPPORTED",
+		message: `Unsupported style mode: ${styleMode}`,
+		severity: "error"
+	});
+	return { nodes: resolvedNodes };
+}
+function parseInlineStyle(style) {
+	const styles = {};
+	if (!style) return styles;
+	for (const declaration of style.split(";")) {
+		const [property, ...valueParts] = declaration.split(":");
+		const value = valueParts.join(":").trim();
+		if (!property?.trim() || !value) continue;
+		styles[property.trim().toLowerCase()] = value;
+	}
+	return styles;
+}
+function parseSelector(selector) {
+	const trimmed = selector.trim();
+	if (!trimmed || /[\s>+~,:]/.test(trimmed)) return;
+	const parsed = {
+		classes: [],
+		attributes: {}
+	};
+	let rest = trimmed;
+	const tagMatch = rest.match(/^[a-zA-Z][a-zA-Z0-9-]*/);
+	if (tagMatch?.[0]) {
+		parsed.tagName = tagMatch[0].toLowerCase();
+		rest = rest.slice(tagMatch[0].length);
+	}
+	while (rest) {
+		if (rest.startsWith(".")) {
+			const match = rest.match(/^\.([a-zA-Z_][a-zA-Z0-9_-]*)/);
+			if (!match?.[1]) return;
+			parsed.classes.push(match[1]);
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		if (rest.startsWith("#")) {
+			const match = rest.match(/^#([a-zA-Z_][a-zA-Z0-9_-]*)/);
+			if (!match?.[1] || parsed.id) return;
+			parsed.id = match[1];
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		if (rest.startsWith("[")) {
+			const match = rest.match(/^\[([a-zA-Z_][a-zA-Z0-9_.:-]*)(?:=(?:"([^"]*)"|'([^']*)'|([^\]]+)))?\]/);
+			if (!match?.[1]) return;
+			parsed.attributes[match[1]] = match[2] ?? match[3] ?? match[4] ?? "";
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		return;
+	}
+	return parsed;
+}
+function matchesSelector(node, selector) {
+	if (node.kind !== "element") return false;
+	const attributes = node.attributes ?? {};
+	if (selector.tagName && node.tagName !== selector.tagName) return false;
+	if (selector.id && attributes.id !== selector.id) return false;
+	const classNames = new Set((attributes.class ?? "").split(/\s+/).filter(Boolean));
+	for (const className of selector.classes) if (!classNames.has(className)) return false;
+	for (const [name, value] of Object.entries(selector.attributes)) {
+		if (!(name in attributes)) return false;
+		if (value !== "" && attributes[name] !== value) return false;
+	}
+	return true;
+}
+function parseCssRules(css, diagnostics) {
+	if (!css?.trim()) return [];
+	const rules = [];
+	let order = 0;
+	for (const match of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+		const selectorText = match[1]?.trim() ?? "";
+		const declarations = parseInlineStyle(match[2]);
+		for (const selector of selectorText.split(",").map((item) => item.trim())) {
+			if (!selector) continue;
+			if (!parseSelector(selector)) {
+				diagnostics.push({
+					code: "CSS_SELECTOR_UNSUPPORTED",
+					message: `Unsupported CSS selector: ${selector}`,
+					severity: "warning",
+					selector
+				});
+				continue;
+			}
+			rules.push({
+				selector,
+				declarations,
+				order
+			});
+			order += 1;
+		}
+	}
+	if (css.replace(/([^{}]+)\{([^{}]*)\}/g, "").trim()) diagnostics.push({
+		code: "CSS_SELECTOR_UNSUPPORTED",
+		message: "Unsupported CSS was ignored.",
+		severity: "warning"
+	});
+	return rules;
+}
+function resolveCssStyles(nodes, rules) {
+	return nodes.map((node) => {
+		if (node.kind !== "element") return node;
+		const matchedDeclarations = rules.filter((rule) => {
+			const selector = parseSelector(rule.selector);
+			return selector ? matchesSelector(node, selector) : false;
+		}).sort((left, right) => left.order - right.order);
+		const stylesFromCss = {};
+		for (const rule of matchedDeclarations) Object.assign(stylesFromCss, rule.declarations);
+		return {
+			...node,
+			styles: {
+				...stylesFromCss,
+				...node.styles ?? {}
+			},
+			children: resolveCssStyles(node.children ?? [], rules)
+		};
+	});
+}
+function mapStyleNodes(nodes, mapper) {
+	return nodes.map((node) => {
+		if (node.kind !== "element") return node;
+		return mapper({
+			...node,
+			children: mapStyleNodes(node.children ?? [], mapper)
+		});
+	});
+}
+function applyTailwindStyles(node, config, diagnostics) {
+	const remaining = {};
+	const generatedClassNames = [...node.generatedClassNames ?? []];
+	for (const [property, value] of sortedEntries(node.styles ?? {})) {
+		const match = matchToken(property, value, config, diagnostics, node);
+		if (!match) {
+			remaining[property] = value;
+			continue;
+		}
+		const className = config?.styleMappings?.[match.group]?.[`${property}:${match.group}.${match.name}`];
+		if (className) generatedClassNames.push(className);
+		else {
+			remaining[property] = match.value;
+			diagnostics.push({
+				code: "TOKEN_NO_MATCH",
+				message: `No Tailwind mapping for ${property}:${match.group}.${match.name}.`,
+				severity: "info",
+				source: node.source,
+				property
+			});
+		}
+	}
+	return {
+		...node,
+		styles: remaining,
+		generatedClassNames
+	};
+}
+function snapStyleValues(styles, config, diagnostics, node) {
+	const snapped = {};
+	for (const [property, value] of sortedEntries(styles)) snapped[property] = matchToken(property, value, config, diagnostics, node)?.value ?? value;
+	return snapped;
+}
+function matchToken(property, value, config, diagnostics, node) {
+	const group = tokenGroupForProperty(property);
+	if (!group) {
+		diagnostics.push({
+			code: "STYLE_UNSUPPORTED_PROPERTY",
+			message: `No token group is configured for CSS property "${property}".`,
+			severity: "info",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	if (group === "colors") return matchColorToken(property, value, config, diagnostics, node);
+	if (group === "shadow") return matchStringToken(property, value, config?.tokens?.shadow, group);
+	return matchNumericToken(property, value, group === "spacing" ? config?.tokens?.spacing?.values : group === "sizing" ? config?.tokens?.sizing?.values : group === "typography" ? config?.tokens?.typography?.values : group === "radius" ? config?.tokens?.radius : config?.tokens?.borderWidth, group, group === "spacing" ? config?.tokens?.spacing?.unit ?? "px" : group === "sizing" ? config?.tokens?.sizing?.unit ?? "px" : group === "typography" ? config?.tokens?.typography?.unit ?? "px" : "px", group === "spacing" ? config?.tokens?.spacing?.threshold ?? 0 : group === "sizing" ? config?.tokens?.sizing?.threshold ?? 0 : group === "typography" ? config?.tokens?.typography?.threshold ?? 0 : 0, diagnostics, node);
+}
+function tokenGroupForProperty(property) {
+	if (/^(margin|padding)(-|$)|^gap$|^row-gap$|^column-gap$/.test(property)) return "spacing";
+	if (/^(width|height|min-width|min-height|max-width|max-height)$/.test(property)) return "sizing";
+	if (/^(font-size|line-height|font-weight)$/.test(property)) return "typography";
+	if (property === "border-radius") return "radius";
+	if (property === "border-width") return "borderWidth";
+	if (property === "box-shadow") return "shadow";
+	if (property === "color" || property === "background" || property === "background-color" || property === "border-color") return "colors";
+}
+function matchNumericToken(property, value, tokens, group, unit, threshold, diagnostics, node) {
+	if (!tokens) return;
+	const parsed = value.match(/^(-?\d+(?:\.\d+)?)(px|rem)?$/);
+	if (!parsed?.[1]) return;
+	const numericValue = Number(parsed[1]);
+	const candidates = sortedEntries(tokens).map(([name, tokenValue]) => ({
+		name,
+		tokenValue,
+		distance: Math.abs(tokenValue - numericValue)
+	})).filter(({ distance }) => distance <= threshold).sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name));
+	if (candidates.length === 0) {
+		diagnostics.push({
+			code: "TOKEN_NO_MATCH",
+			message: `${property}: ${value} did not match a ${group} token.`,
+			severity: "info",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	if (candidates.length > 1 && candidates[0]?.distance === candidates[1]?.distance) {
+		diagnostics.push({
+			code: "TOKEN_AMBIGUOUS_MATCH",
+			message: `${property}: ${value} matches multiple ${group} tokens.`,
+			severity: "error",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	const candidate = candidates[0];
+	if (!candidate) return;
+	return {
+		group,
+		name: candidate.name,
+		value: `${formatNumber(candidate.tokenValue)}${unit}`
+	};
+}
+function matchColorToken(property, value, config, diagnostics, node) {
+	const tokens = config?.tokens?.colors;
+	if (!tokens) return;
+	const color = parseColor(value);
+	if (!color) {
+		diagnostics.push({
+			code: "COLOR_PARSE_FAILED",
+			message: `Could not parse color value: ${value}`,
+			severity: "warning",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	const threshold = config?.tokens?.colorThreshold ?? 0;
+	const candidates = sortedEntries(tokens).map(([name, tokenValue]) => {
+		const tokenColor = parseColor(tokenValue);
+		return tokenColor ? {
+			name,
+			tokenValue,
+			distance: colorDistance(color, tokenColor)
+		} : void 0;
+	}).filter((candidate) => Boolean(candidate && candidate.distance <= threshold)).sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name));
+	if (candidates.length === 0) {
+		diagnostics.push({
+			code: "TOKEN_NO_MATCH",
+			message: `${property}: ${value} did not match a color token.`,
+			severity: "info",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	if (candidates.length > 1 && candidates[0]?.distance === candidates[1]?.distance) {
+		diagnostics.push({
+			code: "TOKEN_AMBIGUOUS_MATCH",
+			message: `${property}: ${value} matches multiple color tokens.`,
+			severity: "error",
+			source: node.source,
+			property
+		});
+		return;
+	}
+	const candidate = candidates[0];
+	if (!candidate) return;
+	return {
+		group: "colors",
+		name: candidate.name,
+		value: normalizeHex(candidate.tokenValue)
+	};
+}
+function matchStringToken(_property, value, tokens, group) {
+	const match = sortedEntries(tokens ?? {}).find(([, tokenValue]) => tokenValue === value);
+	if (!match) return;
+	return {
+		group,
+		name: match[0],
+		value: match[1]
+	};
+}
+function parseColor(value) {
+	const trimmed = value.trim();
+	const hex = trimmed.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+	if (hex?.[1]) {
+		const expanded = hex[1].length === 3 ? hex[1].split("").map((part) => `${part}${part}`).join("") : hex[1];
+		return [
+			Number.parseInt(expanded.slice(0, 2), 16),
+			Number.parseInt(expanded.slice(2, 4), 16),
+			Number.parseInt(expanded.slice(4, 6), 16)
+		];
+	}
+	const rgb = trimmed.match(/^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/i);
+	if (rgb?.[1] && rgb[2] && rgb[3]) return [
+		Number(rgb[1]),
+		Number(rgb[2]),
+		Number(rgb[3])
+	];
+}
+function colorDistance(left, right) {
+	return Math.sqrt((left[0] - right[0]) ** 2 + (left[1] - right[1]) ** 2 + (left[2] - right[2]) ** 2);
+}
+function normalizeHex(value) {
+	const color = parseColor(value);
+	if (!color) return value;
+	return `#${color.map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+}
+function emitCssModuleRule(className, styles) {
+	return `.${className} {\n${sortedEntries(styles).map(([property, value]) => `\t${property}: ${value};`).join("\n")}\n}`;
+}
+function sortedEntries(record) {
+	return Object.entries(record).sort(([left], [right]) => left.localeCompare(right));
+}
+function formatNumber(value) {
+	return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+}
+function collectImports(nodes) {
+	const imports = /* @__PURE__ */ new Map();
+	function visit(node) {
+		if (node.kind === "component" && node.importName && node.importPath) imports.set(`${node.importPath}:${node.importName}`, {
+			importName: node.importName,
+			importPath: node.importPath
+		});
+		for (const child of node.children ?? []) visit(child);
+		for (const prop of Object.values(node.props ?? {})) if (prop.kind === "children") for (const child of prop.value) visit(child);
+	}
+	for (const node of nodes) visit(node);
+	return [...imports.values()].sort((left, right) => left.importPath.localeCompare(right.importPath) || left.importName.localeCompare(right.importName));
+}
+function emitJsxNode(node, depth) {
+	if (!node) return "";
+	const indent = "	".repeat(depth);
+	if (node.kind === "text") return `${indent}${escapeJsxText(node.text ?? "")}\n`;
+	if (node.kind === "component") return emitComponentJsx(node, depth);
+	const tagName = node.tagName ?? "div";
+	const attributes = emitJsxAttributes(node.attributes ?? {}, node.styles ?? {}, node.generatedClassNames ?? []);
+	const children = node.children ?? [];
+	const openTag = attributes ? `<${tagName} ${attributes}>` : `<${tagName}>`;
+	if (children.length === 0) return `${indent}${openTag}</${tagName}>\n`;
+	return `${indent}${openTag}\n${children.map((child) => emitJsxNode(child, depth + 1)).join("")}${indent}</${tagName}>\n`;
+}
+function emitComponentJsx(node, depth) {
+	const indent = "	".repeat(depth);
+	const component = node.component ?? node.importName ?? "Component";
+	const childrenProp = node.props?.children;
+	const attributes = Object.entries(node.props ?? {}).filter(([name]) => name !== "children").sort(([left], [right]) => left.localeCompare(right)).map(([name, prop]) => emitProp(name, prop)).join(" ");
+	const openTag = attributes ? `<${component} ${attributes}>` : `<${component}>`;
+	if (childrenProp?.kind === "text") return `${indent}${openTag}${escapeJsxText(childrenProp.value)}</${component}>\n`;
+	if (childrenProp?.kind === "children") return `${indent}${openTag}\n${childrenProp.value.map((child) => emitJsxNode(child, depth + 1)).join("")}${indent}</${component}>\n`;
+	const children = node.children ?? [];
+	if (children.length === 0) return `${indent}${openTag}</${component}>\n`;
+	return `${indent}${openTag}\n${children.map((child) => emitJsxNode(child, depth + 1)).join("")}${indent}</${component}>\n`;
+}
+function emitProp(name, prop) {
+	if (prop.kind === "children") return "";
+	if (typeof prop.value === "boolean" || typeof prop.value === "number") return `${name}={${JSON.stringify(prop.value)}}`;
+	return `${name}="${escapeAttribute(prop.value)}"`;
+}
+function emitJsxAttributes(attributes, styles, generatedClassNames = [], attributeBindings = /* @__PURE__ */ new Map()) {
+	const mergedAttributes = { ...attributes };
+	const classNames = [...(attributes.class ?? "").split(/\s+/).filter(Boolean), ...generatedClassNames];
+	if (classNames.length > 0) mergedAttributes.class = classNames.join(" ");
+	return Object.entries(mergedAttributes).filter(([name]) => name !== "style").sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => {
+		const jsxName = toJsxAttributeName(name);
+		const binding = attributeBindings.get(name);
+		if (binding) return `${jsxName}={${binding}}`;
+		if (value === "") return jsxName;
+		if (name === "class" && generatedClassNames.some(isCssModuleReference)) return `${jsxName}={${emitClassNameExpression(classNames)}}`;
+		return `${jsxName}="${escapeAttribute(value)}"`;
+	}).concat(emitStyleAttribute(styles)).filter(Boolean).join(" ");
+}
+function emitClassNameExpression(classNames) {
+	return `[${classNames.map((className) => isCssModuleReference(className) ? `styles.${className.slice(7)}` : JSON.stringify(className)).join(", ")}].filter(Boolean).join(" ")`;
+}
+function isCssModuleReference(className) {
+	return className.startsWith("module:");
+}
+function emitStyleAttribute(styles) {
+	const entries = Object.entries(styles).sort(([left], [right]) => left.localeCompare(right));
+	if (entries.length === 0) return [];
+	return [`style={{ ${entries.map(([property, value]) => `${toCamelCase(property)}: ${JSON.stringify(value)}`).join(", ")} }}`];
+}
+function toJsxAttributeName(name) {
+	if (name === "class") return "className";
+	if (name === "for") return "htmlFor";
+	return name;
+}
+function toCamelCase(value) {
+	return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function escapeJsxText(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/{/g, "&#123;").replace(/}/g, "&#125;");
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttribute(value) {
+	return escapeHtml(value).replace(/"/g, "&quot;");
+}
+//#endregion
+export { ReactTarget, emitReactView, reactTestGenerator };