toosoon-utils 4.2.3 → 4.3.0

package/lib/extras/colors/Color.d.ts

@@ -0,0 +1,406 @@
+import type { ColorName, ColorHex, ColorRgb, ColorHsl, ColorHsb, ColorHcl, ColorLab, ColorRepresentation } from '../../types';
+/**
+ * Parameters used for color interpolation
+ */
+export type ColorInterpolationsParameters = {
+    rgb: Parameters<typeof Color.lerpRgb>[3];
+    hsl: Parameters<typeof Color.lerpHsl>[3];
+    hsb: Parameters<typeof Color.lerpHsb>[3];
+    qualitative: Parameters<typeof Color.interpolateQualitative>[3];
+    sequential: Parameters<typeof Color.interpolateSequential>[3];
+    diverging: Parameters<typeof Color.interpolateDiverging>[3];
+};
+/**
+ * Type of interpolation
+ */
+export type ColorInterpolation = keyof ColorInterpolationsParameters;
+/**
+ * Type of hue interpolation
+ */
+export type HueInterpolationMode = 'direct' | 'shortest' | 'longest';
+/**
+ * Utility class for manipulating colors
+ *
+ * @exports
+ * @class Color
+ */
+export default class Color {
+    readonly isColor = true;
+    readonly type: string;
+    /**
+     * Red value of this color in the RGB color space
+     */
+    r: number;
+    /**
+     * Green value of this color in the RGB color space
+     */
+    g: number;
+    /**
+     * Blue value of this color in the RGB color space
+     */
+    b: number;
+    [Symbol.iterator](): Iterator<number>;
+    /**
+     * @param {ColorRepresentation} [color=0x000000] Color representation of this color
+     */
+    constructor(color?: ColorRepresentation);
+    /**
+     * Set this color RGB values
+     *
+     * @param {Color|ColorRepresentation} color Color to set
+     * @returns {this}
+     */
+    set(color: Color | ColorRepresentation): this;
+    /**
+     * Set this color values from a given color name
+     *
+     * @param {ColorName} colorName Color name of the color to set
+     * @returns {this}
+     */
+    setColorName(colorName: ColorName): this;
+    /**
+     * Set this color values from a given RGB color
+     *
+     * Note:
+     *   - RGB values are contained in the interval [0, 1]
+     *
+     * @param {ColorRgb} rgb RGB color
+     * @returns {this}
+     */
+    setRgb([r, g, b]: ColorRgb): this;
+    /**
+     * Set this color values from a given hexadecimal color
+     *
+     * @param {ColorHex} hex Hexadecimal color
+     * @returns {this}
+     */
+    setHex(hex: ColorHex): this;
+    /**
+     * Set this color values from a given HSL color
+     *
+     * Note:
+     *   - HSL values are contained in the intervals:
+     *     - Hue:        [0, 360]
+     *     - Saturation: [0, 1]
+     *     - Lightness:  [0, 1]
+     *
+     * @param {ColorHsl|string} hsl HSL color
+     * @returns {this}
+     */
+    setHsl(hsl: ColorHsl | string): this;
+    /**
+     * Set this color values from a given HSB color
+     *
+     * Note:
+     *   - HSB values are contained in the intervals:
+     *     - Hue:        [0, 360]
+     *     - Saturation: [0, 1]
+     *     - Brightness: [0, 1]
+     *
+     * @param {ColorHsb} hsb HSB color
+     * @returns {this}
+     */
+    setHsb(hsb: ColorHsb): this;
+    /**
+     * Set this color values from a given L*a*b* color
+     *
+     * Note:
+     *   - L*a*b* values are contained in the intervals:
+     *     - Lightness:        [0 à 100]
+     *     - a (green, red):   [~-128, ~+128]
+     *     - b (blue, yellow): [~-128, ~+128]
+     *
+     * @param {ColorLab} lab L*a*b* color
+     * @returns {this}
+     */
+    setLab(lab: ColorLab): this;
+    /**
+     * Set this color values from a given HCL color
+     *
+     * Note:
+     *   - HCL values are contained in the intervals:
+     *     - Hue:       [0, 360]
+     *     - Chroma:    [0, ~150]
+     *     - Lightness: [0, 100]
+     *
+     * @param {ColorHcl} hcl HCL color
+     * @returns {this}
+     */
+    setHcl(hcl: ColorHcl): this;
+    /**
+     * Linearly interpolate this color values to given color values
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {Color|ColorRgb} color Color to interpolate values towards
+     * @returns {this}
+     */
+    lerp(t: number, [r, g, b]: Color | ColorRgb): this;
+    /**
+     * Linearly interpolate this color RGB values towards given RGB values
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorRgb} rgb RGB values to interpolate towards
+     * @param {object} [params]       Interpolation parameters
+     * @param {number} [params.power] Interpolation exponent
+     * @returns {this}
+     */
+    lerpRgb(t: number, rgb: ColorRgb, params?: Parameters<typeof Color.lerpRgb>[3]): this;
+    /**
+     * Linearly interpolate this color HSL values towards given HSL values
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHsl} hsl HSL values to interpolate towards
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, l]
+     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {this}
+     */
+    lerpHsl(t: number, hsl: ColorHsl, params?: Parameters<typeof Color.lerpHsl>[3]): this;
+    /**
+     * Linearly interpolate this color HSB values towards given HSB values
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHsb} hsb HSB values to interpolate towards
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, b]
+     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {this}
+     */
+    lerpHsb(t: number, hsb: ColorHsb, params?: Parameters<typeof Color.lerpHsb>[3]): this;
+    /**
+     * Interpolate this color HCL values towards given HCL values following HCL Qualitative color palettes algorithm
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl HCL values to interpolate towards
+     * @param {object} [params]         Interpolation parameters
+     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {this}
+     */
+    interpolateQualitative(t: number, hcl: ColorHcl, params?: Parameters<typeof Color.interpolateQualitative>[3]): this;
+    /**
+     * Interpolate this color HCL values towards given HCL values following HCL Sequential color palettes algorithm
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl HCL values to interpolate towards
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : [c, l]
+     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @param {number} [params.chromaMax]      Maximum chroma value
+     * @returns {this}
+     */
+    interpolateSequential(t: number, hcl: ColorHcl, params?: Parameters<typeof Color.interpolateSequential>[3]): this;
+    /**
+     * Interpolate this color HCL values towards given HCL values following HCL Diverging color palettes algorithm
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl HCL values to interpolate towards
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : ([c, l])
+     * @returns {this}
+     */
+    interpolateDiverging(t: number, hcl: ColorHcl, params?: Parameters<typeof Color.interpolateDiverging>[3]): this;
+    /**
+     * Check if this color is equal with a given color
+     *
+     * @param {Color|ColorRgb} color Color to check
+     * @returns {boolean} True if this color is equal with the given color, false otherwise
+     */
+    equals(color: Color | ColorRgb): boolean;
+    /**
+     * Return this color RGB values into an array
+     *
+     * @returns {ColorRgb}
+     */
+    toArray(): ColorRgb;
+    /**
+     * Set this color RGB values from a given array
+     *
+     * @param {number[]} values Values to set
+     * @returns {this}
+     */
+    fromArray([r, g, b]: number[]): this;
+    /**
+     * Copy the RGB values of a given color to this color
+     *
+     * @param {Color|ColorRgb} color Color to copy values from
+     * @returns {this}
+     */
+    copy([r, g, b]: Color | ColorRgb): this;
+    /**
+     * Create a new color with copied RGB values from this color
+     *
+     * @returns {Color}
+     */
+    clone(): Color;
+    /**
+     * RGB values of this color
+     */
+    set rgb(rgb: ColorRgb);
+    get rgb(): ColorRgb;
+    /**
+     * Hexadecimal value of this color
+     */
+    set hex(hex: ColorHex);
+    get hex(): number;
+    /**
+     * Hexadecimal string representing this color
+     */
+    get hexString(): string;
+    /**
+     * HSL values of this color
+     */
+    set hsl(hsl: ColorHsl);
+    get hsl(): ColorHsl;
+    /**
+     * HSL string representing this color (format: 'hsl(360, 100%, 100%)')
+     */
+    get hslString(): string;
+    /**
+     * HSB values of this color
+     */
+    set hsb(hsb: ColorHsb);
+    get hsb(): ColorHsb;
+    /**
+     * L*a*b* values of this color
+     */
+    set lab(lab: ColorLab);
+    get lab(): ColorLab;
+    /**
+     * HCL values of this color
+     */
+    set hcl(hcl: ColorHcl);
+    get hcl(): ColorHcl;
+    /**
+     * Linearly interpolate a color between two colors in the RGB color space
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {Color|ColorRgb} rgb1 Start color
+     * @param {Color|ColorRgb} rgb2 End color
+     * @param {object} [params]         Interpolation parameters
+     * @param {number} [params.power=1] Interpolation exponent
+     * @returns {ColorRgb} Interpolated RGB color
+     */
+    static lerpRgb(t: number, [r1, g1, b1]: Color | ColorRgb, [r2, g2, b2]: Color | ColorRgb, { power }?: {
+        power?: number;
+    }): ColorRgb;
+    /**
+     * Linearly interpolate a color between two colors in the HSL color space
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHsl} hsl1 Start color
+     * @param {ColorHsl} hsl2 End color
+     * @param {object} [params]                  Interpolation parameters
+     * @param {number|number[]} [params.power=1] Interpolation exponent(s) : [h, s, l]
+     * @param {string} [params.hueMode]          Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {ColorHsl} Interpolated HSL color
+     */
+    static lerpHsl(t: number, [h1, s1, l1]: ColorHsl, [h2, s2, l2]: ColorHsl, { power, hueMode }?: {
+        power?: number | [number, number, number];
+        hueMode?: HueInterpolationMode;
+    }): ColorHsl;
+    /**
+     * Linearly interpolate a color between two colors in the HSB color space
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHsb} hsb1 Start color
+     * @param {ColorHsb} hsb2 End color
+     * @param {object} [params]                  Interpolation parameters
+     * @param {number|number[]} [params.power=1] Interpolation exponent(s) : [h, s, b]
+     * @param {string} [params.hueMode]          Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {ColorHsb} Interpolated HSB color
+     */
+    static lerpHsb(t: number, [h1, s1, b1]: ColorHsb, [h2, s2, b2]: ColorHsb, { power, hueMode }?: {
+        power?: number | [number, number, number];
+        hueMode?: HueInterpolationMode;
+    }): ColorHsb;
+    /**
+     * Interpolate a color between 2 colors following HCL Qualitative color palettes algorithm
+     *   -> https://colorspace.r-forge.r-project.org/articles/hcl_palettes.html#qualitative-palettes
+     *
+     * Qualitative color palettes:
+     *   - Hue:       Linear
+     *   - Chroma:    Constant
+     *   - Luminance: Constant
+     *
+     *   Designed for coding categorical information,
+     *   where no particular ordering of categories is available
+     *   and every color should receive the same perceptual weight.
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl1 Start color
+     * @param {ColorHcl} hcl2 End color
+     * @param {object} [params]         Interpolation parameters
+     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {ColorHcl} Interpolated HCL color
+     */
+    static interpolateQualitative(t: number, [h1, c1, l1]: ColorHcl, [h2]: ColorHcl, { hueMode }?: {
+        hueMode?: HueInterpolationMode;
+    }): ColorHcl;
+    /**
+     * Interpolate a color between 2 colors following HCL Sequential color palettes algorithm
+     *   -> https://colorspace.r-forge.r-project.org/articles/hcl_palettes.html#sequential-palettes-single-hue
+     *   -> https://colorspace.r-forge.r-project.org/articles/hcl_palettes.html#sequential-palettes-multi-hue
+     *
+     * Sequential color palettes:
+     *   - Hue:       Constant | Linear
+     *   - Chroma:    Linear (+power) | Triangular (+power)
+     *   - Luminance: Linear (+power)
+     *
+     *   Designed for coding ordered/numeric information,
+     *   going from high to low (or vice versa).
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl1 Start color
+     * @param {ColorHcl} hcl2 End color
+     * @param {object} [params]                  Interpolation parameters
+     * @param {number|number[]} [params.power=1] Interpolation exponent(s) : [c, l]
+     * @param {string} [params.hueMode]          Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @param {number} [params.chromaMax]        Maximum chroma value
+     * @returns {ColorHcl} Interpolated HCL color
+     */
+    static interpolateSequential(t: number, [h1, c1, l1]: ColorHcl, [h2, c2, l2]: ColorHcl, { power, hueMode, chromaMax }?: {
+        power?: number | [number, number];
+        hueMode?: HueInterpolationMode;
+        chromaMax?: number;
+    }): ColorHcl;
+    /**
+     * Interpolate a color between 2 colors following HCL Diverging color palettes algorithm
+     *   -> https://colorspace.r-forge.r-project.org/articles/hcl_palettes.html#diverging-palettes
+     *
+     * Diverging color palettes:
+     *   - Hue:       Constants (x2)
+     *   - Chroma:    Linear (+power) | Triangular (+power)
+     *   - Luminance: Linear (+power)
+     *
+     *   Designed for coding ordered/numeric information around a central neutral value,
+     *   where colors diverge from neutral to two extremes.
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {ColorHcl} hcl1 Start color
+     * @param {ColorHcl} hcl2 End color
+     * @param {object} [params]                  Interpolation parameters
+     * @param {number|number[]} [params.power=1] Interpolation exponent(s) : ([c, l])
+     * @returns {ColorHcl} Interpolated HCL color
+     */
+    static interpolateDiverging(t: number, [h1, c1, l1]: ColorHcl, [h2, c2, l2]: ColorHcl, { power }?: {
+        power?: number | [number, number];
+    }): ColorHcl;
+    /**
+     * Interpolate a hue between two hue angles
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @param {number} h1 Start hue angle (in degrees)
+     * @param {number} h2 End hue angle (in degrees)
+     * @param {string} [mode='direct'] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {number} Interpolated hue
+     */
+    static lerpHue(t: number, h1: number, h2: number, mode?: HueInterpolationMode): number;
+    /**
+     * Check if two colors are equal to each other
+     *
+     * @param {Color|ColorRgb} color1 First color
+     * @param {Color|ColorRgb} color2 Second color
+     * @returns {boolean} True if the given colors are equal, false otherwise
+     */
+    static equals([r1, g1, b1]: Color | ColorRgb, [r2, g2, b2]: Color | ColorRgb): boolean;
+}