@versatiles/style 5.2.6 → 5.2.7

package/src/color/hsl.ts

@@ -0,0 +1,122 @@
+import { Color } from './abstract.js';
+import { HSV } from './hsv.js';
+import { RGB } from './rgb.js';
+import { clamp, formatFloat, mod } from './utils.js';
+
+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
+
+	constructor(h: number, s: number, l: number, a: number = 1) {
+		super();
+		this.h = mod(h, 360);
+		this.s = clamp(s, 0, 100);
+		this.l = clamp(l, 0, 100);
+		this.a = clamp(a, 0, 1);
+	}
+
+	asArray(): [number, number, number, number] {
+		return [this.h, this.s, this.l, this.a];
+	}
+
+	round(): HSL {
+		return new HSL(
+			Math.round(this.h),
+			Math.round(this.s),
+			Math.round(this.l),
+			Math.round(this.a * 1000) / 1000,
+		);
+	}
+
+	clone(): HSL {
+		return new HSL(this.h, this.s, this.l, this.a);
+	}
+
+	asString(): string {
+		if (this.a === 1) {
+			return `hsl(${this.h.toFixed(0)},${this.s.toFixed(0)}%,${this.l.toFixed(0)}%)`;
+		} else {
+			return `hsla(${this.h.toFixed(0)},${this.s.toFixed(0)}%,${this.l.toFixed(0)}%,${formatFloat(this.a, 3)})`;
+		}
+	}
+
+	asHSL(): HSL {
+		return this.clone();
+	}
+
+	toHSL(): HSL {
+		return this;
+	}
+
+	asHSV(): HSV {
+		const s = this.s / 100, l = this.l / 100;
+		const v = l + s * Math.min(l, 1 - l);
+		const sv = v === 0 ? 0 : 2 * (1 - l / v);
+		return new HSV(this.h, sv * 100, v * 100, this.a);
+	}
+
+	asRGB(): RGB {
+		const h = this.h / 360;
+		const s = this.s / 100;
+		const l = this.l / 100;
+
+		// Achromatic (grey)
+		if (s === 0) return new RGB(l * 255, l * 255, l * 255, this.a);
+
+		const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+		const p = 2 * l - q;
+
+		const hueToRgb = (t: number): number => {
+			if (t < 0) t += 1;
+			if (t > 1) t -= 1;
+			if (t < 1 / 6) return p + (q - p) * 6 * t;
+			if (t < 1 / 2) return q;
+			if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+			return p;
+		};
+
+		// Convert to RGB in the 0-255 range and return
+		return new RGB(
+			255 * hueToRgb(h + 1 / 3),
+			255 * hueToRgb(h),
+			255 * hueToRgb(h - 1 / 3),
+			this.a
+		);
+	}
+
+	static parse(input: string | Color): HSL {
+		if (input instanceof Color) return input.asHSL();
+
+		input = input.replace(/\s+/g, '').toLowerCase();
+
+		let match = input.match(/^hsl\((?<h>[-+0-9.]+)(?:deg)?,(?<s>[-+0-9.]+)%,(?<l>[-+0-9.]+)%\)$/);
+		if (match) {
+			return new HSL(parseFloat(match.groups!.h), parseFloat(match.groups!.s), parseFloat(match.groups!.l));
+		}
+
+		match = input.match(/^hsla\((?<h>[-+0-9.]+)(?:deg)?,(?<s>[-+0-9.]+)%,(?<l>[-+0-9.]+)%,(?<a>[-+0-9.]+)\)$/);
+		if (match) {
+			return new HSL(parseFloat(match.groups!.h), parseFloat(match.groups!.s), parseFloat(match.groups!.l), parseFloat(match.groups!.a));
+		}
+
+		throw new Error(`Invalid HSL color string: "${input}"`);
+	}
+
+	invertLuminosity(): HSL {
+		return new HSL(this.h, this.s, 100 - this.l, this.a);
+	}
+
+	rotateHue(offset: number): HSL {
+		return new HSL(mod(this.h + offset, 360), this.s, this.l, this.a);
+	}
+
+	saturate(ratio: number): HSL {
+		return new HSL(this.h, clamp(this.s * (1 + ratio), 0, 100), this.l, this.a);
+	}
+
+	fade(value: number): HSL {
+		return new HSL(this.h, this.s, this.l, this.a * (1 - value));
+	}
+}

package/src/color/hsv.test.ts

@@ -0,0 +1,174 @@
+import { HSV } from './hsv.js';
+import { HSL } from './hsl.js';
+import { RGB } from './rgb.js';
+
+describe('HSV Class', () => {
+
+	test('constructor initializes values correctly with clamping', () => {
+		const color = new HSV(400, 120, 120, 2);
+		expect(color.asArray()).toStrictEqual([40, 100, 100, 1]);
+
+		const colorNegative = new HSV(-60, -10, -10, -1);
+		expect(colorNegative.asArray()).toStrictEqual([300, 0, 0, 0]);
+	});
+
+	test('asArray returns correct array representation', () => {
+		const color = new HSV(120, 50, 50, 0.5);
+		expect(color.asArray()).toStrictEqual([120, 50, 50, 0.5]);
+	});
+
+	test('clone returns a new instance with identical values', () => {
+		const color = new HSV(180, 70, 70, 0.7);
+		const clone = color.clone();
+		expect(clone).toBeInstanceOf(HSV);
+		expect(clone).toEqual(color);
+		expect(clone).not.toBe(color);
+	});
+
+	describe('asString', () => {
+		test('converts fully saturated colors correctly', () => {
+			expect(new HSV(0, 100, 100).asString()).toBe('hsl(0,100%,50%)');
+			expect(new HSV(120, 100, 100).asString()).toBe('hsl(120,100%,50%)');
+			expect(new HSV(240, 100, 100).asString()).toBe('hsl(240,100%,50%)');
+		});
+
+		test('handles partially saturated colors', () => {
+			expect(new HSV(60, 50, 100).asString()).toBe('hsl(60,100%,75%)');
+			expect(new HSV(300, 25, 50).asString()).toBe('hsl(300,14%,44%)');
+		});
+
+		test('handles achromatic (grey) colors', () => {
+			expect(new HSV(0, 0, 0).asString()).toBe('hsl(0,0%,0%)');
+			expect(new HSV(0, 0, 50).asString()).toBe('hsl(0,0%,50%)');
+			expect(new HSV(0, 0, 100).asString()).toBe('hsl(0,0%,100%)');
+		});
+
+		test('handles hue wrapping and extreme values', () => {
+			expect(new HSV(-60, 100, 100).asString()).toBe('hsl(300,100%,50%)');
+			expect(new HSV(420, 100, 100).asString()).toBe('hsl(60,100%,50%)');
+		});
+
+		test('handles alpha transparency', () => {
+			expect(new HSV(0, 100, 100, 0.5).asString()).toBe('hsla(0,100%,50%,0.5)');
+			expect(new HSV(120, 100, 100, 0.25).asString()).toBe('hsla(120,100%,50%,0.25)');
+			expect(new HSV(240, 100, 100, 1).asString()).toBe('hsl(240,100%,50%)');
+		});
+
+		test('produces consistent results for repeated calls', () => {
+			const color = new HSV(60, 50, 50);
+			expect(color.asString()).toBe('hsl(60,33%,38%)');
+			expect(color.asString()).toBe('hsl(60,33%,38%)');
+		});
+	});
+
+	describe('color conversion', () => {
+
+		test('asHSL converts HSV to HSL correctly', () => {
+			function check(input: [number, number, number], output: [number, number, number]) {
+				const hsv = new HSV(...input);
+				const hsl = hsv.asHSL();
+				expect(hsl).toBeInstanceOf(HSL);
+				expect(hsl.asArray().map(Math.round))
+					.toStrictEqual([...output, 1]);
+
+				expect(hsv.asHex()).toStrictEqual(hsl.asHex());
+			}
+
+			check([10, 0, 0], [10, 0, 0]);
+			check([11, 0, 50], [11, 0, 50]);
+			check([12, 0, 100], [12, 0, 100]);
+			check([13, 50, 0], [13, 0, 0]);
+			check([14, 50, 50], [14, 33, 38]);
+			check([15, 50, 100], [15, 100, 75]);
+			check([16, 100, 0], [16, 0, 0]);
+			check([17, 100, 50], [17, 100, 25]);
+			check([18, 100, 100], [18, 100, 50]);
+		});
+
+		test('asRGB converts HSV to RGB correctly', () => {
+			const color = new HSV(120, 100, 100);
+			const rgb = color.asRGB();
+			expect(rgb).toBeInstanceOf(RGB);
+			expect(rgb.asArray().map(value => Math.round(value)))
+				.toStrictEqual([0, 255, 0, 1]);
+		});
+
+		test('asHSV and toHSV return the same instance or clone', () => {
+			const color = new HSV(240, 100, 50, 1);
+			expect(color.asHSV()).toStrictEqual(color);
+			expect(color.toHSV()).toStrictEqual(color);
+		});
+
+		test('asRGB conversion S and V', () => {
+			function check(input: [number, number, number], output: [number, number, number]) {
+				const color = new HSV(...input);
+				const rgb = color.asRGB();
+				expect(rgb.asArray().map(value => Math.round(value)))
+					.toStrictEqual([...output, 1]);
+			}
+
+			check([10, 0, 0], [0, 0, 0]);
+			check([11, 0, 50], [128, 128, 128]);
+			check([12, 0, 100], [255, 255, 255]);
+			check([13, 50, 0], [0, 0, 0]);
+			check([14, 50, 50], [128, 79, 64]);
+			check([15, 50, 100], [255, 159, 128]);
+			check([16, 100, 0], [0, 0, 0]);
+			check([17, 100, 50], [128, 36, 0]);
+			check([18, 100, 100], [255, 77, 0]);
+		});
+
+		test('asRGB conversion H', () => {
+			function check(hue: number, output: string) {
+				const color = new HSV(hue, 100, 100);
+				expect(color.asRGB().asHex()).toBe(output);
+			}
+
+			check(-1, '#FF0004');
+			check(0, '#FF0000');
+			check(1, '#FF0400');
+			check(30, '#FF8000');
+			check(60, '#FFFF00');
+			check(90, '#80FF00');
+			check(120, '#00FF00');
+			check(150, '#00FF80');
+			check(180, '#00FFFF');
+			check(210, '#0080FF');
+			check(240, '#0000FF');
+			check(270, '#8000FF');
+			check(300, '#FF00FF');
+			check(330, '#FF0080');
+			check(359, '#FF0004');
+			check(360, '#FF0000');
+			check(361, '#FF0400');
+		});
+
+	});
+
+	describe('parse errors and validations', () => {
+		test('constructor clamps out-of-bound values', () => {
+			const color = new HSV(400, 150, 150, 2);
+			expect(color.asArray()).toStrictEqual([40, 100, 100, 1]);
+		});
+
+		test('negative values are handled correctly', () => {
+			const color = new HSV(-360, -50, -50, -1);
+			expect(color.asArray()).toStrictEqual([0, 0, 0, 0]);
+		});
+	});
+
+	describe('fade', () => {
+		test('reduces alpha correctly', () => {
+			const color = new HSV(120, 50, 50, 0.8);
+			expect(color.fade(0.5).asArray()).toStrictEqual([120, 50, 50, 0.4]); // Alpha reduced by 50%
+		});
+
+		test('handles edge cases for fading', () => {
+			const opaque = new HSV(0, 50, 50, 1);
+			expect(opaque.fade(1).asArray()).toStrictEqual([0, 50, 50, 0]); // Fully faded to transparent
+
+			const transparent = new HSV(0, 50, 50, 0);
+			expect(transparent.fade(0.5).asArray()).toStrictEqual([0, 50, 50, 0]); // Remains fully transparent
+		});
+	});
+});

package/src/color/hsv.ts

@@ -0,0 +1,100 @@
+import { Color } from './abstract.js';
+import { HSL } from './hsl.js';
+import { RGB } from './rgb.js';
+import { clamp, mod } from './utils.js';
+
+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
+
+	constructor(h: number, s: number, v: number, a: number = 1) {
+		super();
+		this.h = mod(h, 360);
+		this.s = clamp(s, 0, 100);
+		this.v = clamp(v, 0, 100);
+		this.a = clamp(a, 0, 1);
+	}
+
+	asArray(): [number, number, number, number] {
+		return [this.h, this.s, this.v, this.a];
+	}
+
+	round(): HSV {
+		return new HSV(
+			Math.round(this.h),
+			Math.round(this.s),
+			Math.round(this.v),
+			Math.round(this.a * 1000) / 1000
+		);
+	}
+
+	asString(): string {
+		return this.asHSL().asString();
+	}
+
+	clone(): HSV {
+		return new HSV(this.h, this.s, this.v, this.a);
+	}
+
+	asHSL(): HSL {
+		const s = this.s / 100;
+		const v = this.v / 100;
+		const k = (2 - s) * v;
+		const q = k < 1 ? k : 2 - k
+		return new HSL(
+			this.h,
+			q == 0 ? 0 : 100 * s * v / q,
+			100 * k / 2,
+			this.a
+		);
+	}
+
+	asHSV(): HSV {
+		return this.clone();
+	}
+
+	toHSV(): HSV {
+		return this;
+	}
+
+	asRGB(): RGB {
+		const h = this.h / 360; // Normalize h to range [0, 1]
+		const s = this.s / 100; // Normalize s to range [0, 1]
+		const v = this.v / 100; // Normalize v to range [0, 1]
+
+		let r = 0, g = 0, b = 0;
+
+		if (s === 0) {
+			// Achromatic (grey)
+			r = g = b = v;
+		} else {
+			const i = Math.floor(h * 6); // Determine the sector of the color wheel
+			const f = h * 6 - i;         // Fractional part of h * 6
+			const p = v * (1 - s);
+			const q = v * (1 - s * f);
+			const t = v * (1 - s * (1 - f));
+
+			switch (i % 6) {
+				case 0: r = v; g = t; b = p; break;
+				case 1: r = q; g = v; b = p; break;
+				case 2: r = p; g = v; b = t; break;
+				case 3: r = p; g = q; b = v; break;
+				case 4: r = t; g = p; b = v; break;
+				case 5: r = v; g = p; b = q; break;
+			}
+		}
+
+		// Convert to RGB in the 0-255 range and return
+		return new RGB(r * 255, g * 255, b * 255, this.a);
+	}
+
+	fade(value: number): HSV {
+		return new HSV(this.h, this.s, this.v, this.a * (1 - value));
+	}
+
+	setHue(value: number): HSV {
+		return new HSV(value, this.s, this.v, this.a);
+	}
+}

package/src/color/index.test.ts

@@ -0,0 +1,119 @@
+import { Color } from './index.js';
+import { HSL } from './hsl.js';
+import { HSV } from './hsv.js';
+import { RGB } from './rgb.js';
+
+describe('Color Conversions', () => {
+
+	const scenarios: [number, number, number, number][] = [
+		[-100, 14, 15, 0],
+		[0, 0, 0, 0.1],
+		[100, 0, 50, 0.2],
+		[200, 0, 100, 0.3],
+		[300, 50, 0, 0.4],
+		[400, 50, 50, 0.5],
+		[500, 50, 100, 0.6],
+		[600, 100, 0, 0.7],
+		[700, 100, 50, 0.8],
+		[800, 100, 100, 0.9],
+		[900, 12, 13, 1.0],
+	]
+	test('test HSV -> HSL -> RGB', () => {
+		for (const v of scenarios) {
+			const hsv = new HSV(...v);
+			expect(hsv.a).toEqual(v[3]);
+			const hsl = hsv.asHSL();
+			const a1 = hsv.asRGB().asArray();
+			const a2 = hsl.asRGB().asArray();
+			for (let i = 0; i < 4; i++) expect(a1[i]).toBeCloseTo(a2[i]);
+		}
+	});
+
+	test('test HSL -> HSV -> RGB', () => {
+		for (const v of scenarios) {
+			const hsl = new HSL(...v);
+			expect(hsl.a).toEqual(v[3]);
+			const hsv = hsl.asHSV();
+			const a1 = hsv.asRGB().asArray();
+			const a2 = hsl.asRGB().asArray();
+			for (let i = 0; i < 4; i++) expect(a1[i]).toBeCloseTo(a2[i]);
+		}
+	});
+})
+
+describe('Color.parse', () => {
+	test('parses hexadecimal color strings correctly', () => {
+		const color = Color.parse('#ff8040');
+		expect(color).toBeInstanceOf(RGB);
+		expect(color.asArray()).toStrictEqual([255, 128, 64, 1]);
+
+		const colorWithAlpha = Color.parse('#ff80407f');
+		expect(colorWithAlpha).toBeInstanceOf(RGB);
+		expect(colorWithAlpha.asHex()).toStrictEqual('#FF80407F');
+	});
+
+	test('parses RGB strings correctly', () => {
+		const color = Color.parse('rgb(255, 128, 64)');
+		expect(color).toBeInstanceOf(RGB);
+		expect(color.asArray()).toStrictEqual([255, 128, 64, 1]);
+
+		const colorWithAlpha = Color.parse('rgba(255, 128, 64, 0.5)');
+		expect(colorWithAlpha).toBeInstanceOf(RGB);
+		expect(colorWithAlpha.asArray()).toStrictEqual([255, 128, 64, 0.5]);
+	});
+
+	test('parses HSL strings correctly', () => {
+		const color = Color.parse('hsl(120, 50%, 50%)');
+		expect(color).toBeInstanceOf(HSL);
+		expect(color.asArray()).toStrictEqual([120, 50, 50, 1]);
+
+		const colorWithAlpha = Color.parse('hsla(120, 50%, 50%, 0.5)');
+		expect(colorWithAlpha).toBeInstanceOf(HSL);
+		expect(colorWithAlpha.asArray()).toStrictEqual([120, 50, 50, 0.5]);
+	});
+
+	test('throws an error for unsupported formats', () => {
+		expect(() => Color.parse('invalid color string')).toThrow('Unknown color format: invalid color string');
+	});
+});
+
+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);
+	});
+
+	test('Color.HSV is accessible', () => {
+		expect(Color.HSV).toBe(HSV);
+	});
+
+	test('Color.RGB is accessible', () => {
+		expect(Color.RGB).toBe(RGB);
+	});
+});
+
+describe('Exported Module', () => {
+	test('named export is Color', async () => {
+		const module = await import('./index.js');
+		expect(module.Color).toBe(Color);
+	});
+});

package/src/color/index.ts

@@ -0,0 +1,38 @@
+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 {
+	if (input instanceof Color) return input;
+
+	input = input.trim().toLowerCase();
+
+	if (input.startsWith('#')) return RGB.parse(input);
+
+	const prefix = input.replace(/\d.*/, '').trim().toLowerCase();
+
+	switch (prefix) {
+		case 'rgb(':
+		case 'rgba(':
+			return RGB.parse(input);
+		case 'hsl(':
+		case 'hsla(':
+			return HSL.parse(input);
+		default:
+			throw Error('Unknown color format: ' + input);
+	}
+}
+
+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';
+export type { RGB } from './rgb.js';
+export { Color };

package/src/color/random.test.ts

@@ -0,0 +1,35 @@
+import type { RandomColorOptions } from './random.js';
+import randomColor from './random.js';
+
+describe('RandomColor', () => {
+	test('constructor initializes without errors', () => {
+		expect(randomColor).toBeDefined();
+	});
+
+	describe('randomColor method', () => {
+		test('returns correct color string for some test cases', () => {
+			function t(options: RandomColorOptions): string {
+				return randomColor(options).asHSL().asString();
+			}
+			expect(t({ seed: 'testSeed', hue: 'red' })).toBe('hsl(356,90%,30%)');
+			expect(t({ seed: 'testSeed', hue: 120 })).toBe('hsl(120,92%,26%)');
+			expect(t({ seed: 'testSeed', luminosity: 'dark' })).toBe('hsl(185,98%,19%)');
+			expect(t({ seed: 'testSeed', luminosity: 12 })).toBe('hsl(185,90%,6%)');
+			expect(t({ seed: 'testSeed', saturation: 'strong' })).toBe('hsl(185,100%,48%)');
+			expect(t({ seed: 'testSeed', opacity: 0.5 })).toBe('hsla(185,90%,23%,0.5)');
+			expect(t({ seed: 'testSeed' })).toBe('hsl(185,90%,23%)');
+		});
+
+		test('consistent color generation with a seed', () => {
+			const color1 = randomColor({ seed: 'consistentSeed' });
+			const color2 = randomColor({ seed: 'consistentSeed' });
+			expect(color1.asHex()).toBe(color2.asHex());
+		});
+
+		test('different color generation without a seed', () => {
+			const color1 = randomColor({ seed: 'seed1' });
+			const color2 = randomColor({ seed: 'seed2' });
+			expect(color1.asHex()).not.toBe(color2.asHex());
+		});
+	});
+});