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]>
kiwicom · Jul 4, 2023 · b2f6a4a · b2f6a4a
1 parent d16864c
commit b2f6a4a
Show file tree

Hide file tree

Showing 10 changed files with 525 additions and 0 deletions.
diff --git a/docs/03-components/05-input/checkbox.md b/docs/03-components/05-input/checkbox.md
@@ -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.
diff --git a/docs/03-components/05-input/inputfield.md b/docs/03-components/05-input/inputfield.md
@@ -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.
diff --git a/docs/03-components/05-input/inputfile.md b/docs/03-components/05-input/inputfile.md
@@ -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) },
+    )
+}
+```
diff --git a/docs/03-components/05-input/radio.md b/docs/03-components/05-input/radio.md
@@ -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.
diff --git a/docs/03-components/05-input/select.md b/docs/03-components/05-input/select.md
@@ -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.
diff --git a/docs/03-components/05-input/textarea.md b/docs/03-components/05-input/textarea.md
@@ -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,
+    )
+}
+```