feat!: migrate android-maps-ktx into android-maps-utils (v6.0.0)

[dkhawk]

Summary

Migrates all Kotlin extensions from android-maps-ktx (maps-ktx and maps-utils-ktx) directly into android-maps-utils, establishing v6.0.0 as the consolidated, single-source release for both Java utilities and Kotlin Coroutine/Flow extensions.

Key Changes

1. Consolidated Kotlin Extensions:
   • Reactive coroutine suspensions (awaitMap(), awaitMapsSdkInitialized(), awaitAnimateCamera()).
   • Reactive Flow event streams (mapClickEvents(), cameraMoveEvents(), markerClickEvents()).
   • DSL option builders (addMarker { ... }, addPolyline { ... }, addPolygon { ... }).
2. Canonical & Compatibility Packages:
   • All extensions and builders live under canonical com.google.maps.android.* packages.
   • Preserves com.google.maps.android.ktx.* with @Deprecated(level = DeprecationLevel.WARNING) forwarding wrappers and typealiases for seamless backward compatibility.
3. Release Please Configuration:
   • Configured release-please-config.json and .release-please-manifest.json for final v6.0.0 stable release.
   • Updated documentation (README.md, MIGRATION.md, llm-integration-prompt.md, .gemini/skills/android-maps-utils/SKILL.md).
4. Rebase & Test Validation:
   • Rebased onto latest main (e8ef093c, Kover migration).
   • 100% unit tests pass across all modules (:library, :clustering, :data, :heatmaps, :ui, :demo).

[googlemaps-bot]

Code Coverage

Overall Project	52.56% -1.78%	🍏
Files changed	77.99%	🍏

Module	Coverage
Kover Gradle Plugin XML report for :library	88.08% -7.11%	🍏
Kover Gradle Plugin XML report for :heatmaps	85.02% -3.61%	❌
Kover Gradle Plugin XML report for :data	48.19% -1.03%	❌
Kover Gradle Plugin XML report for :clustering	32.93%	🍏

Files

Module	File	Coverage
Kover Gradle Plugin XML report for :library	SupportStreetViewPanoramaFragment.kt	100%	🍏
	MapView.kt	100%	🍏
	MapFragment.kt	100%	🍏
	SupportMapFragment.kt	100%	🍏
	StreetViewPanoramaFragment.kt	100%	🍏
	Polyline.kt	100%	🍏
	LatLng.kt	100%	🍏
	SupportStreetViewPanoramaFragment.kt	100%	🍏
	MapView.kt	100%	🍏
	SupportMapFragment.kt	100%	🍏
	Polyline.kt	100%	🍏
	LatLng.kt	100%	🍏
	StreetViewPanoramaView.kt	100%	🍏
	MapFragment.kt	100%	🍏
	MapsInitializer.kt	100%	🍏
	StreetViewPanoramaFragment.kt	100%	🍏
	AttributionIdInitializer.kt	100%	🍏
	PolylineOptions.kt	100%	🍏
	MarkerOptions.kt	100%	🍏
	PolygonOptions.kt	100%	🍏
	CircleOptions.kt	100%	🍏
	StreetViewPanoramaOrientation.kt	100%	🍏
	CameraPosition.kt	100%	🍏
	GroundOverlayOptions.kt	100%	🍏
	TileOverlayOptions.kt	100%	🍏
	StreetViewPanoramaCamera.kt	100%	🍏
	PolylineOptions.kt	100%	🍏
	MarkerOptions.kt	100%	🍏
	PolygonOptions.kt	100%	🍏
	CircleOptions.kt	100%	🍏
	StreetViewPanoramaOrientation.kt	100%	🍏
	CameraPosition.kt	100%	🍏
	GroundOverlayOptions.kt	100%	🍏
	TileOverlayOptions.kt	100%	🍏
	StreetViewPanoramaCamera.kt	100%	🍏
	MarkerManagerFlows.kt	91.2% -8.8%	🍏
	LocationManager.kt	86.71% -13.29%	🍏
	FusedLocationProvider.kt	84.62% -15.38%	🍏
	GoogleMap.kt	83.75% -16.25%	🍏
	Polygon.kt	80.95% -19.05%	🍏
	PolylineManagerFlows.kt	78% -22%	🍏
	GroundOverlayManagerFlows.kt	78% -22%	🍏
	PolygonManagerFlows.kt	78% -22%	🍏
	CircleManagerFlows.kt	78% -22%	🍏
	Polygon.kt	70.73% -29.27%	🍏
	MapsInitializer.kt	66.67% -33.33%	🍏
	MarkerManager.kt	60% -40%	🍏
	GoogleMap.kt	50.63% -49.37%	❌
	LocationManager.kt	50% -50%	❌
	FusedLocationProvider.kt	38.46% -61.54%	❌
	PolygonManager.kt	33.33% -66.67%	❌
	CircleManager.kt	33.33% -66.67%	❌
	GroundOverlayManager.kt	33.33% -66.67%	❌
	PolylineManager.kt	33.33% -66.67%	❌
	StreetViewPanoramaView.kt	27.27% -72.73%	❌
Kover Gradle Plugin XML report for :heatmaps	Heatmap.kt	15.15% -84.85%	❌
	Heatmap.kt	13.73% -86.27%	❌
Kover Gradle Plugin XML report for :data	GeoJson.kt	0%	❌
	GeoJson.kt	0%	❌
	Kml.kt	0%	❌
	Kml.kt	0%	❌
Kover Gradle Plugin XML report for :clustering	ClusterManagerFlows.kt	100%	🍏
	ClusterManager.kt	100%	🍏
	Point.kt	100%	🍏
	PointExtensions.kt	100%	🍏

[LoyalAbbas]

is there any purpose for adding this ?

[kikoso]

Merge error, probably!

[LoyalAbbas]

Do we really need this "/usr/local/google/home/dkhawk/Android/Sdk" path ?

[LoyalAbbas]

When calling awaitAnimateCamera(), we now need to pass 0 if we don't want to set a duration. Is there a reason we didn't make this parameter optional?

[LoyalAbbas]

When calling awaitAnimateCamera(), we now need to pass 0 if we don't want to set a duration. Is there a reason we didn't make this parameter optional ?

[LoyalAbbas]

If status != ConnectionResult.SUCCESS, the continuation resumes with an exception immediately. If Play Services later invokes the OnMapsSdkInitializedCallback asynchronously (or if the coroutine was cancelled while waiting), calling continuation.resume(renderer) without checking if (continuation.isActive), it might be throw IllegalStateException

What did you think on this ??

Fix: Guard resumption with if (continuation.isActive) continuation.resume(...), and add continuation.invokeOnCancellation { setOnMapLoadedCallback(null) } to awaitMapLoad()

[LoyalAbbas]

Unlike FusedLocationProvider.kt(which defaults to looper: Looper = Looper.getMainLooper()), LocationManager.coarseLocationEvents and fineLocationEvents call the 4-argument requestLocationUpdates(provider, minTimeMs, minDistanceM, listener) without a Looper. If collected on Dispatchers.IO or Dispatchers.Default, LocationManager calls Looper.myLooper() and crashes immediately with RuntimeException: Can't create handler inside thread that has not called Looper.prepare().

Fix: Add looper: Looper = Looper.getMainLooper() parameter to coarseLocationEvents and fineLocationEvents and pass it to requestLocationUpdates(provider, minTimeMs, minDistanceM, listener, looper).

[LoyalAbbas]

Unlike FusedLocationProvider.kt(which defaults to looper: Looper = Looper.getMainLooper()), LocationManager.coarseLocationEvents and fineLocationEvents call the 4-argument requestLocationUpdates(provider, minTimeMs, minDistanceM, listener) without a Looper. If collected on Dispatchers.IO or Dispatchers.Default, LocationManager calls Looper.myLooper() and crashes immediately with RuntimeException: Can't create handler inside thread that has not called Looper.prepare().

Fix: Add looper: Looper = Looper.getMainLooper() parameter to coarseLocationEvents and fineLocationEvents and pass it to requestLocationUpdates(provider, minTimeMs, minDistanceM, listener, looper).

[LoyalAbbas]

Currently all test cases are false positive.

If we pass assertThat(event).isEqualTo(LatLng(9999.0, 9999.0)) or even if onMapClick(target) is never called at all, the test still pass, because the assertion line is dead code that gets cancelled before execution.

Solution :

Use async { ... } and deferred.await()
Using async instead of launch is cleaner, shorter, and eliminates manual job.cancel() calls altogether:

@test
public fun testMapClickEvents(): Unit = runTest {
val target = LatLng(10.0, 20.0)
val deferred = async {
googleMap.mapClickEvents().first()
}
advanceUntilIdle()
verify(googleMap).setOnMapClickListener(mapClickListener.capture())
mapClickListener.value.onMapClick(target)
assertThat(deferred.await()).isEqualTo(target)
}

Note : We need to do similar kind of handling for all the test cases

[LoyalAbbas]

Currently all test cases are false positive.

If we pass any cluster value still test will pass, because the assertion line is dead code that gets cancelled before execution.

Solution :

Use async { ... } and deferred.await()
Using async instead of launch is cleaner, shorter, and eliminates manual job.cancel() calls altogether:

@test
public fun testClusterInfoWindowClickEvents(): Unit = runTest {
val deferred = async {
clusterManager.clusterInfoWindowClickEvents().first()
}
advanceUntilIdle()
verify(clusterManager).setOnClusterInfoWindowClickListener(clusterInfoWindowClickListener.capture())
clusterInfoWindowClickListener.value.onClusterInfoWindowClick(cluster)
assertThat(deferred.await()).isEqualTo(cluster)
}

Note : We need to do similar kind of handling for all the test cases

[LoyalAbbas]

test case is false positive.

If we pass any Marker value here, still this test will pass, because the assertion line is dead code that gets cancelled before execution.

Solution :

Use async { ... } and deferred.await()
Using async instead of launch is cleaner, shorter, and eliminates manual job.cancel() calls altogether:

@Test
public fun testMarkerCollectionClickEvents(): Unit = runTest {
    val deferred = async {
        markerCollection.clickEvents().first()
    }
    advanceUntilIdle()
    // Trigger the event via our tracked active listener slot!
    assertThat(activeMarkerClickListener).isNotNull()
    activeMarkerClickListener?.onMarkerClick(marker)

    assertThat(deferred.await()).isEqualTo(marker)
}

Note : We need to do similar kind of handling in other test cases also

[LoyalAbbas]

any specific reason, why we use this instead of "org.mockito.kotlin:mockito-kotlin" lib ?

[LoyalAbbas]

duplicate call

[kikoso]

Second pass, this time anchored to the specific files. Most of it is packaging and release config rather than the Kotlin itself, plus one follow up on the inline thread.

[kikoso]

These six functions are public and return Flow<...>, but clustering/build.gradle.kts still has implementation(libs.kotlinx.coroutines.android). The api(coroutines) you added to :library doesn't help either, since clustering depends on it with implementation.

So the published POM for android-maps-utils-clustering puts coroutines at runtime scope, and an app calling clusterClickEvents() gets "cannot access class kotlinx.coroutines.flow.Flow". Our unit tests won't catch it because they compile inside the module.

Can you move it to api(libs.kotlinx.coroutines.core) and check the other modules while you're there?

[kikoso]

Only coroutines-core is actually in our API surface. coroutines-android is just the Dispatchers.Main artifact, so implementation is enough for it.

Separately on line 66: api(play-services-location) means everyone pulling maps-utils now gets play-services-location, including people who only wanted :data or :heatmaps. AGENTS.md also asks for an issue before adding deps to library modules. See my note on the demo file about where this package should live.

One more while this file is open: explicitApi() isn't enabled anywhere and we have no binary compatibility validator, yet we're adding roughly 200 public symbols in a major. All the new code already writes public explicitly so flipping explicitApi() on is nearly free, and an .api dump in version control would back up the compatibility promise the shim layer is making. Happy for that to be a follow up if you'd rather not grow this PR.

[kikoso]

This registers the attribution initializer a second time, so both it and the canonical one call addInternalUsageAttributionId with the same value on every app start.

The shim class is also internal, so nobody outside the module could ever have referenced it and the @Deprecated on it does nothing. I'd delete both the shim class and this manifest entry.

[kikoso]

AGENTS.md says not to hand edit this or CHANGELOG.md. The title is already feat!: so release-please lands on 6.0.0 by itself. Can we revert both and let it do its job?

Also worth checking: the description says final 6.0.0, but release-please-config.json is untouched and still has "prerelease": true with "prerelease-type": "rc". As it stands the next run gives us 6.0.0-rc05, not 6.0.0.

[kikoso]

gradle.properties isn't in the extra-files list in release-please-config.json, so this goes stale on the next release. Do we need it at all? allprojects { version = ... } in the root build file is already marker managed.

(Minor: trailing blank lines at the end of the file too.)

[kikoso]

Following up on the inline thread: most of them are gone, but three are still inline with no lambda parameter. This one, MapFragment.awaitMap() and SupportMapFragment.awaitMap(). Those files don't carry @file:Suppress("NOTHING_TO_INLINE") either, so they should be warning right now. Can you catch those too?

[kikoso]

The MapView lifecycle is driven by hand here (onCreate / onStart / onResume) and onPause, onStop, onDestroy and onLowMemory are never called, so the MapView and its native resources leak. This wants a DisposableEffect tied to the lifecycle.

Related on line 100: lifecycleScope.launch { repeatOnLifecycle { ... } } is nested inside the LaunchedEffect, so that inner coroutine outlives the composable leaving composition. Moving the repeatOnLifecycle into the LaunchedEffect body fixes it.

This is the sample the README points people at, so I'd rather it show the right pattern. (Also trailing whitespace on line 81.)

[kikoso]

This turns "user switched GPS off" into cancellation, which propagates into the collector's scope instead of being something they can catch and handle. Was that deliberate? A dedicated exception, or just completing the flow, would be easier to work with. Same on line 113.

Broader question on this whole package: should location live in :library at all, given it's what drags play-services-location onto every consumer? A separate :ktx module, or at least a :location one, might be the better home. This is the piece I'd most like settled before merge since it's baked into the 6.0.0 surface.

[kikoso]

Kotlin 2.4.10 to 2.4.20, Gradle wrapper 9.6.1 to 9.7.1, Robolectric 4.16.1 to 4.17, Compose BOM, Navigation SDK, lint, plus a codeql-action SHA bump are all riding along in an 8.5k line migration.

Can those move to a separate build(deps): PR? They'll fight with Renovate, and they make this one harder to revert if we ever need to.

[kikoso]

nit: stray blank line. Same kind of thing in MIGRATION.md line 22 and inside the code fence in .gemini/skills/android-maps-utils/SKILL.md.