@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,125 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Hue Difference Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("hue_difference", "function");
+
+      expect(schema.name).toBe("Hue Difference");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("hue_difference");
+    });
+  });
+
+  describe("Same Hue", () => {
+    it("should return 0 for identical colors", async () => {
+      const result = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 0; c2.b = 0;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeCloseTo(0, 1);
+    });
+  });
+
+  describe("Complementary Colors", () => {
+    it("should return ~180 for complement colors", async () => {
+      // Red vs Cyan are complementary
+      const result = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 0; c2.g = 1; c2.b = 1;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      // Should be close to 180 (complementary)
+      expect(result.value).toBeGreaterThan(150);
+    });
+  });
+
+  describe("Shortest Path", () => {
+    it("should take shortest path around hue circle", async () => {
+      // Test with colors near the 0/360 boundary
+      // Magenta (high hue ~330) vs Red (low hue ~30)
+      // Should be ~60, not ~300
+      const result = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 0; c2.b = 0.5;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      // Should take short path
+      expect(result.value).toBeLessThan(180);
+    });
+  });
+
+  describe("Adjacent Colors", () => {
+    it("should return small value for adjacent hues", async () => {
+      // Red and Orange are adjacent
+      const result = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 0.5; c2.b = 0;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      // Adjacent colors should have small difference
+      expect(result.value).toBeLessThan(60);
+    });
+  });
+
+  describe("Symmetry", () => {
+    it("should be symmetric", async () => {
+      const result1 = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 0; c2.g = 1; c2.b = 0;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "hue_difference",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 1; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 0; c2.b = 0;
+        hue_difference(c1, c2)
+        `,
+      );
+
+      expect(result1.value).toBeCloseTo(result2.value, 3);
+    });
+  });
+});

package/src/schemas/functions/in_gamut/in-gamut.tokenscript

@@ -0,0 +1,51 @@
+// In Gamut Check
+// Checks if a color is within the sRGB gamut
+// Reference: Color.js inGamut implementation
+//
+// sRGB gamut is defined by all RGB components being in [0, 1]
+// This is critical for determining if colors can be displayed
+// on standard monitors without clipping.
+//
+// An epsilon tolerance is used to handle floating-point precision
+// issues near the gamut boundary.
+
+variable input: List = {input};
+variable color: Color.SRGB = input.get(0).to.srgb();
+
+// Default epsilon from Color.js
+variable epsilon: Number = 0.000075;
+if (input.length() > 1) [
+    epsilon = input.get(1);
+];
+
+// Get RGB values
+variable r: Number = color.r;
+variable g: Number = color.g;
+variable b: Number = color.b;
+
+// Check if within gamut bounds with epsilon tolerance
+variable min_bound: Number = 0 - epsilon;
+variable max_bound: Number = 1 + epsilon;
+
+// All channels must be within bounds
+variable r_in: Boolean = r >= min_bound;
+if (r_in) [ r_in = r <= max_bound; ];
+
+variable g_in: Boolean = g >= min_bound;
+if (g_in) [ g_in = g <= max_bound; ];
+
+variable b_in: Boolean = b >= min_bound;
+if (b_in) [ b_in = b <= max_bound; ];
+
+// Return true only if all channels are in gamut
+variable result: Boolean = false;
+if (r_in) [
+    if (g_in) [
+        if (b_in) [
+            result = true;
+        ];
+    ];
+];
+
+return result;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "In Gamut",
+  "type": "function",
+  "description": "Checks if a color is within the sRGB gamut. Returns true if all RGB components are in [0,1] range, false otherwise. Useful for checking if colors from wider gamuts (P3, OKLab) can be displayed on standard monitors.",
+  "keyword": "in_gamut",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Color to check"
+      },
+      "epsilon": {
+        "type": "number",
+        "description": "Tolerance for near-gamut colors (default 0.000075)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./in-gamut.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,178 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("In Gamut Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("in_gamut", "function");
+
+      expect(schema.name).toBe("In Gamut");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("in_gamut");
+    });
+  });
+
+  describe("Basic Checks", () => {
+    it("should return true for black (0,0,0)", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0; c.b = 0;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for white (1,1,1)", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 1; c.b = 1;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for mid-gray (0.5,0.5,0.5)", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0.5; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for primary red (1,0,0)", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 0; c.b = 0;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe("Out of Gamut Detection", () => {
+    it("should return false for negative R", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = -0.1; c.g = 0.5; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for R > 1", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1.1; c.g = 0.5; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for negative G", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = -0.05; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for B > 1", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0.5; c.b = 1.2;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+
+  describe("Epsilon Tolerance", () => {
+    it("should return true for values just within epsilon", async () => {
+      // Default epsilon is 0.000075
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1.00005; c.g = 0.5; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return false for values outside epsilon", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1.001; c.g = 0.5; c.b = 0.5;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle exact boundary values", async () => {
+      const result = await executeWithSchema(
+        "in_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 1; c.b = 0;
+        in_gamut(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+});

package/src/schemas/functions/interpolate/interpolate.tokenscript

@@ -0,0 +1,61 @@
+// interpolate: Blend between two colors in perceptual space
+// Reference: CSS Color Level 4 Color Interpolation
+// Reference: https://www.w3.org/TR/css-color-4/#interpolation
+//
+// Performs linear interpolation in OKLCH space with shortest-path
+// hue interpolation. OKLCH provides perceptually uniform results.
+//
+// Parameters:
+//   start - First color (t=0)
+//   end   - Second color (t=1)
+//   t     - Interpolation factor [0, 1], default 0.5
+//
+// Input:  Any color space (converted to OKLCH internally)
+// Output: OKLCH (working space)
+// To get sRGB: interpolate(start, end, 0.5).to.srgb()
+
+variable input: List = {input};
+variable start: Color.OKLCH = input.get(0).to.oklch();
+variable end: Color.OKLCH = input.get(1).to.oklch();
+
+// Default to midpoint
+variable t: Number = 0.5;
+if (input.length() > 2) [
+    t = input.get(2);
+];
+
+// Clamp t to valid range
+if (t < 0) [ t = 0; ];
+if (t > 1) [ t = 1; ];
+
+// Interpolate lightness and chroma linearly
+variable result_l: Number = start.l + (end.l - start.l) * t;
+variable result_c: Number = start.c + (end.c - start.c) * t;
+
+// Interpolate hue using shortest path
+variable h1: Number = start.h;
+variable h2: Number = end.h;
+variable delta_h: Number = h2 - h1;
+
+// Normalize to shortest path around the circle
+if (delta_h > 180) [
+    delta_h = delta_h - 360;
+];
+if (delta_h < -180) [
+    delta_h = delta_h + 360;
+];
+
+variable result_h: Number = h1 + delta_h * t;
+
+// Normalize result hue to 0-360
+if (result_h < 0) [ result_h = result_h + 360; ];
+if (result_h >= 360) [ result_h = result_h - 360; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = result_l;
+result.c = result_c;
+result.h = result_h;
+
+return result;
+

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

@@ -0,0 +1,52 @@
+{
+  "name": "interpolate",
+  "type": "function",
+  "description": "Interpolates between two colors at a given position in perceptual OKLCH space. Position of 0 returns the first color, 1 returns the second color, 0.5 returns the midpoint. Uses shortest-path hue interpolation for natural color transitions.",
+  "keyword": "interpolate",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Start color",
+            "type": "color"
+          },
+          {
+            "description": "End color",
+            "type": "color"
+          },
+          {
+            "description": "Position (0-1, default 0.5)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Interpolated color"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./interpolate.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Midpoint between red and blue",
+      "input": ["#ff0000", "#0000ff", 0.5],
+      "output": "Purple-ish color in OKLCH"
+    },
+    {
+      "description": "Quarter way from black to white",
+      "input": ["#000000", "#ffffff", 0.25],
+      "output": "Dark gray"
+    }
+  ]
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Unit tests for the interpolate function
+ * Interpolates between colors in perceptual space
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("interpolate function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("interpolate", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("interpolate");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return start color at t=0", async () => {
+      const result = await executeWithSchema(
+        "interpolate",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        interpolate(black, white, 0).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should return end color at t=1", async () => {
+      const result = await executeWithSchema(
+        "interpolate",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        interpolate(black, white, 1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+
+    it("should return midpoint at t=0.5", async () => {
+      const result = await executeWithSchema(
+        "interpolate",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        interpolate(black, white, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      // Should be medium gray
+      expect(r).toBeGreaterThan(0.3);
+      expect(r).toBeLessThan(0.7);
+    });
+
+    it("should use default t=0.5", async () => {
+      const result = await executeWithSchema(
+        "interpolate",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        interpolate(black, white).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.3);
+      expect(r).toBeLessThan(0.7);
+    });
+  });
+});

package/src/schemas/functions/invert/invert-initializer.tokenscript

@@ -0,0 +1,29 @@
+// Invert Color Function
+// Returns the inverse/negative of a color by subtracting each RGB channel from 255
+//
+// Algorithm:
+//   R' = 255 - R
+//   G' = 255 - G  
+//   B' = 255 - B
+//
+// Use cases:
+//   - Creating negative images
+//   - High contrast accessibility variants
+//   - Artistic color effects
+//
+// Input: Any color (converted to RGB internally)
+// Output: Color.Rgb with inverted channels
+
+variable input: List = {input};
+
+// Convert input to RGB (0-255 range)
+variable rgb_color: Color.Rgb = input.get(0).to.rgb();
+
+// Invert each channel by subtracting from 255
+variable inverted_r: Number = 255 - rgb_color.r;
+variable inverted_g: Number = 255 - rgb_color.g;
+variable inverted_b: Number = 255 - rgb_color.b;
+
+// Create and return the inverted color
+variable inverted_color: Color.Rgb = rgb(inverted_r, inverted_g, inverted_b);
+return inverted_color;

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

@@ -0,0 +1,20 @@
+{
+  "name": "Invert Color",
+  "type": "function",
+  "description": "Inverts a color by inverting each RGB channel (R' = 255 - R, G' = 255 - G, B' = 255 - B).",
+  "keyword": "invert",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to invert."
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./invert-initializer.tokenscript"
+  },
+  "requirements": ["/api/v1/core/rgb-color/0/"]
+}