@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,123 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+
+describe("Delta E 76 Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("delta_e_76", "function");
+
+      expect(schema.name).toBe("Delta E 76");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("delta_e_76");
+    });
+  });
+
+  describe("Basic Calculations", () => {
+    it("should return 0 for identical colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.3; c1.b = 0.7;
+        variable c2: Color.SRGB;
+        c2.r = 0.5; c2.g = 0.3; c2.b = 0.7;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeCloseTo(0, 3);
+    });
+
+    it("should return large value for black vs white", async () => {
+      const result = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      // Black vs white in Lab: L difference is ~100
+      expect(result.value).toBeGreaterThan(90);
+    });
+  });
+
+  describe("Color.js Parity", () => {
+    it("should match Color.js for black vs white", async () => {
+      const result = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      const black = new Color("srgb", [0, 0, 0]);
+      const white = new Color("srgb", [1, 1, 1]);
+      const colorJsDeltaE = black.deltaE(white, "76");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+
+    it("should match Color.js for chromatic colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.8; c1.g = 0.2; c1.b = 0.2;
+        variable c2: Color.SRGB;
+        c2.r = 0.2; c2.g = 0.6; c2.b = 0.8;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      const color1 = new Color("srgb", [0.8, 0.2, 0.2]);
+      const color2 = new Color("srgb", [0.2, 0.6, 0.8]);
+      const colorJsDeltaE = color1.deltaE(color2, "76");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+  });
+
+  describe("Symmetry", () => {
+    it("should be symmetric", async () => {
+      const result1 = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.3; c1.g = 0.5; c1.b = 0.7;
+        variable c2: Color.SRGB;
+        c2.r = 0.7; c2.g = 0.3; c2.b = 0.5;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "delta_e_76",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.7; c1.g = 0.3; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.3; c2.g = 0.5; c2.b = 0.7;
+        delta_e_76(c1, c2)
+        `,
+      );
+
+      expect(result1.value).toBeCloseTo(result2.value, 5);
+    });
+  });
+});

package/src/schemas/functions/delta_e_ok/delta-e-ok.tokenscript

@@ -0,0 +1,43 @@
+// Delta E OK (ΔE_OK)
+// Perceptual color difference in OKLab space
+// Reference: Björn Ottosson's OKLab specification
+// Reference: Color.js deltaEOK implementation
+//
+// This is simply the Euclidean distance in OKLab space.
+// OKLab is designed to be perceptually uniform, making this
+// a reliable measure of perceived color difference.
+//
+// Interpretation:
+//   0.00       - Identical colors
+//   < 0.02     - Imperceptible difference (JND threshold)
+//   < 0.05     - Very close colors
+//   < 0.1      - Noticeable but small difference
+//   0.1 - 0.5  - Moderate difference
+//   > 0.5      - Very different colors
+//
+// Formula: sqrt((L1-L2)² + (a1-a2)² + (b1-b2)²)
+
+variable input: List = {input};
+variable color1: Color.OKLab = input.get(0).to.oklab();
+variable color2: Color.OKLab = input.get(1).to.oklab();
+
+// Get OKLab components
+variable l1: Number = color1.l;
+variable a1: Number = color1.a;
+variable b1: Number = color1.b;
+
+variable l2: Number = color2.l;
+variable a2: Number = color2.a;
+variable b2: Number = color2.b;
+
+// Calculate differences
+variable delta_l: Number = l1 - l2;
+variable delta_a: Number = a1 - a2;
+variable delta_b: Number = b1 - b2;
+
+// Calculate Euclidean distance (sqrt of sum of squares)
+variable sum_squares: Number = delta_l * delta_l + delta_a * delta_a + delta_b * delta_b;
+variable result: Number = sqrt(sum_squares);
+
+return result;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Delta E OK",
+  "type": "function",
+  "description": "Calculates perceptual color difference using the OKLab color space (ΔE_OK). This is the Euclidean distance in OKLab space, providing excellent perceptual uniformity. Values: 0 = identical, <0.02 = imperceptible, <0.05 = very close, <0.1 = noticeable, >0.5 = very different.",
+  "keyword": "delta_e_ok",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color (reference)"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color (sample)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./delta-e-ok.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklab-color/0/"]
+}

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

@@ -0,0 +1,235 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+
+describe("Delta E OK Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("delta_e_ok", "function");
+
+      expect(schema.name).toBe("Delta E OK");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("delta_e_ok");
+    });
+  });
+
+  describe("Basic Calculations", () => {
+    it("should return 0 for identical colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.3; c1.b = 0.7;
+        variable c2: Color.SRGB;
+        c2.r = 0.5; c2.g = 0.3; c2.b = 0.7;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeCloseTo(0, 5);
+    });
+
+    it("should return small value for very similar colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.51; c2.g = 0.5; c2.b = 0.5;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      // Very small difference
+      expect(result.value).toBeLessThan(0.05);
+      expect(result.value).toBeGreaterThan(0);
+    });
+
+    it("should return large value for very different colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      // Black vs white is a very large difference
+      expect(result.value).toBeGreaterThan(0.9);
+    });
+  });
+
+  describe("Symmetry", () => {
+    it("should be symmetric - order of colors should not matter", async () => {
+      const result1 = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.2; c1.g = 0.4; c1.b = 0.6;
+        variable c2: Color.SRGB;
+        c2.r = 0.6; c2.g = 0.2; c2.b = 0.4;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.6; c1.g = 0.2; c1.b = 0.4;
+        variable c2: Color.SRGB;
+        c2.r = 0.2; c2.g = 0.4; c2.b = 0.6;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      expect(result1.value).toBeCloseTo(result2.value, 10);
+    });
+  });
+
+  describe("Color.js Parity", () => {
+    it("should match Color.js deltaE for black vs white", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      const black = new Color("srgb", [0, 0, 0]);
+      const white = new Color("srgb", [1, 1, 1]);
+      const colorJsDeltaE = black.deltaE(white, "OK");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 3);
+    });
+
+    it("should match Color.js deltaE for red vs blue", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 1; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 0; c2.g = 0; c2.b = 1;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      const red = new Color("srgb", [1, 0, 0]);
+      const blue = new Color("srgb", [0, 0, 1]);
+      const colorJsDeltaE = red.deltaE(blue, "OK");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 3);
+    });
+
+    it("should match Color.js deltaE for similar grays", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.55; c2.g = 0.55; c2.b = 0.55;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      const gray1 = new Color("srgb", [0.5, 0.5, 0.5]);
+      const gray2 = new Color("srgb", [0.55, 0.55, 0.55]);
+      const colorJsDeltaE = gray1.deltaE(gray2, "OK");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 3);
+    });
+
+    it("should match Color.js deltaE for chromatic colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.8; c1.g = 0.2; c1.b = 0.4;
+        variable c2: Color.SRGB;
+        c2.r = 0.3; c2.g = 0.6; c2.b = 0.5;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      const color1 = new Color("srgb", [0.8, 0.2, 0.4]);
+      const color2 = new Color("srgb", [0.3, 0.6, 0.5]);
+      const colorJsDeltaE = color1.deltaE(color2, "OK");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 3);
+    });
+  });
+
+  describe("Perceptual Thresholds", () => {
+    it("should detect imperceptible difference (< 0.02 JND)", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.502; c2.g = 0.5; c2.b = 0.5;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      // Should be below JND threshold
+      expect(result.value).toBeLessThan(0.02);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle primary colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "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;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      // Red vs green should be a significant difference
+      expect(result.value).toBeGreaterThan(0.3);
+    });
+
+    it("should always return non-negative values", async () => {
+      const result = await executeWithSchema(
+        "delta_e_ok",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.1; c1.g = 0.9; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.9; c2.g = 0.1; c2.b = 0.5;
+        delta_e_ok(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeGreaterThanOrEqual(0);
+    });
+  });
+});

package/src/schemas/functions/desaturate/desaturate.tokenscript

@@ -0,0 +1,32 @@
+// Desaturate a color by decreasing its OKLCH chroma
+// Amount: 0-1 where 0.25 means 25% decrease, 1.0 = full grayscale
+//
+// Algorithm: C' = C * (1 - amount)
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Default amount is 0.25 (25%)
+variable amount: Number = 0.25;
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Calculate new chroma
+variable current_c: Number = color.c;
+variable new_c: Number = current_c * (1 - amount);
+
+// Clamp to valid range
+if (new_c < 0) [ new_c = 0; ];
+
+// Create output in OKLCH, return as sRGB
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+
+
+
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Desaturate",
+  "type": "function",
+  "description": "Decreases color saturation by reducing chroma in OKLCH space. Amount is 0-1 where 0.25 = 25% less saturated.",
+  "keyword": "desaturate",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to desaturate"
+      },
+      "amount": {
+        "type": "number",
+        "description": "Amount to desaturate (0-1). Default is 0.25"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./desaturate.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Unit tests for the Desaturate function
+ * Decreases color saturation by reducing OKLCH chroma
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Desaturate Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("desaturate", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Desaturate");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("desaturate");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should decrease saturation of a vivid color", async () => {
+      const result = await executeWithSchema(
+        "desaturate",
+        "function",
+        `
+        variable vivid: Color.SRGB;
+        vivid.r = 0.9; vivid.g = 0.2; vivid.b = 0.2;
+        desaturate(vivid, 0.1).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      // Desaturated color channels should be closer together
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      expect(r - g).toBeLessThan(0.9 - 0.2);
+    });
+
+    it("should use default amount of 0.1", async () => {
+      const result = await executeWithSchema(
+        "desaturate",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.8; color.g = 0.3; color.b = 0.3;
+        desaturate(color).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+    });
+  });
+});

package/src/schemas/functions/distributed/distributed.tokenscript

@@ -0,0 +1,54 @@
+// Create evenly distributed categorical colors using OKLCH
+// Colors are spaced equally around the hue wheel
+//
+// Ideal for: pie charts, bar charts, legends, category labels
+// Uses golden angle offset for better distinction with many colors
+
+variable input: List = {input};
+
+// Default count is 6
+variable count: Number = 6;
+if (input.length() > 0) [
+    count = input.get(0);
+];
+
+// Default lightness is 0.7 (good for both light/dark backgrounds)
+variable lightness: Number = 0.7;
+if (input.length() > 1) [
+    lightness = input.get(1);
+];
+
+// Default chroma is 0.15 (vivid but not overwhelming)
+variable chroma: Number = 0.15;
+if (input.length() > 2) [
+    chroma = input.get(2);
+];
+
+// Default start hue is 30 (orange - visually distinct starting point)
+variable start_hue: Number = 30;
+if (input.length() > 3) [
+    start_hue = input.get(3);
+];
+
+// Calculate hue step (360° / count for even distribution)
+variable hue_step: Number = 360 / count;
+
+variable result: List;
+variable i: Number = 0;
+variable current_hue: Number = 0;
+variable color: Color.OKLCH;
+
+while (i < count) [
+    current_hue = start_hue + i * hue_step;
+    if (current_hue >= 360) [ current_hue = current_hue - 360; ];
+    
+    color.l = lightness;
+    color.c = chroma;
+    color.h = current_hue;
+    
+    result = result, color.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,32 @@
+{
+  "name": "Distributed",
+  "type": "function",
+  "description": "Creates evenly distributed colors around the OKLCH hue wheel. Perfect for categorical data where each category needs a distinct, visually balanced color.",
+  "keyword": "distributed",
+  "input": {
+    "type": "object",
+    "properties": {
+      "count": {
+        "type": "number",
+        "description": "Number of colors to generate. Default is 6"
+      },
+      "lightness": {
+        "type": "number",
+        "description": "Lightness for all colors (0-1). Default is 0.7"
+      },
+      "chroma": {
+        "type": "number",
+        "description": "Chroma/saturation for all colors (0-0.4). Default is 0.15"
+      },
+      "start_hue": {
+        "type": "number",
+        "description": "Starting hue angle (0-360). Default is 30 (orange)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./distributed.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Unit tests for the Distributed function
+ * Creates evenly distributed categorical colors using OKLCH
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Distributed Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("distributed", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Distributed");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("distributed");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 6 colors by default", async () => {
+      const result = await executeWithSchema(
+        "distributed",
+        "function",
+        `
+        distributed()
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of colors", async () => {
+      const result = await executeWithSchema(
+        "distributed",
+        "function",
+        `
+        distributed(8)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should allow custom lightness and chroma", async () => {
+      const result = await executeWithSchema(
+        "distributed",
+        "function",
+        `
+        distributed(5, 0.6, 0.2)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});