@esri/calcite-design-tokens 1.0.0 → 1.1.0-next.1

package/support/run.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { getThemes } from "./token-transformer/getThemes.js";
+import { run } from "./token-transformer/sd-run.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get all themes defined int the tokens/$themes.json and generate a Style Dictionary output for each theme
+ */
+const rawData = readFileSync(resolve(__dirname, "../src/$themes.json"), { encoding: "utf-8" });
+const data = JSON.parse(rawData);
+
+getThemes(data).then((themes) => Promise.all(themes.map((theme) => run("src", "dist", theme))));

package/support/token-transformer/format/scss.ts

@@ -0,0 +1,81 @@
+import { pascalCase, sentenceCase } from "change-case";
+import StyleDictionary, { Dictionary, File, Platform, Options } from "style-dictionary";
+import { sortAllTokens } from "../utils/sortAllTokens.js";
+
+const regexThemeGroup = /calcite|brand/gi;
+const regexFileNameWithoutExtension = /\w+(?=\.\w+$)/gi;
+
+/**
+ * Exports SCSS style formats
+ *
+ * @param {object} fileInfo the file object
+ * @param {Dictionary} fileInfo.dictionary the Style Dictionary object
+ * @param {File} fileInfo.file information about the file to be generated
+ * @param {Platform} [fileInfo.platform] the platform to generate the asset for
+ * @param {Options} fileInfo.options the Style Dictionary format options passed from the config
+ * @returns {string} a string that is passed to fs.writeFileSync
+ */
+export function formatSCSS(fileInfo: {
+  dictionary: Dictionary;
+  file: File;
+  platform?: Platform;
+  options: Options & { themeable?: boolean };
+}): string {
+  const { dictionary, file, options } = fileInfo;
+  const { outputReferences } = options;
+  const themeName = pascalCase(
+    sentenceCase(file.destination.match(regexFileNameWithoutExtension)[0])
+      .split(" ")
+      .filter((n) => !regexThemeGroup.test(n))
+      .join(" ")
+  ).toLowerCase();
+  const sassProps = StyleDictionary.formatHelpers.createPropertyFormatter({
+    outputReferences,
+    dictionary,
+    format: "sass",
+  });
+  const cssProps = StyleDictionary.formatHelpers.createPropertyFormatter({
+    outputReferences,
+    dictionary,
+    format: "css",
+  });
+  const sortedTokens = sortAllTokens(dictionary, outputReferences);
+  const coreTokens = [...sortedTokens].reduce(
+    (acc, token) => {
+      token.value = token.value.includes(" ") ? `"${token.value}"` : token.value === "Demi" ? 600 : token.value;
+      acc[1].push(cssProps(token));
+
+      if (token.filePath.includes("core")) {
+        const sassToken = { ...token };
+        const path = sassToken.path.filter((p) => !/(core|default|font$)/.test(p));
+        sassToken.name = sassToken.type === "color" ? path.slice(-1).join("-") : path.join("-");
+        sassToken.original.value = sassToken.original.value[0] === "{" ? sassToken.value : sassToken.original.value;
+        acc[0].push(sassProps(sassToken));
+      }
+
+      if (/dark|light/.test(token.filePath) && !token.path.includes("component")) {
+        const sassToken = { ...token };
+        const path = sassToken.path.reduce((acc, p) => {
+          if (p === "default") {
+            return acc;
+          }
+          acc.push(p === "color" ? "ui" : p);
+          return acc;
+        }, []);
+        path.push(token.filePath.includes("dark") ? "dark" : "light");
+        sassToken.name = path.join("-");
+        acc[0].push(sassProps(sassToken));
+      }
+
+      return acc;
+    },
+    [[], []]
+  );
+
+  return `${StyleDictionary.formatHelpers.fileHeader({ file })}
+${coreTokens[0].join("\n")}
+
+@mixin calcite-theme-${themeName}() {
+${coreTokens[1].join("\n")}
+}`;
+}

package/support/token-transformer/getThemes.ts

@@ -0,0 +1,41 @@
+import { Options } from "style-dictionary";
+
+export interface ThemeFileInterface {
+  id: string;
+  name: string;
+  selectedTokenSets: Record<string, "enabled" | "disabled" | "source">;
+  $figmaStyleReferences?: Record<string, string>;
+}
+
+export type Theme = {
+  name: string;
+  enabled: string[];
+  disabled: string[];
+  source: string[];
+  id?: string;
+  options?: Options;
+};
+
+/**
+ *
+ * @param {ThemeFileInterface} themes an array of Figma Token Studio theme definition objects
+ * @returns {Array} an array of Style Dictionary theme definition objects
+ */
+export async function getThemes(themes: ThemeFileInterface[]): Promise<Theme[]> {
+  return themes.map((themeConfig) => {
+    const themeTypes = { enabled: [], disabled: [], source: [] };
+    const { name, id, selectedTokenSets } = themeConfig;
+    const { enabled, disabled, source } = Object.entries(selectedTokenSets).reduce((acc, [key, value]) => {
+      acc[value].push(key);
+      return acc;
+    }, themeTypes);
+
+    return {
+      name,
+      id,
+      enabled,
+      disabled,
+      source,
+    };
+  });
+}

package/support/token-transformer/parse/expandComposites.test.ts

@@ -0,0 +1,144 @@
+const mockCorrectTypeCompoundToken = {
+  core: {
+    1: {
+      type: "sizing",
+      value: "10",
+    },
+  },
+  compound: {
+    value: {
+      fontFamily: "$core.font.font-family.primary",
+      fontWeight: "$core.font.font-weight.light",
+      lineHeight: "$core.font.line-height.fixed.0",
+      fontSize: "$core.font.font-size.0",
+      letterSpacing: "$core.font.letter-spacing.normal",
+      paragraphSpacing: "$core.font.paragraph-spacing.normal",
+      textDecoration: "$core.font.text-decoration.none",
+      textCase: "$core.font.text-case.none",
+    },
+    type: "typography",
+  },
+};
+const mockTransformedCompoundTokens = {
+  core: {
+    1: {
+      type: "sizing",
+      value: "10",
+    },
+  },
+  compound: {
+    "font-family": {
+      value: "$core.font.font-family.primary",
+      type: "font-family",
+    },
+    "font-weight": {
+      value: "$core.font.font-weight.light",
+      type: "font-weights",
+    },
+    "line-height": {
+      value: "$core.font.line-height.fixed.0",
+      type: "line-heights",
+    },
+    "font-size": {
+      value: "$core.font.font-size.0",
+      type: "font-size",
+    },
+    "letter-spacing": {
+      value: "$core.font.letter-spacing.normal",
+      type: "letter-spacing",
+    },
+    "paragraph-spacing": {
+      value: "$core.font.paragraph-spacing.normal",
+      type: "paragraph-spacing",
+    },
+    "text-decoration": {
+      value: "$core.font.text-decoration.none",
+      type: "font-style",
+    },
+    "text-case": {
+      value: "$core.font.text-case.none",
+      type: "text-case",
+    },
+  },
+};
+
+const handleTokenStudioVariables = jest.fn((token) => (token.includes("$") ? `{${token.replace(/\$/g, "")}}` : token));
+const convertTokenToStyleDictionaryFormat = jest.fn(() => handleTokenStudioVariables);
+const shouldExpand = jest.fn().mockReturnValue(true);
+const expandToken = jest.fn().mockReturnValue(mockTransformedCompoundTokens);
+
+jest.mock("../utils/compositeTokens.js", () => {
+  const originalModule = jest.requireActual("../utils/compositeTokens.js");
+  return {
+    __esModule: false,
+    ...originalModule,
+    shouldExpand,
+    expandToken,
+  };
+});
+
+jest.mock("../utils/convertTokenToStyleDictionaryFormat.js", () => {
+  const originalModule = jest.requireActual("../utils/convertTokenToStyleDictionaryFormat.js");
+  return {
+    __esModule: false,
+    ...originalModule,
+    convertTokenToStyleDictionaryFormat,
+  };
+});
+
+import * as expandComposites from "./expandComposites";
+
+describe("expand token dictionary", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should not add placeholder elements", () => {
+    const placeolderToken = {
+      "[placeholder-component]": {
+        type: "other",
+        value: "#333",
+      },
+    };
+    const placeholderValue = {
+      compoonent: {
+        type: "other",
+        value: "[placholder-value]",
+      },
+    };
+
+    // @ts-expect-error - it's fine.
+    const testExpandPlaceholderKey = expandComposites.expandComposites(placeolderToken, "./fakePath");
+    // @ts-expect-error - it's fine.
+    const testExpandPlaceholderValue = expandComposites.expandComposites(placeholderValue, "./fakePath");
+
+    expect(testExpandPlaceholderKey).toMatchObject({});
+    expect(testExpandPlaceholderValue).toMatchObject({});
+  });
+
+  it('should loop through a dictionary and run "shouldExpand" and  "expandToken" on each composite token', () => {
+    // @ts-expect-error - it's fine.
+    const testExpandComposite = expandComposites.expandComposites(mockCorrectTypeCompoundToken, "./fakePath");
+    expect(handleTokenStudioVariables).toHaveBeenCalledTimes(1);
+    expect(shouldExpand).toHaveBeenCalledTimes(1);
+    expect(expandToken).toHaveBeenCalledTimes(1);
+    expect(testExpandComposite).toMatchObject(mockTransformedCompoundTokens);
+  });
+
+  it("should not run expand token on unrecognized types", () => {
+    const mockDictionary = {
+      core: {
+        type: "customType",
+        value: {
+          fontFamily: "Avanir",
+          fontSize: "12px",
+        },
+      },
+    };
+    // @ts-expect-error - it's fine this is a test
+    const testExpandComposite = expandComposites.expandComposites(mockDictionary, "./fakePath");
+    expect(shouldExpand).not.toHaveBeenCalled();
+    expect(expandToken).not.toHaveBeenCalled();
+    expect(testExpandComposite).toMatchObject(mockDictionary);
+  });
+});

package/support/token-transformer/parse/expandComposites.ts

@@ -0,0 +1,72 @@
+import { DeepKeyTokenMap } from "@tokens-studio/types";
+import { DesignToken } from "style-dictionary/types/DesignToken.js";
+import {
+  TransformOptions,
+  ExpandablesAsStrings,
+  Expandables,
+  expandablesAsStringsArr,
+} from "../utils/transformOptions.js";
+import { matchPlaceholderElement, tokenStudioCustomVariableIndicator } from "../utils/regex.js";
+import { shouldExpand, expandToken } from "../utils/compositeTokens.js";
+import { convertTokenToStyleDictionaryFormat } from "../utils/convertTokenToStyleDictionaryFormat.js";
+
+/**
+ * Figma Token Studio creates an odd type of composite token where the "value" may contain an object of "key: value" pairs rather than a sting.
+ * Here we will lift these composite tokens up to match the Style Dictionary format.
+ *
+ * @param {DeepKeyTokenMap} dictionary the raw JSON object in the token files. We will assume this is a token object generated by Figma Token Studio and may require composite tokens to be expanded.
+ * @param {string} filePath the absolute file path to the JSON token file.
+ * @param {TransformOptions} transformOpts the options passed in from the Style Dictionary config and runner
+ * @returns {DeepKeyTokenMap} a token object where any Figma Token Studio composite tokens now match the Style Dictionary token format
+ */
+export function expandComposites(
+  dictionary: DeepKeyTokenMap,
+  filePath: string,
+  transformOpts: TransformOptions = {}
+): DeepKeyTokenMap {
+  const opts = {
+    ...transformOpts,
+    expand: {
+      composition: true,
+      typography: false,
+      border: false,
+      shadow: false,
+      ...transformOpts.expand,
+    },
+  };
+  const returnSlice: DeepKeyTokenMap = {};
+  const handleTokenStudioVariables = convertTokenToStyleDictionaryFormat(tokenStudioCustomVariableIndicator);
+  const newDictionary = Object.entries(dictionary).reduce((acc, [key, token]) => {
+    const { type } = token;
+
+    if (
+      matchPlaceholderElement.test(`${key}`) ||
+      (typeof token.value === "string" && matchPlaceholderElement.test(`${token.value}`))
+    ) {
+      return acc;
+    }
+
+    if (token.value && type) {
+      const includesType = expandablesAsStringsArr.includes(`${type}`);
+
+      if (includesType) {
+        const expandType = (type as ExpandablesAsStrings) === "boxShadow" ? "shadow" : type;
+        const expand = shouldExpand<Expandables>(token as Expandables, opts.expand[`${expandType}`], filePath);
+        if (expand) {
+          const expandedToken = expandToken(token as DesignToken, expandType === "shadow", handleTokenStudioVariables);
+          return expandedToken;
+        }
+      } else if (typeof token.value === "string") {
+        token.value = handleTokenStudioVariables(token.value);
+        acc[key] = token;
+      } else {
+        acc[key] = token;
+      }
+    } else if (typeof token === "object") {
+      acc[key] = expandComposites(token as DeepKeyTokenMap, filePath, transformOpts);
+    }
+    return acc;
+  }, returnSlice);
+
+  return newDictionary || {};
+}

package/support/token-transformer/sd-run.ts

@@ -0,0 +1,147 @@
+import { registerTransforms } from "@tokens-studio/sd-transforms";
+import StyleDictionary from "style-dictionary";
+import { expandComposites } from "./parse/expandComposites.js";
+import { formatSCSS } from "./format/scss.js";
+import { matchExclusions } from "./utils/regex.js";
+import { matchList } from "./utils/matchList.js";
+import { nameCamelCase } from "./transform/nameCamelCase.js";
+import { nameKebabCase } from "./transform/nameKebabCase.js";
+import { parseName } from "./utils/parseName.js";
+import { Theme } from "./getThemes.js";
+
+/**
+ * Style Dictionary runner configuration overrides.
+ *
+ * @param {string} tokenDir the directory containing design token files
+ * @param {string} buildPath the directory to write generated assets to
+ * @param {Theme} theme the theme configuration to use to generate the platform asset files
+ * @param {string} theme.name the name of the theme. This will be used as the basis for the generated asset file names.
+ * @param {string[]} theme.enabled an array of partial file names matching the token files which should be included in the output
+ * @param {string[]} theme.disabled an array of partial file names matching the token files which should explicitly not be included in the output
+ * @param {string[]} theme.source an array of partial file names matching the token files which should not always be included in the output but who's values should be used for variables references in the "enabled" files
+ */
+export const run = async (
+  tokenDir = "tokens",
+  buildPath = "dist",
+  theme: Pick<Theme, "enabled" | "disabled" | "name" | "source">
+): Promise<void> => {
+  const fileName = parseName(theme.name);
+  const include = theme.source.map((tokenFile) => `${tokenDir}/${tokenFile}.json`);
+  const source = theme.enabled.map((tokenFile) => `${tokenDir}/${tokenFile}.json`);
+  const options = {
+    enabled: theme.enabled,
+    source: theme.source,
+    disabled: theme.disabled,
+    outputReferences: false,
+    sourceReferencesOnly: false,
+  };
+
+  // Here we are registering the Transforms provided by Token Studio
+  // https://github.com/tokens-studio/sd-transforms
+  // @ts-expect-error - @token-studio does not keep their types up to date.
+  await registerTransforms(StyleDictionary, {
+    expand: false,
+  });
+
+  // Register custom formatter https://amzn.github.io/style-dictionary/#/formats?id=custom-formats
+  StyleDictionary.registerFormat({
+    name: "calcite/scss",
+    formatter: formatSCSS,
+  });
+
+  // Registering Style Dictionary transformers https://amzn.github.io/style-dictionary/#/transforms?id=defining-custom-transforms
+  StyleDictionary.registerTransform({
+    name: "name/calcite/camel",
+    type: "name",
+    transformer: nameCamelCase,
+  });
+
+  StyleDictionary.registerTransform({
+    name: "name/calcite/kebab",
+    type: "name",
+    transformer: nameKebabCase,
+  });
+
+  StyleDictionary.registerFilter({
+    name: "filterSource",
+    matcher: (token) => token.isSource,
+  });
+
+  // We are programmatically creating the Style Dictionary configuration here
+  // https://amzn.github.io/style-dictionary/#/config
+  const sd = StyleDictionary.extend({
+    source,
+    include,
+    platforms: {
+      css: {
+        prefix: "calcite",
+        transforms: [
+          "ts/descriptionToComment",
+          "ts/size/px",
+          "ts/opacity",
+          "ts/size/lineheight",
+          "ts/type/fontWeight",
+          "ts/resolveMath",
+          "ts/size/css/letterspacing",
+          "ts/color/css/hexrgba",
+          "ts/color/modifiers",
+          "name/calcite/kebab",
+        ],
+        buildPath: `${buildPath}/css/`,
+        files: [
+          {
+            destination: `${fileName}.css`,
+            format: "css/variables",
+            filter: /headless/gi.test(fileName) ? null : "filterSource",
+            options: /headless/gi.test(fileName) ? { ...options, outputReferences: true } : options,
+          },
+        ],
+      },
+      scss: {
+        prefix: "calcite",
+        transforms: [
+          "ts/descriptionToComment",
+          "ts/size/px",
+          "ts/opacity",
+          "ts/size/lineheight",
+          "ts/type/fontWeight",
+          "ts/resolveMath",
+          "ts/size/css/letterspacing",
+          "ts/color/css/hexrgba",
+          "ts/color/modifiers",
+          "name/calcite/kebab",
+        ],
+        buildPath: `${buildPath}/scss/`,
+        files: [
+          {
+            destination: `${fileName}.scss`,
+            format: "calcite/scss",
+            filter: /headless/gi.test(fileName) ? null : "filterSource",
+            options: /headless/gi.test(fileName) ? { ...options, outputReferences: true } : options,
+          },
+        ],
+      },
+    },
+    parsers: [
+      {
+        pattern: /\.json$/,
+        parse: (file) => {
+          if (matchList(file.filePath, [...include, ...theme.source, ...theme.enabled], matchExclusions)) {
+            const obj = JSON.parse(file.contents);
+            const expanded = expandComposites(obj, file.filePath);
+            return expanded;
+          }
+
+          return {};
+        },
+      },
+    ],
+  });
+
+  try {
+    sd.cleanAllPlatforms();
+    sd.buildAllPlatforms();
+  } catch (error) {
+    console.error(error);
+  }
+};

package/support/token-transformer/transform/nameCamelCase.test.ts

@@ -0,0 +1,36 @@
+import { nameCamelCase } from "./nameCamelCase";
+
+describe("transform names to camel case", () => {
+  it("should transform a token path to token name in a camel case format", () => {
+    const mockToken = {
+      name: "current-name",
+      path: ["test", "token", "name"],
+      value: "fake-value",
+      filePath: "./fakePath.json",
+      original: {
+        value: "fake-value",
+        type: "composite",
+      },
+      isSource: true,
+    };
+    expect(nameCamelCase(mockToken, {})).toBe("testTokenName");
+  });
+
+  it("should add prefix to token name", () => {
+    const mockToken = {
+      name: "current-name",
+      path: ["test", "token", "name"],
+      value: "fake-value",
+      filePath: "./fakePath.json",
+      original: {
+        value: "fake-value",
+        type: "composite",
+      },
+      isSource: true,
+    };
+    const mockOptions = {
+      prefix: "calcite",
+    };
+    expect(nameCamelCase(mockToken, mockOptions)).toBe("calciteTestTokenName");
+  });
+});

package/support/token-transformer/transform/nameCamelCase.ts

@@ -0,0 +1,15 @@
+import { camelCase } from "change-case";
+import { TransformedToken } from "style-dictionary/types/TransformedToken.js";
+import { Options } from "style-dictionary/types/Options.js";
+import { parseTokenPath } from "../utils/parseTokenPath.js";
+
+/**
+ * Convert token name to camel case
+ *
+ * @param {TransformedToken} token Style Dictionary token object
+ * @param {Options} options Style Dictionary format options
+ * @returns {string} an updated name for the token which will be used for the final output
+ */
+export function nameCamelCase(token: TransformedToken, options: Options): string {
+  return camelCase([options.prefix].concat(parseTokenPath(token.path)).join(" "));
+}

package/support/token-transformer/transform/nameKebabCase.test.ts

@@ -0,0 +1,36 @@
+import { nameKebabCase } from "./nameKebabCase";
+
+describe("transform names to kebab case", () => {
+  it("should transform a token path to token name in a kebab case format", () => {
+    const mockToken = {
+      name: "current-name",
+      path: ["test", "token", "name"],
+      value: "fake-value",
+      filePath: "./fakePath.json",
+      original: {
+        value: "fake-value",
+        type: "composite",
+      },
+      isSource: true,
+    };
+    expect(nameKebabCase(mockToken, {})).toBe("test-token-name");
+  });
+
+  it("should add prefix to token name", () => {
+    const mockToken = {
+      name: "current-name",
+      path: ["test", "token", "name"],
+      value: "fake-value",
+      filePath: "./fakePath.json",
+      original: {
+        value: "fake-value",
+        type: "composite",
+      },
+      isSource: true,
+    };
+    const mockOptions = {
+      prefix: "calcite",
+    };
+    expect(nameKebabCase(mockToken, mockOptions)).toBe("calcite-test-token-name");
+  });
+});

package/support/token-transformer/transform/nameKebabCase.ts

@@ -0,0 +1,26 @@
+import { paramCase } from "change-case";
+import { TransformedToken } from "style-dictionary/types/TransformedToken.js";
+import { Options } from "style-dictionary/types/Options.js";
+import { parseTokenPath } from "../utils/parseTokenPath.js";
+
+/**
+ * convert token name to kebab case
+ *
+ * @param {TransformedToken} token Style Dictionary token object
+ * @param {Options} options Style Dictionary format options
+ * @returns {string} an updated name for the token which will be used for the final output
+ */
+export function nameKebabCase(token: TransformedToken, options: Options): string {
+  const paths = token.path.reduce((acc, p, idx) => {
+    if (p === "core") {
+      acc.push("app");
+    } else if (typeof token.path[idx + 1] === "string" && !new RegExp(`${p}`).test(token.path[idx + 1])) {
+      acc.push(p);
+    } else if (idx === token.path.length - 1) {
+      acc.push(p);
+    }
+    return acc;
+  }, []);
+
+  return paramCase([options.prefix].concat(parseTokenPath(paths)).join(" "));
+}