@servicetitan/hammer-token 0.0.0-rc-1.48.0-20251104214834 → 0.0.0-rc-3.0.0-20260114215531

package/src/theme/core/status.tokens.json

@@ -0,0 +1,70 @@
+{
+  "status": {
+    "color": {
+      "info": {
+        "$type": "color",
+        "$value": "{color.blue.500}",
+        "$extensions": {
+          "appearance": {
+            "light": {
+              "$type": "color",
+              "$value": "{color.blue.500}"
+            },
+            "dark": {
+              "$type": "color",
+              "$value": "{color.blue.100}"
+            }
+          }
+        }
+      },
+      "danger": {
+        "$type": "color",
+        "$value": "{color.red.500}",
+        "$extensions": {
+          "appearance": {
+            "light": {
+              "$type": "color",
+              "$value": "{color.red.500}"
+            },
+            "dark": {
+              "$type": "color",
+              "$value": "{color.red.100}"
+            }
+          }
+        }
+      },
+      "success": {
+        "$type": "color",
+        "$value": "{color.green.500}",
+        "$extensions": {
+          "appearance": {
+            "light": {
+              "$type": "color",
+              "$value": "{color.green.500}"
+            },
+            "dark": {
+              "$type": "color",
+              "$value": "{color.green.100}"
+            }
+          }
+        }
+      },
+      "warning": {
+        "$type": "color",
+        "$value": "{color.yellow.500}",
+        "$extensions": {
+          "appearance": {
+            "light": {
+              "$type": "color",
+              "$value": "{color.yellow.500}"
+            },
+            "dark": {
+              "$type": "color",
+              "$value": "{color.yellow.100}"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/theme/core/typography.tokens.json

@@ -0,0 +1,100 @@
+{
+  "typography": {
+    "paragraph": {
+      "size": {
+        "xsmall": {
+          "$type": "dimension",
+          "$value": "{font.size.200}"
+        },
+        "small": {
+          "$type": "dimension",
+          "$value": "{font.size.300}"
+        },
+        "default": {
+          "$type": "dimension",
+          "$value": "{font.size.400}"
+        },
+        "large": {
+          "$type": "dimension",
+          "$value": "{font.size.500}"
+        },
+        "xlarge": {
+          "$type": "dimension",
+          "$value": "{font.size.600}"
+        }
+      },
+      "font-weight": {
+        "$type": "number",
+        "$value": "{font.weight.normal}"
+      },
+      "font-family": {
+        "$type": "string",
+        "$value": "{font.family.base}"
+      }
+    },
+    "heading": {
+      "size": {
+        "xsmall": {
+          "$type": "dimension",
+          "$value": "{font.size.300}"
+        },
+        "small": {
+          "$type": "dimension",
+          "$value": "{font.size.400}"
+        },
+        "default": {
+          "$type": "dimension",
+          "$value": "{font.size.500}"
+        },
+        "large": {
+          "$type": "dimension",
+          "$value": "{font.size.600}"
+        },
+        "xlarge": {
+          "$type": "dimension",
+          "$value": "{font.size.800}"
+        }
+      },
+      "font-weight": {
+        "$type": "number",
+        "$value": "{font.weight.bold}"
+      },
+      "font-family": {
+        "$type": "string",
+        "$value": "{font.family.display}"
+      }
+    },
+    "label": {
+      "size": {
+        "xsmall": {
+          "$type": "dimension",
+          "$value": "{font.size.100}"
+        },
+        "small": {
+          "$type": "dimension",
+          "$value": "{font.size.200}"
+        },
+        "default": {
+          "$type": "dimension",
+          "$value": "{font.size.300}"
+        },
+        "large": {
+          "$type": "dimension",
+          "$value": "{font.size.400}"
+        },
+        "xlarge": {
+          "$type": "dimension",
+          "$value": "{font.size.500}"
+        }
+      },
+      "font-weight": {
+        "$type": "number",
+        "$value": "{font.weight.semibold}"
+      },
+      "font-family": {
+        "$type": "string",
+        "$value": "{font.family.base}"
+      }
+    }
+  }
+}

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

@@ -1,9 +1,22 @@
 #!/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,3 +1,18 @@
+/**
+ * CSS utility class generation functions for Style Dictionary
+ * @module css-utils-format-utils
+ */
+
+/**
+ * Formats a dictionary of tokens into CSS utility classes with layer structure and @supports blocks.
+ * This is a legacy formatter that handles both light and dark mode tokens.
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Function} generateFn - The function to generate CSS classes for each token
+ * @param {Object} options - Formatter options
+ * @param {boolean} options.hasDark - Whether the tokens include dark mode variants
+ * @param {string} [options.prefix=''] - CSS class prefix
+ * @returns {string} The complete CSS output with layer declarations and @supports blocks
+ */
 const cssUtilsFormatter = (
   dictionary,
   generateFn,
@@ -54,6 +69,14 @@ ${
 }`;
 };
 
+/**
+ * Creates a new value string by replacing a reference with a CSS var() fallback.
+ * @param {string} value - The original value string containing the reference
+ * @param {Object} ref - The reference object from Style Dictionary
+ * @param {string} [ref.value] - The resolved value of the reference
+ * @param {string} [ref.name] - The name of the referenced token
+ * @returns {string} The value with the reference replaced by var(--name, value) or just the value
+ */
 const getNewValueFromRef = (value, ref) => {
   return value.replace(ref.value, function () {
     // fallback for nested vars
@@ -65,13 +88,28 @@ const getNewValueFromRef = (value, ref) => {
   });
 };
 
+/**
+ * Checks if a color value has an alpha value appended after a CSS var.
+ * This pattern (e.g., var(--something)44) is invalid in CSS.
+ * @param {string} value - The value to check
+ * @returns {boolean} True if the value contains an invalid alpha pattern
+ * @example
+ * colorHasAlphaValue('var(--color)44') // true
+ * colorHasAlphaValue('var(--color, #fff)') // false
+ */
 const colorHasAlphaValue = (value) => {
   // e.g. var(--something)44 isn't valid
   return /\)[\d]+/.test(value);
 };
 
 /**
- * Allow for CSS var instead of static value
+ * Gets the value of a token with CSS variable references resolved to var() syntax.
+ * Supports both light and dark mode values.
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Object} token - The token to get the value for
+ * @param {Object} [options] - Options for value resolution
+ * @param {boolean} [options.isDark=false] - Whether to get the dark mode value
+ * @returns {string} The token value with references converted to CSS var() syntax
  */
 const getVarValue = (dictionary, token, { isDark } = {}) => {
   let value;
@@ -107,10 +145,29 @@ const getVarValue = (dictionary, token, { isDark } = {}) => {
   return value.replaceAll('"', "");
 };
 
+/**
+ * Removes the '-default' suffix from a token name.
+ * @param {string} name - The token name
+ * @returns {string} The name without the '-default' suffix
+ * @example
+ * removeDefaultFromName('color-primary-default') // 'color-primary'
+ */
 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
+ * @returns {string[]} Array of CSS class declarations
+ * @example
+ * generateBorderClasses('border-radius-small', '4px', { prefix: 'a2-' })
+ * // Returns: ['.a2-border-radius-small {border-radius: var(--border-radius-small, 4px)}']
+ */
 const generateBorderClasses = (
   name,
   value,
@@ -140,6 +197,19 @@ const generateBorderClasses = (
   return classes;
 };
 
+/**
+ * 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
+ * @returns {string[]} Array of CSS class declarations
+ * @example
+ * generateColorClasses('background-color-primary', '#fff', { prefix: 'a2-' })
+ * // Returns: ['.a2-bg-primary {background-color: var(--background-color-primary, #fff)}']
+ */
 const generateColorClasses = (name, value, { darkValue, prefix = "" } = {}) => {
   const classes = [];
 
@@ -204,6 +274,18 @@ const generateColorClasses = (name, value, { darkValue, prefix = "" } = {}) => {
   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,6 +308,21 @@ const generateFontClasses = (name, value, { prefix = "" } = {}) => {
   return classes;
 };
 
+/**
+ * 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
+ * @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(--size-4, 1rem)}'
+ * // '.a2-p-inline-start-4 {padding-inline-start: var(--size-4, 1rem)}'
+ * // ... and more for each direction
+ */
 const generateSpacingClasses = (name, value, { prefix = "" } = {}) => {
   const nameWithoutPrefix = name.substring(name.indexOf("-"));