@versatiles/style 5.6.0 → 5.8.0

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@versatiles/style",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "description": "Generate StyleJSON for MapLibre",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=20.0.0 <24.0.0"
+    }
+  },
   "scripts": {
     "check": "npm run lint && npm run build && npm run test ",
     "build": "rm -rf release; npm run build-browser && npm run build-node && npm run build-styles && npm run build-sprites && npm run doc",
-    "build-browser": "rollup --configPlugin '@rollup/plugin-typescript={sourceMap:false}' -c --environment BUILD:browser && $(cd release/versatiles-style; tar -cf - versatiles-style.* | gzip -9 > ../versatiles-style.tar.gz)",
-    "build-node": "rm -rf dist && rollup --configPlugin '@rollup/plugin-typescript={sourceMap:false}' -c --environment BUILD:node && chmod +x dist/index.js && rm -r dist/declaration",
+    "build-browser": "rollup -c --environment BUILD:browser && $(cd release/versatiles-style; tar -cf - versatiles-style.* | gzip -9 > ../versatiles-style.tar.gz)",
+    "build-node": "rm -rf dist && rollup -c --environment BUILD:node && chmod +x dist/index.js && rm -r dist/declaration",
     "build-styles": "tsx scripts/build-styles.ts",
     "build-sprites": "tsx scripts/build-sprites.ts",
     "dev": "tsx scripts/dev.ts",
@@ -20,8 +26,8 @@
     "prepack": "npm run build",
     "release": "vrt release-npm",
     "test": "npm run test-typescript",
-    "test-coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
-    "test-typescript": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test-coverage": "vitest run --coverage",
+    "test-typescript": "vitest run",
     "upgrade": "vrt deps-upgrade"
   },
   "repository": {
@@ -32,44 +38,40 @@
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "brace-expansion": "^4.0.0"
+    "brace-expansion": "^4.0.1"
   },
   "files": [
     "dist/*",
     "src/*"
   ],
   "devDependencies": {
-    "@maplibre/maplibre-gl-native": "^6.0.0",
-    "@maplibre/maplibre-gl-style-spec": "^23.1.0",
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@maplibre/maplibre-gl-native": "^6.2.0",
+    "@maplibre/maplibre-gl-style-spec": "^24.3.1",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.2",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@types/bin-pack": "^1.0.3",
     "@types/brace-expansion": "^1.1.2",
-    "@types/inquirer": "^9.0.7",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.13.10",
-    "@types/tar-stream": "^3.1.3",
-    "@typescript-eslint/eslint-plugin": "^8.26.1",
-    "@typescript-eslint/parser": "^8.26.1",
-    "@versatiles/release-tool": "^2.4.1",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^24.10.1",
+    "@types/tar-stream": "^3.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "@versatiles/release-tool": "^2.4.5",
+    "@vitest/coverage-v8": "^4.0.10",
     "bin-pack": "^1.0.2",
-    "esbuild": "^0.25.1",
-    "eslint": "^9.22.0",
-    "inquirer": "^12.4.3",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "jest-ts-webcompat-resolver": "^1.0.0",
-    "rollup": "^4.35.0",
-    "rollup-plugin-dts": "^6.1.1",
-    "rollup-plugin-sourcemaps2": "^0.5.0",
-    "sharp": "^0.33.5",
+    "esbuild": "^0.27.0",
+    "eslint": "^9.39.1",
+    "inquirer": "^13.0.1",
+    "rollup": "^4.53.3",
+    "rollup-plugin-dts": "^6.2.3",
+    "rollup-plugin-sourcemaps2": "^0.5.4",
+    "sharp": "^0.34.5",
     "tar-stream": "^3.1.7",
-    "ts-jest": "^29.2.6",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.26.1"
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0",
+    "vitest": "^4.0.10"
   }
 }

package/src/color/abstract.ts

@@ -1,87 +1,202 @@
 import type { HSL } from './hsl.js';
 import type { HSV } from './hsv.js';
-import { RandomColorOptions } from './random.js';
 import type { RGB } from './rgb.js';
 
+/**
+ * The abstract `Color` class provides a blueprint for color manipulation and conversion.
+ * It includes methods for converting between different color models ({@link HSL}, {@link HSV}, {@link RGB}),
+ * as well as various color transformations such as inversion, rotation, saturation, and blending.
+ * 
+ * @abstract
+ */
+/**
+ * Abstract class representing a color.
+ */
 export abstract class Color {
+	/**
+	 * Parses a color from a string or another Color instance.
+	 * @param input - The input color as a string or Color instance.
+	 * @returns The parsed Color instance.
+	 */
 	static parse: (input: Color | string) => Color;
+
+	/**
+	 * The HSL color model.
+	 */
 	static HSL: typeof HSL;
+
+	/**
+	 * The HSV color model.
+	 */
 	static HSV: typeof HSV;
+
+	/**
+	 * The RGB color model.
+	 */
 	static RGB: typeof RGB;
-	static random: (options?: RandomColorOptions) => HSV;
+
+	/**
+	 * Creates a clone of the current color instance.
+	 * @returns A new Color instance that is a clone of the current instance.
+	 */
 	abstract clone(): Color;
 
+	/**
+	 * Converts the color to a hexadecimal string.
+	 * @returns The hexadecimal representation of the color.
+	 */
 	asHex(): string {
-		return this.toRGB().asHex();
+		return this.asRGB().asHex();
 	}
 
+	/**
+	 * Converts the color to a string representation.
+	 * @returns The string representation of the color.
+	 */
 	abstract asString(): string;
+
+	/**
+	 * Rounds the color values.
+	 * @returns A new Color instance with rounded values.
+	 */
 	abstract round(): Color;
+
+	/**
+	 * Converts the color to an array of numbers.
+	 * @returns An array representing the color.
+	 */
 	abstract asArray(): number[];
 
+	/**
+	 * Converts the color to the HSL color model.
+	 * @returns The HSL representation of the color.
+	 */
 	abstract asHSL(): HSL;
-	abstract asHSV(): HSV;
-	abstract asRGB(): RGB;
-
-	toHSL(): HSL {
-		return this.asHSL();
-	}
 
-	toHSV(): HSV {
-		return this.asHSV();
-	}
+	/**
+	 * Converts the color to the HSV color model.
+	 * @returns The HSV representation of the color.
+	 */
+	abstract asHSV(): HSV;
 
-	toRGB(): RGB {
-		return this.asRGB();
-	}
+	/**
+	 * Converts the color to the RGB color model.
+	 * @returns The RGB representation of the color.
+	 */
+	abstract asRGB(): RGB;
 
+	/**
+	 * Inverts the luminosity of the color.
+	 * @returns A new HSL color with inverted luminosity.
+	 */
 	invertLuminosity(): HSL {
-		return this.toHSL().invertLuminosity();
+		return this.asHSL().invertLuminosity();
 	}
 
+	/**
+	 * Rotates the hue of the color by a given offset.
+	 * @param offset - The amount to rotate the hue.
+	 * @returns A new HSL color with the hue rotated.
+	 */
 	rotateHue(offset: number): HSL {
-		return this.toHSL().rotateHue(offset);
+		return this.asHSL().rotateHue(offset);
 	}
 
+	/**
+	 * Saturates the color by a given ratio.
+	 * @param ratio - The ratio to saturate the color.
+	 * @returns A new HSL color with increased saturation.
+	 */
 	saturate(ratio: number): HSL {
-		return this.toHSL().saturate(ratio);
+		return this.asHSL().saturate(ratio);
 	}
 
+	/**
+	 * Applies gamma correction to the color.
+	 * @param value - The gamma correction value.
+	 * @returns A new RGB color with gamma correction applied.
+	 */
 	gamma(value: number): RGB {
-		return this.toRGB().gamma(value);
+		return this.asRGB().gamma(value);
 	}
 
+	/**
+	 * Inverts the color.
+	 * @returns A new RGB color with inverted values.
+	 */
 	invert(): RGB {
-		return this.toRGB().invert();
+		return this.asRGB().invert();
 	}
 
+	/**
+	 * Adjusts the contrast of the color.
+	 * @param value - The contrast adjustment value.
+	 * @returns A new RGB color with adjusted contrast.
+	 */
 	contrast(value: number): RGB {
-		return this.toRGB().contrast(value);
+		return this.asRGB().contrast(value);
 	}
 
+	/**
+	 * Adjusts the brightness of the color.
+	 * @param value - The brightness adjustment value.
+	 * @returns A new RGB color with adjusted brightness.
+	 */
 	brightness(value: number): RGB {
-		return this.toRGB().brightness(value);
+		return this.asRGB().brightness(value);
 	}
 
+	/**
+	 * Lightens the color by a given value.
+	 * @param value - The amount to lighten the color.
+	 * @returns A new RGB color that is lightened.
+	 */
 	lighten(value: number): RGB {
-		return this.toRGB().lighten(value);
+		return this.asRGB().lighten(value);
 	}
 
+	/**
+	 * Darkens the color by a given value.
+	 * @param value - The amount to darken the color.
+	 * @returns A new RGB color that is darkened.
+	 */
 	darken(value: number): RGB {
-		return this.toRGB().darken(value);
+		return this.asRGB().darken(value);
 	}
 
+	/**
+	 * Tints the color by blending it with another color.
+	 * @param value - The blend ratio.
+	 * @param tintColor - The color to blend with.
+	 * @returns A new RGB color that is tinted.
+	 */
 	tint(value: number, tintColor: Color): RGB {
-		return this.toRGB().tint(value, tintColor);
+		return this.asRGB().tint(value, tintColor);
 	}
 
+	/**
+	 * Blends the color with another color.
+	 * @param value - The blend ratio.
+	 * @param blendColor - The color to blend with.
+	 * @returns A new RGB color that is blended.
+	 */
 	blend(value: number, blendColor: Color): RGB {
-		return this.toRGB().blend(value, blendColor);
+		return this.asRGB().blend(value, blendColor);
 	}
 
+	/**
+	 * Sets the hue of the color.
+	 * @param value - The new hue value.
+	 * @returns A new HSV color with the hue set.
+	 */
 	setHue(value: number): HSV {
-		return this.toHSV().setHue(value);
+		return this.asHSV().setHue(value);
 	}
 
+	/**
+	 * Fades the color by a given value.
+	 * @param value - The fade value.
+	 * @returns A new Color instance that is faded.
+	 */
 	abstract fade(value: number): Color;
 }

package/src/color/hsl.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it, beforeEach } from 'vitest';
 import { HSL } from './hsl.js';
 import { HSV } from './hsv.js';
 import { RGB } from './rgb.js';
@@ -6,23 +7,23 @@ describe('HSL Class', () => {
 
 	describe('constructor', () => {
 
-		test('should initialize small HSL values correctly', () => {
+		it('should initialize small HSL values correctly', () => {
 			const color = new HSL(10, 20, 30, 0.4);
 			expect(color.asArray()).toStrictEqual([10, 20, 30, 0.4]);
 		});
 
-		test('should initialize big HSL values correctly', () => {
+		it('should initialize big HSL values correctly', () => {
 			const color = new HSL(400, 120, 120, 2);
 			expect(color.asArray()).toStrictEqual([40, 100, 100, 1]);
 		});
 
-		test('should initialize small HSL values correctly', () => {
+		it('should initialize small HSL values correctly', () => {
 			const color = new HSL(-60, -10, -10, -1);
 			expect(color.asArray()).toStrictEqual([300, 0, 0, 0]);
 		});
 	})
 
-	test('clone should return a new HSL instance with identical values', () => {
+	it('clone should return a new HSL instance with identical values', () => {
 		const color = new HSL(120, 50, 50, 0.5);
 		const clone = color.clone();
 		expect(clone).toBeInstanceOf(HSL);
@@ -32,7 +33,7 @@ describe('HSL Class', () => {
 
 	describe('conversion', () => {
 
-		test('asString should return correct HSL and HSLA strings', () => {
+		it('asString should return correct HSL and HSLA strings', () => {
 			const color1 = new HSL(120, 50, 50);
 			expect(color1.asString()).toBe('hsl(120,50%,50%)');
 
@@ -40,13 +41,13 @@ describe('HSL Class', () => {
 			expect(color2.asString()).toBe('hsla(120,50%,50%,0.5)');
 		});
 
-		test('asHSL and toHSL should return the same instance', () => {
+		it('asHSL and toHSL should return the same instance', () => {
 			const color = new HSL(120, 50, 50);
 			expect(color.asHSL()).toStrictEqual(color);
 			expect(color.toHSL()).toStrictEqual(color);
 		});
 
-		test('asHSV should correctly convert HSL to HSV', () => {
+		it('asHSV should correctly convert HSL to HSV', () => {
 			function check(input: [number, number, number], output: [number, number, number]) {
 				const hsl = new HSL(...input);
 				const hsv = hsl.asHSV();
@@ -66,7 +67,7 @@ describe('HSL Class', () => {
 			check([18, 100, 100], [18, 0, 100]);
 		});
 
-		test('asRGB should correctly convert HSL to RGB', () => {
+		it('asRGB should correctly convert HSL to RGB', () => {
 			function check(input: [number, number, number], output: [number, number, number]) {
 				const hsl = new HSL(...input)
 				const rgb = hsl.asRGB();
@@ -90,7 +91,7 @@ describe('HSL Class', () => {
 
 	describe('should parse valid HSL and HSLA strings', () => {
 		function check(str: string, result: number[]) {
-			test(`parse "${str}"`, () => {
+			it(`parse "${str}"`, () => {
 				const color = HSL.parse(str);
 				expect(color).toBeInstanceOf(HSL);
 				expect(color.asArray()).toStrictEqual(result);
@@ -101,7 +102,7 @@ describe('HSL Class', () => {
 		check('hsla(240,100%,50%,0.75)', [240, 100, 50, 0.75]);
 		check('hsl(400,50%,50%)', [40, 50, 50, 1]);
 
-		test('parse should throw an error for invalid strings', () => {
+		it('parse should throw an error for invalid strings', () => {
 			expect(() => HSL.parse('invalid')).toThrow('Invalid HSL color string');
 		});
 	});
@@ -110,11 +111,11 @@ describe('HSL Class', () => {
 		let color: HSL;
 		beforeEach(() => color = new HSL(120, 50, 50, 0.8));
 
-		test('inverts luminosity correctly', () => {
+		it('inverts luminosity correctly', () => {
 			expect(color.invertLuminosity().asArray()).toStrictEqual([120, 50, 50, 0.8]); // Luminosity inverted to 50%
 		});
 
-		test('handles edge cases for luminosity inversion', () => {
+		it('handles edge cases for luminosity inversion', () => {
 			const black = new HSL(0, 0, 0, 1);
 			expect(black.invertLuminosity().asArray()).toStrictEqual([0, 0, 100, 1]); // Black becomes white
 
@@ -127,15 +128,15 @@ describe('HSL Class', () => {
 		let color: HSL;
 		beforeEach(() => color = new HSL(120, 50, 50, 0.8));
 
-		test('rotates hue correctly within the range of 0-360', () => {
+		it('rotates hue correctly within the range of 0-360', () => {
 			expect(color.rotateHue(180).asArray()).toStrictEqual([300, 50, 50, 0.8]); // Hue rotated by 180 degrees
 		});
 
-		test('handles negative rotation correctly', () => {
+		it('handles negative rotation correctly', () => {
 			expect(color.rotateHue(-270).asArray()).toStrictEqual([210, 50, 50, 0.8]); // Hue rotated negatively
 		});
 
-		test('handles rotations that exceed 360 degrees', () => {
+		it('handles rotations that exceed 360 degrees', () => {
 			expect(color.rotateHue(540).asArray()).toStrictEqual([300, 50, 50, 0.8]); // Hue wrapped around to 300
 		});
 	});
@@ -147,16 +148,16 @@ describe('HSL Class', () => {
 			grey = new HSL(120, 0, 50, 0.8);
 		});
 
-		test('increases saturation correctly', () => {
+		it('increases saturation correctly', () => {
 			expect(color.saturate(0.5).asArray()).toStrictEqual([120, 75, 50, 0.8]);
 			expect(grey.saturate(0.5).asArray()).toStrictEqual([120, 0, 50, 0.8]);
 		});
 
-		test('decreases saturation correctly', () => {
+		it('decreases saturation correctly', () => {
 			expect(color.saturate(-0.5).asArray()).toStrictEqual([120, 25, 50, 0.8]); // Saturation decreased by 50%
 		});
 
-		test('clamps saturation to the valid range', () => {
+		it('clamps saturation to the valid range', () => {
 			expect(color.saturate(1.5).asArray()).toStrictEqual([120, 100, 50, 0.8]); // Saturation clamped to 100%
 
 			expect(color.saturate(-2).asArray()).toStrictEqual([120, 0, 50, 0.8]); // Saturation clamped to 0%
@@ -167,11 +168,11 @@ describe('HSL Class', () => {
 		let color: HSL;
 		beforeEach(() => color = new HSL(120, 50, 50, 0.8));
 
-		test('reduces alpha correctly', () => {
+		it('reduces alpha correctly', () => {
 			expect(color.fade(0.5).asArray()).toStrictEqual([120, 50, 50, 0.4]); // Alpha reduced by 50%
 		});
 
-		test('handles edge cases for fading', () => {
+		it('handles edge cases for fading', () => {
 			const opaque = new HSL(0, 50, 50, 1);
 			expect(opaque.fade(1).asArray()).toStrictEqual([0, 50, 50, 0]); // Fully faded to transparent
 

package/src/color/hsl.ts

@@ -3,12 +3,38 @@ import { HSV } from './hsv.js';
 import { RGB } from './rgb.js';
 import { clamp, formatFloat, mod } from './utils.js';
 
+/**
+ * Represents a color in the HSL (Hue, Saturation, Lightness) color space.
+ * Extends the base `Color` class.
+ */
 export class HSL extends Color {
-	readonly h: number = 0; // between 0 and 360
-	readonly s: number = 0; // between 0 and 100
-	readonly l: number = 0; // between 0 and 100
-	readonly a: number = 1; // between 0 and 1
-
+	/**
+	 * The hue component of the color, in the range [0, 360].
+	 */
+	readonly h: number;
+
+	/**
+	 * The saturation component of the color, in the range [0, 100].
+	 */
+	readonly s: number;
+
+	/**
+	 * The lightness component of the color, in the range [0, 100].
+	 */
+	readonly l: number;
+
+	/**
+	 * The alpha (opacity) component of the color, in the range [0, 1].
+	 */
+	readonly a: number;
+
+	/**
+	 * Creates a new HSL color.
+	 * @param h - The hue component, in the range [0, 360].
+	 * @param s - The saturation component, in the range [0, 100].
+	 * @param l - The lightness component, in the range [0, 100].
+	 * @param a - The alpha (opacity) component, in the range [0, 1]. Defaults to 1.
+	 */
 	constructor(h: number, s: number, l: number, a: number = 1) {
 		super();
 		this.h = mod(h, 360);
@@ -17,10 +43,18 @@ export class HSL extends Color {
 		this.a = clamp(a, 0, 1);
 	}
 
+	/**
+	 * Returns the HSL color as an array of numbers.
+	 * @returns An array containing the hue, saturation, lightness, and alpha components.
+	 */
 	asArray(): [number, number, number, number] {
 		return [this.h, this.s, this.l, this.a];
 	}
 
+	/**
+	 * Returns a new HSL color with rounded components.
+	 * @returns A new HSL color with rounded hue, saturation, lightness, and alpha components.
+	 */
 	round(): HSL {
 		return new HSL(
 			Math.round(this.h),
@@ -30,10 +64,18 @@ export class HSL extends Color {
 		);
 	}
 
+	/**
+	 * Creates a copy of the current HSL color.
+	 * @returns A new HSL color with the same components as the current color.
+	 */
 	clone(): HSL {
 		return new HSL(this.h, this.s, this.l, this.a);
 	}
 
+	/**
+	 * Returns the HSL color as a CSS-compatible string.
+	 * @returns A string representing the HSL color in CSS format.
+	 */
 	asString(): string {
 		if (this.a === 1) {
 			return `hsl(${this.h.toFixed(0)},${this.s.toFixed(0)}%,${this.l.toFixed(0)}%)`;
@@ -42,14 +84,26 @@ export class HSL extends Color {
 		}
 	}
 
+	/**
+	 * Returns the current HSL color.
+	 * @returns The current HSL color.
+	 */
 	asHSL(): HSL {
 		return this.clone();
 	}
 
+	/**
+	 * Returns the current HSL color.
+	 * @returns The current HSL color.
+	 */
 	toHSL(): HSL {
 		return this;
 	}
 
+	/**
+	 * Converts the HSL color to an HSV color.
+	 * @returns A new HSV color representing the same color.
+	 */
 	asHSV(): HSV {
 		const s = this.s / 100, l = this.l / 100;
 		const v = l + s * Math.min(l, 1 - l);
@@ -57,6 +111,10 @@ export class HSL extends Color {
 		return new HSV(this.h, sv * 100, v * 100, this.a);
 	}
 
+	/**
+	 * Converts the HSL color to an RGB color.
+	 * @returns A new RGB color representing the same color.
+	 */
 	asRGB(): RGB {
 		const h = this.h / 360;
 		const s = this.s / 100;
@@ -86,6 +144,12 @@ export class HSL extends Color {
 		);
 	}
 
+	/**
+	 * Parses a string or Color object into an HSL color.
+	 * @param input - The input string or Color object to parse.
+	 * @returns A new HSL color parsed from the input.
+	 * @throws Will throw an error if the input string is not a valid HSL color string.
+	 */
 	static parse(input: string | Color): HSL {
 		if (input instanceof Color) return input.asHSL();
 
@@ -104,18 +168,37 @@ export class HSL extends Color {
 		throw new Error(`Invalid HSL color string: "${input}"`);
 	}
 
+	/**
+	 * Inverts the lightness component of the HSL color.
+	 * @returns A new HSL color with the lightness component inverted.
+	 */
 	invertLuminosity(): HSL {
 		return new HSL(this.h, this.s, 100 - this.l, this.a);
 	}
 
+	/**
+	 * Rotates the hue component of the HSL color by a given offset.
+	 * @param offset - The amount to rotate the hue by, in degrees.
+	 * @returns A new HSL color with the hue rotated by the given offset.
+	 */
 	rotateHue(offset: number): HSL {
 		return new HSL(mod(this.h + offset, 360), this.s, this.l, this.a);
 	}
 
+	/**
+	 * Increases the saturation of the HSL color by a given ratio.
+	 * @param ratio - The ratio by which to increase the saturation.
+	 * @returns A new HSL color with increased saturation.
+	 */
 	saturate(ratio: number): HSL {
 		return new HSL(this.h, clamp(this.s * (1 + ratio), 0, 100), this.l, this.a);
 	}
 
+	/**
+	 * Decreases the alpha (opacity) of the HSL color by a given value.
+	 * @param value - The value by which to decrease the alpha.
+	 * @returns A new HSL color with decreased alpha.
+	 */
 	fade(value: number): HSL {
 		return new HSL(this.h, this.s, this.l, this.a * (1 - value));
 	}