[#759] Update components and modules documentation to add a descripti…

…on of the API (#803) * Add api doc for ODSBanner * Add api doc for odsToolBar modifier * Add Api documentation for Buttons * Add Api documentation for Cards * Add Api documentation for Chips * Apply same style on doc * Add Api documentation for ListItems * Update doc for empty state * Update changelog * Rename the Recirculation module (classes, resources, wording keys,...) to moreApps * Rollback * Rollback * review Reviewed-by: Pierre-Yves Lapersonne <[email protected]>
Orange-OpenSource · Apr 11, 2024 · 132b5ac · 132b5ac
1 parent 7482732
commit 132b5ac
Show file tree

Hide file tree

Showing 12 changed files with 314 additions and 54 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,7 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- [DemoApp/SDK] Rename recirculation module to MoreApps, and use EmptyState Assets from Theme bundle ([#801](https://github.com/Orange-OpenSource/ods-ios/issues/801))
+- [Doc] Update components and modules documentation to add a description of the API ([#759](https://github.com/Orange-OpenSource/ods-ios/issues/759))
+- [DemoApp/SDK] Rename "Recirculation" module to "MoreApps", and use "EmptyState" assets from Theme bundle ([#801](https://github.com/Orange-OpenSource/ods-ios/issues/801))
 - [Tooling] Update dependency SwiftFormat/CLI to v0.53.5
 - [DemoApp] The main color names, visible on the screen are not vocalized ([#720](https://github.com/Orange-OpenSource/ods-ios/issues/720))
 - [Doc] Improve release documentation

diff --git a/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Cards/ODSCardSmall.swift b/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Cards/ODSCardSmall.swift
@@ -39,8 +39,8 @@ public struct ODSCardSmall: View {
     ///  - title: Title displayed into the card.
     ///  - imageSource: Image from source [ODSImage.Source] displayed into the card.
     ///  - subtitle: Optional subtitle displayed into the card,d efault set to `nil`
-    ///  - titleAccessibleLineLimit: The line limit to apply to the title is size category is accessibility category, default set to `nil`
-    ///  - subtitleAccessibleLineLimit: The line limit to apply to the subtitle is size category is accessibility category, default set to `nil`
+    ///  - titleAccessibleLineLimit: The line limit to apply to the title if size category is accessibility category, default set to `nil`
+    ///  - subtitleAccessibleLineLimit: The line limit to apply to the subtitle if size category is accessibility category, default set to `nil`
     public init(title: Text, imageSource: ODSImage.Source, subtitle: Text? = nil, titleAccessibleLineLimit: Int? = nil, subtitleAccessibleLineLimit: Int? = nil) {
         self.title = title
         self.subtitle = subtitle

diff --git a/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Lists/ODSListItem.swift b/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Lists/ODSListItem.swift
@@ -167,7 +167,7 @@ public struct ODSListItem: View {
     ///     - title: The primary text of the list item
     ///     - subtitle: The secondary text of the list item (optional)
     ///     - subtitleNumberOfLines: If `subtitle` is provided, it is possible to limit the text
-    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not   design compliant).
+    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be careful: this is not design compliant).
     ///     - leading: The leading icon of the list item (optional)
     ///
     public init(
@@ -205,7 +205,7 @@ public struct ODSListItem: View {
     ///     - title: The primary text of the list item
     ///     - subtitle: The secondary text of the list item (optional)
     ///     - subtitleNumberOfLines: If `subtitle` is provided, it is possible to limit the text
-    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not   design compliant).
+    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be careful: this is not design compliant).
     ///     - leading: The leading icon of the list item (optional)
     ///     - trailingText The text on trailing
     ///     - trailingIButtonAction: The action the i button on trailing
@@ -227,7 +227,7 @@ public struct ODSListItem: View {
     ///     - title: The primary text of the list item
     ///     - subtitle: The secondary text of the list item (optional)
     ///     - subtitleNumberOfLines: If `subtitle` is provided, it is possible to limit the text
-    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not   design compliant).
+    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be careful: this is not   design compliant).
     ///     - leading: The leading icon of the list item (optional)
     ///     - trailingText The text on trailing
     ///     - trailingToggleIsOn: The binding to a property that determines whether the toggle is on or off.
@@ -249,7 +249,7 @@ public struct ODSListItem: View {
     ///     - title: The primary text of the list item
     ///     - subtitle: The secondary text of the list item (optional)
     ///     - subtitleNumberOfLines: If `subtitle` is provided, it is possible to limit the text
-    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not   design compliant).
+    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not design compliant).
     ///     - leading: The leading icon of the list item (optional)
     ///     - trailingText The text on trailing
     ///     - trailingCheckmarkIsSelected: The flag to indicate if checkmark is visbile or not.
@@ -270,7 +270,7 @@ public struct ODSListItem: View {
     ///     - title: The primary text of the list item
     ///     - subtitle: The secondary text of the list item (optional)
     ///     - subtitleNumberOfLines: If `subtitle` is provided, it is possible to limit the text
-    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be carefull: this is not   design compliant).
+    ///     to 1 line or 2 lines. If set to nil, no restriction is applied (be careful: this is not design compliant).
     ///     - leading: The leading icon of the list item (optional)
     ///     - trailing: The trailing element
     ///

diff --git a/...ignSystem/Sources/OrangeDesignSystem/Modules/MoreApps/Data/AppsPlusToMoreAppsMapper.swift b/...ignSystem/Sources/OrangeDesignSystem/Modules/MoreApps/Data/AppsPlusToMoreAppsMapper.swift
@@ -25,8 +25,7 @@ struct AppsPlusToMoreAppsMapper {
     }
 
     func appsSection(from section: AppsPlusSectionDTO) -> MoreAppsAppsListSection {
-        MoreAppsAppsListSection(description: section.description,
-                        apps: section.apps.map { appDetails(from: $0) })
+        MoreAppsAppsListSection(description: section.description, apps: section.apps.map { appDetails(from: $0) })
     }
 
     func appDetails(from details: AppsPlusAppDetailsDTO) -> MoreAppsAppDetails {

diff --git a/OrangeDesignSystemDemo/OrangeDesignSystemDemo/Resources/en.lproj/Localizable.strings b/OrangeDesignSystemDemo/OrangeDesignSystemDemo/Resources/en.lproj/Localizable.strings
@@ -395,13 +395,13 @@
 "screens.modules.empty_state.usage_no_data.buttonLabel" = "Search";
 "screens.modules.empty_state.usage.alert" = "%@ clicked";
 
-// =============================================
+// ====================================
 // MARK: - Screens - Modules - MoreApps
-// =============================================
+// ====================================
 
 "screens.modules.moreApps.title" = "MoreApps";
 "screens.modules.moreApps.title.setup" = "MoreApps: Setup";
-"screens.modules.moreApps.description" = "MoreApps (AppsPlus was a OMD Essential component) making Orange Apps discovery easier than ever.";
+"screens.modules.moreApps.description" = "MoreApps makes Orange Apps discovery easier than ever (based on AppsPlus which cas an OMD Essential component)";
 "screens.modules.moreApps.option.flatten_apps_sections" = "Uncategorize apps";
 "screens.modules.moreApps.option.use_embeded_data_source" = "Use local data";
 "screens.modules.moreApps.option.cache_more_apps_icons" = "Cache apps images";

diff --git a/docs/components/banners.md b/docs/components/banners.md
@@ -30,33 +30,16 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o
 
 ## Variants
 
-### No button
-
-```swift
-ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
-         imageSource: .image(Image("placeholder", bundle: Bundle.ods)))
-```
-
-### One button
-
-The button is placed under the text.
-
-```swift
-ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
-         imageSource: .image(Image("placeholder", bundle: Bundle.ods))) {
-             Button("Button") {
-                 // your action here
-             }
-}
-```
-
 ### Two buttons
 
 Button are placed under the text.
 
+#### SwiftUI examples
+
+- Without image
+
 ```swift
-ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
-         imageSource: .image(Image("placeholder", bundle: Bundle.ods))) {
+ODSBanner(text: "One to two lines is preferable on mobile and tablet.") {
     Button("Button 1") {
         // your action here
     }
@@ -67,10 +50,11 @@ ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
 }
 ```
 
-### Without image
-
+- With image from resourcess
+ 
 ```swift
-ODSBanner(text: "One to two lines is preferable on mobile and tablet.") {
+ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
+         imageSource: .image(Image("placeholder", bundle: Bundle.ods))) {
     Button("Button 1") {
         // your action here
     }
@@ -81,7 +65,8 @@ ODSBanner(text: "One to two lines is preferable on mobile and tablet.") {
 }
 ```
 
-### With image from url
+
+- With image from URL
 
 ```swift
 
@@ -100,4 +85,52 @@ ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
 }
 ```
 
+#### ODSBanner API
+
+| Parameter                       | Default&nbsp;value  | Description                                                                    |
+|-------------------------------- |---------------------|------------------------------------------------------------------------------- |
+| <b>`text: Text`</b>             |                     | Text displayed into the banner.                                                |
+| `imageSource: ODSImage.Source?` | `nil`               | Image displayed in the banner in a circle shape.                               |
+| `firstButton: Button<Text>`     |                     | Primary (leading) button displayed in the banner.                              |
+| `secondButton: Button<Text>`    |                     | Secondary (trailing) button displayed into the banner next to the primary one. |
+
+### One button
+
+The button is placed under the text.
+
+#### SwiftUI example
+
+```swift
+ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
+         imageSource: .image(Image("placeholder", bundle: Bundle.ods))) {
+             Button("Button") {
+                 // your action here
+             }
+}
+```
+
+#### ODSBanner API
+
+| Parameter                       | Default&nbsp;value | Description                                      |
+|---------------------------------|--------------------|--------------------------------------------------|
+| <b>`text: Text`</b>             |                    | Text displayed into the banner.                  |
+| `imageSource: ODSImage.Source?` | `nil`              | Image displayed in the banner in a circle shape. |
+| `button: Button<Text>`          |                    | Primary button displayed in the banner.          |
+
+
+### No button
+
+#### SwiftUI example
+
+```swift
+ODSBanner(text: "One to two lines is preferable on mobile and tablet.",
+         imageSource: .image(Image("placeholder", bundle: Bundle.ods)))
+```
+
+#### ODSBanner API
+
+| Parameter                       | Default&nbsp;value | Description                                      |
+|---------------------------------|--------------------|--------------------------------------------------|
+| <b>`text: Text`</b>             |                    | Text displayed into the banner.                  |
+| `imageSource: ODSImage.Source?` | `nil`              | Image displayed in the banner in a circle shape. |
 
diff --git a/docs/components/barsTool.md b/docs/components/barsTool.md
@@ -55,6 +55,29 @@ NavigationView {
 
 ```
 
+#### odsToolBar Modifier API
+
+| Parameter                       | Default&nbsp;value | Description                           |
+|---------------------------------|--------------------|---------------------------------------|
+| `items: ODSToolbarLabeledItems` |                    | Text items displayed into the banner. |
+
+
+#### ODSToolbarLabeledItems API
+
+| Parameter                                 | Default&nbsp;value | Description                                         |
+|-------------------------------------------|--------------------|---------------------------------------------------- |
+| `description1: ODSToolbarLabelDesription` |                    | Primary description of item in tool bar             |
+| `description2: ODSToolbarLabelDesription` |                    | Secondary description of item in tool bar           |
+| `description3: ODSToolbarLabelDesription?`| `nil`              | Terciary (optional) description of item in tool bar |
+
+#### ODSToolbarLabelDesriptionF API
+
+| Parameter                      | Default&nbsp;value | Description                 |
+|--------------------------------|--------------------|-----------------------------|
+| `text: String                  |                    | Text displayed in the item  |
+| `action: @escaping () -> Void` |                    | Action when item is clicked |
+<BR>
+
 ### With icon items
 
 ![tool bar icons light](images/bars_tool_icons_light.png) ![tool bar icons dark](images/bars_tool_icons_dark.png)
@@ -85,6 +108,33 @@ NavigationView {
 
 ```
 
+#### odsToolBar Modifier API
+
+| Parameter                    | Default value  | Description                           |
+|------------------------------|----------------|---------------------------------------|
+| `items: ODSToolbarIconItems` |                | Icon items displayed into the banner. |
+
+
+#### ODSToolbarIconsItems API
+
+| Parameter                                | Default value | Description                                        |
+|------------------------------------------|---------------|----------------------------------------------------|
+| `description1: ODSToolbarIconDesription` |               | First description of item in tool bar              |
+| `description2: ODSToolbarIconDesription` |               | Second description of item in tool bar             |
+| `description3: ODSToolbarIconDesription?`| `nil`         | Third (optional) description of item in tool bar   |
+| `description4: ODSToolbarIconDesription?`| `nil`         | Fourth (optional) description of item in tool bar  |
+| `description5: ODSToolbarIconDesription?`| `nil`         | Fifth (optional)  description  of item in tool bar |
+
+
+#### ODSToolbarIconDesription API
+
+| Parameter                      | Default value | Description                 |
+|--------------------------------|---------------|-----------------------------|
+| `systemName: String            |               | System name of the image    |
+| `action: @escaping () -> Void` |               | Action when item is clicked |
+<BR>
+
+
 ## Remarks
 
 As toolbar colors depends on theme, don't forget to add it to enviroment and call the view modifier __.toolBarColors(for:)__ to apply colors provided by the theme.

diff --git a/docs/components/buttons.md b/docs/components/buttons.md
@@ -64,9 +64,9 @@ Button variants range in style to denote emphasis. Use different styles and not
 
 ![Buttons lowest emphasis disabled](images/buttons_emphasis_lowest_disabled.png)
 ![Buttons lowest emphasis](images/buttons_emphasis_lowest.png)
-
-- **Implementation**
 
+#### SwiftUI example
+
 ```swift
 // High emphasis
 ODSButton(text: Text("Some text"),
@@ -79,6 +79,18 @@ ODSButton(text: Text("Some text"),
           emphasis: .lowest) {}
 ``` 
 
+#### ODSButton API
+
+| Parameter                   | Default&nbsp;value | Description                                                                       |
+|-----------------------------|--------------------|-----------------------------------------------------------------------------------|
+| <b>`text: Text`</b>         |                    | Text displayed into the banner.                                                   |
+| `image: Image?`             | `nil`              | Icon displayed in the button before the text.                                     |
+| <b>`emphasis: Emphasis`</b> |                    | The button's emphasis'.                                                           |
+| `fullWidth: Bool`           | `false`            | Defines the size of the button layout. Set to `true` means button takes all available space horizontally. Set to `false`, the size of the button is limited to the size of the text added by a padding round it.   
+| <b>`action: () -> Void`</b> |                    | Callback invoked on button click.                                                 |                                                                            
+
+<BR>
+
 ### Functional button
 
 If required, colour versions can also be used to inform users of positive or negative destructive actions.
@@ -93,6 +105,8 @@ If required, colour versions can also be used to inform users of positive or neg
 ![Buttons functional negative disabled](images/buttons_functionnal_disabled.png)
 ![Buttons functional negative](images/buttons_functional_negative.png)
 
+#### SwiftUI example
+
 ```swift
     // Negative button
     ODSFunctionalButton(text: Text("Some text"), style: .negative) 
@@ -113,12 +127,27 @@ If required, colour versions can also be used to inform users of positive or neg
     .disabled(true)
 ```
 
+#### ODSFunctionalButton API
+
+
+| Parameter                                 | Default&nbsp;value | Description                                                                       |
+|-------------------------------------------|--------------------|-----------------------------------------------------------------------------------|
+| <b>`text: Text`</b>                       |                    | Text displayed into the banner.                                                   |
+| `image: Image?`                           | `nil`              | Icon displayed in the button before the text.                                     |
+| <b>`style: ODSFunctionalButton.Style`</b> |                    | Controls the style of the button. Use `ODSFunctionalButton.Style.positive`/`ODSFunctionalButton.Style.negative` to get a green/red button.
+| `fullWidth: Bool`                         | `false`            | Defines the size of the button layout. Set to `true` means button takes all available space horizontally. Set to `false`, the size of the button is limited to the size of the text added by a padding round it.   
+| <b>`action: () -> Void`</b>               |                    | Callback invoked on button click.                                                 |                                                                            
+<BR>
+
+
 ### Icon button
 
 Plain buttons are the most ubiquitous component found throughout applications. Consisting an icon, they are the most simple button style.
 
 ![Buttons icon](images/buttons_icon.png)
 
+#### SwiftUI example
+
 ```swift
 // icon with system asset
 ODSIconButton(image: Image(systemName: "info.circle")) {}
@@ -127,5 +156,9 @@ ODSIconButton(image: Image(systemName: "info.circle")) {}
 ODSIconButton(image: Image("Add")) {}
 ```
 
+#### ODSIconButton API
 
-
+| Parameter                   | Default value | Description                       |
+|-----------------------------|---------------|-----------------------------------|
+| `image: Image`              |               | Icon displayed in the button.     |
+| <b>`action: () -> Void`</b> |               | Callback invoked on button click. |