From 0ee00c1b4a229d8fdb6dc38a2c84cab8c722dba5 Mon Sep 17 00:00:00 2001 From: Pauline Auvray Date: Tue, 10 Oct 2023 11:59:56 +0200 Subject: [PATCH] [#638] Review and improve documentation presentation --- docs/Gemfile.lock | 3 +-- docs/_layouts/main.html | 8 +++--- docs/components/AppBarsBottom.md | 5 ++-- docs/components/AppBarsTop.md | 14 ++++++---- docs/components/Banners.md | 9 ++++--- docs/components/Buttons.md | 33 +++++++++++++++++------- docs/components/Cards.md | 21 ++++++++++----- docs/components/Checkboxes.md | 13 +++++----- docs/components/Chips.md | 21 +++++++++------ docs/components/Dialogs.md | 9 ++++--- docs/components/FloatingActionButtons.md | 15 ++++++----- docs/components/ImageTile.md | 9 ++++--- docs/components/Lists.md | 5 ++-- docs/components/Menus.md | 13 ++++++---- docs/components/NavigationBottom.md | 11 ++++---- docs/components/NavigationDrawers.md | 5 ++-- docs/components/ProgressIndicators.md | 13 ++++++---- docs/components/RadioButtons.md | 11 ++++---- docs/components/SheetsBottom.md | 5 ++-- docs/components/Sliders.md | 11 ++++---- docs/components/Snackbars.md | 5 ++-- docs/components/Switches.md | 4 +-- docs/components/Tabs.md | 5 ++-- docs/components/TextFields.md | 5 ++-- 24 files changed, 146 insertions(+), 107 deletions(-) diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 4e4f775c1..922e82498 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -16,7 +16,6 @@ GEM http_parser.rb (~> 0) eventmachine (1.2.7) ffi (1.15.5) - ffi (1.15.5-x64-mingw-ucrt) ffi (1.15.5-x64-unknown) forwardable-extended (2.6.0) http_parser.rb (0.8.0) @@ -83,7 +82,7 @@ GEM webrick (1.8.1) PLATFORMS - x64-mingw-ucrt + x64-unknown x64-unknown x86_64-darwin-19 x86_64-darwin-21 diff --git a/docs/_layouts/main.html b/docs/_layouts/main.html index 712f397ff..bdd0eddd7 100644 --- a/docs/_layouts/main.html +++ b/docs/_layouts/main.html @@ -17,7 +17,11 @@ max-height: 100%; } - h4 { + h2, h3 { + margin-top: 3rem; + } + + h4, h5 { margin-top: 2rem; } @@ -93,8 +97,6 @@ } - - {{ page.title }} diff --git a/docs/components/AppBarsBottom.md b/docs/components/AppBarsBottom.md index 315e29b85..71ba82119 100644 --- a/docs/components/AppBarsBottom.md +++ b/docs/components/AppBarsBottom.md @@ -4,9 +4,8 @@ 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) diff --git a/docs/components/AppBarsTop.md b/docs/components/AppBarsTop.md index 3c729ebad..890894853 100644 --- a/docs/components/AppBarsTop.md +++ b/docs/components/AppBarsTop.md @@ -4,9 +4,8 @@ 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) @@ -66,8 +65,11 @@ 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). +{:.bd-callout .bd-callout-info} -Parameter | Default value | Description +##### OdsTopAppBar API + +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 @@ -145,7 +147,9 @@ Scaffold( } ``` -Parameter | Default value | Description +##### 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 diff --git a/docs/components/Banners.md b/docs/components/Banners.md index 17e302c08..3ec851f86 100644 --- a/docs/components/Banners.md +++ b/docs/components/Banners.md @@ -10,9 +10,8 @@ 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) @@ -54,7 +53,9 @@ OdsBanner( ) ``` -Parameter | Default value | Description +#### OdsBanner API + +Parameter | Default value | Description -- | -- | -- `message: String` | | Text displayed into the banner `firstButton: OdsBannerButton` | | Principal button displayed in the banner diff --git a/docs/components/Buttons.md b/docs/components/Buttons.md index 9d736d278..6f5f4d906 100644 --- a/docs/components/Buttons.md +++ b/docs/components/Buttons.md @@ -4,9 +4,8 @@ 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) @@ -78,7 +77,9 @@ OdsButton( ) ``` -Parameter | Default value | Description +##### OdsButton API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text displayed into the button `onClick: () -> Unit` | | Callback invoked when the button is clicked @@ -114,7 +115,9 @@ OdsTextButton( ) ``` -Parameter | Default value | Description +##### OdsTextButton API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text displayed into the button `onClick: () -> Unit` | | Callback invoked on button click @@ -149,7 +152,9 @@ OdsOutlinedButton( ) ``` -Parameter | Default value | Description +##### OdsOutlinedButton API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text displayed into the button `onClick: () -> Unit` | | Callback invoked on button click @@ -188,7 +193,9 @@ OdsTextToggleButtonsRow( ) ``` -Parameter | Default value | Description +##### OdsTextToggleButtonsRow API + +Parameter | Default value | Description -- | -- | -- `textToggleButtons: List` | | Items displayed into the toggle group `selectedIndex: Int` | | `textToggleButtons` list index of the selected button @@ -223,7 +230,9 @@ OdsIconButton( ) ``` -Parameter | Default value | Description +##### OdsIconButton API + +Parameter | Default value | Description -- | -- | -- `icon: OdsIconButtonIcon` | | Icon to be drawn into the button `onClick: () -> Unit` | | Callback to be invoked when the button is clicked @@ -259,7 +268,9 @@ OdsIconToggleButton( ) ``` -Parameter | Default value | Description +##### OdsIconToggleButton API + +Parameter | Default value | Description -- | -- | -- `checked: Boolean` | | Controls the checked state of the button `onCheckedChange: (Boolean) -> Unit` | | Callback invoked when the button is checked @@ -305,7 +316,9 @@ OdsIconToggleButtonsRow( ) ``` -Parameter | Default value | Description +##### OdsIconToggleButtonsRow API + +Parameter | Default value | Description -- | -- | -- `icons: List` | | Icons to be displayed into the toggle group `selectedIndex: Int` | | `icons` list index of the selected button diff --git a/docs/components/Cards.md b/docs/components/Cards.md index a845c09f7..e6e2a226d 100644 --- a/docs/components/Cards.md +++ b/docs/components/Cards.md @@ -4,9 +4,8 @@ title: Cards description: Cards contain content and actions about a single subject. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -63,7 +62,9 @@ OdsVerticalImageFirstCard( ) ``` -Parameter | Default value | Description +##### OdsVerticalImageFirstCard API + +Parameter | Default value | Description -- | -- | -- `title: String` | | Title displayed into the card `image: OdsCardImage` | | Image displayed into the card @@ -111,7 +112,9 @@ OdsVerticalHeaderFirstCard( ) ``` -Parameter | Default value | Description +##### OdsVerticalHeaderFirstCard API + +Parameter | Default value | Description -- | -- | -- `title: String` | | Title displayed into the card `image: OdsCardImage` | | Image displayed into the card @@ -163,7 +166,9 @@ Row( } ``` -Parameter | Default value | Description +##### OdsSmallCard API + +Parameter | Default value | Description -- | -- | -- `title: String` | | Title displayed into the card `image: OdsCardImage` | | Image displayed into the card @@ -206,7 +211,9 @@ OdsHorizontalCard( ) ``` -Parameter | Default value | Description +##### OdsHorizontalCard API + +Parameter | Default value | Description -- | -- | -- `title: String` | | Title displayed into the card `image: OdsCardImage` | | Image displayed into the card diff --git a/docs/components/Checkboxes.md b/docs/components/Checkboxes.md index 952d91e9e..a2b2aedcb 100644 --- a/docs/components/Checkboxes.md +++ b/docs/components/Checkboxes.md @@ -10,9 +10,8 @@ Use checkboxes to: * Present a list containing sub-selections * Turn an item on or off in a desktop environment ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -34,11 +33,11 @@ Checkboxes support content labeling for accessibility and are readable by most s as TalkBack. Text rendered in check boxes is automatically provided to accessibility services. Additional content labels are usually unnecessary. -### Implementation +## Implementation ![Checkbox](images/checkbox_light.png) ![Checkbox dark](images/checkbox_dark.png) -#### Jetpack Compose +### Jetpack Compose In your composable screen you can use: @@ -51,7 +50,9 @@ OdsCheckbox( ) ``` -Parameter | Default value | Description +#### OdsCheckbox API + +Parameter | Default value | Description -- | -- | -- `checked: Boolean` | | Controls checked state of the checkbox `onCheckedChange: ((Boolean) -> Unit)?` | | Callback invoked on checkbox click. If `null`, then this is passive and relies entirely on a higher-level component to control the checked state. diff --git a/docs/components/Chips.md b/docs/components/Chips.md index 24e75c2e5..43918775b 100644 --- a/docs/components/Chips.md +++ b/docs/components/Chips.md @@ -4,9 +4,8 @@ title: Chips description: Chips are compact elements that represent an input, attribute, or action. --- ---- - -**Page summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -71,7 +70,9 @@ OdsChip( ) ``` -Parameter | Default value | Description +##### OdsChip API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text to be displayed into the chip `onClick: () -> Unit` | | Callback called on chip click @@ -113,7 +114,7 @@ OdsChip( ) ``` -Use the same API as the [Input chip](#input-chip). +Use the [OdsChip API](#odschip-api). ### Filter chip @@ -147,7 +148,9 @@ OdsFilterChip( ) ``` -Parameter | Default value | Description +##### OdsFilterChip API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text to be displayed into the chip `onClick: () -> Unit` | | Callback called on chip click @@ -188,7 +191,7 @@ OdsChip( ) ``` -Use the same API as the [Input chip](#input-chip). +Use the [OdsChip API](#odschip-api). ## Related components @@ -218,7 +221,9 @@ OdsChoiceChipsFlowRow( ) ``` -Parameter | Default value | Description +#### OdsChoiceChipsFlowRow API + +Parameter | Default value | Description -- | -- | -- `value: String` | | Initial value of the choice chips flow row `onValueChange: (value: T) -> Unit` | | Callback invoked when the value changes. The new value is provided as parameter. diff --git a/docs/components/Dialogs.md b/docs/components/Dialogs.md index 18dbd6e87..e6650b8c8 100644 --- a/docs/components/Dialogs.md +++ b/docs/components/Dialogs.md @@ -11,9 +11,8 @@ or a required action has been taken. Dialogs are purposefully interruptive, so they should be used sparingly. ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -55,7 +54,9 @@ OdsAlertDialog( ) ``` -Parameter | Default value | Description +##### OdsAlertDialog API + +Parameter | Default value | Description -- | -- | -- `text: String` | | Text displayed into the dialog which presents the details regarding the Dialog's purpose `confirmButton: OdsAlertDialogButton` | | Button displayed into the dialog which is meant to confirm a proposed action, thus resolving what triggered the dialog diff --git a/docs/components/FloatingActionButtons.md b/docs/components/FloatingActionButtons.md index 1806cd241..0d1dfa94b 100644 --- a/docs/components/FloatingActionButtons.md +++ b/docs/components/FloatingActionButtons.md @@ -4,9 +4,8 @@ title: Floating action buttons description: A floating action button (FAB) represents the primary action of a screen. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -57,7 +56,9 @@ OdsFloatingActionButton( ) ``` -Parameter | Default value | Description +##### OdsFloatingActionButton API + +Parameter | Default value | Description -- | -- | -- `icon: OdsFloatingActionButtonIcon` | | Icon used into the FAB `onClick: () -> Unit` | | Callback invoked on FAB click @@ -89,7 +90,7 @@ OdsFloatingActionButton( ) ``` -Use the same API as the [Regular FAB](#regular-fab). +Use [OdsFloatingActionButton API](#odsfloatingactionbutton-api). ### Extended FAB @@ -112,7 +113,9 @@ OdsExtendedFloatingActionButton( ) ``` -Parameter | Default value | Description +##### OdsExtendedFloatingActionButton API + +Parameter | Default value | Description -- | -- | -- `icon: OdsFloatingActionButtonIcon` | | Icon used into the FAB `onClick: () -> Unit` | | Callback invoked on FAB click diff --git a/docs/components/ImageTile.md b/docs/components/ImageTile.md index 2720f041f..c1c18808d 100644 --- a/docs/components/ImageTile.md +++ b/docs/components/ImageTile.md @@ -4,9 +4,8 @@ title: Image Tile description: --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -57,7 +56,9 @@ OdsImageTile( ) ``` -Parameter | Default value | Description +##### OdsImageTile API + +Parameter | Default value | Description -- | -- | -- `image: OdsImageTileImage` | | Image displayed into the tile `legendAreaDisplayType: OdsImageTileLegendAreaDisplayType` | | Controls how the title and the icon are displayed relatively to the image. If set to `OdsImageTileLegendAreaDisplayType.None`, no legend area will be displayed. diff --git a/docs/components/Lists.md b/docs/components/Lists.md index e47531ba7..0ce195c7d 100644 --- a/docs/components/Lists.md +++ b/docs/components/Lists.md @@ -4,9 +4,8 @@ title: Lists description: Lists are continuous, vertical indexes of text or images. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) diff --git a/docs/components/Menus.md b/docs/components/Menus.md index 940606d3f..e626b1e6d 100644 --- a/docs/components/Menus.md +++ b/docs/components/Menus.md @@ -4,9 +4,8 @@ title: Menus description: Menus appear from a button, action, or other control. It contains at least 2 items that can affect the app, the view or elements within the view. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -63,7 +62,9 @@ OdsDropdownMenu( ) ``` -Parameter | Default value | Description +##### OdsDropdownMenu API + +Parameter | Default value | Description -- | -- | -- `items: List` | | Items displayed into the dropdown menu `expanded: Boolean` | | Controls whether the menu is currently open and visible to the user @@ -102,7 +103,9 @@ OdsExposedDropdownMenu( ) ``` -Parameter | Default value | Description +##### OdsExposedDropdownMenu API + +Parameter | Default value | Description -- | -- | -- `label: String` | | Label of the exposed menu text field `items: List` | | Items displayed into the dropdown menu diff --git a/docs/components/NavigationBottom.md b/docs/components/NavigationBottom.md index d02eeb3dd..6950652fd 100644 --- a/docs/components/NavigationBottom.md +++ b/docs/components/NavigationBottom.md @@ -4,9 +4,8 @@ title: "Navigation: bottom" description: Bottom navigation bars allow movement between primary destinations in an app. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -32,7 +31,7 @@ Note that TalkBack already reads the bottom navigation items labels so the conte ![BottomNavigation dark](images/bottom_navigation_dark.png) -#### Jetpack Compose +### Jetpack Compose In your composable screen, use the `OdsBottomNavigation` composable. It should contain multiple `OdsBottomNavigationItem`s. @@ -72,7 +71,9 @@ OdsBottomNavigation( ) ``` -Parameter | Default value | Description +#### OdsBottomNavigation API + +Parameter | Default value | Description -- | -- | -- `modifier: Modifier` | `Modifier` | `Modifier` applied to the bottom navigation `items: List` | | Items displayed into the bottom navigation diff --git a/docs/components/NavigationDrawers.md b/docs/components/NavigationDrawers.md index fad504c4f..bf97fd0f5 100644 --- a/docs/components/NavigationDrawers.md +++ b/docs/components/NavigationDrawers.md @@ -4,9 +4,8 @@ title: Navigation drawers description: The navigation drawer slides in from the left when the nav icon is tapped. The content should be concerned with identity and/or navigation.. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) diff --git a/docs/components/ProgressIndicators.md b/docs/components/ProgressIndicators.md index 0a6901e1f..b888685b1 100644 --- a/docs/components/ProgressIndicators.md +++ b/docs/components/ProgressIndicators.md @@ -4,9 +4,8 @@ title: Progress indicators description: Progress indicators express an unspecified wait time or display the length of a process. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -75,7 +74,9 @@ OdsLinearProgressIndicator( ) ``` -Parameter | Default value | Description +##### OdsLinearProgressIndicator API + +Parameter | Default value | Description -- | -- | -- `modifier: Modifier` | `Modifier` | `Modifier` applied to the progress indicator `progress: Float?` | `null` | Progress indicator value where 0.0 represents no progress and 1.0 represents full progress. Values outside of this range are coerced into the range. If set to `null`, the progress indicator is indeterminate. @@ -121,7 +122,9 @@ OdsCircularProgressIndicator( ) ``` -Parameter | Default value | Description +##### OdsCircularProgressIndicator API + +Parameter | Default value | Description -- | -- | -- `modifier: Modifier` | `Modifier` | `Modifier` applied to the progress indicator `progress: Float?` | `null` | Progress indicator value where 0.0 represents no progress and 1.0 represents full progress. Values outside of this range are coerced into the range. If set to `null`, the progress indicator is indeterminate. diff --git a/docs/components/RadioButtons.md b/docs/components/RadioButtons.md index 84a6b605d..7261436ed 100644 --- a/docs/components/RadioButtons.md +++ b/docs/components/RadioButtons.md @@ -11,9 +11,8 @@ Use radio buttons to: * If available options can be collapsed, consider using a dropdown menu instead, as it uses less space. ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -40,7 +39,7 @@ usually unnecessary. ![RadioButton](images/radio_button_light.png) ![RadioButton dark](images/radio_button_dark.png) -### Jetpack Compose implementation +### Jetpack Compose In your composable screen you can use: @@ -52,7 +51,9 @@ OdsRadioButton( ) ``` -Parameter | Default value | Description +#### OdsRadioButton API + +Parameter | Default value | Description -- | -- | -- `selected: Boolean` | | Controls the selected state of the radio button `onClick: (() -> Unit)?` | | Callback invoked on radio button click. If `null`, then the radio button will not handle input events, and only act as a visual indicator of `selected` state. diff --git a/docs/components/SheetsBottom.md b/docs/components/SheetsBottom.md index d72081c79..64cd173a1 100644 --- a/docs/components/SheetsBottom.md +++ b/docs/components/SheetsBottom.md @@ -9,9 +9,8 @@ Use Sheets bottom to: * Display content that complements the screen’s primary content * Expose all complements options ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) diff --git a/docs/components/Sliders.md b/docs/components/Sliders.md index 4914d0cb1..476ac122f 100644 --- a/docs/components/Sliders.md +++ b/docs/components/Sliders.md @@ -4,9 +4,8 @@ title: Sliders description: Sliders allow users to make selections from a range of values. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -67,7 +66,9 @@ OdsSlider( ) ``` -Parameter | Default value | Description +##### OdsSlider API + +Parameter | Default value | Description -- | -- | -- `value: Float` | | Current value of the slider. If outside of `valueRange` provided, value will be coerced to this range. `onValueChange: (Float) -> Unit` | | Callback invoked on slider value change. `value` should be updated here. @@ -114,7 +115,7 @@ OdsSliderLockups( ) ``` -Parameter | Default value | Description +Parameter | Default value | Description -- | -- | -- `value: Float` | | Current value of the slider. If outside of `valueRange` provided, value will be coerced to this range. `onValueChange: (Float) -> Unit` | | Callback invoked on slider value change. `value` should be updated here. diff --git a/docs/components/Snackbars.md b/docs/components/Snackbars.md index 1065424b2..1ab751074 100644 --- a/docs/components/Snackbars.md +++ b/docs/components/Snackbars.md @@ -13,9 +13,8 @@ the screen, but can also be swiped off the screen. Snackbars can also offer the ability to perform an action, such as undoing an action that was just taken, or retrying an action that had failed. ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) diff --git a/docs/components/Switches.md b/docs/components/Switches.md index 6bfda5c21..232fbfd4b 100644 --- a/docs/components/Switches.md +++ b/docs/components/Switches.md @@ -8,7 +8,7 @@ Switches toggle the state of a single setting on or off. They are the preferred way to adjust settings on mobile.
-**Page Summary** +**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) @@ -49,7 +49,7 @@ OdsSwitch( #### OdsSwitch API -Parameter | Default value | Description +Parameter | Default value | Description -- | -- | -- `checked: Boolean` | | Controls the checked state of the switch `onCheckedChange: ((Boolean) -> Unit)?` | | Callback invoked on switch check. If `null`, then this is passive and relies entirely on a higher-level component to control the "checked" state. diff --git a/docs/components/Tabs.md b/docs/components/Tabs.md index 57113a3f1..b0fd66efb 100644 --- a/docs/components/Tabs.md +++ b/docs/components/Tabs.md @@ -4,9 +4,8 @@ title: Tabs description: Tabs organize content across different screens, data sets, and other interactions. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility) diff --git a/docs/components/TextFields.md b/docs/components/TextFields.md index f77d4ae2d..dc132c05b 100644 --- a/docs/components/TextFields.md +++ b/docs/components/TextFields.md @@ -4,9 +4,8 @@ title: Text fields description: Text fields let users enter and edit text. --- ---- - -**Page Summary** +
+**On this page** * [Specifications references](#specifications-references) * [Accessibility](#accessibility)