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 ?

[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