Add oklch() color function and to-oklch() method (#10431)

* Add oklch() color function and to-oklch() method

Add support for the Oklch perceptually uniform color space:

- Add oklch(lightness, chroma, hue, alpha?) global function
- Add color.to-oklch() method returning {lightness, chroma, hue, alpha}
- Add C++ API: OklchColor struct, Color::from_oklch(), Color::to_oklch()
- Add FFI functions: slint_color_from_oklch, slint_color_to_oklch
- Add interpreter and LSP preview support
- Add documentation and tests

* Add Wikipedia link for Oklch color space in documentation

* Add percentage and angle support for oklch() parameters

- Lightness can be specified as percentage (0% to 100%)
- Chroma can be specified as percentage (0% to 100%, where 100% = 0.4)
- Hue can be specified as angle (e.g., 180deg, 0.5turn)

* Add angle support for hsv() hue parameter

The hue parameter can now be specified as an angle (e.g., 240deg, 1turn)
in addition to a plain float value.

* Fix alignment in C++ slint_color.h to_oklch method

Author: task-jp

api/cpp/cbindgen.rs

@@ -508,7 +508,9 @@ fn gen_corelib(
             "slint_color_mix",
             "slint_color_with_alpha",
             "slint_color_to_hsva",
-            "slint_color_from_hsva",],
+            "slint_color_from_hsva",
+            "slint_color_from_oklch",
+            "slint_color_to_oklch",],
             "slint_color_internal.h",
             "",
         ),

api/cpp/include/slint_color.h

@@ -49,6 +49,20 @@ struct HsvaColor
     float alpha;
 };
 
+/// OklchColor stores the lightness, chroma, hue, and alpha components of a color in the Oklch
+/// color space (a perceptually uniform color space).
+struct OklchColor
+{
+    /// The lightness component, between 0 (black) and 1 (white).
+    float lightness;
+    /// The chroma component (saturation), typically between 0 (grayscale) and ~0.4 (vivid).
+    float chroma;
+    /// The hue component in degrees between 0 and 360.
+    float hue;
+    /// The alpha component, between 0 and 1.
+    float alpha;
+};
+
 /// Color represents a color in the Slint run-time, represented using 8-bit channels for
 /// red, green, blue and the alpha (opacity).
 class Color
@@ -154,6 +168,28 @@ class Color
         return hsv;
     }
 
+    /// Construct a color from the Oklch color space components.
+    /// Oklch is a perceptually uniform color space.
+    /// The lightness is expected to be in the range between 0 and 1,
+    /// chroma typically between 0 and 0.4, hue between 0 and 360,
+    /// and alpha between 0 and 1.
+    [[nodiscard]] static Color from_oklch(float l, float c, float h, float a)
+    {
+        Color ret;
+        ret.inner = cbindgen_private::types::slint_color_from_oklch(l, c, h, a);
+        return ret;
+    }
+
+    /// Convert this color to the Oklch color space.
+    /// @returns a new OklchColor.
+    [[nodiscard]] OklchColor to_oklch() const
+    {
+        OklchColor oklch {};
+        cbindgen_private::types::slint_color_to_oklch(&inner, &oklch.lightness, &oklch.chroma,
+                                                      &oklch.hue, &oklch.alpha);
+        return oklch;
+    }
+
     /// Returns the red channel of the color as u8 in the range 0..255.
     [[nodiscard]] uint8_t red() const { return inner.red; }
 

docs/astro/src/content/docs/reference/colors-and-brushes.mdx

@@ -67,6 +67,16 @@ Returns a color using HSV (Hue, Saturation, Value) coordinates. The hue paramete
 representing degrees (0-360) and wraps around (e.g., 480 becomes 120).
 The saturation, value, and optional alpha parameter are expected to be within the range of 0 and 1.
 
+### oklch(l: float, c: float, h: float) -> color
+### oklch(l: float, c: float, h: float, a: float) -> color
+
+Returns a color using the [Oklch color space](https://en.wikipedia.org/wiki/Oklab_color_space) (a perceptually uniform color space).
+
+- `l` (lightness): 0 (black) to 1 (white), or 0% to 100%
+- `c` (chroma): 0 (grayscale) to ~0.4 (vivid), or 0% to 100% (where 100% = 0.4)
+- `h` (hue): 0-360 degrees, or as an angle (e.g., `180deg`, `0.5turn`)
+- `a` (alpha): 0-1, defaults to 1
+
 ## Color Methods
 All colors and brushes define the following methods:
 
@@ -105,6 +115,12 @@ Returns a new color with the alpha value set to `alpha` (between 0 and 1)
 Converts this color to the HSV color space and returns a struct with the `hue`, `saturation`, `value`,
 and `alpha` fields. `hue` is between 0 and 360 while `saturation`, `value`, and `alpha` are between 0 and 1.
 
+### to-oklch() -> \{ lightness: float, chroma: float, hue: float, alpha: float }
+
+Converts this color to the [Oklch color space](https://en.wikipedia.org/wiki/Oklab_color_space) and returns a struct with the `lightness`, `chroma`, `hue`,
+and `alpha` fields. `lightness` is between 0 and 1, `chroma` is typically between 0 and ~0.4,
+`hue` is between 0 and 360, and `alpha` is between 0 and 1.
+
 ## Linear Gradients
 
 Linear gradients describe smooth, colorful surfaces. They're specified using an angle and a series of

internal/compiler/builtin_macros.rs

@@ -87,6 +87,7 @@ pub fn lower_macro(
         }
         BuiltinMacroFunction::Rgb => rgb_macro(n, sub_expr.collect(), diag),
         BuiltinMacroFunction::Hsv => hsv_macro(n, sub_expr.collect(), diag),
+        BuiltinMacroFunction::Oklch => oklch_macro(n, sub_expr.collect(), diag),
     }
 }
 
@@ -277,8 +278,22 @@ fn hsv_macro(
         );
         return Expression::Invalid;
     }
-    let mut arguments: Vec<_> =
-        args.into_iter().map(|(expr, n)| expr.maybe_convert_to(Type::Float32, &n, diag)).collect();
+    let mut arguments: Vec<_> = args
+        .into_iter()
+        .enumerate()
+        .map(|(i, (expr, n))| {
+            // For hue (index 0), convert angle to degrees
+            if i == 0 && expr.ty() == Type::Angle {
+                Expression::BinaryExpression {
+                    lhs: Box::new(expr),
+                    rhs: Box::new(Expression::NumberLiteral(1., Unit::Deg)),
+                    op: '/',
+                }
+            } else {
+                expr.maybe_convert_to(Type::Float32, &n, diag)
+            }
+        })
+        .collect();
     if arguments.len() < 4 {
         arguments.push(Expression::NumberLiteral(1., Unit::None))
     }
@@ -289,6 +304,51 @@ fn hsv_macro(
     }
 }
 
+fn oklch_macro(
+    node: &dyn Spanned,
+    args: Vec<(Expression, Option<NodeOrToken>)>,
+    diag: &mut BuildDiagnostics,
+) -> Expression {
+    if args.len() < 3 || args.len() > 4 {
+        diag.push_error(
+            format!("This function needs 3 or 4 arguments, but {} were provided", args.len()),
+            node,
+        );
+        return Expression::Invalid;
+    }
+    let mut arguments: Vec<_> = args
+        .into_iter()
+        .enumerate()
+        .map(|(i, (expr, n))| {
+            // For chroma (index 1), 100% should equal 0.4, not 1.0
+            if i == 1 && expr.ty() == Type::Percent {
+                Expression::BinaryExpression {
+                    lhs: Box::new(expr),
+                    rhs: Box::new(Expression::NumberLiteral(0.004, Unit::None)),
+                    op: '*',
+                }
+            // For hue (index 2), convert angle to degrees
+            } else if i == 2 && expr.ty() == Type::Angle {
+                Expression::BinaryExpression {
+                    lhs: Box::new(expr),
+                    rhs: Box::new(Expression::NumberLiteral(1., Unit::Deg)),
+                    op: '/',
+                }
+            } else {
+                expr.maybe_convert_to(Type::Float32, &n, diag)
+            }
+        })
+        .collect();
+    if arguments.len() < 4 {
+        arguments.push(Expression::NumberLiteral(1., Unit::None))
+    }
+    Expression::FunctionCall {
+        function: BuiltinFunction::Oklch.into(),
+        arguments,
+        source_location: Some(node.to_source_location()),
+    }
+}
+
 fn debug_macro(
     node: &dyn Spanned,
     args: Vec<(Expression, Option<NodeOrToken>)>,

internal/compiler/expression_tree.rs

@@ -75,6 +75,7 @@ pub enum BuiltinFunction {
     StringToUppercase,
     ColorRgbaStruct,
     ColorHsvaStruct,
+    ColorOklchStruct,
     ColorBrighter,
     ColorDarker,
     ColorTransparentize,
@@ -84,6 +85,7 @@ pub enum BuiltinFunction {
     ArrayLength,
     Rgb,
     Hsv,
+    Oklch,
     ColorScheme,
     SupportsNativeMenuBar,
     /// Setup the menu bar
@@ -142,6 +144,7 @@ pub enum BuiltinMacroFunction {
     /// transform the argument so it is always rgb(r, g, b, a) with r, g, b between 0 and 255.
     Rgb,
     Hsv,
+    Oklch,
     /// transform `debug(a, b, c)` into debug `a + " " + b + " " + c`
     Debug,
 }
@@ -231,6 +234,16 @@ declare_builtin_function_types!(
         .collect(),
         name: BuiltinPublicStruct::Color.into(),
     })),
+    ColorOklchStruct: (Type::Color) -> Type::Struct(Rc::new(Struct {
+        fields: IntoIterator::into_iter([
+            (SmolStr::new_static("lightness"), Type::Float32),
+            (SmolStr::new_static("chroma"), Type::Float32),
+            (SmolStr::new_static("hue"), Type::Float32),
+            (SmolStr::new_static("alpha"), Type::Float32),
+        ])
+        .collect(),
+        name: BuiltinPublicStruct::Color.into(),
+    })),
     ColorBrighter: (Type::Brush, Type::Float32) -> Type::Brush,
     ColorDarker: (Type::Brush, Type::Float32) -> Type::Brush,
     ColorTransparentize: (Type::Brush, Type::Float32) -> Type::Brush,
@@ -247,6 +260,7 @@ declare_builtin_function_types!(
     ArrayLength: (Type::Model) -> Type::Int32,
     Rgb: (Type::Int32, Type::Int32, Type::Int32, Type::Float32) -> Type::Color,
     Hsv: (Type::Float32, Type::Float32, Type::Float32, Type::Float32) -> Type::Color,
+    Oklch: (Type::Float32, Type::Float32, Type::Float32, Type::Float32) -> Type::Color,
     ColorScheme: () -> Type::Enumeration(
         typeregister::BUILTIN.with(|e| e.enums.ColorScheme.clone()),
     ),
@@ -343,6 +357,7 @@ impl BuiltinFunction {
             | BuiltinFunction::StringToUppercase => true,
             BuiltinFunction::ColorRgbaStruct
             | BuiltinFunction::ColorHsvaStruct
+            | BuiltinFunction::ColorOklchStruct
             | BuiltinFunction::ColorBrighter
             | BuiltinFunction::ColorDarker
             | BuiltinFunction::ColorTransparentize
@@ -359,6 +374,7 @@ impl BuiltinFunction {
             BuiltinFunction::ArrayLength => true,
             BuiltinFunction::Rgb => true,
             BuiltinFunction::Hsv => true,
+            BuiltinFunction::Oklch => true,
             BuiltinFunction::SetTextInputFocused => false,
             BuiltinFunction::TextInputFocused => false,
             BuiltinFunction::ImplicitLayoutInfo(_) => false,
@@ -429,6 +445,7 @@ impl BuiltinFunction {
             | BuiltinFunction::StringToUppercase => true,
             BuiltinFunction::ColorRgbaStruct
             | BuiltinFunction::ColorHsvaStruct
+            | BuiltinFunction::ColorOklchStruct
             | BuiltinFunction::ColorBrighter
             | BuiltinFunction::ColorDarker
             | BuiltinFunction::ColorTransparentize
@@ -438,6 +455,7 @@ impl BuiltinFunction {
             BuiltinFunction::ArrayLength => true,
             BuiltinFunction::Rgb => true,
             BuiltinFunction::Hsv => true,
+            BuiltinFunction::Oklch => true,
             BuiltinFunction::ImplicitLayoutInfo(_) => true,
             BuiltinFunction::ItemAbsolutePosition => true,
             BuiltinFunction::SetTextInputFocused => false,

internal/compiler/generator/cpp.rs

@@ -3981,6 +3981,9 @@ fn compile_builtin_function_call(
         BuiltinFunction::ColorHsvaStruct => {
             format!("{}.to_hsva()", a.next().unwrap())
         }
+        BuiltinFunction::ColorOklchStruct => {
+            format!("{}.to_oklch()", a.next().unwrap())
+        }
         BuiltinFunction::ColorBrighter => {
             format!("{}.brighter({})", a.next().unwrap(), a.next().unwrap())
         }
@@ -4018,6 +4021,14 @@ fn compile_builtin_function_call(
                 a = a.next().unwrap(),
             )
         }
+        BuiltinFunction::Oklch => {
+            format!("slint::Color::from_oklch(std::clamp(static_cast<float>({l}), 0.f, 1.f), std::max(static_cast<float>({c}), 0.f), static_cast<float>({h}), std::clamp(static_cast<float>({alpha}), 0.f, 1.f))",
+                l = a.next().unwrap(),
+                c = a.next().unwrap(),
+                h = a.next().unwrap(),
+                alpha = a.next().unwrap(),
+            )
+        }
         BuiltinFunction::ColorScheme => {
             format!("{}.color_scheme()", access_window_field(ctx))
         }

internal/compiler/generator/rust.rs

@@ -3232,6 +3232,7 @@ fn compile_builtin_function_call(
         BuiltinFunction::StringToUppercase => quote!(sp::SharedString::from(#(#a)*.to_uppercase())),
         BuiltinFunction::ColorRgbaStruct => quote!( #(#a)*.to_argb_u8()),
         BuiltinFunction::ColorHsvaStruct => quote!( #(#a)*.to_hsva()),
+        BuiltinFunction::ColorOklchStruct => quote!( #(#a)*.to_oklch()),
         BuiltinFunction::ColorBrighter => {
             let x = a.next().unwrap();
             let factor = a.next().unwrap();
@@ -3287,6 +3288,16 @@ fn compile_builtin_function_call(
                 sp::Color::from_hsva(#h as f32, s, v, a)
             })
         }
+        BuiltinFunction::Oklch => {
+            let (l, c, h, alpha) =
+                (a.next().unwrap(), a.next().unwrap(), a.next().unwrap(), a.next().unwrap());
+            quote!({
+                let l: f32 = (#l as f32).max(0.).min(1.) as f32;
+                let c: f32 = (#c as f32).max(0.) as f32;
+                let alpha: f32 = (#alpha as f32).max(0.).min(1.) as f32;
+                sp::Color::from_oklch(l, c, #h as f32, alpha)
+            })
+        }
         BuiltinFunction::ColorScheme => {
             let window_adapter_tokens = access_window_adapter_field(ctx);
             quote!(sp::WindowInner::from_pub(#window_adapter_tokens.window()).color_scheme())

internal/compiler/llr/optim_passes/inline_expressions.rs

@@ -123,6 +123,7 @@ fn builtin_function_cost(function: &BuiltinFunction) -> isize {
         BuiltinFunction::StringToUppercase => ALLOC_COST,
         BuiltinFunction::ColorRgbaStruct => 50,
         BuiltinFunction::ColorHsvaStruct => 50,
+        BuiltinFunction::ColorOklchStruct => 50,
         BuiltinFunction::ColorBrighter => 50,
         BuiltinFunction::ColorDarker => 50,
         BuiltinFunction::ColorTransparentize => 50,
@@ -132,6 +133,7 @@ fn builtin_function_cost(function: &BuiltinFunction) -> isize {
         BuiltinFunction::ArrayLength => 50,
         BuiltinFunction::Rgb => 50,
         BuiltinFunction::Hsv => 50,
+        BuiltinFunction::Oklch => 50,
         BuiltinFunction::ImplicitLayoutInfo(_) => isize::MAX,
         BuiltinFunction::ItemAbsolutePosition => isize::MAX,
         BuiltinFunction::RegisterCustomFontByPath => isize::MAX,

internal/compiler/lookup.rs

@@ -819,6 +819,7 @@ impl LookupObject for ColorFunctions {
         None.or_else(|| f("rgb", BuiltinMacroFunction::Rgb))
             .or_else(|| f("rgba", BuiltinMacroFunction::Rgb))
             .or_else(|| f("hsv", BuiltinMacroFunction::Hsv))
+            .or_else(|| f("oklch", BuiltinMacroFunction::Oklch))
     }
 }
 
@@ -989,7 +990,10 @@ impl LookupObject for ColorExpression<'_> {
         f: &mut impl FnMut(&SmolStr, LookupResult) -> Option<R>,
     ) -> Option<R> {
         let member_function = |f: BuiltinFunction| {
-            let base = if f == BuiltinFunction::ColorHsvaStruct && self.0.ty() == Type::Brush {
+            let base = if (f == BuiltinFunction::ColorHsvaStruct
+                || f == BuiltinFunction::ColorOklchStruct)
+                && self.0.ty() == Type::Brush
+            {
                 Expression::Cast { from: Box::new(self.0.clone()), to: Type::Color }
             } else {
                 self.0.clone()
@@ -1022,6 +1026,7 @@ impl LookupObject for ColorExpression<'_> {
             .or_else(|| f("blue", field_access("blue")))
             .or_else(|| f("alpha", field_access("alpha")))
             .or_else(|| f("to-hsv", member_function(BuiltinFunction::ColorHsvaStruct)))
+            .or_else(|| f("to-oklch", member_function(BuiltinFunction::ColorOklchStruct)))
             .or_else(|| f("brighter", member_function(BuiltinFunction::ColorBrighter)))
             .or_else(|| f("darker", member_function(BuiltinFunction::ColorDarker)))
             .or_else(|| f("transparentize", member_function(BuiltinFunction::ColorTransparentize)))

internal/compiler/tests/syntax/lookup/color.slint

@@ -50,7 +50,13 @@ export X := Rectangle {
 //                                 >  <error{This function needs 3 or 4 arguments, but 5 were provided}
         property<color> c5: Colors.hsv(1,2,3,4,5);
 //                                 > <error{This function needs 3 or 4 arguments, but 5 were provided}
+        property<color> c6: Colors.oklch(1,2,3,4,5);
+//                                 >   <error{This function needs 3 or 4 arguments, but 5 were provided}
+        property<color> c7: oklch(0.5, 0.1, 180);
+        property<color> c8: oklch(0.5, 0.1, 180, 0.8);
 
+        // Test to-oklch() method
+        property<{ lightness: float, chroma: float, hue: float, alpha: float }> oklch-result: Colors.blue.to-oklch();
 
     }