@fragments-sdk/cli 0.2.2

package/src/service/__tests__/figma/figma.test.ts

@@ -0,0 +1,652 @@
+import { describe, it, expect } from "vitest";
+import { FigmaClient, FigmaError } from "../../figma.js";
+import type {
+  FigmaColor,
+  FigmaDesignProperties,
+  FigmaFill,
+  FigmaStroke,
+  FigmaEffect,
+  FigmaTypography,
+} from "../../figma.js";
+
+// Create a client instance for testing (no API calls needed for these tests)
+const client = new FigmaClient({ accessToken: "test-token" });
+
+describe("FigmaClient", () => {
+  describe("colorToCSS", () => {
+    it("converts fully opaque color to hex", () => {
+      const color: FigmaColor = { r: 1, g: 0, b: 0, a: 1 };
+      expect(client.colorToCSS(color)).toBe("#ff0000");
+    });
+
+    it("converts fully opaque white to hex", () => {
+      const color: FigmaColor = { r: 1, g: 1, b: 1, a: 1 };
+      expect(client.colorToCSS(color)).toBe("#ffffff");
+    });
+
+    it("converts fully opaque black to hex", () => {
+      const color: FigmaColor = { r: 0, g: 0, b: 0, a: 1 };
+      expect(client.colorToCSS(color)).toBe("#000000");
+    });
+
+    it("converts semi-transparent color to rgba", () => {
+      const color: FigmaColor = { r: 1, g: 0, b: 0, a: 0.5 };
+      expect(client.colorToCSS(color)).toBe("rgba(255, 0, 0, 0.50)");
+    });
+
+    it("converts fully transparent color to rgba", () => {
+      const color: FigmaColor = { r: 0, g: 0, b: 0, a: 0 };
+      expect(client.colorToCSS(color)).toBe("rgba(0, 0, 0, 0.00)");
+    });
+
+    it("handles fractional RGB values correctly", () => {
+      const color: FigmaColor = { r: 0.2, g: 0.4, b: 0.6, a: 1 };
+      expect(client.colorToCSS(color)).toBe("#336699");
+    });
+
+    it("applies opacity parameter to color alpha", () => {
+      const color: FigmaColor = { r: 1, g: 0, b: 0, a: 1 };
+      expect(client.colorToCSS(color, 0.5)).toBe("rgba(255, 0, 0, 0.50)");
+    });
+
+    it("multiplies opacity parameter with color alpha", () => {
+      const color: FigmaColor = { r: 1, g: 0, b: 0, a: 0.5 };
+      expect(client.colorToCSS(color, 0.5)).toBe("rgba(255, 0, 0, 0.25)");
+    });
+
+    it("handles common design colors", () => {
+      // Figma blue
+      const blue: FigmaColor = { r: 0.2, g: 0.6, b: 1, a: 1 };
+      expect(client.colorToCSS(blue)).toBe("#3399ff");
+
+      // Primary green
+      const green: FigmaColor = { r: 0, g: 0.8, b: 0.4, a: 1 };
+      expect(client.colorToCSS(green)).toBe("#00cc66");
+    });
+  });
+
+  describe("convertToCSS", () => {
+    describe("background color", () => {
+      it("converts solid fill to backgroundColor", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          fills: [{ type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 } }],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.backgroundColor).toBe("#ff0000");
+      });
+
+      it("ignores invisible fills", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          fills: [
+            { type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 }, visible: false },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.backgroundColor).toBeUndefined();
+      });
+
+      it("applies fill opacity", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          fills: [
+            { type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 }, opacity: 0.5 },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.backgroundColor).toBe("rgba(255, 0, 0, 0.50)");
+      });
+
+      it("skips gradient fills", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          fills: [{ type: "GRADIENT_LINEAR" }],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.backgroundColor).toBeUndefined();
+      });
+    });
+
+    describe("border", () => {
+      it("converts stroke to borderColor", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          strokes: [{ type: "SOLID", color: { r: 0, g: 0, b: 0, a: 1 } }],
+          strokeWeight: 2,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.borderColor).toBe("#000000");
+        expect(css.borderWidth).toBe("2px");
+      });
+
+      it("ignores invisible strokes", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          strokes: [
+            {
+              type: "SOLID",
+              color: { r: 0, g: 0, b: 0, a: 1 },
+              visible: false,
+            },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.borderColor).toBeUndefined();
+      });
+    });
+
+    describe("border radius", () => {
+      it("converts uniform cornerRadius", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          cornerRadius: 8,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.borderRadius).toBe("8px");
+      });
+
+      it("converts individual corner radii", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          topLeftRadius: 4,
+          topRightRadius: 8,
+          bottomRightRadius: 12,
+          bottomLeftRadius: 16,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.borderRadius).toBe("4px 8px 12px 16px");
+      });
+
+      it("handles mixed undefined corner radii", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          topLeftRadius: 4,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.borderRadius).toBe("4px 0px 0px 0px");
+      });
+    });
+
+    describe("box shadow", () => {
+      it("converts drop shadow to boxShadow", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Card",
+          type: "FRAME",
+          effects: [
+            {
+              type: "DROP_SHADOW",
+              color: { r: 0, g: 0, b: 0, a: 0.25 },
+              offset: { x: 0, y: 4 },
+              radius: 8,
+              spread: 0,
+            },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.boxShadow).toBe("0px 4px 8px 0px rgba(0, 0, 0, 0.25)");
+      });
+
+      it("combines multiple shadows", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Card",
+          type: "FRAME",
+          effects: [
+            {
+              type: "DROP_SHADOW",
+              color: { r: 0, g: 0, b: 0, a: 0.1 },
+              offset: { x: 0, y: 2 },
+              radius: 4,
+              spread: 0,
+            },
+            {
+              type: "DROP_SHADOW",
+              color: { r: 0, g: 0, b: 0, a: 0.2 },
+              offset: { x: 0, y: 8 },
+              radius: 16,
+              spread: 0,
+            },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        // Should have two shadows separated by ", " after the rgba()
+        expect(css.boxShadow).toMatch(/rgba\([^)]+\), 0px 8px/);
+        // Count occurrences of "px rgba" to verify two shadows
+        const matches = css.boxShadow?.match(/px rgba/g);
+        expect(matches).toHaveLength(2);
+      });
+
+      it("ignores invisible effects", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Card",
+          type: "FRAME",
+          effects: [
+            {
+              type: "DROP_SHADOW",
+              color: { r: 0, g: 0, b: 0, a: 0.25 },
+              offset: { x: 0, y: 4 },
+              radius: 8,
+              visible: false,
+            },
+          ],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.boxShadow).toBeUndefined();
+      });
+
+      it("ignores blur effects", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Card",
+          type: "FRAME",
+          effects: [{ type: "LAYER_BLUR", radius: 8 }],
+        };
+        const css = client.convertToCSS(props);
+        expect(css.boxShadow).toBeUndefined();
+      });
+    });
+
+    describe("typography", () => {
+      it("converts font family and size", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Text",
+          type: "TEXT",
+          typography: {
+            fontFamily: "Inter",
+            fontStyle: "Regular",
+            fontSize: 16,
+          },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.fontFamily).toBe("Inter");
+        expect(css.fontSize).toBe("16px");
+        expect(css.fontWeight).toBe("400");
+      });
+
+      it("converts font weight from style name", () => {
+        const weights: Array<[string, string]> = [
+          ["Thin", "100"],
+          ["ExtraLight", "200"],
+          ["Light", "300"],
+          ["Regular", "400"],
+          ["Medium", "500"],
+          ["SemiBold", "600"],
+          ["Bold", "700"],
+          ["ExtraBold", "800"],
+          ["Black", "900"],
+        ];
+
+        for (const [style, weight] of weights) {
+          const props: FigmaDesignProperties = {
+            nodeId: "1:2",
+            name: "Text",
+            type: "TEXT",
+            typography: {
+              fontFamily: "Inter",
+              fontStyle: style,
+              fontSize: 16,
+            },
+          };
+          const css = client.convertToCSS(props);
+          expect(css.fontWeight).toBe(weight);
+        }
+      });
+
+      it("defaults to 400 for unknown font style", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Text",
+          type: "TEXT",
+          typography: {
+            fontFamily: "Inter",
+            fontStyle: "Custom",
+            fontSize: 16,
+          },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.fontWeight).toBe("400");
+      });
+
+      it("converts pixel line height", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Text",
+          type: "TEXT",
+          typography: {
+            fontFamily: "Inter",
+            fontStyle: "Regular",
+            fontSize: 16,
+            lineHeight: { value: 24, unit: "PIXELS" },
+          },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.lineHeight).toBe("24px");
+      });
+
+      it("converts percent line height", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Text",
+          type: "TEXT",
+          typography: {
+            fontFamily: "Inter",
+            fontStyle: "Regular",
+            fontSize: 16,
+            lineHeight: { value: 150, unit: "PERCENT" },
+          },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.lineHeight).toBe("150%");
+      });
+
+      it("converts letter spacing", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Text",
+          type: "TEXT",
+          typography: {
+            fontFamily: "Inter",
+            fontStyle: "Regular",
+            fontSize: 16,
+            letterSpacing: -0.5,
+          },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.letterSpacing).toBe("-0.5px");
+      });
+
+      it("converts text alignment", () => {
+        const alignments: Array<
+          ["LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED", string]
+        > = [
+          ["LEFT", "left"],
+          ["CENTER", "center"],
+          ["RIGHT", "right"],
+          ["JUSTIFIED", "justified"],
+        ];
+
+        for (const [figmaAlign, cssAlign] of alignments) {
+          const props: FigmaDesignProperties = {
+            nodeId: "1:2",
+            name: "Text",
+            type: "TEXT",
+            typography: {
+              fontFamily: "Inter",
+              fontStyle: "Regular",
+              fontSize: 16,
+              textAlignHorizontal: figmaAlign,
+            },
+          };
+          const css = client.convertToCSS(props);
+          expect(css.textAlign).toBe(cssAlign);
+        }
+      });
+    });
+
+    describe("padding", () => {
+      it("converts uniform padding", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          padding: { top: 16, right: 16, bottom: 16, left: 16 },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.padding).toBe("16px");
+      });
+
+      it("converts symmetric padding (vertical/horizontal)", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          padding: { top: 8, right: 16, bottom: 8, left: 16 },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.padding).toBe("8px 16px");
+      });
+
+      it("converts asymmetric padding", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          padding: { top: 4, right: 8, bottom: 12, left: 16 },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.padding).toBe("4px 8px 12px 16px");
+      });
+
+      it("handles missing padding values", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Button",
+          type: "FRAME",
+          padding: { top: 8 },
+        };
+        const css = client.convertToCSS(props);
+        expect(css.padding).toBe("8px 0px 0px 0px");
+      });
+    });
+
+    describe("gap", () => {
+      it("converts itemSpacing to gap", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Stack",
+          type: "FRAME",
+          itemSpacing: 16,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.gap).toBe("16px");
+      });
+    });
+
+    describe("opacity", () => {
+      it("converts opacity when not 1", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Overlay",
+          type: "FRAME",
+          opacity: 0.75,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.opacity).toBe("0.75");
+      });
+
+      it("does not include opacity when 1", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Overlay",
+          type: "FRAME",
+          opacity: 1,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.opacity).toBeUndefined();
+      });
+    });
+
+    describe("dimensions", () => {
+      it("converts width and height", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Box",
+          type: "FRAME",
+          width: 200,
+          height: 100,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.width).toBe("200px");
+        expect(css.height).toBe("100px");
+      });
+
+      it("rounds dimensions to whole pixels", () => {
+        const props: FigmaDesignProperties = {
+          nodeId: "1:2",
+          name: "Box",
+          type: "FRAME",
+          width: 199.7,
+          height: 100.2,
+        };
+        const css = client.convertToCSS(props);
+        expect(css.width).toBe("200px");
+        expect(css.height).toBe("100px");
+      });
+    });
+  });
+
+  describe("parseVariantName", () => {
+    it("parses single property", () => {
+      const result = client.parseVariantName("Size=Medium");
+      expect(result).toEqual({ Size: "Medium" });
+    });
+
+    it("parses multiple properties", () => {
+      const result = client.parseVariantName("State=Primary, Size=Medium");
+      expect(result).toEqual({ State: "Primary", Size: "Medium" });
+    });
+
+    it("handles extra spaces", () => {
+      const result = client.parseVariantName(
+        "State = Primary ,  Size = Medium"
+      );
+      expect(result).toEqual({ State: "Primary", Size: "Medium" });
+    });
+
+    it("handles boolean-like values", () => {
+      const result = client.parseVariantName("Disabled=true, Loading=false");
+      expect(result).toEqual({ Disabled: "true", Loading: "false" });
+    });
+
+    it("handles complex variant names", () => {
+      const result = client.parseVariantName(
+        "Type=Primary, Size=Large, State=Hover, Disabled=false"
+      );
+      expect(result).toEqual({
+        Type: "Primary",
+        Size: "Large",
+        State: "Hover",
+        Disabled: "false",
+      });
+    });
+
+    it("returns empty object for invalid format", () => {
+      const result = client.parseVariantName("InvalidFormat");
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("parseUrl", () => {
+    it("parses file URL with node-id", () => {
+      const result = client.parseUrl(
+        "https://figma.com/file/abc123/MyDesign?node-id=1:2"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: "1:2" });
+    });
+
+    it("parses design URL format", () => {
+      const result = client.parseUrl(
+        "https://figma.com/design/xyz789/Components?node-id=10:20"
+      );
+      expect(result).toEqual({ fileKey: "xyz789", nodeId: "10:20" });
+    });
+
+    it("handles URL-encoded node IDs", () => {
+      const result = client.parseUrl(
+        "https://figma.com/file/abc123/MyDesign?node-id=1%3A2"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: "1:2" });
+    });
+
+    it("handles www prefix", () => {
+      const result = client.parseUrl(
+        "https://www.figma.com/file/abc123/MyDesign?node-id=1:2"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: "1:2" });
+    });
+
+    it("handles dash-style node IDs", () => {
+      const result = client.parseUrl(
+        "https://figma.com/design/abc123/MyDesign?node-id=1-2"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: "1-2" });
+    });
+
+    it("throws FigmaError for invalid URL", () => {
+      expect(() => client.parseUrl("https://example.com/invalid")).toThrow(
+        FigmaError
+      );
+    });
+
+    it("throws FigmaError for URL without node-id", () => {
+      expect(() =>
+        client.parseUrl("https://figma.com/file/abc123/MyDesign")
+      ).toThrow(FigmaError);
+    });
+  });
+
+  describe("parseFileUrl", () => {
+    it("parses file URL without node-id", () => {
+      const result = client.parseFileUrl(
+        "https://figma.com/file/abc123/MyDesign"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: undefined });
+    });
+
+    it("parses file URL with node-id", () => {
+      const result = client.parseFileUrl(
+        "https://figma.com/file/abc123/MyDesign?node-id=1:2"
+      );
+      expect(result).toEqual({ fileKey: "abc123", nodeId: "1:2" });
+    });
+
+    it("throws FigmaError for invalid URL", () => {
+      expect(() =>
+        client.parseFileUrl("https://example.com/invalid")
+      ).toThrow(FigmaError);
+    });
+  });
+
+  describe("buildNodeUrl", () => {
+    it("builds URL with file name", () => {
+      const url = client.buildNodeUrl("abc123", "1:2", "My Design");
+      expect(url).toBe(
+        "https://www.figma.com/design/abc123/My-Design?node-id=1%3A2"
+      );
+    });
+
+    it("builds URL without file name", () => {
+      const url = client.buildNodeUrl("abc123", "1:2");
+      expect(url).toBe(
+        "https://www.figma.com/design/abc123/Design?node-id=1%3A2"
+      );
+    });
+
+    it("URL-encodes the node ID", () => {
+      const url = client.buildNodeUrl("abc123", "10:20", "Test");
+      expect(url).toContain("node-id=10%3A20");
+    });
+  });
+});