@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.12

package/src/schemas/functions/alpha_blend/alpha-blend.tokenscript

@@ -0,0 +1,46 @@
+// Alpha Blend (Porter-Duff Over Compositing)
+// Reference: Porter & Duff "Compositing Digital Images" (1984)
+// Reference: W3C CSS Color Level 4 - Alpha Compositing
+//
+// Formula: result = foreground × α + background × (1 - α)
+// 
+// This is the standard "over" operation:
+// - α = 0: result is entirely background
+// - α = 1: result is entirely foreground
+// - 0 < α < 1: blend of both colors
+//
+// Used in:
+// - CSS opacity and rgba
+// - Semi-transparent overlays
+// - Gradient stops
+// - Glass/frosted effects
+
+variable input: List = {input};
+variable fg: Color.SRGB = input.get(0).to.srgb();
+variable bg: Color.SRGB = input.get(1).to.srgb();
+
+// Default alpha is 0.5 (50% opacity)
+variable alpha: Number = 0.5;
+if (input.length() > 2) [
+    alpha = input.get(2);
+];
+
+// Clamp alpha to valid range
+if (alpha < 0) [ alpha = 0; ];
+if (alpha > 1) [ alpha = 1; ];
+
+// Porter-Duff "over" compositing
+variable inv_alpha: Number = 1 - alpha;
+
+variable r: Number = fg.r * alpha + bg.r * inv_alpha;
+variable g: Number = fg.g * alpha + bg.g * inv_alpha;
+variable b: Number = fg.b * alpha + bg.b * inv_alpha;
+
+// Create result
+variable result: Color.SRGB;
+result.r = r;
+result.g = g;
+result.b = b;
+
+return result;
+

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

@@ -0,0 +1,28 @@
+{
+  "name": "Alpha Blend",
+  "type": "function",
+  "description": "Performs Porter-Duff 'over' compositing to blend a foreground color over a background color using the foreground's alpha. Formula: result = fg × α + bg × (1-α). Standard alpha compositing used in CSS and graphics software.",
+  "keyword": "alpha_blend",
+  "input": {
+    "type": "object",
+    "properties": {
+      "foreground": {
+        "type": "color",
+        "description": "Foreground (top) color"
+      },
+      "background": {
+        "type": "color",
+        "description": "Background (bottom) color"
+      },
+      "alpha": {
+        "type": "number",
+        "description": "Opacity of foreground (0-1, default: 0.5)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./alpha-blend.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,135 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Alpha Blend Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("alpha_blend", "function");
+
+      expect(schema.name).toBe("Alpha Blend");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("alpha_blend");
+    });
+  });
+
+  describe("Extreme Alpha Values", () => {
+    it("alpha=0 should return background color", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 0; fg.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 1;
+        alpha_blend(fg, bg, 0)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(0, 5);
+      expect(result.value.g.value).toBeCloseTo(0, 5);
+      expect(result.value.b.value).toBeCloseTo(1, 5);
+    });
+
+    it("alpha=1 should return foreground color", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 0; fg.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 1;
+        alpha_blend(fg, bg, 1)
+        `,
+      );
+
+      expect(result.value.r.value).toBeCloseTo(1, 5);
+      expect(result.value.g.value).toBeCloseTo(0, 5);
+      expect(result.value.b.value).toBeCloseTo(0, 5);
+    });
+  });
+
+  describe("Default Alpha", () => {
+    it("should use 0.5 alpha by default", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 1; fg.b = 1;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 0;
+        alpha_blend(fg, bg)
+        `,
+      );
+
+      // 50% white over black = 50% gray
+      expect(result.value.r.value).toBeCloseTo(0.5, 5);
+      expect(result.value.g.value).toBeCloseTo(0.5, 5);
+      expect(result.value.b.value).toBeCloseTo(0.5, 5);
+    });
+  });
+
+  describe("Blending Formula", () => {
+    it("should blend correctly at 25% alpha", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 0; fg.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 1; bg.b = 0;
+        alpha_blend(fg, bg, 0.25)
+        `,
+      );
+
+      // R: 1*0.25 + 0*0.75 = 0.25
+      // G: 0*0.25 + 1*0.75 = 0.75
+      // B: 0*0.25 + 0*0.75 = 0
+      expect(result.value.r.value).toBeCloseTo(0.25, 5);
+      expect(result.value.g.value).toBeCloseTo(0.75, 5);
+      expect(result.value.b.value).toBeCloseTo(0, 5);
+    });
+  });
+
+  describe("Alpha Clamping", () => {
+    it("should clamp negative alpha to 0", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 0; fg.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 1; bg.b = 0;
+        alpha_blend(fg, bg, -0.5)
+        `,
+      );
+
+      // Should be same as alpha=0 (all background)
+      expect(result.value.r.value).toBeCloseTo(0, 5);
+      expect(result.value.g.value).toBeCloseTo(1, 5);
+    });
+
+    it("should clamp alpha > 1 to 1", async () => {
+      const result = await executeWithSchema(
+        "alpha_blend",
+        "function",
+        `
+        variable fg: Color.SRGB;
+        fg.r = 1; fg.g = 0; fg.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 1; bg.b = 0;
+        alpha_blend(fg, bg, 1.5)
+        `,
+      );
+
+      // Should be same as alpha=1 (all foreground)
+      expect(result.value.r.value).toBeCloseTo(1, 5);
+      expect(result.value.g.value).toBeCloseTo(0, 5);
+    });
+  });
+});

package/src/schemas/functions/alpha_scale/alpha-scale.tokenscript

@@ -0,0 +1,38 @@
+// Generate alpha/transparency scale
+// Returns colors from 100% opacity down to nearly transparent
+//
+// Default 10 steps: 100%, 90%, 80%, 70%, 60%, 50%, 40%, 30%, 20%, 10%
+// Useful for: overlays, shadows, backgrounds, hover states
+
+variable input: List = {input};
+variable base: Color.SRGB = input.get(0).to.srgb();
+
+variable count: Number = 10;
+if (input.length() > 1) [
+    count = input.get(1);
+];
+
+variable result: List;
+variable i: Number = 0;
+variable step_alpha: Number = 0;
+variable step_color: Color.SRGB;
+
+while (i < count) [
+    // Alpha from 1.0 down to 0.1
+    step_alpha = 1 - (i / count);
+    
+    // Create color with alpha
+    // Note: This creates the color value; actual alpha handling
+    // depends on how the consuming system processes the output
+    step_color.r = base.r;
+    step_color.g = base.g;
+    step_color.b = base.b;
+    
+    // Store alpha as 4th value (RGBA convention)
+    // Use .to.srgb() to create a new color instance for each step
+    result = result, step_color.to.srgb(), step_alpha;
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Alpha Scale",
+  "type": "function",
+  "description": "Generates transparency variants of a color. Returns colors with progressively lower opacity. Perfect for overlays, shadows, and layered UI elements.",
+  "keyword": "alpha_scale",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of alpha steps. Default is 10"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./alpha-scale.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Unit tests for the Alpha Scale function
+ * Generates an alpha transparency scale
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Alpha Scale Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("alpha_scale", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Alpha Scale");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("alpha_scale");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate alpha scale", async () => {
+      const result = await executeWithSchema(
+        "alpha_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.2; base.g = 0.4; base.b = 0.8;
+        alpha_scale(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of steps", async () => {
+      const result = await executeWithSchema(
+        "alpha_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.9; base.g = 0.2; base.b = 0.3;
+        alpha_scale(base, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/analogous/analogous.tokenscript

@@ -0,0 +1,47 @@
+// Generate analogous colors (adjacent hues)
+// Colors are spread evenly around the base hue
+//
+// Use case: Harmonious, subtle palettes
+// Example: 5 colors with 60° spread = -30°, -15°, 0°, +15°, +30°
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+variable count: Number = 5;
+if (input.length() > 1) [
+    count = input.get(1);
+];
+
+variable spread: Number = 60;
+if (input.length() > 2) [
+    spread = input.get(2);
+];
+
+// Calculate step size and starting offset
+variable step: Number = spread / (count - 1);
+variable start_offset: Number = 0 - spread / 2;
+
+variable result: List;
+variable i: Number = 0;
+variable hue_offset: Number = 0;
+variable new_hue: Number = 0;
+variable color: Color.OKLCH;
+
+while (i < count) [
+    hue_offset = start_offset + i * step;
+    new_hue = base.h + hue_offset;
+    
+    // Normalize hue to 0-360
+    if (new_hue < 0) [ new_hue = new_hue + 360; ];
+    if (new_hue >= 360) [ new_hue = new_hue - 360; ];
+    
+    color.l = base.l;
+    color.c = base.c;
+    color.h = new_hue;
+    
+    result = result, color.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,28 @@
+{
+  "name": "Analogous",
+  "type": "function",
+  "description": "Generates analogous colors - hues adjacent on the color wheel. Creates harmonious, low-contrast palettes. Perfect for backgrounds and subtle variations.",
+  "keyword": "analogous",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of colors (odd recommended). Default is 5"
+      },
+      "spread": {
+        "type": "number",
+        "description": "Total angle spread in degrees. Default is 60"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./analogous.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for the Analogous function
+ * Generates analogous colors (adjacent hues)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Analogous Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("analogous", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Analogous");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("analogous");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 5 colors by default", async () => {
+      const result = await executeWithSchema(
+        "analogous",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.8; base.g = 0.3; base.b = 0.3;
+        analogous(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of colors", async () => {
+      const result = await executeWithSchema(
+        "analogous",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.3; base.g = 0.6; base.b = 0.9;
+        analogous(base, 3)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should use custom spread angle", async () => {
+      const result = await executeWithSchema(
+        "analogous",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.5; base.g = 0.8; base.b = 0.3;
+        analogous(base, 5, 30)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/apca_contrast/apca-contrast.tokenscript

@@ -0,0 +1,129 @@
+// APCA Contrast (Accessible Perceptual Contrast Algorithm)
+// Version: APCA 0.0.98G (W3C/WCAG 3.0 Draft)
+// Reference: https://github.com/Myndex/apca-w3
+// Reference: https://www.w3.org/TR/wcag-3.0/#visual-contrast-of-text
+//
+// Returns Lc (Lightness contrast) value:
+//   - Range: approximately -108 to +106
+//   - Positive values: light text on dark background
+//   - Negative values: dark text on light background
+//   - |Lc| >= 75: Preferred for body text
+//   - |Lc| >= 60: Minimum for body text
+//   - |Lc| >= 45: Minimum for large text (≥24px)
+//   - |Lc| >= 30: Minimum for non-text elements
+//
+// Algorithm:
+// 1. Convert to sRGB and linearize with simple 2.4 gamma
+// 2. Calculate screen luminance Y with sRGB coefficients
+// 3. Apply soft black clamp for flare compensation
+// 4. Calculate contrast with asymmetric formula (BoW vs WoB)
+// 5. Apply low clip and offset
+
+variable input: List = {input};
+variable text: Color.SRGB = input.get(0).to.srgb();
+variable bg: Color.SRGB = input.get(1).to.srgb();
+
+// APCA Constants (from specification)
+// Exponents
+variable norm_bg: Number = 0.56;
+variable norm_txt: Number = 0.57;
+variable rev_txt: Number = 0.62;
+variable rev_bg: Number = 0.65;
+
+// Soft black clamp constants
+variable blk_thrs: Number = 0.022;
+variable blk_clmp: Number = 1.414;
+
+// Low clip (noise gate)
+variable lo_clip: Number = 0.1;
+variable delta_y_min: Number = 0.0005;
+
+// Scalers and offset
+variable scale_bow: Number = 1.14;
+variable scale_wob: Number = 1.14;
+variable lo_offset: Number = 0.027;
+
+// Linearize sRGB with simple 2.4 gamma (NOT full sRGB transfer function)
+// This is per APCA specification which uses simplified gamma
+variable text_r: Number = text.r;
+variable text_g: Number = text.g;
+variable text_b: Number = text.b;
+variable bg_r: Number = bg.r;
+variable bg_g: Number = bg.g;
+variable bg_b: Number = bg.b;
+
+// Handle negative values (out of gamut)
+if (text_r < 0) [ text_r = 0 - text_r; ];
+if (text_g < 0) [ text_g = 0 - text_g; ];
+if (text_b < 0) [ text_b = 0 - text_b; ];
+if (bg_r < 0) [ bg_r = 0 - bg_r; ];
+if (bg_g < 0) [ bg_g = 0 - bg_g; ];
+if (bg_b < 0) [ bg_b = 0 - bg_b; ];
+
+// Linearize with 2.4 gamma
+variable lin_text_r: Number = pow(text_r, 2.4);
+variable lin_text_g: Number = pow(text_g, 2.4);
+variable lin_text_b: Number = pow(text_b, 2.4);
+variable lin_bg_r: Number = pow(bg_r, 2.4);
+variable lin_bg_g: Number = pow(bg_g, 2.4);
+variable lin_bg_b: Number = pow(bg_b, 2.4);
+
+// Calculate screen luminance Y using sRGB coefficients
+// Coefficients from Myndex/APCA spec (via Lindbloom)
+variable y_text: Number = 0.2126729 * lin_text_r + 0.7151522 * lin_text_g + 0.0721750 * lin_text_b;
+variable y_bg: Number = 0.2126729 * lin_bg_r + 0.7151522 * lin_bg_g + 0.0721750 * lin_bg_b;
+
+// Soft clamp for flare (low luminance adjustment)
+// If Y >= threshold, use Y as-is
+// Otherwise: Y + (threshold - Y)^1.414
+variable y_txt_clamped: Number = y_text;
+variable y_bg_clamped: Number = y_bg;
+
+if (y_text < blk_thrs) [
+    variable diff_txt: Number = blk_thrs - y_text;
+    y_txt_clamped = y_text + pow(diff_txt, blk_clmp);
+];
+
+if (y_bg < blk_thrs) [
+    variable diff_bg: Number = blk_thrs - y_bg;
+    y_bg_clamped = y_bg + pow(diff_bg, blk_clmp);
+];
+
+// Determine polarity: BoW (dark on light) or WoB (light on dark)
+variable sapc: Number = 0;
+variable s_contrast: Number = 0;
+
+// Noise gate check
+variable y_diff: Number = y_bg_clamped - y_txt_clamped;
+if (y_diff < 0) [ y_diff = 0 - y_diff; ];
+
+// Negative lo_clip for comparison (avoid parsing issues)
+variable neg_lo_clip: Number = 0 - lo_clip;
+
+if (y_diff >= delta_y_min) [
+    if (y_bg_clamped > y_txt_clamped) [
+        // BoW: Dark text on light background (returns POSITIVE per APCA spec)
+        s_contrast = pow(y_bg_clamped, norm_bg) - pow(y_txt_clamped, norm_txt);
+        sapc = s_contrast * scale_bow;
+        
+        if (sapc < lo_clip) [
+            sapc = 0;
+        ] else [
+            sapc = sapc - lo_offset;
+        ];
+    ] else [
+        // WoB: Light text on dark background (returns NEGATIVE per APCA spec)
+        s_contrast = pow(y_bg_clamped, rev_bg) - pow(y_txt_clamped, rev_txt);
+        sapc = s_contrast * scale_wob;
+        
+        if (sapc > neg_lo_clip) [
+            sapc = 0;
+        ] else [
+            sapc = sapc + lo_offset;
+        ];
+    ];
+];
+
+// Return Lc * 100 (standard APCA output format)
+return sapc * 100;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "APCA Contrast",
+  "type": "function",
+  "description": "Calculates APCA (Accessible Perceptual Contrast Algorithm) contrast between text and background colors. APCA is part of WCAG 3.0 draft and provides perceptually uniform contrast values. Returns Lc value from -108 to +106. Positive = light text on dark, negative = dark text on light. |Lc| ≥ 60 recommended for body text.",
+  "keyword": "apca_contrast",
+  "input": {
+    "type": "object",
+    "properties": {
+      "text": {
+        "type": "color",
+        "description": "Text/foreground color"
+      },
+      "background": {
+        "type": "color",
+        "description": "Background color"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./apca-contrast.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-color/0/"]
+}