@versatiles/style 5.5.2 → 5.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/style",
-  "version": "5.5.2",
+  "version": "5.7.0",
   "description": "Generate StyleJSON for MapLibre",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,44 +32,45 @@
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "brace-expansion": "^4.0.0"
+    "@versatiles/style": "^5.6.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.0",
+    "@maplibre/maplibre-gl-native": "^6.1.0",
+    "@maplibre/maplibre-gl-style-spec": "^23.3.0",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.2",
+    "@rollup/plugin-typescript": "^12.1.3",
     "@types/bin-pack": "^1.0.3",
     "@types/brace-expansion": "^1.1.2",
-    "@types/inquirer": "^9.0.7",
+    "@types/inquirer": "^9.0.8",
     "@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.3.1",
+    "@types/node": "^24.0.4",
+    "@types/tar-stream": "^3.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.35.0",
+    "@typescript-eslint/parser": "^8.35.0",
+    "@versatiles/release-tool": "^2.4.2",
     "bin-pack": "^1.0.2",
-    "esbuild": "^0.25.1",
-    "eslint": "^9.22.0",
-    "inquirer": "^12.4.3",
+    "esbuild": "^0.25.5",
+    "eslint": "^9.29.0",
+    "inquirer": "^12.6.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",
+    "jest-ts-webcompat-resolver": "^1.0.1",
+    "rollup": "^4.44.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-sourcemaps2": "^0.5.2",
+    "sharp": "^0.34.2",
     "tar-stream": "^3.1.7",
-    "ts-jest": "^29.2.6",
+    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.26.1"
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.0"
   }
 }

package/src/color/abstract.ts

@@ -1,83 +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.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.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));
 	}

package/src/color/hsv.ts

@@ -3,12 +3,38 @@ import { HSL } from './hsl.js';
 import { RGB } from './rgb.js';
 import { clamp, mod } from './utils.js';
 
+/**
+ * Represents a color in the HSV (Hue, Saturation, Value) color space.
+ * Extends the base `Color` class.
+ */
 export class HSV extends Color {
-	readonly h: number = 0; // between 0 and 360
-	readonly s: number = 0; // between 0 and 100
-	readonly v: 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 value (brightness) component of the color, in the range [0, 100].
+	 */
+	readonly v: number;
+
+	/**
+	 * The alpha (opacity) component of the color, in the range [0, 1].
+	 */
+	readonly a: number;
+
+	/**
+	 * Constructs a new HSV color.
+	 * @param h - The hue component, in the range [0, 360].
+	 * @param s - The saturation component, in the range [0, 100].
+	 * @param v - The value (brightness) 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, v: number, a: number = 1) {
 		super();
 		this.h = mod(h, 360);
@@ -17,10 +43,18 @@ export class HSV extends Color {
 		this.a = clamp(a, 0, 1);
 	}
 
+	/**
+	 * Returns the HSV color as an array of numbers.
+	 * @returns An array containing the hue, saturation, value, and alpha components.
+	 */
 	asArray(): [number, number, number, number] {
 		return [this.h, this.s, this.v, this.a];
 	}
 
+	/**
+	 * Returns a new HSV color with the components rounded to the nearest integer.
+	 * @returns A new HSV color with rounded components.
+	 */
 	round(): HSV {
 		return new HSV(
 			Math.round(this.h),
@@ -30,14 +64,26 @@ export class HSV extends Color {
 		);
 	}
 
+	/**
+	 * Returns the color as a string representation.
+	 * @returns A string representation of the color.
+	 */
 	asString(): string {
 		return this.asHSL().asString();
 	}
 
+	/**
+	 * Creates a new HSV color that is a copy of the current color.
+	 * @returns A new HSV color that is a clone of the current color.
+	 */
 	clone(): HSV {
 		return new HSV(this.h, this.s, this.v, this.a);
 	}
 
+	/**
+	 * Converts the HSV color to an HSL color.
+	 * @returns An HSL representation of the color.
+	 */
 	asHSL(): HSL {
 		const s = this.s / 100;
 		const v = this.v / 100;
@@ -51,14 +97,26 @@ export class HSV extends Color {
 		);
 	}
 
+	/**
+	 * Returns the current HSV color.
+	 * @returns The current HSV color.
+	 */
 	asHSV(): HSV {
 		return this.clone();
 	}
 
+	/**
+	 * Returns the current HSV color.
+	 * @returns The current HSV color.
+	 */
 	toHSV(): HSV {
 		return this;
 	}
 
+	/**
+	 * Converts the HSV color to an RGB color.
+	 * @returns An RGB representation of the color.
+	 */
 	asRGB(): RGB {
 		const h = this.h / 360; // Normalize h to range [0, 1]
 		const s = this.s / 100; // Normalize s to range [0, 1]
@@ -90,10 +148,20 @@ export class HSV extends Color {
 		return new RGB(r * 255, g * 255, b * 255, this.a);
 	}
 
+	/**
+	 * Fades the color by a given value.
+	 * @param value - The amount to fade the color by, in the range [0, 1].
+	 * @returns A new HSV color with the alpha component faded by the given value.
+	 */
 	fade(value: number): HSV {
 		return new HSV(this.h, this.s, this.v, this.a * (1 - value));
 	}
 
+	/**
+	 * Sets the hue component of the color.
+	 * @param value - The new hue value, in the range [0, 360].
+	 * @returns A new HSV color with the updated hue component.
+	 */
 	setHue(value: number): HSV {
 		return new HSV(value, this.s, this.v, this.a);
 	}

package/src/color/index.test.ts

@@ -77,26 +77,6 @@ describe('Color.parse', () => {
 	});
 });
 
-describe('Color.random', () => {
-	test('generates random HSV colors', () => {
-		const random = Color.random();
-		expect(random).toBeInstanceOf(HSV);
-		const array = random.asArray();
-		expect(array[0]).toBeGreaterThanOrEqual(0);
-		expect(array[0]).toBeLessThanOrEqual(360);
-		expect(array[1]).toBeGreaterThanOrEqual(0);
-		expect(array[1]).toBeLessThanOrEqual(100);
-		expect(array[2]).toBeGreaterThanOrEqual(0);
-		expect(array[2]).toBeLessThanOrEqual(100);
-	});
-
-	test('supports options for generating random colors', () => {
-		const random = Color.random({ hue: 'red', luminosity: 'bright' });
-		expect(random).toBeInstanceOf(HSV);
-		// Additional checks based on the options provided can be added here
-	});
-});
-
 describe('Color Class Properties', () => {
 	test('Color.HSL is accessible', () => {
 		expect(Color.HSL).toBe(HSL);

package/src/color/index.ts

@@ -1,7 +1,6 @@
 import { Color } from './abstract.js';
 import { HSL } from './hsl.js';
 import { HSV } from './hsv.js';
-import randomColor from './random.js';
 import { RGB } from './rgb.js';
 
 Color.parse = function (input: string | Color): Color {
@@ -29,8 +28,6 @@ Color.HSL = HSL;
 Color.HSV = HSV;
 Color.RGB = RGB;
 
-Color.random = randomColor;
-
 export type { RandomColorOptions } from './random.js';
 export type { HSL } from './hsl.js';
 export type { HSV } from './hsv.js';

package/src/color/random.test.ts

@@ -1,3 +1,4 @@
+import { HSV } from './hsv.js';
 import type { RandomColorOptions } from './random.js';
 import randomColor from './random.js';
 
@@ -6,6 +7,26 @@ describe('RandomColor', () => {
 		expect(randomColor).toBeDefined();
 	});
 
+	describe('Color.random', () => {
+		test('generates random HSV colors', () => {
+			const random = randomColor();
+			expect(random).toBeInstanceOf(HSV);
+			const array = random.asArray();
+			expect(array[0]).toBeGreaterThanOrEqual(0);
+			expect(array[0]).toBeLessThanOrEqual(360);
+			expect(array[1]).toBeGreaterThanOrEqual(0);
+			expect(array[1]).toBeLessThanOrEqual(100);
+			expect(array[2]).toBeGreaterThanOrEqual(0);
+			expect(array[2]).toBeLessThanOrEqual(100);
+		});
+	
+		test('supports options for generating random colors', () => {
+			const random = randomColor({ hue: 'red', luminosity: 'bright' });
+			expect(random).toBeInstanceOf(HSV);
+			// Additional checks based on the options provided can be added here
+		});
+	});
+
 	describe('randomColor method', () => {
 		test('returns correct color string for some test cases', () => {
 			function t(options: RandomColorOptions): string {