chore: Change the confusing parameter position to a clear name. #637 (#638)

* feat: Change the `position` parameter of MarkerState to a clearer name. #637

* feat: Rename example codes that were using the position `parameter` to `initialPosition`. #637

* Revert "feat: Rename example codes that were using the position `parameter` to `initialPosition`. #637"

This reverts commit 565007e4c2162a2b6e59e9eefee1718e067f0eb2.

* Revert "feat: Change the `position` parameter of MarkerState to a clearer name. #637"

This reverts commit 2aa9d4aba5503f670087a975ae20c66935e26845.

* feat: Add 'rememberUpdatedMarkerState' which updates the state value based on updates to the input parameters.

* chore: Add warning comment at rememberMarkerState.

* feat: Modify the example project to use the newly added 'rememberUpdatedMarkerState'.

* feat: Add test case for 'testRememberUpdatedMarkerStateBeUpdate'.

* feat: remove rememberSavable for rememberUpdatedMarkerState.

* feat: Deprecate rememberMarkerState function.

* Update maps-compose/src/main/java/com/google/maps/android/compose/Marker.kt

Co-authored-by: Uli Bubenheimer <[email protected]>

---------

Co-authored-by: Uli Bubenheimer <[email protected]>
Co-authored-by: Enrique López Mañas <[email protected]>

Author: 3 people

app/src/androidTest/java/com/google/maps/android/compose/GoogleMapViewTests.kt

@@ -18,6 +18,7 @@ import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.junit4.createComposeRule
@@ -281,6 +282,30 @@ class GoogleMapViewTests {
             .performClick()
     }
 
+    @Test
+    fun testRememberUpdatedMarkerStateBeUpdate() {
+        val testPoint0 = LatLng(0.0,0.0)
+        val testPoint1 = LatLng(37.6281576,-122.4264549)
+        val testPoint2 = LatLng(37.500012, 127.0364185)
+
+        val positionState = mutableStateOf(testPoint0)
+        lateinit var markerState: MarkerState
+
+        initMap {
+            markerState = rememberUpdatedMarkerState(position = positionState.value)
+        }
+
+        assertEquals(testPoint0, markerState.position)
+
+        positionState.value = testPoint1
+        composeTestRule.waitForIdle()
+        assertEquals(testPoint1, markerState.position)
+
+        positionState.value = testPoint2
+        composeTestRule.waitForIdle()
+        assertEquals(testPoint2, markerState.position)
+    }
+
     private fun zoom(
         shouldAnimate: Boolean,
         zoomIn: Boolean,

app/src/main/java/com/google/maps/android/compose/markerexamples/updatingnodragmarkerwithdatamodel/UpdatingNoDragMarkerWithDataModelActivity.kt

@@ -24,17 +24,15 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.Immutable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
-import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import androidx.lifecycle.lifecycleScope
 import com.google.android.gms.maps.model.LatLng
 import com.google.maps.android.compose.GoogleMap
 import com.google.maps.android.compose.Marker
-import com.google.maps.android.compose.MarkerState
 import com.google.maps.android.compose.defaultCameraPosition
 import com.google.maps.android.compose.rememberCameraPositionState
-import com.google.maps.android.compose.rememberMarkerState
+import com.google.maps.android.compose.rememberUpdatedMarkerState
 import com.google.maps.android.compose.singapore
 import com.google.maps.android.compose.singapore2
 import com.google.maps.android.compose.singapore3
@@ -128,30 +126,10 @@ fun Marker(
     position: LatLng,
     onClick: () -> Boolean = { false },
 ) {
-    val markerState = rememberUpdatedMarkerState(position)
+    val markerState = rememberUpdatedMarkerState(position = position)
 
     Marker(
         state = markerState,
         onClick = { onClick() }
     )
-}
-
-/**
- * Standard API pattern for remembering, initializing, and updating MarkerState for a
- * non-draggable Marker, where [position] comes from a data model.
- *
- * Implementation modeled after `rememberUpdatedState`.
- *
- * This one uses [remember] behind the scenes, not [rememberMarkerState], which uses
- * `rememberSaveable`. Our data model is the source of truth - `rememberSaveable` would
- * create a conflicting source of truth.
- */
-@Composable
-fun rememberUpdatedMarkerState(position: LatLng): MarkerState =
-    // This pattern is equivalent to what rememberUpdatedState() does:
-    // rememberUpdatedState() uses MutableState, we use MarkerState.
-    // This is more efficient than updating position in an effect,
-    // as we avoid an additional recomposition.
-    remember { MarkerState(position = position) }.also {
-        it.position = position
-    }
+}

maps-compose/src/main/java/com/google/maps/android/compose/Marker.kt

@@ -23,6 +23,7 @@ import androidx.compose.runtime.MutableState
 import androidx.compose.runtime.currentComposer
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCompositionContext
 import androidx.compose.runtime.saveable.Saver
 import androidx.compose.runtime.saveable.rememberSaveable
@@ -182,15 +183,43 @@ public class MarkerState private constructor(position: LatLng) {
  * Other use cases may be better served syncing [MarkerState.position] with a data model.
  *
  * This cannot be used to preserve info window visibility across configuration changes.
+ *
+ * This function does not automatically update the MarkerState when the input parameters change.
+ * If you need this implementation, use 'rememberUpdatedMarkerState'.
  */
 @Composable
+@Deprecated(
+    message = "Use 'rememberUpdatedMarkerState' instead - It may be confusing to think " +
+            "that the state is automatically updated as the position changes, " +
+            "so it will be changed or removed.",
+    replaceWith = ReplaceWith(
+        expression = """
+            val markerState = rememberSaveable(key = key, saver = MarkerState.Saver) {
+                MarkerState(position)
+            }
+        """
+    )
+)
 public fun rememberMarkerState(
     key: String? = null,
     position: LatLng = LatLng(0.0, 0.0)
 ): MarkerState = rememberSaveable(key = key, saver = MarkerState.Saver) {
     MarkerState(position)
 }
 
+/**
+ * This function updates the state value according to the update of the input parameter,
+ * like 'rememberUpdatedState'.
+ *
+ * This cannot be used to preserve state across configuration changes.
+ */
+@Composable
+public fun rememberUpdatedMarkerState(
+    position: LatLng = LatLng(0.0, 0.0)
+): MarkerState = remember {
+    MarkerState(position = position)
+}.also { it.position = position }
+
 /**
  * A composable for a marker on the map.
  * @param state the [MarkerState] to be used to control or observe the marker