feat(collections): introduce unified OverlayManager and polymorphic MapOverlay system

[dkhawk]

Summary

This draft PR introduces an alternate, polymorphic map object collection architecture under com.google.maps.android.collections.overlay designed for idiomatic Kotlin usage, heterogeneous layer grouping, and future Kotlin Multiplatform (KMP) readiness while maintaining 100% coexistence and backward compatibility with the existing collection managers.

1. Polymorphic Abstraction Hierarchy (MapOverlay<T>):

   • Common interface representing any visual map feature with uniform properties (isVisible, zIndex, tag, remove()).
   • Concrete, decoupled wrappers: MarkerOverlay, CircleOverlay, PolygonOverlay, PolylineOverlay, GroundOverlayOverlay.
   • Direct per-overlay lambda event listeners (marker.onClick { ... }, marker.onDrag { ... }, marker.onInfoWindowClick { ... }).

2. Heterogeneous OverlayCollection:

   • Single logical feature collections holding mixed geometry types (markers, polylines, polygons, circles, ground overlays).
   • Uniform overloaded add(options) and operator += syntax.
   • Batch operations (showAll(), hideAll(), clear(), isVisible = false).
   • Direct typed querying (collection.markers, collection.polylines, collection.polygons, etc.).

3. Coexistence with Legacy Managers:

   • OverlayManager can run standalone or share listeners with existing MarkerManager, CircleManager, PolygonManager, PolylineManager, and GroundOverlayManager instances on the same map without listener collisions.

4. Unit Test Suite with Google Truth:

   • Full test suites with Google Truth and literate programming KDoc (OverlayManagerTest, OverlayCollectionTest, MapOverlayTest).

Verification

• ./gradlew test lint assemble jacocoTestDebugUnitTestReport — all 265 test suites passed.
• Code coverage across new overlay classes is between 80% and 98% (overall :library at 88.24%).

Reviewer

cc @LoyalAbbas

[kikoso]

A minSdk increase would be required to use Map.putIfAbsent().

Do we want to update? It will be a breaking change, which is also fine IMO