feat(clustering): add incremental item diffing

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

@@ -23,6 +23,7 @@ import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.test.junit4.createComposeRule
@@ -164,6 +165,132 @@ class GoogleMapViewClusteringTests {
         }
     }
 
+    @OptIn(MapsComposeExperimentalApi::class)
+    @Test
+    fun testKeyedClusteringAppliesAdditionsRemovalsAndUpdates() {
+        val clusterManagerHolder = arrayOfNulls<ClusterManager<MyItem>>(1)
+        val firstItem = MyItem(startingPosition, "first", "Snippet", 0f)
+        val items = mutableStateOf(listOf(firstItem))
+
+        composeTestRule.setContent {
+            GoogleMapView(
+                modifier = Modifier.fillMaxSize(),
+                cameraPositionState = cameraPositionState,
+            ) {
+                Clustering(
+                    items = items.value,
+                    key = MyItem::title,
+                    onClusterManager = { clusterManagerHolder[0] = it },
+                )
+            }
+        }
+
+        val timeoutMillis = TimeUnit.SECONDS.toMillis(MAP_LOAD_TIMEOUT_SECONDS)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                clusterManagerHolder[0]?.algorithm?.items?.size == 1
+            }
+        }
+
+        val updatedPosition = LatLng(2.34, 5.67)
+        val addedItem = MyItem(LatLng(3.45, 6.78), "added", "Snippet", 0f)
+        items.value = listOf(firstItem.copy(position = updatedPosition), addedItem)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                val currentItems = clusterManagerHolder[0]?.algorithm?.items.orEmpty()
+                currentItems.size == 2 &&
+                    currentItems.any { it.title == "first" && it.position == updatedPosition } &&
+                    currentItems.any { it.title == "added" }
+            }
+        }
+
+        items.value = listOf(addedItem)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                val currentItems = clusterManagerHolder[0]?.algorithm?.items.orEmpty()
+                currentItems.size == 1 && currentItems.single().title == "added"
+            }
+        }
+    }
+
+    @OptIn(MapsComposeExperimentalApi::class)
+    @Test
+    fun testKeyedClusteringLeavesUnchangedItemsAlone() {
+        val clusterManagerHolder = arrayOfNulls<ClusterManager<MyItem>>(1)
+        val initialItem = MyItem(startingPosition, "same", "Snippet", 0f)
+        val items = mutableStateOf(listOf(initialItem))
+
+        composeTestRule.setContent {
+            GoogleMapView(
+                modifier = Modifier.fillMaxSize(),
+                cameraPositionState = cameraPositionState,
+            ) {
+                Clustering(
+                    items = items.value,
+                    key = MyItem::title,
+                    onClusterManager = { clusterManagerHolder[0] = it },
+                )
+            }
+        }
+
+        val timeoutMillis = TimeUnit.SECONDS.toMillis(MAP_LOAD_TIMEOUT_SECONDS)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                clusterManagerHolder[0]?.algorithm?.items?.size == 1
+            }
+        }
+        val marker = composeTestRule.runOnUiThread {
+            clusterManagerHolder[0]!!.markerCollection.getMarkers().single()
+        }
+
+        items.value = listOf(initialItem.copy())
+        composeTestRule.waitForIdle()
+
+        composeTestRule.runOnUiThread {
+            assertThat(clusterManagerHolder[0]?.algorithm?.items).containsExactly(initialItem)
+            assertThat(clusterManagerHolder[0]?.markerCollection?.getMarkers()).contains(marker)
+        }
+    }
+
+    @OptIn(MapsComposeExperimentalApi::class)
+    @Test
+    fun testUnkeyedClusteringStillUpdatesItemsByEquality() {
+        val clusterManagerHolder = arrayOfNulls<ClusterManager<MyItem>>(1)
+        val initialItem = MyItem(startingPosition, "first", "Snippet", 0f)
+        val items = mutableStateOf(listOf(initialItem))
+
+        composeTestRule.setContent {
+            GoogleMapView(
+                modifier = Modifier.fillMaxSize(),
+                cameraPositionState = cameraPositionState,
+            ) {
+                Clustering(
+                    items = items.value,
+                    onClusterManager = { clusterManagerHolder[0] = it },
+                )
+            }
+        }
+
+        val timeoutMillis = TimeUnit.SECONDS.toMillis(MAP_LOAD_TIMEOUT_SECONDS)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                clusterManagerHolder[0]?.algorithm?.items?.size == 1
+            }
+        }
+
+        val updatedItem = initialItem.copy(position = LatLng(2.34, 5.67))
+        val addedItem = MyItem(LatLng(3.45, 6.78), "added", "Snippet", 0f)
+        items.value = listOf(updatedItem, addedItem)
+        composeTestRule.waitUntil(timeoutMillis = timeoutMillis) {
+            composeTestRule.runOnUiThread {
+                val currentItems = clusterManagerHolder[0]?.algorithm?.items.orEmpty()
+                currentItems.size == 2 &&
+                    currentItems.any { it.title == "first" && it.position == updatedItem.position } &&
+                    currentItems.any { it.title == "added" }
+            }
+        }
+    }
+
     @OptIn(MapsComposeExperimentalApi::class)
     @Test
     fun testClusterItemContentUsingRememberComposeBitmapDescriptorDoesNotCrash() {

maps-app/src/main/java/com/google/maps/android/compose/markerexamples/MarkerClusteringActivity.kt

@@ -18,7 +18,6 @@ package com.google.maps.android.compose.markerexamples
 
 import android.os.Bundle
 import android.util.Log
-import androidx.compose.ui.text.intl.Locale
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
@@ -27,6 +26,7 @@ import androidx.compose.foundation.ScrollState
 import androidx.compose.foundation.horizontalScroll
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
@@ -43,25 +43,30 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.SideEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableStateListOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
-import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.platform.LocalConfiguration
 import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.intl.Locale
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import com.google.android.gms.maps.model.CameraPosition
 import com.google.android.gms.maps.model.LatLng
 import com.google.maps.android.clustering.ClusterItem
+import com.google.maps.android.clustering.ClusterManager
 import com.google.maps.android.clustering.algo.NonHierarchicalViewBasedAlgorithm
 import com.google.maps.android.clustering.view.DefaultClusterRenderer
+import com.google.maps.android.compose.Circle
 import com.google.maps.android.compose.GoogleMap
+import com.google.maps.android.compose.GoogleMapComposable
 import com.google.maps.android.compose.MapsComposeExperimentalApi
 import com.google.maps.android.compose.MarkerInfoWindow
 import com.google.maps.android.compose.clustering.Clustering
@@ -70,10 +75,10 @@ import com.google.maps.android.compose.clustering.rememberClusterManager
 import com.google.maps.android.compose.clustering.rememberClusterRenderer
 import com.google.maps.android.compose.rememberCameraPositionState
 import com.google.maps.android.compose.rememberUpdatedMarkerState
-import com.google.maps.android.compose.Circle
 import com.google.maps.android.compose.singapore
 import com.google.maps.android.compose.singapore2
 import kotlin.random.Random
+import kotlinx.coroutines.delay
 
 private val TAG = MarkerClusteringActivity::class.simpleName
 
@@ -107,57 +112,120 @@ fun GoogleMapClustering() {
     }
 }
 
+@OptIn(MapsComposeExperimentalApi::class)
 @Composable
 fun GoogleMapClustering(items: List<MyItem>) {
     var clusteringType by remember {
         mutableStateOf(ClusteringType.Default)
     }
+    Box(Modifier.fillMaxSize()) {
+        if (clusteringType == ClusteringType.KeyedDiff) {
+            KeyedDiffClustering()
+        } else {
+            ClusteringMap {
+                when (clusteringType) {
+                    ClusteringType.Default -> DefaultClustering(items)
+                    ClusteringType.CustomUi -> CustomUiClustering(items)
+                    ClusteringType.CustomRenderer -> CustomRendererClustering(items)
+                    ClusteringType.Decorations -> DecorationsClustering(items)
+                    ClusteringType.KeyedDiff -> Unit
+                }
+            }
+        }
+
+        ClusteringTypeControls(
+            modifier = Modifier.align(Alignment.TopCenter),
+            onClusteringTypeClick = { clusteringType = it },
+        )
+    }
+}
+
+@Composable
+private fun ClusteringMap(content: @Composable @GoogleMapComposable () -> Unit) {
     GoogleMap(
         modifier = Modifier.fillMaxSize(),
         cameraPositionState = rememberCameraPositionState {
             position = CameraPosition.fromLatLngZoom(singapore2, 6f)
         }
     ) {
-        when (clusteringType) {
-            ClusteringType.Default -> {
-                DefaultClustering(
-                    items = items,
-                )
+        content()
+        MarkerInfoWindow(
+            state = rememberUpdatedMarkerState(position = singapore2),
+            onClick = {
+                Log.d(TAG, "Non-cluster marker clicked! $it")
+                true
             }
+        )
+    }
+}
 
-            ClusteringType.CustomUi -> {
-                CustomUiClustering(
-                    items = items,
+@OptIn(MapsComposeExperimentalApi::class)
+@Composable
+private fun KeyedDiffClustering(modifier: Modifier = Modifier) {
+    val keyedItems = remember {
+        mutableStateListOf<MyItem>().apply {
+            addAll(List(5_000) { index ->
+                val row = index / 100
+                val column = index % 100
+                MyItem(
+                    position = LatLng(
+                        singapore2.latitude + (row - 25) * 0.001f,
+                        singapore2.longitude + (column - 50) * 0.001f,
+                    ),
+                    title = "item-$index",
+                    snippet = "Frequently updated keyed cluster item",
+                    zIndex = 0f,
                 )
-            }
+            })
+        }
+    }
+    var updateCount by remember { mutableIntStateOf(0) }
+    var lastUpdatedItemIndex by remember { mutableIntStateOf(-1) }
+    var clusterManager by remember { mutableStateOf<ClusterManager<MyItem>?>(null) }
 
-            ClusteringType.CustomRenderer -> {
-                CustomRendererClustering(
-                    items = items,
+    LaunchedEffect(Unit) {
+        var nextItemIndex = 0
+        while (true) {
+            delay(500)
+            repeat(100) {
+                val index = nextItemIndex++ % keyedItems.size
+                val item = keyedItems[index]
+                val direction = if (updateCount % 2 == 0) 1 else -1
+                keyedItems[index] = item.copy(
+                    position = LatLng(
+                        item.position.latitude + direction * 0.0002,
+                        item.position.longitude + direction * 0.0002,
+                    )
                 )
             }
+            lastUpdatedItemIndex = (nextItemIndex - 1) % keyedItems.size
+            updateCount++
+        }
+    }
 
-            ClusteringType.Decorations -> {
-                DecorationsClustering(
-                    items = items,
+    Box(modifier.fillMaxSize()) {
+        ClusteringMap {
+            Clustering(
+                items = keyedItems,
+                key = { item -> item.title },
+                onClusterManager = { clusterManager = it },
+            )
+        }
+        val managerItems = clusterManager?.algorithm?.items.orEmpty()
+        val lastUpdatedItem = managerItems.firstOrNull { it.title == "item-$lastUpdatedItemIndex" }
+        Surface(
+            modifier = Modifier.align(Alignment.TopCenter).padding(top = 72.dp),
+            color = MaterialTheme.colorScheme.surface.copy(alpha = 0.9f),
+        ) {
+            Column(Modifier.padding(8.dp)) {
+                Text("Keyed diff demo: 5,000 items; 100 updates / 500 ms")
+                Text(
+                    "Update $updateCount · ${managerItems.size} items · " +
+                        "item $lastUpdatedItemIndex at ${lastUpdatedItem?.position}"
                 )
             }
         }
-
-        MarkerInfoWindow(
-            state = rememberUpdatedMarkerState(position = singapore2),
-            onClick = {
-                Log.d(TAG, "Non-cluster marker clicked! $it")
-                true
-            }
-        )
     }
-
-    ClusteringTypeControls(
-        onClusteringTypeClick = {
-            clusteringType = it
-        },
-    )
 }
 
 @OptIn(MapsComposeExperimentalApi::class)
@@ -354,6 +422,7 @@ private fun ClusteringTypeControls(
                     ClusteringType.CustomUi -> "Custom UI"
                     ClusteringType.CustomRenderer -> "Custom Renderer"
                     ClusteringType.Decorations -> "Decorations"
+                    ClusteringType.KeyedDiff -> "Keyed diff (5k)"
                 },
                 onClick = { onClusteringTypeClick(it) }
             )
@@ -380,6 +449,7 @@ private enum class ClusteringType {
     CustomUi,
     CustomRenderer,
     Decorations,
+    KeyedDiff,
 }
 
 data class MyItem(