@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for the Darken function
+ * Decreases color lightness in OKLab perceptual space
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Darken Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("darken", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Darken");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("darken");
+    });
+
+    it("should have script defined", async () => {
+      const schema = (await getBundledSchema("darken", "function")) as FunctionSpecification;
+
+      expect(schema.script).toBeDefined();
+      expect(schema.script.script).toBeTruthy();
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should darken a light color", async () => {
+      const result = await executeWithSchema(
+        "darken",
+        "function",
+        `
+        variable light: Color.SRGB;
+        light.r = 0.8; light.g = 0.8; light.b = 0.9;
+        darken(light, 0.2).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).toBeLessThan(0.8);
+      expect(g).toBeLessThan(0.8);
+      expect(b).toBeLessThan(0.9);
+    });
+
+    it("should use default amount of 0.25", async () => {
+      const result = await executeWithSchema(
+        "darken",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.7; color.g = 0.7; color.b = 0.7;
+        darken(color).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      expect(r).toBeLessThan(0.7);
+    });
+
+    it("should not go below minimum lightness", async () => {
+      const result = await executeWithSchema(
+        "darken",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.1; dark.g = 0.1; dark.b = 0.1;
+        darken(dark, 0.5).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).toBeGreaterThanOrEqual(0);
+      expect(g).toBeGreaterThanOrEqual(0);
+      expect(b).toBeGreaterThanOrEqual(0);
+    });
+
+    it("should preserve hue when darkening", async () => {
+      const result = await executeWithSchema(
+        "darken",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0.3; blue.g = 0.5; blue.b = 0.9;
+        darken(blue, 0.15).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;
+      // Blue should still dominate
+      expect(b).toBeGreaterThan(r);
+      expect(b).toBeGreaterThan(g);
+    });
+  });
+});

package/src/schemas/functions/delta_e_2000/delta-e-2000.tokenscript

@@ -0,0 +1,184 @@
+// CIEDE2000 Color Difference Formula (ΔE00)
+// Reference: CIE 142-2001 (Technical Report)
+// Reference: Color.js deltaE2000 implementation
+// Reference: Sharma, Wu, Dalal "The CIEDE2000 Color-Difference Formula" (2005)
+//
+// This is the CIE-recommended color difference formula, providing
+// better correlation with visual perception than CIE76 or CIE94.
+//
+// Parametric factors (kL, kC, kH):
+// - All default to 1.0 for reference conditions
+// - kL can be increased for lightness texture/noise
+// - kC can be increased for chroma noise
+//
+// Interpretation (approximate):
+//   0.0        - Identical colors
+//   < 1.0      - Not perceptible by human eye
+//   1.0 - 2.0  - Perceptible through close observation
+//   2.0 - 10.0 - Perceptible at a glance
+//   > 10.0     - Colors are obviously different
+
+variable input: List = {input};
+
+// Convert both colors to CIE Lab
+variable color1: Color.Lab = input.get(0).to.lab();
+variable color2: Color.Lab = input.get(1).to.lab();
+
+// Get parametric weighting factors (default to 1)
+variable k_l: Number = 1;
+variable k_c: Number = 1;
+variable k_h: Number = 1;
+if (input.length() > 2) [ k_l = input.get(2); ];
+if (input.length() > 3) [ k_c = input.get(3); ];
+if (input.length() > 4) [ k_h = input.get(4); ];
+
+// Constants
+variable pi: Number = pi();
+variable r2d: Number = 180 / pi;
+variable d2r: Number = pi / 180;
+variable g_factor: Number = 6103515625; // 25^7
+variable e: Number = 2.718281828459045; // Euler's number
+
+// Get Lab values
+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 C* (chroma) for both colors
+variable c1: Number = sqrt(a1 * a1 + b1 * b1);
+variable c2: Number = sqrt(a2 * a2 + b2 * b2);
+
+// Ensure non-negative chroma
+if (c1 < 0) [ c1 = 0; ];
+if (c2 < 0) [ c2 = 0; ];
+
+// Mean chroma
+variable c_bar: Number = (c1 + c2) / 2;
+
+// Calculate G (a-axis asymmetry factor)
+variable c7: Number = c_bar * c_bar * c_bar * c_bar * c_bar * c_bar * c_bar;
+variable g: Number = 0.5 * (1 - sqrt(c7 / (c7 + g_factor)));
+
+// Scale a* values by asymmetry factor
+variable a_prime1: Number = (1 + g) * a1;
+variable a_prime2: Number = (1 + g) * a2;
+
+// Calculate C' from scaled a' and original b
+variable c_prime1: Number = sqrt(a_prime1 * a_prime1 + b1 * b1);
+variable c_prime2: Number = sqrt(a_prime2 * a_prime2 + b2 * b2);
+
+// Calculate h' (hue angles in degrees)
+variable h1: Number = 0;
+if (a_prime1 != 0) [ h1 = atan2(b1, a_prime1); ];
+if (b1 != 0) [ h1 = atan2(b1, a_prime1); ];
+if (a_prime1 == 0) [
+    if (b1 == 0) [ h1 = 0; ] else [ h1 = atan2(b1, a_prime1); ];
+];
+h1 = h1 * r2d;
+if (h1 < 0) [ h1 = h1 + 360; ];
+
+variable h2: Number = 0;
+if (a_prime2 != 0) [ h2 = atan2(b2, a_prime2); ];
+if (b2 != 0) [ h2 = atan2(b2, a_prime2); ];
+if (a_prime2 == 0) [
+    if (b2 == 0) [ h2 = 0; ] else [ h2 = atan2(b2, a_prime2); ];
+];
+h2 = h2 * r2d;
+if (h2 < 0) [ h2 = h2 + 360; ];
+
+// Lightness and Chroma differences
+variable delta_l: Number = l2 - l1;
+variable delta_c: Number = c_prime2 - c_prime1;
+
+// Hue difference (getting the sign correct)
+variable h_diff: Number = h2 - h1;
+variable h_sum: Number = h1 + h2;
+variable h_abs: Number = h_diff;
+if (h_abs < 0) [ h_abs = 0 - h_abs; ];
+
+variable delta_h: Number = 0;
+variable c_product: Number = c_prime1 * c_prime2;
+
+if (c_product == 0) [
+    delta_h = 0;
+] else [
+    if (h_abs <= 180) [
+        delta_h = h_diff;
+    ] else [
+        if (h_diff > 180) [
+            delta_h = h_diff - 360;
+        ] else [
+            if (h_diff < -180) [
+                delta_h = h_diff + 360;
+            ] else [
+                delta_h = h_diff;
+            ];
+        ];
+    ];
+];
+
+// Weighted hue difference (ΔH')
+variable delta_h_prime: Number = 2 * sqrt(c_prime2 * c_prime1) * sin(delta_h * d2r / 2);
+
+// Mean lightness and chroma
+variable l_bar: Number = (l1 + l2) / 2;
+variable c_bar_prime: Number = (c_prime1 + c_prime2) / 2;
+variable c_bar_prime7: Number = c_bar_prime * c_bar_prime * c_bar_prime * c_bar_prime * c_bar_prime * c_bar_prime * c_bar_prime;
+
+// Mean hue (handling the 0/360 wraparound)
+variable h_bar: Number = 0;
+if (c_product == 0) [
+    h_bar = h_sum;
+] else [
+    if (h_abs <= 180) [
+        h_bar = h_sum / 2;
+    ] else [
+        if (h_sum < 360) [
+            h_bar = (h_sum + 360) / 2;
+        ] else [
+            h_bar = (h_sum - 360) / 2;
+        ];
+    ];
+];
+
+// SL - Lightness crispening factor (assumes L=50 background)
+variable l_bar_minus_50: Number = l_bar - 50;
+variable l_sq: Number = l_bar_minus_50 * l_bar_minus_50;
+variable s_l: Number = 1 + (0.015 * l_sq) / sqrt(20 + l_sq);
+
+// SC - Chroma factor
+variable s_c: Number = 1 + 0.045 * c_bar_prime;
+
+// T - Cross term for blue non-linearity
+variable t: Number = 1;
+t = t - 0.17 * cos((h_bar - 30) * d2r);
+t = t + 0.24 * cos(2 * h_bar * d2r);
+t = t + 0.32 * cos((3 * h_bar + 6) * d2r);
+t = t - 0.20 * cos((4 * h_bar - 63) * d2r);
+
+// SH - Hue factor
+variable s_h: Number = 1 + 0.015 * c_bar_prime * t;
+
+// RT - Hue rotation term (for blue region 225-315 degrees)
+variable h_bar_minus_275: Number = h_bar - 275;
+variable exp_arg: Number = -1 * (h_bar_minus_275 / 25) * (h_bar_minus_275 / 25);
+variable delta_theta: Number = 30 * pow(e, exp_arg);
+variable r_c: Number = 2 * sqrt(c_bar_prime7 / (c_bar_prime7 + g_factor));
+variable r_t: Number = -1 * sin(2 * delta_theta * d2r) * r_c;
+
+// Calculate final ΔE00
+variable term_l: Number = delta_l / (k_l * s_l);
+variable term_c: Number = delta_c / (k_c * s_c);
+variable term_h: Number = delta_h_prime / (k_h * s_h);
+
+variable de: Number = term_l * term_l + term_c * term_c + term_h * term_h;
+de = de + r_t * (delta_c / (k_c * s_c)) * (delta_h_prime / (k_h * s_h));
+
+variable result: Number = sqrt(de);
+
+return result;
+

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

@@ -0,0 +1,36 @@
+{
+  "name": "Delta E 2000",
+  "type": "function",
+  "description": "Calculates perceptual color difference using CIEDE2000 (ΔE00), the CIE-recommended color difference formula. More accurate than CIE76 for small differences. Industry standard for color quality control. Uses parametric weighting factors kL, kC, kH (all default to 1).",
+  "keyword": "delta_e_2000",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color (reference)"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color (sample)"
+      },
+      "kL": {
+        "type": "number",
+        "description": "Lightness weight (default 1)"
+      },
+      "kC": {
+        "type": "number",
+        "description": "Chroma weight (default 1)"
+      },
+      "kH": {
+        "type": "number",
+        "description": "Hue weight (default 1)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./delta-e-2000.tokenscript"
+  },
+  "requirements": ["/api/v1/core/lab-color/0/", "/api/v1/core/lch-color/0/"]
+}

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

@@ -0,0 +1,243 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+
+describe("Delta E 2000 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_2000", "function");
+
+      expect(schema.name).toBe("Delta E 2000");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("delta_e_2000");
+    });
+  });
+
+  describe("Basic Calculations", () => {
+    it("should return 0 for identical colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeCloseTo(0, 3);
+    });
+
+    it("should return large value for black vs white", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      // Black vs white is a very large difference (should be ~100)
+      expect(result.value).toBeGreaterThan(90);
+    });
+  });
+
+  describe("Symmetry", () => {
+    it("should be symmetric - order should not matter", async () => {
+      const result1 = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      expect(result1.value).toBeCloseTo(result2.value, 5);
+    });
+  });
+
+  describe("Color.js Parity", () => {
+    it("should match Color.js for black vs white", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      const black = new Color("srgb", [0, 0, 0]);
+      const white = new Color("srgb", [1, 1, 1]);
+      const colorJsDeltaE = black.deltaE(white, "2000");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+
+    it("should match Color.js for red vs blue", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      const red = new Color("srgb", [1, 0, 0]);
+      const blue = new Color("srgb", [0, 0, 1]);
+      const colorJsDeltaE = red.deltaE(blue, "2000");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+
+    it("should match Color.js for similar grays", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(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, "2000");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+
+    it("should match Color.js for chromatic colors", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(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, "2000");
+
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 1);
+    });
+  });
+
+  describe("Perceptual Thresholds", () => {
+    it("should detect imperceptible difference (< 1.0)", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.505; c2.g = 0.5; c2.b = 0.5;
+        delta_e_2000(c1, c2)
+        `,
+      );
+
+      // Very small differences should be < 1.0 (imperceptible threshold)
+      expect(result.value).toBeLessThan(2);
+    });
+  });
+
+  describe("Blue Region Correction", () => {
+    it("should handle blue region colors (RT correction)", async () => {
+      // Blue region (225-315 degrees) has special rotation term
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.2; c1.g = 0.2; c1.b = 0.8;
+        variable c2: Color.SRGB;
+        c2.r = 0.3; c2.g = 0.2; c2.b = 0.7;
+        delta_e_2000(c1, c2)
+        `,
+      );
+
+      const blue1 = new Color("srgb", [0.2, 0.2, 0.8]);
+      const blue2 = new Color("srgb", [0.3, 0.2, 0.7]);
+      const colorJsDeltaE = blue1.deltaE(blue2, "2000");
+
+      // Should be close to Color.js (allows for some tolerance due to complexity)
+      expect(result.value).toBeCloseTo(colorJsDeltaE, 0);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle achromatic colors (C=0)", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.3; c1.g = 0.3; c1.b = 0.3;
+        variable c2: Color.SRGB;
+        c2.r = 0.7; c2.g = 0.7; c2.b = 0.7;
+        delta_e_2000(c1, c2)
+        `,
+      );
+
+      // Two grays - should give valid result
+      expect(typeof result.value).toBe("number");
+      expect(Number.isFinite(result.value)).toBe(true);
+      expect(result.value).toBeGreaterThan(0);
+    });
+
+    it("should always return non-negative values", async () => {
+      const result = await executeWithSchema(
+        "delta_e_2000",
+        "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_2000(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBeGreaterThanOrEqual(0);
+    });
+  });
+});

package/src/schemas/functions/delta_e_76/delta-e-76.tokenscript

@@ -0,0 +1,45 @@
+// Delta E 76 (CIE76 Color Difference)
+// Reference: CIE Publication 15.2 (1986)
+// Reference: ASTM E308 Standard
+//
+// The original CIE color difference formula from 1976.
+// Simple Euclidean distance in CIE Lab space.
+//
+// Formula: ΔE*ab = sqrt((L1-L2)² + (a1-a2)² + (b1-b2)²)
+//
+// Interpretation:
+//   0 - 1:     Not perceptible by human eye
+//   1 - 2:     Perceptible through close observation
+//   2 - 10:    Perceptible at a glance
+//   11 - 49:   Colors are more similar than opposite
+//   100+:      Colors are exact opposite
+//
+// Limitations:
+// - Lab is not perfectly perceptually uniform
+// - Overestimates differences for saturated colors
+// - Use Delta E 2000 for critical color matching
+
+variable input: List = {input};
+variable color1: Color.Lab = input.get(0).to.lab();
+variable color2: Color.Lab = input.get(1).to.lab();
+
+// Get Lab 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;
+
+// Euclidean distance
+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_76/schema.json

@@ -0,0 +1,24 @@
+{
+  "name": "Delta E 76",
+  "type": "function",
+  "description": "Calculates color difference using CIE76 formula (ΔE*ab). Simple Euclidean distance in CIE Lab space. Less accurate than Delta E 2000 for small differences, but faster and adequate for many applications. Formula: sqrt((L1-L2)² + (a1-a2)² + (b1-b2)²).",
+  "keyword": "delta_e_76",
+  "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-76.tokenscript"
+  },
+  "requirements": ["/api/v1/core/lab-color/0/"]
+}