@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,201 @@
+/**
+ * HSL Color Schema Tests
+ *
+ * Tests for the HSL color space (Hue, Saturation, Lightness)
+ * 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("HSL Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("hsl-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("HSL");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("h");
+      expect(schema.schema?.properties).toHaveProperty("s");
+      expect(schema.schema?.properties).toHaveProperty("l");
+      expect(schema.schema?.required).toEqual(["h", "s", "l"]);
+    });
+
+    it("should have hsl initializer", async () => {
+      const schema = (await getBundledSchema("hsl-color")) as ColorSpecification;
+
+      expect(schema.initializers).toHaveLength(1);
+      expect(schema.initializers[0].keyword).toBe("hsl");
+    });
+
+    it("should have conversion from sRGB", async () => {
+      const schema = (await getBundledSchema("hsl-color")) as ColorSpecification;
+
+      expect(schema.conversions).toHaveLength(1);
+
+      const srgbToHsl = schema.conversions.find((c: { source: string }) =>
+        c.source.includes("srgb-color"),
+      );
+      expect(srgbToHsl).toBeDefined();
+    });
+  });
+
+  describe("Conversion from sRGB to HSL", () => {
+    it("should convert sRGB red to HSL", async () => {
+      const result = await executeWithSchema(
+        "hsl-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 0;
+        srgb.b = 0;
+        srgb.to.hsl()
+      `,
+      );
+
+      // ColorJS reference (uses 0-100 for S and L, we use 0-1)
+      const colorJS = new Color("srgb", [1, 0, 0]).to("hsl");
+      const cjS = colorJS.coords[1] / 100;
+      const cjL = colorJS.coords[2] / 100;
+
+      log.info(`\n=== sRGB RED → HSL ===`);
+      log.info(
+        `TokenScript: { h: ${(result as any).value.h.value}, s: ${(result as any).value.s.value}, l: ${(result as any).value.l.value} }`,
+      );
+      log.info(`ColorJS:     { h: ${colorJS.coords[0]}, s: ${cjS}, l: ${cjL} } (normalized)`);
+
+      expect((result as any).value.h.value).toBeCloseTo(colorJS.coords[0], 6);
+      expect((result as any).value.s.value).toBeCloseTo(cjS, 9);
+      expect((result as any).value.l.value).toBeCloseTo(cjL, 9);
+    });
+  });
+
+  describe("ColorJS Parity", () => {
+    const testCases = [
+      { name: "red", srgb: [1, 0, 0], expectedH: 0 },
+      { name: "green", srgb: [0, 1, 0], expectedH: 120 },
+      { name: "blue", srgb: [0, 0, 1], expectedH: 240 },
+      { name: "cyan", srgb: [0, 1, 1], expectedH: 180 },
+      { name: "magenta", srgb: [1, 0, 1], expectedH: 300 },
+      { name: "yellow", srgb: [1, 1, 0], expectedH: 60 },
+      { name: "coral", srgb: [1, 0.5, 0.314], expectedH: null },
+    ];
+
+    for (const { name, srgb, expectedH } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "hsl-color",
+          "type",
+          `
+          variable srgb: Color.SRGB;
+          srgb.r = ${srgb[0]};
+          srgb.g = ${srgb[1]};
+          srgb.b = ${srgb[2]};
+          srgb.to.hsl()
+        `,
+        );
+
+        // ColorJS reference (uses 0-100 for S and L, we use 0-1)
+        const colorJS = new Color("srgb", srgb as [number, number, number]).to("hsl");
+
+        const tsH = (result as any).value.h.value;
+        const tsS = (result as any).value.s.value;
+        const tsL = (result as any).value.l.value;
+
+        // ColorJS uses 0-100 scale for S and L, convert to 0-1 for comparison
+        const cjS = colorJS.coords[1] / 100;
+        const cjL = colorJS.coords[2] / 100;
+
+        let diffH = Math.abs(tsH - colorJS.coords[0]);
+        if (diffH > 180) diffH = 360 - diffH;
+        const diffS = Math.abs(tsS - cjS);
+        const diffL = Math.abs(tsL - cjL);
+        const maxDiff = Math.max(diffS, diffL);
+
+        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)}, s: ${tsS.toFixed(6)}, l: ${tsL.toFixed(6)} }`,
+        );
+        log.info(
+          `ColorJS:     { h: ${colorJS.coords[0].toFixed(3)}, s: ${cjS.toFixed(6)}, l: ${cjL.toFixed(6)} } (normalized from 0-100)`,
+        );
+        log.info(`Max Diff (S,L): ${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);
+
+        // For primary colors, also check expected hue
+        if (expectedH !== null) {
+          expect(tsH).toBeCloseTo(expectedH, 5);
+        }
+      });
+    }
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle white (S=0)", async () => {
+      const result = await executeWithSchema(
+        "hsl-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 1;
+        srgb.b = 1;
+        srgb.to.hsl()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.l.value).toBeCloseTo(1, 9);
+    });
+
+    it("should handle black (S=0, L=0)", async () => {
+      const result = await executeWithSchema(
+        "hsl-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0;
+        srgb.g = 0;
+        srgb.b = 0;
+        srgb.to.hsl()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.l.value).toBeCloseTo(0, 9);
+    });
+
+    it("should handle gray (S=0)", async () => {
+      const result = await executeWithSchema(
+        "hsl-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0.5;
+        srgb.g = 0.5;
+        srgb.b = 0.5;
+        srgb.to.hsl()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.l.value).toBeCloseTo(0.5, 9);
+    });
+  });
+});

package/src/schemas/types/hsv-color/from-srgb.tokenscript

@@ -0,0 +1,80 @@
+// sRGB to HSV Conversion
+// Reference: Standard RGB to HSV algorithm
+//
+// Algorithm:
+// V = max(R, G, B)
+// S = (V - min(R, G, B)) / V  (if V > 0)
+// H depends on which channel is max
+//
+// Input: Color.SRGB with r, g, b in 0-1 range
+// Output: Color.HSV with h (0-360), s (0-1), v (0-1)
+
+// Get input sRGB values
+variable r: Number = {input}.r;
+variable g: Number = {input}.g;
+variable b: Number = {input}.b;
+
+// Find max and min
+variable max_val: Number = r;
+if (g > max_val) [
+    max_val = g;
+];
+if (b > max_val) [
+    max_val = b;
+];
+
+variable min_val: Number = r;
+if (g < min_val) [
+    min_val = g;
+];
+if (b < min_val) [
+    min_val = b;
+];
+
+// Value is the max channel
+variable v: Number = max_val;
+
+// Calculate saturation and hue
+variable s: Number = 0;
+variable h: Number = 0;
+variable delta: Number = max_val - min_val;
+
+if (max_val > 0) [
+    s = delta / max_val;
+];
+
+if (delta > 0) [
+    // Hue calculation depends on which channel is max
+    if (max_val == r) [
+        h = ((g - b) / delta);
+        if (g < b) [
+            h = h + 6;
+        ];
+    ] else [
+        if (max_val == g) [
+            h = (b - r) / delta + 2;
+        ] else [
+            h = (r - g) / delta + 4;
+        ];
+    ];
+    
+    // Convert to degrees
+    h = h * 60;
+];
+
+// Normalize hue to 0-360
+if (h < 0) [
+    h = h + 360;
+];
+
+// Create output
+variable output: Color.HSV;
+output.h = h;
+output.s = s;
+output.v = v;
+
+return output;
+
+
+
+

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

@@ -0,0 +1,16 @@
+// HSV Color Initializer
+// Creates an HSV color from H, S, V values
+// Input: List of [h, s, v] values
+
+variable hsv_values: List = {input};
+variable output: Color.HSV;
+
+output.h = hsv_values.get(0);
+output.s = hsv_values.get(1);
+output.v = hsv_values.get(2);
+
+return output;
+
+
+
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "HSV",
+  "type": "color",
+  "description": "HSV color space - Hue, Saturation, Value. Also known as HSB (Hue, Saturation, Brightness).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "h": {
+        "type": "number",
+        "description": "Hue angle (0-360 degrees)"
+      },
+      "s": {
+        "type": "number",
+        "description": "Saturation (0-1)"
+      },
+      "v": {
+        "type": "number",
+        "description": "Value/Brightness (0-1)"
+      }
+    },
+    "required": ["h", "s", "v"],
+    "order": ["h", "s", "v"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "HSV Color Initializer",
+      "keyword": "hsv",
+      "description": "Creates an HSV color from H, S, V values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/srgb-color/0/",
+      "target": "$self",
+      "description": "Converts sRGB to HSV",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-srgb.tokenscript"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,162 @@
+/**
+ * HSV Color Schema Tests
+ *
+ * Tests for the HSV color space (Hue, Saturation, Value)
+ * 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("HSV Color Schema", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("hsv-color")) as ColorSpecification;
+
+      expect(schema.name).toBe("HSV");
+      expect(schema.type).toBe("color");
+      expect(schema.schema).toBeDefined();
+      expect(schema.schema?.properties).toHaveProperty("h");
+      expect(schema.schema?.properties).toHaveProperty("s");
+      expect(schema.schema?.properties).toHaveProperty("v");
+      expect(schema.schema?.required).toEqual(["h", "s", "v"]);
+    });
+
+    it("should have hsv initializer", async () => {
+      const schema = (await getBundledSchema("hsv-color")) as ColorSpecification;
+
+      expect(schema.initializers).toHaveLength(1);
+      expect(schema.initializers[0].keyword).toBe("hsv");
+    });
+
+    it("should have conversion from sRGB", async () => {
+      const schema = (await getBundledSchema("hsv-color")) as ColorSpecification;
+
+      expect(schema.conversions).toHaveLength(1);
+    });
+  });
+
+  describe("ColorJS Parity", () => {
+    const testCases = [
+      { name: "red", srgb: [1, 0, 0], expectedH: 0 },
+      { name: "green", srgb: [0, 1, 0], expectedH: 120 },
+      { name: "blue", srgb: [0, 0, 1], expectedH: 240 },
+      { name: "cyan", srgb: [0, 1, 1], expectedH: 180 },
+      { name: "magenta", srgb: [1, 0, 1], expectedH: 300 },
+      { name: "yellow", srgb: [1, 1, 0], expectedH: 60 },
+      { name: "coral", srgb: [1, 0.5, 0.314], expectedH: null },
+    ];
+
+    for (const { name, srgb, expectedH } of testCases) {
+      it(`should match ColorJS for ${name}`, async () => {
+        const result = await executeWithSchema(
+          "hsv-color",
+          "type",
+          `
+          variable srgb: Color.SRGB;
+          srgb.r = ${srgb[0]};
+          srgb.g = ${srgb[1]};
+          srgb.b = ${srgb[2]};
+          srgb.to.hsv()
+        `,
+        );
+
+        // ColorJS reference (uses 0-100 for S and V, we use 0-1)
+        const colorJS = new Color("srgb", srgb as [number, number, number]).to("hsv");
+        const cjS = colorJS.coords[1] / 100;
+        const cjV = colorJS.coords[2] / 100;
+
+        const tsH = (result as any).value.h.value;
+        const tsS = (result as any).value.s.value;
+        const tsV = (result as any).value.v.value;
+
+        let diffH = Math.abs(tsH - colorJS.coords[0]);
+        if (diffH > 180) diffH = 360 - diffH;
+        const diffS = Math.abs(tsS - cjS);
+        const diffV = Math.abs(tsV - cjV);
+        const maxDiff = Math.max(diffS, diffV);
+
+        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)}, s: ${tsS.toFixed(6)}, v: ${tsV.toFixed(6)} }`,
+        );
+        log.info(
+          `ColorJS:     { h: ${colorJS.coords[0].toFixed(3)}, s: ${cjS.toFixed(6)}, v: ${cjV.toFixed(6)} } (normalized)`,
+        );
+        log.info(`Max Diff (S,V): ${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);
+
+        if (expectedH !== null) {
+          expect(tsH).toBeCloseTo(expectedH, 5);
+        }
+      });
+    }
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle white (S=0, V=1)", async () => {
+      const result = await executeWithSchema(
+        "hsv-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 1;
+        srgb.g = 1;
+        srgb.b = 1;
+        srgb.to.hsv()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.v.value).toBeCloseTo(1, 9);
+    });
+
+    it("should handle black (S=0, V=0)", async () => {
+      const result = await executeWithSchema(
+        "hsv-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0;
+        srgb.g = 0;
+        srgb.b = 0;
+        srgb.to.hsv()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.v.value).toBeCloseTo(0, 9);
+    });
+
+    it("should handle gray (S=0)", async () => {
+      const result = await executeWithSchema(
+        "hsv-color",
+        "type",
+        `
+        variable srgb: Color.SRGB;
+        srgb.r = 0.5;
+        srgb.g = 0.5;
+        srgb.b = 0.5;
+        srgb.to.hsv()
+      `,
+      );
+
+      expect((result as any).value.s.value).toBeCloseTo(0, 9);
+      expect((result as any).value.v.value).toBeCloseTo(0.5, 9);
+    });
+  });
+});

package/src/schemas/types/hwb-color/from-hsv.tokenscript

@@ -0,0 +1,31 @@
+// HSV to HWB Conversion
+// Reference: CSS Color Level 4
+//
+// Algorithm:
+// H stays the same
+// W = (1 - S) * V  (Whiteness)
+// B = 1 - V        (Blackness)
+//
+// Input: Color.HSV with h, s, v values
+// Output: Color.HWB with h, w, b values
+
+// Get input HSV values
+variable h: Number = {input}.h;
+variable s: Number = {input}.s;
+variable v: Number = {input}.v;
+
+// Calculate whiteness and blackness
+variable w: Number = (1 - s) * v;
+variable b: Number = 1 - v;
+
+// Create output
+variable output: Color.HWB;
+output.h = h;
+output.w = w;
+output.b = b;
+
+return output;
+
+
+
+

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

@@ -0,0 +1,16 @@
+// HWB Color Initializer
+// Creates an HWB color from H, W, B values
+// Input: List of [h, w, b] values
+
+variable hwb_values: List = {input};
+variable output: Color.HWB;
+
+output.h = hwb_values.get(0);
+output.w = hwb_values.get(1);
+output.b = hwb_values.get(2);
+
+return output;
+
+
+
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "HWB",
+  "type": "color",
+  "description": "HWB color space - Hue, Whiteness, Blackness. CSS Color Level 4.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "h": {
+        "type": "number",
+        "description": "Hue angle (0-360 degrees)"
+      },
+      "w": {
+        "type": "number",
+        "description": "Whiteness (0-1)"
+      },
+      "b": {
+        "type": "number",
+        "description": "Blackness (0-1)"
+      }
+    },
+    "required": ["h", "w", "b"],
+    "order": ["h", "w", "b"],
+    "additionalProperties": false
+  },
+  "initializers": [
+    {
+      "title": "HWB Color Initializer",
+      "keyword": "hwb",
+      "description": "Creates an HWB color from H, W, B values",
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./initializer.tokenscript"
+      }
+    }
+  ],
+  "conversions": [
+    {
+      "source": "/api/v1/core/hsv-color/0/",
+      "target": "$self",
+      "description": "Converts HSV to HWB",
+      "lossless": true,
+      "script": {
+        "type": "/api/v1/core/tokenscript/0/",
+        "script": "./from-hsv.tokenscript"
+      }
+    }
+  ]
+}