Orange-OpenSource
diff --git a/‎.github/DEVELOP.md
+58-8 b/‎.github/DEVELOP.md
+58-8
diff --git a/‎.gitignore
+3 b/‎.gitignore
+3
diff --git a/‎CHANGELOG.md
+56-11 b/‎CHANGELOG.md
+56-11
diff --git a/‎Gemfile.lock
+1-1 b/‎Gemfile.lock
+1-1
diff --git a/‎OUDS/Core/Components/Sources/Buttons/OUDSButton.swift
+73 b/‎OUDS/Core/Components/Sources/Buttons/OUDSButton.swift
+73
diff --git a/‎OUDS/Core/Components/Sources/Extensions/View+Font.swift
+35 b/‎OUDS/Core/Components/Sources/Extensions/View+Font.swift
+35
diff --git a/‎OUDS/Core/Components/Sources/Extensions/View+Shadows.swift
+31 b/‎OUDS/Core/Components/Sources/Extensions/View+Shadows.swift
+31
@@ -3,6 +3,9 @@
 - [Technical preconditions](#technical-preconditions)
 - [Build showcase demo app](#build-showcase-demo-app)
 - [Documentation](#documentation)
+- [Run tests](#run-tests)
+  * [Unit tests for OUDS Swift package](#unit-tests-for-ouds-swift-package)
+  * [UI tests in demo app](#ui-tests-in-demo-app)
 - [Build phases](#build-phases)
 - [Targets](#targets)
 - [Certificates, profiles and identifiers](#certificates-profiles-and-identifiers)
@@ -20,12 +23,12 @@
 You should check wether or not you have the tools in use in the project like _Fastlane_, _SwiftLint_, _SwiftFormat_, etc.
 You can have a look for example in thr **THIRD\_PARTY.md** file which lists any dependencies and tools we use are different levels (SDK, showcase app, projects).
 
-If some tools are missing, pick the suitable command line bellow:
+If some tools are missing, pick the suitable command line below:
 ```bash
 # Use Bundler to install a major part of dependencies (thanks to Gemfile and Gemfile.lock files)
 bundle install
 
-# Use CocoaPods to install other dependencies not avaialble as rubygems (thanks to Podfile and Podfile.lock files)
+# Use CocoaPods to install other dependencies not available as rubygems (thanks to Podfile and Podfile.lock files)
 bundle exec pod install
 
 # Some dependencies must be downloaded by hand:
@@ -49,7 +52,53 @@ To build the demo application follow those steps:
 
 ## Documentation
 
-_To be defined soon_
+The documentation is based on the Swift documentation with [DocC](https://www.swift.org/documentation/docc/).
+We use here the [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin) to build the HTML documentations using the documentation catalogs
+and any _DocC_ comments in the source code.
+
+The documentation can be built from Xcode with _Product > Build Documentation_.
+
+The `generateDoc.sh` script helps to build the HTML version of documentation and compress it in ZIP file, and also can update
+the online version based on [_GitHub Pages_](https://pages.github.com/), this version is hosted in the [*gh-pages* GitHub branch](https://github.com/Orange-OpenSource/ouds-ios/tree/gh-pages).
+
+## Run tests 
+
+### Unit tests for OUDS Swift package
+
+To run these unit tests follow some steps:
+
+1. `cd Showcase`
+2. `bundle exec pod install`
+3. Open *Showcase.xcworkspace*
+4. Select *Showcase* scheme
+5. Run tests (Product -> Test)
+
+Unit tests care have been implemented for several reasons. 
+
+First, we don't have too much control on the raw tokens values. We rely on the _Figma_ design tool which outputs the tokens in a JSON file. 
+And this file will be parsed to as to generate Swift files. But if there are inconsistencies in the _Figma_ side or in the parser side, the inconsistencies will be spread in our code base. 
+It is not useful to define unit tests for raw tokens to test their values ; in fact they exist here to be updated.
+But we wan still check other things like the relationship between them. For example a _grid100_ should always be less or equal than a _grid100_. Some _color100_ should be always lighter than a _color200_, etc, etc. A small typo should be always smaller or with the sale size has a one-step-bigger typo.
+
+Then, we want to know when tokens have been removed so as to warn our users and keep release notes and changelog clean. If we don't spot such changes, maybe some users will be impacted.
+
+Finally, we ensure our themes can override any semantic tokens. Themes are in fact a set of values for the whole universe of semantic tokens, and if a theme cannot override a semantic token, there could be an issue. Unit tests also help us to find if some tokens have been removed before releasing the library.
+
+### UI tests in demo app
+
+To run these UI tests follow some steps:
+
+1. `cd Showcase`
+2. `bundle exec pod install`
+3. Open *Showcase.xcworkspace*
+4. Select *ShowcaseTests* scheme
+5. Select some simulator (tests designed for *iPhone 13 Pro Max* and *iPhone 14 Pro Max* but works elsewhere)
+6. Run tests (Product -> Test)
+
+Beware, if you add new UI tests using [swift-snapshot-testing](https://github.com/pointfreeco/swift-snapshot-testing) library, you may have new tests which fail at first time.
+Indeed for new tests the tool makes snapshots of the views, thus for the first run no preview exist making the tests fail. You should run the tests twice for new tests.
+
+Such tests here are used to as to be sure the look and feel of any components and tokens rendering remaing the expected ones.
 
 ## Build phases
 
@@ -65,11 +114,12 @@ The Xcode project contains two targets:
 
 1. _Showcase_ for the demo application
 2. _Periphery_ to look for dead code in the source code
+3. _ShowcaseTests_ for UI tests in demo app
 
 ## Certificates, profiles and identifiers
 
 We choose to use Xcode automatic signing for debug builds of the app so as to make easier onboarding of newcomers in development team, and also to prevent to update provisioning profiles with individual developers certificates each team someone wants to build the app and also to prevent to register each new build device). You may need to be part of our team if you want to build in debug mode.
-Note the bundle identifier here for lcoal builds is **com.orange.ouds.demoapp-debug**, with a **-debug** suffix so as to prevent any local build to be replaced by TestFlight builds which have **com.orange.ouds.demoapp** identifiers.  
+Note the bundle identifier here for local builds is **com.orange.ouds.demoapp-debug**, with a **-debug** suffix so as to prevent any local build to be replaced by TestFlight builds which have **com.orange.ouds.demoapp** identifiers.
 
 However for release builds we use a dedicated _provisioning profile_ built with of course a _distribution certificate_(.p12 format with private key, not .cer) and the _bundle identifier_ `com.orange.ouds.demoapp` for our _Apple Team_ `France Telecom (MG2LSJNJB6)`. Thus you won't be able to build and sign in release mode without this provisioning profile and this distribution certificate. These elements are stored in our local GitLab CI runners and must not be available outside.
 
@@ -166,7 +216,7 @@ exit 0
 We try also to apply [keep a changelog](https://keepachangelog.com/en/1.0.0/), and [semantic versioning](https://semver.org/spec/v2.0.0.html) both with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 You can generate a `RELEASE_NOTE.md` file using your Git history and [git cliff](https://git-cliff.org/) tool.
-Define first a `cliff.toml` configuration file containing the code bellow.
+Define first a `cliff.toml` configuration file containing the code below.
 
 ```toml
 # git-cliff ~ configuration file
@@ -176,7 +226,7 @@ Define first a `cliff.toml` configuration file containing the code bellow.
 # changelog header
 header = """
 # Release Note\n
-All notable changes for this version are here and blablbla.\n
+All notable changes for this version are here and blablabla.\n
 """
 # template for the changelog body
 # https://keats.github.io/tera/docs/#introduction
@@ -353,9 +403,9 @@ sort_commits = "oldest"
 A [GitHub Action](https://github.com/gitleaks/gitleaks-action) has been integrated to the repository with a configuration file defined in _/github/workflows_ named _gitleaks-action.yaml_.
 It will launch the _Gitleaks_ tool automatically.
 
-Howevere this tool does not detect plain API key mixed in URL, that is a reason why _Gitleaks_ can be called in a pre-commit hook, using the _giteaks.toml_ at the root of the prokect.
+However this tool does not detect plain API key mixed in URL, that is a reason why _Gitleaks_ can be called in a pre-commit hook, using the _giteaks.toml_ at the root of the project.
 To call _Gitleaks_ in pre-commit hooks, create a file named **pre-commit** inside _.git/hooks_ (then run `chmod u+x` in the file).
-Then place the bash code bellow in this file:
+Then place the bash code below in this file:
 
 ```bash
 # Run Gitleaks before commits
 
@@ -27,6 +27,9 @@
 /Showcase/Showcase.xcworkspace/xcuserdata/
 /DerivedData/
 
+# Produced by generateDoc.sh
+.build
+
 # Produced by Swift Package Manager
 /.swiftpm/xcode/xcshareddata/
 /.swiftpm/xcode/xcuserdata/
 
@@ -4,27 +4,73 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0](https://github.com/Orange-OpenSource/ouds-ios/compare/0.1.0...0.2.0) - 2024-09-19
+
+### Added
+
+- [Tests] Add UI regression tests using snapshot comparisons with *swift-snapshot-testing* tool ([#78](https://github.com/Orange-OpenSource/ouds-ios/issues/78))
+- [DemoApp] Display fake components for elevation rendering tests
+- [Library] A theme can now override the custom font family
+- [Tests] Add more unit tests for theme overriding and raw tokens controls
+- [Library] Add and update raw and semantic grid tokens ([#40](https://github.com/Orange-OpenSource/ouds-ios/issues/40))
+- [Library] Manage regular and compact layouts for sizing and spacing tokens
+- [Library] "Box shadow 0" has been defined and "elevation drag" changed
+- [Doc] Create the basics of a documentation ([#9](https://github.com/Orange-OpenSource/ouds-ios/issues/9))
+- [Library] Add more semanttic and raw tokens for typography
+- [Library] Add more semantic and raw tokens for typography, and SwiftUI API to apply them
+- [Library] Computation of SwiftUI radius from Figma blur and spread values for elevation tokens
+- [Library] Add elevation tokens ([#32](https://github.com/Orange-OpenSource/ouds-ios/issues/32))
+
+### Changed
+
+- [Library] Split raws, semantics and components tokens definitions and also values, composites and type aliases
+- [Showcase] Improve Fastlane alpha build notifications
+- [Library] Do not store blur value in elevation semantic tokens
+- [Library] Change type aliases for X and Y offsets of elevations tokens
+- [Library] Update border semantic tokens values ([#106](https://github.com/Orange-OpenSource/ouds-ios/issues/106))
+- [Showcase] Add fake components for demo and tokens tests
+- [Library] Remove spread value for elevation tokens
+- [Library] Remove paragraph spacing tokens for typography
+- [Library] Term "fluid" has been replaced by "adaptable" in spacing semantic tokens
+- [Doc] Improve DocC documentation about tokens and views extensions
+- [Doc] Add more details in release documentation
+- [Library] Rename semantic token "opacityEmphasized" to "opacityStrong" ([#94](https://github.com/Orange-OpenSource/ouds-ios/issues/94))
+- [Library] Update value of opacity raw token "opacity800" from 0.88 to 0.80 ([#87](https://github.com/Orange-OpenSource/ouds-ios/issues/87))
+- [Tests] Add missing unit tests for opacity raw tokens
+- [Library] "OUDSThemesCommons" product has been renamed to "OUDS"
+
+### Removed
+
+- [Library] Remove Z Index tokens for elevations ([#109](https://github.com/Orange-OpenSource/ouds-ios/issues/109))
+- [Library] Remove token "borderRadiusPill" and "borderRadiusCircle" ([#58](https://github.com/Orange-OpenSource/ouds-ios/issues/58))
+- [Library] "Emphasis" words have been replaced by "emphasized"
+- [Library] "Box shadow" words have been removed in elevation semantic and raw tokens 
+
+### Fixed
+
+- [Library] Fix some typos in documentation ([#89](https://github.com/Orange-OpenSource/ouds-ios/issues/89))
+
 ## [0.1.0](https://github.com/Orange-OpenSource/ouds-ios/compare/0.0.0...0.1.0) - 2024-08-08
 
 ### Added
 
 - [Library] Add simple logger for console outputs
-- [Library] Add unit tests for Sosh brand colors raw tokens
-- [Library] Add unit tests for Orange brand colors raw tokens
-- [Library] Add unit tests for foundations
-- [Library] Add unit tests for raw tokens and semantic tokens for colors
+- [Tests] Add unit tests for Sosh brand colors raw tokens
+- [Tests] Add unit tests for Orange brand colors raw tokens
+- [Tests] Add unit tests for foundations
+- [Tests] Add unit tests for raw tokens and semantic tokens for colors
 - [Library] Add draft of raw tokens and semantic tokens for grids
 
 ### Changed
 
 - [Library] Redefine Swift Package with clearer path for sources, tests cases and test plan
 - [Library] Expose product "OUDSThemesCommons" instead of "OUDSThemesShared"
-- [Library] Improve unit tests for elevation semantic tokens
-- [Library] Improve unit tests for typography raw tokens
-- [Library] Improve unit tests for opacity raw tokens
-- [Library] Improve unit tests for elevations raw tokens
-- [Library] Improve unit tests for dimensions raw tokens
-- [Library] Improve unit tests for borders raw tokens
+- [Tests] Improve unit tests for elevation semantic tokens
+- [Tests] Improve unit tests for typography raw tokens
+- [Tests] Improve unit tests for opacity raw tokens
+- [Tests] Improve unit tests for elevations raw tokens
+- [Tests] Improve unit tests for dimensions raw tokens
+- [Tests] Improve unit tests for borders raw tokens
 
 ### Fixed
 
@@ -43,7 +89,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [Library] Add raw tokens and semantic tokens for border ([#30](https://github.com/Orange-OpenSource/ouds-ios/issues/30))
 - [Library] Define Swift Package architecture of library and tokens (raw and semantic) ([#33](https://github.com/Orange-OpenSource/ouds-ios/issues/33))
 - [Library] Define Swift Package library for OUDS ([#46](https://github.com/Orange-OpenSource/ouds-ios/issues/46))
-
 - [Showcase] Publication of comment on issues about new alpha build upload on TestFlight ([#56](https://github.com/Orange-OpenSource/ouds-ios/issues/56))
 - [Showcase] Distribute demo app development version ([#12](https://github.com/Orange-OpenSource/ouds-ios/issues/12)) 
 - [Showcase] Distribute demo app for feature validation ([#13](https://github.com/Orange-OpenSource/ouds-ios/issues/13))
 
@@ -322,4 +322,4 @@ DEPENDENCIES
   xcode-install (= 2.8.1)
 
 BUNDLED WITH
-   2.5.11
+   2.5.17
@@ -0,0 +1,73 @@
+//
+// Software Name: OUDS iOS
+// SPDX-FileCopyrightText: Copyright (c) Orange SA
+// SPDX-License-Identifier: MIT
+//
+// This software is distributed under the MIT license,
+// the text of which is available at https://opensource.org/license/MIT/
+// or see the "LICENSE" file for more details.
+//
+// Authors: See CONTRIBUTORS.txt
+// Software description: A SwiftUI components library with code examples for Orange Unified Design System
+//
+
+import Foundation
+import OUDSFoundations
+import OUDSTokensSemantic
+import SwiftUI
+
+/// An OUDS component for buttons.
+/// __Warning: This is a draft component__.
+///
+/// This component is created to illustrate the mecanism of theme and tokens and for tests.
+public struct OUDSButton: View {
+
+    // MARK: - Properties
+
+    /// The text to display inside the button
+    private let text: String
+
+    /// The action to process when the button is activated by a user interaction like a tap
+    private let action: () -> Void
+
+    /// To get tokens to customize the component
+    @Environment(\.theme) private var theme
+
+    /// To choose if ight or dark color must be used
+    @Environment(\.colorScheme) private var colorScheme
+
+    /// To get programatically and on the fly the horizontal layout size
+    @Environment(\.horizontalSizeClass) private var sizeClass
+
+    // MARK: - Init
+
+    /// Initializes the button.
+    ///
+    /// - Parameters:
+    ///   - text: Text displayed in the button.
+    ///   - action: Will be called when the user clicks the button.
+    public init(text: String, action: @escaping () -> Void) {
+        self.text = text
+        self.action = action
+    }
+
+    // MARK: - Body
+
+    public var body: some View {
+        Button {
+            action()
+        } label: {
+            Text(text)
+                .systemFont(typography: theme.buttonTypography)
+                .padding(theme.buttonInternalSpacing)
+                .foregroundColor(colorScheme == .light
+                                 ? theme.buttonForegroundColorLight.color
+                                 : theme.buttonForegroundColorDark.color)
+                .modifier(BorderStyleModifier(theme.buttonBorderStyle,
+                                              theme.buttonBorderWidth,
+                                              theme.buttonBorderRadius,
+                                              theme.buttonBorderColorLight,
+                                              theme.buttonBorderColorDark))
+        }.frame(width: theme.buttonWidth, height: theme.buttonHeight)
+    }
+}
@@ -0,0 +1,35 @@
+//
+// Software Name: OUDS iOS
+// SPDX-FileCopyrightText: Copyright (c) Orange SA
+// SPDX-License-Identifier: MIT
+// 
+// This software is distributed under the MIT license,
+// the text of which is available at https://opensource.org/license/MIT/
+// or see the "LICENSE" file for more details.
+// 
+// Authors: See CONTRIBUTORS.txt
+// Software description: A SwiftUI components library with code examples for Orange Unified Design System 
+//
+
+import Foundation
+import OUDSTokensSemantic
+import SwiftUI
+
+extension View {
+
+    /// Applies a `CustomFontModifier` on the current `View` so as to add a specific `Font`.
+    /// - Parameters:
+    ///    - familyName: The font family name to load later (e.g. "Luciole")
+    ///    - token: The typography token to use to get useful values for `compact` or `regular` mode
+    /// - Returns: The `View` with the custom font applied
+    func customFont(familyName: String, typography token: TypographyCompositeSemanticToken) -> some View {
+        self.modifier(CustomFontModifier(token: token, fontFamilyName: familyName))
+    }
+
+    /// Applies a `FontModifier` to use the system font on the current `View` with a specific token
+    /// - Parameter token: The typography token to use to get useful values for `compact` or `regular` mode
+    /// - Returns: The `View` with the custom font applied
+    func systemFont(typography token: TypographyCompositeSemanticToken) -> some View {
+        self.modifier(FontModifier(token: token))
+    }
+}
@@ -0,0 +1,31 @@
+//
+// Software Name: OUDS iOS
+// SPDX-FileCopyrightText: Copyright (c) Orange SA
+// SPDX-License-Identifier: MIT
+// 
+// This software is distributed under the MIT license,
+// the text of which is available at https://opensource.org/license/MIT/
+// or see the "LICENSE" file for more details.
+// 
+// Authors: See CONTRIBUTORS.txt
+// Software description: A SwiftUI components library with code examples for Orange Unified Design System 
+//
+
+import Foundation
+import OUDSTokensSemantic
+import SwiftUI
+
+extension View {
+
+    /// Wraps the *SwiftUI* `shadow(color:radius:x:y)` method so as to use as `radius` value
+    /// the computed `radius` value of the given `ElevationCompositeSemanticToken`.
+    /// - Parameter elevation: The token to give for the shadow / elevation effect
+    /// - Returns `View`: The current `View` with the shadow / elevation effect
+    public func shadow(elevation: ElevationCompositeSemanticToken) -> some View {
+        return self
+            .shadow(color: elevation.color.color,
+                    radius: elevation.radius,
+                    x: CGFloat(elevation.x),
+                    y: CGFloat(elevation.y))
+    }
+}