toosoon-utils
Version:
Utility functions & classes
407 lines (406 loc) • 15.8 kB
TypeScript
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;
}