[#1336] In documentation add new tutorial since Mobile App Dev Days

.swiftlint.yml

@@ -28,7 +28,8 @@ included:
 # ========
 
 excluded:
-- OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial
+- OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery
+- OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_onboarding
 
 # ==============
 # Disabled rules

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Tutorial for onboardings and meetups (Orange-OpenSource/ouds-ios#1336)
 - View helpers to use scaled spaces tokens to add padding and for HStack/VStack (Orange-OpenSource/ouds-ios#1324)
 - GitHub Copilot instructions file for maintainers and contributors (Orange-OpenSource/ouds-ios#1314)
 - Helper to apply grid margin on views (Orange-OpenSource/ouds-ios#1317)

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial/Table Of Contents.tutorial → OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/Table Of Contents (discovery).tutorial

@@ -1,5 +1,5 @@
 @Tutorials(name: "Orange Unified Design System") {
-    @Intro(title: "Swift Package iOS Tutorial") {
+    @Intro(title: "Swift Package Discovery Tutorial") {
         Discovering a new framework can be exciting and scary. Learn how you can embed and use OUDS Swift Package.
         With this tutorial you will learn fundamental concepts of Orange Unified Design System and discover the layers of this framework.
         Theme, components, tokens... everything will be introduced!
@@ -9,51 +9,51 @@
 
     @Chapter(name: "Import of the Swift Package and choose its librairies") {
         In this chapter you will learn how to import the OUDS iOS Swift Package and which librairies it provides
-        you should choose for your needs
+        you should choose for your needs.
 
         @Image(source: "ic_unified_ds", alt: "Logo of OUDS")
 
-        @TutorialReference(tutorial: "doc:tutorial-1-package-and-librairies")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-1-package-and-librairies")
     }
 
     @Chapter(name: "Preparation of the theme") {
         In this chapter you will see how to instanciate a theme and inject it inside your app
 
         @Image(source: "ic_theme_intro", alt: "OUDS themes logo")
 
-        @TutorialReference(tutorial: "doc:tutorial-2-instanciate-theme")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-2-instanciate-theme")
     }
 
     @Chapter(name: "Use of first components provided by OUDS") {
         In this chapter you will see how you can use your first components provided by OUDS Swift Package
 
         @Image(source: "ic_component_intro", alt: "OUDS components logo")
 
-        @TutorialReference(tutorial: "doc:tutorial-3-use-first-components")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-3-use-first-components")
     }
 
     @Chapter(name: "Richer and more original components of OUDS") {
         In this chapter you will use original components of OUDS and richer ones
 
         @Image(source: "ic_component_intro", alt: "Logo of OUDS")
 
-        @TutorialReference(tutorial: "doc:tutorial-4-use-other-components")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-4-use-other-components")
     }
 
     @Chapter(name: "Typography, view modifiers and tokens") {
         OUDS is not only about components and themes. It provides view modifiers, typographies and tokens which can be used. You will learn how.
 
         @Image(source: "ic_design_token_intro", alt: "OUDS tokens logo")
 
-        @TutorialReference(tutorial: "doc:tutorial-5-styling-things")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-5-styling-things")
     }
 
     @Chapter(name: "Go further with more ressources") {
         You can have questions and issues, and there are resources online. Let's see that together.
 
         @Image(source: "ic_unified_ds", alt: "Logo of OUDS")
 
-        @TutorialReference(tutorial: "doc:tutorial-6-going-further")
+        @TutorialReference(tutorial: "doc:tutorial-discovery-6-going-further")
     }
 }
 

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial/swift-samples/tutorial (solution).swift → OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/resources/swift-samples/tutorial-discovery (solution).swift

@@ -19,12 +19,12 @@ import SwiftUI
 @main
 struct OUDSTutorialSandboxApp: App {
 
-    let themeTuning = Tuning(hasRoundedButtons: true, hasRoundedTextInputs: true, hasRoundedAlertMessages: true)
+    static let themeTuning = Tuning(hasRoundedButtons: true, hasRoundedTextInputs: true, hasRoundedAlertMessages: true)
 
     let myTheme = OrangeTheme(borders: MyOwnProviderOfBorderTokens(),
                               colors: MyOwnProviderOfColorTokens(),
                               fontFamily: "Menlo",
-                              tuning: themeTuning)
+                              tuning: Self.themeTuning)
 
     var body: some Scene {
         WindowGroup {
@@ -165,7 +165,7 @@ struct ContentView: View {
 // MARK: - Custom tokens providers
 // WARNING: Can have side effects, use with care!
 
-class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
+nonisolated class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
 
     /// Some tokens have light and dark values used according to color scheme
     override var actionEnabledLight: ColorSemanticToken {
@@ -178,7 +178,7 @@ class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
     }
 }
 
-class MyOwnProviderOfBorderTokens: OrangeThemeBorderSemanticTokensProvider {
+nonisolated class MyOwnProviderOfBorderTokens: OrangeThemeBorderSemanticTokensProvider {
 
     override var widthThin: BorderWidthSemanticToken {
         BorderRawTokens.width75

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial/swift-samples/tutorial-5-10.swift → OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/resources/swift-samples/tutorial-discovery-5-10.swift

@@ -17,11 +17,11 @@ import SwiftUI
 @main
 struct OUDSTutorialSandboxApp: App {
 
-    let themeTuning = Tuning(hasRoundedButtons: true, hasRoundedTextInputs: true, hasRoundedAlertMessages: true)
+    static let themeTuning = Tuning(hasRoundedButtons: true, hasRoundedTextInputs: true, hasRoundedAlertMessages: true)
     let myTheme = OrangeTheme(borders: MyOwnProviderOfBorderTokens(),
                               colors: MyOwnProviderOfColorTokens(),
                               fontFamily: "Menlo",
-                              tuning: themeTuning)
+                              tuning: Self.themeTuning)
 
     var body: some Scene {
         WindowGroup {
@@ -35,7 +35,7 @@ struct OUDSTutorialSandboxApp: App {
 /// Change the provider of semantic tokens of colors for the Orange theme
 /// Keep in mind colors are used everywhere in plenty of components
 /// so your changes can impact other elements
-class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
+nonisolated class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
 
     /// Some tokens have light and dark values used according to color scheme
     override var actionEnabledLight: ColorSemanticToken {
@@ -51,7 +51,7 @@ class MyOwnProviderOfColorTokens: OrangeThemeColorSemanticTokensProvider {
 /// Change the provider of semantic tokens of border for the Orange theme
 /// Keep in mind borders are used everywhere in plenty of components
 /// so your changes can impact other elements
-class MyOwnProviderOfBorderTokens: OrangeThemeBorderSemanticTokensProvider {
+nonisolated class MyOwnProviderOfBorderTokens: OrangeThemeBorderSemanticTokensProvider {
 
     override var widthThin: BorderWidthSemanticToken {
         BorderRawTokens.width75

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/tutorial-discovery-1-package-and-librairies.tutorial

@@ -0,0 +1,104 @@
+@Tutorial(time: 10, projectFiles: "OUDS-Discovery-Tutorial") {
+    @Intro(title: "Swift Package integration") {
+        OUDS iOS is exposed through an open source Swift Package hosted on GitHub, and provides several librairies for your needs.
+        These librairies help to split products and make users able to select only what they need.
+        SwiftUI is the only official supported framework for Apple platforms.
+
+        @Image(source: "ic_unified_ds", alt: "Logo of OUDS")
+    }
+
+    @XcodeRequirement(title: "Xcode 26.2", destination: "https://developer.apple.com/download/")
+
+    @Section(title: "Import the Swift Package and the libraries") {
+
+        @ContentAndMedia {
+            OUDS for iOS is an open source Swift Package available on GitHub under MIT license.
+            The package and the librairies must be added through Xcode.
+        }
+
+        @Steps {
+            @Step {
+                Using Xcode, in your **project package dependencies**, add a new **dependency**.
+                Search with the GitHub repository URL (https://github.com/Orange-OpenSource/ouds-ios), and select the *ouds-ios* dependency.
+                You can then choose the **dependency rule** you want.
+                To know which version you need, you can have a look on the [available API list](https://github.com/Orange-OpenSource/ouds-ios/wiki/01-%E2%80%90-Available-API)
+                and also the [GitHub releases](https://github.com/Orange-OpenSource/ouds-ios/releases).
+                Let's say you will use some beta version today, e.g. the version1.3.0-beta.2
+
+                @Image(source: "tutorial-discovery-1-ouds-swift-package", alt: "Description by Xcode of the OUDS Swift Package with its README preview")
+            }
+
+            @Step {
+                Once you downloaded the package, you will see several librairies are available. 
+                They can be embeded inside your **target** librairies.
+                Things are separated to let users integrate only what they need and embed the abre minimum of content.
+                The *OUDSThemesContract* library provides the main elements like the `OUDSThemeableView`. The theme contract is defined inside it.
+                *OUDSThemesOrange* provides the theme implementation for the Orange products, and contains also assets and all tokens for this theme.
+                *OUDSThemesSosh* provides the theme implementation for the Sosh products, and contains also assets and all tokens for this theme.
+                *OUDSThemesWireframe* provides the theme implementation for the Wireframe theme, which is a theme dedicated to mockups and prototypes.
+                *OUDSThemesOrangeCompact* provides the theme implementation for the Orange products but with constraints of sizes and spaces.
+                *OUDSComponents* contains the SwiftUI OUDS components defined with the Figma specifications, and also useful view modifers.
+                *OUDSTokensRaw*, *OUDSTokensSemantic* and *OUDSTokensComponents* are librairies defining and providing the tokens for low level (raw), 
+                middle level (semantic) or component levels (high level).
+                *OUDSModules* is for modules or rich components with extra logic.
+                *OUDSFoundations* is dedicated to some utilities and shared logic.
+
+                Add for example only the umbrella product merging all products mentioned above: *OUDSSwiftUI*
+
+                @Image(source: "tutorial-discovery-1-ouds-libraries.png", alt: "Embed librairies inside target")
+            }
+        }
+    }
+
+    @Assessments {
+        @MultipleChoice {
+            Which of these choices is correct?
+
+            @Choice(isCorrect: true) {
+                I can contribute to OUDS using pull request 
+
+                @Justification(reaction: "That's right!") {
+                    OUDS is open source, under MIT license, and hosted on GitHub. Of course you can contribute!
+                }
+            }
+
+            @Choice(isCorrect: false) {
+                OUDS supports officialy all Apple OS like visionOS, tvOS, watchOS, iPadOS, iOS and also CarPlay.
+
+                @Justification(reaction: "Try again!") {
+                    The main supported targets are iOS / iPadOS. However we do our best to support macOS, visionOS, tvOS and watchOS.
+                    CarPlay specific cases are not scoped yet. 
+                }
+            }
+
+            @Choice(isCorrect: false) {
+                OUDS provides UIKit components 
+
+                @Justification(reaction: "Try again!") {
+                    OUDS supports only SwiftUI.
+                }
+            }
+        }
+
+        @MultipleChoice {
+            Which imports of the OUDS Swift Package products can I choose?
+
+            @Choice(isCorrect: true) {
+                Some of the available products depending to my needs, or only `OUDSSwiftUI` if I am very lazy and don't care about my app size.
+
+                @Justification(reaction: "Correct!") {
+                    You can import all products provided by the Swift Package, and tailor your choice to keep only the ones needed.
+                    Even if we recommend to choose only the atomic products you need, the `OUDSSwiftUI` product wraps all of them.
+                }
+            }
+
+            @Choice(isCorrect: false) {
+                None, only the Swift package dependency matter. 
+
+                @Justification(reaction: "Try again!") {
+                    You need to chose the products the Swift package provides.
+                }
+            }
+        }        
+    }
+}

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial/tutorial-2-instanciate-theme.tutorial → OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/tutorial-discovery-2-instanciate-theme.tutorial

@@ -1,4 +1,4 @@
-@Tutorial(time: 15) {
+@Tutorial(time: 15, projectFiles: "OUDS-Discovery-Tutorial") {
     @Intro(title: "Instanciate and inject a theme") {
         The theme is exposed as one object which will be injected inside your SwiftUI view.
         The theme provides all tokens which defines in the end the rendering of everything.
@@ -22,8 +22,8 @@
             @Step {
                 Define a basic `App` object using *SwiftUI*. Add inside a simple text
 
-                @Code(name: "Tutorial.swift", file: "tutorial-2-1.swift") {
-                    @Image(source: "tutorial-2-1.png", alt: "A text displaying the \"Hello OUDS!\" message")
+                @Code(name: "Tutorial.swift", file: "tutorial-discovery-2-1.swift") {
+                    @Image(source: "tutorial-discovery-2-1.png", alt: "A text displaying the \"Hello OUDS!\" message")
                 } 
             }
 
@@ -34,8 +34,8 @@
 
                 Project must compile then. This is until today (API 0.20.0) the only way to instanciated and inject a theme.
 
-                @Code(name: "Tutorial.swift", file: "tutorial-2-2.swift") {
-                    @Image(source: "tutorial-2-2.png", alt: "A text displaying the \"Hello OUDS!\" message")
+                @Code(name: "Tutorial.swift", file: "tutorial-discovery-2-2.swift") {
+                    @Image(source: "tutorial-discovery-2-2.png", alt: "A text displaying the \"Hello OUDS!\" message")
                 } 
             }
         }

OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial/tutorial-3-use-first-components.tutorial → OUDS/Core/ThemesContract/Sources/_ThemesContract.docc/Tutorial_discovery/tutorial-discovery-3-use-first-components.tutorial

@@ -1,4 +1,4 @@
-@Tutorial(time: 30) {
+@Tutorial(time: 30, projectFiles: "OUDS-Discovery-Tutorial") {
     @Intro(title: "Use your first OUDS components") {
         OUDS provides components ready to be used, specified in Figma assets and preventing users to handle tokens.
         They are rendered thanks to the theme in use.
@@ -19,7 +19,7 @@
             @Step {
                 First, prepare the `ContentView` by adding inside it a `ScrollView`.   
 
-                @Code(name: "Tutorial.swift", file: "tutorial-3-1.swift", previousFile: "tutorial-2-2.swift") 
+                @Code(name: "Tutorial.swift", file: "tutorial-discovery-3-1.swift", previousFile: "tutorial-discovery-2-2.swift") 
             }
 
             @Step {
@@ -31,8 +31,8 @@
 
                 Add such picker with three items inside.
 
-                @Code(name: "Content.swift", file: "tutorial-3-2.swift") {
-                    @Image(source: "tutorial-3-2.png", alt: "A radio picker")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-2.swift") {
+                    @Image(source: "tutorial-discovery-3-2.png", alt: "A radio picker")
                 } 
             }
 
@@ -43,8 +43,8 @@
 
                 Add a checkbox item with only two states.
 
-                @Code(name: "Content.swift", file: "tutorial-3-3.swift") {
-                    @Image(source: "tutorial-3-3.png", alt: "A radio picker and a checkbox item")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-3.swift") {
+                    @Image(source: "tutorial-discovery-3-3.png", alt: "A radio picker and a checkbox item")
                 } 
             }
 
@@ -54,8 +54,8 @@
 
                 Choose to add an instance of `OUDSHorizontalDivider`. 
 
-                @Code(name: "Content.swift", file: "tutorial-3-4.swift") {
-                    @Image(source: "tutorial-3-4.png", alt: "A radio picker, an horizontal divider and a checkbox item")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-4.swift") {
+                    @Image(source: "tutorial-discovery-3-4.png", alt: "A radio picker, an horizontal divider and a checkbox item")
                 } 
             }
 
@@ -66,8 +66,8 @@
                 Add a switch item, it will be used as a trick to force the change of the color scheme for the view for our future operations.
                 You will then be able to see the automatic changes of colors when you switch the color scheme.
 
-                @Code(name: "Content.swift", file: "tutorial-3-5.swift") {
-                    @Image(source: "tutorial-3-5.png", alt: "A radio picker, an horizontal divider, a checkbox item and a switch item")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-5.swift") {
+                    @Image(source: "tutorial-discovery-3-5.png", alt: "A radio picker, an horizontal divider, a checkbox item and a switch item")
                 } 
             }
 
@@ -76,8 +76,8 @@
 
                 Add an `OUDSLink` in the app and make it open the iOS documentation OUDS website.
 
-                @Code(name: "Content.swift", file: "tutorial-3-6.swift") {
-                    @Image(source: "tutorial-3-6.png", alt: "A radio picker, an horizontal divider, a checkbox item, a switch item and a link")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-6.swift") {
+                    @Image(source: "tutorial-discovery-3-6.png", alt: "A radio picker, an horizontal divider, a checkbox item, a switch item and a link")
                 } 
             }
 
@@ -88,8 +88,8 @@
 
                 Let's add a button with some rules: if checkbox is not checked it is disabled. When tapped, change the style of the button during 5 seconds.
 
-                @Code(name: "Content.swift", file: "tutorial-3-7.swift") {
-                    @Image(source: "tutorial-3-7.png", alt: "A radio picker, an horizontal divider, a checkbox item, a switch item, a link and a button")
+                @Code(name: "Content.swift", file: "tutorial-discovery-3-7.swift") {
+                    @Image(source: "tutorial-discovery-3-7.png", alt: "A radio picker, an horizontal divider, a checkbox item, a switch item, a link and a button")
                 } 
             }
         }