@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,167 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Clamp to Gamut Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("clamp_to_gamut", "function");
+
+      expect(schema.name).toBe("Clamp to Gamut");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("clamp_to_gamut");
+    });
+  });
+
+  describe("In-Gamut Colors", () => {
+    it("should not modify colors already in gamut", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0.3; c.b = 0.7;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(0.5, 5);
+      expect(result.value.g.value).toBeCloseTo(0.3, 5);
+      expect(result.value.b.value).toBeCloseTo(0.7, 5);
+    });
+
+    it("should preserve black", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0; c.b = 0;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBe(0);
+      expect(result.value.g.value).toBe(0);
+      expect(result.value.b.value).toBe(0);
+    });
+
+    it("should preserve white", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 1; c.b = 1;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBe(1);
+      expect(result.value.g.value).toBe(1);
+      expect(result.value.b.value).toBe(1);
+    });
+  });
+
+  describe("Clamping Overflow Values", () => {
+    it("should clamp R > 1 to 1", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1.5; c.g = 0.5; c.b = 0.5;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBe(1);
+      expect(result.value.g.value).toBeCloseTo(0.5, 5);
+      expect(result.value.b.value).toBeCloseTo(0.5, 5);
+    });
+
+    it("should clamp G > 1 to 1", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 2.0; c.b = 0.5;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(0.5, 5);
+      expect(result.value.g.value).toBe(1);
+      expect(result.value.b.value).toBeCloseTo(0.5, 5);
+    });
+
+    it("should clamp B > 1 to 1", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0.5; c.b = 1.3;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(0.5, 5);
+      expect(result.value.g.value).toBeCloseTo(0.5, 5);
+      expect(result.value.b.value).toBe(1);
+    });
+  });
+
+  describe("Clamping Underflow Values", () => {
+    it("should clamp R < 0 to 0", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = -0.5; c.g = 0.5; c.b = 0.5;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBe(0);
+      expect(result.value.g.value).toBeCloseTo(0.5, 5);
+      expect(result.value.b.value).toBeCloseTo(0.5, 5);
+    });
+
+    it("should clamp negative G to 0", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = -0.1; c.b = 0.5;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(0.5, 5);
+      expect(result.value.g.value).toBe(0);
+      expect(result.value.b.value).toBeCloseTo(0.5, 5);
+    });
+  });
+
+  describe("Multiple Channel Clamping", () => {
+    it("should clamp all channels that are out of range", async () => {
+      const result = await executeWithSchema(
+        "clamp_to_gamut",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = -0.2; c.g = 1.5; c.b = 2.0;
+        clamp_to_gamut(c)
+        `,
+      );
+
+      expect(result.value.r.value).toBe(0);
+      expect(result.value.g.value).toBe(1);
+      expect(result.value.b.value).toBe(1);
+    });
+  });
+});

package/src/schemas/functions/complement/complement.tokenscript

@@ -0,0 +1,21 @@
+// Get the complementary color by rotating hue 180° in OKLCH
+// Preserves lightness and chroma for perceptually balanced results
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Rotate hue by 180°
+variable new_h: Number = color.h + 180;
+if (new_h >= 360) [ new_h = new_h - 360; ];
+
+// Create complementary color
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_h;
+
+return result;
+
+
+
+

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

@@ -0,0 +1,20 @@
+{
+  "name": "Complement",
+  "type": "function",
+  "description": "Returns the complementary color by rotating hue 180° in OKLCH space.",
+  "keyword": "complement",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to find the complement of"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./complement.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Unit tests for the Complement function
+ * Returns the complementary color (180° hue rotation in OKLCH)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Complement Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("complement", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Complement");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("complement");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return complementary color (red → cyan)", async () => {
+      const result = await executeWithSchema(
+        "complement",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 0.9; red.g = 0.2; red.b = 0.2;
+        complement(red).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;
+      // Complement of red-ish should be cyan-ish (g and b higher than r)
+      expect(g).toBeGreaterThan(r);
+      expect(b).toBeGreaterThan(r);
+    });
+
+    it("should be reversible (complement of complement = original hue)", async () => {
+      const result = await executeWithSchema(
+        "complement",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0.2; blue.g = 0.3; blue.b = 0.8;
+        complement(complement(blue)).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const b = (result as any).value.b.value;
+      // Should be back to blue-ish
+      expect(b).toBeGreaterThan(r);
+    });
+
+    it("should preserve lightness", async () => {
+      const result = await executeWithSchema(
+        "complement",
+        "function",
+        `
+        variable light: Color.SRGB;
+        light.r = 0.9; light.g = 0.85; light.b = 0.5;
+        complement(light).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      // Result should have similar luminance
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      const avgOriginal = (0.9 + 0.85 + 0.5) / 3;
+      const avgResult = (r + g + b) / 3;
+      expect(Math.abs(avgOriginal - avgResult)).toBeLessThan(0.3);
+    });
+  });
+});

package/src/schemas/functions/contrast_ratio/contrast-ratio.tokenscript

@@ -0,0 +1,36 @@
+// Calculate WCAG 2.1 contrast ratio between two colors
+//
+// Returns: 1.0 (identical) to 21.0 (black vs white)
+//
+// WCAG Guidelines:
+//   - AA Normal text: ≥ 4.5:1
+//   - AA Large text:  ≥ 3.0:1
+//   - AAA Normal text: ≥ 7.0:1
+//   - AAA Large text:  ≥ 4.5:1
+//
+// Algorithm:
+// 1. Convert to linear RGB
+// 2. Calculate relative luminance: L = 0.2126*R + 0.7152*G + 0.0722*B
+// 3. Contrast ratio: (L_lighter + 0.05) / (L_darker + 0.05)
+
+variable input: List = {input};
+variable color1: Color.LinearSRGB = input.get(0).to.linearsrgb();
+variable color2: Color.LinearSRGB = input.get(1).to.linearsrgb();
+
+// Calculate relative luminance for each color
+variable lum1: Number = 0.2126 * color1.r + 0.7152 * color1.g + 0.0722 * color1.b;
+variable lum2: Number = 0.2126 * color2.r + 0.7152 * color2.g + 0.0722 * color2.b;
+
+// Determine lighter and darker
+variable lighter: Number = lum1;
+variable darker: Number = lum2;
+if (lum2 > lum1) [
+    lighter = lum2;
+    darker = lum1;
+];
+
+// Calculate contrast ratio
+variable ratio: Number = (lighter + 0.05) / (darker + 0.05);
+
+return ratio;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Contrast Ratio",
+  "type": "function",
+  "description": "Calculates the WCAG 2.1 contrast ratio between two colors. Returns a value from 1 (no contrast) to 21 (black/white). WCAG AA requires 4.5:1 for normal text, 3:1 for large text.",
+  "keyword": "contrast_ratio",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color (e.g., background)"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color (e.g., foreground)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./contrast-ratio.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-linear-color/0/"]
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Unit tests for the Contrast Ratio function
+ * Calculates WCAG 2.1 contrast ratio between two colors
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Contrast Ratio Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "contrast_ratio",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("Contrast Ratio");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("contrast_ratio");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return 21:1 for black on white", async () => {
+      const result = await executeWithSchema(
+        "contrast_ratio",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        contrast_ratio(white, black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const ratio = (result as any).value ?? result;
+      expect(ratio).toBeCloseTo(21, 0);
+    });
+
+    it("should return 1:1 for identical colors", async () => {
+      const result = await executeWithSchema(
+        "contrast_ratio",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.5; c2.g = 0.5; c2.b = 0.5;
+        contrast_ratio(c1, c2)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const ratio = (result as any).value ?? result;
+      expect(ratio).toBeCloseTo(1, 0);
+    });
+
+    it("should be symmetrical (a,b = b,a)", async () => {
+      const result1 = await executeWithSchema(
+        "contrast_ratio",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.2; dark.g = 0.2; dark.b = 0.3;
+        variable light: Color.SRGB;
+        light.r = 0.8; light.g = 0.85; light.b = 0.9;
+        contrast_ratio(dark, light)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "contrast_ratio",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.2; dark.g = 0.2; dark.b = 0.3;
+        variable light: Color.SRGB;
+        light.r = 0.8; light.g = 0.85; light.b = 0.9;
+        contrast_ratio(light, dark)
+        `,
+      );
+
+      const ratio1 = (result1 as any).value ?? result1;
+      const ratio2 = (result2 as any).value ?? result2;
+      expect(ratio1).toBeCloseTo(ratio2, 1);
+    });
+  });
+});

package/src/schemas/functions/cooler/cooler.tokenscript

@@ -0,0 +1,45 @@
+// cooler: Shift hue towards cool colors
+//
+// Cool colors are centered around blue (~260° in OKLCH).
+// The function interpolates the hue towards this target via
+// the shortest angular path on the hue wheel.
+//
+// Parameters:
+//   color  - Input color
+//   amount - Shift amount (0 = no change, 1 = fully cool), default 0.25
+//
+// Preserves lightness and chroma.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable amount: Number = 0.25;
+
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Cool hue target (blue in OKLCH is around 260°)
+variable cool_hue: Number = 260;
+
+// Calculate shortest path hue difference
+variable hue_diff: Number = cool_hue - color.h;
+
+// Wrap to shortest path
+if (hue_diff > 180) [ hue_diff = hue_diff - 360; ];
+if (hue_diff < -180) [ hue_diff = hue_diff + 360; ];
+
+// Apply interpolation
+variable new_hue: Number = color.h + (hue_diff * amount);
+
+// Normalize to 0-360
+if (new_hue < 0) [ new_hue = new_hue + 360; ];
+if (new_hue >= 360) [ new_hue = new_hue - 360; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_hue;
+
+return result;
+

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

@@ -0,0 +1,43 @@
+{
+  "name": "cooler",
+  "type": "function",
+  "description": "Shifts a color's hue towards cool colors (blue, ~260° in OKLCH). The amount parameter controls how much to shift, from 0 (no change) to 1 (fully cool). Preserves lightness and chroma.",
+  "keyword": "cooler",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to cool",
+            "type": "color"
+          },
+          {
+            "description": "Amount to shift (0-1), default 0.25",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color shifted towards cool hues"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./cooler.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Make orange cooler",
+      "input": ["#ff6600", 0.5],
+      "output": "Orange shifted towards neutral"
+    }
+  ]
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Unit tests for the cooler function
+ * Shifts hue towards cool colors
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("cooler function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("cooler", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("cooler");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should shift red towards cool (purple)", async () => {
+      const result = await executeWithSchema(
+        "cooler",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        cooler(red, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Red shifted cool should have more blue
+      const b = (result as any).value?.b?.value ?? (result as any).value?.b;
+      expect(b).toBeGreaterThan(0.1);
+    });
+
+    it("should shift yellow towards cool (green)", async () => {
+      const result = await executeWithSchema(
+        "cooler",
+        "function",
+        `
+        variable yellow: Color.SRGB;
+        yellow.r = 1; yellow.g = 1; yellow.b = 0;
+        cooler(yellow, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Yellow shifted cool should have reduced red or increased blue
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeLessThan(1);
+    });
+
+    it("should use default amount if not provided", async () => {
+      const result = await executeWithSchema(
+        "cooler",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        cooler(red).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/darken/darken.tokenscript

@@ -0,0 +1,37 @@
+// darken: Decrease lightness proportionally towards black
+// Amount: 0-1 where 0.25 means 25% closer to black
+//
+// Algorithm: L' = L * (1 - amount)
+// This ensures we approach black (L=0) proportionally.
+//
+// Input:  Any color space (converted to OKLab internally)
+// Output: OKLCH (working space)
+// To get sRGB: darken(color, 0.25).to.srgb()
+
+variable input: List = {input};
+variable color: Color.OKLab = input.get(0).to.oklab();
+
+// Default amount is 0.25 (25%)
+variable amount: Number = 0.25;
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Calculate new lightness (move toward 0)
+variable current_l: Number = color.l;
+variable new_l: Number = current_l * (1 - amount);
+
+// Clamp to valid range
+if (new_l < 0) [ new_l = 0; ];
+
+// Create output in OKLab, return as OKLCH (working space)
+variable result: Color.OKLab;
+result.l = new_l;
+result.a = color.a;
+result.b = color.b;
+
+return result.to.oklch();
+
+
+
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Darken",
+  "type": "function",
+  "description": "Makes a color darker by decreasing its lightness in OKLab space. Amount is 0-1 where 0.25 = 25% darker.",
+  "keyword": "darken",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to darken"
+      },
+      "amount": {
+        "type": "number",
+        "description": "Amount to darken (0-1). Default is 0.25"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./darken.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklab-color/0/", "/api/v1/core/srgb-color/0/"]
+}