diff --git a/changelog.md b/changelog.md index 7ca4c937d..dc189a0a8 100644 --- a/changelog.md +++ b/changelog.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased](https://github.com/Orange-OpenSource/ods-android/compare/0.16.0...develop) +### Changed + +- \[Lib\] Review and update technical documentation ([#638](https://github.com/Orange-OpenSource/ods-android/issues/638)) + ### Fixed - \[App\] Change illustrations alignment for slider and text field components ([#618](https://github.com/Orange-OpenSource/ods-android/issues/618)) diff --git a/docs/_layouts/main.html b/docs/_layouts/main.html index 959e4ea1e..bdd0eddd7 100644 --- a/docs/_layouts/main.html +++ b/docs/_layouts/main.html @@ -17,6 +17,14 @@ max-height: 100%; } + h2, h3 { + margin-top: 3rem; + } + + h4, h5 { + margin-top: 2rem; + } + #outer { width:100%; height:100%; diff --git a/docs/components/AppBarsBottom.md b/docs/components/AppBarsBottom.md index c78807e84..8c7367f02 100644 --- a/docs/components/AppBarsBottom.md +++ b/docs/components/AppBarsBottom.md @@ -4,14 +4,10 @@ title: "App bars: bottom" description: A bottom app bar displays navigation and key actions at the bottom of mobile screens. --- ---- - -**Page Summary** +
**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) -* [Implementation](#implementation) -* [Component specific tokens](#component-specific-tokens) --- @@ -19,7 +15,6 @@ description: A bottom app bar displays navigation and key actions at the bottom - [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 @@ -33,135 +28,4 @@ action performs. While optional, their use is strongly encouraged. 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_ +like TalkBack are able to announce their purpose or action, if any. \ No newline at end of file diff --git a/docs/components/AppBarsTop.md b/docs/components/AppBarsTop.md index b51fb0d83..1024be842 100644 --- a/docs/components/AppBarsTop.md +++ b/docs/components/AppBarsTop.md @@ -4,18 +4,17 @@ title: "App bars: top" description: Top app bars display information and actions relating to the current screen. --- ---- - -**Page Summary** +
**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) -* [Extras](#extras) - * [Overflow menu](#overflow-menu) -* [Component specific tokens](#component-specific-tokens) + * [Jetpack Compose](#jetpack-compose-1) + * [OdsLargeTopAppBar API](#odslargetopappbar-api) --- @@ -23,51 +22,23 @@ description: Top app bars display information and actions relating to the curren - [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, +`OdsTopAppBar` provides accessibility 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`. +action performs. ## Variants ### Regular top app bar -> **Jetpack Compose implementation** +#### Jetpack Compose -Add `OdsTopAppBar` composable to your Scaffold topBar: +Add `OdsTopAppBar` composable to your Scaffold `topBar`. +Here is an example of use: ```kotlin OdsTopAppBar( @@ -75,20 +46,20 @@ OdsTopAppBar( navigationIcon = OdsTopAppBarNavigationIcon( painter = painterResource(id = R.drawable.ic_back), contentDescription = "content description", - onClick = { /* Do something */ } + onClick = { doSomething() } ), actions = listOf( OdsTopAppBarActionButton( painter = painterResource(id = R.drawable.ic_share), contentDescription = "content description", - onClick = { } + onClick = { doSomething() } ), // ... ), overflowMenuActions = listOf( OdsTopAppBarOverflowMenuActionItem( text = "Text", - onClick = { } + onClick = { doSomething() } ), // ... ) @@ -97,140 +68,21 @@ OdsTopAppBar( 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: +##### OdsTopAppBar API -```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 - - - - - - - - - - -``` +Parameter | Default 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: OdsTopAppBarNavigationIcon?` | `null` | Icon to be displayed at the start of the top app bar +`actions: List` | `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. +`overflowMenuActions: List` | `emptyList()` | Actions to be displayed in the 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 implementation** +#### 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: @@ -238,7 +90,7 @@ First, you have to add this line in your application `build.gradle.kts` file cau implementation("androidx.compose.material3:material3:") ``` -Then you can add `OdsLargeTopAppBar` composable to your Scaffold topBar: +Then you can add `OdsLargeTopAppBar` composable to your Scaffold `topBar`: ```kotlin OdsLargeTopAppBar( @@ -246,23 +98,23 @@ OdsLargeTopAppBar( navigationIcon = OdsTopAppBarNavigationIcon( painter = painterResource(id = R.drawable.ic_back), contentDescription = "content description", - onClick = { /* Do something */ } + onClick = { doSomething() } ), actions = listOf( OdsTopAppBarActionButton( painter = painterResource(id = R.drawable.ic_share), contentDescription = "content description", - onClick = { } + onClick = { doSomething() } ), // ... ), overflowMenuActions = listOf( OdsTopAppBarOverflowMenuActionItem( text = "Text", - onClick = { } + onClick = { doSomething() } ), // ... - ) + ), scrollBehavior = null // See below to attach a scroll behavior and make the top app bar collapsible ) ``` @@ -292,32 +144,14 @@ Scaffold( } ``` -## 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_ +##### OdsLargeTopAppBar API + +Parameter | Default 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: OdsTopAppBarNavigationIcon?` | `null` | Icon displayed at the start of the top app bar +`actions: List` | `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. +`overflowMenuActions: List` | `emptyList()` | Actions displayed in the overflow menu +`scrollBehavior: TopAppBarScrollBehavior?` | `null` | `TopAppBarScrollBehavior` attached to the top app bar +{:.table} diff --git a/docs/components/Banners.md b/docs/components/Banners.md index 5311c240a..8db1347dc 100644 --- a/docs/components/Banners.md +++ b/docs/components/Banners.md @@ -10,14 +10,13 @@ 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** +
**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) * [Implementation](#implementation) -* [Component specific tokens](#component-specific-tokens) + * [Jetpack Compose](#jetpack-compose) + * [OdsBanner API](#odsbanner-api) --- @@ -25,15 +24,12 @@ Only one banner should be shown at a time - [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 +`OdsBanner` is built to support accessibility criteria and is readable by most screen readers, such as TalkBack. The use of an `OdsBannerImage` force the developer to associate a content description to the banner image. ## Implementation @@ -41,26 +37,26 @@ Recommendation is available at the Orange Accessibility site ![Banner dark](images/banner_dark.png) -> **Jetpack Compose implementation** +### Jetpack Compose 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 + message = "Message displayed into the banner.", + firstButton = OdsBannerButton("Dismiss") { doSomething() }, + secondButton = OdsBannerButton("Detail") { doSomething() }, + image = OdsBannerImage(painterResource(id = R.drawable.placeholder), "") ) ``` -## Component specific tokens +#### OdsBanner API -_Soon available_ \ No newline at end of file +Parameter | Default value | Description +-- | -- | -- +`message: String` | | Text displayed into the banner +`firstButton: OdsBannerButton` | | Primary button displayed in the banner +`modifier: Modifier` | `Modifier` | `Modifier` applied to the banner +`image: OdsBannerImage?` | `null` | Image displayed in the banner in a circle shape +`secondButton: OdsBannerButton?` | `null` | Secondary button displayed into the banner next to the primary one +{:.table} diff --git a/docs/components/Buttons.md b/docs/components/Buttons.md index 269a6776a..893b847c7 100644 --- a/docs/components/Buttons.md +++ b/docs/components/Buttons.md @@ -4,21 +4,32 @@ title: Buttons description: Buttons allow users to take actions, and make choices, with a single tap. --- ---- - -**Page Summary** +
**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) * [Variants](#variants) + * [Contained button](#contained-button) + * [Jetpack Compose](#jetpack-compose) + * [OdsButton API](#odsbutton-api) * [Text button](#text-button) + * [Jetpack Compose](#jetpack-compose-1) + * [OdsTextButton API](#odstextbutton-api) * [Outlined button](#outlined-button) - * [Contained button](#contained-button) + * [Jetpack Compose](#jetpack-compose-2) + * [OdsOutlinedButton API](#odsoutlinedbutton-api) * [Text toggle buttons group](#text-toggle-buttons-group) + * [Jetpack Compose](#jetpack-compose-3) + * [OdsTextToggleButtonsRow API](#odstexttogglebuttonsrow-api) * [Icon button](#icon-button) + * [Jetpack Compose](#jetpack-compose-4) + * [OdsIconButton API](#odsiconbutton-api) * [Icon toggle button](#icon-toggle-button) + * [Jetpack Compose](#jetpack-compose-5) + * [OdsIconToggleButton API](#odsicontogglebutton-api) * [Icon toggle buttons group](#icon-toggle-buttons-group) -* [Component specific tokens](#component-specific-tokens) + * [Jetpack Compose](#jetpack-compose-6) + * [OdsIconToggleButtonsRow API](#odsicontogglebuttonsrow-api) --- @@ -26,104 +37,16 @@ description: Buttons allow users to take actions, and make choices, with a singl - [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 = OdsButtonIcon(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 - -