toosoon-utils 4.2.3 → 4.3.0

package/lib/extras/colors/ColorPalette.js

@@ -0,0 +1,124 @@
+import Color from './Color';
+import ColorScale from './ColorScale';
+/**
+ * Utility class for generating color palettes
+ *
+ * @exports
+ * @class ColorPalette
+ */
+export default class ColorPalette {
+    isColorPalette = true;
+    type = 'ColorPalette';
+    _base = new Color();
+    /**
+     * Object containing this color palette color scales
+     */
+    scales = {};
+    /**
+     * Object containing this color palette generators
+     */
+    generators = {};
+    /**
+     * @param {Color|ColorRepresentation} color Base color
+     * @param {object} generators Object containing generators
+     */
+    constructor(color, generators = {}) {
+        this.base = color;
+        this.generators = generators;
+        this.update();
+    }
+    /**
+     * Pick an interpolated color from one of this color palette color scale
+     *
+     * @param {string} key Name of the color scale
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Color} Interpolated color
+     */
+    getColor(key, t) {
+        return this.scales[key]?.getColor(t) ?? this.base.clone();
+    }
+    /**
+     * Add a given generator to this color palette
+     *
+     * @param {string} key Name of the generator
+     * @param {ColorPaletteGenerator} generator Generator to add
+     */
+    subscribe(key, generator) {
+        this.generators[key] = generator;
+        this.scales[key] = this.generate(generator);
+    }
+    /**
+     * Generate a color scale
+     *
+     * @param {ColorPaletteGenerator} 				 generator 							 Generator interface to use for generation
+     * @param {ColorInterpolation} 						 generator.interpolation Type of interpolation used for generation
+     * @param {number} 												 generator.length 			 Amount of colors to generate
+     * @param {Color} 												 [generator.target] 		 Target color to interpolate towards
+     * @param {ColorScaleProcessingParameters} [generator.processing]  Target color processing parameters, for processing the target color before generation
+     * @param {object} 												 [generator.params]  		 Interpolation parameters
+     * @returns {ColorScale} Generated color scale
+     */
+    generate(generator) {
+        const { interpolation, length, target: color, processing, params } = generator;
+        const base = ColorScale.processColor(this.base.clone(), params?.preprocessing);
+        const target = ColorScale.processColor(color ?? this.base.clone(), processing);
+        return new ColorScale().generate(interpolation, length, base, target, params).process(params?.postprocessing);
+    }
+    /**
+     * Update this color palette color scales
+     */
+    update() {
+        for (let key in this.generators) {
+            const generator = this.generators[key];
+            this.scales[key] = this.generate(generator);
+        }
+    }
+    /**
+     * Base color of this color palette
+     */
+    set base(color) {
+        this._base.set(color);
+        this.update();
+    }
+    get base() {
+        return this._base;
+    }
+}
+/** Generators */
+const length = 9;
+export const LightScaleGenerator = {
+    interpolation: 'hsl',
+    length,
+    processing: { hsl: { lightness: 1 - 1 / length } },
+    params: {
+        preprocessing: { hsl: { lightness: 0.5 } },
+        postprocessing: {}
+    }
+};
+export const DarkScaleGenerator = {
+    interpolation: 'hsl',
+    length,
+    processing: { hsl: { lightness: 1 / length } },
+    params: {
+        preprocessing: { hsl: { lightness: 0.5 } },
+        postprocessing: {}
+    }
+};
+export const SequentialLightGenerator = {
+    interpolation: 'sequential',
+    length,
+    processing: { hcl: { luminance: 100 } },
+    params: {
+        preprocessing: { hcl: { luminance: 50 } },
+        postprocessing: {}
+    }
+};
+export const SequentialDarkGenerator = {
+    interpolation: 'sequential',
+    length,
+    processing: { hcl: { luminance: 0 } },
+    params: {
+        preprocessing: { hcl: { luminance: 50 } },
+        postprocessing: {}
+    }
+};

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

@@ -0,0 +1,257 @@
+import type { Range } from '../../types';
+import Color, { type ColorInterpolationsParameters, type ColorInterpolation } from './Color';
+/**
+ * Processing parameter used to modify an input value into a target.
+ *   - If the target is a number, the input will be set to its value
+ *   - If the target is an array of numbers, the input will be clamped inside the range [min, max]
+ *   - If the target is undefined, the input will stay the same
+ */
+export type ColorScaleProcessingTarget = number | Range | undefined;
+/**
+ * Parameters used for color scale processing
+ */
+export type ColorScaleProcessingParameters = {
+    /**
+     * Processing HSL modifiers
+     */
+    hsl?: {
+        hue?: ColorScaleProcessingTarget;
+        saturation?: ColorScaleProcessingTarget;
+        lightness?: ColorScaleProcessingTarget;
+    };
+    /**
+     * Processing HSB modifiers
+     */
+    hsb?: {
+        hue?: ColorScaleProcessingTarget;
+        saturation?: ColorScaleProcessingTarget;
+        brightness?: ColorScaleProcessingTarget;
+    };
+    /**
+     * Processing HCL modifiers
+     */
+    hcl?: {
+        hue?: ColorScaleProcessingTarget;
+        chroma?: ColorScaleProcessingTarget;
+        luminance?: ColorScaleProcessingTarget;
+    };
+};
+/**
+ * Utility class for generating and processing color scales
+ *
+ * @exports
+ * @class ColorScale
+ */
+export default class ColorScale {
+    readonly isColorScale = true;
+    readonly type: string;
+    /**
+     * Array of colors composing this color scale
+     */
+    colors: Color[];
+    [Symbol.iterator](): Iterator<Color>;
+    /**
+     * Pick an interpolated color from this color scale
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Color} Interpolated color on this scale
+     */
+    getColor(t: number): Color;
+    /**
+     * Set this color scale colors to an array of interpolated colors
+     *
+     * @param {ColorInterpolation} interpolation Type of interpolation used for generation
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params] Interpolation parameters
+     * @returns {this}
+     */
+    generate<I extends ColorInterpolation>(interpolation: I, length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters[I]): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors in the RGB color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]       Interpolation parameters
+     * @param {number} [params.power] Interpolation exponent
+     * @returns {this}
+     */
+    generateRgb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['rgb']): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors in the HSL color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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}
+     */
+    generateHsl(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsl']): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors in the HSB color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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}
+     */
+    generateHsb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsb']): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors following HCL Qualitative color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]         Interpolation parameters
+     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {this}
+     */
+    generateQualitative(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['qualitative']): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors following HCL Sequential color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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}
+     */
+    generateSequential(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['sequential']): this;
+    /**
+     * Set this color scale colors to an array of interpolated colors following HCL Diverging color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : ([c, l])
+     * @returns {this}
+     */
+    generateDiverging(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['diverging']): this;
+    /**
+     * Process all colors composing this scale
+     *
+     * @param {ColorScaleProcessingParameters} [params] Processing parameters
+     * @returns {this}
+     */
+    process(params?: ColorScaleProcessingParameters): this;
+    /**
+     * Amount of colors composing this color scale
+     */
+    get length(): number;
+    /**
+     * Generate an array of interpolated colors
+     *
+     * @param {ColorInterpolation} interpolation Type of interpolation used for generation
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params] Interpolation parameters
+     * @returns {Color[]} Generated color scale
+     */
+    static generate<I extends ColorInterpolation>(interpolation: I, length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters[I]): Color[];
+    /**
+     * Generate an array of interpolated colors in the RGB color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]       Interpolation parameters
+     * @param {number} [params.power] Interpolation exponent
+     * @returns {Color[]} Generated RGB color scale
+     */
+    static generateRgb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['rgb']): Color[];
+    /**
+     * Generate an array of interpolated colors in the HSL color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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 {Color[]} Generated HSL color scale
+     */
+    static generateHsl(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsl']): Color[];
+    /**
+     * Generate an array of interpolated colors in the HSB color space
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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 {Color[]} Generated HSB color scale
+     */
+    static generateHsb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsb']): Color[];
+    /**
+     * Generate an array of interpolated colors following HCL Qualitative color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]         Interpolation parameters
+     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
+     * @returns {Color[]} Generated qualitative color scale
+     */
+    static generateQualitative(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['qualitative']): Color[];
+    /**
+     * Generate an array of interpolated colors following HCL Sequential color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @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 {Color[]} Generated sequential color scale
+     */
+    static generateSequential(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['sequential']): Color[];
+    /**
+     * Generate an array of interpolated colors following HCL Diverging color palettes algorithm
+     *
+     * @param {number} length Amount of colors to generate
+     * @param {Color} color1 Start color
+     * @param {Color} color2 End color
+     * @param {object} [params]                Interpolation parameters
+     * @param {number|number[]} [params.power] Interpolation exponent(s) : ([c, l])
+     * @returns {Color[]} Generated diverging color scale
+     */
+    static generateDiverging(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['diverging']): Color[];
+    /**
+     * Process a given value
+     *
+     * @param {number} value Value to process
+     * @param {ColorScaleProcessingTarget} [target] Processing target
+     * @returns {number} Processed value
+     */
+    static processValue(value: number, target: ColorScaleProcessingTarget): number;
+    /**
+     * Process a given color
+     *
+     * @param {Color} color Color to process
+     * @param {ColorScaleProcessingParameters} [params] Processing parameters
+     * @returns {Color} Processed color
+     */
+    static processColor(color: Color, params?: ColorScaleProcessingParameters): Color;
+    /**
+     * Process all colors composing a given scale
+     *
+     * @param {ColorScale} scale Color scale to process
+     * @param {ColorScaleProcessingParameters} [params] Processing parameters
+     * @returns {ColorScale} Processed color scale
+     */
+    static process(scale: ColorScale, params?: ColorScaleProcessingParameters): ColorScale;
+    private static _getInterpolateFunction;
+}