@design-embed/plugin-figma-html 0.1.0

package/src/external/imageDownloader.ts

@@ -0,0 +1,136 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { FigmaNode } from "../types.ts";
+import type { FigmaFetcher } from "./figmaApi.ts";
+
+export interface DownloadFigmaImagesOptions {
+	fetcher?: FigmaFetcher;
+	publicPath?: string;
+}
+
+export interface DownloadedFigmaImage {
+	imageRef: string;
+	sourceUrl: string;
+	filePath: string;
+	publicPath: string;
+}
+
+interface ImageFillTarget {
+	imageRef: string;
+	imageUrl: string;
+	fills: NonNullable<FigmaNode["fills"]>;
+	fillIndex: number;
+}
+
+export async function downloadFigmaImageFills(
+	rootNode: FigmaNode,
+	outDir: string,
+	options: DownloadFigmaImagesOptions = {},
+): Promise<DownloadedFigmaImage[]> {
+	const targets = collectImageFillTargets(rootNode);
+	const uniqueTargets = Array.from(
+		new Map(targets.map((target) => [target.imageRef, target])).values(),
+	);
+
+	if (uniqueTargets.length === 0) return [];
+
+	mkdirSync(outDir, { recursive: true });
+
+	const downloadedImages = await Promise.all(
+		uniqueTargets.map((target) => downloadImageFill(target, outDir, options)),
+	);
+	const publicPathByRef = new Map(
+		downloadedImages.map((image) => [image.imageRef, image.publicPath]),
+	);
+
+	for (const target of targets) {
+		const fill = target.fills[target.fillIndex];
+		if (fill) {
+			fill.imageLocalPath = publicPathByRef.get(target.imageRef);
+		}
+	}
+
+	return downloadedImages;
+}
+
+function collectImageFillTargets(node: FigmaNode): ImageFillTarget[] {
+	const targets: ImageFillTarget[] = [];
+
+	node.fills?.forEach((fill, fillIndex, fills) => {
+		if (fill.type === "IMAGE" && fill.imageRef && fill.imageUrl) {
+			targets.push({
+				imageRef: fill.imageRef,
+				imageUrl: fill.imageUrl,
+				fills,
+				fillIndex,
+			});
+		}
+	});
+
+	for (const child of node.children || []) {
+		targets.push(...collectImageFillTargets(child));
+	}
+
+	return targets;
+}
+
+async function downloadImageFill(
+	target: ImageFillTarget,
+	outDir: string,
+	options: DownloadFigmaImagesOptions,
+): Promise<DownloadedFigmaImage> {
+	const fetcher = options.fetcher ?? fetch;
+	const response = await fetcher(target.imageUrl);
+
+	if (!response.ok) {
+		throw new Error(
+			`Figma image download failed for ${target.imageRef}: ${response.status} ${response.statusText}`,
+		);
+	}
+
+	const extension = extensionFromResponse(response, target.imageUrl);
+	const filename = `${sanitizeFilename(target.imageRef)}.${extension}`;
+	const filePath = join(outDir, filename);
+	const publicPath = posix.join(options.publicPath || outDir, filename);
+
+	writeFileSync(filePath, Buffer.from(await response.arrayBuffer()));
+
+	return {
+		imageRef: target.imageRef,
+		sourceUrl: target.imageUrl,
+		filePath,
+		publicPath,
+	};
+}
+
+function extensionFromResponse(response: Response, url: string): string {
+	const contentType = response.headers.get("content-type")?.split(";")[0];
+	switch (contentType) {
+		case "image/jpeg":
+			return "jpg";
+		case "image/png":
+			return "png";
+		case "image/svg+xml":
+			return "svg";
+		case "image/webp":
+			return "webp";
+		case "image/gif":
+			return "gif";
+	}
+
+	const pathname = safeUrlPathname(url);
+	const extension = pathname.match(/\.([a-z0-9]+)$/i)?.[1]?.toLowerCase();
+	return extension || "img";
+}
+
+function safeUrlPathname(url: string): string {
+	try {
+		return new URL(url).pathname;
+	} catch {
+		return url;
+	}
+}
+
+function sanitizeFilename(value: string): string {
+	return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export {
+	compileHtml,
+	compileReact,
+	compileVanjs,
+	getCompiler,
+	isCompilerMode,
+} from "./compilers/index.ts";
+export type {
+	FigmaApiResponse,
+	FigmaClientOptions,
+	FigmaFetcher,
+} from "./external/figmaApi.ts";
+export {
+	extractParamsFromURL,
+	fetchFigmaApiResponse,
+	fetchFigmaNode,
+} from "./external/figmaApi.ts";
+export type { FigmaHtmlPluginOptions } from "./plugin.ts";
+export { FigmaHtmlPlugin } from "./plugin.ts";
+export type {
+	CompilerMode,
+	ExtractedParams,
+	FigmaCompiler,
+	FigmaNode,
+	GeneratedFile,
+} from "./types.ts";

package/src/plugin.ts

@@ -0,0 +1,76 @@
+import { join } from "node:path";
+import type { PluginDefinition } from "@design-embed/config";
+import type {
+	SourcePlugin,
+	SourcePluginInput,
+	SourcePluginResult,
+} from "@design-embed/core";
+import { compileHtml } from "./compilers/index.ts";
+import { extractParamsFromURL, fetchFigmaNode } from "./external/figmaApi.ts";
+import { downloadFigmaImageFills } from "./external/imageDownloader.ts";
+
+export interface FigmaHtmlPluginOptions {
+	url: string;
+	token?: string;
+	assetsDir?: string;
+}
+
+export class FigmaHtmlPlugin implements PluginDefinition, SourcePlugin {
+	readonly name = "figma-html";
+
+	constructor(private readonly options: FigmaHtmlPluginOptions) {}
+
+	async run(input: SourcePluginInput): Promise<SourcePluginResult> {
+		const { url, token: optionsToken, assetsDir = "assets" } = this.options;
+		const token = optionsToken ?? process.env.FIGMA_TOKEN;
+
+		if (!token) {
+			return {
+				diagnostics: [
+					{
+						code: "FIGMA_TOKEN_REQUIRED",
+						message:
+							"figma-html requires a Figma token. Pass token in the FigmaHtmlPlugin constructor or set the FIGMA_TOKEN environment variable.",
+						severity: "error",
+					},
+				],
+			};
+		}
+
+		try {
+			const { fileKey, nodeId } = extractParamsFromURL(url);
+			const rootNode = await fetchFigmaNode(fileKey, nodeId, { token });
+			const downloadedImages = await downloadFigmaImageFills(
+				rootNode,
+				join(input.cwd, assetsDir),
+				{ publicPath: assetsDir },
+			);
+			const [htmlFile] = compileHtml(rootNode);
+
+			return {
+				html: htmlFile?.contents,
+				diagnostics:
+					downloadedImages.length > 0
+						? [
+								{
+									code: "FIGMA_ASSETS_DOWNLOADED",
+									message: `Downloaded ${downloadedImages.length} image asset(s).`,
+									severity: "info",
+								},
+							]
+						: [],
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				diagnostics: [
+					{
+						code: "FIGMA_HTML_FAILED",
+						message,
+						severity: "error",
+					},
+				],
+			};
+		}
+	}
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+export interface ExtractedParams {
+	fileKey: string;
+	nodeId: string | null;
+}
+
+export interface FigmaNode {
+	id?: string;
+	name?: string;
+	type?: string;
+	visible?: boolean;
+	characters?: string;
+	children?: FigmaNode[];
+	layoutMode?: "NONE" | "HORIZONTAL" | "VERTICAL" | "GRID" | string;
+	layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL" | string;
+	layoutSizingVertical?: "FIXED" | "HUG" | "FILL" | string;
+	layoutWrap?: "NO_WRAP" | "WRAP" | string;
+	primaryAxisSizingMode?: "FIXED" | "AUTO" | string;
+	counterAxisSizingMode?: "FIXED" | "AUTO" | string;
+	primaryAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "SPACE_BETWEEN" | string;
+	counterAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "BASELINE" | string;
+	layoutPositioning?: "ABSOLUTE" | "AUTO" | string;
+	layoutAlign?: "INHERIT" | "STRETCH" | "MIN" | "CENTER" | "MAX" | string;
+	layoutGrow?: number;
+	itemSpacing?: number;
+	counterAxisSpacing?: number;
+	gridRowGap?: number;
+	gridColumnGap?: number;
+	gridColumnsSizing?: string;
+	gridRowsSizing?: string;
+	gridColumnSpan?: number;
+	gridRowSpan?: number;
+	paddingTop?: number;
+	paddingBottom?: number;
+	paddingLeft?: number;
+	paddingRight?: number;
+	absoluteBoundingBox?: {
+		x?: number;
+		y?: number;
+		width?: number;
+		height?: number;
+	};
+	fills?: Array<{
+		type?: string;
+		opacity?: number;
+		scaleMode?: string;
+		imageRef?: string;
+		imageUrl?: string;
+		imageLocalPath?: string;
+		color?: {
+			r: number;
+			g: number;
+			b: number;
+		};
+	}>;
+	cornerRadius?: number;
+	rectangleCornerRadii?: number[];
+	strokes?: Array<{
+		type?: string;
+		opacity?: number;
+		color?: {
+			r: number;
+			g: number;
+			b: number;
+		};
+	}>;
+	strokeWeight?: number;
+	strokeAlign?: "INSIDE" | "OUTSIDE" | "CENTER" | string;
+	opacity?: number;
+	clipsContent?: boolean;
+	style?: {
+		fontSize?: number;
+		fontWeight?: number | string;
+		fontFamily?: string;
+		lineHeightPx?: number;
+	};
+}
+
+export interface GeneratedFile {
+	path: string;
+	contents: string;
+}
+
+export type CompilerMode = "react" | "html" | "vanjs";
+
+export type FigmaCompiler = (node: FigmaNode) => GeneratedFile[];