@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,267 @@
+/**
+ * OKLCH Color Schema Tests
+ *
+ * Tests for the OKLCH color space (polar form of OKLab)
+ * 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
+// Hue angles can have larger differences near 0/360
+const TOLERANCE = 1e-6;
+const HUE_TOLERANCE = 1e-3;
+
+describe("OKLCH Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("oklch-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("OKLCH");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("l");
+      expect(schema.schema?.properties).toHaveProperty("c");
+      expect(schema.schema?.properties).toHaveProperty("h");
+      expect(schema.schema?.required).toEqual(["l", "c", "h"]);
+    });
+
+    it("should have oklch initializer", async () => {
+      const schema = (await getBundledSchema("oklch-color")) as ColorSpecification;
+
+      expect(schema.initializers).toHaveLength(1);
+      expect(schema.initializers[0].keyword).toBe("oklch");
+      expect(schema.initializers[0].script.script).toContain("Color.OKLCH");
+    });
+
+    it("should have conversion from OKLab", async () => {
+      const schema = (await getBundledSchema("oklch-color")) as ColorSpecification;
+
+      expect(schema.conversions).toHaveLength(1);
+
+      const oklabToOklch = schema.conversions.find((c: { source: string }) =>
+        c.source.includes("oklab-color"),
+      );
+      expect(oklabToOklch).toBeDefined();
+      expect(oklabToOklch?.lossless).toBe(true);
+    });
+  });
+
+  describe("Initialization", () => {
+    it("should create OKLCH color from values", async () => {
+      const result = await executeWithSchema(
+        "oklch-color",
+        "type",
+        `
+        variable c: Color.OKLCH;
+        c.l = 0.7;
+        c.c = 0.15;
+        c.h = 30;
+        c
+      `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      expect((result as any).subType).toBe("OKLCH");
+      expect((result as any).value.l.value).toBeCloseTo(0.7, 10);
+      expect((result as any).value.c.value).toBeCloseTo(0.15, 10);
+      expect((result as any).value.h.value).toBeCloseTo(30, 10);
+    });
+  });
+
+  describe("Conversion from OKLab to OKLCH", () => {
+    it("should convert OKLab to OKLCH correctly", async () => {
+      const result = await executeWithSchema(
+        "oklch-color",
+        "type",
+        `
+        variable lab: Color.OKLab;
+        lab.l = 0.7;
+        lab.a = 0.1;
+        lab.b = 0.05;
+        lab.to.oklch()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("oklab", [0.7, 0.1, 0.05]).to("oklch");
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      expect((result as any).subType).toBe("OKLCH");
+      expect((result as any).value.l.value).toBeCloseTo(colorJS.coords[0], 9);
+      expect((result as any).value.c.value).toBeCloseTo(colorJS.coords[1], 9);
+      expect((result as any).value.h.value).toBeCloseTo(colorJS.coords[2], 3);
+    });
+  });
+
+  describe("Full Conversion Chain: sRGB → ... → OKLab → OKLCH", () => {
+    it("should convert sRGB red through to OKLCH", async () => {
+      const result = await executeWithSchema(
+        "oklch-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz: Color.XYZD65 = linear.to.xyzd65();
+        variable lab: Color.OKLab = xyz.to.oklab();
+        lab.to.oklch()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("srgb", [1, 0, 0]).to("oklch");
+
+      log.info(`\n=== sRGB RED → OKLCH (full chain) ===`);
+      log.info(
+        `TokenScript: { l: ${(result as any).value.l.value}, c: ${(result as any).value.c.value}, h: ${(result as any).value.h.value} }`,
+      );
+      log.info(
+        `ColorJS:     { l: ${colorJS.coords[0]}, c: ${colorJS.coords[1]}, h: ${colorJS.coords[2]} }`,
+      );
+
+      expect((result as any).value.l.value).toBeCloseTo(colorJS.coords[0], 6);
+      expect((result as any).value.c.value).toBeCloseTo(colorJS.coords[1], 6);
+      expect((result as any).value.h.value).toBeCloseTo(colorJS.coords[2], 1); // Hue needs more tolerance
+    });
+  });
+
+  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.341, 0.2] },
+    ];
+
+    for (const { name, srgb } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "oklch-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 xyz: Color.XYZD65 = linear.to.xyzd65();
+          variable lab: Color.OKLab = xyz.to.oklab();
+          lab.to.oklch()
+        `,
+        );
+
+        // ColorJS reference
+        const colorJS = new Color("srgb", srgb as [number, number, number]).to("oklch");
+
+        const tsL = (result as any).value.l.value;
+        const tsC = (result as any).value.c.value;
+        const tsH = (result as any).value.h.value;
+
+        const diffL = Math.abs(tsL - colorJS.coords[0]);
+        const diffC = Math.abs(tsC - colorJS.coords[1]);
+        // For hue, handle the 0/360 wraparound
+        let diffH = Math.abs(tsH - colorJS.coords[2]);
+        if (diffH > 180) diffH = 360 - diffH;
+
+        const maxDiff = Math.max(diffL, diffC);
+
+        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(6)}, c: ${tsC.toFixed(6)}, h: ${tsH.toFixed(3)} }`,
+        );
+        log.info(
+          `ColorJS:     { l: ${colorJS.coords[0].toFixed(6)}, c: ${colorJS.coords[1].toFixed(6)}, h: ${colorJS.coords[2].toFixed(3)} }`,
+        );
+        log.info(`Max Diff (L,C): ${maxDiff.toExponential(2)}`);
+        log.info(`Hue Diff:       ${diffH.toExponential(2)}`);
+        log.info(
+          `Status:         ${maxDiff < TOLERANCE && diffH < HUE_TOLERANCE ? "✅ PASS" : "❌ FAIL"}`,
+        );
+
+        expect(maxDiff).toBeLessThan(TOLERANCE);
+        expect(diffH).toBeLessThan(HUE_TOLERANCE);
+      });
+    }
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle neutral gray (chroma ≈ 0)", async () => {
+      const result = await executeWithSchema(
+        "oklch-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 xyz: Color.XYZD65 = linear.to.xyzd65();
+        variable lab: Color.OKLab = xyz.to.oklab();
+        lab.to.oklch()
+      `,
+      );
+
+      // Gray should have chroma ≈ 0
+      // Hue is undefined for neutral colors (NaN in ColorJS)
+      expect((result as any).value.c.value).toBeLessThan(1e-5);
+    });
+
+    it("should handle black (L=0, C=0)", async () => {
+      const result = await executeWithSchema(
+        "oklch-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0;
+        srgb.g = 0;
+        srgb.b = 0;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz: Color.XYZD65 = linear.to.xyzd65();
+        variable lab: Color.OKLab = xyz.to.oklab();
+        lab.to.oklch()
+      `,
+      );
+
+      expect((result as any).value.l.value).toBeCloseTo(0, 6);
+      expect((result as any).value.c.value).toBeCloseTo(0, 6);
+    });
+
+    it("should handle white (L=1, C=0)", async () => {
+      const result = await executeWithSchema(
+        "oklch-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 1;
+        srgb.b = 1;
+        
+        variable linear: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz: Color.XYZD65 = linear.to.xyzd65();
+        variable lab: Color.OKLab = xyz.to.oklab();
+        lab.to.oklch()
+      `,
+      );
+
+      const colorJS = new Color("srgb", [1, 1, 1]).to("oklch");
+
+      expect((result as any).value.l.value).toBeCloseTo(colorJS.coords[0], 6);
+      expect((result as any).value.c.value).toBeLessThan(1e-5);
+    });
+  });
+});

package/src/schemas/types/p3-color/from-p3-linear.tokenscript

@@ -0,0 +1,59 @@
+// Linear P3 to P3 Conversion
+// Applies sRGB transfer function (gamma encoding)
+// P3 uses the same transfer function as sRGB
+// Reference: CSS Color Level 4
+//
+// Algorithm (same as sRGB):
+//   if linear ≤ 0.0031308: encoded = 12.92 × linear
+//   else: encoded = 1.055 × linear^(1/2.4) - 0.055
+//
+// Input: Color.LinearP3 with linear r, g, b values
+// Output: Color.P3 with gamma-encoded r, g, b values
+
+// Transfer function constants (same as sRGB)
+variable threshold: Number = 0.0031308;
+variable linear_scale: Number = 12.92;
+variable gamma_scale: Number = 1.055;
+variable gamma_offset: Number = 0.055;
+variable gamma_exponent: Number = 0.4166666666666667;
+
+// Get linear values
+variable linear_r: Number = {input}.r;
+variable linear_g: Number = {input}.g;
+variable linear_b: Number = {input}.b;
+
+// Convert red channel
+variable encoded_r: Number = 0;
+if (linear_r <= threshold) [
+    encoded_r = linear_scale * linear_r;
+] else [
+    encoded_r = gamma_scale * pow(linear_r, gamma_exponent) - gamma_offset;
+];
+
+// Convert green channel
+variable encoded_g: Number = 0;
+if (linear_g <= threshold) [
+    encoded_g = linear_scale * linear_g;
+] else [
+    encoded_g = gamma_scale * pow(linear_g, gamma_exponent) - gamma_offset;
+];
+
+// Convert blue channel
+variable encoded_b: Number = 0;
+if (linear_b <= threshold) [
+    encoded_b = linear_scale * linear_b;
+] else [
+    encoded_b = gamma_scale * pow(linear_b, gamma_exponent) - gamma_offset;
+];
+
+// Create output
+variable output: Color.P3;
+output.r = encoded_r;
+output.g = encoded_g;
+output.b = encoded_b;
+
+return output;
+
+
+
+

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

@@ -0,0 +1,16 @@
+// Display-P3 Color Initializer
+// Creates a Display-P3 color from 0-1 values
+// Input: List of [r, g, b] values
+
+variable color_values: List = {input};
+variable output: Color.P3;
+
+output.r = color_values.get(0);
+output.g = color_values.get(1);
+output.b = color_values.get(2);
+
+return output;
+
+
+
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "P3",
+  "type": "color",
+  "description": "Display-P3 color space with sRGB transfer function. Wider gamut than sRGB, common on modern Apple displays.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "r": {
+        "type": "number",
+        "description": "Red channel (0-1, can exceed for out-of-gamut)"
+      },
+      "g": {
+        "type": "number",
+        "description": "Green channel (0-1, can exceed for out-of-gamut)"
+      },
+      "b": {
+        "type": "number",
+        "description": "Blue channel (0-1, can exceed for out-of-gamut)"
+      }
+    },
+    "required": ["r", "g", "b"],
+    "order": ["r", "g", "b"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "Display-P3 Color Initializer",
+      "keyword": "p3",
+      "description": "Creates a Display-P3 color from 0-1 values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/p3-linear-color/0/",
+      "target": "$self",
+      "description": "Converts Linear P3 to P3 by applying sRGB transfer function",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-p3-linear.tokenscript"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Display-P3 Color Schema Tests
+ */
+
+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";
+
+describe("Display-P3 Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("p3-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("P3");
+      expect(schema.type).toBe("color");
+      expect(schema.schema?.properties).toHaveProperty("r");
+      expect(schema.schema?.properties).toHaveProperty("g");
+      expect(schema.schema?.properties).toHaveProperty("b");
+    });
+  });
+
+  describe("Conversion from Linear P3", () => {
+    const testCases = [
+      { name: "black", linear: [0, 0, 0] },
+      { name: "white", linear: [1, 1, 1] },
+      { name: "mid-gray", linear: [0.214, 0.214, 0.214] },
+      { name: "P3 red", linear: [1, 0, 0] },
+      { name: "P3 green", linear: [0, 1, 0] },
+    ];
+
+    for (const { name, linear } of testCases) {
+      it(`should apply gamma encoding for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "p3-color",
+          "type",
+          `
+          variable linear: Color.LinearP3;
+          linear.r = ${linear[0]}; linear.g = ${linear[1]}; linear.b = ${linear[2]};
+          linear.to.p3()
+        `,
+        );
+
+        // ColorJS reference
+        const colorJS = new Color("p3-linear", linear as [number, number, number]).to("p3");
+
+        const tsR = (result as any).value.r.value;
+        const tsG = (result as any).value.g.value;
+        const tsB = (result as any).value.b.value;
+
+        expect(tsR).toBeCloseTo(colorJS.coords[0], 8);
+        expect(tsG).toBeCloseTo(colorJS.coords[1], 8);
+        expect(tsB).toBeCloseTo(colorJS.coords[2], 8);
+      });
+    }
+  });
+
+  describe("Full Conversion Chain: sRGB → P3", () => {
+    it("should convert sRGB red through to P3", async () => {
+      // sRGB red converted to P3 should have slightly lower values
+      // because P3 has a wider gamut
+      const result = await executeWithSchema(
+        "p3-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1; srgb.g = 0; srgb.b = 0;
+        variable linear_srgb: Color.LinearSRGB = srgb.to.linearsrgb();
+        variable xyz: Color.XYZD65 = linear_srgb.to.xyzd65();
+        variable linear_p3: Color.LinearP3 = xyz.to.linearp3();
+        linear_p3.to.p3()
+      `,
+      );
+
+      // ColorJS reference
+      const colorJS = new Color("srgb", [1, 0, 0]).to("p3");
+
+      const tsR = (result as any).value.r.value;
+      const tsG = (result as any).value.g.value;
+      const tsB = (result as any).value.b.value;
+
+      log.info(`\n=== sRGB Red → P3 ===`);
+      log.info(`TokenScript: { r: ${tsR.toFixed(6)}, g: ${tsG.toFixed(6)}, b: ${tsB.toFixed(6)} }`);
+      log.info(
+        `ColorJS:     { r: ${colorJS.coords[0].toFixed(6)}, g: ${colorJS.coords[1].toFixed(6)}, b: ${colorJS.coords[2].toFixed(6)} }`,
+      );
+
+      expect(tsR).toBeCloseTo(colorJS.coords[0], 8);
+      expect(tsG).toBeCloseTo(colorJS.coords[1], 8);
+      expect(tsB).toBeCloseTo(colorJS.coords[2], 8);
+    });
+
+    it("should demonstrate P3 has wider gamut than sRGB", async () => {
+      // When converting sRGB colors to P3, they will be "pulled in"
+      // because P3 has a larger gamut - sRGB red is less saturated in P3 space
+      const colorJS_srgbRed = new Color("srgb", [1, 0, 0]).to("p3");
+
+      // sRGB red (1, 0, 0) in P3 space should have r < 1
+      // because P3 red is more saturated
+      log.info(`\n=== sRGB Red expressed in P3 ===`);
+      log.info(
+        `P3: { r: ${colorJS_srgbRed.coords[0].toFixed(6)}, g: ${colorJS_srgbRed.coords[1].toFixed(6)}, b: ${colorJS_srgbRed.coords[2].toFixed(6)} }`,
+      );
+      log.info(`Note: R < 1 because P3 red primary is more saturated than sRGB red`);
+
+      // P3 green primary is way outside sRGB gamut
+      const colorJS_p3Green = new Color("p3", [0, 1, 0]).to("srgb");
+      log.info(`\n=== P3 Green expressed in sRGB (clipped) ===`);
+      log.info(
+        `sRGB: { r: ${colorJS_p3Green.coords[0].toFixed(6)}, g: ${colorJS_p3Green.coords[1].toFixed(6)}, b: ${colorJS_p3Green.coords[2].toFixed(6)} }`,
+      );
+      log.info(`Note: Negative R value indicates out-of-sRGB-gamut color`);
+
+      // P3 green in sRGB space has negative red
+      expect(colorJS_p3Green.coords[0]).toBeLessThan(0);
+    });
+  });
+});

package/src/schemas/types/p3-linear-color/from-xyz-d65.tokenscript

@@ -0,0 +1,47 @@
+// XYZ-D65 to Linear P3 Conversion
+// Converts CIE XYZ (D65) to linear Display-P3 RGB
+// Reference: CSS Color Level 4 specification
+//
+// Uses the inverse of the P3 to XYZ-D65 matrix
+// Matrix values from ColorJS / CSS Color Level 4
+//
+// Input: Color.XYZD65 with x, y, z tristimulus values
+// Output: Color.LinearP3 with linear r, g, b values (may be outside 0-1 for out-of-gamut)
+
+// Get XYZ values
+variable x: Number = {input}.x;
+variable y: Number = {input}.y;
+variable z: Number = {input}.z;
+
+// XYZ to Linear P3 matrix (inverse of P3 to XYZ)
+// Row 1
+variable m00: Number = 2.4934969119414254;
+variable m01: Number = -0.9313836179191239;
+variable m02: Number = -0.40271078445071684;
+
+// Row 2
+variable m10: Number = -0.8294889695615747;
+variable m11: Number = 1.7626640603183463;
+variable m12: Number = 0.023624685841943577;
+
+// Row 3
+variable m20: Number = 0.03584583024378447;
+variable m21: Number = -0.07617238926804182;
+variable m22: Number = 0.9568845240076872;
+
+// Matrix multiplication: [r, g, b] = M × [x, y, z]
+variable linear_r: Number = m00 * x + m01 * y + m02 * z;
+variable linear_g: Number = m10 * x + m11 * y + m12 * z;
+variable linear_b: Number = m20 * x + m21 * y + m22 * z;
+
+// Create output (note: values may be outside 0-1 for out-of-gamut colors)
+variable output: Color.LinearP3;
+output.r = linear_r;
+output.g = linear_g;
+output.b = linear_b;
+
+return output;
+
+
+
+

package/src/schemas/types/p3-linear-color/initializer.tokenscript

@@ -0,0 +1,16 @@
+// Linear P3 Color Initializer
+// Creates a linear Display-P3 color from linear 0-1 values
+// Input: List of [r, g, b] linear values
+
+variable color_values: List = {input};
+variable output: Color.LinearP3;
+
+output.r = color_values.get(0);
+output.g = color_values.get(1);
+output.b = color_values.get(2);
+
+return output;
+
+
+
+

package/src/schemas/types/p3-linear-color/schema.json

@@ -0,0 +1,48 @@
+{
+  "name": "LinearP3",
+  "type": "color",
+  "description": "Linear Display-P3 color space (gamma-decoded). Used for matrix transformations to XYZ.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "r": {
+        "type": "number",
+        "description": "Linear red channel (0-1, can exceed for HDR)"
+      },
+      "g": {
+        "type": "number",
+        "description": "Linear green channel (0-1, can exceed for HDR)"
+      },
+      "b": {
+        "type": "number",
+        "description": "Linear blue channel (0-1, can exceed for HDR)"
+      }
+    },
+    "required": ["r", "g", "b"],
+    "order": ["r", "g", "b"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "Linear P3 Color Initializer",
+      "keyword": "linearp3",
+      "description": "Creates a linear Display-P3 color from linear 0-1 values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/xyz-d65-color/0/",
+      "target": "$self",
+      "description": "Converts XYZ-D65 to Linear P3 using the P3 transformation matrix",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-xyz-d65.tokenscript"
+      }
+    }
+  ]
+}