@fibery/ui-kit 2.0.0 → 2.1.0

package/src/color-utils.test.ts

@@ -1,37 +1,47 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+// oxlint-disable typescript/no-require-imports
+import {Color, differenceCie76} from "culori";
 import {
-  fromHSL,
+  clampRgb,
+  cssFromUnsafe,
+  darkenChroma,
+  desaturateChroma,
   fromOKLCH,
   getAlpha,
   getColorDistance,
-  getContrastRatio,
-  getHsl,
   getLuminance,
   isValidColor,
-  toCss,
-  toOKLCH,
+  produceColor,
+  rgbFrom,
+  setLuminanceChroma,
 } from "./color-utils";
 
+const testColors = ["#FF5400", "#4978D4", "#08BD9F", "#FBA32F", "#673DB6", "#000000", "#FFFFFF"];
+
+const parseSafe = (color: string): Color => rgbFrom(color)!;
+const cie76 = differenceCie76();
+
 describe("color-utils", () => {
-  describe("css", () => {
+  describe("cssFromUnsafe", () => {
     it("normalizes hex to rgb", () => {
-      expect(toCss("#ff0000")).toMatchInlineSnapshot(`"rgb(255,0,0)"`);
+      expect(cssFromUnsafe("#ff0000")).toMatchInlineSnapshot(`"rgb(255, 0, 0)"`);
     });
 
     it("normalizes named colors to rgb", () => {
-      expect(toCss("red")).toMatchInlineSnapshot(`"rgb(255,0,0)"`);
-      expect(toCss("blue")).toMatchInlineSnapshot(`"rgb(0,0,255)"`);
+      expect(cssFromUnsafe("red")).toMatchInlineSnapshot(`"rgb(255, 0, 0)"`);
+      expect(cssFromUnsafe("blue")).toMatchInlineSnapshot(`"rgb(0, 0, 255)"`);
     });
 
     it("preserves alpha in rgba", () => {
-      expect(toCss("rgba(255, 0, 0, 0.5)")).toMatchInlineSnapshot(`"rgba(255,0,0,0.5)"`);
+      expect(cssFromUnsafe("rgba(255, 0, 0, 0.5)")).toMatchInlineSnapshot(`"rgba(255, 0, 0, 0.5)"`);
     });
 
     it("converts hsl to rgb", () => {
-      expect(toCss("hsl(0, 100%, 50%)")).toMatchInlineSnapshot(`"rgb(255,0,0)"`);
+      expect(cssFromUnsafe("hsl(0, 100%, 50%)")).toMatchInlineSnapshot(`"rgb(255, 0, 0)"`);
     });
 
     it("returns fallback for invalid color", () => {
-      expect(toCss("invalid")).toMatchInlineSnapshot(`"rgb(73,120,212)"`);
+      expect(cssFromUnsafe("invalid")).toMatchInlineSnapshot(`"rgb(73, 120, 212)"`);
     });
   });
 
@@ -96,41 +106,13 @@ describe("color-utils", () => {
 
   describe("toCss", () => {
     it("converts to rgb for opaque colors", () => {
-      const result = toCss("#ff0000");
-      expect(result).toMatchInlineSnapshot(`"rgb(255,0,0)"`);
+      const result = cssFromUnsafe("#ff0000");
+      expect(result).toMatchInlineSnapshot(`"rgb(255, 0, 0)"`);
     });
 
     it("converts to rgba for colors with alpha", () => {
-      const result = toCss("rgba(255, 0, 0, 0.5)");
-      expect(result).toMatchInlineSnapshot(`"rgba(255,0,0,0.5)"`);
-    });
-  });
-
-  describe("getContrastRatio", () => {
-    it("returns 21 for black on white", () => {
-      expect(getContrastRatio("#000000", "#ffffff")).toBeCloseTo(21, 0);
-    });
-
-    it("returns 21 for white on black", () => {
-      expect(getContrastRatio("#ffffff", "#000000")).toBeCloseTo(21, 0);
-    });
-
-    it("returns 1 for same colors", () => {
-      expect(getContrastRatio("#808080", "#808080")).toBeCloseTo(1, 0);
-      expect(getContrastRatio("#ff0000", "#ff0000")).toBeCloseTo(1, 0);
-    });
-
-    it("returns symmetric results", () => {
-      const ratio1 = getContrastRatio("#ff0000", "#00ff00");
-      const ratio2 = getContrastRatio("#00ff00", "#ff0000");
-      expect(ratio1).toBeCloseTo(ratio2, 5);
-    });
-
-    it("returns expected values for known pairs", () => {
-      // Red on white should have moderate contrast
-      const redWhite = getContrastRatio("#ff0000", "#ffffff");
-      expect(redWhite).toBeGreaterThan(3);
-      expect(redWhite).toBeLessThan(5);
+      const result = cssFromUnsafe("rgba(255, 0, 0, 0.5)");
+      expect(result).toMatchInlineSnapshot(`"rgba(255, 0, 0, 0.5)"`);
     });
   });
 
@@ -184,124 +166,272 @@ describe("color-utils", () => {
     });
   });
 
-  describe("hsl", () => {
-    it("creates red at hue 0", () => {
-      expect(fromHSL(0, 1, 0.5)).toMatchInlineSnapshot(`"rgb(255,0,0)"`);
-    });
+  describe("fromLCH (OKLCH)", () => {
+    let oklchModule: typeof import("./color-utils");
 
-    it("creates green at hue 120", () => {
-      const color = fromHSL(120, 1, 0.5);
-      expect(color).toMatchInlineSnapshot(`"rgb(0,255,0)"`);
-    });
+    beforeAll(() => {
+      // Navigate so window.location.search includes ?oklch
+      window.history.pushState({}, "", "?oklch-defs");
 
-    it("creates blue at hue 240", () => {
-      const color = fromHSL(240, 1, 0.5);
-      expect(color).toMatchInlineSnapshot(`"rgb(0,0,255)"`);
+      // Re-import module so useOklch is true
+      jest.isolateModules(() => {
+        // @ts-expect-error jest provides require at runtime
+        oklchModule = require("./color-utils") as typeof import("./color-utils");
+      });
     });
 
-    it("creates white at lightness 1", () => {
-      const color = fromHSL(0, 1, 1);
-      expect(color).toMatchInlineSnapshot(`"rgb(255,255,255)"`);
+    afterAll(() => {
+      window.history.pushState({}, "", "/");
     });
 
-    it("creates black at lightness 0", () => {
-      const color = fromHSL(0, 1, 0);
-      expect(color).toMatchInlineSnapshot(`"rgb(0,0,0)"`);
-    });
-
-    it("creates gray at saturation 0", () => {
-      const color = fromHSL(0, 0, 0.5);
-      expect(color).toMatchInlineSnapshot(`"rgb(128,128,128)"`);
-    });
-  });
-
-  describe("fromLCH (OKLCH)", () => {
     it("creates color from OKLCH values", () => {
-      expect(fromOKLCH(0.592, 0.16, 264)).toMatchInlineSnapshot(`"rgb(76,120,220)"`);
+      expect(fromOKLCH(0.592, 0.16, 264)).toMatchInlineSnapshot(`"rgb(76, 120, 220)"`);
     });
 
     it("creates white at L=1 with zero chroma", () => {
-      expect(fromOKLCH(1, 0, 0)).toMatchInlineSnapshot(`"rgb(255,255,255)"`);
+      expect(fromOKLCH(1, 0, 0)).toMatchInlineSnapshot(`"rgb(255, 255, 255)"`);
     });
 
     it("creates black at L=0", () => {
-      expect(fromOKLCH(0, 0, 0)).toMatchInlineSnapshot(`"rgb(0,0,0)"`);
+      expect(fromOKLCH(0, 0, 0)).toMatchInlineSnapshot(`"rgb(0, 0, 0)"`);
     });
 
     it("creates gray at mid-lightness with zero chroma", () => {
-      expect(fromOKLCH(0.5, 0, 0)).toMatchInlineSnapshot(`"rgb(99,99,99)"`);
+      expect(fromOKLCH(0.5, 0, 0)).toMatchInlineSnapshot(`"rgb(99, 99, 99)"`);
     });
 
     it("creates saturated red at hue ~29", () => {
-      expect(fromOKLCH(0.628, 0.258, 29)).toMatchInlineSnapshot(`"rgb(255,0,3)"`);
+      expect(fromOKLCH(0.628, 0.258, 29)).toMatchInlineSnapshot(`"rgb(255, 0, 3)"`);
     });
 
     it("creates saturated blue at hue ~264", () => {
-      expect(fromOKLCH(0.452, 0.313, 264)).toMatchInlineSnapshot(`"rgb(0,1,255)"`);
+      expect(fromOKLCH(0.452, 0.313, 264)).toMatchInlineSnapshot(`"rgb(0, 1, 255)"`);
     });
 
     it("higher chroma produces more saturated colors", () => {
-      expect(fromOKLCH(0.6, 0.05, 264)).toMatchInlineSnapshot(`"rgb(113,128,159)"`);
-      expect(fromOKLCH(0.6, 0.2, 264)).toMatchInlineSnapshot(`"rgb(64,118,245)"`);
+      expect(fromOKLCH(0.6, 0.05, 264)).toMatchInlineSnapshot(`"rgb(113, 128, 159)"`);
+      expect(fromOKLCH(0.6, 0.2, 264)).toMatchInlineSnapshot(`"rgb(64, 118, 245)"`);
     });
 
     it("gamut maps out-of-range colors", () => {
-      expect(fromOKLCH(0.7, 0.4, 150)).toMatchInlineSnapshot(`"rgb(0,194,72)"`);
-      expect(fromOKLCH(0.8, 0.4, 150)).toMatchInlineSnapshot(`"rgb(0,231,90)"`);
-      expect(fromOKLCH(0.9, 0.4, 150)).toMatchInlineSnapshot(`"rgb(65,255,135)"`);
-      expect(fromOKLCH(1, 0.4, 150)).toMatchInlineSnapshot(`"rgb(255,255,255)"`);
+      expect(fromOKLCH(0.7, 0.4, 150)).toMatchInlineSnapshot(`"rgb(0, 194, 72)"`);
+      expect(fromOKLCH(0.8, 0.4, 150)).toMatchInlineSnapshot(`"rgb(0, 231, 90)"`);
+      expect(fromOKLCH(0.9, 0.4, 150)).toMatchInlineSnapshot(`"rgb(65, 255, 135)"`);
+      expect(fromOKLCH(1, 0.4, 150)).toMatchInlineSnapshot(`"rgb(255, 255, 255)"`);
+      expect(oklchModule.fromOKLCH(1, 0.4, 150)).toMatchInlineSnapshot(`"oklch(1 0.4 150)"`);
     });
   });
 
-  describe("getHsl", () => {
-    it("extracts HSL from red", () => {
-      const [h, s, l] = getHsl("#ff0000");
-      expect(h).toBeCloseTo(0, 0);
-      expect(s).toBeCloseTo(1, 2);
-      expect(l).toBeCloseTo(0.5, 2);
+  describe("produceColor", () => {
+    let oklchModule: typeof import("./color-utils");
+
+    beforeAll(() => {
+      // Navigate so window.location.search includes ?oklch
+      window.history.pushState({}, "", "?oklch-defs");
+
+      // Re-import module so useOklch is true
+      jest.isolateModules(() => {
+        // @ts-expect-error jest provides require at runtime
+        oklchModule = require("./color-utils") as typeof import("./color-utils");
+      });
     });
 
-    it("extracts HSL from green", () => {
-      const [h, s, l] = getHsl("#00ff00");
-      expect(h).toBeCloseTo(120, 0);
-      expect(s).toBeCloseTo(1, 2);
-      expect(l).toBeCloseTo(0.5, 2);
+    afterAll(() => {
+      window.history.pushState({}, "", "/");
     });
 
-    it("extracts HSL from blue", () => {
-      const [h, s, l] = getHsl("#0000ff");
-      expect(h).toBeCloseTo(240, 0);
-      expect(s).toBeCloseTo(1, 2);
-      expect(l).toBeCloseTo(0.5, 2);
+    const toOKLCH = (x: string) => oklchModule.produceColor(x, []);
+    it("outputs oklch format when OKLCH space is specified", () => {
+      expect(toOKLCH("#ff0000")).toMatchInlineSnapshot(
+        `"oklch(0.6279553639214311 0.2576833038053608 29.233880279627854)"`
+      );
+      expect(toOKLCH("rgb(0, 128, 255)")).toMatchInlineSnapshot(
+        `"oklch(0.6151653614766294 0.21081893200648957 256.09895972083694)"`
+      );
+      expect(toOKLCH("oklch(61.517% 0.21082 256.1)")).toMatchInlineSnapshot(`"oklch(0.61517 0.21082 256.1)"`);
+    });
+
+    it("parses display-p3 colors correctly", () => {
+      expect(toOKLCH("color(display-p3 0.992 0.992 0.978)")).toMatchInlineSnapshot(
+        `"oklch(0.9928464031174811 0.0051602645977199746 106.49321580372934)"`
+      );
+      expect(toOKLCH("color(display-p3 0.995 0.99 0.922)")).toMatchInlineSnapshot(
+        `"oklch(0.9884066405507254 0.02504787644348708 102.9151657650749)"`
+      );
+      expect(toOKLCH("color(display-p3 0.997 0.982 0.749)")).toMatchInlineSnapshot(
+        `"oklch(0.9740185549741557 0.08449100709025309 104.35896559356009)"`
+      );
     });
+  });
 
-    it("extracts HSL from white", () => {
-      const [, , l] = getHsl("#ffffff");
-      expect(l).toBeCloseTo(1, 2);
+  describe("darkenChroma (legacy Lab path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => produceColor(c, (co) => darkenChroma(co, 0.5)))).toMatchInlineSnapshot(`
+        [
+          "rgb(226, 56, 0)",
+          "rgb(42, 98, 187)",
+          "rgb(0, 164, 135)",
+          "rgb(223, 139, 14)",
+          "rgb(78, 39, 157)",
+          "rgb(0, 0, 0)",
+          "rgb(229, 229, 229)",
+        ]
+      `);
+    });
+
+    it("darken(1) is stronger than darken(0.5)", () => {
+      const light = produceColor("#4978D4", (c) => darkenChroma(c, 0.5));
+      const strong = produceColor("#4978D4", (c) => darkenChroma(c, 1));
+      expect(getLuminance(strong)).toBeLessThan(getLuminance(light));
     });
+  });
 
-    it("extracts HSL from black", () => {
-      const [, l] = getHsl("#000000");
-      expect(l).toBeCloseTo(0, 2);
+  describe("setLuminanceChroma (legacy binary-search path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => produceColor(c, (co) => setLuminanceChroma(co, 0.5)))).toMatchInlineSnapshot(`
+        [
+          "rgb(255, 166, 122)",
+          "rgb(165, 188, 234)",
+          "rgb(77, 208, 186)",
+          "rgb(251, 171, 65)",
+          "rgb(196, 180, 227)",
+          "rgb(188, 188, 188)",
+          "rgb(188, 188, 188)",
+        ]
+      `);
     });
+  });
 
-    it("returns 0 for undefined hue (grayscale)", () => {
-      const [h] = getHsl("#808080");
-      expect(h).toBe(0); // NaN converted to 0
+  describe("desaturateChroma (legacy LCH path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => produceColor(c, (co) => desaturateChroma(co, 0.8)))).toMatchInlineSnapshot(`
+        [
+          "rgb(242, 98, 36)",
+          "rgb(94, 120, 187)",
+          "rgb(93, 183, 161)",
+          "rgb(241, 167, 79)",
+          "rgb(102, 67, 162)",
+          "rgb(0, 0, 0)",
+          "rgb(255, 255, 255)",
+        ]
+      `);
     });
   });
 
-  describe("produceColor", () => {
-    it("outputs oklch format when OKLCH space is specified", () => {
-      expect(toOKLCH("#ff0000")).toMatchInlineSnapshot(`"oklch(62.796% 0.25768 29.234)"`);
-      expect(toOKLCH("rgb(0, 128, 255)")).toMatchInlineSnapshot(`"oklch(61.517% 0.21082 256.1)"`);
-      expect(toOKLCH("oklch(61.517% 0.21082 256.1)")).toMatchInlineSnapshot(`"oklch(61.517% 0.21082 256.1)"`);
+  describe("clampRgb (legacy naive-clamp path)", () => {
+    it("keeps in-gamut colors unchanged", () => {
+      const rgb = clampRgb(rgbFrom("#4978D4")!);
+      expect(rgb.r).toBeCloseTo(73 / 255, 2);
+      expect(rgb.g).toBeCloseTo(120 / 255, 2);
+      expect(rgb.b).toBeCloseTo(212 / 255, 2);
+    });
+
+    it("clamps out-of-gamut values", () => {
+      const oob = {mode: "rgb" as const, r: 1.2, g: -0.1, b: 0.5};
+      const clamped = clampRgb(oob);
+      expect(clamped.r).toBe(1);
+      expect(clamped.g).toBe(0);
+      expect(clamped.b).toBe(0.5);
+    });
+  });
+});
+
+describe("color-utils (oklch-math flag)", () => {
+  let oklchModule: typeof import("./color-utils");
+
+  beforeAll(() => {
+    // Navigate so window.location.search includes ?oklch
+    window.history.pushState({}, "", "?oklch-math");
+
+    // Re-import module so useOklch is true
+    jest.isolateModules(() => {
+      // @ts-expect-error jest provides require at runtime
+      oklchModule = require("./color-utils") as typeof import("./color-utils");
     });
+  });
+
+  afterAll(() => {
+    window.history.pushState({}, "", "/");
+  });
+
+  describe("darkenChroma (oklch path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => oklchModule.produceColor(c, (co) => oklchModule.darkenChroma(co, 0.5))))
+        .toMatchInlineSnapshot(`
+        [
+          "rgb(222, 49, 0)",
+          "rgb(48, 93, 182)",
+          "rgb(0, 160, 132)",
+          "rgb(220, 134, 0)",
+          "rgb(79, 30, 152)",
+          "rgb(0, 0, 0)",
+          "rgb(225, 225, 225)",
+        ]
+      `);
+    });
+
+    it.each(testColors)("produces perceptually similar results to Lab darken", (color) => {
+      const labResult = produceColor(color, (c) => darkenChroma(c, 0.5));
+      const oklchResult = oklchModule.produceColor(color, (c) => oklchModule.darkenChroma(c, 0.5));
+      expect(cie76(parseSafe(labResult), parseSafe(oklchResult))).toBeLessThan(25);
+    });
+  });
+
+  describe("setLuminanceChroma (oklch path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => oklchModule.produceColor(c, (co) => oklchModule.setLuminanceChroma(co, 0.5))))
+        .toMatchInlineSnapshot(`
+        [
+          "rgb(255, 152, 115)",
+          "rgb(144, 187, 255)",
+          "rgb(64, 215, 184)",
+          "rgb(254, 166, 51)",
+          "rgb(194, 169, 255)",
+          "rgb(188, 188, 188)",
+          "rgb(188, 188, 188)",
+        ]
+      `);
+    });
+
+    it("target 0.6 maps to cbrt(0.6) ≈ 0.843", () => {
+      const result = oklchModule.produceColor("#FF5400", (c) => oklchModule.setLuminanceChroma(c, 0.6));
+      expect(result).toMatchInlineSnapshot(`"rgb(255, 178, 149)"`);
+    });
+  });
+
+  describe("desaturateChroma (oklch path)", () => {
+    it("snapshot", () => {
+      expect(testColors.map((c) => oklchModule.produceColor(c, (co) => oklchModule.desaturateChroma(co, 0.8))))
+        .toMatchInlineSnapshot(`
+        [
+          "rgb(239, 102, 56)",
+          "rgb(87, 123, 190)",
+          "rgb(90, 182, 160)",
+          "rgb(236, 170, 95)",
+          "rgb(100, 72, 164)",
+          "rgb(0, 0, 0)",
+          "rgb(255, 255, 255)",
+        ]
+      `);
+    });
+  });
 
-    it("parses display-p3 colors correctly (P3 space removed for bundle size)", () => {
-      expect(toOKLCH("color(display-p3 0.992 0.992 0.978)")).toMatchInlineSnapshot(`"oklch(99.285% 0.00516 106.49)"`);
-      expect(toOKLCH("color(display-p3 0.995 0.99 0.922)")).toMatchInlineSnapshot(`"oklch(98.841% 0.02505 102.92)"`);
-      expect(toOKLCH("color(display-p3 0.997 0.982 0.749)")).toMatchInlineSnapshot(`"oklch(97.402% 0.08449 104.36)"`);
+  describe("clampRgb (oklch path uses clampChroma)", () => {
+    it("keeps in-gamut colors unchanged", () => {
+      const rgb = oklchModule.clampRgb(rgbFrom("#4978D4")!);
+      expect(rgb.r).toBeCloseTo(73 / 255, 2);
+      expect(rgb.g).toBeCloseTo(120 / 255, 2);
+      expect(rgb.b).toBeCloseTo(212 / 255, 2);
+    });
+
+    it("gamut maps out-of-range via chroma reduction", () => {
+      const oob = {mode: "rgb" as const, r: 1.2, g: -0.1, b: 0.5};
+      const clamped = oklchModule.clampRgb(oob);
+      expect(clamped.r).toBeGreaterThanOrEqual(0);
+      expect(clamped.r).toBeLessThanOrEqual(1);
+      expect(clamped.g).toBeGreaterThanOrEqual(0);
+      expect(clamped.b).toBeGreaterThanOrEqual(0);
+      expect(clamped.b).toBeLessThanOrEqual(1);
     });
   });
 });