fix: correct hsl saturation and hue

close #93 and #90

Author: XGHeaven

src/FastColor.ts

@@ -227,7 +227,14 @@ export class FastColor {
     return this._h;
   }
 
+  /**
+   * @deprecated should use getHSVSaturation or getHSLSaturation instead
+   */
   getSaturation(): number {
+    return this.getHSVSaturation();
+  }
+
+  getHSVSaturation(): number {
     if (typeof this._s === 'undefined') {
       const delta = this.getMax() - this.getMin();
       if (delta === 0) {
@@ -239,6 +246,19 @@ export class FastColor {
     return this._s;
   }
 
+  getHSLSaturation(): number {
+    if (typeof this._s === 'undefined') {
+      const delta = this.getMax() - this.getMin();
+      if (delta === 0) {
+        this._s = 0;
+      } else {
+        const l = this.getLightness();
+        this._s = (delta/255) / (1 - Math.abs(2 * l - 1));
+      }
+    }
+    return this._s;
+  }
+
   getLightness(): number {
     if (typeof this._l === 'undefined') {
       this._l = (this.getMax() + this.getMin()) / 510;
@@ -384,7 +404,7 @@ export class FastColor {
   toHsl(): HSL {
     return {
       h: this.getHue(),
-      s: this.getSaturation(),
+      s: this.getHSLSaturation(),
       l: this.getLightness(),
       a: this.a,
     };
@@ -393,7 +413,7 @@ export class FastColor {
   /** CSS support color pattern */
   toHslString(): string {
     const h = this.getHue();
-    const s = round(this.getSaturation() * 100);
+    const s = round(this.getHSLSaturation() * 100);
     const l = round(this.getLightness() * 100);
 
     return this.a !== 1
@@ -405,7 +425,7 @@ export class FastColor {
   toHsv(): HSV {
     return {
       h: this.getHue(),
-      s: this.getSaturation(),
+      s: this.getHSVSaturation(),
       v: this.getValue(),
       a: this.a,
     };
@@ -482,7 +502,7 @@ export class FastColor {
   }
 
   private fromHsl({ h, s, l, a }: OptionalA<HSL>): void {
-    this._h = h % 360;
+    this._h = h = h % 360;
     this._s = s;
     this._l = l;
     this.a = typeof a === 'number' ? a : 1;
@@ -492,6 +512,7 @@ export class FastColor {
       this.r = rgb;
       this.g = rgb;
       this.b = rgb;
+      return;
     }
 
     let r = 0,

tests/hsl.test.ts

@@ -0,0 +1,91 @@
+import { FastColor } from '../src';
+
+describe('hsl', () => {
+	// Unified hex<->hsl fixtures
+	const hexHslFixtures: Array<{ hex: string; hsl: { h: number; s: number; l: number } }> = [
+		// Boundaries
+		{ hex: '#000000', hsl: { h: 0, s: 0, l: 0 } },
+		{ hex: '#ffffff', hsl: { h: 0, s: 0, l: 1 } },
+
+		// Primaries
+		{ hex: '#ff0000', hsl: { h: 0, s: 1, l: 0.5 } },
+		{ hex: '#00ff00', hsl: { h: 120, s: 1, l: 0.5 } },
+		{ hex: '#0000ff', hsl: { h: 240, s: 1, l: 0.5 } },
+
+		// Secondaries
+		{ hex: '#ffff00', hsl: { h: 60, s: 1, l: 0.5 } },
+		{ hex: '#00ffff', hsl: { h: 180, s: 1, l: 0.5 } },
+		{ hex: '#ff00ff', hsl: { h: 300, s: 1, l: 0.5 } },
+
+		// Specific samples
+		{ hex: '#2400c2', hsl: { h: 251, s: 1, l: 0.3804 } },
+		{ hex: '#3d5dff', hsl: { h: 230, s: 1, l: 0.6196 } },
+	];
+
+	// hex -> hsl object values and roundtrip
+	hexHslFixtures.forEach(({ hex, hsl: expected }) => {
+		it(`hex to hsl object values: ${hex}`, () => {
+			const hsl = new FastColor(hex).toHsl();
+			expect(hsl.h).toBe(expected.h);
+			expect(hsl.s).toBe(expected.s);
+			expect(hsl.l).toBeCloseTo(expected.l, 4);
+			expect(hsl.a).toBe(1);
+
+			const back = new FastColor(hsl).toHexString();
+			expect(back).toBe(hex);
+		});
+	});
+
+	it('setHue should not change lightness', () => {
+		const base = new FastColor('#1677ff');
+		expect(base.getLightness()).toBeCloseTo(new FastColor('#1677ff').getLightness(), 4);
+
+		const turn = base.setHue(233);
+		expect(turn.getLightness()).toBeCloseTo(base.getLightness(), 4);
+	});
+
+	const hslaAlphaCases: Array<[string, string, number]> = [
+		['hsla(251, 100%, 38%, 0.5)', 'hsla(251,100%,38%,0.5)', 0.5],
+		['hsla(120, 25%, 33%, 0.7)', 'hsla(120,25%,33%,0.7)', 0.7],
+	];
+
+	hslaAlphaCases.forEach(([str, normalized, alpha]) => {
+		it(`supports hsla alpha: ${str}`, () => {
+			expect(new FastColor(str).toHslString()).toBe(normalized);
+			expect(new FastColor(str).toRgb().a).toBe(alpha);
+		});
+	});
+
+	it('hue 0 and 360 are equivalent', () => {
+		const c0 = new FastColor('hsl(0, 100%, 50%)');
+		const c360 = new FastColor('hsl(360, 100%, 50%)');
+		expect(c0.toHexString()).toBe(c360.toHexString());
+	});
+
+	it('s=0 yields grayscale regardless of hue', () => {
+		const a = new FastColor('hsl(0, 0%, 40%)');
+		const b = new FastColor('hsl(200, 0%, 40%)');
+		expect(a.toHexString()).toBe(b.toHexString());
+	});
+
+	it('roundtrip toHslString keeps values', () => {
+		const c = new FastColor('hsla(120, 25%, 33%, 0.7)');
+		expect(c.toHslString()).toBe('hsla(120,25%,33%,0.7)');
+		const parsed = new FastColor(c.toHslString());
+		expect(parsed.toHslString()).toBe('hsla(120,25%,33%,0.7)');
+	});
+
+	it('darken and lighten adjust lightness bounds', () => {
+		const c = new FastColor('hsl(200, 50%, 50%)');
+		const darker = c.darken(20);
+		const lighter = c.lighten(20);
+		expect(darker.getLightness()).toBeCloseTo(c.getLightness() - 0.2, 4);
+		expect(lighter.getLightness()).toBeCloseTo(c.getLightness() + 0.2, 4);
+
+		const minCap = c.darken(100);
+		const maxCap = c.lighten(100);
+		expect(minCap.getLightness()).toBe(0);
+		expect(maxCap.getLightness()).toBe(1);
+	});
+});
+