@servicetitan/hammer-token 2.5.2 → 3.0.1

package/src/utils/figma/__tests__/sync-gradient.test.js

@@ -0,0 +1,561 @@
+import { describe, it, expect } from "vitest";
+import { buildSemanticVariableRequest } from "../sync-semantic.js";
+import { buildComponentVariableRequest } from "../sync-components.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const MODES = {
+  light: { id: "mode-light" },
+  dark: { id: "mode-dark" },
+};
+
+const COLLECTION_ID = "col-1";
+
+/**
+ * Build the resolved token map that sync-semantic and sync-components expect.
+ * Each entry mirrors what resolvePrimitiveReferences produces.
+ */
+function makeTokenMap(entries) {
+  return new Map(entries);
+}
+
+/**
+ * Minimal primitive color token data
+ */
+function makePrimitiveTokenData(tokenPath, hexValue) {
+  return [
+    tokenPath,
+    {
+      token: { $type: "color", $value: hexValue },
+      resolvedLight: hexValue,
+      resolvedDark: hexValue,
+      isPrimitive: true,
+      sourceFilePath: "/src/global/primitive/color.tokens.json",
+      path: tokenPath.split("/"),
+      variableName: tokenPath,
+    },
+  ];
+}
+
+/**
+ * Gradient token data for the semantic tier (gradient.primary)
+ */
+function makeSemanticGradientTokenData() {
+  const gradientValue = {
+    type: "linear",
+    angle: 90,
+    stops: [
+      {
+        position: 0,
+        color: {
+          $type: "color",
+          $value: "{color.blue.600}",
+          $extensions: {
+            appearance: {
+              light: { $type: "color", $value: "{color.blue.600}" },
+              dark: { $type: "color", $value: "{color.cyan.300}" },
+            },
+            "com.figma.scopes": ["SHAPE_FILL", "FRAME_FILL", "STROKE_COLOR"],
+          },
+        },
+      },
+      {
+        position: 1,
+        color: {
+          $type: "color",
+          $value: "{color.cyan.300}",
+          $extensions: {
+            appearance: {
+              light: { $type: "color", $value: "{color.cyan.300}" },
+              dark: { $type: "color", $value: "{color.cyan.50}" },
+            },
+            "com.figma.scopes": ["SHAPE_FILL", "FRAME_FILL", "STROKE_COLOR"],
+          },
+        },
+      },
+    ],
+  };
+
+  return [
+    "gradient/primary",
+    {
+      token: { $type: "gradient", $value: gradientValue },
+      resolvedLight: gradientValue,
+      resolvedDark: gradientValue,
+      isPrimitive: false,
+      sourceFilePath: "/src/theme/core/gradient.tokens.json",
+      path: ["gradient", "primary"],
+      variableName: "gradient/primary",
+    },
+  ];
+}
+
+/**
+ * Component gradient token data for ai-mark.primary.background.gradient
+ */
+function makeComponentGradientTokenData() {
+  return [
+    "ai-mark/primary/background/gradient",
+    {
+      token: {
+        $type: "gradient",
+        $value: "{gradient.primary}",
+        $extensions: {
+          appearance: {
+            light: { $type: "gradient", $value: "{gradient.primary}" },
+            dark: { $type: "gradient", $value: "{gradient.primary}" },
+          },
+          "com.figma.scopes": ["FRAME_FILL", "SHAPE_FILL"],
+        },
+      },
+      resolvedLight: "{gradient.primary}",
+      resolvedDark: "{gradient.primary}",
+      isPrimitive: false,
+      sourceFilePath: "/src/theme/core/component/ai-mark.tokens.json",
+      path: ["ai-mark", "primary", "background", "gradient"],
+      variableName: "ai-mark/primary/background/gradient",
+    },
+  ];
+}
+
+// Shared token map with all required entries
+function makeFullTokenMap() {
+  return makeTokenMap([
+    makePrimitiveTokenData("color/blue/600", "#0265dc"),
+    makePrimitiveTokenData("color/cyan/300", "#45d8f2"),
+    makePrimitiveTokenData("color/cyan/50", "#cdf4fb"),
+    makeSemanticGradientTokenData(),
+    makeComponentGradientTokenData(),
+  ]);
+}
+
+// Existing primitive variables with IDs (simulates what Figma already has)
+const existingPrimitiveVariables = [
+  {
+    id: "var-blue-600",
+    name: "primitive/color/blue/600",
+    variableCollectionId: COLLECTION_ID,
+    scopes: ["ALL_SCOPES"],
+    valuesByMode: {
+      "mode-light": { r: 0.01, g: 0.4, b: 0.86, a: 1 },
+      "mode-dark": { r: 0.01, g: 0.4, b: 0.86, a: 1 },
+    },
+  },
+  {
+    id: "var-cyan-300",
+    name: "primitive/color/cyan/300",
+    variableCollectionId: COLLECTION_ID,
+    scopes: ["ALL_SCOPES"],
+    valuesByMode: {
+      "mode-light": { r: 0.27, g: 0.85, b: 0.95, a: 1 },
+      "mode-dark": { r: 0.27, g: 0.85, b: 0.95, a: 1 },
+    },
+  },
+  {
+    id: "var-cyan-50",
+    name: "primitive/color/cyan/50",
+    variableCollectionId: COLLECTION_ID,
+    scopes: ["ALL_SCOPES"],
+    valuesByMode: {
+      "mode-light": { r: 0.8, g: 0.96, b: 0.98, a: 1 },
+      "mode-dark": { r: 0.8, g: 0.96, b: 0.98, a: 1 },
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// buildSemanticVariableRequest — gradient unpacking
+// ---------------------------------------------------------------------------
+
+describe("buildSemanticVariableRequest — gradient tokens", () => {
+  it("creates two COLOR stop variables for gradient/primary", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const gradientVars = result.variableChanges.filter((v) =>
+      v.name?.startsWith("semantic/gradient/primary/stop-"),
+    );
+    expect(gradientVars).toHaveLength(2);
+    expect(gradientVars[0].name).toBe("semantic/gradient/primary/stop-0");
+    expect(gradientVars[1].name).toBe("semantic/gradient/primary/stop-1");
+  });
+
+  it("creates stop variables as COLOR type", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stopVars = result.variableChanges.filter((v) =>
+      v.name?.startsWith("semantic/gradient/primary/stop-"),
+    );
+    for (const v of stopVars) {
+      expect(v.resolvedType).toBe("COLOR");
+    }
+  });
+
+  it("stop-0 light mode aliases primitive/color/blue/600", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stop0ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return varChange?.name === "semantic/gradient/primary/stop-0";
+    });
+
+    const lightModeValue = stop0ModeValues.find(
+      (mv) => mv.modeId === "mode-light",
+    );
+    expect(lightModeValue?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "var-blue-600",
+    });
+  });
+
+  it("stop-0 dark mode aliases primitive/color/cyan/300", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stop0ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return varChange?.name === "semantic/gradient/primary/stop-0";
+    });
+
+    const darkModeValue = stop0ModeValues.find(
+      (mv) => mv.modeId === "mode-dark",
+    );
+    expect(darkModeValue?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "var-cyan-300",
+    });
+  });
+
+  it("stop-1 light mode aliases primitive/color/cyan/300", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stop1ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return varChange?.name === "semantic/gradient/primary/stop-1";
+    });
+
+    const lightModeValue = stop1ModeValues.find(
+      (mv) => mv.modeId === "mode-light",
+    );
+    expect(lightModeValue?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "var-cyan-300",
+    });
+  });
+
+  it("stop-1 dark mode aliases primitive/color/cyan/50", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stop1ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return varChange?.name === "semantic/gradient/primary/stop-1";
+    });
+
+    const darkModeValue = stop1ModeValues.find(
+      (mv) => mv.modeId === "mode-dark",
+    );
+    expect(darkModeValue?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "var-cyan-50",
+    });
+  });
+
+  it("assigns correct figma scopes to stop variables", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const stopVars = result.variableChanges.filter((v) =>
+      v.name?.startsWith("semantic/gradient/primary/stop-"),
+    );
+    for (const v of stopVars) {
+      expect(v.scopes).toEqual(
+        expect.arrayContaining(["SHAPE_FILL", "FRAME_FILL", "STROKE_COLOR"]),
+      );
+    }
+  });
+
+  it("does NOT create a variable for the gradient/primary composite token itself", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const gradientComposite = result.variableChanges.find(
+      (v) => v.name === "semantic/gradient/primary",
+    );
+    expect(gradientComposite).toBeUndefined();
+  });
+
+  it("produces no errors when primitives exist", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const gradientErrors = result.errors.filter((e) => e.includes("gradient"));
+    expect(gradientErrors).toHaveLength(0);
+  });
+
+  it("skips stop variables that already exist with matching values", () => {
+    const tokensToSync = makeFullTokenMap();
+
+    // Pre-populate existing variables with the stop vars
+    const existingWithStops = [
+      ...existingPrimitiveVariables,
+      {
+        id: "existing-stop-0",
+        name: "semantic/gradient/primary/stop-0",
+        variableCollectionId: COLLECTION_ID,
+        scopes: ["SHAPE_FILL", "FRAME_FILL", "STROKE_COLOR"],
+        description:
+          "stop 0 at 0%: light: color/blue/600 → #0265dc, dark: color/cyan/300 → #45d8f2",
+        valuesByMode: {
+          "mode-light": { type: "VARIABLE_ALIAS", id: "var-blue-600" },
+          "mode-dark": { type: "VARIABLE_ALIAS", id: "var-cyan-300" },
+        },
+      },
+      {
+        id: "existing-stop-1",
+        name: "semantic/gradient/primary/stop-1",
+        variableCollectionId: COLLECTION_ID,
+        scopes: ["SHAPE_FILL", "FRAME_FILL", "STROKE_COLOR"],
+        description:
+          "stop 1 at 100%: light: color/cyan/300 → #45d8f2, dark: color/cyan/50 → #cdf4fb",
+        valuesByMode: {
+          "mode-light": { type: "VARIABLE_ALIAS", id: "var-cyan-300" },
+          "mode-dark": { type: "VARIABLE_ALIAS", id: "var-cyan-50" },
+        },
+      },
+    ];
+
+    const result = buildSemanticVariableRequest(
+      tokensToSync,
+      existingWithStops,
+      COLLECTION_ID,
+      MODES,
+      new Map(),
+      tokensToSync,
+    );
+
+    const gradientCreates = result.variableChanges.filter(
+      (v) =>
+        v.action === "CREATE" &&
+        v.name?.startsWith("semantic/gradient/primary/stop-"),
+    );
+    expect(gradientCreates).toHaveLength(0);
+    expect(result.stats.skipped).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildComponentVariableRequest — gradient stop aliasing
+// ---------------------------------------------------------------------------
+
+describe("buildComponentVariableRequest — gradient tokens", () => {
+  // Build semantic tempIdMap with stop variable IDs already resolved
+  function makeSemanticTempIdMap() {
+    const tempIdMap = new Map();
+    tempIdMap.set("gradient/primary/stop-0", "sem-stop-0-id");
+    tempIdMap.set("semantic/gradient/primary/stop-0", "sem-stop-0-id");
+    tempIdMap.set("gradient/primary/stop-1", "sem-stop-1-id");
+    tempIdMap.set("semantic/gradient/primary/stop-1", "sem-stop-1-id");
+    return tempIdMap;
+  }
+
+  it("creates two stop variables for ai-mark gradient component token", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const compStopVars = result.variableChanges.filter((v) =>
+      v.name?.startsWith("component/ai-mark/primary/background/gradient/stop-"),
+    );
+    expect(compStopVars).toHaveLength(2);
+  });
+
+  it("component stop variables alias the corresponding semantic stop variables", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const stop0ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return (
+        varChange?.name ===
+        "component/ai-mark/primary/background/gradient/stop-0"
+      );
+    });
+
+    expect(stop0ModeValues[0]?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "sem-stop-0-id",
+    });
+  });
+
+  it("component stop-1 aliases semantic/gradient/primary/stop-1", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const stop1ModeValues = result.variableModeValues.filter((mv) => {
+      const varChange = result.variableChanges.find(
+        (v) => v.id === mv.variableId,
+      );
+      return (
+        varChange?.name ===
+        "component/ai-mark/primary/background/gradient/stop-1"
+      );
+    });
+
+    expect(stop1ModeValues[0]?.value).toEqual({
+      type: "VARIABLE_ALIAS",
+      id: "sem-stop-1-id",
+    });
+  });
+
+  it("does NOT create a variable for the ai-mark gradient composite token itself", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const compositeVar = result.variableChanges.find(
+      (v) => v.name === "component/ai-mark/primary/background/gradient",
+    );
+    expect(compositeVar).toBeUndefined();
+  });
+
+  it("produces no errors when semantic stop IDs are in tempIdMap", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const gradientErrors = result.errors.filter(
+      (e) => e.includes("gradient") || e.includes("ai-mark"),
+    );
+    expect(gradientErrors).toHaveLength(0);
+  });
+
+  it("component stop variables are COLOR type", () => {
+    const tokensToSync = makeFullTokenMap();
+    const result = buildComponentVariableRequest(
+      tokensToSync,
+      existingPrimitiveVariables,
+      COLLECTION_ID,
+      MODES,
+      makeSemanticTempIdMap(),
+      tokensToSync,
+    );
+
+    const compStopVars = result.variableChanges.filter((v) =>
+      v.name?.startsWith("component/ai-mark/primary/background/gradient/stop-"),
+    );
+    for (const v of compStopVars) {
+      expect(v.resolvedType).toBe("COLOR");
+    }
+  });
+});

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

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import { isGradientToken, parseGradientStops } from "../token-conversion.js";
+
+// ---------------------------------------------------------------------------
+// isGradientToken
+// ---------------------------------------------------------------------------
+
+describe("isGradientToken", () => {
+  it("returns true for 'gradient' type", () => {
+    expect(isGradientToken("gradient")).toBe(true);
+  });
+
+  it("returns false for 'color' type", () => {
+    expect(isGradientToken("color")).toBe(false);
+  });
+
+  it("returns false for 'dimension' type", () => {
+    expect(isGradientToken("dimension")).toBe(false);
+  });
+
+  it("returns false for undefined", () => {
+    expect(isGradientToken(undefined)).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isGradientToken("")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseGradientStops
+// ---------------------------------------------------------------------------
+
+const makeStop = (lightRef, darkRef, position = 0) => ({
+  position,
+  color: {
+    $type: "color",
+    $value: lightRef,
+    $extensions: {
+      appearance: {
+        light: { $type: "color", $value: lightRef },
+        dark: { $type: "color", $value: darkRef },
+      },
+    },
+  },
+});
+
+describe("parseGradientStops", () => {
+  it("returns an array with one entry per stop", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [makeStop("{color.blue.600}", "{color.cyan.300}", 0)],
+    };
+    const result = parseGradientStops(gradient);
+    expect(result).toHaveLength(1);
+  });
+
+  it("extracts lightRef and darkRef for each stop", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [
+        makeStop("{color.blue.600}", "{color.cyan.300}", 0),
+        makeStop("{color.cyan.300}", "{color.cyan.50}", 1),
+      ],
+    };
+    const result = parseGradientStops(gradient);
+    expect(result[0]).toEqual({
+      lightRef: "{color.blue.600}",
+      darkRef: "{color.cyan.300}",
+    });
+    expect(result[1]).toEqual({
+      lightRef: "{color.cyan.300}",
+      darkRef: "{color.cyan.50}",
+    });
+  });
+
+  it("falls back to stop.color.$value when appearance is absent", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [
+        {
+          position: 0,
+          color: { $type: "color", $value: "#fallback" },
+        },
+      ],
+    };
+    const result = parseGradientStops(gradient);
+    expect(result[0].lightRef).toBe("#fallback");
+    expect(result[0].darkRef).toBe("#fallback");
+  });
+
+  it("returns null for null input", () => {
+    expect(parseGradientStops(null)).toBeNull();
+  });
+
+  it("returns null for undefined input", () => {
+    expect(parseGradientStops(undefined)).toBeNull();
+  });
+
+  it("returns null when stops is not an array", () => {
+    expect(
+      parseGradientStops({ type: "linear", angle: 90, stops: null }),
+    ).toBeNull();
+  });
+
+  it("returns null for a string (reference not yet resolved)", () => {
+    expect(parseGradientStops("{gradient.primary}")).toBeNull();
+  });
+
+  it("returns empty array for gradient with no stops", () => {
+    const result = parseGradientStops({ type: "linear", angle: 90, stops: [] });
+    expect(result).toEqual([]);
+  });
+});