@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,24 @@
+{
+  "name": "Best Contrast",
+  "type": "function",
+  "description": "Selects the color with highest contrast against a background from a list of candidates. Uses WCAG 2.1 contrast ratio. Perfect for choosing readable text colors.",
+  "keyword": "best_contrast",
+  "input": {
+    "type": "object",
+    "properties": {
+      "background": {
+        "type": "color",
+        "description": "The background color to contrast against"
+      },
+      "candidates": {
+        "type": "list",
+        "description": "List of candidate colors to choose from. Default is [black, white]"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./best-contrast.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-linear-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for the Best Contrast function
+ * Selects the most contrasting color from candidates against a background
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Best Contrast Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("best_contrast", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Best Contrast");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("best_contrast");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return white on dark background (default candidates)", async () => {
+      const result = await executeWithSchema(
+        "best_contrast",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.1; dark.g = 0.1; dark.b = 0.2;
+        best_contrast(dark)
+        `,
+      );
+
+      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;
+      // Should be white (high values)
+      expect(r).toBeGreaterThan(0.9);
+      expect(g).toBeGreaterThan(0.9);
+      expect(b).toBeGreaterThan(0.9);
+    });
+
+    it("should return black on light background (default candidates)", async () => {
+      const result = await executeWithSchema(
+        "best_contrast",
+        "function",
+        `
+        variable light: Color.SRGB;
+        light.r = 0.95; light.g = 0.95; light.b = 0.9;
+        best_contrast(light)
+        `,
+      );
+
+      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;
+      // Should be black (low values)
+      expect(r).toBeLessThan(0.1);
+      expect(g).toBeLessThan(0.1);
+      expect(b).toBeLessThan(0.1);
+    });
+  });
+});

package/src/schemas/functions/chroma/chroma.tokenscript

@@ -0,0 +1,12 @@
+// chroma: Extract chroma (colorfulness) from a color
+// Reference: OKLCH Color Space (Björn Ottosson)
+// Reference: https://bottosson.github.io/posts/oklab/
+//
+// Returns the C component from OKLCH, which represents
+// colorfulness/saturation. Range: 0 (gray) to ~0.4 (most vivid).
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+return color.c;
+

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

@@ -0,0 +1,44 @@
+{
+  "name": "chroma",
+  "type": "function",
+  "description": "Extracts the chroma (colorfulness/saturation) value from any color using OKLCH. Returns a value from 0 (gray) to approximately 0.4 (most saturated colors). Chroma in OKLCH represents the colorfulness independent of lightness - higher values mean more vivid colors. Essential for creating consistent color scales and checking color vibrancy.",
+  "keyword": "chroma",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to extract chroma from",
+            "type": "color"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 1
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "number",
+    "description": "Chroma value (0 to ~0.4)"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./chroma.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Gray has chroma 0",
+      "input": ["#808080"],
+      "output": 0
+    },
+    {
+      "description": "Saturated red has high chroma",
+      "input": ["#ff0000"],
+      "output": 0.26
+    }
+  ]
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Unit tests for the chroma function
+ * Extracts chroma (colorfulness) from a color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("chroma function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("chroma", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("chroma");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return 0 for gray", async () => {
+      const result = await executeWithSchema(
+        "chroma",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        chroma(gray)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const c = (result as any).value ?? result;
+      expect(c).toBeCloseTo(0, 2);
+    });
+
+    it("should return 0 for white", async () => {
+      const result = await executeWithSchema(
+        "chroma",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        chroma(white)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const c = (result as any).value ?? result;
+      expect(c).toBeCloseTo(0, 2);
+    });
+
+    it("should return 0 for black", async () => {
+      const result = await executeWithSchema(
+        "chroma",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        chroma(black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const c = (result as any).value ?? result;
+      expect(c).toBeCloseTo(0, 2);
+    });
+
+    it("should return high chroma for saturated red", async () => {
+      const result = await executeWithSchema(
+        "chroma",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        chroma(red)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const c = (result as any).value ?? result;
+      // Red has high chroma in OKLCH
+      expect(c).toBeGreaterThan(0.2);
+    });
+  });
+});

package/src/schemas/functions/clamp_chroma/clamp-chroma.tokenscript

@@ -0,0 +1,21 @@
+// clamp_chroma: Constrain chroma to a range
+// Preserves hue and lightness
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable min_c: Number = input.get(1);
+variable max_c: Number = input.get(2);
+
+// Clamp chroma
+variable new_c: Number = color.c;
+if (new_c < min_c) [ new_c = min_c; ];
+if (new_c > max_c) [ new_c = max_c; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,52 @@
+{
+  "name": "clamp_chroma",
+  "type": "function",
+  "description": "Constrains a color's chroma (saturation) to a specified range while preserving hue and lightness. Useful for ensuring colors stay within brand guidelines or design constraints. Uses OKLCH for perceptually uniform clamping.",
+  "keyword": "clamp_chroma",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to clamp",
+            "type": "color"
+          },
+          {
+            "description": "Minimum chroma (0+)",
+            "type": "number"
+          },
+          {
+            "description": "Maximum chroma (typically 0-0.4)",
+            "type": "number"
+          }
+        ],
+        "minItems": 3,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with clamped chroma"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./clamp-chroma.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Limit maximum saturation",
+      "input": ["#ff0000", 0, 0.15],
+      "output": "Muted red with chroma 0.15"
+    },
+    {
+      "description": "Ensure minimum saturation",
+      "input": ["#808080", 0.05, 0.3],
+      "output": "Slightly colored gray"
+    }
+  ]
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for the clamp_chroma function
+ * Constrains chroma to a range
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("clamp_chroma function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("clamp_chroma", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("clamp_chroma");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should clamp saturated color to maximum", async () => {
+      const result = await executeWithSchema(
+        "clamp_chroma",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        clamp_chroma(red, 0, 0.1).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be less saturated
+      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;
+      // Less extreme difference between channels
+      expect(r - g).toBeLessThan(0.8);
+    });
+
+    it("should preserve already-low-chroma colors", async () => {
+      const result = await executeWithSchema(
+        "clamp_chroma",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        clamp_chroma(gray, 0, 0.3).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Gray should remain gray
+      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.1);
+      expect(Math.abs(g - b)).toBeLessThan(0.1);
+    });
+  });
+});

package/src/schemas/functions/clamp_lightness/clamp-lightness.tokenscript

@@ -0,0 +1,21 @@
+// clamp_lightness: Constrain lightness to a range
+// Preserves hue and chroma
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable min_l: Number = input.get(1);
+variable max_l: Number = input.get(2);
+
+// Clamp lightness
+variable new_l: Number = color.l;
+if (new_l < min_l) [ new_l = min_l; ];
+if (new_l > max_l) [ new_l = max_l; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = new_l;
+result.c = color.c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,52 @@
+{
+  "name": "clamp_lightness",
+  "type": "function",
+  "description": "Constrains a color's lightness to a specified range while preserving hue and chroma. Useful for ensuring colors stay within readable/accessible bounds. Uses OKLCH for perceptually uniform clamping.",
+  "keyword": "clamp_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 clamp",
+            "type": "color"
+          },
+          {
+            "description": "Minimum lightness (0-1)",
+            "type": "number"
+          },
+          {
+            "description": "Maximum lightness (0-1)",
+            "type": "number"
+          }
+        ],
+        "minItems": 3,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with clamped lightness"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./clamp-lightness.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Clamp too-dark color to minimum",
+      "input": ["#111111", 0.3, 0.9],
+      "output": "Color with lightness 0.3"
+    },
+    {
+      "description": "Clamp too-light color to maximum",
+      "input": ["#ffffff", 0.2, 0.8],
+      "output": "Color with lightness 0.8"
+    }
+  ]
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for the clamp_lightness function
+ * Constrains lightness to a range
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("clamp_lightness function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "clamp_lightness",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("clamp_lightness");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should clamp dark color to minimum", async () => {
+      const result = await executeWithSchema(
+        "clamp_lightness",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.1; dark.g = 0.1; dark.b = 0.1;
+        clamp_lightness(dark, 0.5, 0.9).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be brighter than input
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.3);
+    });
+
+    it("should clamp light color to maximum", async () => {
+      const result = await executeWithSchema(
+        "clamp_lightness",
+        "function",
+        `
+        variable light: Color.SRGB;
+        light.r = 1; light.g = 1; light.b = 1;
+        clamp_lightness(light, 0.1, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Result should be darker than input
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeLessThan(0.8);
+    });
+
+    it("should not change color within range", async () => {
+      const result = await executeWithSchema(
+        "clamp_lightness",
+        "function",
+        `
+        variable mid: Color.SRGB;
+        mid.r = 0.5; mid.g = 0.5; mid.b = 0.5;
+        clamp_lightness(mid, 0.1, 0.9).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Mid-gray should remain mid-gray
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.3);
+      expect(r).toBeLessThan(0.7);
+    });
+  });
+});

package/src/schemas/functions/clamp_to_gamut/clamp-to-gamut.tokenscript

@@ -0,0 +1,41 @@
+// Clamp to Gamut (Simple Clipping)
+// Clips out-of-gamut sRGB values to [0, 1] range
+// Reference: Color.js toGamut with method="clip"
+//
+// This is the simplest gamut mapping approach:
+// - Fast and deterministic
+// - Preserves hue when only one channel clips
+// - Can cause hue shifts when multiple channels clip
+// - May lose saturation detail
+//
+// For perceptually better results, use toGamut() which
+// reduces chroma in OKLCH before clipping.
+
+variable input: List = {input};
+variable color: Color.SRGB = input.get(0).to.srgb();
+
+// Get RGB values
+variable r: Number = color.r;
+variable g: Number = color.g;
+variable b: Number = color.b;
+
+// Clamp R
+if (r < 0) [ r = 0; ];
+if (r > 1) [ r = 1; ];
+
+// Clamp G
+if (g < 0) [ g = 0; ];
+if (g > 1) [ g = 1; ];
+
+// Clamp B
+if (b < 0) [ b = 0; ];
+if (b > 1) [ b = 1; ];
+
+// Create clamped result
+variable result: Color.SRGB;
+result.r = r;
+result.g = g;
+result.b = b;
+
+return result;
+

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

@@ -0,0 +1,20 @@
+{
+  "name": "Clamp to Gamut",
+  "type": "function",
+  "description": "Clips a color to the sRGB gamut by clamping each RGB channel to [0,1]. This is a simple but lossy approach - for perceptually better results, consider using gamut mapping algorithms that reduce chroma first.",
+  "keyword": "clamp_to_gamut",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Color to clamp"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./clamp-to-gamut.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-color/0/"]
+}