-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs: add new component chapters (#476)
* docs: add TextField * docs: add SelectField * docs: add RadioField * docs: add ClickableField * docs: add CheckboxField * Update docs/03-components/05-input/checkbox.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/checkbox.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/checkbox.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/checkbox.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/inputfield.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/radio.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/textarea.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/radio.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/select.md Co-authored-by: Marek Osvald <[email protected]> * Update docs/03-components/05-input/select.md Co-authored-by: Marek Osvald <[email protected]> --------- Co-authored-by: Marek Osvald <[email protected]>
- Loading branch information
Showing
10 changed files
with
525 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
`Checkbox` component is provided in two flavors, as a simple checkbox and as a row with an additional label and a description: | ||
|
||
- [`Checkbox`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-checkbox.html) - a simple checkbox | ||
- [`CheckboxField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-checkbox-field.html) a checkbox with a label and a description | ||
|
||
## Usage | ||
|
||
`Checkbox` accepts a `Boolean` state and a callback on its change. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
Checkbox( | ||
checked = false, | ||
onCheckedChange = {}, | ||
) | ||
} | ||
``` | ||
|
||
`CheckboxField` has two additional slots - `description` and `label`. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
CheckboxField( | ||
checked = false, | ||
onCheckedChange = {}, | ||
description = { Text("If selected, you will get the latest updates.") } | ||
) { | ||
Text("Autoupdate") | ||
} | ||
} | ||
``` | ||
|
||
## UI testing | ||
|
||
The slotting API allows you to add a testTag to particular component parts. Utilize `assertIsOn` and `assertIsOff` to check the state. | ||
|
||
```kotlin | ||
composeTestRule.setContent { | ||
var checked by remember { mutableStateOf(false) } | ||
CheckboxField( | ||
modifier = Modifier.testTag("checkbox"), | ||
checked = checked, | ||
onCheckedChange = { checked = !checked }, | ||
) { | ||
Text("Label") | ||
} | ||
} | ||
|
||
val checkbox = composeTestRule.onNodeWithTag("checkbox") | ||
checkbox.assertIsOff() | ||
checkbox.performClick() | ||
checkbox.assertIsOn() | ||
``` | ||
|
||
## Customization | ||
|
||
`Checkbox` and `CheckboxField` appearance is not customizable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,120 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
`TextField` component is provided as Orbit Compose implementation of `Input Field` in Orbit design. It is available in two | ||
flavors: | ||
|
||
- [`TextField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-text-field.html) | ||
- [`PasswordTextField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-password-text-field.html) | ||
|
||
To customize Password field, you may want to show | ||
|
||
- [`PasswordStrengthIndicator`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-password-strength-indicator.html) | ||
|
||
`TextField` represents an atomic block of a label, an input and an info/error message. | ||
|
||
## Usage | ||
|
||
`TextField` accepts a text value and a callback for its change. Read how to [manage text field state](https://medium.com/androiddevelopers/effective-state-management-for-textfield-in-compose-d6e5b070fbe5). | ||
Provide a label. Optionally, you may pass a placeholder, leading & trailing icons with their respective callbacks, or an error or an info message. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
TextField( | ||
value = "...", | ||
onValueChange = { /* ... */ }, | ||
label = { Text("Full name") }, | ||
) | ||
} | ||
``` | ||
|
||
Pass a composable lambda if there is an error: | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
var value by remember { mutableStateOf("") } | ||
TextField( | ||
value = value, | ||
onValueChange = { value = it }, | ||
error = if (value.length > 3) { | ||
@Composable { Text("Error") } | ||
} else { | ||
null | ||
}, | ||
) | ||
} | ||
``` | ||
|
||
To utilize password strength indicator, use the `strengthContent` slot on `PasswordTextField` composable, evaluate the strength as a `0f <= strength <= 1f` and map this strength to predefined colors, alternatively pass custom colors. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
PasswordTextField( | ||
value = value, | ||
onValueChange = { value = it }, | ||
strengthContent = { | ||
val strength = calcStrength(value) | ||
PasswordStrengthIndicator( | ||
modifier = Modifier.testTag("passwordStrength"), | ||
value = strength, | ||
color = when { | ||
strength < 0.2f -> PasswordStrengthColor.Weak | ||
strength < 0.6f -> PasswordStrengthColor.Weak | ||
strength < 0.8f -> PasswordStrengthColor.Medium | ||
else -> PasswordStrengthColor.Strong | ||
}, | ||
label = { Text("Strength: $strength") }, | ||
) | ||
}, | ||
) | ||
} | ||
``` | ||
|
||
## UI testing | ||
|
||
Slotting API allows you to add testTag to particular component parts. | ||
|
||
```kotlin | ||
composeTestRule.setContent { | ||
var value by remember { mutableStateOf("") } | ||
TextField( | ||
modifier = Modifier.testTag("textfield"), | ||
value = value, | ||
onValueChange = { value = it }, | ||
info = { Text("Info") }, | ||
error = if (value.length > 3) { | ||
@Composable { Text("Error") } | ||
} else { | ||
null | ||
}, | ||
label = { Text("Label") }, | ||
placeholder = { Text("Placeholder") }, | ||
) | ||
} | ||
|
||
val textField = composeTestRule.onNodeWithTag("textfield") | ||
textField.assert(hasEditTextExactly("")) | ||
textField.assertTextEquals("Label", "Placeholder", includeEditableText = false) | ||
textField.performTextReplacement("text") | ||
textField.assert(hasEditTextExactly("text")) | ||
|
||
private fun hasEditTextExactly(expected: String): SemanticsMatcher { | ||
val propertyName = SemanticsProperties.EditableText.name | ||
return SemanticsMatcher( | ||
"$propertyName = [$expected]", | ||
) { node -> | ||
val actual = node.config.getOrNull(SemanticsProperties.EditableText) | ||
actual?.text == expected | ||
} | ||
} | ||
``` | ||
|
||
## Customization | ||
|
||
`TextField` appearance is not customizable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
InputFile orbit component is provided only as a visual representation of a clickable field with the almost same API as common TextField. | ||
- [`ClickableField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-clickable-field.html) | ||
|
||
## Usage | ||
|
||
Define the text value and click action of the `ClickableField`. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
ClickableField( | ||
value = "Attach filed", | ||
onClick = { /* ... */ }, | ||
label = { Text("Attachment") }, | ||
info = { Text("Attach JPEG.") }, | ||
leadingIcon = { Icon(Icons.Attachment, contentDescription = null) }, | ||
) | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
`Radio` component is provided in two flavors, as a simple radio and as a row with an additional label and a | ||
description: | ||
|
||
- [`Radio`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-radio.html) - simple radio | ||
- [`RadioField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-radio-field.html) a radio with label and description | ||
|
||
## Usage | ||
|
||
`Checkbox` accepts a boolean state and a callback on its change. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
Radio( | ||
selected = false, | ||
onClick = { /*...*/ }, | ||
) | ||
} | ||
``` | ||
|
||
`RadioField` has two additional slots - a `description` and a `label`. | ||
|
||
```kotlin | ||
@Composable | ||
enum class TvShow { StarTrek, StarWars } | ||
|
||
fun Example() { | ||
var tvshow by remember { mutableStateOf(TvShow.StarTrek) } | ||
Column { | ||
RadioField( | ||
selected = tvshow == TvShow.StarTrek, | ||
onClick = { tvshow = TvShow.StarTrek }, | ||
description = { Text("Engage.") } | ||
) { | ||
Text("StarTrek") | ||
} | ||
RadioField( | ||
selected = tvshow == TvShow.StarWars, | ||
onClick = { tvshow = TvShow.StarWars }, | ||
description = { Text("May the force be with you.") } | ||
) { | ||
Text("StarWars") | ||
} | ||
} | ||
} | ||
``` | ||
|
||
## UI testing | ||
|
||
The Slotting API allows you to add a `testTag` to particular component parts. Utilize `assertIsSelected` | ||
and `assertIsNotSelected` to check the state. | ||
|
||
```kotlin | ||
composeTestRule.setContent { | ||
var selected by remember { mutableStateOf(false) } | ||
RadioField( | ||
modifier = Modifier.testTag("radio"), | ||
selected = selected, | ||
onClick = { selected = !selected }, | ||
description = { Text("Description") }, | ||
) { | ||
Text("Label") | ||
} | ||
} | ||
|
||
val radio = composeTestRule.onNodeWithTag("radio") | ||
radio.assertIsNotSelected() | ||
radio.performClick() | ||
radio.assertIsSelected() | ||
``` | ||
|
||
## Customization | ||
|
||
`Radio` and `RadioField` appearance is not customizable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
`SelectField` component is provided as combination of the input and popup list: | ||
|
||
- [`SelectField`](https://kiwicom.github.io/orbit-compose/ui/kiwi.orbit.compose.ui.controls/-select.html) | ||
|
||
## Usage | ||
|
||
`SelectField` API is similar to `TextField`, it accepts the value, `label`, `error` and `info` slots, and more. Pass the `List<T>` options and define their rendering using the `optionContent` slot. You may utilize `leadingIcon`, but it cannot be made clickable as the whole field is clickable and opens the popup list. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
var selected by remeber { mutableStateOf("A") } | ||
SelectField( | ||
value = selected, | ||
options = remember { listOf("A", "B", "C") }, | ||
onOptionSelect = { selected = it }, | ||
label = { Text("Pick a letter") } | ||
) { letter -> | ||
Text(letter) | ||
} | ||
} | ||
``` | ||
|
||
## UI testing | ||
|
||
The slotting API allows you to add `testTag` to particular options. Utilize the unmerged tree to click them. The select's value is exposed through the `EditableText` semantic property. | ||
|
||
```kotlin | ||
composeTestRule.setContent { | ||
var selected by remember { mutableStateOf("A") } | ||
SelectField( | ||
modifier = Modifier.testTag("select"), | ||
value = selected, | ||
options = listOf("A", "B", "C"), | ||
onOptionSelect = { selected = it }, | ||
label = { Text("Pick letter") }, | ||
) { letter -> | ||
Text(letter, modifier = Modifier.testTag("option$letter")) | ||
} | ||
} | ||
|
||
val select = composeTestRule.onNodeWithTag("select") | ||
select.assert(hasEditTextExactly("A")) | ||
select.performClick() | ||
composeTestRule.onNodeWithTag("optionB", useUnmergedTree = true).performClick() | ||
select.assert(hasEditTextExactly("B")) | ||
|
||
private fun hasEditTextExactly(expected: String): SemanticsMatcher { | ||
val propertyName = SemanticsProperties.EditableText.name | ||
return SemanticsMatcher( | ||
"$propertyName = [$expected]", | ||
) { node -> | ||
val actual = node.config.getOrNull(SemanticsProperties.EditableText) | ||
actual?.text == expected | ||
} | ||
} | ||
``` | ||
|
||
## Customization | ||
|
||
`SelectField` appearance is not customizable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
--- | ||
title: Android | ||
--- | ||
|
||
## Overview | ||
|
||
Support for a multi-line text input (textarea) is provided | ||
by [TextField composable](https://orbit.kiwi/components/input/inputfield/android/). | ||
|
||
Simply utilize `singleLine`. Optionally you may set up the maximum of rendered lines by the `maxLines` argument. | ||
|
||
```kotlin | ||
@Composable | ||
fun Example() { | ||
TextField( | ||
value = "...", | ||
onValueChange = {}, | ||
singleLine = false, | ||
maxLines = 4, | ||
) | ||
} | ||
``` |
Oops, something went wrong.