@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/copy-css-utils-cli.js

@@ -1,9 +1,21 @@
 #!/usr/bin/env node
-/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * CLI tool for copying CSS utility files from hammer-token to a target project
+ * @module copy-css-utils-cli
+ */
 const { program } = require("commander");
 const path = require("path");
 const fs = require("fs");
 
+/**
+ * Runs the CLI program that provides the copy-css-utils command.
+ * This command copies all CSS utility files from the hammer-token build directory
+ * to a specified destination directory in the user's project.
+ * @returns {void}
+ * @example
+ * // From command line:
+ * // npx hammer-token copy-css-utils ./src/styles
+ */
 function run() {
   program
     .command("copy-css-utils")

package/src/utils/css-utils-format-utils.js

@@ -1,209 +1,119 @@
-const cssUtilsFormatter = (
-  dictionary,
-  generateFn,
-  { hasDark, prefix = "" },
-) => {
-  const result = dictionary.allTokens
-    .filter((token) => token.name.includes("color"))
-    .map((token) => {
-      const value = getVarValue(dictionary, token);
-      const name = `${token.name.replace("Default", "")}`;
-
-      if (hasDark && token.attributes.appearance) {
-        const darkValue = getVarValue(dictionary, token, { isDark: true });
-        return generateFn(name, value, { darkValue, prefix });
-      }
-      return generateFn(name, value, { prefix });
-    })
-    .flat()
-    .map((t) => `${t}`)
-    .sort((a, b) => a.localeCompare(b))
-    .join(`\n`);
-
-  const fallback = dictionary.allTokens
-    .map((token) => {
-      const value = getVarValue(dictionary, token);
-      const name = `${token.name.replace("Default", "")}`;
-      return generateFn(name, value, { prefix });
-    })
-    .flat()
-    .map((t) => `${t}`)
-    .sort((a, b) => a.localeCompare(b))
-    .join(`\n`);
-
-  return `@layer starter, reset, base, state, application;
-
-${fallback}
-${
-  result.length > 0
-    ? `\n@supports (color: light-dark(#fff, #000)) {
-  ${result.replaceAll("\n", "\n  ")}
-}`
-    : ""
-}
-    
-@layer application {
-  ${fallback.replaceAll("\n", "\n  ")}
-  ${
-    result.length > 0
-      ? `\n  @supports (color: light-dark(#fff, #000)) {
-    ${result.replaceAll("\n", "\n    ")}
-  }`
-      : ""
-  }
-}`;
-};
-
-const getNewValueFromRef = (value, ref) => {
-  return value.replace(ref.value, function () {
-    // fallback for nested vars
-    if (ref.name === undefined) {
-      return `${ref.value}`;
-    } else {
-      return `var(--${ref.name}, ${ref.value})`;
-    }
-  });
-};
-
-const colorHasAlphaValue = (value) => {
-  // e.g. var(--something)44 isn't valid
-  return /\)[\d]+/.test(value);
-};
-
 /**
- * Allow for CSS var instead of static value
+ * CSS utility class generation functions for Style Dictionary
+ * @module css-utils-format-utils
  */
-const getVarValue = (dictionary, token, { isDark } = {}) => {
-  let value;
-
-  if (isDark) {
-    value = JSON.stringify(token.attributes.appearance.dark.value);
-    if (
-      dictionary.usesReference(token.original.attributes.appearance.dark.value)
-    ) {
-      const refs = dictionary.getReferences(
-        token.original.attributes.appearance.dark.value,
-      );
-      refs.forEach((ref) => {
-        const newValue = getNewValueFromRef(value, ref);
-        if (colorHasAlphaValue(newValue) === false) {
-          value = newValue;
-        }
-      });
-    }
-  } else {
-    value = JSON.stringify(token.value);
-    if (dictionary.usesReference(token.original.value)) {
-      const refs = dictionary.getReferences(token.original.value);
-      refs.forEach((ref) => {
-        const newValue = getNewValueFromRef(value, ref);
-        if (colorHasAlphaValue(newValue) === false) {
-          value = newValue;
-        }
-      });
-    }
-  }
-
-  return value.replaceAll('"', "");
-};
-
-const removeDefaultFromName = (name) => {
-  return name.replace("-default", "");
-};
 
+/**
+ * Generates CSS utility classes for border tokens (radius, width, color).
+ * @param {string} name - The token name
+ * @param {string} value - The token value
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.darkValue] - The dark mode value for light-dark() support
+ * @param {string} [options.prefix=''] - CSS class prefix
+ * @param {string} [options.cssVarPrefix=''] - CSS variable prefix (e.g., 'a2-')
+ * @returns {string[]} Array of CSS class declarations
+ * @example
+ * generateBorderClasses('border-radius-small', '4px', { prefix: 'a2-', cssVarPrefix: 'a2-' })
+ * // Returns: ['.a2-border-radius-small {border-radius: var(--a2-border-radius-small, 4px)}']
+ */
 const generateBorderClasses = (
   name,
   value,
-  { darkValue, prefix = "" } = {},
+  { darkValue, prefix = "", cssVarPrefix = "" } = {},
 ) => {
   const classes = [];
+  const cssVar = `${cssVarPrefix}${name}`;
 
   if (name.startsWith("border-radius")) {
     classes.push(
-      `.${prefix}${name} {border-radius: var(--${removeDefaultFromName(name)}, ${value})}`,
+      `.${prefix}${name} {border-radius: var(--${cssVar}, ${value})}`,
     );
   } else if (name.startsWith("border-width")) {
     classes.push(
-      `.${prefix}${name} {border-width: var(--${removeDefaultFromName(name)}, ${value})}`,
+      `.${prefix}${name} {border-width: var(--${cssVar}, ${value})}`,
     );
   } else if (name.startsWith("border-color")) {
     if (darkValue) {
       classes.push(
-        `.${prefix}${name} {border-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
+        `.${prefix}${name} {border-color: var(--${cssVar}, light-dark(${value}, ${darkValue}))}`,
       );
     } else {
       classes.push(
-        `.${prefix}${name} {border-color: var(--${removeDefaultFromName(name)}, ${value})}`,
+        `.${prefix}${name} {border-color: var(--${cssVar}, ${value})}`,
       );
     }
   }
   return classes;
 };
 
-const generateColorClasses = (name, value, { darkValue, prefix = "" } = {}) => {
+/**
+ * Generates CSS utility classes for color tokens (background, foreground, status, overlay, border).
+ * Creates appropriate class names based on the token type (bg-, c-, bg-status-, etc.).
+ * @param {string} name - The token name
+ * @param {string} value - The token value
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.darkValue] - The dark mode value for light-dark() support
+ * @param {string} [options.prefix=''] - CSS class prefix
+ * @param {string} [options.cssVarPrefix=''] - CSS variable prefix (e.g., 'a2-')
+ * @returns {string[]} Array of CSS class declarations
+ * @example
+ * generateColorClasses('background-color-primary', '#fff', { prefix: 'a2-', cssVarPrefix: 'a2-' })
+ * // Returns: ['.a2-bg-primary {background-color: var(--a2-background-color-primary, #fff)}']
+ */
+const generateColorClasses = (
+  name,
+  value,
+  { darkValue, prefix = "", cssVarPrefix = "" } = {},
+) => {
   const classes = [];
+  const resolvedValue = darkValue
+    ? `light-dark(${value}, ${darkValue})`
+    : value;
+  const cssVar = `${cssVarPrefix}${name}`;
 
-  if (darkValue) {
-    if (name.startsWith("background-color")) {
-      classes.push(
-        `.${prefix}${name.replace("background-color", "bg")} {background-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-      );
-    } else if (name.startsWith("foreground-color")) {
-      classes.push(
-        `.${prefix}${name.replace("foreground-color", "c")} {color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-      );
-    } else if (name.startsWith("overlay-color")) {
-      classes.push(
-        `.${prefix}${name.replace("overlay-color", "bg-overlay")} {background-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-      );
-    } else if (name.startsWith("status-color")) {
-      classes.push(
-        `.${prefix}${name.replace("status-color", "c-status")} {color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-        `.${prefix}${name.replace("status-color", "bg-status")} {background-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-      );
-      if (!name.includes("danger")) {
-        classes.push(
-          `.${prefix}${name.replace("status-color", "border-color-status")} {border-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-        );
-      }
-    } else if (name.startsWith("border-color")) {
-      classes.push(
-        `.${prefix}${name} {border-color: var(--${removeDefaultFromName(name)}, light-dark(${value}, ${darkValue}))}`,
-      );
-    }
-  } else {
-    if (name.startsWith("background-color")) {
-      classes.push(
-        `.${prefix}${name.replace("background-color", "bg")} {background-color: var(--${removeDefaultFromName(name)}, ${value})}`,
-      );
-    } else if (name.startsWith("foreground-color")) {
-      classes.push(
-        `.${prefix}${name.replace("foreground-color", "c")} {color: var(--${removeDefaultFromName(name)}, ${value})}`,
-      );
-    } else if (name.startsWith("overlay-color")) {
-      classes.push(
-        `.${prefix}${name.replace("overlay-color", "bg-overlay")} {background-color: var(--${removeDefaultFromName(name)}, ${value})}`,
-      );
-    } else if (name.startsWith("status-color")) {
-      classes.push(
-        `.${prefix}${name.replace("status-color", "c-status")} {color: var(--${removeDefaultFromName(name)}, ${value})}`,
-        `.${prefix}${name.replace("status-color", "bg-status")} {background-color: var(--${removeDefaultFromName(name)}, ${value})}`,
-      );
-      if (!name.includes("danger")) {
-        classes.push(
-          `.${prefix}${name.replace("status-color", "border-color-status")} {border-color: var(--${removeDefaultFromName(name)}, ${value})}`,
-        );
-      }
-    } else if (name.startsWith("border-color")) {
+  if (name.startsWith("background-color")) {
+    classes.push(
+      `.${prefix}${name.replace("background-color", "bg")} {background-color: var(--${cssVar}, ${resolvedValue})}`,
+    );
+  } else if (name.startsWith("foreground-color")) {
+    classes.push(
+      `.${prefix}${name.replace("foreground-color", "c")} {color: var(--${cssVar}, ${resolvedValue})}`,
+    );
+  } else if (name.startsWith("overlay-color")) {
+    classes.push(
+      `.${prefix}${name.replace("overlay-color", "bg-overlay")} {background-color: var(--${cssVar}, ${resolvedValue})}`,
+    );
+  } else if (name.startsWith("status-color")) {
+    classes.push(
+      `.${prefix}${name.replace("status-color", "c-status")} {color: var(--${cssVar}, ${resolvedValue})}`,
+      `.${prefix}${name.replace("status-color", "bg-status")} {background-color: var(--${cssVar}, ${resolvedValue})}`,
+    );
+    if (!name.includes("danger")) {
       classes.push(
-        `.${prefix}${name} {border-color: var(--${removeDefaultFromName(name)}, ${value})}`,
+        `.${prefix}${name.replace("status-color", "border-color-status")} {border-color: var(--${cssVar}, ${resolvedValue})}`,
       );
     }
+  } else if (name.startsWith("border-color")) {
+    classes.push(
+      `.${prefix}${name} {border-color: var(--${cssVar}, ${resolvedValue})}`,
+    );
   }
 
   return classes;
 };
 
+/**
+ * Generates CSS utility classes for typography tokens (font-family, font-weight, font-size).
+ * Creates class names with ff-, fw-, fs- prefixes based on the typography property.
+ * @param {string} name - The token name
+ * @param {string} value - The token value
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.prefix=''] - CSS class prefix
+ * @returns {string[]} Array of CSS class declarations
+ * @example
+ * generateFontClasses('typography-body-font-family', 'Arial', { prefix: 'a2-' })
+ * // Returns: ['.a2-ff-body {font-family: Arial}']
+ */
 const generateFontClasses = (name, value, { prefix = "" } = {}) => {
   const classes = [];
 
@@ -226,7 +136,27 @@ const generateFontClasses = (name, value, { prefix = "" } = {}) => {
   return classes;
 };
 
-const generateSpacingClasses = (name, value, { prefix = "" } = {}) => {
+/**
+ * Generates CSS utility classes for spacing/size tokens (margin, padding).
+ * Creates classes for all logical property directions (inline-start, inline-end, block-start, etc.).
+ * @param {string} name - The token name (e.g., 'size-4')
+ * @param {string} value - The token value (e.g., '1rem')
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.prefix=''] - CSS class prefix
+ * @param {string} [options.cssVarPrefix=''] - CSS variable prefix (e.g., 'a2-')
+ * @returns {string[]} Array of CSS class declarations for margin and padding utilities
+ * @example
+ * generateSpacingClasses('size-4', '1rem', { prefix: 'a2-' })
+ * // Returns array including:
+ * // '.a2-m-inline-start-4 {margin-inline-start: var(--a2-size-4, 1rem)}'
+ * // '.a2-p-inline-start-4 {padding-inline-start: var(--a2-size-4, 1rem)}'
+ * // ... and more for each direction
+ */
+const generateSpacingClasses = (
+  name,
+  value,
+  { prefix = "", cssVarPrefix = "" } = {},
+) => {
   const nameWithoutPrefix = name.substring(name.indexOf("-"));
 
   const directions = [
@@ -238,28 +168,27 @@ const generateSpacingClasses = (name, value, { prefix = "" } = {}) => {
     "inline",
   ];
   const classes = [];
+  const cssVar = `${cssVarPrefix}${name}`;
 
   directions.forEach((direction) => {
     classes.push(
-      `.${prefix}m-${direction}${nameWithoutPrefix} {margin-${direction}: var(--${name}, ${value})}`,
+      `.${prefix}m-${direction}${nameWithoutPrefix} {margin-${direction}: var(--${cssVar}, ${value})}`,
     );
     classes.push(
-      `.${prefix}p-${direction}${nameWithoutPrefix} {padding-${direction}: var(--${name}, ${value})}`,
+      `.${prefix}p-${direction}${nameWithoutPrefix} {padding-${direction}: var(--${cssVar}, ${value})}`,
     );
   });
   classes.push(
-    `.${prefix}m${nameWithoutPrefix} {margin: var(--${name}, ${value})}`,
+    `.${prefix}m${nameWithoutPrefix} {margin: var(--${cssVar}, ${value})}`,
   );
   classes.push(
-    `.${prefix}p${nameWithoutPrefix} {padding: var(--${name}, ${value})}`,
+    `.${prefix}p${nameWithoutPrefix} {padding: var(--${cssVar}, ${value})}`,
   );
 
   return classes;
 };
 
 module.exports = {
-  cssUtilsFormatter,
-  getVarValue,
   generateBorderClasses,
   generateColorClasses,
   generateFontClasses,