@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/schemas/types/hwb-color/unit.test.ts

@@ -0,0 +1,150 @@
+/**
+ * HWB Color Schema Tests
+ *
+ * Tests for the HWB color space (Hue, Whiteness, Blackness)
+ * Validates against ColorJS for parity
+ */
+
+import { log } from "@tests/helpers/logger";
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+import type { ColorSpecification } from "@/bundler/types";
+
+// ColorJS reference tolerance
+const TOLERANCE = 1e-9;
+const HUE_TOLERANCE = 1e-6;
+
+describe("HWB Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("hwb-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("HWB");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("h");
+      expect(schema.schema?.properties).toHaveProperty("w");
+      expect(schema.schema?.properties).toHaveProperty("b");
+    });
+  });
+
+  describe("ColorJS Parity", () => {
+    const testCases = [
+      { name: "red", srgb: [1, 0, 0] },
+      { name: "green", srgb: [0, 1, 0] },
+      { name: "blue", srgb: [0, 0, 1] },
+      { name: "cyan", srgb: [0, 1, 1] },
+      { name: "magenta", srgb: [1, 0, 1] },
+      { name: "yellow", srgb: [1, 1, 0] },
+      { name: "coral", srgb: [1, 0.5, 0.314] },
+    ];
+
+    for (const { name, srgb } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "hwb-color",
+          "type",
+          `
+          variable srgb: Color.SRGB;
+          srgb.r = ${srgb[0]};
+          srgb.g = ${srgb[1]};
+          srgb.b = ${srgb[2]};
+          
+          variable hsv: Color.HSV = srgb.to.hsv();
+          hsv.to.hwb()
+        `,
+        );
+
+        // ColorJS reference (uses 0-100 for W and B, we use 0-1)
+        const colorJS = new Color("srgb", srgb as [number, number, number]).to("hwb");
+        const cjW = colorJS.coords[1] / 100;
+        const cjB = colorJS.coords[2] / 100;
+
+        const tsH = (result as any).value.h.value;
+        const tsW = (result as any).value.w.value;
+        const tsB = (result as any).value.b.value;
+
+        let diffH = Math.abs(tsH - colorJS.coords[0]);
+        if (diffH > 180) diffH = 360 - diffH;
+        const diffW = Math.abs(tsW - cjW);
+        const diffB = Math.abs(tsB - cjB);
+        const maxDiff = Math.max(diffW, diffB);
+
+        log.info(`\n=== ${name.toUpperCase()} ColorJS Parity ===`);
+        log.info(`Input sRGB:  { r: ${srgb[0]}, g: ${srgb[1]}, b: ${srgb[2]} }`);
+        log.info(
+          `TokenScript: { h: ${tsH.toFixed(3)}, w: ${tsW.toFixed(6)}, b: ${tsB.toFixed(6)} }`,
+        );
+        log.info(
+          `ColorJS:     { h: ${colorJS.coords[0].toFixed(3)}, w: ${cjW.toFixed(6)}, b: ${cjB.toFixed(6)} } (normalized)`,
+        );
+        log.info(`Max Diff (W,B): ${maxDiff.toExponential(2)}`);
+        log.info(`Status:         ${maxDiff < TOLERANCE ? "✅ PASS" : "❌ FAIL"}`);
+
+        expect(maxDiff).toBeLessThan(TOLERANCE);
+        expect(diffH).toBeLessThan(HUE_TOLERANCE);
+      });
+    }
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle white (W=1, B=0)", async () => {
+      const result = await executeWithSchema(
+        "hwb-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 1;
+        srgb.b = 1;
+        
+        variable hsv: Color.HSV = srgb.to.hsv();
+        hsv.to.hwb()
+      `,
+      );
+
+      expect((result as any).value.w.value).toBeCloseTo(1, 9);
+      expect((result as any).value.b.value).toBeCloseTo(0, 9);
+    });
+
+    it("should handle black (W=0, B=1)", async () => {
+      const result = await executeWithSchema(
+        "hwb-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable hsv: Color.HSV = srgb.to.hsv();
+        hsv.to.hwb()
+      `,
+      );
+
+      expect((result as any).value.w.value).toBeCloseTo(0, 9);
+      expect((result as any).value.b.value).toBeCloseTo(1, 9);
+    });
+
+    it("should handle gray (W+B near 1)", async () => {
+      const result = await executeWithSchema(
+        "hwb-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0.5;
+        srgb.g = 0.5;
+        srgb.b = 0.5;
+        
+        variable hsv: Color.HSV = srgb.to.hsv();
+        hsv.to.hwb()
+      `,
+      );
+
+      // For gray, W + B = 1
+      expect((result as any).value.w.value).toBeCloseTo(0.5, 9);
+      expect((result as any).value.b.value).toBeCloseTo(0.5, 9);
+    });
+  });
+});

package/src/schemas/types/lab-color/from-xyz-d50.tokenscript

@@ -0,0 +1,78 @@
+// XYZ-D50 to CIE Lab Conversion
+// Reference: CIE 15.3:2004 section 8.2.1.1
+// Reference: https://github.com/color-js/color.js/blob/main/src/spaces/lab.js
+//
+// Algorithm:
+// 1. Scale XYZ by D50 white point reference
+// 2. Apply f function: f(x) = x > ε ? cbrt(x) : (κ*x + 16)/116
+// 3. L = 116 * f[Y] - 16
+// 4. a = 500 * (f[X] - f[Y])
+// 5. b = 200 * (f[Y] - f[Z])
+//
+// Input: Color.XYZD50 with x, y, z tristimulus
+// Output: Color.Lab with l, a, b coordinates
+
+// Get input XYZ-D50 values
+variable x: Number = {input}.x;
+variable y: Number = {input}.y;
+variable z: Number = {input}.z;
+
+// CIE constants (exact rational fractions)
+// ε = 216/24389 = (6/29)^3
+variable epsilon: Number = 0.008856451679035631;
+// κ = 24389/27 = (29/3)^3  
+variable kappa: Number = 903.2962962962963;
+
+// D50 white point reference (ColorJS exact values)
+// D50: [0.3457/0.3585, 1.0, (1-0.3457-0.3585)/0.3585]
+variable white_x: Number = 0.9642956764295677;
+variable white_y: Number = 1.0;
+variable white_z: Number = 0.8251046025104602;
+
+// Scale XYZ by white point
+variable xr: Number = x / white_x;
+variable yr: Number = y / white_y;
+variable zr: Number = z / white_z;
+
+// Apply f function with cube root
+// f(t) = t > ε ? t^(1/3) : (κt + 16) / 116
+variable cube_root_exp: Number = 0.3333333333333333;
+
+variable fx: Number = 0;
+variable fy: Number = 0;
+variable fz: Number = 0;
+
+if (xr > epsilon) [
+    fx = pow(xr, cube_root_exp);
+] else [
+    fx = (kappa * xr + 16) / 116;
+];
+
+if (yr > epsilon) [
+    fy = pow(yr, cube_root_exp);
+] else [
+    fy = (kappa * yr + 16) / 116;
+];
+
+if (zr > epsilon) [
+    fz = pow(zr, cube_root_exp);
+] else [
+    fz = (kappa * zr + 16) / 116;
+];
+
+// Calculate Lab values
+variable lab_l: Number = 116 * fy - 16;
+variable lab_a: Number = 500 * (fx - fy);
+variable lab_b: Number = 200 * (fy - fz);
+
+// Create output
+variable output: Color.Lab;
+output.l = lab_l;
+output.a = lab_a;
+output.b = lab_b;
+
+return output;
+
+
+
+

package/src/schemas/types/lab-color/initializer.tokenscript

@@ -0,0 +1,16 @@
+// CIE Lab Color Initializer
+// Creates a Lab color from L, a, b values
+// Input: List of [l, a, b] values
+
+variable lab_values: List = {input};
+variable output: Color.Lab;
+
+output.l = lab_values.get(0);
+output.a = lab_values.get(1);
+output.b = lab_values.get(2);
+
+return output;
+
+
+
+

package/src/schemas/types/lab-color/schema.json

@@ -0,0 +1,48 @@
+{
+  "name": "Lab",
+  "type": "color",
+  "description": "CIE Lab (L*a*b*) perceptually uniform color space. L is lightness (0-100), a is green-red axis, b is blue-yellow axis.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "l": {
+        "type": "number",
+        "description": "Lightness (0-100)"
+      },
+      "a": {
+        "type": "number",
+        "description": "Green-red axis (typically -125 to 125)"
+      },
+      "b": {
+        "type": "number",
+        "description": "Blue-yellow axis (typically -125 to 125)"
+      }
+    },
+    "required": ["l", "a", "b"],
+    "order": ["l", "a", "b"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "Lab Color Initializer",
+      "keyword": "lab",
+      "description": "Creates a CIE Lab color from L, a, b values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/xyz-d50-color/0/",
+      "target": "$self",
+      "description": "Converts XYZ-D50 to CIE Lab using the CIE standard formula",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-xyz-d50.tokenscript"
+      }
+    }
+  ]
+}

package/src/schemas/types/lab-color/unit.test.ts

@@ -0,0 +1,263 @@
+/**
+ * CIE Lab Color Schema Tests
+ *
+ * Tests for the CIE Lab perceptually uniform color space
+ * Validates against ColorJS for parity
+ */
+
+import { log } from "@tests/helpers/logger";
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+import type { ColorSpecification } from "@/bundler/types";
+
+// ColorJS reference tolerance
+const TOLERANCE = 1e-7;
+
+describe("CIE Lab Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("lab-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("Lab");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("l");
+      expect(schema.schema?.properties).toHaveProperty("a");
+      expect(schema.schema?.properties).toHaveProperty("b");
+      expect(schema.schema?.required).toEqual(["l", "a", "b"]);
+    });
+
+    it("should have lab initializer", async () => {
+      const schema = (await getBundledSchema("lab-color")) as ColorSpecification;
+
+      expect(schema.initializers).toHaveLength(1);
+      expect(schema.initializers[0].keyword).toBe("lab");
+    });
+
+    it("should have conversion from XYZ-D50", async () => {
+      const schema = (await getBundledSchema("lab-color")) as ColorSpecification;
+
+      expect(schema.conversions).toHaveLength(1);
+
+      const xyzToLab = schema.conversions.find((c: { source: string }) =>
+        c.source.includes("xyz-d50-color"),
+      );
+      expect(xyzToLab).toBeDefined();
+      expect(xyzToLab?.lossless).toBe(true);
+    });
+  });
+
+  describe("Initialization", () => {
+    it("should create Lab color from values", async () => {
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable c: Color.Lab;
+        c.l = 50;
+        c.a = 25;
+        c.b = -10;
+        c
+      `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      expect((result as any).subType).toBe("Lab");
+      expect((result as any).value.l.value).toBeCloseTo(50, 10);
+      expect((result as any).value.a.value).toBeCloseTo(25, 10);
+      expect((result as any).value.b.value).toBeCloseTo(-10, 10);
+    });
+  });
+
+  describe("Conversion from XYZ-D50 to Lab", () => {
+    it("should convert D50 white to Lab (L=100)", async () => {
+      // D50 white point
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable xyz: Color.XYZD50;
+        xyz.x = 0.96429567;
+        xyz.y = 1.0;
+        xyz.z = 0.82510460;
+        xyz.to.lab()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("xyz-d50", [0.96429567, 1.0, 0.8251046]).to("lab");
+
+      log.info(`\n=== D50 WHITE → Lab ===`);
+      log.info(
+        `TokenScript: { l: ${(result as any).value.l.value}, a: ${(result as any).value.a.value}, b: ${(result as any).value.b.value} }`,
+      );
+      log.info(
+        `ColorJS:     { l: ${colorJS.coords[0]}, a: ${colorJS.coords[1]}, b: ${colorJS.coords[2]} }`,
+      );
+
+      // White should have L≈100 and a≈b≈0
+      expect((result as any).value.l.value).toBeCloseTo(colorJS.coords[0], 5);
+      expect((result as any).value.a.value).toBeCloseTo(colorJS.coords[1], 5);
+      expect((result as any).value.b.value).toBeCloseTo(colorJS.coords[2], 5);
+    });
+  });
+
+  describe("Full Conversion Chain: sRGB → ... → XYZ-D50 → Lab", () => {
+    it("should convert sRGB red through to Lab", async () => {
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz65: Color.XYZD65 = linear.to.xyzd65();
+        variable xyz50: Color.XYZD50 = xyz65.to.xyzd50();
+        xyz50.to.lab()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("srgb", [1, 0, 0]).to("lab");
+
+      log.info(`\n=== sRGB RED → Lab (full chain) ===`);
+      log.info(
+        `TokenScript: { l: ${(result as any).value.l.value}, a: ${(result as any).value.a.value}, b: ${(result as any).value.b.value} }`,
+      );
+      log.info(
+        `ColorJS:     { l: ${colorJS.coords[0]}, a: ${colorJS.coords[1]}, b: ${colorJS.coords[2]} }`,
+      );
+
+      expect((result as any).value.l.value).toBeCloseTo(colorJS.coords[0], 5);
+      expect((result as any).value.a.value).toBeCloseTo(colorJS.coords[1], 5);
+      expect((result as any).value.b.value).toBeCloseTo(colorJS.coords[2], 5);
+    });
+  });
+
+  describe("ColorJS Parity", () => {
+    const testCases = [
+      { name: "red", srgb: [1, 0, 0] },
+      { name: "green", srgb: [0, 1, 0] },
+      { name: "blue", srgb: [0, 0, 1] },
+      { name: "white", srgb: [1, 1, 1] },
+      { name: "black", srgb: [0, 0, 0] },
+      { name: "gray-50%", srgb: [0.5, 0.5, 0.5] },
+      { name: "cyan", srgb: [0, 1, 1] },
+      { name: "magenta", srgb: [1, 0, 1] },
+      { name: "yellow", srgb: [1, 1, 0] },
+    ];
+
+    for (const { name, srgb } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "lab-color",
+          "type",
+          `
+          variable srgb: Color.SRGB;
+          srgb.r = ${srgb[0]};
+          srgb.g = ${srgb[1]};
+          srgb.b = ${srgb[2]};
+          
+          variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+          variable xyz65: Color.XYZD65 = linear.to.xyzd65();
+          variable xyz50: Color.XYZD50 = xyz65.to.xyzd50();
+          xyz50.to.lab()
+        `,
+        );
+
+        // ColorJS reference
+        const colorJS = new Color("srgb", srgb as [number, number, number]).to("lab");
+
+        const tsL = (result as any).value.l.value;
+        const tsA = (result as any).value.a.value;
+        const tsB = (result as any).value.b.value;
+
+        const diffL = Math.abs(tsL - colorJS.coords[0]);
+        const diffA = Math.abs(tsA - colorJS.coords[1]);
+        const diffB = Math.abs(tsB - colorJS.coords[2]);
+        const maxDiff = Math.max(diffL, diffA, diffB);
+
+        log.info(`\n=== ${name.toUpperCase()} ColorJS Parity ===`);
+        log.info(`Input sRGB:  { r: ${srgb[0]}, g: ${srgb[1]}, b: ${srgb[2]} }`);
+        log.info(
+          `TokenScript: { l: ${tsL.toFixed(4)}, a: ${tsA.toFixed(4)}, b: ${tsB.toFixed(4)} }`,
+        );
+        log.info(
+          `ColorJS:     { l: ${colorJS.coords[0].toFixed(4)}, a: ${colorJS.coords[1].toFixed(4)}, b: ${colorJS.coords[2].toFixed(4)} }`,
+        );
+        log.info(`Max Diff:    ${maxDiff.toExponential(2)}`);
+        log.info(`Status:      ${maxDiff < TOLERANCE ? "✅ PASS" : "❌ FAIL"}`);
+
+        expect(maxDiff).toBeLessThan(TOLERANCE);
+      });
+    }
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle black (L=0)", async () => {
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz65: Color.XYZD65 = linear.to.xyzd65();
+        variable xyz50: Color.XYZD50 = xyz65.to.xyzd50();
+        xyz50.to.lab()
+      `,
+      );
+
+      expect((result as any).value.l.value).toBeCloseTo(0, 5);
+    });
+
+    it("should handle white (L=100)", async () => {
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 1;
+        srgb.b = 1;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz65: Color.XYZD65 = linear.to.xyzd65();
+        variable xyz50: Color.XYZD50 = xyz65.to.xyzd50();
+        xyz50.to.lab()
+      `,
+      );
+
+      expect((result as any).value.l.value).toBeCloseTo(100, 4);
+    });
+
+    it("should handle neutral gray (a≈0, b≈0)", async () => {
+      const result = await executeWithSchema(
+        "lab-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0.5;
+        srgb.g = 0.5;
+        srgb.b = 0.5;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz65: Color.XYZD65 = linear.to.xyzd65();
+        variable xyz50: Color.XYZD50 = xyz65.to.xyzd50();
+        xyz50.to.lab()
+      `,
+      );
+
+      // Gray should have a≈0 and b≈0
+      expect(Math.abs((result as any).value.a.value)).toBeLessThan(0.01);
+      expect(Math.abs((result as any).value.b.value)).toBeLessThan(0.01);
+    });
+  });
+});

package/src/schemas/types/lch-color/from-lab.tokenscript

@@ -0,0 +1,44 @@
+// CIE Lab to LCH Conversion
+// Converts Cartesian (a, b) to polar (C, H) coordinates
+// Same algorithm as OKLab → OKLCH, but for CIE Lab
+//
+// Algorithm:
+// L stays the same (lightness 0-100)
+// C = sqrt(a² + b²) (chroma)
+// H = atan2(b, a) * 180/π (hue angle in degrees)
+//
+// Input: Color.Lab with l, a, b coordinates
+// Output: Color.LCH with l, c, h coordinates
+
+// Get input Lab values
+variable l: Number = {input}.l;
+variable a: Number = {input}.a;
+variable b: Number = {input}.b;
+
+// Constants
+variable pi: Number = pi();
+variable rad_to_deg: Number = 180 / pi;
+
+// Calculate chroma (distance from neutral axis)
+variable c: Number = sqrt(a * a + b * b);
+
+// Calculate hue angle using atan2
+variable h_rad: Number = atan2(b, a);
+variable h: Number = h_rad * rad_to_deg;
+
+// Normalize hue to 0-360 range
+if (h < 0) [
+    h = h + 360;
+];
+
+// Create output
+variable output: Color.LCH;
+output.l = l;
+output.c = c;
+output.h = h;
+
+return output;
+
+
+
+

package/src/schemas/types/lch-color/initializer.tokenscript

@@ -0,0 +1,16 @@
+// CIE LCH Color Initializer
+// Creates a LCH color from L, C, H values
+// Input: List of [l, c, h] values
+
+variable lch_values: List = {input};
+variable output: Color.LCH;
+
+output.l = lch_values.get(0);
+output.c = lch_values.get(1);
+output.h = lch_values.get(2);
+
+return output;
+
+
+
+

package/src/schemas/types/lch-color/schema.json

@@ -0,0 +1,48 @@
+{
+  "name": "LCH",
+  "type": "color",
+  "description": "CIE LCH color space - the polar form of CIE Lab. L is lightness (0-100), C is chroma, H is hue angle (0-360).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "l": {
+        "type": "number",
+        "description": "Lightness (0-100)"
+      },
+      "c": {
+        "type": "number",
+        "description": "Chroma"
+      },
+      "h": {
+        "type": "number",
+        "description": "Hue angle (0-360 degrees)"
+      }
+    },
+    "required": ["l", "c", "h"],
+    "order": ["l", "c", "h"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "LCH Color Initializer",
+      "keyword": "lch",
+      "description": "Creates a CIE LCH color from L, C, H values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/lab-color/0/",
+      "target": "$self",
+      "description": "Converts CIE Lab to LCH using Cartesian to polar transformation",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-lab.tokenscript"
+      }
+    }
+  ]
+}