@sit-onyx/figma-utils 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -1,9 +1,5 @@
 <div align="center" style="text-align: center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-light.svg">
-    <source media="(prefers-color-scheme: light)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg">
-    <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg" width="160px">
-  </picture>
+  <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo.svg" height="96px">
 </div>
 
 <br>

package/dist/cli.js

@@ -2,11 +2,12 @@
 import { Command } from "commander";
 import fs from "node:fs";
 import { fileURLToPath, URL } from "node:url";
+import { importFlagsCommand } from "./commands/import-flags.js";
 import { importIconsCommand } from "./commands/import-icons.js";
 import { importVariablesCommand } from "./commands/import-variables.js";
 const packageJson = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
 const cli = new Command();
 cli.version(packageJson.version, "-v, --version").description(packageJson.description);
-const availableCommands = [importVariablesCommand, importIconsCommand];
+const availableCommands = [importVariablesCommand, importIconsCommand, importFlagsCommand];
 availableCommands.forEach((command) => cli.addCommand(command));
 cli.parse();

package/dist/commands/import-flags.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+export type ImportFlagsCommandOptions = {
+    fileKey: string;
+    token: string;
+    pageId: string;
+    dir?: string;
+    metaFile?: string;
+};
+export declare const importFlagsCommand: Command;
+/**
+ * Action to run when executing the import action. Only intended to be called manually for testing.
+ */
+export declare function importFlagsCommandAction(options: ImportFlagsCommandOptions): Promise<void>;

package/dist/commands/import-flags.js

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeFlagMetadata } from "../flags/generate.js";
+import { parseComponentsToFlags } from "../flags/parse.js";
+import { fetchFigmaComponents, fetchFigmaSVGs } from "../index.js";
+import { optimizeSvg } from "../utils/optimize.js";
+export const importFlagsCommand = new Command("import-flags")
+    .description("CLI tool to import SVG flags from Figma.")
+    .requiredOption("-k, --file-key <string>", "Figma file key (required)")
+    .requiredOption("-t, --token <string>", "Figma access token with scope `file_read` or `files:read` (required)")
+    .requiredOption("-p, --page-id <string>", "Figma page ID that contains the flags (required)")
+    .option("-d, --dir <string>", "Directory to save the flags to. Defaults to current working directory of the script.")
+    .option("-m, --meta-file <string>", 'JSON filename/path to write flag metadata to (country name etc.). Must end with ".json". If unset, no metadata will be generated.')
+    .action(importFlagsCommandAction);
+/**
+ * Action to run when executing the import action. Only intended to be called manually for testing.
+ */
+export async function importFlagsCommandAction(options) {
+    console.log("Fetching components from Figma API...");
+    const data = await fetchFigmaComponents(options.fileKey, options.token);
+    console.log("Parsing Figma flags...");
+    const parsedFlags = parseComponentsToFlags({
+        components: data.meta.components,
+        pageId: options.pageId,
+    });
+    const outputDirectory = options.dir ?? process.cwd();
+    console.log(`Fetching SVG content for ${parsedFlags.length} flags...`);
+    const svgContents = await fetchFigmaSVGs(options.fileKey, parsedFlags.map(({ id }) => id), options.token);
+    console.log("Optimizing and writing flag files...");
+    await mkdir(outputDirectory, { recursive: true });
+    await Promise.all(parsedFlags.map((flag) => {
+        const content = optimizeSvg(svgContents[flag.id], "image");
+        const fullPath = path.join(outputDirectory, `${flag.code}.svg`);
+        return writeFile(fullPath, content, "utf-8");
+    }));
+    if (options.metaFile) {
+        console.log("Writing flag metadata...");
+        await writeFlagMetadata(options.metaFile, parsedFlags);
+    }
+    console.log("Done.");
+}

package/dist/commands/import-icons.js

@@ -2,10 +2,9 @@ import { Command } from "commander";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { writeIconMetadata } from "../icons/generate.js";
-import { optimizeSvg } from "../icons/optimize.js";
 import { parseComponentsToIcons } from "../icons/parse.js";
 import { fetchFigmaComponents, fetchFigmaSVGs } from "../index.js";
-import { isDirectory } from "../utils/fs.js";
+import { optimizeSvg } from "../utils/optimize.js";
 export const importIconsCommand = new Command("import-icons")
     .description("CLI tool to import SVG icons from Figma.")
     .requiredOption("-k, --file-key <string>", "Figma file key (required)")
@@ -31,9 +30,7 @@ export async function importIconsCommandAction(options) {
     console.log(`Fetching SVG content for ${parsedIcons.length} icons...`);
     const svgContents = await fetchFigmaSVGs(options.fileKey, parsedIcons.map(({ id }) => id), options.token);
     console.log("Optimizing and writing icon files...");
-    if (!(await isDirectory(outputDirectory))) {
-        await mkdir(outputDirectory, { recursive: true });
-    }
+    await mkdir(outputDirectory, { recursive: true });
     await Promise.all(parsedIcons.map((icon) => {
         const content = optimizeSvg(svgContents[icon.id]);
         const fullPath = path.join(outputDirectory, `${icon.name}.svg`);

package/dist/flags/generate.d.ts

@@ -0,0 +1,8 @@
+import { ParsedFlag } from "../types/figma.js";
+/**
+ * Writes a JSON file with metadata of the given flags (code, name etc.).
+ *
+ * @param path File path of the .json file, e.g. "./metadata.json"
+ * @param flags Flags to write metadata for
+ */
+export declare const writeFlagMetadata: (path: string, flags: ParsedFlag[]) => Promise<void>;

package/dist/flags/generate.js

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * Writes a JSON file with metadata of the given flags (code, name etc.).
+ *
+ * @param path File path of the .json file, e.g. "./metadata.json"
+ * @param flags Flags to write metadata for
+ */
+export const writeFlagMetadata = async (path, flags) => {
+    const metaDirname = dirname(path);
+    await mkdir(metaDirname, { recursive: true });
+    const flagMetadata = flags.reduce((meta, flag) => {
+        const { id: _id, code, ...rest } = flag;
+        meta[code] = rest;
+        return meta;
+    }, {});
+    await writeFile(path, JSON.stringify(flagMetadata, null, 2), "utf-8");
+};

package/dist/flags/parse.d.ts

@@ -0,0 +1,12 @@
+import { Component, ParsedFlag } from "../types/figma.js";
+export type ParseFlagComponentsOptions = {
+    /**
+     * Available Figma components.
+     */
+    components: Component[];
+    /**
+     * Page ID that contains all flags. Components will be filtered accordingly.
+     */
+    pageId: string;
+};
+export declare const parseComponentsToFlags: (options: ParseFlagComponentsOptions) => ParsedFlag[];

package/dist/flags/parse.js

@@ -0,0 +1,34 @@
+/**
+ * Map of country names for country codes that are not (yet) supported by `Intl.DisplayNames`.
+ */
+const UNKNOWN_COUNTRY_NAMES = {
+    "CA-BC": "British Columbia",
+    "GB-ENG": "England",
+    "GB-SCT": "Scotland",
+    "GB-WLS": "Wales",
+    "US-HI": "Hawaii",
+};
+export const parseComponentsToFlags = (options) => {
+    const pageComponents = options.components.filter(({ containing_frame }) => containing_frame.pageId === options.pageId);
+    const countryCodeFormatter = new Intl.DisplayNames("en", { type: "region" });
+    return (pageComponents
+        .map((component) => {
+        const code = component.description.trim();
+        let internationalName = UNKNOWN_COUNTRY_NAMES[code] ?? "";
+        try {
+            internationalName = countryCodeFormatter.of(code) || internationalName;
+        }
+        catch {
+            // noop
+        }
+        return {
+            id: component.node_id,
+            code,
+            continent: component.containing_frame.name.trim(),
+            internationalName,
+        };
+    })
+        // remove invalid flags without a country code
+        .filter(({ code }) => code)
+        .sort((a, b) => a.code.localeCompare(b.code)));
+};

package/dist/icons/generate.js

@@ -1,6 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { isDirectory } from "../utils/fs.js";
 /**
  * Writes a JSON file with metadata of the given icons (category, aliases etc.).
  *
@@ -9,14 +8,10 @@ import { isDirectory } from "../utils/fs.js";
  */
 export const writeIconMetadata = async (path, icons) => {
     const metaDirname = dirname(path);
-    if (!(await isDirectory(metaDirname))) {
-        await mkdir(metaDirname, { recursive: true });
-    }
+    await mkdir(metaDirname, { recursive: true });
     const iconMetadata = icons.reduce((meta, icon) => {
-        meta[icon.name] = {
-            category: icon.category,
-            aliases: icon.aliases,
-        };
+        const { id: _id, name, ...rest } = icon;
+        meta[name] = rest;
         return meta;
     }, {});
     await writeFile(path, JSON.stringify(iconMetadata, null, 2), "utf-8");

package/dist/icons/parse.js

@@ -5,11 +5,11 @@ export const parseComponentsToIcons = (options) => {
         return {
             id: component.node_id,
             name: component.name,
+            category: component.containing_frame.name.trim(),
             aliases: component.description
                 .split(options.aliasSeparator ?? ",")
                 .map((alias) => alias.trim())
                 .filter((i) => i !== ""),
-            category: component.containing_frame.name.trim(),
         };
     })
         .sort((a, b) => a.name.localeCompare(b.name));

package/dist/index.d.ts

@@ -1,7 +1,9 @@
+export * from "./flags/generate.js";
+export * from "./flags/parse.js";
 export * from "./icons/generate.js";
-export * from "./icons/optimize.js";
 export * from "./icons/parse.js";
 export * from "./types/figma.js";
 export * from "./utils/fetch.js";
+export * from "./utils/optimize.js";
 export * from "./variables/generate.js";
 export * from "./variables/parse.js";

package/dist/index.js

@@ -1,7 +1,9 @@
+export * from "./flags/generate.js";
+export * from "./flags/parse.js";
 export * from "./icons/generate.js";
-export * from "./icons/optimize.js";
 export * from "./icons/parse.js";
 export * from "./types/figma.js";
 export * from "./utils/fetch.js";
+export * from "./utils/optimize.js";
 export * from "./variables/generate.js";
 export * from "./variables/parse.js";

package/dist/types/figma.d.ts

@@ -20,6 +20,7 @@ export type Variable = {
     name: string;
     variableCollectionId: string;
     hiddenFromPublishing: boolean;
+    deletedButReferenced?: boolean;
     valuesByMode: Record<string, VariableValue>;
 };
 export type VariableValue = RGBAValue | ColorsAlias | number;
@@ -104,3 +105,9 @@ export type ParsedIcon = {
     aliases: string[];
     category: string;
 };
+export type ParsedFlag = {
+    id: string;
+    code: string;
+    internationalName: string;
+    continent: string;
+};

package/dist/utils/fs.js

@@ -9,7 +9,7 @@ export const isDirectory = async (path) => {
         const stats = await stat(path);
         return stats.isDirectory();
     }
-    catch (e) {
+    catch {
         return false;
     }
 };

package/dist/{icons → utils}/optimize.d.ts

@@ -1,8 +1,8 @@
 /**
  * Optimizes the given SVG content for usage inside an icon library using [svgo](https://svgo.dev).
  * Will apply the following optimizations:
- * - remove all fills so the color can be set via CSS
  * - remove dimensions (height/width) so it can be set via CSS
  * - "preset-default" to reduce file size and redundant information
+ * - (only if type "icon"): remove all fills so the color can be set via CSS
  */
-export declare const optimizeSvg: (svgContent: string) => string;
+export declare const optimizeSvg: (svgContent: string, type?: "icon" | "image") => string;

package/dist/utils/optimize.js

@@ -0,0 +1,25 @@
+import { optimize } from "svgo";
+/**
+ * Optimizes the given SVG content for usage inside an icon library using [svgo](https://svgo.dev).
+ * Will apply the following optimizations:
+ * - remove dimensions (height/width) so it can be set via CSS
+ * - "preset-default" to reduce file size and redundant information
+ * - (only if type "icon"): remove all fills so the color can be set via CSS
+ */
+export const optimizeSvg = (svgContent, type = "icon") => {
+    const plugins = [{ name: "preset-default" }, { name: "removeDimensions" }];
+    if (type === "icon") {
+        plugins.push({
+            name: "removeAttrs",
+            params: {
+                // remove all fills so we can set the color via CSS
+                attrs: ["fill"],
+            },
+        });
+    }
+    const { data } = optimize(svgContent, {
+        multipass: true,
+        plugins,
+    });
+    return data;
+};

package/dist/variables/parse.d.ts

@@ -26,7 +26,7 @@ export declare const parseFigmaVariables: (apiResponse: FigmaVariablesApiRespons
  * @param value Figma variable value
  * @param allVariables Object of all variables. Needed for variables that use aliases.
  */
-export declare const resolveFigmaVariableValue: (value: VariableValue, allVariables: Record<string, Variable>, remBase?: ParseFigmaVariablesOptions["remBase"]) => string;
+export declare const resolveFigmaVariableValue: (value: VariableValue, allVariables: Record<string, Variable>, remBase?: ParseFigmaVariablesOptions["remBase"], name?: string) => string;
 /**
  * Converts a RGBA value to a hex color.
  * Transparency will only be added if its not 1, e.g. "#000000" instead of "#000000ff"

package/dist/variables/parse.js

@@ -14,12 +14,14 @@ export const parseFigmaVariables = (apiResponse, options) => {
      */
     Object.values(apiResponse.meta.variables).forEach((variable) => {
         const collection = apiResponse.meta.variableCollections[variable.variableCollectionId];
-        if (variable.hiddenFromPublishing || collection.hiddenFromPublishing)
+        if (variable.hiddenFromPublishing ||
+            variable.deletedButReferenced ||
+            collection.hiddenFromPublishing)
             return;
         // parse variable value for every mode
         Object.values(collection.modes).forEach((mode) => {
             const variableName = normalizeVariableName(variable.name);
-            const variableValue = resolveFigmaVariableValue(variable.valuesByMode?.[mode.modeId], apiResponse.meta.variables, options?.remBase);
+            const variableValue = resolveFigmaVariableValue(variable.valuesByMode?.[mode.modeId], apiResponse.meta.variables, options?.remBase, variableName);
             // add/update parsed variable value
             const existingIndex = parsedData.findIndex((i) => i.modeName === mode.name);
             if (existingIndex !== -1) {
@@ -71,8 +73,10 @@ export const parseFigmaVariables = (apiResponse, options) => {
  * @param value Figma variable value
  * @param allVariables Object of all variables. Needed for variables that use aliases.
  */
-export const resolveFigmaVariableValue = (value, allVariables, remBase = 16) => {
+export const resolveFigmaVariableValue = (value, allVariables, remBase = 16, name) => {
     if (typeof value === "number") {
+        if (name?.includes("font-weight"))
+            return `${value}`;
         // numeric value, parse as rem or pixel value
         // note: value 0 should also be parsed as "0rem" instead of just "0" because otherwise
         // the CSS variable could not be used together with "calc()"
@@ -80,6 +84,9 @@ export const resolveFigmaVariableValue = (value, allVariables, remBase = 16) =>
             return `${value}px`;
         return `${value / remBase}rem`;
     }
+    if (typeof value === "string") {
+        return `"${value}"`;
+    }
     if ("type" in value) {
         // parse value as alias
         if (value.type !== "VARIABLE_ALIAS") {

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-beta.4",
+  "version": "1.0.0-beta.6",
   "type": "module",
   "bin": {
     "@sit-onyx/figma-utils": "./dist/cli.js"
@@ -10,7 +10,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "types": "./dist/index.d.ts",
   "exports": {
@@ -29,7 +29,7 @@
     "url": "https://github.com/SchwarzIT/onyx/issues"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^14.0.0"
   },
   "optionalDependencies": {
     "svgo": "^3.3.2"

package/dist/icons/optimize.js

@@ -1,25 +0,0 @@
-import { optimize } from "svgo";
-/**
- * Optimizes the given SVG content for usage inside an icon library using [svgo](https://svgo.dev).
- * Will apply the following optimizations:
- * - remove all fills so the color can be set via CSS
- * - remove dimensions (height/width) so it can be set via CSS
- * - "preset-default" to reduce file size and redundant information
- */
-export const optimizeSvg = (svgContent) => {
-    const { data } = optimize(svgContent, {
-        multipass: true,
-        plugins: [
-            { name: "preset-default" },
-            { name: "removeDimensions" },
-            {
-                name: "removeAttrs",
-                params: {
-                    // remove all fills so we can set the color via CSS
-                    attrs: ["fill"],
-                },
-            },
-        ],
-    });
-    return data;
-};