🤖 Merge PR DefinitelyTyped#69771 culori: Add XYB colorspace, missing …

…fns, and culori/css + culori/all entry points by @drwpow

types/culori/all/index.d.ts

@@ -0,0 +1,31 @@
+export {
+    a98,
+    cubehelix,
+    dlab,
+    dlch,
+    hsi,
+    hsl,
+    hsv,
+    hwb,
+    jab,
+    jch,
+    lab,
+    lab65,
+    lch,
+    lch65,
+    lchuv,
+    lrgb,
+    luv,
+    okhsl,
+    okhsv,
+    oklab,
+    oklch,
+    p3,
+    prophoto,
+    rec2020,
+    rgb,
+    xyb,
+    xyz50,
+    xyz65,
+    yiq,
+} from "../index";

types/culori/css/index.d.ts

@@ -0,0 +1,19 @@
+export {
+    a98,
+    hsl,
+    hsv,
+    hwb,
+    lab,
+    lab65,
+    lch,
+    lch65,
+    lrgb,
+    oklab,
+    oklch,
+    p3,
+    prophoto,
+    rec2020,
+    rgb,
+    xyz50,
+    xyz65,
+} from "../index";

types/culori/fn/index.d.ts

@@ -70,8 +70,7 @@ export {
     interpolatorSplineMonotoneClosed,
 } from "../src/interpolate/splineMonotone";
 
-export { clampChroma, clampRgb } from "../src/clamp";
-export { default as displayable } from "../src/displayable";
+export { clampChroma, clampGamut, clampRgb, displayable, inGamut, toGamut } from "../src/clamp";
 export { default as lerp } from "../src/interpolate/lerp";
 export { getMode, removeParser, useMode, useParser } from "../src/modes";
 export { default as nearest } from "../src/nearest";

types/culori/index.d.ts

@@ -25,6 +25,7 @@ import modeP3 from "./src/p3/definition";
 import modeProphoto from "./src/prophoto/definition";
 import modeRec2020 from "./src/rec2020/definition";
 import modeRgb from "./src/rgb/definition";
+import modeXyb from "./src/xyb/definition";
 import modeXyz50 from "./src/xyz50/definition";
 import modeXyz65 from "./src/xyz65/definition";
 import modeYiq from "./src/yiq/definition";
@@ -72,8 +73,7 @@ export {
     interpolatorSplineMonotoneClosed,
 } from "./src/interpolate/splineMonotone";
 
-export { clampChroma, clampRgb } from "./src/clamp";
-export { default as displayable } from "./src/displayable";
+export { clampChroma, clampGamut, clampRgb, displayable, inGamut, toGamut } from "./src/clamp";
 export { default as lerp } from "./src/interpolate/lerp";
 export { getMode, removeParser, useMode, useParser } from "./src/modes";
 export { default as nearest } from "./src/nearest";
@@ -172,6 +172,8 @@ export { default as convertProphotoToXyz50 } from "./src/prophoto/convertProphot
 export { default as convertXyz50ToProphoto } from "./src/prophoto/convertXyz50ToProphoto";
 export { default as convertRec2020ToXyz65 } from "./src/rec2020/convertRec2020ToXyz65";
 export { default as convertXyz65ToRec2020 } from "./src/rec2020/convertXyz65ToRec2020";
+export { default as convertRgbToXyb } from "./src/xyb/convertRgbToXyb";
+export { default as convertXybToRgb } from "./src/xyb/convertXybToRgb";
 export { default as convertRgbToXyz50 } from "./src/xyz50/convertRgbToXyz50";
 export { default as convertXyz50ToRgb } from "./src/xyz50/convertXyz50ToRgb";
 export { default as convertRgbToXyz65 } from "./src/xyz65/convertRgbToXyz65";
@@ -207,6 +209,7 @@ export {
     modeProphoto,
     modeRec2020,
     modeRgb,
+    modeXyb,
     modeXyz50,
     modeXyz65,
     modeYiq,
@@ -238,6 +241,7 @@ export const prophoto: ConvertFn<"prophoto">;
 export const rec2020: ConvertFn<"rec2020">;
 // tslint:disable-next-line:use-default-type-parameter
 export const rgb: ConvertFn<"rgb">;
+export const xyb: ConvertFn<"xyb">;
 export const xyz50: ConvertFn<"xyz50">;
 export const xyz65: ConvertFn<"xyz65">;
 export const yiq: ConvertFn<"yiq">;
@@ -270,6 +274,7 @@ export type { P3 } from "./src/p3/types";
 export type { Prophoto } from "./src/prophoto/types";
 export type { Rec2020 } from "./src/rec2020/types";
 export type { Rgb } from "./src/rgb/types";
+export type { Xyb } from "./src/xyb/types";
 export type { Xyz50 } from "./src/xyz50/types";
 export type { Xyz65 } from "./src/xyz65/types";
 export type { Yiq } from "./src/yiq/types";

types/culori/package.json

@@ -12,6 +12,10 @@
         {
             "name": "Bijela Gora",
             "githubUsername": "bijela-gora"
+        },
+        {
+            "name": "Drew Powrs",
+            "githubUsername": "drwpow"
         }
     ]
 }

types/culori/src/clamp.d.ts

@@ -1,7 +1,84 @@
-import { Color, GamutMode, Mode } from "./common";
+import { Color, FindColorByMode, GamutMode, Mode } from "./common";
 
+/**
+ * Returns whether the color is in the sRGB gamut.
+ */
+export function displayable(color: Color | string): boolean;
+
+/**
+ * Given a color space `mode`, returns a function
+ * with which to check whether a color is
+ * in that color space's gamut.
+ */
+export function inGamut(mode?: Mode): (color: Color | string) => boolean;
+
+/*
+ * Obtain a color that's in the sRGB gamut
+ * by converting it to sRGB and clipping the channel values
+ * so that they're within the [0, 1] range.
+ *
+ * The result is returned in the color's original color space.
+ */
 export function clampRgb(color: string): Color | undefined;
 export function clampRgb<C extends Color>(color: C): C;
 
-export function clampChroma(color: string, mode?: Mode, rgbGamut?: GamutMode): Color | undefined;
+/**
+ * Given the `mode` color space, returns a function
+ * with which to obtain a color that's in gamut for
+ * the `mode` color space by clipping the channel values
+ * so that they fit in their respective ranges.
+ *
+ * It's similar to `clampRgb`, but works for any
+ * bounded color space (RGB or not) for which
+ * any combination of in-range channel values
+ * produces an in-gamut color.
+ */
+export function clampGamut<M extends Mode = "rgb">(mode?: M): (color: Color | string) => FindColorByMode<M> | undefined;
+
+/**
+ * Obtain a color that’s in a RGB gamut (by default sRGB)
+ * by first converting it to `mode` and then finding
+ * the greatest chroma value that fits the gamut.
+ *
+ * By default, the CIELCh color space is used,
+ * but any color that has a chroma component will do.
+ *
+ * The result is returned in the color's original color space.
+ */
+export function clampChroma(
+    color: string,
+    mode?: Mode,
+    rgbGamut?: GamutMode,
+): Color | undefined;
 export function clampChroma<C extends Color>(color: C, mode?: Mode, rgbGamut?: GamutMode): C;
+
+/*
+ * Obtain a color that's in the `dest` gamut,
+ * by first converting it to the `mode` color space
+ * and then finding the largest chroma that's in gamut,
+ * similar to `clampChroma`.
+ *
+ * The color returned is in the `dest` color space.
+ *
+ * To address the shortcomings of `clampChroma`, which can
+ * sometimes produce colors more desaturated than necessary,
+ * the test used in the binary search is replaced with
+ * "is color is roughly in gamut", by comparing the candidate
+ * to the clipped version (obtained with `clampGamut`).
+ * The test passes if the colors are not too dissimilar,
+ * judged by the `delta` color difference function
+ * and an associated `jnd` just-noticeable difference value.
+ *
+ * The default arguments for this function correspond to the
+ * gamut mapping algorithm defined in CSS Color Level 4:
+ * https://drafts.csswg.org/css-color/#css-gamut-mapping
+ *
+ * To disable the “roughly in gamut” part, pass either
+ * `null` for the `delta` parameter, or zero for `jnd`.
+ */
+export function toGamut<M extends Mode>(
+    dest: M,
+    mode: Mode,
+    delta?: number | null,
+    jnd?: number,
+): (color: string | Color) => FindColorByMode<M>;

types/culori/src/common.d.ts

@@ -23,6 +23,7 @@ import { P3 } from "./p3/types";
 import { Prophoto } from "./prophoto/types";
 import { Rec2020 } from "./rec2020/types";
 import { Rgb } from "./rgb/types";
+import { Xyb } from "./xyb/types";
 import { Xyz50 } from "./xyz50/types";
 import { Xyz65 } from "./xyz65/types";
 import { Yiq } from "./yiq/types";
@@ -53,6 +54,7 @@ export type Color =
     | Prophoto
     | Rec2020
     | Rgb
+    | Xyb
     | Xyz50
     | Xyz65
     | Yiq;

types/culori/src/xyb/constants.d.ts

@@ -0,0 +1,2 @@
+export const bias: number;
+export const bias_cbrt: number;

types/culori/src/xyb/convertRgbToXyb.d.ts

@@ -0,0 +1,6 @@
+import { Rgb } from "../rgb/types";
+import { Xyb } from "./types";
+
+declare function convertRgbToXyb(rgb: Omit<Rgb, "mode">): Xyb;
+
+export default convertRgbToXyb;

types/culori/src/xyb/convertXybToRgb.d.ts

@@ -0,0 +1,6 @@
+import { Rgb } from "../rgb/types";
+import { Xyb } from "./types";
+
+declare function convertXybToRgb(color: Omit<Xyb, "mode">): Rgb;
+
+export default convertXybToRgb;

types/culori/src/xyb/definition.d.ts

@@ -0,0 +1,35 @@
+import { fixupAlpha } from "../fixup/alpha";
+import { interpolatorLinear } from "../interpolate/linear";
+import convertRgbToXyb from "./convertRgbToXyb";
+import convertXybToRgb from "./convertXybToRgb";
+
+declare const definition: {
+    mode: "xyb";
+    parse: ["xyz-d50", "--xyz-d50"];
+    serialize: "xyz-d50";
+
+    toMode: {
+        rgb: typeof convertXybToRgb;
+    };
+
+    fromMode: {
+        rgb: typeof convertRgbToXyb;
+    };
+
+    channels: ["x", "y", "z", "alpha"];
+
+    ranges: {
+        x: [0, 0.964];
+        y: [0, 0.999];
+        z: [0, 0.825];
+    };
+
+    interpolate: {
+        x: typeof interpolatorLinear;
+        y: typeof interpolatorLinear;
+        b: typeof interpolatorLinear;
+        alpha: { use: typeof interpolatorLinear; fixup: typeof fixupAlpha };
+    };
+};
+
+export default definition;

types/culori/src/xyb/types.d.ts

@@ -0,0 +1,7 @@
+export interface Xyb {
+    mode: "xyb";
+    x: number;
+    y: number;
+    b: number;
+    alpha?: number;
+}

types/culori/test/clamp.test.ts

@@ -1,4 +1,4 @@
-import { clampChroma, clampRgb, Lch } from "culori/fn";
+import { clampChroma, clampGamut, clampRgb, displayable, inGamut, Lch, toGamut } from "culori/fn";
 
 const lch1 = "lch(50% 50 90)";
 const lch2: Lch = { mode: "lch", l: 50, c: 50, h: 90, alpha: 1 };
@@ -14,3 +14,23 @@ clampChroma(lch1, mode); // $ExpectType Color | undefined
 clampChroma(lch2, mode); // $ExpectType Lch
 clampChroma(lch1, mode, gamutMode); // $ExpectType Color | undefined
 clampChroma(lch2, mode, gamutMode); // $ExpectType Lch
+
+clampGamut()(lch2); // $ExpectType Rgb | undefined
+clampGamut(mode)(lch1); // $ExpectType Lch | undefined
+clampGamut(mode)(lch2); // $ExpectType Lch | undefined
+
+displayable(lch1); // $ExpectType boolean
+displayable(lch2); // $ExpectType boolean
+
+inGamut(mode)(lch1); // $ExpectType boolean
+inGamut(mode)(lch2); // $ExpectType boolean
+
+toGamut("p3", mode)(lch1); // $ExpectType P3
+toGamut("p3", mode)(lch2); // $ExpectType P3
+toGamut("rgb", mode)(lch2); // $ExpectType Rgb
+toGamut("lch", mode)(lch2); // $ExpectType Lch
+toGamut("p3", mode, 0)(lch1); // $ExpectType P3
+toGamut("p3", mode, 0)(lch2); // $ExpectType P3
+toGamut("p3", mode, null)(lch2); // $ExpectType P3
+toGamut("p3", mode, 0, 0.02)(lch1); // $ExpectType P3
+toGamut("p3", mode, 0, 0.02)(lch2); // $ExpectType P3

types/culori/tsconfig.json

@@ -13,6 +13,9 @@
         "forceConsistentCasingInFileNames": true
     },
     "files": [
+        "all/index.d.ts",
+        "css/index.d.ts",
+        "fn/index.d.ts",
         "index.d.ts",
         "test/average.test.ts",
         "test/blend.test.ts",