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

package/src/utils/sd-transforms.js

@@ -0,0 +1,126 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * Style Dictionary transform registrations
+ * @module sd-transforms
+ */
+const {
+  getDtcgValue,
+  getTokenType,
+  isCompositeColor,
+  isDimensionValue,
+} = require("./token-helpers");
+
+/**
+ * Registers all custom Style Dictionary transforms for DTCG token format.
+ * This includes transforms for token names, values, cubic-bezier functions, and color opacity.
+ * Also registers a "dtcg" transform group that combines all these transforms.
+ * @param {import('style-dictionary').default} StyleDictionary - The Style Dictionary class instance
+ * @returns {void}
+ * @example
+ * const StyleDictionary = require('style-dictionary');
+ * registerTransforms(StyleDictionary);
+ */
+const registerTransforms = (StyleDictionary) => {
+  /**
+   * Transform: dtcg/name
+   * Generates a clean token name from the token path, filtering out $root, $schema,
+   * and other $-prefixed segments.
+   */
+  StyleDictionary.registerTransform({
+    name: "dtcg/name",
+    type: "name",
+    transform: (token) => {
+      const tokenPath =
+        token.path || token.original?.path || token.pathSegments;
+
+      if (Array.isArray(tokenPath) && tokenPath.length > 0) {
+        // Filter out $root, $schema, and other $-prefixed segments from path
+        const filteredPath = tokenPath.filter(
+          (segment) =>
+            segment !== "$root" &&
+            segment !== "$schema" &&
+            !String(segment).startsWith("$"),
+        );
+        if (filteredPath.length > 0) {
+          return filteredPath.join("-");
+        }
+      }
+      if (token.name && typeof token.name === "string") {
+        // Clean up name: remove $root, $schema, collapse dashes
+        return token.name
+          .replace(/\$root/g, "")
+          .replace(/\$schema/g, "")
+          .replace(/\$\$+/g, "-")
+          .replace(/-+/g, "-")
+          .replace(/^-|-$/g, "");
+      }
+      return "unknown";
+    },
+  });
+
+  /**
+   * Transform: dtcg/value
+   * Extracts the DTCG $value from a token, handling dimension objects with value/unit.
+   */
+  StyleDictionary.registerTransform({
+    name: "dtcg/value",
+    type: "value",
+    transform: (token) => {
+      const value = getDtcgValue(token);
+
+      // Handle new format { value, unit }
+      if (isDimensionValue(value)) {
+        return `${value.value}${value.unit}`;
+      }
+      return value;
+    },
+  });
+
+  /**
+   * Transform: dtcg/cubic-bezier
+   * Converts cubicBezier token arrays to CSS cubic-bezier() function strings.
+   */
+  StyleDictionary.registerTransform({
+    name: "dtcg/cubic-bezier",
+    type: "value",
+    matcher: (token) => getTokenType(token) === "cubicBezier",
+    transform: (token) => {
+      const value = getDtcgValue(token);
+      if (Array.isArray(value)) {
+        return `cubic-bezier(${value.join(", ")})`;
+      }
+      return value;
+    },
+  });
+
+  /**
+   * Transform: dtcg/color-opacity
+   * Handles composite color tokens that have separate color and alpha values.
+   */
+  StyleDictionary.registerTransform({
+    name: "dtcg/color-opacity",
+    type: "value",
+    matcher: (token) =>
+      getTokenType(token) === "color" && isCompositeColor(getDtcgValue(token)),
+    transform: (token) => getDtcgValue(token),
+  });
+
+  /**
+   * Transform Group: dtcg
+   * Combines all DTCG-related transforms plus the built-in color/css transform.
+   */
+  StyleDictionary.registerTransformGroup({
+    name: "dtcg",
+    transforms: [
+      "dtcg/name",
+      "dtcg/value",
+      "dtcg/cubic-bezier",
+      "dtcg/color-opacity",
+      "color/css",
+    ],
+  });
+};
+
+module.exports = {
+  registerTransforms,
+};

package/src/utils/token-helpers.js

@@ -0,0 +1,555 @@
+/**
+ * Token helper functions for Style Dictionary DTCG format
+ * These functions handle token value extraction, resolution, and CSS variable chain building
+ */
+
+/**
+ * Extracts the DTCG value from a token
+ * @param {Object} token - The token object
+ * @returns {*} The token's $value property
+ */
+const getDtcgValue = (token) => token.$value;
+
+/**
+ * Extracts the DTCG token type
+ * @param {Object} token - The token object
+ * @returns {string|undefined} The token's $type property
+ */
+const getTokenType = (token) => token.$type;
+
+/**
+ * Checks if a token has a dark mode value
+ * @param {Object} token - The token object
+ * @returns {boolean} True if the token has a dark mode value defined
+ */
+const hasDarkValue = (token) =>
+  token.$extensions?.appearance?.dark?.$value !== undefined;
+
+/**
+ * Gets the dark mode value from a token
+ * @param {Object} token - The token object
+ * @returns {*} The dark mode value, or undefined if not present
+ */
+const getDarkValue = (token) => token.$extensions?.appearance?.dark?.$value;
+
+/**
+ * Checks if a value is a composite color object (contains color and alpha properties)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a composite color object
+ * @example
+ * isCompositeColor({ color: '#fff', alpha: 0.5 }) // true
+ * isCompositeColor('#fff') // false
+ */
+const isCompositeColor = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  value.color !== undefined &&
+  value.alpha !== undefined;
+
+/**
+ * Checks if a value is a dimension object (contains value and unit properties)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a dimension object
+ * @example
+ * isDimensionValue({ value: 16, unit: 'px' }) // true
+ * isDimensionValue('16px') // false
+ */
+const isDimensionValue = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  value.value !== undefined &&
+  value.unit !== undefined;
+
+/**
+ * Wraps values containing commas in double quotes for SCSS map compatibility.
+ * SCSS maps use commas as entry separators, so values with commas need quoting.
+ * @param {*} value - The value to potentially wrap
+ * @returns {*} The wrapped value if it contains commas, otherwise the original value
+ * @example
+ * wrapScssValue('Arial, sans-serif') // '"Arial, sans-serif"'
+ * wrapScssValue('Arial') // 'Arial'
+ */
+const wrapScssValue = (value) => {
+  if (typeof value !== "string") return value;
+  if (value.includes(",")) {
+    return `"${value}"`;
+  }
+  return value;
+};
+
+/**
+ * Gets the token name from its path, filtering out $root segments
+ * @param {Object} token - The token object
+ * @returns {string} The token name as a hyphen-separated string
+ * @example
+ * getTokenName({ path: ['color', 'primary', '500'] }) // 'color-primary-500'
+ */
+const getTokenName = (token) => {
+  const tokenPath = token.path;
+  if (Array.isArray(tokenPath) && tokenPath.length > 0) {
+    // Filter out $root if it's the last segment
+    const filteredPath =
+      tokenPath[tokenPath.length - 1] === "$root"
+        ? tokenPath.slice(0, -1)
+        : tokenPath;
+    return filteredPath.join("-");
+  }
+  return "unknown";
+};
+
+/**
+ * Builds a Map of tokens keyed by their names for O(1) lookups
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @returns {Map<string, Object>} A Map where keys are token names and values are token objects
+ */
+const buildTokenMap = (dictionary) =>
+  new Map(
+    (dictionary.unfilteredAllTokens || dictionary.allTokens).map((t) => [
+      getTokenName(t),
+      t,
+    ]),
+  );
+
+/**
+ * Converts a hex color to hex8 format (with alpha channel)
+ * @param {string} hexColor - The hex color to convert (e.g., '#ff0000' or '#f00')
+ * @param {number} alpha - The alpha value between 0 and 1
+ * @returns {string} The hex8 color string (e.g., '#ff000080')
+ * @example
+ * convertToHex8('#ff0000', 0.5) // '#ff000080'
+ * convertToHex8('#f00', 1) // '#ff0000FF'
+ */
+const convertToHex8 = (hexColor, alpha) => {
+  if (!hexColor || typeof hexColor !== "string" || !hexColor.startsWith("#")) {
+    return hexColor;
+  }
+
+  // Remove # and normalize to 6-digit hex
+  let hex = hexColor.replace("#", "");
+  if (hex.length === 3) {
+    // Expand shorthand: #RGB -> #RRGGBB
+    hex = hex
+      .split("")
+      .map((char) => char + char)
+      .join("");
+  } else if (hex.length !== 6) {
+    return hexColor; // Invalid hex format
+  }
+
+  // Convert alpha (0-1) to hex (00-FF)
+  const alphaHex = Math.round(alpha * 255)
+    .toString(16)
+    .padStart(2, "0")
+    .toUpperCase();
+
+  return `#${hex}${alphaHex}`;
+};
+
+/**
+ * Resolves a reference string using Style Dictionary utilities.
+ * If reference points to a group, tries appending .$root to find the token.
+ * @param {string} refString - The reference string to resolve (e.g., '{color.primary.500}')
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {*} The resolved value, or the original string if resolution fails
+ */
+const resolveReference = (refString, dictionary, resolveReferences) => {
+  if (typeof refString !== "string") {
+    return refString;
+  }
+  try {
+    // 1. Try resolving exactly as requested (your suggestion step 1 & 2)
+    const result = resolveReferences(refString, dictionary.tokens, {
+      usesDtcg: true,
+    });
+
+    // 2. If it couldn't be resolved (it still contains braces), try with .$root (your suggestion step 3)
+    if (
+      typeof result === "string" &&
+      result.includes("{") &&
+      result.includes("}")
+    ) {
+      const withRoot = refString.replace(/\{([^{}]+)\}/g, (match, path) => {
+        // Only append .$root if it's not already there
+        return path.endsWith(".$root") ? match : `{${path}.$root}`;
+      });
+
+      try {
+        const rootResult = resolveReferences(withRoot, dictionary.tokens, {
+          usesDtcg: true,
+        });
+        // If the .$root version resolved successfully, use it
+        if (!rootResult.includes("{")) {
+          return rootResult;
+        }
+      } catch {
+        // Fallback to original result if .$root also fails
+      }
+    }
+    return result;
+  } catch {
+    return refString;
+  }
+};
+
+/**
+ * Resolves a composite color object (with color and alpha properties) to a hex8 string
+ * @param {Object} colorObj - The composite color object with color and alpha properties
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string|null} The resolved hex8 color string, or null if not a composite color
+ */
+const resolveCompositeColor = (colorObj, dictionary, resolveReferences) => {
+  if (!isCompositeColor(colorObj)) {
+    return null;
+  }
+  const colorValue = resolveReference(
+    colorObj.color,
+    dictionary,
+    resolveReferences,
+  );
+  if (typeof colorValue === "string" && colorValue.startsWith("#")) {
+    return convertToHex8(colorValue, colorObj.alpha);
+  }
+  return colorValue;
+};
+
+/**
+ * Gets the resolved token value, handling dark mode, composite colors, and references
+ * @param {Object} token - The token object
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Object} [options] - Options for value resolution
+ * @param {boolean} [options.isDark=false] - Whether to get the dark mode value
+ * @param {boolean} [options.forScssMap=false] - Whether to format for SCSS map (quotes commas)
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string} The resolved token value as a string
+ */
+const getTokenValue = (
+  token,
+  dictionary,
+  { isDark = false, forScssMap = false } = {},
+  resolveReferences,
+) => {
+  let value = getDtcgValue(token);
+
+  // Handle dark mode
+  if (isDark && hasDarkValue(token)) {
+    value = getDarkValue(token);
+  }
+
+  // Handle composite colors
+  if (isCompositeColor(value)) {
+    const resolved = resolveCompositeColor(
+      value,
+      dictionary,
+      resolveReferences,
+    );
+    if (resolved) {
+      value = resolved;
+    }
+  }
+
+  // Handle dimension values { value, unit }
+  if (isDimensionValue(value)) {
+    value = `${value.value}${value.unit}`;
+  }
+
+  // Resolve references
+  if (typeof value === "string" && value.includes("{") && value.includes("}")) {
+    value = resolveReference(value, dictionary, resolveReferences);
+  }
+
+  // Convert to string and clean up
+  if (value === undefined || value === null) {
+    return "";
+  }
+  const valueStr = typeof value === "string" ? value : JSON.stringify(value);
+
+  // Normalize transparent to rgba for consistency
+  const cleaned = valueStr.replaceAll('"', "");
+  if (cleaned === "transparent") {
+    return "rgba(0, 0, 0, 0)";
+  }
+
+  // Wrap values with commas in quotes for SCSS map compatibility
+  if (forScssMap) {
+    return wrapScssValue(cleaned);
+  }
+  return cleaned;
+};
+
+/**
+ * Checks if a value is a reference string using the usesReferences function
+ * @param {*} value - The value to check
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @returns {boolean} True if the value is a reference string
+ */
+const isReferenceString = (value, usesReferences) =>
+  typeof value === "string" && usesReferences(value);
+
+/**
+ * Builds a recursive CSS var chain with light-dark() at the level where light/dark values differ.
+ * Creates nested var() fallbacks that ultimately resolve to light-dark() at the primitive level.
+ * @param {string} originalValue - The original reference string (e.g., '{status.color.danger}')
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {boolean} [useLightDark=false] - Whether to include light-dark() for color variants
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @param {string} [cssVarPrefix=''] - Prefix for CSS variable names (e.g., 'a2-')
+ * @param {boolean} [forScssMap=false] - Whether to format for SCSS map
+ * @returns {string} The CSS var chain string
+ * @example
+ * // Returns: 'var(--a2-status-color-danger, light-dark(var(--a2-color-red-500, #e13212), var(--a2-color-red-100, #ff745f)))'
+ * buildRecursiveVarChainWithLightDark('{status.color.danger}', tokenMap, dictionary, true, usesReferences, resolveReferences, 'a2-')
+ */
+const buildRecursiveVarChainWithLightDark = (
+  originalValue,
+  tokenMap,
+  dictionary,
+  useLightDark = false,
+  usesReferences,
+  resolveReferences,
+  cssVarPrefix = "",
+  forScssMap = false,
+) => {
+  // If not a reference string, return the value as-is
+  if (
+    !originalValue ||
+    typeof originalValue !== "string" ||
+    !usesReferences(originalValue)
+  ) {
+    return originalValue;
+  }
+
+  // Replace each {reference} with var(--name, recursiveResult)
+  return originalValue.replace(/\{([^{}]+)\}/g, (_, refPath) => {
+    const refTokenName = refPath.replace(/\./g, "-");
+    const refToken = tokenMap.get(refTokenName);
+    if (!refToken) return `var(--${cssVarPrefix}${refTokenName})`;
+
+    const refOriginalLight = refToken.original?.$value;
+    const refOriginalDark =
+      refToken.original?.$extensions?.appearance?.dark?.$value;
+    const refHasDarkVariant = refOriginalDark !== undefined;
+
+    // Check if light and dark values are DIFFERENT - this is where light-dark() should go
+    const lightDarkDiffer =
+      refHasDarkVariant && refOriginalLight !== refOriginalDark;
+
+    if (useLightDark && lightDarkDiffer) {
+      // Light and dark values differ - insert light-dark() here
+      const lightResult = buildRecursiveVarChainWithLightDark(
+        refOriginalLight,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      // Same fix as darkFinal: ensure lightResult is a string before using it
+      const lightFinal =
+        typeof lightResult === "string" && usesReferences(refOriginalLight)
+          ? lightResult
+          : getTokenValue(
+              refToken,
+              dictionary,
+              { isDark: false, forScssMap },
+              resolveReferences,
+            );
+
+      const darkResult = buildRecursiveVarChainWithLightDark(
+        refOriginalDark,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      // Ensure darkResult is a string (resolved var chain), not just truthy.
+      // Composite color objects pass through buildRecursiveVarChainWithLightDark unchanged,
+      // but usesReferences() returns true for them (checks nested properties).
+      const darkFinal =
+        typeof darkResult === "string" && usesReferences(refOriginalDark)
+          ? darkResult
+          : getTokenValue(
+              refToken,
+              dictionary,
+              { isDark: true, forScssMap },
+              resolveReferences,
+            );
+
+      return `var(--${cssVarPrefix}${refTokenName}, light-dark(${lightFinal}, ${darkFinal}))`;
+    }
+
+    // Light and dark are same (or no dark) - continue recursing, propagate useLightDark
+    if (
+      refOriginalLight &&
+      typeof refOriginalLight === "string" &&
+      usesReferences(refOriginalLight)
+    ) {
+      const nestedResult = buildRecursiveVarChainWithLightDark(
+        refOriginalLight,
+        tokenMap,
+        dictionary,
+        useLightDark,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      return `var(--${cssVarPrefix}${refTokenName}, ${nestedResult})`;
+    }
+
+    // Final value (primitive) - get resolved value
+    const finalValue = getTokenValue(
+      refToken,
+      dictionary,
+      { isDark: false, forScssMap },
+      resolveReferences,
+    );
+    return `var(--${cssVarPrefix}${refTokenName}, ${finalValue})`;
+  });
+};
+
+/**
+ * Builds a fallback value with recursive refs and light-dark() at the appropriate level.
+ * This is the main entry point for generating CSS fallback values with dark mode support.
+ * @param {Object} token - The token object
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @param {Object} [options] - Options for fallback building
+ * @param {boolean} [options.isDark=false] - Whether to get the dark mode value
+ * @param {boolean} [options.useLightDark=false] - Whether to include light-dark() for color variants
+ * @param {string} [options.cssVarPrefix=''] - Prefix for CSS variable names
+ * @param {boolean} [options.forScssMap=false] - Whether to format for SCSS map
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string} The fallback value string with CSS var chains and/or light-dark()
+ */
+const buildFallbackWithRefs = (
+  token,
+  dictionary,
+  tokenMap,
+  {
+    isDark = false,
+    useLightDark = false,
+    cssVarPrefix = "",
+    forScssMap = false,
+  } = {},
+  usesReferences,
+  resolveReferences,
+) => {
+  const originalValue = token.original?.$value;
+  const originalDark = token.original?.$extensions?.appearance?.dark?.$value;
+  const hasDark = originalDark !== undefined;
+
+  // Check if this token's light/dark values are different at top level
+  // Use JSON.stringify for object comparison (composite colors)
+  const lightDarkDifferAtTop =
+    hasDark && JSON.stringify(originalValue) !== JSON.stringify(originalDark);
+
+  // If useLightDark and light/dark differ at this level, insert light-dark() here
+  if (useLightDark && lightDarkDifferAtTop) {
+    // Handle light value - could be a string reference or composite object
+    let lightFinal;
+    if (isReferenceString(originalValue, usesReferences)) {
+      lightFinal = buildRecursiveVarChainWithLightDark(
+        originalValue,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+    } else {
+      // Composite color or plain value - resolve directly
+      lightFinal = getTokenValue(
+        token,
+        dictionary,
+        { isDark: false, forScssMap },
+        resolveReferences,
+      );
+    }
+
+    // Handle dark value - could be a string reference or composite object
+    let darkFinal;
+    if (isReferenceString(originalDark, usesReferences)) {
+      darkFinal = buildRecursiveVarChainWithLightDark(
+        originalDark,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+    } else {
+      // Composite color or plain value - resolve directly
+      darkFinal = getTokenValue(
+        token,
+        dictionary,
+        { isDark: true, forScssMap },
+        resolveReferences,
+      );
+    }
+
+    return `light-dark(${lightFinal}, ${darkFinal})`;
+  }
+
+  // Light/dark same or no dark - recurse and propagate useLightDark to find where they differ
+  // When isDark is true and we have a dark value, use originalDark instead of originalValue
+  const valueToProcess = isDark && hasDark ? originalDark : originalValue;
+
+  if (isReferenceString(valueToProcess, usesReferences)) {
+    const result = buildRecursiveVarChainWithLightDark(
+      valueToProcess,
+      tokenMap,
+      dictionary,
+      useLightDark,
+      usesReferences,
+      resolveReferences,
+      cssVarPrefix,
+      forScssMap,
+    );
+    if (result && result !== valueToProcess) {
+      return result;
+    }
+  }
+
+  // No references or composite value - return the resolved final value
+  return getTokenValue(
+    token,
+    dictionary,
+    { isDark, forScssMap },
+    resolveReferences,
+  );
+};
+
+module.exports = {
+  getDtcgValue,
+  getTokenType,
+  hasDarkValue,
+  getDarkValue,
+  isCompositeColor,
+  isDimensionValue,
+  wrapScssValue,
+  getTokenName,
+  buildTokenMap,
+  convertToHex8,
+  resolveReference,
+  resolveCompositeColor,
+  getTokenValue,
+  isReferenceString,
+  buildRecursiveVarChainWithLightDark,
+  buildFallbackWithRefs,
+};

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*.js", "config.js"],
+  "exclude": ["node_modules", "build", "build-reference"]
+}