refactor: improve signature of control item components woth better management of labels (#1314) (#1316)

Improve API of checkbox item, checkbox item indeterminate and radio item signatures to use first the label as not-named parameter and then the binding so as to be aligned with switch item signature

Closes #1314

Assisted-by: GitHub Copilot
Reviewed-by: Ludovic Pinel <ludovic.pinel@orange.com>
Reviewed-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Ludovic Pinel <ludovic.pinel@orange.com>
Co-authored-by: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>
Signed-off-by: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>

Author: pylapp

AGENTS.md

@@ -564,16 +564,16 @@ OUDSCheckbox(isOn: $isOn, accessibilityLabel: "Some label to vocalize")
 or with texts and image:
 ```swift
 @Published var isOn: Bool = true
-OUDSCheckboxItem(isOn: $isOn,
-                 label: "An important text",
+OUDSCheckboxItem("An important text",
+                 isOn: $isOn,
                  description: "A secondary text",
                  icon: Image(decorative: "image_name"))
 ```
 
 or only with one text:
 ```swift
 @Published var isOn: Bool = true
-OUDSCheckboxItem(isOn: $isOn, label: "Hello world")
+OUDSCheckboxItem("Hello world", isOn: $isOn)
 ```
 
 Checkboxes can be wrapped inside a checkbox picker.
@@ -615,15 +615,15 @@ OUDSRadio(isOn: $selection, accessibilityLabel: "Some label to vocalized")
 or with texts and image:
 ```swift
 @Published var isOn: Bool = true
-OUDSRadioItem(isOn: $isOn,
-              label: "Some text",
+OUDSRadioItem("Some text",
+              isOn: $isOn,
               icon: Image(decorative: "image_name"))
 ```
 
 or only with one text:
 ```swift
 @Published var isOn: Bool = true
-OUDSRadioItem(isOn: $isOn, label: "Some text")
+OUDSRadioItem("Some text", isOn: $isOn)
 ```
 
 Radio buttons can be wrapped inside a radio picker.

CHANGELOG.md

@@ -10,6 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `alert message` component (Orange-OpenSource/ouds-ios#1159)
 
+### Changed
+
+- Signatures of control-item-based components (Orange-OpenSource/ouds-ios#1314)
+
 ### Fixed
 
 - Size of loader for `button` component (Orange-OpenSource/ouds-ios#1296)

OUDS/Core/Components/Sources/Controls/Checkbox/OUDSCheckbox.swift

@@ -110,7 +110,7 @@ public struct OUDSCheckbox: View {
     /// **The design system does not allow to have both an error or read only situation and a disabled state for the component.**
     ///
     /// - Parameters:
-    ///    - isOn: A binding to a property that determines wether the indicator is ticked (selected) or not (not selected)
+    ///    - isOn: A binding to a property that determines whether the indicator is ticked (selected) or not (not selected)
     ///    - accessibilityLabel: The accessibility label the component must have
     ///    - isError: True if the look and feel of the component must reflect an error state, default set to `false`
     ///    - isReadOnly: True if the look and feel of the component must reflect a read only state, default set to `false`

OUDS/Core/Components/Sources/Controls/Checkbox/OUDSCheckboxIndeterminate.swift

@@ -110,7 +110,7 @@ public struct OUDSCheckboxIndeterminate: View {
     /// **The design system does not allow to have both an error situation and a disabled state for the component.**
     ///
     /// - Parameters:
-    ///    - selection: A binding to a property that determines wether the indicator is ticked, unticked or preticked.
+    ///    - selection: A binding to a property that determines whether the indicator is ticked, unticked or preticked.
     ///    - accessibilityLabel: The accessibility label the component must have
     ///    - isError: True if the look and feel of the component must reflect an error state, default set to `false`
     ///    - isReadOnly: True if the look and feel of the component must reflect a read only state, default set to `false`

OUDS/Core/Components/Sources/Controls/Checkbox/OUDSCheckboxItem.swift

@@ -68,48 +68,48 @@ import SwiftUI
 ///
 ///     // A leading checkbox with a label.
 ///     // The default layout will be used here.
-///     OUDSCheckboxItem(isOn: $isOn, label: "Hello world")
+///     OUDSCheckboxItem("Hello world", isOn: $isOn)
 ///
 ///     // A leading checkbox with a label, but in read only mode (user cannot interact yet, but not disabled).
 ///     // The default layout will be used here.
-///     OUDSCheckboxItem(isOn: $isOn, label: "Hello world", isReadOnly: true)
+///     OUDSCheckboxItem("Hello world", isOn: $isOn, isReadOnly: true)
 ///
 ///     // A leading checkbox with a label and a description as helper text.
 ///     // The default layout will be used here.
-///     OUDSCheckboxItem(isOn: $isOn, label: "Bazinga!", description: "Doll-Dagga Buzz-Buzz Ziggety-Zag")
+///     OUDSCheckboxItem("Bazinga!", isOn: $isOn, description: "Doll-Dagga Buzz-Buzz Ziggety-Zag")
 ///
 ///     // A trailing checkbox with a label, a description and an icon.
 ///     // The reversed layout will be used here.
-///     OUDSCheckboxItem(isOn: $isOn,
-///                      label: "We live in a fabled world",
+///     OUDSCheckboxItem("We live in a fabled world",
+///                      isOn: $isOn,
 ///                      description: "Of dreaming boys and wide-eyed girls",
 ///                      isReversed: true,
 ///                      icon: Image(decorative: "ic_heart"))
 ///
 ///     // If on error, add an error message can help user to understand error context
-///     OUDSCheckboxItem(isOn: $isOn,
-///                      label: "We live in a fabled world",
+///     OUDSCheckboxItem("We live in a fabled world",
+///                      isOn: $isOn,
 ///                      isError: true,
 ///                      errorText: "Something wrong",
 ///                      hasDivider: true)
 ///
 ///     // A leading checkbox with a label, but disabled.
 ///     // The default layout will be used here.
-///     OUDSCheckboxItem(isOn: $isOn, label: "Hello world")
+///     OUDSCheckboxItem("Hello world", isOn: $isOn)
 ///         .disabled(true)
 ///
 ///     // Never disable a read only or an error-related checkbox as it will crash
 ///     // This is forbidden by design!
-///     OUDSCheckboxItem(isOn: $isOn, label: "Hello world", isError: true).disabled(true) // fatal error
-///     OUDSCheckboxItem(isOn: $isOn, label: "Hello world", isReadyOnly: true).disabled(true) // fatal error
+///     OUDSCheckboxItem("Hello world", isOn: $isOn, isError: true).disabled(true) // fatal error
+///     OUDSCheckboxItem("Hello world", isOn: $isOn, isReadyOnly: true).disabled(true) // fatal error
 /// ```
 ///
 /// If you need to flip your icon depending to the layout direction or not (e.g. if RTL mode lose semantics  / meanings):
 /// ```swift
 ///     @Environment(\.layoutDirection) var layoutDirection
 ///
-///     OUDSCheckboxItem(isOn: $selection,
-///                      label: "Cocorico !",
+///     OUDSCheckboxItem("Cocorico !",
+///                      isOn: $selection,
 ///                      icon: Image(systemName: "figure.handball"),
 ///                      flipIcon: layoutDirection == .rightToLeft,
 ///                      isInversed: layoutDirection == .rightToLeft)
@@ -173,12 +173,12 @@ public struct OUDSCheckboxItem: View {
     /// provide the localized string if key is stored in another bundle.**
     ///
     /// - Parameters:
-    ///   - isOn: A binding to a property that determines wether the indicator is ticked (selected) or not (unselected)
+    ///   - isOn: A binding to a property that determines whether the indicator is ticked (selected) or not (unselected)
     ///   - label: The main label text of the checkbox, must not be empty
-    ///   - description: An additonal helper text, a description, which should not be empty, default set to `nil`. Will be repalced by `errorText` in case of error.
-    ///   - icon: An optional icon,  default set to `nil`
-    ///   - flipIcon: Default set to `false`, set to true` to reverse the image (i.e. flip vertically)
-    ///   - isReversed: `true` if the checkbox indicator must be in trailing position,` false` otherwise. Default to `false`
+    ///   - description: An additional helper text, a description, which should not be empty, default set to `nil`. Will be replaced by `errorText` in case of error.
+    ///   - icon: An optional icon, default set to `nil`
+    ///   - flipIcon: Default set to `false`, set to `true` to reverse the image (i.e. flip vertically)
+    ///   - isReversed: `true` if the checkbox indicator must be in trailing position, `false` otherwise. Default to `false`
     ///   - isError: `true` if the look and feel of the component must reflect an error state, default set to `false`
     ///   - errorText: An optional error message to display at the bottom. This message is ignored if `isError` is `false`.
     ///   The `errorText`can be different if switch is selected or not.
@@ -188,6 +188,7 @@ public struct OUDSCheckboxItem: View {
     ///     When `false`, no specific width constraint is applied, allowing the component to size itself or follow external
     ///     modifier. Defaults to `false`.
     ///   - action: An additional action to trigger when the checkbox has been pressed
+    @available(*, deprecated, message: "Use instead OUDSCheckboxItem(:isOn:)")
     public init(isOn: Binding<Bool>,
                 label: String,
                 description: String? = nil,
@@ -200,6 +201,63 @@ public struct OUDSCheckboxItem: View {
                 hasDivider: Bool = false,
                 constrainedMaxWidth: Bool = false,
                 action: (() -> Void)? = nil)
+    {
+        self.init(label,
+                  isOn: isOn,
+                  description: description,
+                  icon: icon,
+                  flipIcon: flipIcon,
+                  isReversed: isReversed,
+                  isError: isError,
+                  errorText: errorText,
+                  isReadOnly: isReadOnly,
+                  hasDivider: hasDivider,
+                  constrainedMaxWidth: constrainedMaxWidth,
+                  action: action)
+    }
+
+    /// Creates a checkbox with label and optional helper text, icon, divider.
+    ///
+    /// ```swift
+    ///     OUDSCheckboxItem("Virgin Holy Lava",
+    ///                      isOn: $isOn,
+    ///                      description: "Very spicy",
+    ///                      icon: Image(systemName: "flame")
+    /// ```
+    ///
+    /// **The design system does not allow to have both an error situation and a read only mode for the component.**
+    ///
+    /// **Remark: If `label` and `description` strings are wording keys from strings catalog stored in `Bundle.main`, they are automatically localized. Else, prefer to
+    /// provide the localized string if key is stored in another bundle.**
+    ///
+    /// - Parameters:
+    ///   - label: The main label text of the checkbox, must not be empty
+    ///   - isOn: A binding to a property that determines whether the indicator is ticked (selected) or not (unselected)
+    ///   - description: An additional helper text, a description, which should not be empty, default set to `nil`. Will be replaced by `errorText` in case of error.
+    ///   - icon: An optional icon, default set to `nil`
+    ///   - flipIcon: Default set to `false`, set to `true` to reverse the image (i.e. flip vertically)
+    ///   - isReversed: `true` if the checkbox indicator must be in trailing position, `false` otherwise. Default to `false`
+    ///   - isError: `true` if the look and feel of the component must reflect an error state, default set to `false`
+    ///   - errorText: An optional error message to display at the bottom. This message is ignored if `isError` is `false`.
+    ///   The `errorText`can be different if switch is selected or not.
+    ///   - isReadOnly: True if component is in read only, i.e. not really disabled but user cannot interact with it yet, default set to `false`
+    ///   - hasDivider: If `true` a divider is added at the bottom of the view, by default set to `false`
+    ///   - constrainedMaxWidth: When `true`, the item width is constrained to a maximum value defined by the design system.
+    ///     When `false`, no specific width constraint is applied, allowing the component to size itself or follow external
+    ///     modifier. Defaults to `false`.
+    ///   - action: An additional action to trigger when the checkbox has been pressed
+    public init(_ label: String,
+                isOn: Binding<Bool>,
+                description: String? = nil,
+                icon: Image? = nil,
+                flipIcon: Bool = false,
+                isReversed: Bool = false,
+                isError: Bool = false,
+                errorText: String? = nil,
+                isReadOnly: Bool = false,
+                hasDivider: Bool = false,
+                constrainedMaxWidth: Bool = false,
+                action: (() -> Void)? = nil)
     {
         if isError, isReadOnly {
             OL.fatal("It is forbidden by design to have an OUDSCheckboxItem in an error context and in read only mode")