toosoon-utils 4.2.2 → 4.3.0

package/lib/colors.d.ts

@@ -1,11 +1,11 @@
-import type { ColorRepresentation } from './types';
+import type { ColorHex, ColorRgb, ColorHsl, ColorHsb, ColorHcl, ColorLab, ColorRepresentation } from './types';
 /**
  * Normalize a color representation into RGB
  *
  * @param {ColorRepresentation} color Color representation
- * @returns {[number,number,number]} Normalized RGB color
+ * @returns {ColorRgb} Normalized RGB color
  */
-export declare function normalizeColor(color: ColorRepresentation): [number, number, number];
+export declare function normalizeColor(color: ColorRepresentation): ColorRgb;
 /**
  * Normalize an hexadecimal string
  *
@@ -15,28 +15,34 @@ export declare function normalizeColor(color: ColorRepresentation): [number, num
 export declare function normalizeHexString(hex: string): string;
 /**
  * Convert RGB to hexadecimal
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {number} Hexadecimal color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorRgb} rgb RGB color
+ * @returns {ColorHex} Hexadecimal color
  */
-export declare function rgbToHex([r, g, b]: [number, number, number]): number;
+export declare function rgbToHex([r, g, b]: ColorRgb): ColorHex;
 /**
  * Convert RGB to hexadecimal string
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorRgb} rgb RGB color
  * @returns {string} Hexadecimal string
  */
-export declare function rgbToHexString([r, g, b]: [number, number, number]): string;
+export declare function rgbToHexString([r, g, b]: ColorRgb): string;
 /**
  * Convert hexadecimal to RGB
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {number|string} hex Hexadecimal color
- * @returns {[number, number, number]} RGB color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorHex|string} hex Hexadecimal color
+ * @returns {ColorRgb} RGB color
  */
-export declare function hexToRgb(hex: number | string): [number, number, number];
+export declare function hexToRgb(hex: ColorHex | string): ColorRgb;
 /**
  * Lighten a color
  *
@@ -55,101 +61,176 @@ export declare function lighten(hex: string, amount?: number): string;
 export declare function darken(hex: string, amount?: number): string;
 /**
  * Normalize an HSL string
- * Note: hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *
+ * Note:
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
  * @param  {string} hsl HSL string (format: 'hsl(360, 100%, 100%)')
- * @returns {[number, number, number]} Normalized HSL color
+ * @returns {ColorHsl} Normalized HSL color
  */
-export declare function normalizeHslString(hsl: string): [number, number, number];
+export declare function normalizeHslString(hsl: string): ColorHsl;
 /**
  * Convert RGB to HSL
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HSL color
+ * @param  {ColorHgb} rgb RGB color
+ * @returns {ColorHsl} HSL color
  */
-export declare function rgbToHsl([r, g, b]: [number, number, number]): [number, number, number];
+export declare function rgbToHsl([r, g, b]: ColorRgb): ColorHsl;
 /**
  * Convert HSL to RGB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
- * @param  {[number, number, number]} hsl HSL color
- * @returns {[number, number, number]} RGB color
+ * @param  {ColorHsl} hsl HSL color
+ * @returns {ColorRgb} RGB color
  */
-export declare function hslToRgb([h, s, l]: [number, number, number]): [number, number, number];
+export declare function hslToRgb([h, s, l]: ColorHsl): ColorRgb;
 /**
  * Convert RGB to HSB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsb values are contained in the intervals H: [0, 360], S: [0, 1], B: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSB values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Brightness: [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HSB color
+ * @param  {ColorRgb} rgb RGB color
+ * @returns {ColorHsb} HSB color
  */
-export declare function rgbToHsb([r, g, b]: [number, number, number]): [number, number, number];
+export declare function rgbToHsb([r, g, b]: ColorRgb): ColorHsb;
 /**
  * Convert HSB to RGB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsb values are contained in the intervals H: [0, 360], S: [0, 1], B: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSB values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Brightness: [0, 1]
  *
- * @param  {[number, number, number]} hsb HSB color
- * @returns {[number, number, number]} RGB color
+ * @param  {ColorHsb} hsb HSB color
+ * @returns {ColorRgb} RGB color
  */
-export declare function hsbToRgb([h, s, b]: [number, number, number]): [number, number, number];
+export declare function hsbToRgb([h, s, b]: ColorHsb): ColorRgb;
 /**
- * Convert LAB to HCL
- * -> http://www.brucelindbloom.com/index.html?Eqn_Lab_to_LCH.html
+ * Convert L*a*b* to HCL
+ *   -> http://www.brucelindbloom.com/index.html?Eqn_Lab_to_LCH.html
  *
- * @param {[number, number, number]} lab LAB color
- * @returns {[number, number, number]} HCL color
+ * Notes:
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Lightness: [0, 100]
+ *
+ * @param {ColorLab} lab LAB color
+ * @returns {ColorHcl} HCL color
  */
-export declare function labToHcl([l, a, b]: [number, number, number]): [number, number, number];
+export declare function labToHcl([l, a, b]: ColorLab): ColorHcl;
 /**
- * Convert HCL to LAB
- * -> http://www.brucelindbloom.com/index.html?Eqn_LCH_to_Lab.html
+ * Convert HCL to L*a*b*
+ *   -> http://www.brucelindbloom.com/index.html?Eqn_LCH_to_Lab.html
  *
- * @param {[number, number, number]} hcl HCL color
- * @returns {[number, number, number]} LAB color space
+ * Notes:
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Lightness: [0, 100]
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
+ *
+ * @param {ColorHcl} hcl HCL color
+ * @returns {ColorLab} LAB color
  */
-export declare function hclToLab([h, c, l]: [number, number, number]): [number, number, number];
+export declare function hclToLab([h, c, l]: ColorHcl): ColorLab;
 /**
- * Converts LAB to RGB
+ * Convert L*a*b* to RGB
+ *
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
  *
- * @param {[number, number, number]} lab LAB color
- * @returns {[number, number, number]} RGB color
+ * @param {ColorLab} lab L*a*b* color
+ * @returns {ColorRgb} RGB color
  */
-export declare function labToRgb([l, a, b]: [number, number, number]): [number, number, number];
+export declare function labToRgb([l, a, b]: ColorLab): ColorRgb;
 /**
- * Converts RGB to LAB
+ * Convert RGB to L*a*b*
+ *
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
  *
- * @param {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} LAB color
+ * @param {ColorRgb} rgb RGB color
+ * @returns {ColorLab} L*a*b* color
  */
-export declare function rgbToLab([r, g, b]: [number, number, number]): [number, number, number];
+export declare function rgbToLab([r, g, b]: ColorRgb): ColorLab;
 /**
- * Get the delta from two LAB colors
+ * Get the delta from two L*a*b* colors
  *
- * @param {[number, number, number]} labA First LAB color
- * @param {[number, number, number]} labB Second LAB color
- * @returns {number} Delta
+ * 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} lab1 First L*a*b* color
+ * @param {ColorLab} lab2 Second L*a*b* color
+ * @returns {number}
  */
-export declare function deltaE(labA: [number, number, number], labB: [number, number, number]): number;
+export declare function deltaE(lab1: ColorLab, lab2: ColorLab): number;
 /**
  * Convert RGB to HCL
  *
- * @param {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HCL color
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Luminance: [0, 100]
+ *
+ * @param {ColorRgb} rgb RGB color
+ * @returns {ColorHcl} HCL color
  */
-export declare function rgbToHcl([r, g, b]: [number, number, number]): [number, number, number];
+export declare function rgbToHcl([r, g, b]: ColorRgb): ColorHcl;
 /**
  * Converts HCL to RGB
  *
- * @param {[number, number, number]} hcl RGB color
- * @returns {[number, number, number]} RGB color
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Luminance: [0, 100]
+ *
+ * @param {ColorHcl} hcl RGB color
+ * @returns {ColorRgb} RGB color
  */
-export declare function hclToRgb([h, c, l]: [number, number, number]): [number, number, number];
+export declare function hclToRgb([h, c, l]: ColorHcl): ColorRgb;

package/lib/colors.js

@@ -5,7 +5,7 @@ import { clamp } from './maths';
  * Normalize a color representation into RGB
  *
  * @param {ColorRepresentation} color Color representation
- * @returns {[number,number,number]} Normalized RGB color
+ * @returns {ColorRgb} Normalized RGB color
  */
 export function normalizeColor(color) {
     if (typeof color === 'string') {
@@ -47,19 +47,23 @@ export function normalizeHexString(hex) {
 }
 /**
  * Convert RGB to hexadecimal
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {number} Hexadecimal color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorRgb} rgb RGB color
+ * @returns {ColorHex} Hexadecimal color
  */
 export function rgbToHex([r, g, b]) {
     return ((r * 255) << 16) ^ ((g * 255) << 8) ^ ((b * 255) << 0);
 }
 /**
  * Convert RGB to hexadecimal string
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorRgb} rgb RGB color
  * @returns {string} Hexadecimal string
  */
 export function rgbToHexString([r, g, b]) {
@@ -71,10 +75,12 @@ export function rgbToHexString([r, g, b]) {
 }
 /**
  * Convert hexadecimal to RGB
- * Note: rgb values are contained in the interval [0, 1]
  *
- * @param  {number|string} hex Hexadecimal color
- * @returns {[number, number, number]} RGB color
+ * Note:
+ *  - RGB values are contained in the interval [0, 1]
+ *
+ * @param  {ColorHex|string} hex Hexadecimal color
+ * @returns {ColorRgb} RGB color
  */
 export function hexToRgb(hex) {
     if (typeof hex === 'number') {
@@ -127,10 +133,15 @@ export function darken(hex, amount = 0) {
 // ***************************************************
 /**
  * Normalize an HSL string
- * Note: hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *
+ * Note:
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
  * @param  {string} hsl HSL string (format: 'hsl(360, 100%, 100%)')
- * @returns {[number, number, number]} Normalized HSL color
+ * @returns {ColorHsl} Normalized HSL color
  */
 export function normalizeHslString(hsl) {
     const [h, s, l] = hsl.match(/\d+/g)?.map(Number) ?? [0, 0, 0];
@@ -138,12 +149,16 @@ export function normalizeHslString(hsl) {
 }
 /**
  * Convert RGB to HSL
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HSL color
+ * @param  {ColorHgb} rgb RGB color
+ * @returns {ColorHsl} HSL color
  */
 export function rgbToHsl([r, g, b]) {
     const l = Math.max(r, g, b);
@@ -157,12 +172,16 @@ export function rgbToHsl([r, g, b]) {
 }
 /**
  * Convert HSL to RGB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsl values are contained in the intervals H: [0, 360], S: [0, 1], L: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSL values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Lightness:  [0, 1]
  *
- * @param  {[number, number, number]} hsl HSL color
- * @returns {[number, number, number]} RGB color
+ * @param  {ColorHsl} hsl HSL color
+ * @returns {ColorRgb} RGB color
  */
 export function hslToRgb([h, s, l]) {
     const a = s * Math.min(l, 1 - l);
@@ -175,12 +194,16 @@ export function hslToRgb([h, s, l]) {
 // ***************************************************
 /**
  * Convert RGB to HSB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsb values are contained in the intervals H: [0, 360], S: [0, 1], B: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSB values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Brightness: [0, 1]
  *
- * @param  {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HSB color
+ * @param  {ColorRgb} rgb RGB color
+ * @returns {ColorHsb} HSB color
  */
 export function rgbToHsb([r, g, b]) {
     const max = Math.max(r, g, b);
@@ -191,27 +214,41 @@ export function rgbToHsb([r, g, b]) {
 }
 /**
  * Convert HSB to RGB
+ *
  * Notes:
- *  - rgb values are contained in the interval [0, 1]
- *  - hsb values are contained in the intervals H: [0, 360], S: [0, 1], B: [0, 1]
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HSB values are contained in the intervals:
+ *     - Hue:        [0, 360]
+ *     - Saturation: [0, 1]
+ *     - Brightness: [0, 1]
  *
- * @param  {[number, number, number]} hsb HSB color
- * @returns {[number, number, number]} RGB color
+ * @param  {ColorHsb} hsb HSB color
+ * @returns {ColorRgb} RGB color
  */
 export function hsbToRgb([h, s, b]) {
     const k = (v) => (v + h / 60) % 6;
     const f = (v) => b * (1 - s * Math.max(0, Math.min(k(v), 4 - k(v), 1)));
     return [f(5), f(3), f(1)];
 }
-// *********************************************
-// LAB & Hue-Chroma-Luminance (HCL) color spaces
-// *********************************************
+// ************************************************
+// L*a*b* & Hue-Chroma-Luminance (HCL) color spaces
+// ************************************************
 /**
- * Convert LAB to HCL
- * -> http://www.brucelindbloom.com/index.html?Eqn_Lab_to_LCH.html
+ * Convert L*a*b* to HCL
+ *   -> http://www.brucelindbloom.com/index.html?Eqn_Lab_to_LCH.html
+ *
+ * Notes:
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Lightness: [0, 100]
  *
- * @param {[number, number, number]} lab LAB color
- * @returns {[number, number, number]} HCL color
+ * @param {ColorLab} lab LAB color
+ * @returns {ColorHcl} HCL color
  */
 export function labToHcl([l, a, b]) {
     const c = Math.sqrt(a * a + b * b);
@@ -219,11 +256,21 @@ export function labToHcl([l, a, b]) {
     return [h, c, l];
 }
 /**
- * Convert HCL to LAB
- * -> http://www.brucelindbloom.com/index.html?Eqn_LCH_to_Lab.html
+ * Convert HCL to L*a*b*
+ *   -> http://www.brucelindbloom.com/index.html?Eqn_LCH_to_Lab.html
  *
- * @param {[number, number, number]} hcl HCL color
- * @returns {[number, number, number]} LAB color space
+ * Notes:
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Lightness: [0, 100]
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
+ *
+ * @param {ColorHcl} hcl HCL color
+ * @returns {ColorLab} LAB color
  */
 export function hclToLab([h, c, l]) {
     const a = c * Math.cos(toRadians(h));
@@ -231,11 +278,16 @@ export function hclToLab([h, c, l]) {
     return [l, a, b];
 }
 /**
- * Convert A and B of LAB to Hue of LCH
- * -> https://stackoverflow.com/questions/53733379/conversion-of-cielab-to-cielchab-not-yielding-correct-result
+ * Convert a and b of L*a*b* to Hue of HCL
+ *   -> https://stackoverflow.com/questions/53733379/conversion-of-cielab-to-cielchab-not-yielding-correct-result
+ *
+ * Note:
+ *   - ab values are contained in the intervals:
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
  *
- * @param {number} a A value of LAB color
- * @param {number} b B value of LAB color
+ * @param {number} a
+ * @param {number} b
  * @returns {number} Hue value
  */
 function abToHue(a, b) {
@@ -264,17 +316,24 @@ function abToHue(a, b) {
     return toDegrees(Math.atan(b / a)) + xBias;
 }
 // ******************************************
-// LAB & RGB color spaces
+// L*a*b* & RGB color spaces
 // ******************************************
 const f1 = (v) => (v * v * v > 0.008856 ? v * v * v : (v - 16 / 116) / 7.787);
 const f2 = (v) => (v > 0.0031308 ? 1.055 * Math.pow(v, 1 / 2.4) - 0.055 : 12.92 * v);
 const f3 = (v) => (v > 0.04045 ? Math.pow((v + 0.055) / 1.055, 2.4) : v / 12.92);
 const f4 = (v) => (v > 0.008856 ? Math.pow(v, 1 / 3) : 7.787 * v + 16 / 116);
 /**
- * Converts LAB to RGB
+ * Convert L*a*b* to RGB
  *
- * @param {[number, number, number]} lab LAB color
- * @returns {[number, number, number]} RGB color
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - 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 {ColorRgb} RGB color
  */
 export function labToRgb([l, a, b]) {
     let y = (l + 16) / 116;
@@ -290,10 +349,17 @@ export function labToRgb([l, a, b]) {
     ];
 }
 /**
- * Converts RGB to LAB
+ * Convert RGB to L*a*b*
+ *
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
  *
- * @param {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} LAB color
+ * @param {ColorRgb} rgb RGB color
+ * @returns {ColorLab} L*a*b* color
  */
 export function rgbToLab([r, g, b]) {
     r = f3(r);
@@ -305,18 +371,24 @@ export function rgbToLab([r, g, b]) {
     return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
 }
 /**
- * Get the delta from two LAB colors
+ * Get the delta from two L*a*b* colors
+ *
+ * Note:
+ *   - L*a*b* values are contained in the intervals:
+ *     - Lightness:        [0 à 100]
+ *     - a (green, red):   [~-128, ~+128]
+ *     - b (blue, yellow): [~-128, ~+128]
  *
- * @param {[number, number, number]} labA First LAB color
- * @param {[number, number, number]} labB Second LAB color
- * @returns {number} Delta
+ * @param {ColorLab} lab1 First L*a*b* color
+ * @param {ColorLab} lab2 Second L*a*b* color
+ * @returns {number}
  */
-export function deltaE(labA, labB) {
-    const deltaL = labA[0] - labB[0];
-    const deltaA = labA[1] - labB[1];
-    const deltaB = labA[2] - labB[2];
-    const c1 = Math.sqrt(labA[1] * labA[1] + labA[2] * labA[2]);
-    const c2 = Math.sqrt(labB[1] * labB[1] + labB[2] * labB[2]);
+export function deltaE(lab1, lab2) {
+    const deltaL = lab1[0] - lab2[0];
+    const deltaA = lab1[1] - lab2[1];
+    const deltaB = lab1[2] - lab2[2];
+    const c1 = Math.sqrt(lab1[1] * lab1[1] + lab1[2] * lab1[2]);
+    const c2 = Math.sqrt(lab2[1] * lab2[1] + lab2[2] * lab2[2]);
     const deltaC = c1 - c2;
     let deltaH = deltaA * deltaA + deltaB * deltaB - deltaC * deltaC;
     deltaH = deltaH < 0 ? 0 : Math.sqrt(deltaH);
@@ -334,8 +406,15 @@ export function deltaE(labA, labB) {
 /**
  * Convert RGB to HCL
  *
- * @param {[number, number, number]} rgb RGB color
- * @returns {[number, number, number]} HCL color
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Luminance: [0, 100]
+ *
+ * @param {ColorRgb} rgb RGB color
+ * @returns {ColorHcl} HCL color
  */
 export function rgbToHcl([r, g, b]) {
     return labToHcl(rgbToLab([r, g, b]));
@@ -343,8 +422,15 @@ export function rgbToHcl([r, g, b]) {
 /**
  * Converts HCL to RGB
  *
- * @param {[number, number, number]} hcl RGB color
- * @returns {[number, number, number]} RGB color
+ * Notes:
+ *   - RGB values are contained in the interval [0, 1]
+ *   - HCL values are contained in the intervals:
+ *     - Hue:       [0, 360]
+ *     - Chroma:    [0, ~150]
+ *     - Luminance: [0, 100]
+ *
+ * @param {ColorHcl} hcl RGB color
+ * @returns {ColorRgb} RGB color
  */
 export function hclToRgb([h, c, l]) {
     return labToRgb(hclToLab([h, c, l]));

package/lib/constants.js

@@ -14,7 +14,7 @@ export const QUARTER_PI = PI / 4;
 // Colors
 // *********************
 // X11 colors
-// -> https://www.w3.org/TR/css-color-3/#svg-color
+//   -> https://www.w3.org/TR/css-color-3/#svg-color
 export const W3CX11 = {
     aliceblue: 0xf0f8ff,
     antiquewhite: 0xfaebd7,

package/lib/dom.d.ts

@@ -1,7 +1,7 @@
 /**
  * Find the closest parent that matches a selector
  *
- * @param {Element|null}     element  Target element
+ * @param {Element|null}   element  Target element
  * @param {Element|string} selector Selector or parent to match
  * @returns {Element|null}
  */

package/lib/dom.js

@@ -2,7 +2,7 @@ const DOCUMENT_NODE_TYPE = 9;
 /**
  * Find the closest parent that matches a selector
  *
- * @param {Element|null}     element  Target element
+ * @param {Element|null}   element  Target element
  * @param {Element|string} selector Selector or parent to match
  * @returns {Element|null}
  */