@sb1/ffe-core 100.0.0 → 100.0.3

package/scripts/figma-api/token_import.ts

@@ -0,0 +1,430 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { colorApproximatelyEqual, parseColor } from './color';
+import { areSetsEqual } from './utils';
+import { Token, TokenOrTokenGroup, TokensFile } from './token_types';
+import {
+    GetLocalVariablesResponse,
+    LocalVariable,
+    LocalVariableCollection,
+    PostVariablesRequestBody,
+    VariableCodeSyntax,
+    VariableCreate,
+    VariableUpdate,
+    VariableValue,
+} from '@figma/rest-api-spec';
+
+export type FlattenedTokensByFile = {
+    [fileName: string]: {
+        [tokenName: string]: Token;
+    };
+};
+
+function traverseCollection({
+    key,
+    object,
+    tokens,
+}: {
+    key: string;
+    object: TokenOrTokenGroup;
+    tokens: { [tokenName: string]: Token };
+}) {
+    // if key is a meta field, move on
+    if (key.charAt(0) === '$') {
+        return;
+    }
+
+    if (object.$value !== undefined) {
+        tokens[key] = object;
+    } else {
+        Object.entries<TokenOrTokenGroup>(object).forEach(([key2, object2]) => {
+            if (key2.charAt(0) !== '$' && typeof object2 === 'object') {
+                traverseCollection({
+                    key: `${key}/${key2}`,
+                    object: object2,
+                    tokens,
+                });
+            }
+        });
+    }
+}
+
+function collectionAndModeFromFileName(fileName: string) {
+    const fileNameParts = fileName.split('.');
+    if (fileNameParts.length < 3) {
+        throw new Error(
+            `Invalid tokens file name: ${fileName}. File names must be in the format: {collectionName}.{modeName}.json`,
+        );
+    }
+    const [collectionName, modeName] = fileNameParts;
+    return { collectionName, modeName };
+}
+
+function flattenTokensFile(tokensFile: TokensFile) {
+    const flattenedTokens: { [tokenName: string]: Token } = {};
+
+    Object.entries(tokensFile).forEach(([tokenGroup, groupValues]) => {
+        traverseCollection({
+            key: tokenGroup,
+            object: groupValues,
+            tokens: flattenedTokens,
+        });
+    });
+
+    return flattenedTokens;
+}
+
+export function readJsonFiles(files: string[]) {
+    const tokensJsonByFile: FlattenedTokensByFile = {};
+
+    const seenCollectionsAndModes = new Set<string>();
+
+    files.forEach(file => {
+        const baseFileName = path.basename(file);
+        const { collectionName, modeName } =
+            collectionAndModeFromFileName(baseFileName);
+
+        if (seenCollectionsAndModes.has(`${collectionName}.${modeName}`)) {
+            throw new Error(`Duplicate collection and mode in file: ${file}`);
+        }
+
+        seenCollectionsAndModes.add(`${collectionName}.${modeName}`);
+
+        const fileContent = fs.readFileSync(file, { encoding: 'utf-8' });
+
+        if (!fileContent) {
+            throw new Error(`Invalid tokens file: ${file}. File is empty.`);
+        }
+        const tokensFile: TokensFile = JSON.parse(fileContent);
+
+        tokensJsonByFile[baseFileName] = flattenTokensFile(tokensFile);
+    });
+
+    return tokensJsonByFile;
+}
+
+function variableResolvedTypeFromToken(token: Token) {
+    switch (token.$type) {
+        case 'color':
+            return 'COLOR';
+        case 'number':
+            return 'FLOAT';
+        case 'string':
+            return 'STRING';
+        case 'boolean':
+            return 'BOOLEAN';
+        default:
+            throw new Error(`Invalid token $type: ${token.$type}`);
+    }
+}
+
+function isAlias(value: string) {
+    return value.toString().trim().charAt(0) === '{';
+}
+
+function variableValueFromToken(
+    token: Token,
+    localVariablesByCollectionAndName: {
+        [variableCollectionId: string]: {
+            [variableName: string]: LocalVariable;
+        };
+    },
+): VariableValue {
+    if (typeof token.$value === 'string' && isAlias(token.$value)) {
+        // Assume aliases are in the format {group.subgroup.token} with any number of optional groups/subgroups
+        // The Figma syntax for variable names is: group/subgroup/token
+        const value = token.$value
+            .trim()
+            .replace(/\./g, '/')
+            .replace(/[{}]/g, '');
+
+        // When mapping aliases to existing local variables, we assume that variable names
+        // are unique *across all collections* in the Figma file
+        for (const localVariablesByName of Object.values(
+            localVariablesByCollectionAndName,
+        )) {
+            if (localVariablesByName[value]) {
+                return {
+                    type: 'VARIABLE_ALIAS',
+                    id: localVariablesByName[value].id,
+                };
+            }
+        }
+
+        // If we don't find a local variable matching the alias, we assume it's a variable
+        // that we're going to create elsewhere in the payload.
+        // If the file has an invalid alias, we rely on the Figma API to return a 400 error
+        return {
+            type: 'VARIABLE_ALIAS',
+            id: value,
+        };
+    } else if (typeof token.$value === 'string' && token.$type === 'color') {
+        return parseColor(token.$value);
+    }
+    return token.$value;
+}
+
+function compareVariableValues(a: VariableValue, b: VariableValue) {
+    if (typeof a === 'object' && typeof b === 'object') {
+        if (
+            'type' in a &&
+            'type' in b &&
+            a.type === 'VARIABLE_ALIAS' &&
+            b.type === 'VARIABLE_ALIAS'
+        ) {
+            return a.id === b.id;
+        } else if ('r' in a && 'r' in b) {
+            return colorApproximatelyEqual(a, b);
+        }
+    } else {
+        return a === b;
+    }
+
+    return false;
+}
+
+function isCodeSyntaxEqual(a: VariableCodeSyntax, b: VariableCodeSyntax) {
+    return (
+        Object.keys(a).length === Object.keys(b).length &&
+        Object.keys(a).every(
+            key =>
+                a[key as keyof VariableCodeSyntax] ===
+                b[key as keyof VariableCodeSyntax],
+        )
+    );
+}
+
+/**
+ * Get writable token properties that are different from the variable.
+ * If the variable does not exist, all writable properties are returned.
+ *
+ * This function is being used to decide what properties to include in the
+ * POST variables call to update variables in Figma. If a token does not have
+ * a particular property, we do not include it in the differences object to avoid
+ * touching that property in Figma.
+ */
+function tokenAndVariableDifferences(
+    token: Token,
+    variable: LocalVariable | null,
+) {
+    const differences: Partial<
+        Omit<
+            VariableCreate | VariableUpdate,
+            'id' | 'name' | 'variableCollectionId' | 'resolvedType' | 'action'
+        >
+    > = {};
+
+    if (
+        token.$description !== undefined &&
+        (!variable || token.$description !== variable.description)
+    ) {
+        differences.description = token.$description;
+    }
+
+    if (token.$extensions && token.$extensions['com.figma']) {
+        const figmaExtensions = token.$extensions['com.figma'];
+
+        if (
+            figmaExtensions.hiddenFromPublishing !== undefined &&
+            (!variable ||
+                figmaExtensions.hiddenFromPublishing !==
+                    variable.hiddenFromPublishing)
+        ) {
+            differences.hiddenFromPublishing =
+                figmaExtensions.hiddenFromPublishing;
+        }
+
+        if (
+            figmaExtensions.scopes &&
+            (!variable ||
+                !areSetsEqual(
+                    new Set(figmaExtensions.scopes),
+                    new Set(variable.scopes),
+                ))
+        ) {
+            differences.scopes = figmaExtensions.scopes;
+        }
+
+        if (
+            figmaExtensions.codeSyntax &&
+            (!variable ||
+                !isCodeSyntaxEqual(
+                    figmaExtensions.codeSyntax,
+                    variable.codeSyntax,
+                ))
+        ) {
+            differences.codeSyntax = figmaExtensions.codeSyntax;
+        }
+    }
+
+    return differences;
+}
+
+export function generatePostVariablesPayload(
+    tokensByFile: FlattenedTokensByFile,
+    localVariables: GetLocalVariablesResponse,
+) {
+    const localVariableCollectionsByName: {
+        [name: string]: LocalVariableCollection;
+    } = {};
+    const localVariablesByCollectionAndName: {
+        [variableCollectionId: string]: {
+            [variableName: string]: LocalVariable;
+        };
+    } = {};
+
+    Object.values(localVariables.meta.variableCollections).forEach(
+        collection => {
+            if (localVariableCollectionsByName[collection.name]) {
+                throw new Error(
+                    `Duplicate variable collection in file: ${collection.name}`,
+                );
+            }
+
+            localVariableCollectionsByName[collection.name] = collection;
+        },
+    );
+
+    Object.values(localVariables.meta.variables).forEach(variable => {
+        if (!localVariablesByCollectionAndName[variable.variableCollectionId]) {
+            localVariablesByCollectionAndName[variable.variableCollectionId] =
+                {};
+        }
+
+        localVariablesByCollectionAndName[variable.variableCollectionId][
+            variable.name
+        ] = variable;
+    });
+
+    console.log(
+        'Local variable collections in Figma file:',
+        Object.keys(localVariableCollectionsByName),
+    );
+
+    const postVariablesPayload: PostVariablesRequestBody = {
+        variableCollections: [],
+        variableModes: [],
+        variables: [],
+        variableModeValues: [],
+    };
+
+    Object.entries(tokensByFile).forEach(([fileName, tokens]) => {
+        const { collectionName, modeName } =
+            collectionAndModeFromFileName(fileName);
+
+        const variableCollection =
+            localVariableCollectionsByName[collectionName];
+        // Use the actual variable collection id or use the name as the temporary id
+        const variableCollectionId = variableCollection
+            ? variableCollection.id
+            : collectionName;
+        const variableMode = variableCollection?.modes.find(
+            mode => mode.name === modeName,
+        );
+        // Use the actual mode id or use the name as the temporary id
+        const modeId = variableMode ? variableMode.modeId : modeName;
+
+        if (
+            !variableCollection &&
+            !postVariablesPayload.variableCollections!.find(
+                c => c.id === variableCollectionId,
+            )
+        ) {
+            postVariablesPayload.variableCollections!.push({
+                action: 'CREATE',
+                id: variableCollectionId,
+                name: variableCollectionId,
+                initialModeId: modeId, // Use the initial mode as the first mode
+            });
+
+            // Rename the initial mode, since we're using it as our first mode in the collection
+            postVariablesPayload.variableModes!.push({
+                action: 'UPDATE',
+                id: modeId,
+                name: modeId,
+                variableCollectionId,
+            });
+        }
+
+        // Add a new mode if it doesn't exist in the Figma file
+        // and it's not the initial mode in the collection
+        if (
+            !variableMode &&
+            !postVariablesPayload.variableCollections!.find(
+                c =>
+                    c.id === variableCollectionId &&
+                    'initialModeId' in c &&
+                    c.initialModeId === modeId,
+            )
+        ) {
+            postVariablesPayload.variableModes!.push({
+                action: 'CREATE',
+                id: modeId,
+                name: modeId,
+                variableCollectionId,
+            });
+        }
+
+        const localVariablesByName =
+            localVariablesByCollectionAndName[variableCollection?.id] || {};
+
+        Object.entries(tokens).forEach(([tokenName, token]) => {
+            const variable = localVariablesByName[tokenName];
+            const variableId = variable ? variable.id : tokenName;
+            const variableInPayload = postVariablesPayload.variables!.find(
+                v =>
+                    v.id === variableId &&
+                    'variableCollectionId' in v &&
+                    v.variableCollectionId === variableCollectionId,
+            );
+            const differences = tokenAndVariableDifferences(token, variable);
+
+            // Add a new variable if it doesn't exist in the Figma file,
+            // and we haven't added it already in another mode
+            if (!variable && !variableInPayload) {
+                postVariablesPayload.variables!.push({
+                    action: 'CREATE',
+                    id: variableId,
+                    name: tokenName,
+                    variableCollectionId,
+                    resolvedType: variableResolvedTypeFromToken(token),
+                    ...differences,
+                });
+            } else if (variable && Object.keys(differences).length > 0) {
+                if (variable.remote) {
+                    throw new Error(
+                        `Cannot update remote variable "${variable.name}" in collection "${collectionName}"`,
+                    );
+                }
+
+                postVariablesPayload.variables!.push({
+                    action: 'UPDATE',
+                    id: variableId,
+                    ...differences,
+                });
+            }
+
+            const existingVariableValue =
+                variable && variableMode ? variable.valuesByMode[modeId] : null;
+            const newVariableValue = variableValueFromToken(
+                token,
+                localVariablesByCollectionAndName,
+            );
+
+            // Only include the variable mode value in the payload if it's different from the existing value
+            if (
+                existingVariableValue === null ||
+                !compareVariableValues(existingVariableValue, newVariableValue)
+            ) {
+                postVariablesPayload.variableModeValues!.push({
+                    variableId,
+                    modeId,
+                    value: newVariableValue,
+                });
+            }
+        });
+    });
+
+    return postVariablesPayload;
+}

package/scripts/figma-api/token_types.ts

@@ -0,0 +1,55 @@
+/**
+ * This file defines what design tokens and design token files look like in the codebase.
+ *
+ * Tokens are distinct from variables, in that a [token](https://tr.designtokens.org/format/#design-token)
+ * is a name/value pair (with other properties), while a variable in Figma stores multiple values,
+ * one for each mode.
+ */
+
+import { VariableCodeSyntax, VariableScope } from '@figma/rest-api-spec';
+
+export interface Token {
+    /**
+     * The [type](https://tr.designtokens.org/format/#type-0) of the token.
+     *
+     * We allow `string` and `boolean` types in addition to the draft W3C spec's `color` and `number` types
+     * to align with the resolved types for Figma variables.
+     */
+    $type: 'color' | 'number' | 'string' | 'boolean';
+    $value: string | number | boolean;
+    $description?: string;
+    $extensions?: {
+        /**
+         * The `com.figma` namespace stores Figma-specific variable properties
+         */
+        'com.figma'?: {
+            hiddenFromPublishing?: boolean;
+            scopes?: VariableScope[];
+            codeSyntax?: VariableCodeSyntax;
+        };
+    };
+}
+
+export type TokenOrTokenGroup =
+    | Token
+    | ({
+          [tokenName: string]: Token;
+      } & { $type?: never; $value?: never });
+
+/**
+ * Defines what we expect a Design Tokens file to look like in the codebase.
+ *
+ * This format mostly adheres to the [draft W3C spec for Design Tokens](https://tr.designtokens.org/format/)
+ * as of its most recent 24 July 2023 revision except for the $type property, for which
+ * we allow `string` and `boolean` values in addition to the spec's `color` and `number` values.
+ * We need to support `string` and `boolean` types to align with the resolved types for Figma variables.
+ *
+ * Additionally, we expect each tokens file to define tokens for a single variable collection and mode.
+ * There currently isn't a way to represent modes or themes in the W3C community group design token specification.
+ * Once the spec resolves how it wants to treat/handle modes, this code will be updated to reflect the new standard.
+ *
+ * Follow this discussion for updates: https://github.com/design-tokens/community-group/issues/210
+ */
+export type TokensFile = {
+    [key: string]: TokenOrTokenGroup;
+};

package/scripts/figma-api/utils.ts

@@ -0,0 +1,11 @@
+export function green(msg: string) {
+    return `\x1b[32m${msg}\x1b[0m`;
+}
+
+export function brightRed(msg: string) {
+    return `\x1b[1;31m${msg}\x1b[0m`;
+}
+
+export function areSetsEqual<T>(a: Set<T>, b: Set<T>) {
+    return a.size === b.size && Array.from(a).every(item => b.has(item));
+}

package/scripts/lib/extractCustomProps.cjs

@@ -0,0 +1,24 @@
+const postcss = require('postcss');
+const Case = require('case');
+
+const genPropName = prop => Case.camel(prop.replace(/^--(ffe-)?/, ''));
+
+/**
+ * Extract all custom properties from a given stylesheet and create an object
+ * mapping properties to thier value.
+ */
+
+module.exports = async css => {
+    const { root } = await postcss().process(css, {
+        from: false,
+        hideNothingWarning: true,
+    });
+
+    const obj = {};
+
+    root.walkDecls(decl => {
+        obj[genPropName(decl.prop)] = decl.value;
+    });
+
+    return obj;
+};

package/scripts/lib/genTypeScript.cjs

@@ -0,0 +1,7 @@
+module.exports.genTSSource = obj =>
+    Object.keys(obj)
+        .map(k => `export const ${k} = '${obj[k]}';`)
+        .join('\n');
+
+module.exports.genTSModIndex = sources =>
+    sources.map(s => `export * from './${s}';`).join('\n');

package/scripts/lib/renderLessVarsToCSSProps.cjs

@@ -0,0 +1,23 @@
+const fs = require('fs').promises;
+const less = require('less');
+
+/**
+ * Takes less variables from a given file and generates a css stylesheet with
+ * these variables as custom properties on the :root pseudo-class.
+ */
+module.exports = async inputFile => {
+    const data = await fs.readFile(inputFile, 'utf8');
+    const root = await less.parse(data, { filename: inputFile });
+
+    const propertyNames = root.rules
+        .filter(r => r.variable)
+        .map(n => n.name.slice(1));
+
+    const { css } = await less.render(
+        `@import '${inputFile}';` +
+            `@props: ${propertyNames.join(', ')};` +
+            `:root, :host { each(@props, { --@{value}: @@value; }); }`,
+    );
+
+    return css;
+};

package/scripts/lib/writeToFile.cjs

@@ -0,0 +1,9 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+module.exports = filename => data =>
+    fs
+        .mkdir(path.dirname(filename), { recursive: true })
+        .then(() => fs.writeFile(filename, data, 'utf8'))
+        .then(() => console.log(`wrote ${filename}`))
+        .then(() => data); // return input data for smoother pipelines

package/scripts/utils.cjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+
+function getProcessArguments() {
+  const args = {};
+  console.log(process.argv);
+  process.argv.slice(2).forEach((arg) => {
+    if (!arg.includes("=")) return;
+    const [key, value] = arg.split("=");
+    args[key] = value.split(",");
+  });
+  return args;
+}
+
+const writeToFile = (filename) => (data) => {
+  const dir = path.dirname(filename);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filename, data, "utf8");
+  console.log(`wrote ${filename}`);
+  return data; // return input data for smoother pipelines
+};
+
+module.exports = { getProcessArguments, writeToFile };