@servicetitan/hammer-token 2.5.2 → 3.0.1

package/src/utils/figma/utils.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * Utility Functions for Figma Sync
+ *
+ * Common utility functions for validation, token masking, and other helpers.
+ */
+
+/**
+ * Mask a token for safe logging (shows first 8 chars and last 4 chars)
+ * @param {string} token - Token to mask
+ * @returns {string} Masked token
+ */
+function maskToken(token) {
+  if (!token || typeof token !== "string") {
+    return "***";
+  }
+  if (token.length <= 12) {
+    return "***";
+  }
+  return token.substring(0, 8) + "..." + token.substring(token.length - 4);
+}
+
+/**
+ * Validate fileKey format
+ * @param {string} fileKey - Figma file key to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If fileKey is invalid
+ */
+function validateFileKey(fileKey) {
+  if (!fileKey || typeof fileKey !== "string") {
+    throw new Error("File key must be a non-empty string");
+  }
+
+  // Figma file keys are typically 15-30 alphanumeric characters
+  if (!/^[a-zA-Z0-9]{15,30}$/.test(fileKey)) {
+    throw new Error(
+      `Invalid file key format: ${fileKey}. Expected 15-30 alphanumeric characters.`,
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Parse CLI arguments into options object
+ * @param {Array<string>} args - Command line arguments
+ * @returns {Object} Parsed options
+ */
+function parseCliArgs(args) {
+  const options = {
+    command: null,
+    fileKey: null,
+    dryRun: false,
+    verbose: false,
+    full: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    // Handle flags
+    if (arg === "--file-key" || arg === "-f") {
+      if (i + 1 < args.length) {
+        options.fileKey = args[i + 1];
+        i += 2;
+        continue;
+      } else {
+        throw new Error(`Missing value for ${arg}`);
+      }
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--verbose" || arg === "-v") {
+      options.verbose = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--full") {
+      options.full = true;
+      i++;
+      continue;
+    }
+
+    // Handle commands
+    if (arg === "sync" || arg === "test" || arg === "validate") {
+      options.command = arg;
+      i++;
+      continue;
+    }
+
+    // Handle test:file command
+    if (arg === "test:file") {
+      options.command = "test:file";
+      if (i + 1 < args.length) {
+        options.fileKey = args[i + 1];
+        i += 2;
+        continue;
+      } else {
+        throw new Error("test:file requires a fileKey argument");
+      }
+    }
+
+    // Legacy: file command
+    if (arg === "file" || arg === "--file") {
+      if (i + 1 < args.length) {
+        options.fileKey = args[i + 1];
+        options.command = "file";
+        i += 2;
+        continue;
+      } else {
+        throw new Error("file command requires a fileKey argument");
+      }
+    }
+
+    // Legacy: If it looks like a fileKey and we don't have one, use it
+    if (!options.fileKey && /^[a-zA-Z0-9]{15,30}$/.test(arg)) {
+      options.fileKey = arg;
+      i++;
+      continue;
+    }
+
+    // Unknown argument
+    i++;
+  }
+
+  return options;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted duration
+ */
+function formatDuration(ms) {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(2)}s`;
+  }
+  const minutes = Math.floor(ms / 60000);
+  const seconds = ((ms % 60000) / 1000).toFixed(2);
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Print help text
+ */
+function printHelp() {
+  console.log(`
+Figma Variables Sync - Usage
+
+Commands:
+  sync                    Sync tokens to Figma (default)
+  test                    Test Figma API access
+  test:file <fileKey>      Test access to a specific Figma file
+  validate                Validate token files without syncing
+  file <fileKey>           Legacy: Sync to specific file
+
+Options:
+  -f, --file-key <key>     Figma file key (overrides env/config)
+  --dry-run                Validate without making changes
+  --verbose, -v            Enable verbose logging
+  --full                   Run full test suite (for test commands)
+  --help, -h               Show this help message
+
+Examples:
+  pnpm figma:sync
+  pnpm figma:sync --file-key <fileKey>
+  pnpm figma:sync --dry-run
+  pnpm figma:test
+  pnpm figma:test:file rBPlrqjRiS8vxfY3IsNfZB
+  pnpm figma:test:file rBPlrqjRiS8vxfY3IsNfZB --full
+  pnpm figma:validate
+
+Environment Variables:
+  FIGMA_CLIENT_ID          OAuth2 client ID
+  FIGMA_CLIENT_SECRET      OAuth2 client secret
+  FIGMA_REFRESH_TOKEN      OAuth2 refresh token
+  FIGMA_FILE_KEY           Default Figma file key
+  DEBUG                    Enable debug logging
+`);
+}
+
+module.exports = {
+  maskToken,
+  validateFileKey,
+  parseCliArgs,
+  formatDuration,
+  printHelp,
+};

package/src/utils/sd-build-configs.js

@@ -0,0 +1,305 @@
+/**
+ * Style Dictionary build configurations
+ * @module sd-build-configs
+ */
+const { getTokenName } = require("./token-helpers");
+
+/**
+ * CSS Utils prefixes for generating utility class variants
+ * @constant {string[]}
+ */
+const CSS_UTILS_PREFIXES = ["", "a2-"];
+
+/**
+ * Filters tokens to include only semantic tokens (excludes primitive and component tokens).
+ * @param {Object} token - The token object from Style Dictionary
+ * @returns {boolean} True if the token is a semantic token
+ */
+const isSemanticToken = (token) => {
+  if (!token.filePath) return true;
+  return (
+    !token.filePath.includes("primitive") &&
+    !token.filePath.includes("/component/")
+  );
+};
+
+/**
+ * Filters tokens to include only component tokens.
+ * @param {Object} token - The token object from Style Dictionary
+ * @returns {boolean} True if the token is a component token
+ */
+const isComponentToken = (token) =>
+  token.filePath && token.filePath.includes("/component/");
+
+/**
+ * Creates a platform configuration for Style Dictionary.
+ * @param {Object} options - Platform configuration options
+ * @param {string} options.buildPath - Output directory path for built files
+ * @param {Array<Object>} options.files - Array of file configurations with destination and format
+ * @returns {Object} Platform configuration object
+ */
+const createPlatform = ({ buildPath, files }) => ({
+  transformGroup: "dtcg",
+  options: {
+    usesDtcg: true,
+  },
+  buildPath,
+  files,
+});
+
+/**
+ * Creates CSS utility file configurations for a given class prefix.
+ * Generates configurations for all utils, colors, fonts, and spacing.
+ * Note: borders are only in the semantic build (createSemanticCssUtilsFiles).
+ * @param {string} prefix - CSS class prefix (e.g., '' or 'a2-')
+ * @returns {Array<Object>} Array of file configurations for CSS utilities
+ */
+const createCssUtilsFiles = (prefix) => [
+  {
+    destination: `${prefix}utils.css`,
+    format: `custom/CSSUtils/${prefix}All`,
+  },
+  {
+    destination: `${prefix}color.css`,
+    format: `custom/CSSUtils/${prefix}Colors`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.startsWith("color");
+    },
+  },
+  {
+    destination: `${prefix}font.css`,
+    format: `custom/CSSUtils/${prefix}Fonts`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.startsWith("font");
+    },
+  },
+  {
+    destination: `${prefix}spacing.css`,
+    format: `custom/CSSUtils/${prefix}Spacing`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.startsWith("size");
+    },
+  },
+];
+
+/**
+ * Creates CSS utility file configurations for semantic tokens with a given class prefix.
+ * Similar to createCssUtilsFiles but with filters appropriate for semantic token naming.
+ * @param {string} prefix - CSS class prefix (e.g., '' or 'a2-')
+ * @returns {Array<Object>} Array of file configurations for semantic CSS utilities
+ * @example
+ * createSemanticCssUtilsFiles('a2-')
+ */
+const createSemanticCssUtilsFiles = (prefix) => [
+  {
+    destination: `${prefix}utils.css`,
+    format: `custom/CSSUtils/${prefix}All`,
+    filter: () => true,
+  },
+  {
+    destination: `${prefix}border.css`,
+    format: `custom/CSSUtils/${prefix}Borders`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.includes("border");
+    },
+  },
+  {
+    destination: `${prefix}color.css`,
+    format: `custom/CSSUtils/${prefix}Colors`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return (
+        name &&
+        (name.includes("color") ||
+          name.includes("status-color") ||
+          name.includes("foreground-color") ||
+          name.includes("background-color") ||
+          name.includes("overlay-color"))
+      );
+    },
+  },
+  {
+    destination: `${prefix}font.css`,
+    format: `custom/CSSUtils/${prefix}Fonts`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.includes("typography");
+    },
+  },
+  {
+    destination: `${prefix}spacing.css`,
+    format: `custom/CSSUtils/${prefix}Spacing`,
+    filter: (token) => {
+      const name = getTokenName(token);
+      return name && name.startsWith("size");
+    },
+  },
+];
+
+/**
+ * Creates the Style Dictionary configuration for primitive tokens.
+ * Primitive tokens are the foundational design values (colors, sizes, etc.).
+ * @returns {Object} Style Dictionary configuration object for primitive tokens
+ * @example
+ * const StyleDictionary = require('style-dictionary');
+ * const config = createPrimitiveConfig();
+ * const sd = new StyleDictionary(config);
+ */
+const createPrimitiveConfig = () => ({
+  log: {
+    verbosity: "verbose",
+  },
+  preprocessors: ["dtcg/set-token-names"],
+  source: ["src/global/primitive/*.tokens.json"],
+  platforms: {
+    scss: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "primitive.scss",
+          format: "custom/scss-variables",
+        },
+        {
+          destination: "primitive-variables.scss",
+          format: "custom/scss-variables-map",
+        },
+      ],
+    }),
+    js: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "primitive.js",
+          format: "custom/es6-variable",
+        },
+      ],
+    }),
+    css: createPlatform({
+      buildPath: "build/web/core/css-utils/",
+      files: CSS_UTILS_PREFIXES.flatMap((prefix) =>
+        createCssUtilsFiles(prefix),
+      ),
+    }),
+  },
+});
+
+/**
+ * Creates the Style Dictionary configuration for theme tokens.
+ * Theme tokens include semantic tokens that reference primitives, excluding component tokens.
+ * @returns {Object} Style Dictionary configuration object for theme tokens
+ * @example
+ * const StyleDictionary = require('style-dictionary');
+ * const config = createThemeConfig();
+ * const sd = new StyleDictionary(config);
+ */
+const createThemeConfig = () => ({
+  log: {
+    verbosity: "verbose",
+    errors: {
+      brokenReferences: "warn",
+    },
+  },
+  preprocessors: ["dtcg/set-token-names"],
+  include: [
+    "src/global/primitive/*.tokens.json",
+    "src/theme/core/status.tokens.json",
+  ],
+  source: ["src/theme/**/*.tokens.json"],
+  platforms: {
+    scss: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "semantic.scss",
+          format: "custom/scss-variables",
+          filter: isSemanticToken,
+        },
+        {
+          destination: "semantic-variables.scss",
+          format: "custom/scss-variables-map",
+          filter: isSemanticToken,
+        },
+      ],
+    }),
+    js: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "semantic.js",
+          format: "custom/es6-variable",
+          filter: isSemanticToken,
+        },
+      ],
+    }),
+    css: createPlatform({
+      buildPath: "build/web/core/css-utils/",
+      files: CSS_UTILS_PREFIXES.flatMap((prefix) =>
+        createSemanticCssUtilsFiles(prefix),
+      ),
+    }),
+  },
+});
+
+/**
+ * Creates the Style Dictionary configuration for component tokens.
+ * Component tokens are specific to UI components and reference theme/primitive tokens.
+ * @returns {Object} Style Dictionary configuration object for component tokens
+ * @example
+ * const StyleDictionary = require('style-dictionary');
+ * const config = createComponentConfig();
+ * const sd = new StyleDictionary(config);
+ */
+const createComponentConfig = () => ({
+  usesDtcg: true,
+  log: {
+    verbosity: "verbose",
+    errors: {
+      brokenReferences: "warn",
+    },
+  },
+  preprocessors: ["dtcg/set-token-names"],
+  include: [
+    "src/global/primitive/*.tokens.json",
+    "src/theme/core/*.tokens.json",
+  ],
+  source: ["src/theme/core/component/*.tokens.json"],
+  platforms: {
+    scss: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "component.scss",
+          format: "custom/scss-variables",
+          filter: isComponentToken,
+        },
+        {
+          destination: "component-variables.scss",
+          format: "custom/scss-variables-map",
+          filter: isComponentToken,
+        },
+      ],
+    }),
+    js: createPlatform({
+      buildPath: "build/web/core/",
+      files: [
+        {
+          destination: "component.js",
+          format: "custom/es6-variable",
+          filter: isComponentToken,
+        },
+      ],
+    }),
+  },
+});
+
+module.exports = {
+  createPrimitiveConfig,
+  createThemeConfig,
+  createComponentConfig,
+  isSemanticToken,
+  isComponentToken,
+};