Merge branch 'main' into fix/clustering-idle-timeout

Author: dkhawk

.gemini/config.yaml

@@ -0,0 +1,23 @@
+# Gemini Code Assist Configuration
+# See: https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github
+
+# Feature settings
+have_fun: false
+
+code_review:
+  disable: false
+  comment_severity_threshold: MEDIUM
+  max_review_comments: -1
+
+pull_request_opened:
+  summary: true
+  code_review: true
+  include_drafts: true
+
+# Files to ignore in Gemini analysis
+ignore_patterns:
+  - "**/*.bin"
+  - "**/*.exe"
+  - "**/build/**"
+  - "**/.gradle/**"
+  - "**/secrets.properties"

.gemini/styleguide.md

@@ -0,0 +1,18 @@
+# Gemini Code Assist Style Guide: android-maps-compose
+
+This guide defines the custom code review and generation rules for the `android-maps-compose` project.
+
+## Jetpack Compose Guidelines
+- **API Guidelines**: Strictly follow the [Jetpack Compose API guidelines](https://github.com/androidx/androidx/blob/androidx-main/compose/docs/compose-api-guidelines.md).
+- **Naming**: Composable functions must be PascalCase.
+- **State Management**: Prefer library-provided state holders like `rememberCameraPositionState` or `MarkerState`.
+- **Modifiers**: The first optional parameter of any Composable should be `modifier: Modifier = Modifier`.
+
+## Kotlin Style
+- **Naming**: Use camelCase for variables and functions.
+- **Documentation**: Provide KDoc for all public classes, properties, and functions.
+- **Safety**: Use null-safe operators and avoid `!!`.
+
+## Project Specifics
+- **Secrets**: Never commit API keys. Ensure they are read from `secrets.properties` via `BuildConfig` or similar.
+- **Maps SDK**: Use the components provided in `maps-compose`, `maps-compose-utils`, and `maps-compose-widgets` rather than raw `GoogleMap` objects.

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "8.1.0"
+    ".": "8.2.0"
 }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [8.2.0](https://github.com/googlemaps/android-maps-compose/compare/v8.1.0...v8.2.0) (2026-02-24)
+
+
+### Features
+
+* added Clustering decoration ([#848](https://github.com/googlemaps/android-maps-compose/issues/848)) ([aa5793a](https://github.com/googlemaps/android-maps-compose/commit/aa5793a920f92c1efb0b90287092a33661acac4c))
+
 ## [8.1.0](https://github.com/googlemaps/android-maps-compose/compare/v8.0.1...v8.1.0) (2026-02-06)
 
 

README.md

@@ -29,12 +29,12 @@ You no longer need to specify the Maps SDK for Android or its Utility Library as
 
 ```groovy
 dependencies {
-    implementation 'com.google.maps.android:maps-compose:8.1.0' // {x-release-please-version}
+    implementation 'com.google.maps.android:maps-compose:8.2.0' // {x-release-please-version}
     // Optionally, you can include the Compose utils library for Clustering,
     // Street View metadata checks, etc.
-    implementation 'com.google.maps.android:maps-compose-utils:8.1.0' // {x-release-please-version}
+    implementation 'com.google.maps.android:maps-compose-utils:8.2.0' // {x-release-please-version}
     // Optionally, you can include the widgets library for ScaleBar, etc.
-    implementation 'com.google.maps.android:maps-compose-widgets:8.1.0' // {x-release-please-version}
+    implementation 'com.google.maps.android:maps-compose-widgets:8.2.0' // {x-release-please-version}
 }
 ```
 

build.gradle.kts

@@ -33,7 +33,7 @@ val projectArtifactId by extra { project: Project ->
 allprojects {
     group = "com.google.maps.android"
     // {x-release-please-start-version}
-    version = "8.1.0"
+    version = "8.2.0"
     // {x-release-please-end}
 }
 

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

@@ -54,6 +54,7 @@ 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
@@ -98,7 +99,7 @@ fun GoogleMapClustering(items: List<MyItem>) {
     GoogleMap(
         modifier = Modifier.fillMaxSize(),
         cameraPositionState = rememberCameraPositionState {
-            position = CameraPosition.fromLatLngZoom(singapore, 6f)
+            position = CameraPosition.fromLatLngZoom(singapore2, 6f)
         }
     ) {
         when (clusteringType) {
@@ -119,10 +120,16 @@ fun GoogleMapClustering(items: List<MyItem>) {
                     items = items,
                 )
             }
+
+            ClusteringType.Decorations -> {
+                DecorationsClustering(
+                    items = items,
+                )
+            }
         }
 
         MarkerInfoWindow(
-            state = rememberUpdatedMarkerState(position = singapore),
+            state = rememberUpdatedMarkerState(position = singapore2),
             onClick = {
                 Log.d(TAG, "Non-cluster marker clicked! $it")
                 true
@@ -272,6 +279,23 @@ fun CustomRendererClustering(items: List<MyItem>) {
 
 }
 
+@OptIn(MapsComposeExperimentalApi::class)
+@Composable
+private fun DecorationsClustering(items: List<MyItem>) {
+    Clustering(
+        items = items,
+        clusterItemDecoration = { item ->
+            Circle(
+                center = item.position,
+                radius = 10000.0,
+                fillColor = Color.Blue.copy(alpha = 0.2f),
+                strokeColor = Color.Blue,
+                strokeWidth = 2f
+            )
+        }
+    )
+}
+
 @Composable
 private fun CircleContent(
     color: Color,
@@ -313,6 +337,7 @@ private fun ClusteringTypeControls(
                     ClusteringType.Default -> "Default"
                     ClusteringType.CustomUi -> "Custom UI"
                     ClusteringType.CustomRenderer -> "Custom Renderer"
+                    ClusteringType.Decorations -> "Decorations"
                 },
                 onClick = { onClusteringTypeClick(it) }
             )
@@ -338,6 +363,7 @@ private enum class ClusteringType {
     Default,
     CustomUi,
     CustomRenderer,
+    Decorations,
 }
 
 data class MyItem(

maps-compose-utils/src/main/java/com/google/maps/android/compose/clustering/ClusterRenderer.kt

@@ -1,12 +1,14 @@
 package com.google.maps.android.compose.clustering
 
+import androidx.compose.runtime.State
+import androidx.compose.runtime.mutableStateOf
+
 import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.view.View
 import android.view.ViewGroup
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.State
 import androidx.compose.ui.platform.AbstractComposeView
 import androidx.core.graphics.applyCanvas
 import androidx.core.view.doOnAttach
@@ -29,6 +31,10 @@ import kotlinx.coroutines.flow.callbackFlow
 import kotlinx.coroutines.flow.collectLatest
 import kotlinx.coroutines.launch
 
+internal interface ClusterRendererItemState<T : ClusterItem> {
+    val unclusteredItems: State<Set<T>>
+}
+
 /**
  * Implementation of [ClusterRenderer] that renders marker bitmaps from Compose UI content.
  * [clusterContentState] renders clusters, and [clusterItemContentState] renders non-clustered
@@ -50,13 +56,19 @@ internal class ComposeUiClusterRenderer<T : ClusterItem>(
     context,
     map,
     clusterManager
-) {
+), ClusterRendererItemState<T> {
+
+    override val unclusteredItems = mutableStateOf(emptySet<T>())
 
     private val fakeCanvas = Canvas()
     private val keysToViews = mutableMapOf<ViewKey<T>, ViewInfo>()
 
     override fun onClustersChanged(clusters: Set<Cluster<T>>) {
         super.onClustersChanged(clusters)
+        unclusteredItems.value = clusters.filter { !shouldRenderAsCluster(it) }
+            .flatMap { it.items }
+            .toSet()
+
         val keys = clusters.flatMap { it.computeViewKeys() }
 
         with(keysToViews.iterator()) {

maps-compose-utils/src/main/java/com/google/maps/android/compose/clustering/Clustering.kt

@@ -1,5 +1,6 @@
 package com.google.maps.android.compose.clustering
 
+import android.content.Context
 import android.os.Handler
 import android.os.Looper
 import androidx.compose.runtime.Composable
@@ -138,6 +139,7 @@ public fun <T : ClusterItem> Clustering(
     clusterContentZIndex: Float = 0.0f,
     clusterItemContentZIndex: Float = 0.0f,
     clusterRenderer: ClusterRenderer<T>? = null,
+    clusterItemDecoration: @Composable @GoogleMapComposable (T) -> Unit = {},
 ) {
     val clusterManager = rememberClusterManager(
         clusterContent,
@@ -158,6 +160,8 @@ public fun <T : ClusterItem> Clustering(
     Clustering(
         items = items,
         clusterManager = clusterManager,
+        clusterItemDecoration = clusterItemDecoration,
+        renderer = clusterManager.renderer,
     )
 }
 
@@ -193,6 +197,7 @@ public fun <T : ClusterItem> Clustering(
     clusterItemContentAnchor: Offset = Offset(0.5f, 1.0f),
     clusterContentZIndex: Float = 0.0f,
     clusterItemContentZIndex: Float = 0.0f,
+    clusterItemDecoration: @Composable @GoogleMapComposable (T) -> Unit = {},
 ) {
     Clustering(
         items = items,
@@ -206,6 +211,7 @@ public fun <T : ClusterItem> Clustering(
         clusterItemContentAnchor = clusterItemContentAnchor,
         clusterContentZIndex = clusterContentZIndex,
         clusterItemContentZIndex = clusterItemContentZIndex,
+        clusterItemDecoration = clusterItemDecoration,
         onClusterManager = null,
     )
 }
@@ -244,6 +250,7 @@ public fun <T : ClusterItem> Clustering(
     clusterItemContentAnchor: Offset = Offset(0.5f, 1.0f),
     clusterContentZIndex: Float = 0.0f,
     clusterItemContentZIndex: Float = 0.0f,
+    clusterItemDecoration: @Composable @GoogleMapComposable (T) -> Unit = {},
     onClusterManager: ((ClusterManager<T>) -> Unit)? = null,
 ) {
     val clusterManager = rememberClusterManager<T>()
@@ -277,6 +284,8 @@ public fun <T : ClusterItem> Clustering(
         Clustering(
             items = items,
             clusterManager = clusterManager,
+            clusterItemDecoration = clusterItemDecoration,
+            renderer = renderer,
         )
     }
 }
@@ -293,6 +302,24 @@ public fun <T : ClusterItem> Clustering(
 public fun <T : ClusterItem> Clustering(
     items: Collection<T>,
     clusterManager: ClusterManager<T>,
+    clusterItemDecoration: @Composable @GoogleMapComposable (T) -> Unit = {},
+) {
+    Clustering(
+        items = items,
+        clusterManager = clusterManager,
+        clusterItemDecoration = clusterItemDecoration,
+        renderer = null
+    )
+}
+
+@Composable
+@GoogleMapComposable
+@MapsComposeExperimentalApi
+internal fun <T : ClusterItem> Clustering(
+    items: Collection<T>,
+    clusterManager: ClusterManager<T>,
+    clusterItemDecoration: @Composable @GoogleMapComposable (T) -> Unit = {},
+    renderer: ClusterRenderer<T>? = null,
 ) {
     ResetMapListeners(clusterManager)
     InputHandler(
@@ -327,6 +354,13 @@ public fun <T : ClusterItem> Clustering(
             clusterManager.cluster()
         }
     }
+
+    val actualRenderer = renderer ?: clusterManager.renderer
+    val unclusteredItems by (actualRenderer as? ClusterRendererItemState<T>)?.unclusteredItems
+        ?: remember { mutableStateOf(emptySet()) }
+    unclusteredItems.forEach { item ->
+        clusterItemDecoration(item)
+    }
 }
 
 
@@ -341,7 +375,7 @@ public fun <T : ClusterItem> rememberClusterRenderer(
 
     clusterManager ?: return null
     MapEffect(context) { map ->
-        val renderer = DefaultClusterRenderer(context, map, clusterManager)
+        val renderer = ReportingDefaultClusterRenderer(context, map, clusterManager)
         clusterRendererState.value = renderer
     }
 
@@ -457,7 +491,7 @@ private fun <T : ClusterItem> rememberClusterManager(
                                 clusterItemContentZIndexState,
                             )
                         } else {
-                            DefaultClusterRenderer(context, map, clusterManager)
+                            ReportingDefaultClusterRenderer(context, map, clusterManager)
                         }
                     clusterManager.renderer = renderer
                 }
@@ -488,3 +522,19 @@ private fun ResetMapListeners(
         }
     }
 }
+
+private class ReportingDefaultClusterRenderer<T : ClusterItem>(
+    context: Context,
+    map: GoogleMap,
+    clusterManager: ClusterManager<T>
+) : DefaultClusterRenderer<T>(context, map, clusterManager), ClusterRendererItemState<T> {
+
+    override val unclusteredItems = mutableStateOf(emptySet<T>())
+
+    override fun onClustersChanged(clusters: Set<Cluster<T>>) {
+        super.onClustersChanged(clusters)
+        unclusteredItems.value = clusters.filter { !shouldRenderAsCluster(it) }
+            .flatMap { it.items }
+            .toSet()
+    }
+}