googlemaps · dkhawk · May 26, 2026 · May 26, 2026 · May 26, 2026 · May 26, 2026
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -35,6 +35,7 @@ plugins {
     alias(libs.plugins.versions)
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
+    id("com.diffplug.spotless") version "6.25.0"
 }
 
 val projectArtifactId by extra { project: Project ->
@@ -57,4 +58,12 @@ tasks.register<Exec>("installAndLaunch") {
     group = "install"
     dependsOn(":maps-app:installDebug")
     commandLine("adb", "shell", "am", "start", "-n", "com.google.maps.android.compose/.MainActivity")
+}
+
+configure<com.diffplug.gradle.spotless.SpotlessExtension> {
+    kotlin {
+        target("snippets/**/*.kt")
+        targetExclude("**/build/**/*.kt")
+        ktfmt("0.46").googleStyle()
+    }
 }
diff --git a/docs/CATALOG.md b/docs/CATALOG.md
@@ -0,0 +1,28 @@
+# 🚀 Jetpack Compose Samples Catalog
+
+This directory contains the Compose samples for the Google Maps SDK for Android. We use a state-driven approach and lean on the `maps-compose` library.
+
+## 📊 Sample Status
+
+| Feature | Status | Source Code | Screenshot | Description |
+| :--- | :---: | :--- | :--- | :--- |
+| **Basic Map** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MapInitSnippets.kt#L58-L60) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L58)) | <img src="images/basic_map.png" alt="Screenshot" width="121"/> | Initializes a basic, interactive Google Map with standard road layers and default controls.<br>**Region Tag:** `maps_android_compose_init_basic` |
+| **Custom Configuration** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MapInitSnippets.kt#L71-L111) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L70)) | <img src="images/custom_config.gif" alt="Screenshot" width="121"/> | Configures custom map properties such as satellite type layers, compass visibility, and hides default zoom controls.<br>**Region Tag:** `maps_android_compose_init_custom` |
+| **Move Camera** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/CameraSnippets.kt#L42-L53) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L82)) | <img src="images/camera_move.gif" alt="Screenshot" width="121"/> | Demonstrates how to move the map camera instantly to a targeted coordinate and zoom level without animations.<br>**Region Tag:** `maps_android_compose_camera_move` |
+| **Animate Camera** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/CameraSnippets.kt#L64-L77) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L94)) | <img src="images/camera_animate.gif" alt="Screenshot" width="121"/> | Demonstrates how to smoothly animate the map camera to a target position over a specified duration in milliseconds.<br>**Region Tag:** `maps_android_compose_camera_animate` |
+| **Camera Restrictions** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/CameraSnippets.kt#L88-L102) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L106)) | <img src="images/camera_bounds.png" alt="Screenshot" width="121"/> | Constrains camera panning and zooming strictly within a geographic LatLngBounds box (e.g., Singapore bounds).<br>**Region Tag:** `maps_android_compose_camera_bounds` |
+| **Basic Marker** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MarkerSnippets.kt#L49-L56) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L119)) | <img src="images/marker_basic.png" alt="Screenshot" width="121"/> | Adds a standard red pin marker to the map centered over Singapore coordinates, complete with title and snippet popups.<br>**Region Tag:** `maps_android_compose_marker_basic` |
+| **Custom Marker Icon** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MarkerSnippets.kt#L67-L81) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L131)) | <img src="images/marker_custom_icon.png" alt="Screenshot" width="121"/> | Customizes the standard marker icon to a default azure color, demonstrating how to pass custom drawable/descriptor objects.<br>**Region Tag:** `maps_android_compose_marker_custom_icon` |
+| **Marker Composable** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MarkerSnippets.kt#L93-L117) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L143)) | <img src="images/marker_composable.png" alt="Screenshot" width="121"/> | Renders arbitrary Jetpack Compose layout structures directly on the map as custom interactive markers (e.g., rounded red badges).<br>**Region Tag:** `maps_android_compose_marker_composable` |
+| **Custom Info Window** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/MarkerSnippets.kt#L128-L158) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L155)) | <img src="images/marker_info_window.png" alt="Screenshot" width="121"/> | Replaces the standard marker balloon popup with an arbitrary styled Compose layout (e.g., yellow rectangular banner).<br>**Region Tag:** `maps_android_compose_marker_info_window` |
+| **Polylines** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/ShapeSnippets.kt#L39-L47) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L166)) | <img src="images/polyline.png" alt="Screenshot" width="121"/> | Draws a styled solid blue vector line connecting three coordinate vertices on the map.<br>**Region Tag:** `maps_android_compose_polyline` |
+| **Polygons** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/ShapeSnippets.kt#L58-L71) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L178)) | <img src="images/polygon.png" alt="Screenshot" width="121"/> | Draws a closed, filled red triangular area with a solid red border.<br>**Region Tag:** `maps_android_compose_polygon` |
+| **Circle Overlay** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/ShapeSnippets.kt#L82-L94) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L190)) | <img src="images/circle.png" alt="Screenshot" width="121"/> | Draws a translucent green geographic circle centered at Singapore coordinates.<br>**Region Tag:** `maps_android_compose_circle` |
+| **Marker Clustering** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/ClusteringSnippets.kt#L61-L88) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L202)) | <img src="images/clustering.png" alt="Screenshot" width="121"/> | Groups adjacent markers dynamically inside cluster badges to avoid map clutter.<br>**Region Tag:** `maps_android_compose_clustering` |
+| **GeoJSON Layer** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/DataLayerSnippets.kt#L42-L72) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L214)) | <img src="images/geojson_layer.png" alt="Screenshot" width="121"/> | Parses and overlays a GeoJSON data layer dynamically in Compose using `MapEffect` to obtain the underlying GoogleMap instance safely.<br>**Region Tag:** `maps_android_compose_geojson_layer` |
+| **KML Layer** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/DataLayerSnippets.kt#L84-L117) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L225)) | <img src="images/kml_layer.png" alt="Screenshot" width="121"/> | Parses and overlays a KML data stream dynamically in Compose using `MapEffect`.<br>**Region Tag:** `maps_android_compose_kml_layer` |
+| **Ground Overlay** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/AdvancedSnippets.kt#L59-L97) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L237)) | <img src="images/ground_overlay.png" alt="Screenshot" width="121"/> | Displays a static flat image stretched flatly over geographic coordinate bounds.<br>**Region Tag:** `maps_android_compose_ground_overlay` |
+| **Tile Overlay** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/AdvancedSnippets.kt#L108-L144) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L249)) | <img src="images/tile_overlay.png" alt="Screenshot" width="121"/> | Overlays custom dynamic styled map tile layers on top of the default viewport.<br>**Region Tag:** `maps_android_compose_tile_overlay` |
+| **WMS Tile Overlay** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/AdvancedSnippets.kt#L155-L181) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L261)) | <img src="images/wms_tile_overlay.png" alt="Screenshot" width="121"/> | Displays dynamically loaded raster map tile layers fetched from a Web Map Service (WMS) using EPSG:3857 projection.<br>**Region Tag:** `maps_android_compose_wms_tile_overlay` |
+| **Compose Bitmap Descriptor** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/AdvancedSnippets.kt#L193-L228) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L273)) | <img src="images/compose_bitmap_descriptor.png" alt="Screenshot" width="121"/> | Renders custom graphics dynamically to standard marker descriptors using standard Canvas drawing.<br>**Region Tag:** `maps_android_compose_remember_bitmap_descriptor` |
+| **Scale Bar Widget** | ✅ Done | [Source Code](../snippets/src/main/java/com/google/maps/android/compose/snippets/AdvancedSnippets.kt#L240-L252) ([Activity](../snippets/src/main/java/com/google/maps/android/compose/snippets/SnippetActivities.kt#L289)) | <img src="images/scale_bar.png" alt="Screenshot" width="121"/> | Displays an on-screen dynamic map distance scale bar overlay widget that reacts to pinch-to-zoom events.<br>**Region Tag:** `maps_android_compose_scale_bar` |
diff --git a/docs/images/basic_map.png b/docs/images/basic_map.png
diff --git a/docs/images/camera_animate.gif b/docs/images/camera_animate.gif
diff --git a/docs/images/camera_animate.mp4 b/docs/images/camera_animate.mp4
diff --git a/docs/images/camera_bounds.png b/docs/images/camera_bounds.png
diff --git a/docs/images/camera_move.gif b/docs/images/camera_move.gif
diff --git a/docs/images/camera_move.mp4 b/docs/images/camera_move.mp4
diff --git a/docs/images/circle.png b/docs/images/circle.png
diff --git a/docs/images/clustering.png b/docs/images/clustering.png
diff --git a/docs/images/compose_bitmap_descriptor.png b/docs/images/compose_bitmap_descriptor.png
diff --git a/docs/images/custom_config.gif b/docs/images/custom_config.gif
diff --git a/docs/images/geojson_layer.png b/docs/images/geojson_layer.png
diff --git a/docs/images/ground_overlay.png b/docs/images/ground_overlay.png
diff --git a/docs/images/kml_layer.png b/docs/images/kml_layer.png
diff --git a/docs/images/marker_basic.png b/docs/images/marker_basic.png
diff --git a/docs/images/marker_composable.png b/docs/images/marker_composable.png
diff --git a/docs/images/marker_custom_icon.png b/docs/images/marker_custom_icon.png
diff --git a/docs/images/marker_info_window.png b/docs/images/marker_info_window.png
diff --git a/docs/images/polygon.png b/docs/images/polygon.png
diff --git a/docs/images/polyline.png b/docs/images/polyline.png
diff --git a/docs/images/scale_bar.png b/docs/images/scale_bar.png
diff --git a/docs/images/tile_overlay.png b/docs/images/tile_overlay.png
diff --git a/docs/images/wms_tile_overlay.png b/docs/images/wms_tile_overlay.png
diff --git a/docs/screenshot_validation.md b/docs/screenshot_validation.md
@@ -0,0 +1,28 @@
+# 📊 Visual Screenshot Validation Oracle
+
+This document lists the strict visual validation criteria (verification prompts) for each snippet screenshot and records the inspection results on the connected Pixel 6 device.
+
+## 📑 Visual Verification Matrix
+
+| # | Snippet Screenshot | Filename | Visual Validation Oracle Criteria | Inspection Verdict | Details & Visual Analysis |
+|---|---|---|---|:---:|---|
+| 1 | **Basic Map** | `basic_map.png` | Clean standard Google Map viewport showing streets, terrain, and water. No custom markers, shapes, or overlays. | ✅ **PASS** | Shows standard map tiles rendering Europe and Africa correctly under SystemUI Demo Mode (12:00 clock). |
+| 2 | **Custom Configuration** | `custom_config.png` | Map rendered as textured satellite imagery (green/brown terrain). Default zoom controls (+/-) must be absent. | ✅ **PASS** | Shows high-fidelity satellite textures. Default +/- zoom controls are completely absent from screen. |
+| 3 | **Move Camera** | `camera_move.png` | Map view centered directly over Singapore island. | ✅ **PASS** | Map view successfully centered over Singapore peninsula. |
+| 4 | **Animate Camera** | `camera_animate.png` | Map view smoothly zoomed in closer over Singapore sub-region coordinates. | ✅ **PASS** | Displays zoomed-in focus over Singapore coordinates correctly. |
+| 5 | **Restrict Camera Bounds** | `camera_bounds.png` | View constrained and centered strictly to the Singapore bounding box. | ✅ **PASS** | Map panning locked to the Singapore coordinate bounds. |
+| 6 | **Basic Marker** | `marker_basic.png` | Standard red map pin positioned over Singapore. | ✅ **PASS** | Standard red pin marker rendered accurately in the center. |
+| 7 | **Custom Marker Icon** | `marker_custom_icon.png` | Azure-colored (light blue) standard map pin positioned over Singapore. | ✅ **PASS** | Standard pin color altered to azure blue flawlessly. |
+| 8 | **Marker Composable** | `marker_composable.png` | Styled rectangular red badge with rounded corners containing the text "Compose UI" in white. | ✅ **PASS** | Styled red Compose rectangular badge rendered natively on-map. |
+| 9 | **Custom Info Window** | `marker_info_window.png` | A solid blue circle marker with a yellow rectangular balloon popup (InfoWindow) containing "Marker Info Window" in black. | ✅ **PASS** | Custom yellow balloon popup info frame positioned directly above a blue circle marker. |
+| 10 | **Polyline** | `polyline.png` | A solid blue vector line connecting three coordinate vertices. | ✅ **PASS** | Solid blue polyline path connecting the three Singapore points. |
+| 11 | **Polygon** | `polygon.png` | A solid filled red triangular polygon area with a solid red border. | ✅ **PASS** | Red translucent filled triangle area bounded by a solid red outline. |
+| 12 | **Circle** | `circle.png` | Translucent green filled circular area with a solid green border centered over Singapore. | ✅ **PASS** | 2,000m radius translucent green circular bounds overlaying Singapore. |
+| 13 | **Marker Clustering** | `clustering.png` | Multiple markers or circular cluster badges (e.g., blue circle with a number "4" indicating clustered pins). | ✅ **PASS** | Markers grouped dynamically under a cluster badge overlay showing the exact count. |
+| 14 | **GeoJSON Layer** | `geojson_layer.png` | A GeoJSON point (standard red marker) rendered dynamically from parsed GeoJSON coordinates. | ✅ **PASS** | GeoJSON dataset parsed and loaded natively. |
+| 15 | **KML Layer** | `kml_layer.png` | A KML placemark (standard red marker) rendered dynamically from parsed KML input stream. | ✅ **PASS** | KML vector data parsed and displayed dynamically on map. |
+| 16 | **Ground Overlay** | `ground_overlay.png` | A custom flat blue square image with a yellow cross stretched over Singapore bounds. | ✅ **PASS** | Custom blue/yellow GroundOverlay flat image stretched correctly over Singapore coordinates with zero crashes. |
+| 17 | **Tile Overlay** | `tile_overlay.png` | Custom dynamic styled tile raster overlays (translucent pink grid pattern). | ✅ **PASS** | Custom dynamic translucent pink tile overlay with solid gray borders rendering cleanly over Singapore. |
+| 18 | **WMS Tile Overlay** | `wms_tile_overlay.png` | Satellite Bluemarble tiles fetched from WMS server overlaying the Denver/Boulder, Colorado area. | ✅ **PASS** | EPSG:3857 projected WMS satellite tiles fetched and rendered successfully over Boulder, Colorado at zoom 10. |
+| 19 | **Compose Bitmap Descriptor** | `compose_bitmap_descriptor.png` | A standard map pin marker displaying a custom-rendered Compose magenta circle containing "Icon" in white. | ✅ **PASS** | Custom Canvas-drawn magenta/white pin generated and displayed with zero runtime crashes. |
+| 20 | **Scale Bar Widget** | `scale_bar.png` | An overlaid distance scale bar widget anchored at the top-start of the map showing numeric ratios (e.g. "2 mi"). | ✅ **PASS** | Dynamic scale bar widget anchored at the top-start displaying precise zoom scale ratios. |
diff --git a/settings.gradle.kts b/settings.gradle.kts
@@ -42,4 +42,5 @@ include(":maps-app")
 include(":maps-compose")
 include(":maps-compose-widgets")
 include(":maps-compose-utils")
-include(":docs")
+include(":docs")
+include(":snippets")