fix: robust HSL hue handling + add from_degrees and tests

Author: zxq82lm

plotters/src/style/color.rs

@@ -8,39 +8,46 @@ use serde::{Deserialize, Serialize};
 
 use std::marker::PhantomData;
 
-/// Common trait for all color representations.
+/// Any color representation
 pub trait Color {
+    /// Normalize this color representation to the backend color
     fn to_backend_color(&self) -> BackendColor;
 
+    /// Convert the RGB representation to the standard RGB tuple
     #[inline(always)]
     fn rgb(&self) -> (u8, u8, u8) {
         self.to_backend_color().rgb
     }
 
+    /// Get the alpha channel of the color
     #[inline(always)]
     fn alpha(&self) -> f64 {
         self.to_backend_color().alpha
     }
 
+    /// Mix the color with given opacity
     fn mix(&self, value: f64) -> RGBAColor {
         let (r, g, b) = self.rgb();
         let a = self.alpha() * value;
         RGBAColor(r, g, b, a)
     }
 
+    /// Convert the color into the RGBA color which is internally used by Plotters
     fn to_rgba(&self) -> RGBAColor {
         let (r, g, b) = self.rgb();
         let a = self.alpha();
         RGBAColor(r, g, b, a)
     }
 
+    /// Make a filled style form the color
     fn filled(&self) -> ShapeStyle
     where
         Self: Sized,
     {
         Into::<ShapeStyle>::into(self).filled()
     }
 
+    /// Make a shape style with stroke width from a color
     fn stroke_width(&self, width: u32) -> ShapeStyle
     where
         Self: Sized,
@@ -55,6 +62,10 @@ impl<T: Color> Color for &'_ T {
     }
 }
 
+/// The RGBA representation of the color, Plotters use RGBA as the internal representation
+/// of color
+///
+/// If you want to directly create a RGB color with transparency use [RGBColor::mix]
 #[derive(Copy, Clone, PartialEq, Debug, Default)]
 #[cfg_attr(feature = "serialization", derive(Serialize, Deserialize))]
 pub struct RGBAColor(pub u8, pub u8, pub u8, pub f64);
@@ -75,11 +86,13 @@ impl From<RGBColor> for RGBAColor {
     }
 }
 
+/// A color in the given palette
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Default)]
 #[cfg_attr(feature = "serialization", derive(Serialize, Deserialize))]
 pub struct PaletteColor<P: Palette>(usize, PhantomData<P>);
 
 impl<P: Palette> PaletteColor<P> {
+    /// Pick a color from the palette
     pub fn pick(idx: usize) -> PaletteColor<P> {
         PaletteColor(idx % P::COLORS.len(), PhantomData)
     }
@@ -95,6 +108,7 @@ impl<P: Palette> Color for PaletteColor<P> {
     }
 }
 
+/// The color described by its RGB value
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Default)]
 #[cfg_attr(feature = "serialization", derive(Serialize, Deserialize))]
 pub struct RGBColor(pub u8, pub u8, pub u8);
@@ -114,13 +128,13 @@ impl Color for RGBColor {
         }
     }
 }
-
 impl BackendStyle for RGBColor {
     fn color(&self) -> BackendColor {
         self.to_backend_color()
     }
 }
 
+/// The color described by HSL color space
 #[derive(Copy, Clone, PartialEq, Debug, Default)]
 #[cfg_attr(feature = "serialization", derive(Serialize, Deserialize))]
 pub struct HSLColor(pub f64, pub f64, pub f64);
@@ -136,18 +150,23 @@ impl Color for HSLColor {
     #[inline(always)]
     #[allow(clippy::many_single_char_names)]
     fn to_backend_color(&self) -> BackendColor {
+        // Hue: do not clamp; normalize
+        // - If >1.0, treat as degrees (divide by 360), then wrap to [0,1)
+        // - Else, wrap value to [0,1) to accept negatives
         let h = if self.0 > 1.0 {
             (self.0 / 360.0).rem_euclid(1.0)
         } else {
             self.0.rem_euclid(1.0)
         };
+
+        // Saturation & lightness remain clamped to valid ranges
         let s = self.1.clamp(0.0, 1.0);
         let l = self.2.clamp(0.0, 1.0);
 
         if s == 0.0 {
-            let v = (l * 255.0).round() as u8;
+            let value = (l * 255.0).round() as u8;
             return BackendColor {
-                rgb: (v, v, v),
+                rgb: (value, value, value),
                 alpha: 1.0,
             };
         }
@@ -159,8 +178,13 @@ impl Color for HSLColor {
         };
         let p = 2.0 * l - q;
 
-        let cvt = |t: f64| {
-            let t = t.rem_euclid(1.0);
+        let cvt = |mut t| {
+            if t < 0.0 {
+                t += 1.0;
+            }
+            if t > 1.0 {
+                t -= 1.0;
+            }
             let value = if t < 1.0 / 6.0 {
                 p + (q - p) * 6.0 * t
             } else if t < 1.0 / 2.0 {