@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for the adjust_chroma function
+ * Adjusts chroma by relative amount
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("adjust_chroma function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("adjust_chroma", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("adjust_chroma");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should increase chroma with positive value", async () => {
+      const result = await executeWithSchema(
+        "adjust_chroma",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.5; color.g = 0.4; color.b = 0.4;
+        adjust_chroma(color, 0.1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // More saturated means greater difference between channels
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      expect(r - g).toBeGreaterThan(0.1);
+    });
+
+    it("should decrease chroma with negative value", async () => {
+      const result = await executeWithSchema(
+        "adjust_chroma",
+        "function",
+        `
+        variable orange: Color.SRGB;
+        orange.r = 1; orange.g = 0.4; orange.b = 0;
+        adjust_chroma(orange, -0.1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be less saturated
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      expect(g).toBeGreaterThan(0.4);
+    });
+
+    it("should clamp at zero", async () => {
+      const result = await executeWithSchema(
+        "adjust_chroma",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        adjust_chroma(gray, -1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Should remain gray (all channels equal)
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      const b = (result as any).value?.b?.value ?? (result as any).value?.b;
+      expect(Math.abs(r - g)).toBeLessThan(0.02);
+      expect(Math.abs(g - b)).toBeLessThan(0.02);
+    });
+  });
+});

package/src/schemas/functions/adjust_hue/adjust-hue.tokenscript

@@ -0,0 +1,32 @@
+// adjust_hue: Rotate hue by a relative angle
+//
+// Adds the specified degrees to the color's hue, wrapping
+// around the 360° color wheel. Positive values rotate clockwise,
+// negative values rotate counter-clockwise.
+//
+// Uses OKLCH for perceptually uniform hue rotation.
+// Preserves lightness and chroma.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable degrees: Number = input.get(1);
+
+// Calculate new hue
+variable new_h: Number = color.h + degrees;
+
+// Normalize to 0-360
+while (new_h < 0) [
+    new_h = new_h + 360;
+];
+while (new_h >= 360) [
+    new_h = new_h - 360;
+];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_h;
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "adjust_hue",
+  "type": "function",
+  "description": "Adjusts a color's hue by a relative amount in degrees. Positive values rotate clockwise, negative values counter-clockwise. Unlike set_hue which sets an absolute value, adjust_hue adds to the current hue. Uses OKLCH for perceptually uniform hue rotation.",
+  "keyword": "adjust_hue",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to adjust",
+            "type": "color"
+          },
+          {
+            "description": "Degrees to rotate hue (+ or -)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with adjusted hue"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./adjust-hue.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Shift red toward orange",
+      "input": ["#ff0000", 30],
+      "output": "Orange color"
+    },
+    {
+      "description": "Shift blue toward green",
+      "input": ["#0000ff", -60],
+      "output": "Cyan color"
+    }
+  ]
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Unit tests for the adjust_hue function
+ * Adjusts hue by relative degrees
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("adjust_hue function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("adjust_hue", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("adjust_hue");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should rotate hue clockwise", async () => {
+      const result = await executeWithSchema(
+        "adjust_hue",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        adjust_hue(red, 90).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect((result as any).constructor.name).toBe("ColorSymbol");
+    });
+
+    it("should rotate hue counter-clockwise", async () => {
+      const result = await executeWithSchema(
+        "adjust_hue",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        adjust_hue(red, -90).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect((result as any).constructor.name).toBe("ColorSymbol");
+    });
+
+    it("should wrap around at 360", async () => {
+      const result = await executeWithSchema(
+        "adjust_hue",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        adjust_hue(red, 360).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Should be same hue as input (full rotation)
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.7);
+    });
+  });
+});

package/src/schemas/functions/adjust_lightness/adjust-lightness.tokenscript

@@ -0,0 +1,31 @@
+// adjust_lightness: Adjust lightness by a relative amount
+//
+// Modifies the lightness of a color by adding the specified
+// amount. Positive values lighten, negative values darken.
+// Result is clamped to [0, 1].
+//
+// Preserves hue and chroma.
+//
+// Input:  Any color space (converted to OKLCH internally)
+// Output: OKLCH (working space)
+// To get sRGB: adjust_lightness(color, 0.2).to.srgb()
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable amount: Number = input.get(1);
+
+// Calculate new lightness
+variable new_l: Number = color.l + amount;
+
+// Clamp to valid range
+if (new_l < 0) [ new_l = 0; ];
+if (new_l > 1) [ new_l = 1; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = new_l;
+result.c = color.c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "adjust_lightness",
+  "type": "function",
+  "description": "Adjusts a color's lightness by a relative amount. Positive values make it lighter, negative values make it darker. Unlike set_lightness which sets an absolute value, adjust_lightness adds to the current lightness. Result is clamped to valid range [0, 1].",
+  "keyword": "adjust_lightness",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to adjust",
+            "type": "color"
+          },
+          {
+            "description": "Amount to adjust lightness (+/-)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with adjusted lightness"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./adjust-lightness.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Lighten a color",
+      "input": ["#808080", 0.2],
+      "output": "Lighter gray"
+    },
+    {
+      "description": "Darken a color",
+      "input": ["#808080", -0.3],
+      "output": "Darker gray"
+    }
+  ]
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for the adjust_lightness function
+ * Adjusts lightness by relative amount
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("adjust_lightness function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "adjust_lightness",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("adjust_lightness");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should increase lightness with positive value", async () => {
+      const result = await executeWithSchema(
+        "adjust_lightness",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.3; gray.g = 0.3; gray.b = 0.3;
+        adjust_lightness(gray, 0.3).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.4);
+    });
+
+    it("should decrease lightness with negative value", async () => {
+      const result = await executeWithSchema(
+        "adjust_lightness",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.7; gray.g = 0.7; gray.b = 0.7;
+        adjust_lightness(gray, -0.3).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeLessThan(0.6);
+    });
+
+    it("should clamp to 0 at minimum", async () => {
+      const result = await executeWithSchema(
+        "adjust_lightness",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.2; gray.g = 0.2; gray.b = 0.2;
+        adjust_lightness(gray, -1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should clamp to 1 at maximum", async () => {
+      const result = await executeWithSchema(
+        "adjust_lightness",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.8; gray.g = 0.8; gray.b = 0.8;
+        adjust_lightness(gray, 1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+  });
+});

package/src/schemas/functions/adjust_to_contrast/adjust-to-contrast.tokenscript

@@ -0,0 +1,131 @@
+// adjust_to_contrast: Adjust foreground to meet target WCAG contrast ratio
+// Reference: WCAG 2.1 Contrast Ratio Definition
+// Reference: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+//
+// Modifies the foreground color's lightness (in OKLCH) to achieve
+// the specified contrast ratio against the background, while
+// preserving hue and chroma.
+//
+// Parameters:
+//   foreground   - Color to adjust
+//   background   - Reference background color
+//   target_ratio - Minimum contrast ratio (default: 4.5 for WCAG AA)
+//
+// Uses binary search in OKLCH lightness for convergence.
+//
+// Input:  Any color space (converted to OKLCH internally)
+// Output: OKLCH (working space)
+// To get sRGB: adjust_to_contrast(fg, bg, 4.5).to.srgb()
+
+variable input: List = {input};
+variable foreground: Color.OKLCH = input.get(0).to.oklch();
+variable bg_xyz: Color.XYZD65 = input.get(1).to.xyzd65();
+
+// Default to WCAG AA for normal text
+variable target_ratio: Number = 4.5;
+if (input.length() > 2) [
+    target_ratio = input.get(2);
+];
+
+// Get background luminance
+variable bg_lum: Number = bg_xyz.y;
+
+// Determine if we need to go lighter or darker
+// Test with current foreground
+variable test_oklch: Color.OKLCH;
+test_oklch.l = foreground.l;
+test_oklch.c = foreground.c;
+test_oklch.h = foreground.h;
+
+variable test_xyz: Color.XYZD65 = test_oklch.to.srgb().to.xyzd65();
+variable fg_lum: Number = test_xyz.y;
+
+// Calculate current contrast
+variable l1: Number = fg_lum;
+variable l2: Number = bg_lum;
+if (l2 > l1) [
+    l1 = bg_lum;
+    l2 = fg_lum;
+];
+variable current_ratio: Number = (l1 + 0.05) / (l2 + 0.05);
+
+// If already meets target, return as-is (in OKLCH working space)
+if (current_ratio >= target_ratio) [
+    return foreground;
+];
+
+// Determine direction: if background is dark, we need lighter foreground and vice versa
+variable search_min: Number = 0;
+variable search_max: Number = 1;
+
+// Binary search for correct lightness
+variable epsilon: Number = 0.001;
+variable iterations: Number = 0;
+variable max_iterations: Number = 30;
+variable best_l: Number = foreground.l;
+variable best_ratio: Number = current_ratio;
+
+variable diff: Number = search_max - search_min;
+variable mid_l: Number = 0.5;
+variable test_ratio: Number = 1;
+
+while (diff > epsilon) [
+    if (iterations >= max_iterations) [
+        diff = 0;  // Force exit
+    ];
+    mid_l = (search_min + search_max) / 2;
+    
+    // Test this lightness
+    test_oklch.l = mid_l;
+    test_oklch.c = foreground.c;
+    test_oklch.h = foreground.h;
+    
+    // Convert to get luminance
+    test_xyz = test_oklch.to.srgb().to.xyzd65();
+    fg_lum = test_xyz.y;
+    
+    // Calculate contrast
+    l1 = fg_lum;
+    l2 = bg_lum;
+    if (l2 > l1) [
+        l1 = bg_lum;
+        l2 = fg_lum;
+    ];
+    test_ratio = (l1 + 0.05) / (l2 + 0.05);
+    
+    // Track best result
+    if (test_ratio >= target_ratio) [
+        // This lightness works, but can we get closer to original?
+        // If background is dark (low lum), we want darker foreground closer to original
+        // If background is light (high lum), we want lighter foreground closer to original
+        if (bg_lum < 0.18) [
+            // Dark background: search lower (darker)
+            search_max = mid_l;
+        ] else [
+            // Light background: search higher (lighter)
+            search_min = mid_l;
+        ];
+        best_l = mid_l;
+        best_ratio = test_ratio;
+    ] else [
+        // Not enough contrast, need more separation
+        if (bg_lum < 0.18) [
+            // Dark background: need lighter foreground
+            search_min = mid_l;
+        ] else [
+            // Light background: need darker foreground
+            search_max = mid_l;
+        ];
+    ];
+    
+    iterations = iterations + 1;
+    diff = search_max - search_min;
+];
+
+// Apply best lightness found, return in OKLCH working space
+variable result: Color.OKLCH;
+result.l = best_l;
+result.c = foreground.c;
+result.h = foreground.h;
+
+return result;

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

@@ -0,0 +1,56 @@
+{
+  "name": "adjust_to_contrast",
+  "type": "function",
+  "description": "Adjusts a foreground color's lightness to achieve a target WCAG contrast ratio against a background. Preserves hue and chroma while finding the optimal lightness. Uses binary search in OKLCH space for perceptually even adjustments. If target contrast cannot be achieved (e.g., trying to get 21:1 with mid-gray), returns the best possible result.",
+  "keyword": "adjust_to_contrast",
+  "requirements": [
+    "/api/v1/core/srgb-color/0/",
+    "/api/v1/core/oklch-color/0/",
+    "/api/v1/core/xyz-d65-color/0/"
+  ],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Foreground color to adjust",
+            "type": "color"
+          },
+          {
+            "description": "Background color (fixed)",
+            "type": "color"
+          },
+          {
+            "description": "Target contrast ratio (default 4.5 for WCAG AA)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Adjusted foreground color meeting the target contrast"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./adjust-to-contrast.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Adjust light gray to meet AA on white",
+      "input": ["#cccccc", "#ffffff", 4.5],
+      "output": "Darkened gray meeting 4.5:1"
+    },
+    {
+      "description": "Adjust brand color for accessibility",
+      "input": ["#6750a4", "#ffffff", 4.5],
+      "output": "Adjusted purple meeting 4.5:1"
+    }
+  ]
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Unit tests for the adjust_to_contrast function
+ * Adjusts a color to meet a target contrast ratio
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("adjust_to_contrast function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "adjust_to_contrast",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("adjust_to_contrast");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return unchanged if already meets contrast", async () => {
+      const result = await executeWithSchema(
+        "adjust_to_contrast",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        adjust_to_contrast(black, white, 4.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Black on white already has 21:1 contrast, should stay black
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should darken light color on white background", async () => {
+      const result = await executeWithSchema(
+        "adjust_to_contrast",
+        "function",
+        `
+        variable light_gray: Color.SRGB;
+        light_gray.r = 0.8; light_gray.g = 0.8; light_gray.b = 0.8;
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        adjust_to_contrast(light_gray, white, 4.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be darker than original
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeLessThan(0.7);
+    });
+
+    it("should lighten dark color on black background", async () => {
+      const result = await executeWithSchema(
+        "adjust_to_contrast",
+        "function",
+        `
+        variable dark_gray: Color.SRGB;
+        dark_gray.r = 0.2; dark_gray.g = 0.2; dark_gray.b = 0.2;
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        adjust_to_contrast(dark_gray, black, 4.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be lighter than original
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.3);
+    });
+  });
+});