@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/figma/token-conversion.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+
+/**
+ * Token Conversion Utilities
+ *
+ * Functions for converting token values to Figma variable format.
+ */
+
+/**
+ * Convert color value to Figma format
+ * Figma expects RGBA object: { r: 0-1, g: 0-1, b: 0-1, a: 0-1 }
+ * @param {any} colorValue - Color value to convert
+ * @returns {Object|null} Figma color object or null if conversion fails
+ */
+function convertColorValue(colorValue) {
+  if (typeof colorValue !== "string") {
+    // Handle composite color objects
+    if (colorValue && typeof colorValue === "object" && colorValue.color) {
+      const baseColor = convertColorValue(colorValue.color);
+      if (baseColor === null) {
+        return null;
+      }
+      return {
+        ...baseColor,
+        a: colorValue.alpha ?? baseColor.a,
+      };
+    }
+    return null;
+  }
+
+  // Handle rgba/rgb strings
+  const rgbaMatch = colorValue.match(
+    /rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/,
+  );
+  if (rgbaMatch) {
+    return {
+      r: parseInt(rgbaMatch[1]) / 255,
+      g: parseInt(rgbaMatch[2]) / 255,
+      b: parseInt(rgbaMatch[3]) / 255,
+      a: rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1,
+    };
+  }
+
+  // Handle hex colors
+  const hexMatch = colorValue.match(/^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/);
+  if (hexMatch) {
+    const r = parseInt(hexMatch[1].substring(0, 2), 16) / 255;
+    const g = parseInt(hexMatch[1].substring(2, 4), 16) / 255;
+    const b = parseInt(hexMatch[1].substring(4, 6), 16) / 255;
+    const a = hexMatch[2] ? parseInt(hexMatch[2], 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+
+  // Handle 3-digit hex
+  const hex3Match = colorValue.match(/^#([0-9a-fA-F]{3})$/);
+  if (hex3Match) {
+    const hex = hex3Match[1];
+    const r = parseInt(hex[0] + hex[0], 16) / 255;
+    const g = parseInt(hex[1] + hex[1], 16) / 255;
+    const b = parseInt(hex[2] + hex[2], 16) / 255;
+    return { r, g, b, a: 1 };
+  }
+
+  // Handle transparent
+  if (colorValue === "transparent") {
+    return { r: 0, g: 0, b: 0, a: 0 };
+  }
+
+  return null;
+}
+
+/**
+ * Convert a CSS font-family value to a single font name for Figma.
+ * Figma expects one font name; CSS allows a comma-separated stack with generic fallbacks.
+ * e.g. "'Nunito Sans', sans-serif" -> "Nunito Sans", "'Sofia Pro', SofiaPro, sans-serif" -> "Sofia Pro"
+ * @param {string} cssFontFamily - CSS font-family string (may be quoted, comma-separated)
+ * @returns {string} Single font name with quotes stripped
+ */
+function cssFontFamilyToFigmaFontName(cssFontFamily) {
+  if (typeof cssFontFamily !== "string") return cssFontFamily;
+  const first = cssFontFamily.split(",")[0].trim();
+  const unquoted = first.replace(/^["']|["']$/g, "").trim();
+  return unquoted || first;
+}
+
+/** Base font size for rem-to-px conversion (1rem = 16px) */
+const REM_BASE_PX = 16;
+
+/** Figma does not support percentage for dimensions; 100% (circular radius) is the only outlier we map, to 5000px. */
+const CIRCULAR_RADIUS_PX = 5000;
+
+/**
+ * Convert a numeric dimension and unit to pixels (as a number).
+ * rem is converted to px using REM_BASE_PX; px is returned as-is.
+ * Only 100% is converted (to 5000px); other percentages are not supported by Figma.
+ * @param {number} num - Numeric value
+ * @param {string} [unit] - Unit (e.g. "rem", "px", "%")
+ * @returns {number|null} Value in pixels, or null if unit is % and num is not 100
+ */
+function dimensionToPx(num, unit) {
+  if (unit === "rem") {
+    return num * REM_BASE_PX;
+  }
+  if (unit === "%") {
+    return num === 100 ? CIRCULAR_RADIUS_PX : null;
+  }
+  return num;
+}
+
+/**
+ * Convert dimension value to Figma number format (pixels).
+ * Figma variables support FLOAT type for dimensions; we store px values.
+ * rem units are converted to px (e.g. 2rem → 32).
+ * @param {any} dimensionValue - Dimension value to convert (object with value/unit, or string like "2rem"/"32px")
+ * @returns {number|null} Numeric value in pixels, or null if conversion fails
+ */
+function convertDimensionValue(dimensionValue) {
+  if (
+    typeof dimensionValue === "object" &&
+    dimensionValue.value !== undefined
+  ) {
+    const num = Number(dimensionValue.value);
+    if (Number.isNaN(num)) return null;
+    const unit = dimensionValue.unit ?? "px";
+    return dimensionToPx(num, unit);
+  }
+  if (typeof dimensionValue === "string") {
+    // Match number and optional unit: "16px", "1.5rem", "24", "100%" (Figma has no %; 100% → 5000px)
+    const match = dimensionValue.match(/^([\d.]+)\s*(px|rem|%)?$/);
+    if (match) {
+      const num = parseFloat(match[1]);
+      const unit = match[2] ?? "px";
+      return dimensionToPx(num, unit);
+    }
+  }
+  if (typeof dimensionValue === "number") {
+    return dimensionValue;
+  }
+  return null;
+}
+
+/**
+ * Convert line-height from decimal (1 = 100%) to Figma percentage string ("100%").
+ * @param {number|string} value - Decimal line-height (e.g. 1.5 = 150%)
+ * @returns {string} Percentage string for Figma (e.g. "150%")
+ */
+function lineHeightToFigmaPercent(value) {
+  const num = typeof value === "number" ? value : parseFloat(value);
+  if (Number.isNaN(num)) return value;
+  const pct = num * 100;
+  return `${Number.isInteger(pct) ? pct : Number(pct.toFixed(2))}%`;
+}
+
+/**
+ * Check if options indicate a line-height token (path or variable name).
+ * @param {{ tokenPath?: string, variableName?: string }} [options]
+ * @returns {boolean}
+ */
+function isLineHeightContext(options) {
+  if (!options) return false;
+  const path = options.tokenPath ?? options.variableName ?? "";
+  return typeof path === "string" && path.includes("line-height");
+}
+
+/**
+ * Check if options indicate a font-family token (path or variable name).
+ * Used so we only collapse comma-separated font stacks to a single name for Figma;
+ * other comma-containing strings (e.g. cubic-bezier) are left intact.
+ * @param {{ tokenPath?: string, variableName?: string }} [options]
+ * @returns {boolean}
+ */
+function isFontFamilyContext(options) {
+  if (!options) return false;
+  const path = options.tokenPath ?? options.variableName ?? "";
+  return (
+    typeof path === "string" &&
+    (path.includes("font/family") || path.includes("font-family"))
+  );
+}
+
+/**
+ * Convert token value to Figma variable value based on type
+ * @param {string} tokenType - Token type (color, dimension, etc.)
+ * @param {any} value - Value to convert
+ * @param {{ tokenPath?: string, variableName?: string, scopes?: string[] }} [options] - Optional token path or variable name for context (e.g. line-height → %)
+ * @returns {any} Converted value for Figma
+ */
+function convertTokenValueToFigma(tokenType, value, options) {
+  switch (tokenType) {
+    case "color":
+      return convertColorValue(value);
+    case "dimension":
+    case "duration":
+      // If the value is a string with spaces (e.g., "0rem 0rem 0rem"),
+      // treat it as a string since Figma doesn't support space-separated dimension values
+      if (typeof value === "string" && value.includes(" ")) {
+        return value;
+      }
+      // Opacity scope: Figma expects 0–100 (percentage), tokens use 0–1 (decimal)
+      if (
+        Array.isArray(options?.scopes) &&
+        options.scopes.includes("OPACITY")
+      ) {
+        const num = typeof value === "number" ? value : parseFloat(value);
+        if (!Number.isNaN(num)) return num * 100;
+      }
+      return convertDimensionValue(value);
+    case "number":
+      // Line-height: tokens use decimal (1 = 100%); Figma expects % string (e.g. "150%")
+      if (isLineHeightContext(options)) {
+        return lineHeightToFigmaPercent(value);
+      }
+      return typeof value === "number" ? value : parseFloat(value);
+    case "string":
+      // Figma font family expects a single font name; CSS uses comma-separated stacks.
+      // Only collapse to first name when we're in a font-family context so we don't
+      // truncate other comma-containing strings (e.g. cubic-bezier(.4, 0, .2, 1)).
+      if (
+        typeof value === "string" &&
+        isFontFamilyContext(options) &&
+        (value.includes(",") || /^["'].*["']$/.test(value.trim()))
+      ) {
+        return cssFontFamilyToFigmaFontName(value);
+      }
+      return value;
+    default:
+      // For unknown types, try to extract value from objects with a value property
+      // This handles cases where tokens have structured values like {value: 200, unit: "ms"}
+      if (
+        typeof value === "object" &&
+        value !== null &&
+        value.value !== undefined
+      ) {
+        return convertDimensionValue(value);
+      }
+      // If it's a string with spaces, return as string
+      if (typeof value === "string" && value.includes(" ")) {
+        return value;
+      }
+      return value;
+  }
+}
+
+/**
+ * Get Figma variable type from token type
+ * @param {string} tokenType - Token type
+ * @returns {string} Figma variable type (COLOR, FLOAT, or STRING)
+ */
+function getFigmaVariableType(tokenType) {
+  switch (tokenType) {
+    case "color":
+      return "COLOR";
+    case "dimension":
+    case "duration":
+    case "number":
+      return "FLOAT";
+    case "string":
+      return "STRING";
+    default:
+      return "STRING";
+  }
+}
+
+/**
+ * Check if a token path is a shadow size token
+ * @param {string} tokenPath - Token path
+ * @returns {boolean} True if token is a shadow size token
+ */
+function isShadowSizeToken(tokenPath) {
+  return tokenPath.startsWith("shadow/size/");
+}
+
+/**
+ * Parse a shadow size value string to extract x, y, blur references
+ * Returns {x, y, blur} or null if parsing fails
+ * Example: "{size.0} {size.0} {size.0}" -> {x: "size.0", y: "size.0", blur: "size.0"}
+ * @param {string} value - Shadow size value string
+ * @returns {Object|null} Parsed shadow components or null
+ */
+function parseShadowSizeValue(value) {
+  if (typeof value !== "string") return null;
+
+  // Match pattern like "{ref1} {ref2} {ref3}" (three space-separated references)
+  const match = value.match(/^\{([^}]+)\}\s+\{([^}]+)\}\s+\{([^}]+)\}$/);
+  if (!match) return null;
+
+  return {
+    x: match[1], // e.g., "size.0"
+    y: match[2], // e.g., "size.0"
+    blur: match[3], // e.g., "size.0"
+  };
+}
+
+/**
+ * Check if a token type is a gradient type
+ * @param {string} tokenType - Token type
+ * @returns {boolean}
+ */
+function isGradientToken(tokenType) {
+  return tokenType === "gradient";
+}
+
+/**
+ * Parse gradient stops from a gradient token, extracting per-stop light/dark color refs.
+ * Returns null if the token value is not a resolved gradient object.
+ * Component tokens reference a semantic gradient token, so the raw $value may be a
+ * reference string — pass the actual gradient object (already resolved) as gradientValue.
+ *
+ * @param {Object} gradientValue - Gradient $value object { type, angle, stops[] }
+ * @returns {Array<{lightRef: string, darkRef: string}>|null}
+ */
+function parseGradientStops(gradientValue) {
+  if (
+    !gradientValue ||
+    typeof gradientValue !== "object" ||
+    !Array.isArray(gradientValue.stops)
+  ) {
+    return null;
+  }
+
+  return gradientValue.stops.map((stop) => {
+    const lightRef =
+      stop.color?.$extensions?.appearance?.light?.$value ?? stop.color?.$value;
+    const darkRef =
+      stop.color?.$extensions?.appearance?.dark?.$value ?? stop.color?.$value;
+    return { lightRef, darkRef };
+  });
+}
+
+module.exports = {
+  convertColorValue,
+  convertDimensionValue,
+  cssFontFamilyToFigmaFontName,
+  convertTokenValueToFigma,
+  getFigmaVariableType,
+  isShadowSizeToken,
+  parseShadowSizeValue,
+  isGradientToken,
+  parseGradientStops,
+};

package/src/utils/figma/token-parsing.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * Token Parsing Utilities
+ *
+ * Functions for loading, parsing, and processing token files.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// Configuration
+const TOKEN_SRC_DIR = path.join(__dirname, "../../");
+const THEME_DIR = path.join(TOKEN_SRC_DIR, "theme");
+
+/**
+ * Load all token JSON files recursively
+ * @param {string} dir - Directory to search
+ * @param {Array<string>} fileList - Accumulated file list
+ * @returns {Array<string>} Array of file paths
+ */
+function loadTokenFiles(dir, fileList = []) {
+  const files = fs.readdirSync(dir);
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+
+    if (stat.isDirectory()) {
+      loadTokenFiles(filePath, fileList);
+    } else if (file.endsWith(".tokens.json")) {
+      fileList.push(filePath);
+    }
+  }
+
+  return fileList;
+}
+
+/**
+ * Parse a token file and return the token object
+ * @param {string} filePath - Path to token file
+ * @returns {Object} Parsed token object
+ */
+function parseTokenFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Failed to parse token file ${filePath}: ${error.message}`);
+  }
+}
+
+/**
+ * Detect all themes in src/theme/ directory
+ * @returns {Array<string>} Array of theme names (e.g., ["core", "test"])
+ */
+function detectThemes() {
+  if (!fs.existsSync(THEME_DIR)) {
+    return ["core"]; // Default to core if theme directory doesn't exist
+  }
+
+  const themes = [];
+  const entries = fs.readdirSync(THEME_DIR, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      themes.push(entry.name);
+    }
+  }
+
+  // Ensure "core" is first if it exists
+  if (themes.includes("core")) {
+    themes.sort((a, b) => {
+      if (a === "core") return -1;
+      if (b === "core") return 1;
+      return a.localeCompare(b);
+    });
+  }
+
+  return themes.length > 0 ? themes : ["core"];
+}
+
+/**
+ * Load token files for a specific theme
+ * @param {string} themeName - Theme name (e.g., "core", "test")
+ * @returns {Array<string>} Array of file paths
+ */
+function loadThemeTokenFiles(themeName) {
+  const themePath = path.join(THEME_DIR, themeName);
+  if (!fs.existsSync(themePath)) {
+    return [];
+  }
+
+  // Also include global/primitive tokens (they're shared across themes)
+  // TOKEN_SRC_DIR is already packages/hammer-token/src/, so we don't need to add "src/" again
+  const globalPrimitivePath = path.join(TOKEN_SRC_DIR, "global/primitive");
+  const files = [];
+
+  // Load primitive tokens (shared)
+  if (fs.existsSync(globalPrimitivePath)) {
+    loadTokenFiles(globalPrimitivePath, files);
+  }
+
+  // Load theme-specific tokens
+  loadTokenFiles(themePath, files);
+
+  return files;
+}
+
+/**
+ * Flatten token tree to a list of tokens with their paths
+ * @param {Object} obj - Token object to flatten
+ * @param {Array} path - Current path in the token tree
+ * @param {Array} tokens - Accumulated tokens array
+ * @param {string} sourceFilePath - Path to the source file (for determining token type)
+ * @returns {Array} Array of token objects with path information
+ */
+function flattenTokenTree(obj, path = [], tokens = [], sourceFilePath = "") {
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$schema" || key === "$type") {
+      continue;
+    }
+
+    const currentPath = [...path, key];
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (value.$type !== undefined || value.$value !== undefined) {
+        tokens.push({
+          path: currentPath,
+          token: value,
+          sourceFilePath,
+        });
+      } else {
+        flattenTokenTree(value, currentPath, tokens, sourceFilePath);
+      }
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Convert token path to Figma variable name (path-based with slashes)
+ * @param {Array<string>} tokenPath - Token path array
+ * @returns {string} Variable name with slashes
+ */
+function pathToVariableName(tokenPath) {
+  return tokenPath.join("/");
+}
+
+/**
+ * Determine if a token is a primitive token based on its source file path
+ * @param {string} sourceFilePath - Path to the source token file
+ * @returns {boolean} True if the token is a primitive token
+ */
+function isPrimitiveToken(sourceFilePath) {
+  if (!sourceFilePath) return false;
+  // Primitive tokens are in src/global/primitive/ directory
+  // Normalize path separators for cross-platform compatibility
+  const normalizedPath = sourceFilePath.replace(/\\/g, "/");
+  return normalizedPath.includes("/primitive/");
+}
+
+/**
+ * Determine if a token is a component token based on its source file path
+ * @param {string} sourceFilePath - Path to the source token file
+ * @returns {boolean} True if the token is a component token
+ */
+function isComponentToken(sourceFilePath) {
+  if (!sourceFilePath) return false;
+  // Component tokens are in src/theme/core/component/ directory
+  // Normalize path separators for cross-platform compatibility
+  const normalizedPath = sourceFilePath.replace(/\\/g, "/");
+  return normalizedPath.includes("/component/");
+}
+
+module.exports = {
+  loadTokenFiles,
+  parseTokenFile,
+  detectThemes,
+  loadThemeTokenFiles,
+  flattenTokenTree,
+  pathToVariableName,
+  isPrimitiveToken,
+  isComponentToken,
+};