fix: correct hsl saturation and hue (#94)

Author: XGHeaven

src/FastColor.ts

@@ -86,7 +86,8 @@ export class FastColor {
 
   // HSV privates
   private _h?: number;
-  private _s?: number;
+  private _hsl_s?: number;
+  private _hsv_s?: number;
   private _l?: number;
   private _v?: number;
 
@@ -143,7 +144,8 @@ export class FastColor {
       this.b = input.b;
       this.a = input.a;
       this._h = input._h;
-      this._s = input._s;
+      this._hsl_s = input._hsl_s;
+      this._hsv_s = input._hsv_s;
       this._l = input._l;
       this._v = input._v;
     } else if (matchFormat('rgb')) {
@@ -227,16 +229,36 @@ export class FastColor {
     return this._h;
   }
 
+  /**
+   * @deprecated should use getHSVSaturation or getHSLSaturation instead
+   */
   getSaturation(): number {
-    if (typeof this._s === 'undefined') {
+    return this.getHSVSaturation();
+  }
+
+  getHSVSaturation(): number {
+    if (typeof this._hsv_s === 'undefined') {
+      const delta = this.getMax() - this.getMin();
+      if (delta === 0) {
+        this._hsv_s = 0;
+      } else {
+        this._hsv_s = delta / this.getMax();
+      }
+    }
+    return this._hsv_s;
+  }
+
+  getHSLSaturation(): number {
+    if (typeof this._hsl_s === 'undefined') {
       const delta = this.getMax() - this.getMin();
       if (delta === 0) {
-        this._s = 0;
+        this._hsl_s = 0;
       } else {
-        this._s = delta / this.getMax();
+        const l = this.getLightness();
+        this._hsl_s = (delta/255) / (1 - Math.abs(2 * l - 1));
       }
     }
-    return this._s;
+    return this._hsl_s;
   }
 
   getLightness(): number {
@@ -384,7 +406,7 @@ export class FastColor {
   toHsl(): HSL {
     return {
       h: this.getHue(),
-      s: this.getSaturation(),
+      s: this.getHSLSaturation(),
       l: this.getLightness(),
       a: this.a,
     };
@@ -393,7 +415,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 +427,7 @@ export class FastColor {
   toHsv(): HSV {
     return {
       h: this.getHue(),
-      s: this.getSaturation(),
+      s: this.getHSVSaturation(),
       v: this.getValue(),
       a: this.a,
     };
@@ -481,9 +503,10 @@ export class FastColor {
     }
   }
 
-  private fromHsl({ h, s, l, a }: OptionalA<HSL>): void {
-    this._h = h % 360;
-    this._s = s;
+  private fromHsl({ h: _h, s, l, a }: OptionalA<HSL>): void {
+    const h = ((_h % 360) + 360) % 360;
+    this._h = h;
+    this._hsl_s = s;
     this._l = l;
     this.a = typeof a === 'number' ? a : 1;
 
@@ -492,6 +515,7 @@ export class FastColor {
       this.r = rgb;
       this.g = rgb;
       this.b = rgb;
+      return;
     }
 
     let r = 0,
@@ -528,9 +552,10 @@ export class FastColor {
     this.b = round((b + lightnessModification) * 255);
   }
 
-  private fromHsv({ h, s, v, a }: OptionalA<HSV>): void {
-    this._h = h % 360;
-    this._s = s;
+  private fromHsv({ h: _h, s, v, a }: OptionalA<HSV>): void {
+    const h = ((_h % 360) + 360) % 360;
+    this._h = h;
+    this._hsv_s = s;
     this._v = v;
     this.a = typeof a === 'number' ? a : 1;
 

tests/hsl.test.ts

@@ -0,0 +1,98 @@
+import { FastColor } from '../src';
+
+describe('hsl', () => {
+	// Unified hex<->hsl fixtures
+	const hexHslFixtures: { 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: [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);
+	});
+
+	it('normalizes H outside range for HSL (object input)', () => {
+		// -60 -> 300 (magenta)
+		expect(new FastColor({ h: -60, s: 1, l: 0.5 }).toHexString()).toBe('#ff00ff');
+		// 420 -> 60 (yellow)
+		expect(new FastColor({ h: 420, s: 1, l: 0.5 }).toHexString()).toBe('#ffff00');
+	});
+});
+

tests/hsv.test.ts

@@ -55,4 +55,11 @@ describe('hsv', () => {
     const turn = base.setHue(233);
     expect(turn.getValue()).toBe(1);
   });
+
+  it('normalizes H outside range for HSV (object input)', () => {
+    // -60 -> 300 (magenta)
+    expect(new FastColor({ h: -60, s: 1, v: 1 }).toHexString()).toBe('#ff00ff');
+    // 420 -> 60 (yellow)
+    expect(new FastColor({ h: 420, s: 1, v: 1 }).toHexString()).toBe('#ffff00');
+  });
 });