@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/schemas/functions/diverging/diverging.tokenscript

@@ -0,0 +1,58 @@
+// Create a diverging color palette for data visualization
+// Goes: color1 → neutral → color2
+//
+// Ideal for: heatmaps, correlation matrices, deviation from mean
+// Example: blue → white → red for temperature anomalies
+
+variable input: List = {input};
+variable color1: Color.OKLCH = input.get(0).to.oklch();
+variable color2: Color.OKLCH = input.get(1).to.oklch();
+
+// Default count is 9 (gives clear midpoint at index 4)
+variable count: Number = 9;
+if (input.length() > 2) [
+    count = input.get(2);
+];
+
+// Default neutral lightness is 0.95 (near white)
+variable neutral_l: Number = 0.95;
+if (input.length() > 3) [
+    neutral_l = input.get(3);
+];
+
+// Calculate midpoint index
+variable mid: Number = (count - 1) / 2;
+
+variable result: List;
+variable i: Number = 0;
+variable t: Number = 0;
+variable step_color: Color.OKLCH;
+
+while (i < count) [
+    if (i < mid) [
+        // First half: color1 → neutral
+        t = i / mid;
+        step_color.l = color1.l + (neutral_l - color1.l) * t;
+        step_color.c = color1.c * (1 - t);
+        step_color.h = color1.h;
+    ] else [
+        if (i == mid) [
+            // Midpoint: neutral (achromatic)
+            step_color.l = neutral_l;
+            step_color.c = 0;
+            step_color.h = 0;
+        ] else [
+            // Second half: neutral → color2
+            t = (i - mid) / mid;
+            step_color.l = neutral_l + (color2.l - neutral_l) * t;
+            step_color.c = color2.c * t;
+            step_color.h = color2.h;
+        ];
+    ];
+    
+    result = result, step_color.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

package/src/schemas/functions/diverging/schema.json

@@ -0,0 +1,32 @@
+{
+  "name": "Diverging",
+  "type": "function",
+  "description": "Creates a diverging color palette for heatmaps. Goes from color1 through a neutral midpoint to color2. Perfect for data that diverges from a center value (e.g., -1 to 0 to +1).",
+  "keyword": "diverging",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "Color for negative/low end (e.g., blue)"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Color for positive/high end (e.g., red)"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of steps (should be odd for clear midpoint). Default is 9"
+      },
+      "neutral": {
+        "type": "number",
+        "description": "Lightness of neutral midpoint (0-1). Default is 0.95 (near white)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./diverging.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/diverging/unit.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Unit tests for the Diverging function
+ * Creates a diverging color palette for data visualization
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Diverging Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("diverging", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Diverging");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("diverging");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 9 steps by default", async () => {
+      const result = await executeWithSchema(
+        "diverging",
+        "function",
+        `
+        variable cold: Color.SRGB;
+        cold.r = 0.2; cold.g = 0.4; cold.b = 0.8;
+        variable hot: Color.SRGB;
+        hot.r = 0.8; hot.g = 0.2; hot.b = 0.2;
+        diverging(cold, hot)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of steps", async () => {
+      const result = await executeWithSchema(
+        "diverging",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0.3; blue.b = 0.7;
+        variable red: Color.SRGB;
+        red.r = 0.7; red.g = 0.1; red.b = 0.1;
+        diverging(blue, red, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should have neutral midpoint", async () => {
+      const result = await executeWithSchema(
+        "diverging",
+        "function",
+        `
+        variable neg: Color.SRGB;
+        neg.r = 0; neg.g = 0.5; neg.b = 0.8;
+        variable pos: Color.SRGB;
+        pos.r = 0.9; pos.g = 0.4; pos.b = 0;
+        diverging(neg, pos, 9)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/grayscale/grayscale.tokenscript

@@ -0,0 +1,17 @@
+// Convert a color to grayscale by setting OKLCH chroma to 0
+// This preserves perceptual lightness (unlike simple RGB averaging)
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Create grayscale by removing chroma
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = 0;
+result.h = 0;
+
+return result;
+
+
+
+

package/src/schemas/functions/grayscale/schema.json

@@ -0,0 +1,20 @@
+{
+  "name": "Grayscale",
+  "type": "function",
+  "description": "Converts a color to grayscale by removing all chroma in OKLCH space. Preserves perceptual lightness.",
+  "keyword": "grayscale",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to convert to grayscale"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./grayscale.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/grayscale/unit.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Unit tests for the Grayscale function
+ * Converts color to grayscale by setting OKLCH chroma to 0
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Grayscale Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("grayscale", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Grayscale");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("grayscale");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should convert colored to grayscale", async () => {
+      const result = await executeWithSchema(
+        "grayscale",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 0.8; red.g = 0.2; red.b = 0.2;
+        grayscale(red).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      // All channels should be approximately equal (gray)
+      expect(Math.abs(r - g)).toBeLessThan(0.05);
+      expect(Math.abs(g - b)).toBeLessThan(0.05);
+    });
+
+    it("should preserve lightness", async () => {
+      const result = await executeWithSchema(
+        "grayscale",
+        "function",
+        `
+        variable bright: Color.SRGB;
+        bright.r = 0.9; bright.g = 0.9; bright.b = 0.3;
+        grayscale(bright).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      // Should still be relatively bright
+      expect(r).toBeGreaterThan(0.5);
+    });
+
+    it("should handle already gray colors", async () => {
+      const result = await executeWithSchema(
+        "grayscale",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        grayscale(gray).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      expect(r).toBeCloseTo(0.5, 1);
+      expect(g).toBeCloseTo(0.5, 1);
+      expect(b).toBeCloseTo(0.5, 1);
+    });
+  });
+});

package/src/schemas/functions/harmonize/harmonize.tokenscript

@@ -0,0 +1,61 @@
+// harmonize: Shift hue towards a source color for visual harmony
+// Reference: Material Design 3 Color System
+// Reference: https://m3.material.io/styles/color/dynamic-color
+//
+// Shifts the input color's hue towards a source color by a specified
+// amount, creating a harmonized palette. Uses OKLCH for perceptually
+// uniform hue interpolation via the shortest angular path.
+//
+// Parameters:
+//   color  - Color to harmonize
+//   source - Target hue source
+//   amount - Shift amount (0 = no change, 1 = match source), default 0.5
+//
+// Input:  Any color space (converted to OKLCH internally)
+// Output: OKLCH (working space)
+// To get sRGB: harmonize(color, source, 0.5).to.srgb()
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable source: Color.OKLCH = input.get(1).to.oklch();
+
+// Default harmonization amount (0.5 = 50% shift)
+variable amount: Number = 0.5;
+if (input.length() > 2) [
+    amount = input.get(2);
+];
+
+// Get hues
+variable color_hue: Number = color.h;
+variable source_hue: Number = source.h;
+
+// Calculate shortest path around the hue circle
+variable diff: Number = source_hue - color_hue;
+
+// Normalize to -180 to 180 range for shortest path
+if (diff > 180) [
+    diff = diff - 360;
+];
+if (diff < -180) [
+    diff = diff + 360;
+];
+
+// Apply harmonization: shift hue by amount * difference
+variable new_hue: Number = color_hue + (diff * amount);
+
+// Normalize hue to 0-360
+if (new_hue < 0) [
+    new_hue = new_hue + 360;
+];
+if (new_hue >= 360) [
+    new_hue = new_hue - 360;
+];
+
+// Create result with shifted hue, preserving lightness and chroma
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_hue;
+
+return result;
+

package/src/schemas/functions/harmonize/schema.json

@@ -0,0 +1,52 @@
+{
+  "name": "harmonize",
+  "type": "function",
+  "description": "Harmonizes a color by shifting its hue toward a source color. Inspired by Material Design 3's color harmonization algorithm. This creates visual cohesion in design systems by making colors feel related while preserving their identity. The amount parameter controls how much the hue shifts (0 = no change, 1 = full shift to source hue).",
+  "keyword": "harmonize",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to harmonize",
+            "type": "color"
+          },
+          {
+            "description": "Source color (hue target)",
+            "type": "color"
+          },
+          {
+            "description": "Amount of harmonization (0-1, default 0.5)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Harmonized color with hue shifted toward source"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./harmonize.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Harmonize red toward blue",
+      "input": ["#ff0000", "#0000ff", 0.3],
+      "output": "Color with hue shifted toward blue"
+    },
+    {
+      "description": "Harmonize green toward brand color",
+      "input": ["#00ff00", "#6750a4"],
+      "output": "Green shifted toward purple brand"
+    }
+  ]
+}

package/src/schemas/functions/harmonize/unit.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for the harmonize function
+ * Shifts a color's hue toward a source color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("harmonize function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("harmonize", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("harmonize");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should shift hue toward source color", async () => {
+      const result = await executeWithSchema(
+        "harmonize",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 1; color.g = 0; color.b = 0;
+        variable source: Color.SRGB;
+        source.r = 0; source.g = 0; source.b = 1;
+        harmonize(color, source, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect((result as any).constructor.name).toBe("ColorSymbol");
+    });
+
+    it("should return original color with amount 0", async () => {
+      const result = await executeWithSchema(
+        "harmonize",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 1; color.g = 0; color.b = 0;
+        variable source: Color.SRGB;
+        source.r = 0; source.g = 0; source.b = 1;
+        harmonize(color, source, 0).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+  });
+});

package/src/schemas/functions/hue/hue.tokenscript

@@ -0,0 +1,12 @@
+// hue: Extract hue angle from a color
+// Reference: OKLCH Color Space (Björn Ottosson)
+// Reference: https://bottosson.github.io/posts/oklab/
+//
+// Returns the H component from OKLCH, representing the
+// perceptually uniform hue angle. Range: 0-360 degrees.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+return color.h;
+

package/src/schemas/functions/hue/schema.json

@@ -0,0 +1,44 @@
+{
+  "name": "hue",
+  "type": "function",
+  "description": "Extracts the hue angle from any color using OKLCH. Returns a value from 0 to 360 degrees representing the color's position on the hue wheel. Hue in OKLCH is perceptually uniform, meaning equal angular steps produce equally perceived hue changes. Essential for color harmony calculations and palette generation.",
+  "keyword": "hue",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to extract hue from",
+            "type": "color"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 1
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "number",
+    "description": "Hue angle (0-360 degrees)"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./hue.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Red has hue around 30° in OKLCH",
+      "input": ["#ff0000"],
+      "output": 29
+    },
+    {
+      "description": "Cyan has hue around 195°",
+      "input": ["#00ffff"],
+      "output": 195
+    }
+  ]
+}

package/src/schemas/functions/hue/unit.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for the hue function
+ * Extracts hue angle from a color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("hue function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("hue", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("hue");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return hue for red (~30° in OKLCH)", async () => {
+      const result = await executeWithSchema(
+        "hue",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        hue(red)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const h = (result as any).value ?? result;
+      // Red in OKLCH has hue around 29-30°
+      expect(h).toBeGreaterThan(20);
+      expect(h).toBeLessThan(40);
+    });
+
+    it("should return hue for green (~142° in OKLCH)", async () => {
+      const result = await executeWithSchema(
+        "hue",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0; green.g = 1; green.b = 0;
+        hue(green)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const h = (result as any).value ?? result;
+      // Green in OKLCH has hue around 142°
+      expect(h).toBeGreaterThan(130);
+      expect(h).toBeLessThan(160);
+    });
+
+    it("should return hue for blue (~264° in OKLCH)", async () => {
+      const result = await executeWithSchema(
+        "hue",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        hue(blue)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const h = (result as any).value ?? result;
+      // Blue in OKLCH has hue around 264°
+      expect(h).toBeGreaterThan(250);
+      expect(h).toBeLessThan(280);
+    });
+  });
+});

package/src/schemas/functions/hue_difference/hue-difference.tokenscript

@@ -0,0 +1,42 @@
+// Hue Difference
+// Calculates angular hue difference using shortest path
+//
+// The hue circle wraps at 360°, so we need to find
+// the shortest angular distance between two hues.
+//
+// Examples:
+//   hue_diff(350°, 10°) = 20° (not 340°)
+//   hue_diff(0°, 180°) = 180° (maximum difference)
+//   hue_diff(90°, 90°) = 0° (same hue)
+//
+// Returns value in range [0, 180]
+
+variable input: List = {input};
+variable color1: Color.OKLCH = input.get(0).to.oklch();
+variable color2: Color.OKLCH = input.get(1).to.oklch();
+
+// Get hue values
+variable h1: Number = color1.h;
+variable h2: Number = color2.h;
+
+// Normalize to 0-360
+if (h1 < 0) [ h1 = h1 + 360; ];
+if (h1 >= 360) [ h1 = h1 - 360; ];
+if (h2 < 0) [ h2 = h2 + 360; ];
+if (h2 >= 360) [ h2 = h2 - 360; ];
+
+// Calculate raw difference
+variable diff: Number = h1 - h2;
+
+// Make positive
+if (diff < 0) [
+    diff = 0 - diff;
+];
+
+// Take shortest path around circle
+if (diff > 180) [
+    diff = 360 - diff;
+];
+
+return diff;
+

package/src/schemas/functions/hue_difference/schema.json

@@ -0,0 +1,24 @@
+{
+  "name": "Hue Difference",
+  "type": "function",
+  "description": "Calculates the angular difference between two color hues. Returns the shortest path around the hue circle (0-180°). Useful for determining how different two colors are in terms of hue alone, ignoring lightness and chroma.",
+  "keyword": "hue_difference",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./hue-difference.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/"]
+}