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

package/support/token-transformer/utils/compositeTokens.test.ts

@@ -0,0 +1,133 @@
+import { expandToken, shouldExpand } from "./compositeTokens";
+
+const mockHandleValue = jest.fn((val) => val);
+
+describe("expand composite token", () => {
+  it("should expand a non-shadow token", () => {
+    const mockTypographyToken = {
+      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 mockExpandedTypographyToken = {
+      "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 testExpandToken = expandToken(mockTypographyToken, false, mockHandleValue);
+    expect(testExpandToken).toMatchObject(mockExpandedTypographyToken);
+  });
+  it("should expand a shadow token", () => {
+    const mockShadowToken = {
+      value: [
+        {
+          x: "0",
+          y: "2",
+          blur: "8",
+          spread: "0",
+          color: "rgba($core.color.neutral.blk-240, $core.opacity.4)",
+          type: "dropShadow",
+        },
+        {
+          x: "0",
+          y: "4",
+          blur: "16",
+          spread: "0",
+          color: "rgba($core.color.neutral.blk-240, $core.opacity.8)",
+          type: "dropShadow",
+        },
+      ],
+      type: "boxShadow",
+    };
+    const mockExpandedShadowToken = {
+      "1": {
+        x: {
+          type: "dimension",
+          value: "0",
+        },
+        y: {
+          type: "dimension",
+          value: "2",
+        },
+        blur: {
+          type: "dimension",
+          value: "8",
+        },
+        spread: {
+          type: "dimension",
+          value: "0",
+        },
+        color: {
+          type: "color",
+          value: "rgba($core.color.neutral.blk-240, $core.opacity.4)",
+        },
+      },
+    };
+    const testExpandToken = expandToken(mockShadowToken, true, mockHandleValue);
+    expect(testExpandToken).toMatchObject(mockExpandedShadowToken);
+  });
+});
+
+describe("shouldExpand", () => {
+  const filePath = "./mockFile.json";
+  const mockToken = {
+    name: "testToken",
+    type: "fontFamilies",
+    value: "san-serif",
+  };
+
+  it("should return true", () => {
+    // @ts-expect-error - type is fine here.
+    const testExpand = shouldExpand(mockToken, true, filePath);
+    expect(testExpand).toBe(true);
+  });
+  it("should return false", () => {
+    // @ts-expect-error - type is fine here.
+    const testExpand = shouldExpand(mockToken, false, filePath);
+    expect(testExpand).toBe(false);
+  });
+  it("should use condition function", () => {
+    const mockExpandFunction = jest.fn(() => true);
+    // @ts-expect-error - type is fine here.
+    const testExpand = shouldExpand(mockToken, mockExpandFunction, filePath);
+    expect(testExpand).toBe(true);
+    expect(mockExpandFunction).toHaveBeenCalled();
+  });
+});

package/support/token-transformer/utils/compositeTokens.ts

@@ -0,0 +1,103 @@
+import { ExpandFilter } from "../utils/transformOptions";
+import { matchPlaceholderElement } from "./regex.js";
+import { DesignToken } from "style-dictionary/types/DesignToken";
+import { SingleToken } from "@tokens-studio/types";
+import { paramCase } from "change-case";
+
+// A customized type map based off Token Studio.
+// This determines the applied "type" associated with each Style Dictionary token value
+const typeMaps = {
+  boxShadow: {
+    x: "dimension",
+    y: "dimension",
+    blur: "dimension",
+    spread: "dimension",
+    type: "other",
+    color: "color",
+  },
+  border: {
+    width: "border-width",
+    style: "other",
+  },
+  composition: {
+    typography: "font-size",
+    fontWeight: "font-weight",
+  },
+  typography: {
+    fontFamily: "font-family",
+    fontWeight: "font-weights",
+    lineHeight: "line-heights",
+    fontSize: "font-size",
+    letterSpacing: "letter-spacing",
+    paragraphSpacing: "paragraph-spacing",
+    textDecoration: "font-style",
+    textCase: "text-case",
+  },
+};
+
+/**
+ * Get type from type map
+ *
+ * @param {string} key type
+ * @param {DesignToken} compositeToken a Style Dictionary token
+ * @returns {string} approved token type
+ */
+export const getType = (key: string, compositeToken: DesignToken): string => typeMaps[compositeToken.type][key] ?? key;
+
+/**
+ * This is a recursive function to dig into composite tokens and lift up the token values in a Style Dictionary format.
+ *
+ * @param {DesignToken} compositeToken the composite token object
+ * @param {boolean} isShadow is a drop shadow?
+ * @param {Function} handleValue a function to determine how the final token value string should be passed to Style Dictionary
+ * @returns {DesignToken} a single Style Dictionary token object
+ */
+export function expandToken(compositeToken: DesignToken, isShadow = false, handleValue = (v) => v): DesignToken {
+  const expandedObj = {} as DesignToken;
+
+  if (isShadow && Array.isArray(compositeToken.value)) {
+    compositeToken.value.forEach((shadow, index) => {
+      expandedObj[index + 1] = {};
+      Object.entries(shadow).forEach(([key, value]) => {
+        if (matchPlaceholderElement.test(`${value}`) || key === "type") {
+          return;
+        }
+        expandedObj[index + 1][key] = {
+          value: `${handleValue(value)}`,
+          type: getType(key, compositeToken),
+        };
+      });
+    });
+  } else {
+    Object.entries(compositeToken.value).forEach(([key, value]) => {
+      const newKey = paramCase(key);
+      if (matchPlaceholderElement.test(`${value}`)) {
+        return;
+      }
+      expandedObj[newKey] = {
+        value: `${handleValue(value)}`,
+        type: getType(key, compositeToken),
+      };
+    });
+  }
+
+  return expandedObj;
+}
+
+/**
+ *
+ * @param {DesignToken} token Style Dictionary token object
+ * @param {boolean |  ExpandFilter<SingleToken>} condition check if the token should be expanded or not
+ * @param {string} filePath the file path where the token came from
+ * @returns {boolean} if the token should be expanded
+ */
+export function shouldExpand<T extends SingleToken>(
+  token: T,
+  condition: boolean | ExpandFilter<T>,
+  filePath: string
+): boolean {
+  if (typeof condition === "function") {
+    return condition(token, filePath);
+  }
+  return condition;
+}

package/support/token-transformer/utils/convertTokenToStyleDictionaryFormat.ts

@@ -0,0 +1,20 @@
+/**
+ * Some tokens defined in Figma Token Studio do not used the common { [variable.name] } for token references.
+ * This function loops over each value, finds custom token references and converts them to the expected Style Dictionary format.
+ *
+ * @param {RegExp} customReferenceTokenIndicator a regex to find the token references
+ * @returns {Function} to convert the token to the reference format expected by Style Dictionary "{ [variable.name] }"
+ */
+export function convertTokenToStyleDictionaryFormat(
+  customReferenceTokenIndicator: RegExp
+): (value: string | number) => string {
+  return (value: string | number): string => {
+    let newValue = `${value}`;
+    const matchesArr = [...newValue.matchAll(customReferenceTokenIndicator)];
+    matchesArr.forEach((match) => {
+      const figmaVariable = match[0];
+      newValue = newValue.replace(figmaVariable, `{${figmaVariable.slice(1)}}`);
+    });
+    return newValue;
+  };
+}

package/support/token-transformer/utils/matchList.ts

@@ -0,0 +1,11 @@
+/**
+ * Find the string in a list
+ *
+ * @param {string} str the string to find in the list
+ * @param {string[]} list the list of strings to match with the provided string
+ * @param {RegExp} regexExclude a regular expression defining strings that should always be excluded
+ * @returns {boolean} does the string match the items in the list
+ */
+export const matchList = (str: string, list: string[], regexExclude: RegExp): boolean => {
+  return list.some((value) => str.includes(value) && !regexExclude.test(str));
+};

package/support/token-transformer/utils/parseName.ts

@@ -0,0 +1,18 @@
+import { paramCase } from "change-case";
+
+/**
+ * Used to set the file name for the generated theme file.
+ *
+ * @param {string} name the file name passed from the themes object
+ * @param {string} prefix an optional prefix for each file name
+ * @returns {string} a kebab-case file name from the passed name, optionally starting with a prefix
+ */
+export function parseName(name: string, prefix?: string): string {
+  const regexWord = /^\w+$/;
+  const themeName = `${prefix || ""} ${name}`
+    .split(" ")
+    .filter((word) => regexWord.test(word))
+    .join(" ");
+
+  return paramCase(themeName);
+}

package/support/token-transformer/utils/parseTokenPath.ts

@@ -0,0 +1,19 @@
+/**
+ * Replaces the word "color" with "ui" when it is the first value in the path and removes the word "default" from the final token names.
+ * This puts generated tokens in alignment with the theme variable names in Calcite-Colors
+ *
+ * @param {string[]} path the path to each token value in the Style Dictionary token object
+ * @returns {string[]} an updated token path
+ */
+export const parseTokenPath = (path: string[]): string[] =>
+  path.reduce((acc, p, idx) => {
+    if (idx === 0 && p === "color") {
+      acc.push("ui");
+    } else if (p === "default") {
+      return acc;
+    } else {
+      acc.push(p);
+    }
+
+    return acc;
+  }, []);

package/support/token-transformer/utils/regex.ts

@@ -0,0 +1,9 @@
+// Match files and tokens which include "[" or "]"
+export const matchPlaceholderElement = new RegExp(/[\[\]]/, "g");
+
+// Match custom variable indicator created by Designers in Token Studio.
+// Using the ${token.name} format in Token Studio makes it much easier for Designers to search for token references while doing their work.
+export const tokenStudioCustomVariableIndicator = new RegExp(/\$[.\w-]+/, "g");
+
+// Match files and tokens which include "backup", "[", "]", or file extensions
+export const matchExclusions = /(backup|\[|\])(?=\.\w+$)/;

package/support/token-transformer/utils/sortAllTokens.ts

@@ -0,0 +1,12 @@
+import { Dictionary } from "style-dictionary/types/Dictionary";
+import { default as StyleDictionary } from "style-dictionary";
+import { TransformedToken } from "style-dictionary/types/TransformedToken";
+
+export function sortAllTokens(dictionary: Dictionary, outputReferences: boolean): TransformedToken[] {
+  let tokens = dictionary.allTokens;
+  if (outputReferences) {
+    tokens = [...dictionary.allTokens].sort(StyleDictionary.formatHelpers["sortByReference"](dictionary));
+  }
+
+  return tokens;
+}

package/support/token-transformer/utils/transformOptions.ts

@@ -0,0 +1,31 @@
+import {
+  SingleBorderToken,
+  SingleBoxShadowToken,
+  SingleCompositionToken,
+  SingleToken,
+  SingleTypographyToken,
+} from "@tokens-studio/types";
+
+/**
+ * Copied from https://github.com/tokens-studio/sd-transforms/blob/main/src/TransformOptions.ts
+ * This is needed for correct type setting and is not exported by Token Studio SD Transforms.
+ */
+
+export type Expandables = SingleCompositionToken | SingleTypographyToken | SingleBorderToken | SingleBoxShadowToken;
+
+export const expandablesAsStringsArr = ["composition", "typography", "border", "boxShadow"];
+export type ExpandablesAsStrings = (typeof expandablesAsStringsArr)[number];
+
+export type ExpandFilter<T extends SingleToken> = (token: T, filePath: string) => boolean;
+
+export interface ExpandOptions {
+  typography?: boolean | ExpandFilter<SingleTypographyToken>;
+  border?: boolean | ExpandFilter<SingleBorderToken>;
+  shadow?: boolean | ExpandFilter<SingleBoxShadowToken>;
+  composition?: boolean | ExpandFilter<SingleCompositionToken>;
+}
+
+export interface TransformOptions {
+  expand?: ExpandOptions | false;
+  excludeParentKeys?: boolean;
+}

package/tsconfig-base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "allowUnreachableCode": false,
+    "declaration": false,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "lib": ["dom", "dom.iterable", "ES2021"],
+    "module": "esnext",
+    "moduleResolution": "node",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "target": "ES2021"
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig-eslint.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig-base.json",
+  "include": ["./**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig-base",
+  "include": ["support", "src"]
+}