@sit-onyx/figma-utils 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/commands/import-variables.js

@@ -10,7 +10,7 @@ export const importCommand = new Command("import-variables")
     .option("-n, --filename <string>", "Base name of the generated variables file", "variables")
     .option("-d, --dir <string>", "Working directory to use. Defaults to current working directory of the script.")
     .option("-m, --modes <strings...>", "Can be used to only export specific Figma modes. If unset, all modes will be exported as a separate file.")
-    .option("-s, --selector <string>", 'CSS selector to use for the CSS format. The mode name will be added to the selector if it is set to something other than ":root", e.g. for the mode named "dark", passing the selector "html" will result in "html.dark"', ":root")
+    .option("-s, --selector <string>", 'CSS selector to use for the CSS format. You can use {mode} as placeholder for the mode name, so e.g. for the mode named "dark", passing the selector "html.{mode}" will result in "html.dark"', ":root")
     .action(importCommandAction);
 /**
  * Action to run when executing the import action. Only intended to be called manually for testing.

package/dist/utils/generate.d.ts

@@ -10,12 +10,11 @@ export type BaseGenerateOptions = {
 };
 export type GenerateAsCSSOptions = BaseGenerateOptions & {
     /**
-     * Selector to use for the CSS format. The mode name will be added to the selector
-     * if it is set to something other than ":root"
+     * Selector to use for the CSS format. You can use {mode} as placeholder for the mode name.
      *
      * @default ":root"
      * @example
-     * for the mode named "dark", passing the selector "html" will result in "html.dark"
+     * for the mode named "dark", passing the selector "html.{mode}" will result in "html.dark"
      */
     selector?: string;
 };

package/dist/utils/generate.js

@@ -7,9 +7,7 @@
  */
 export const generateAsCSS = (data, options) => {
     const variableContent = getCssOrScssVariableContent(data.variables, (name) => `  --${name}`, (name) => `var(--${name})`, options);
-    let fullSelector = options?.selector?.trim() || ":root";
-    if (fullSelector !== ":root")
-        fullSelector += `.${data.modeName}`;
+    const fullSelector = options?.selector?.trim().replaceAll("{mode}", data.modeName ?? "") || ":root";
     return `${generateTimestampComment(data.modeName)}
 ${fullSelector} {\n${variableContent.join("\n")}\n}\n`;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/figma-utils",
   "description": "Utility functions and CLI for importing data from the Figma API into different formats (e.g. CSS, SCSS etc.)",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "type": "module",
   "bin": {
     "@sit-onyx/figma-utils": "./dist/cli.js"
@@ -12,6 +12,7 @@
   "engines": {
     "node": ">=18"
   },
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/dist/commands/import-variables.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/import-variables.spec.js

@@ -1,49 +0,0 @@
-import fs from "node:fs";
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import * as functions from "../index.js";
-import { importCommandAction } from "./import-variables.js";
-vi.mock("node:fs");
-vi.mock("../index.js");
-describe("import-variables.ts", () => {
-    const mockOptions = {
-        fileKey: "test-file-key",
-        filename: "test-file-name",
-        format: ["CSS"],
-        token: "test-token",
-        selector: ":root",
-    };
-    beforeEach(() => {
-        vi.clearAllMocks();
-        vi.spyOn(console, "log").mockImplementation(() => ({}));
-        vi.spyOn(process, "cwd").mockReturnValue("test-cwd");
-    });
-    test("should throw error for unknown formats", () => {
-        const promise = () => importCommandAction({ ...mockOptions, format: ["does-not-exist"] });
-        expect(promise).rejects.toThrowError('Unknown format "does-not-exist". Supported: CSS, SCSS, JSON');
-    });
-    test("should throw error for unknown modes", () => {
-        vi.spyOn(functions, "parseFigmaVariables").mockReturnValue([
-            { modeName: "test-mode-1", variables: {} },
-        ]);
-        const promise = () => importCommandAction({
-            ...mockOptions,
-            modes: ["test-mode-1", "does-not-exist"],
-        });
-        expect(promise).rejects.toThrowError('Mode "does-not-exist" not found. Available modes: "test-mode-1"');
-    });
-    test("should generate variables", async () => {
-        vi.spyOn(functions, "parseFigmaVariables").mockReturnValue([
-            { modeName: "test-mode-1", variables: {} },
-            { modeName: "test-mode-2", variables: {} },
-            { modeName: "test-mode-3", variables: {} },
-        ]);
-        vi.spyOn(functions, "generateAsCSS").mockReturnValue("mock-css-file-content");
-        await importCommandAction({ ...mockOptions, modes: ["test-mode-1", "test-mode-2"] });
-        expect(functions.fetchFigmaVariables).toHaveBeenCalledOnce();
-        expect(functions.parseFigmaVariables).toHaveBeenCalledOnce();
-        expect(functions.generateAsCSS).toHaveBeenCalledTimes(2);
-        expect(fs.writeFileSync).toHaveBeenCalledTimes(2);
-        expect(fs.writeFileSync).toHaveBeenCalledWith("test-cwd/test-file-name-test-mode-1.css", "mock-css-file-content");
-        expect(fs.writeFileSync).toHaveBeenCalledWith("test-cwd/test-file-name-test-mode-2.css", "mock-css-file-content");
-    });
-});

package/dist/utils/generate.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/utils/generate.spec.js

@@ -1,77 +0,0 @@
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import { generateAsCSS, generateAsJSON, generateAsSCSS } from "./generate.js";
-describe("generate.ts", () => {
-    const mockData = {
-        modeName: "test-mode-1",
-        variables: {
-            "test-1": "#ffffff",
-            "test-2": "1rem",
-            "test-3": "{test-2}",
-        },
-    };
-    beforeEach(() => {
-        vi.setSystemTime(new Date(2024, 0, 7, 13, 42));
-    });
-    test("should generate as CSS", () => {
-        const fileContent = generateAsCSS(mockData);
-        expect(fileContent).toBe(`/**
- * Do not edit directly.
- * This file contains the specific variables for the "test-mode-1" theme.
- * Imported from Figma API on Sun, 07 Jan 2024 13:42:00 GMT
- */
-:root {
-  --test-1: #ffffff;
-  --test-2: 1rem;
-  --test-3: var(--test-2);
-}
-`);
-    });
-    test("should generate as CSS with custom selector", () => {
-        const fileContent = generateAsCSS(mockData, { selector: "html" });
-        expect(fileContent).toBe(`/**
- * Do not edit directly.
- * This file contains the specific variables for the "test-mode-1" theme.
- * Imported from Figma API on Sun, 07 Jan 2024 13:42:00 GMT
- */
-html.test-mode-1 {
-  --test-1: #ffffff;
-  --test-2: 1rem;
-  --test-3: var(--test-2);
-}
-`);
-    });
-    test("should generate as CSS with resolved aliases", () => {
-        const fileContent = generateAsCSS(mockData, { resolveAlias: true });
-        expect(fileContent).toBe(`/**
- * Do not edit directly.
- * This file contains the specific variables for the "test-mode-1" theme.
- * Imported from Figma API on Sun, 07 Jan 2024 13:42:00 GMT
- */
-:root {
-  --test-1: #ffffff;
-  --test-2: 1rem;
-  --test-3: 1rem;
-}
-`);
-    });
-    test("should generate as SCSS", () => {
-        const fileContent = generateAsSCSS(mockData);
-        expect(fileContent).toBe(`/**
- * Do not edit directly.
- * This file contains the specific variables for the "test-mode-1" theme.
- * Imported from Figma API on Sun, 07 Jan 2024 13:42:00 GMT
- */
-$test-1: #ffffff;
-$test-2: 1rem;
-$test-3: $test-2;
-`);
-    });
-    test("should generate as JSON", () => {
-        const fileContent = generateAsJSON(mockData);
-        expect(JSON.parse(fileContent)).toStrictEqual({
-            "test-1": "#ffffff",
-            "test-2": "1rem",
-            "test-3": "1rem",
-        });
-    });
-});

package/dist/utils/parse.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/utils/parse.spec.js

@@ -1,187 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { DEFAULT_MODE_NAME, normalizeVariableName, parseFigmaVariables, resolveFigmaVariableValue, rgbaToHex, } from "./parse.js";
-describe("parse.ts", () => {
-    test("should convert RGBA to hex color", () => {
-        let hex = rgbaToHex({ r: 1, g: 1, b: 1, a: 1 });
-        expect(hex).toBe("#ffffff");
-        hex = rgbaToHex({ r: 1, g: 0, b: 0, a: 1 });
-        expect(hex).toBe("#ff0000");
-        hex = rgbaToHex({ r: 0, g: 1, b: 0, a: 1 });
-        expect(hex).toBe("#00ff00");
-        hex = rgbaToHex({ r: 0, g: 0, b: 1, a: 1 });
-        expect(hex).toBe("#0000ff");
-        hex = rgbaToHex({ r: 0, g: 0, b: 0, a: 0 });
-        expect(hex).toBe("#00000000");
-    });
-    test("should normalize variable name", () => {
-        const name = normalizeVariableName("a/b c+d&e");
-        expect(name).toBe("a-b-c-d-e");
-    });
-    test("should resolve color variable value", () => {
-        const value = { r: 1, g: 1, b: 1, a: 1 };
-        const resolvedValue = resolveFigmaVariableValue(value, {});
-        expect(resolvedValue).toBe("#ffffff");
-    });
-    test("should resolve numeric value and convert to rem", () => {
-        // with default rem base
-        let resolvedValue = resolveFigmaVariableValue(16, {});
-        expect(resolvedValue).toBe("1rem");
-        // with individual rem base
-        resolvedValue = resolveFigmaVariableValue(16, {}, 8);
-        expect(resolvedValue).toBe("2rem");
-        // without rem base (pixel value)
-        resolvedValue = resolveFigmaVariableValue(16, {}, false);
-        expect(resolvedValue).toBe("16px");
-    });
-    test("should resolve alias value", () => {
-        const value = { type: "VARIABLE_ALIAS", id: "test-1" };
-        const allVariables = {
-            "test-1": {
-                hiddenFromPublishing: false,
-                name: "test-variable-1",
-                valuesByMode: {},
-                variableCollectionId: "collection-1",
-            },
-        };
-        const resolvedValue = resolveFigmaVariableValue(value, allVariables);
-        expect(resolvedValue).toBe("{test-variable-1}");
-        // should throw error if alias can not be found
-        expect(() => resolveFigmaVariableValue({ type: "VARIABLE_ALIAS", id: "does-not-exist" }, allVariables)).toThrowError();
-    });
-    test("should parse all Figma variables", () => {
-        const apiResponse = {
-            meta: {
-                variableCollections: {
-                    "collection-1": {
-                        hiddenFromPublishing: false,
-                        defaultModeId: "test-1",
-                        modes: [
-                            { modeId: "test-1", name: "Test 1" },
-                            { modeId: "test-2", name: "Test 2" },
-                            { modeId: "test-3", name: "Test 3" },
-                        ],
-                    },
-                    "collection-2": {
-                        hiddenFromPublishing: false,
-                        defaultModeId: "test-2",
-                        modes: [
-                            { modeId: "test-1", name: "Test 1" },
-                            { modeId: "test-2", name: "Test 2" },
-                            { modeId: "test-3", name: "Test 3" },
-                        ],
-                    },
-                },
-                variables: {
-                    "variable-1": {
-                        hiddenFromPublishing: false,
-                        name: "variable-1",
-                        variableCollectionId: "collection-1",
-                        valuesByMode: {
-                            "test-1": { r: 1, g: 1, b: 1, a: 1 },
-                            "test-2": { type: "VARIABLE_ALIAS", id: "variable-2" },
-                            "test-3": 42,
-                        },
-                    },
-                    "variable-2": {
-                        hiddenFromPublishing: false,
-                        name: "variable-2",
-                        variableCollectionId: "collection-2",
-                        valuesByMode: {
-                            "test-1": { type: "VARIABLE_ALIAS", id: "variable-1" },
-                            "test-2": 42,
-                            "test-3": { r: 1, g: 1, b: 1, a: 1 },
-                        },
-                    },
-                },
-            },
-        };
-        const parsedVariables = parseFigmaVariables(apiResponse);
-        expect(parsedVariables).toStrictEqual([
-            {
-                modeName: "Test 1",
-                variables: {
-                    "variable-1": "#ffffff",
-                    "variable-2": "{variable-1}",
-                },
-            },
-            {
-                modeName: "Test 2",
-                variables: {
-                    "variable-1": "{variable-2}",
-                    "variable-2": "2.625rem",
-                },
-            },
-            {
-                modeName: "Test 3",
-                variables: {
-                    "variable-1": "2.625rem",
-                    "variable-2": "#ffffff",
-                },
-            },
-        ]);
-    });
-    test("should ignore variables/collections that are hidden from publishing", () => {
-        const apiResponse = {
-            meta: {
-                variableCollections: {
-                    "collection-1": {
-                        hiddenFromPublishing: true,
-                        defaultModeId: "test-1",
-                        modes: [{ modeId: "test-1", name: "Test 1" }],
-                    },
-                },
-                variables: {
-                    "variable-1": {
-                        hiddenFromPublishing: true,
-                        name: "variable-1",
-                        variableCollectionId: "collection-1",
-                        valuesByMode: {
-                            "test-1": 42,
-                        },
-                    },
-                    "variable-2": {
-                        hiddenFromPublishing: false,
-                        name: "variable-2",
-                        variableCollectionId: "collection-1",
-                        valuesByMode: {
-                            "test-1": 42,
-                        },
-                    },
-                },
-            },
-        };
-        const parsedVariables = parseFigmaVariables(apiResponse);
-        expect(parsedVariables).toStrictEqual([]);
-    });
-    test("should clear mode name if its the default Figma mode name", () => {
-        const apiResponse = {
-            meta: {
-                variableCollections: {
-                    "collection-1": {
-                        hiddenFromPublishing: false,
-                        defaultModeId: "test-1",
-                        modes: [{ modeId: "test-1", name: DEFAULT_MODE_NAME }],
-                    },
-                },
-                variables: {
-                    "variable-1": {
-                        hiddenFromPublishing: false,
-                        name: "variable-1",
-                        variableCollectionId: "collection-1",
-                        valuesByMode: {
-                            "test-1": 16,
-                        },
-                    },
-                },
-            },
-        };
-        const parsedVariables = parseFigmaVariables(apiResponse);
-        expect(parsedVariables).toStrictEqual([
-            {
-                variables: {
-                    "variable-1": "1rem",
-                },
-            },
-        ]);
-    });
-});