[ColorHelper] Add new ColorHelper API

[Avid29]

Fixes CommunityToolkit/Labs-Windows#756

PR Type

What kind of change does this PR introduce?

This PR introduces a new API for the ColorHelper, though leaves the old API available with no breaking changes (though marked as deprecated)

What is the current behavior?

This is the current API

public static class ColorHelper
{
  public static Color ToColor(this string colorString);
  
  public static string ToHex(this Color color);

  public static int ToInt(this Color color);

  public static HslColor ToHsl(this Color color);

  public static HsvColor ToHsv(this Color color);

  public static Color FromHsl(double hue, double saturation, double lightness, double alpha = 1.0);

  public static Color FromHsv(double hue, double saturation, double value, double alpha = 1.0);
}

public struct HslColor
{
  public double H;
  public double S;
  public double L;
  public double A;
}

public struct HsvColor
{
  public double H;
  public double S;
  public double V;
  public double A;
}

What is the new behavior?

This is the full new API, including the old API marked obsolete.

public static partial class ColorHelper
{
    public static bool TryParseColor(string colorString, out Color color);

    public static bool TryParseHexColor(string hexString, out Color color);

    public static bool TryParseHslColor(string hslColor, out HslColor color);

    public static bool TryParseHsvColor(string hsvColor, out HsvColor color);

    public static bool TryParseScreenColor(string screenColor, out Color color);

    public static bool TryParseColorName(string colorName, out Color color);

    public static Color ParseColor(string colorString);

    public static Color ParseHexColor(string hexColor);

    public static HslColor ParseHslColor(string hslColor);

    public static HsvColor ParseHsvColor(string hsvColor);

    public static Color ParseScreenColor(string screenColor);

    public static Color ParseColorName(string colorName);

    [Obsolete("This method is marked deprecated, and will be removed in a future version. Please replace with ColorHelper.ParseColor(string colorString).")]
    public static Color ToColor(this string colorString);

    [Obsolete("This method is marked deprecated, and will be removed in a future version. Please replace with (Color)HslColor.Create().")]
    public static Color FromHsl(double hue, double saturation, double lightness, double alpha = 1.0);

    [Obsolete("This method is marked deprecated, and will be removed in a future version. Please replace with (Color)HsvColor.Create().")]
    public static Color FromHsv(double hue, double saturation, double value, double alpha = 1.0);

    [Obsolete("This method is marked deprecated, and will be removed in a future version. Please replace with .ToString().")]
    public static string ToHex(this Color color);
}

public static class ColorExtensions
{
    public static int ToInt(this Color color);

    public static HslColor ToHsl(this Color color);

    public static HsvColor ToHsv(this Color color);

    public static Color AlphaOver(this Color @base, Color overlay);

    public static Color AlphaOver(this Color @base, Color overlay, double alpha);

    public static HsvColor WithHue(this Color original, double hue);

    public static HsvColor WithSaturation(this Color original, double saturation);

    public static HsvColor WithValue(this Color original, double value);

    public static HslColor WithLightness(this Color original, double lightness);

#if NET10_0_OR_GREATER
    extension(Color color)
    {
        public static HslColor FromAhsl(double a, double h, double s, double l);

        public static HsvColor FromAhsv(double a, double h, double s, double v);

        public static Color Mix(Color color1, Color color2, double factor);

        public static Color Add(Color color1, Color color2);

        public static Color Subtract(Color color1, Color color2);

        public static Color operator +(Color color1, Color color2);

        public static Color operator -(Color color1, Color color2);
    }
#endif
}

public struct HslColor
{
    public static HslColor Create(double hue, double saturation, double lightness, double alpha = 1);

    public double Hue { readonly get; set; }

    public double Saturation { readonly get; set; }

    public double Lightness { readonly get; set; }

    public double Alpha { readonly get; set; }

    public readonly Color ToColor();

    public static implicit operator Color(HslColor hsl);

    public static explicit operator HslColor(Color color);

    public static explicit operator HslColor(HsvColor color);

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Hue property")]
    public double H;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Saturation property")]
    public double S;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Lightness property")]
    public double L;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Alpha property")]
    public double A;
}

public struct HsvColor
{
    public static HsvColor Create(double hue, double saturation, double value, double alpha = 1);

    public double Hue { readonly get; set; }

    public double Saturation { readonly get; set; }

    public double Value { readonly get; set; }

    public double Alpha { readonly get; set; }

    public readonly Color ToColor();

    public static implicit operator Color(HsvColor hsv);

    public static explicit operator HsvColor(Color color);

    public static explicit operator HsvColor(HslColor color);

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Hue property")]
    public double H;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Saturation property")]
    public double S;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Value property")]
    public double V;

    [Obsolete("This field is marked deprecated, and will be removed in a future version. Please replace with the HsvColor.Alpha property")]
    public double A;
}

PR Checklist

Please check if your PR fulfills the following requirements:

• Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
• Based off latest main branch of toolkit
• Tested code with current supported SDKs
• Tests for the changes have been added (if applicable)
• Header has been added to all new source files
• Contains NO breaking changes

By keeping the old fields available and using the new properties to wrap them, breaking changes have been averted. However, the plan would be to removed these deprecated APIs in future versions.

Other information

Note that the ObsoleteAttribute messages contain a recommendation for how to migrate to the new API. All these migrations have complete behavioral parity, except the fields/properties in HslColor and HsvColor which are now clamped to a valid range.