Merge pull request #740 from Orange-OpenSource/prepare-release

Prepare release 0.18.0
Orange-OpenSource · Dec 11, 2023 · c5f1f2e · c5f1f2e
2 parents 7215a48 + 236edce
commit c5f1f2e
Show file tree

Hide file tree

Showing 187 changed files with 3,355 additions and 5 deletions.
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -18,7 +18,7 @@ repositories {
 
 ```groovy
 dependencies {
-    implementation 'com.orange.ods.android:ods-lib:0.17.0'
+    implementation 'com.orange.ods.android:ods-lib:0.18.0'
 }
 ```
 

diff --git a/app/build.gradle.kts b/app/build.gradle.kts
@@ -35,7 +35,7 @@ android {
         minSdk = Versions.minSdk
         targetSdk = Versions.targetSdk
         val versionCodeProperty = project.findTypedProperty<String>("versionCode")
-        versionCode = versionCodeProperty?.toInt() ?: 9
+        versionCode = versionCodeProperty?.toInt() ?: 10
         versionName = version.toString()
         val versionNameSuffixProperty = project.findTypedProperty<String>("versionNameSuffix")
         versionNameSuffix = versionNameSuffixProperty

diff --git a/changelog.md b/changelog.md
@@ -5,7 +5,7 @@ All notable changes done in ODS library 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).
 
-## [Unreleased](https://github.com/Orange-OpenSource/ods-android/compare/0.17.0...develop)
+## [0.18.0](https://github.com/Orange-OpenSource/ods-android/compare/0.17.0...0.18.0) - 2023-12-11
 
 ### Added
 

diff --git a/docs/0.18.0/404.html b/docs/0.18.0/404.html
@@ -0,0 +1,26 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+
+</style>
+
+<div class="container">
+    <h1>404</h1>
+
+    <p><strong>Page not found :(</strong></p>
+    <p>The requested page could not be found.</p>
+</div>
diff --git a/docs/0.18.0/components/AppBarsBottom.md b/docs/0.18.0/components/AppBarsBottom.md
@@ -0,0 +1,31 @@
+---
+layout: detail
+title: "App bars: bottom"
+description: A bottom app bar displays navigation and key actions at the bottom of mobile screens.
+---
+
+<br>**On this page**
+
+* [Specifications references](#specifications-references)
+* [Accessibility](#accessibility)
+
+---
+
+## Specifications references
+
+- [Design System Manager - App bars](https://system.design.orange.com/0c1af118d/p/23e0e6-app-bars/b/620966)
+- [Material Design - App bars: bottom](https://material.io/components/app-bars-bottom)
+
+## Accessibility
+
+Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/).
+
+Android's bottom app bar component APIs provide support for the navigation icon,
+action items, overflow menu and more for informing the user as to what each
+action performs. While optional, their use is strongly encouraged.
+
+**Content descriptions**
+
+When using icons for navigation icons, action items and other elements of bottom
+app bars, you should set a content description on them so that screen readers
+like TalkBack are able to announce their purpose or action, if any.
diff --git a/docs/0.18.0/components/AppBarsBottom_docs.md b/docs/0.18.0/components/AppBarsBottom_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: AppBarsBottom.md
+---
diff --git a/docs/0.18.0/components/AppBarsTop.md b/docs/0.18.0/components/AppBarsTop.md
@@ -0,0 +1,157 @@
+---
+layout: detail
+title: "App bars: top"
+description: Top app bars display information and actions relating to the current screen.
+---
+
+<br>**On this page**
+
+* [Specifications references](#specifications-references)
+* [Accessibility](#accessibility)
+* [Variants](#variants)
+    * [Regular top app bar](#regular-top-app-bar)
+        * [Jetpack Compose](#jetpack-compose)
+            * [OdsTopAppBar API](#odstopappbar-api)
+    * [Large top app bar](#large-top-app-bar)
+        * [Jetpack Compose](#jetpack-compose-1)
+            * [OdsLargeTopAppBar API](#odslargetopappbar-api)
+
+---
+
+## Specifications references
+
+- [Design System Manager - App bars](https://system.design.orange.com/0c1af118d/p/23e0e6-app-bars/b/620966)
+- [Material Design - App bars: top](https://material.io/components/app-bars-top/)
+
+## Accessibility
+
+Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/).
+
+`OdsTopAppBar` provides accessibility support for the navigation icon,
+action items, overflow menu and more for informing the user as to what each
+action performs.
+
+## Variants
+
+### Regular top app bar
+
+#### Jetpack Compose
+
+Add `OdsTopAppBar` composable to your Scaffold `topBar`.
+Here is an example of use:
+
+```kotlin
+OdsTopAppBar(
+    title = "Title",
+    navigationIcon = OdsTopAppBar.NavigationIcon(
+        painter = painterResource(id = R.drawable.ic_back),
+        contentDescription = "content description",
+        onClick = { doSomething() }
+    ),
+    actions = listOf(
+        OdsTopAppBar.ActionButton(
+            painter = painterResource(id = R.drawable.ic_share),
+            contentDescription = "content description",
+            onClick = { doSomething() }
+        ),
+        // ...
+    ),
+    overflowMenuItems = listOf(
+        OdsDropdownMenu.Item(
+            text = "Text",
+            onClick = { doSomething() }
+        ),
+        // ...
+    )
+)
+```
+
+Note: By default, the `OdsTopAppBar` is elevated but you can set `elevated` parameter to `false` if you don't want any shadow below it (for example if you want to display tabs below).
+
+##### OdsTopAppBar API
+
+Parameter | Default&nbsp;value | Description
+-- | -- | --
+`title: String` | | Title to be displayed in the center of the top app bar
+`modifier: Modifier` | `Modifier` |`Modifier` to be applied to the top app bar
+`navigationIcon: OdsTopAppBar.NavigationIcon?` | `null` | Icon to be displayed at the start of the top app bar
+`actions: List<OdsTopAppBar.ActionButton>` | `emptyList()` | Actions to be displayed at the end of the top app bar. The default layout here is a `Row`, so icons inside will be placed horizontally.
+`overflowMenuItems: List<OdsDropdownMenu.Item>` | `emptyList()` | List of items displayed in the overflow menu. The top app bar uses `OdsDropdownMenu` to display its overflow menu.
+`elevated: Boolean` | `true` | Controls the elevation of the top app bar: `true` to set an elevation to the top app bar (a shadow is displayed below), `false` otherwise
+{:.table}
+
+### Large top app bar
+
+#### Jetpack Compose
+
+First, you have to add this line in your application `build.gradle.kts` file cause this component relies on Compose Material 3 implementation:
+
+```kotlin
+implementation("androidx.compose.material3:material3:<version number>")
+```
+
+Then you can add `OdsLargeTopAppBar` composable to your Scaffold `topBar`:
+
+```kotlin
+OdsLargeTopAppBar(
+    title = "Title",
+    navigationIcon = OdsTopAppBar.NavigationIcon(
+        painter = painterResource(id = R.drawable.ic_back),
+        contentDescription = "content description",
+        onClick = { doSomething() }
+    ),
+    actions = listOf(
+        OdsTopAppBar.ActionButton(
+            painter = painterResource(id = R.drawable.ic_share),
+            contentDescription = "content description",
+            onClick = { doSomething() }
+        ),
+        // ...
+    ),
+    overflowMenuItems = listOf(
+        OdsDropdownMenu.Item(
+            text = "Text",
+            onClick = { doSomething() }
+        ),
+        // ...
+    ),
+    scrollBehavior = null // See below to attach a scroll behavior and make the top app bar collapsible
+)
+```
+
+If you want a collapsible large top app bar, you can follow these steps:
+
+1 - Define the scroll behavior to use:
+
+```kotlin
+val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior(rememberTopAppBarState())
+```
+
+2 - Provide this `scrollBehavior` to the `OdsLargeTopAppBar` and as a modifier of your Scaffold in order to listen to the scroll event
+
+```kotlin
+Scaffold(
+    modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
+    topBar = {
+        OdsLargeTopAppBar(
+            //...
+            scrollBehavior = scrollBehavior,
+        )
+    },
+    //...
+) {
+    // Scaffold content
+}
+```
+
+##### OdsLargeTopAppBar API
+
+Parameter | Default&nbsp;value | Description
+-- | -- | --
+`title: String` | | Title displayed in the center of the top app bar
+`modifier: Modifier` | `Modifier` |`Modifier` applied to the top app bar
+`navigationIcon: OdsTopAppBar.NavigationIcon?` | `null` | Icon displayed at the start of the top app bar
+`actions: List<OdsTopAppBar.ActionButton>` | `emptyList()` | Actions displayed at the end of the top app bar. The default layout here is a `Row`, so icons inside will be placed horizontally.
+`overflowMenuItems: List<OdsDropdownMenu.Item>` | `emptyList()` | List of items displayed in the overflow menu. The top app bar uses `OdsDropdownMenu` to display its overflow menu.
+`scrollBehavior: TopAppBarScrollBehavior?` | `null` | `TopAppBarScrollBehavior` attached to the top app bar
+{:.table}
diff --git a/docs/0.18.0/components/AppBarsTop_docs.md b/docs/0.18.0/components/AppBarsTop_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: AppBarsTop.md
+---
diff --git a/docs/0.18.0/components/Banners.md b/docs/0.18.0/components/Banners.md
@@ -0,0 +1,62 @@
+---
+layout: detail
+title: Banners
+description: Banners displays an important message which requires an action to be dismissed.
+---
+
+A banner displays an important, succinct message, and provides actions for users to address (or dismiss the banner).
+It requires a user action to be dismissed.
+
+Banners should be displayed at the top of the screen, below a top app bar. They’re persistent and nonmodal, allowing the user to either ignore them or interact with them at any time.
+Only one banner should be shown at a time
+
+<br>**On this page**
+
+* [Specifications references](#specifications-references)
+* [Accessibility](#accessibility)
+* [Implementation](#implementation)
+    * [Jetpack Compose](#jetpack-compose)
+        * [OdsBanner API](#odsbanner-api)
+
+---
+
+## Specifications references
+
+- [Design System Manager - Banners](https://system.design.orange.com/0c1af118d/p/19a040-banners/b/497b77)
+- [Material Design - Banners](https://m2.material.io/components/banners)
+
+## Accessibility
+
+Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/).
+
+`OdsBanner` is built to support accessibility criteria and is readable by most screen readers, such as TalkBack. The use of an `OdsBanner.Image` force the developer to associate a content description to the banner image.
+
+## Implementation
+
+![Banner light](images/banner_light.png)
+
+![Banner dark](images/banner_dark.png)
+
+### Jetpack Compose
+
+You can use the `OdsBanner` composable like this:
+
+```kotlin
+OdsBanner(
+    message = "Message displayed into the banner.",
+    firstButton = OdsBanner.Button("Dismiss") { doSomething() },
+    secondButton = OdsBanner.Button("Detail") { doSomething() },
+    image = OdsBanner.Image(painterResource(id = R.drawable.placeholder), "")
+)
+```
+
+#### OdsBanner API
+
+Parameter | Default&nbsp;value | Description
+-- | -- | --
+`message: String` | | Text displayed into the banner
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the banner
+`image: OdsBanner.Image?` | `null` | Image displayed in the banner in a circle shape
+`firstButton: OdsBanner.Button?` | `null` | Primary button displayed in the banner
+`secondButton: OdsBanner.Button?` | `null` | Secondary button displayed into the banner next to the primary one
+{:.table}
diff --git a/docs/0.18.0/components/Banners_docs.md b/docs/0.18.0/components/Banners_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: Banners.md
+---