diff --git a/DEVELOP.md b/DEVELOP.md index 4cf005cfc..153d89284 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -18,7 +18,7 @@ repositories { ```groovy dependencies { - implementation 'com.orange.ods.android:ods-lib:0.13.0' + implementation 'com.orange.ods.android:ods-lib:0.14.0' } ``` diff --git a/app/build.gradle.kts b/app/build.gradle.kts index 75269d399..ff1c70991 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -34,7 +34,7 @@ android { minSdk = Versions.minSdk targetSdk = Versions.targetSdk val versionCodeProperty = project.findTypedProperty("versionCode") - versionCode = versionCodeProperty?.toInt() ?: 4 + versionCode = versionCodeProperty?.toInt() ?: 5 versionName = version.toString() val versionNameSuffixProperty = project.findTypedProperty("versionNameSuffix") versionNameSuffix = versionNameSuffixProperty diff --git a/changelog.md b/changelog.md index 2d3f709e2..ea01ea21c 100644 --- 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.13.0...develop) +## [0.14.0](https://github.com/Orange-OpenSource/ods-android/compare/0.13.0...0.14.0) - 2023-07-12 ### Added diff --git a/docs/0.14.0/404.html b/docs/0.14.0/404.html new file mode 100644 index 000000000..dd331eb8e --- /dev/null +++ b/docs/0.14.0/404.html @@ -0,0 +1,26 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
\ No newline at end of file diff --git a/docs/0.14.0/components/AppBarsBottom.md b/docs/0.14.0/components/AppBarsBottom.md new file mode 100644 index 000000000..c78807e84 --- /dev/null +++ b/docs/0.14.0/components/AppBarsBottom.md @@ -0,0 +1,167 @@ +--- +layout: detail +title: "App bars: bottom" +description: A bottom app bar displays navigation and key actions at the bottom of mobile screens. +--- + +--- + +**Page Summary** + +* [Specifications references](#specifications-references) +* [Accessibility](#accessibility) +* [Implementation](#implementation) +* [Component specific tokens](#component-specific-tokens) + +--- + +## 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) +- *Technical documentation soon available* + +## 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. + +For an overall content description of the bottom app bar, set an +`android:contentDescription` or use the `setContentDescription` method on the +`BottomAppBar`. + +For the navigation icon, this can be achieved via the +`app:navigationContentDescription` attribute or +`setNavigationContentDescription` method. + +For action items and items within the overflow menu, the content description +needs to be set in the menu: + +```xml + + + + +``` + +## Implementation + +Bottom app bars provide access to a bottom navigation drawer and up to four +actions, including the floating action button. + +> **Jetpack Compose implementation** + +*Not available yet* + +> **XML implementation** + +API and source code: + +* `CoordinatorLayout`: [Class definition](https://developer.android.com/reference/androidx/coordinatorlayout/widget/CoordinatorLayout) +* `BottomAppBar`: [Class definition](https://developer.android.com/reference/com/google/android/material/bottomappbar/BottomAppBar), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomappbar/BottomAppBar.java) +* `FloatingActionButton`: [Class definition](https://developer.android.com/reference/com/google/android/material/floatingactionbutton/FloatingActionButton), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/FloatingActionButton.java) + +In the layout: + +```xml + + + + + + + + + + + + + + +``` + +In `menu/bottom_app_bar.xml`: + +```xml + + + + + + + +``` + +In menu/navigation icon drawables: + +```xml + + +``` + +In code: + +```kotlin +bottomAppBar.setNavigationOnClickListener { + // Handle navigation icon press +} + +bottomAppBar.setOnMenuItemClickListener { menuItem -> + when (menuItem.itemId) { + R.id.search -> { + // Handle search icon press + true + } + R.id.more -> { + // Handle more item (inside overflow menu) press + true + } + else -> false + } +} +``` + +## Component specific tokens + +_Soon available_ diff --git a/docs/0.14.0/components/AppBarsBottom_docs.md b/docs/0.14.0/components/AppBarsBottom_docs.md new file mode 100644 index 000000000..4566c033f --- /dev/null +++ b/docs/0.14.0/components/AppBarsBottom_docs.md @@ -0,0 +1,4 @@ +--- +layout: main +content_page: AppBarsBottom.md +--- \ No newline at end of file diff --git a/docs/0.14.0/components/AppBarsTop.md b/docs/0.14.0/components/AppBarsTop.md new file mode 100644 index 000000000..a1918cc4e --- /dev/null +++ b/docs/0.14.0/components/AppBarsTop.md @@ -0,0 +1,319 @@ +--- +layout: detail +title: "App bars: top" +description: Top app bars display information and actions relating to the current screen. +--- + +--- + +**Page Summary** + +* [Specifications references](#specifications-references) +* [Accessibility](#accessibility) +* [Variants](#variants) + * [Regular top app bar](#regular-top-app-bar) + * [Large top app bar](#large-top-app-bar) +* [Extras](#extras) + * [Overflow menu](#overflow-menu) +* [Component specific tokens](#component-specific-tokens) + +--- + +## 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/) +- Technical documentation soon available + +## Accessibility + +Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) + +Android's top 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 top +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. + +For an overall content description of the top app bar, set an +`android:contentDescription` or use the `setContentDescription` method on the +`MaterialToolbar`. + +For the navigation icon, this can be achieved via the +`app:navigationContentDescription` attribute or +`setNavigationContentDescription` method. + +For action items and items within the overflow menu, the content description +needs to be set in the menu: + +```xml + + + + + +``` + +For images within top app bars, set an `android:contentDescription` +or use the `setContentDescription` method on the `ImageView`. + +## Variants + +### Regular top app bar + +> **Jetpack Compose implementation** + +Add `OdsTopAppBar` composable to your Scaffold topBar: + +```kotlin +OdsTopAppBar( + title = { + Text(text = "Title") + }, + navigationIcon = { + Icon( + painter = painterResource(id = R.drawable.ic_back), + contentDescription = "content description" + ) + }, + onNavigationIconClick = { + // Do something + }, + actions = { + OdsTopAppBarActionButton( + onClick = { }, + painter = painterResource(id = R.drawable.ic_share), + contentDescription = "content description" + ) // Each action should be an `OdsTopAppBarActionButton`. They are displayed in a `Row`, so icons inside will be placed horizontally. + } +) +``` + +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). + +> **XML implementation** + +API and source code: + +* `CoordinatorLayout`: [Class definition](https://developer.android.com/reference/androidx/coordinatorlayout/widget/CoordinatorLayout) +* `AppBarLayout`: [Class definition](https://developer.android.com/reference/com/google/android/material/appbar/AppBarLayout), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/appbar/AppBarLayout.java) +* `MaterialToolbar`: [Class definition](https://developer.android.com/reference/com/google/android/material/appbar/MaterialToolbar), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/appbar/MaterialToolbar.java) +* `CollapsingToolbarLayout`: [Class definition](https://developer.android.com/reference/com/google/android/material/appbar/CollapsingToolbarLayout), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/appbar/CollapsingToolbarLayout.java) + +In the layout: + +```xml + + + + + + + + + + + + + + + + + +``` + +In `@menu/top_app_bar.xml`: + +```xml + + + + + + + + + + +``` + +In menu/navigation icons: + +```xml + + +``` + +In code: + +```kotlin +topAppBar.setNavigationOnClickListener { + // Handle navigation icon press +} + +topAppBar.setOnMenuItemClickListener { menuItem -> + when (menuItem.itemId) { + R.id.favorite -> { + // Handle favorite icon press + true + } + R.id.search -> { + // Handle search icon press + true + } + R.id.more -> { + // Handle more item (inside overflow menu) press + true + } + else -> false + } +} +``` + +_**Applying scrolling behavior to the top app bar**_ + +The following example shows the top app bar positioned at the same elevation as +content. Upon scroll, it increases elevation and lets content scroll behind it. + +In the layout: + +```xml + + + + + + + + + + +``` + +_**Raised top app bar**_ + +If you need to have a top app bar with some elevation you can set the `@style/Widget.Orange.Toolbar.Raised` + +```xml + + + + + + + + + + +``` + +### Large top app bar + +> **Jetpack Compose implementation** + +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:") +``` + +Then you can add `OdsLargeTopAppBar` composable to your Scaffold topBar: + +```kotlin +OdsLargeTopAppBar( + title = { + Text(text = "Title") + }, + navigationIcon = { + Icon( + painter = painterResource(id = R.drawable.ic_back), + contentDescription = "content description" + ) + }, + onNavigationIconClick = { + // Do something + }, + actions = { + OdsTopAppBarActionButton( + onClick = { }, + painter = painterResource(id = R.drawable.ic_share), + contentDescription = "content description" + ) // Each action should be an `OdsTopAppBarActionButton`. They are displayed in a `Row`, so icons inside will be placed horizontally. + }, + 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 +} +``` + +## Extras + +### Overflow menu + +![Overflow menu light](images/app_bar_top_overflow_menu_light.png) +![Overflow menu dark](images/app_bar_top_overflow_menu_dark.png) + +You can easily add an overflow menu to your top app bar by using the `OdsTopAppBarOverflowMenuBox` composable as follow: + +```kotlin +OdsTopAppBarOverflowMenuBox(overflowIconContentDescription = "more actions") { + OdsDropdownMenuItem( + text = "account", + onClick = { + // Do something + } + ) + OdsDropdownMenuItem( + text = "settings", + onClick = { + // Do something + } + ) +} +``` + +## Component specific tokens + +_Soon available_ diff --git a/docs/0.14.0/components/AppBarsTop_docs.md b/docs/0.14.0/components/AppBarsTop_docs.md new file mode 100644 index 000000000..1afad632b --- /dev/null +++ b/docs/0.14.0/components/AppBarsTop_docs.md @@ -0,0 +1,4 @@ +--- +layout: main +content_page: AppBarsTop.md +--- \ No newline at end of file diff --git a/docs/0.14.0/components/Banners.md b/docs/0.14.0/components/Banners.md new file mode 100644 index 000000000..5311c240a --- /dev/null +++ b/docs/0.14.0/components/Banners.md @@ -0,0 +1,66 @@ +--- +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 + +--- + +**Page Summary** + +* [Specifications references](#specifications-references) +* [Accessibility](#accessibility) +* [Implementation](#implementation) +* [Component specific tokens](#component-specific-tokens) + +--- + +## 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) +- Technical documentation soon available + +## Accessibility + +Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) + +Users should be able to use the left phone buttons to interact with the banner. +The user should be able to hear the current state of the banner at all times. +Recommendation is available at the Orange Accessibility site + +## Implementation + +![Banner light](images/banner_light.png) + +![Banner dark](images/banner_dark.png) + +> **Jetpack Compose implementation** + +You can use the `OdsBanner` composable like this: + +```kotlin +OdsBanner( + message = "Message displayed in the banner.", + button1Text = "Dismiss", + button2Text = "Detail", // Optional + image = painterResource(id = R.drawable.placeholder), // Optional + imageContentDescription = "", // Optional + onButton1Click = { + // Do something + }, + onButton2Click = { + // Do something + }, // Optional +) +``` + +## Component specific tokens + +_Soon available_ \ No newline at end of file diff --git a/docs/0.14.0/components/Banners_docs.md b/docs/0.14.0/components/Banners_docs.md new file mode 100644 index 000000000..78ed1c027 --- /dev/null +++ b/docs/0.14.0/components/Banners_docs.md @@ -0,0 +1,4 @@ +--- +layout: main +content_page: Banners.md +--- \ No newline at end of file diff --git a/docs/0.14.0/components/Buttons.md b/docs/0.14.0/components/Buttons.md new file mode 100644 index 000000000..e4ad3dd9c --- /dev/null +++ b/docs/0.14.0/components/Buttons.md @@ -0,0 +1,301 @@ +--- +layout: detail +title: Buttons +description: Buttons allow users to take actions, and make choices, with a single tap. +--- + +--- + +**Page Summary** + +* [Specifications references](#specifications-references) +* [Accessibility](#accessibility) +* [Variants](#variants) + * [Text button](#text-button) + * [Outlined button](#outlined-button) + * [Contained button](#contained-button) + * [Icon button](#icon-button) + * [Icon toggle button](#icon-toggle-button) + * [Icon toggle buttons row](#icon-toggle-buttons-row) +* [Component specific tokens](#component-specific-tokens) + +--- + +## Specifications references + +- [Design System Manager - Buttons](https://system.design.orange.com/0c1af118d/p/06a393-buttons/b/530521) +- [Material Design - Buttons](https://material.io/components/buttons/) +- Technical documentation soon available + +## Accessibility + +Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) + +Buttons support content labeling for accessibility and are readable by most screen readers, such as +TalkBack. Text rendered in buttons is automatically provided to accessibility services. Additional +content labels are usually unnecessary. + +## Variants + +### Text button + +Text buttons are typically used for less-pronounced actions, including those located in dialogs and +cards. In cards, text buttons help maintain an emphasis on card content. + +![TextButton](images/button_text_light.png) ![TextButton dark](images/button_text_dark.png) + +> **Jetpack Compose implementation** + +Use the `OdsTextButton` composable: + +```kotlin +OdsTextButton( + text = "Text button", + onClick = {}, + enabled = true, + icon = painterResource(R.drawable.ic_coffee), // Optional, line can be removed if you don't need any icon + style = OdsTextButtonStyle.Primary +) +``` + +> **XML implementation** + +To create a Text Button using Orange theme you will need to apply +style `@style/Widget.Orange.Button.Text` on your `Button` layout + +In the layout: + +```xml +