documentation and tests

Signed-off-by: Pablo <[email protected]>

designsystem/src/androidUnitTest/kotlin/org/hisp/dhis/mobile/ui/designsystem/LocationBarButtonSnapshotTest.kt

@@ -0,0 +1,23 @@
+package org.hisp.dhis.mobile.ui.designsystem
+
+import org.hisp.dhis.mobile.ui.designsystem.component.LocationBar
+import org.junit.Rule
+import org.junit.Test
+
+class LocationBarButtonSnapshotTest {
+    @get:Rule
+    val paparazzi = paparazzi()
+
+    @Test
+    fun launchSearchBarButtonTest() {
+        paparazzi.snapshot {
+            LocationBar(
+                currentResults = emptyList(),
+                onBackClicked = {},
+                onClearLocation = {},
+                onSearchLocation = {},
+                onLocationSelected = {},
+            )
+        }
+    }
+}

designsystem/src/androidUnitTest/kotlin/org/hisp/dhis/mobile/ui/designsystem/LocationBarSearchSnapshotTest.kt

@@ -0,0 +1,39 @@
+package org.hisp.dhis.mobile.ui.designsystem
+
+import org.hisp.dhis.mobile.ui.designsystem.component.LocationBar
+import org.hisp.dhis.mobile.ui.designsystem.component.SearchBarMode
+import org.hisp.dhis.mobile.ui.designsystem.component.model.LocationItemModel
+import org.junit.Rule
+import org.junit.Test
+
+class LocationBarSearchSnapshotTest {
+    @get:Rule
+    val paparazzi = paparazzi()
+
+    @Test
+    fun launchSearchBarButtonTest() {
+        paparazzi.snapshot {
+            LocationBar(
+                currentResults = listOf(
+                    LocationItemModel.StoredResult(
+                        "Location Item title",
+                        "Location Item address",
+                        0.0,
+                        0.0
+                    ),
+                    LocationItemModel.SearchResult(
+                        "Location Item title 2",
+                        "Location Item address 2",
+                        0.0,
+                        0.0
+                    )
+                ),
+                mode = SearchBarMode.SEARCH,
+                onBackClicked = {},
+                onClearLocation = {},
+                onSearchLocation = {},
+                onLocationSelected = {},
+            )
+        }
+    }
+}

designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/LocationSearchBar.kt

@@ -56,21 +56,37 @@ import org.hisp.dhis.mobile.ui.designsystem.theme.Spacing.Spacing16
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 import org.hisp.dhis.mobile.ui.designsystem.theme.TextColor
 
+/**
+ * DHIS2 Location Bar modes
+ * BUTTON: the Location Bar is displayed as a button and shows current search query if available.
+ * SEARCH: The Location Bar is displayed as an input and displays available location items.
+ */
 enum class SearchBarMode {
     BUTTON,
     SEARCH,
 }
 
+/**
+ * DHIS2 Location Bar.
+ * @param currentResults: the available location items to display before/after search.
+ * @param mode: the initial mode for the composable.
+ * @param onBackClicked: callback for when the back button is clicked.
+ * @param onClearLocation: callback for when the clear location button is clicked.
+ * @param onSearchLocation: callback for when the search location button is clicked.
+ * @param onLocationSelected: callback for when a location item is selected.
+ * @param onModeChanged: optional callback for when the mode is changed.
+ */
 @Composable
 fun LocationBar(
     currentResults: List<LocationItemModel>,
+    mode: SearchBarMode = SearchBarMode.BUTTON,
     onBackClicked: () -> Unit,
     onClearLocation: () -> Unit,
     onSearchLocation: (query: String) -> Unit,
     onLocationSelected: (LocationItemModel) -> Unit,
     onModeChanged: (currentMode: SearchBarMode) -> Unit = {},
 ) {
-    var currentMode by remember { mutableStateOf(SearchBarMode.BUTTON) }
+    var currentMode by remember { mutableStateOf(mode) }
     var currentSearch: String by remember { mutableStateOf("") }
 
     LaunchedEffect(currentMode) {
@@ -339,6 +355,12 @@ private fun SearchResultLocationItem(
     )
 }
 
+/**
+ * DHIS2 Location Item icon.
+ * @param icon: the ImageVector to display as an icon.
+ * @param tintedColor: the color to tint the icon with.
+ * @param bgColor: the color for the background.
+ */
 @Composable
 fun LocationItemIcon(
     icon: ImageVector,

designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/SearchBar.kt

@@ -57,6 +57,8 @@ import org.hisp.dhis.mobile.ui.designsystem.theme.TextColor
  * @param onQueryChange: on query change callback.
  * @param state: input shell state.
  * @param modifier: optional modifier.
+ * @param leadingIcon: optional leading icon to display.
+ * @param focusRequester: optional focus requester.
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable

designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/internal/modifiers/ClickableWithRipple.kt

@@ -11,7 +11,7 @@ import androidx.compose.ui.semantics.Role
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 
 @Composable
-fun Modifier.clickableWithRipple(
+internal fun Modifier.clickableWithRipple(
     role: Role = Role.Button,
     color: Color = SurfaceColor.Primary,
     onClick: () -> Unit,

designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/model/LocationItemModel.kt

@@ -6,6 +6,13 @@ sealed class LocationItemModel(
     val latitude: Double,
     val longitude: Double,
 ) {
+    /**
+     * UiModel used for Location Items which are stored in cache or local database.
+     * @param storedTitle: the label to display.
+     * @param storedSubtitle: the subtitle to display.
+     * @param storedLatitude: the latitude of the location.
+     * @param storedLongitude the longitude of the location.
+     */
     data class StoredResult(
         private val storedTitle: String,
         private val storedSubtitle: String,
@@ -18,6 +25,13 @@ sealed class LocationItemModel(
         longitude = storedLongitude,
     )
 
+    /**
+     * UiModel used for Location Items which are provided by external apis.
+     * @param searchedTitle: the label to display.
+     * @param searchedSubtitle: the subtitle to display.
+     * @param searchedLatitude: the latitude of the location.
+     * @param searchedLongitude the longitude of the location.
+     */
     data class SearchResult(
         private val searchedTitle: String,
         private val searchedSubtitle: String,