feat: Update to play-services-maps3d-0.1.0 (#16)

* test: Add UI tests and update build configurations

This commit introduces Espresso UI tests for `HelloMapActivity` in both the Java and Kotlin sample apps to verify that the map view is displayed.

Additionally, this commit includes several build and dependency updates:
- Upgrades Gradle, the Android Gradle Plugin, Kotlin, and other AndroidX libraries.
- Centralizes `minSdk` and `targetSdk` in the version catalog (`libs.versions.toml`).
- Moves the Maps 3D SDK dependency to the `common` module and exposes it to the app modules using the `api` configuration.

* test: Add instrumented test for CameraControlsActivity

This commit introduces an instrumented test for `CameraControlsActivity`.

The test verifies two main functionalities:
- The `Map3DView` is displayed correctly.
- The "Fly to" button animates the camera to the expected location.

The `androidx.test.uiautomator` dependency was added to support the test implementation.

* test: (WIP) Add test for fly around camera animation

This commit introduces a new instrumentation test, `testFlyAround`, to `CameraControlsActivityTest`.

The test verifies the functionality of the "Fly Around" button by clicking it and then using `OnMapSteadyListener` to assert that the animation completes and the map returns to a steady state.

* feat: Update to Maps3D SDK 0.0.3 and dependencies

This commit updates the project to use version 0.0.3 of the Maps3D SDK, which is now included as a local AAR file. It also updates various dependencies, including the Android Gradle Plugin, Kotlin, Compose BOM, and the Gradle wrapper.

Key API changes from the SDK update have been applied:
*   `PolygonOptions.outerCoordinates` is now `path`.
*   `PolygonOptions.innerCoordinates` is now `innerPaths`.
*   `PolylineOptions.coordinates` is now `path`.

Additionally, the build configuration is streamlined by centralizing `compileSdk`, `minSdk`, and `targetSdk` versions in the `libs.versions.toml` files.

* test: Add Google Truth and refactor assertions

This commit adds the Google Truth assertion library as a testing dependency for both the Java and Kotlin sample apps.

Existing instrumentation tests have been refactored to use Truth's fluent `assertThat` API instead of JUnit assertions, improving the readability and expressiveness of the test code.

* chore: Remove local Maps 3D SDK AAR dependency

* feat: Add click listeners for map elements

This commit introduces click handling for various map elements and adds a new sample to demonstrate place clicks.

- **Map Interactions Sample:** A new `MapInteractionsActivity` has been added to show how to use `setMap3DClickListener` to handle clicks on the map and on places.
- **Marker Clicks:** The `MarkersActivity` now sets a `clickListener` on each marker, displaying a `Toast` with the marker's label when clicked.
- **Polyline Clicks:** The `PolylinesActivity` now sets a `clickListener` on the trail polyline.
- **Polygon Clicks:** The `PolygonsActivity` now sets `clickListener`s on the museum and zoo polygons.

* refactor: Use local AAR and improve sample list implementation

This commit introduces several improvements to the sample applications:

- The build configuration is updated across all modules to depend on a local `play-services-maps3d` AAR file instead of a remote dependency.
- The Kotlin `MainActivity` is refactored to use a `Sample` data class for the list of demos, improving type safety and code readability.
- The XML themes for the Java and Kotlin ApiDemos apps are updated to consistently use `Theme.Material3.DayNight.NoActionBar`.

* refactor: Improve documentation and code quality in samples

This commit enhances the `HelloMapActivity` and `MarkersActivity` samples with improved documentation and modern Android development patterns.

Key changes include:
- Expanded KDoc comments in `HelloMapActivity` and `MarkersActivity` to provide more detailed explanations of the code and concepts.
- Refactored `MarkersActivity` to use `lifecycleScope` for managing coroutines and to extract marker creation and click listener setup into separate functions.
- Updated `SampleBaseActivity` to extend `AppCompatActivity` for better support and consistency.
- Moved the `TAG` definition in `HelloMapActivity` to a `companion object` to follow common Kotlin idioms.

* refactor(ModelsActivity): Improve structure and use lifecycleScope

This commit refactors `ModelsActivity` for better code organization, readability, and lifecycle safety.

Key changes include:
- Replaced `CoroutineScope(Dispatchers.Main)` with `lifecycleScope` to tie coroutines to the activity's lifecycle, preventing potential leaks.
- Extracted logic into smaller, well-documented helper functions like `setupUI`, `addPlaneModel`, and `runAnimationSequence`.
- Used `kotlin.time.Duration` for more readable and type-safe time values in animations and flows.
- Added extensive KDoc comments to the class and methods to improve documentation.

* refactor(PolygonsActivity): Improve structure and add documentation

This commit refactors the `PolygonsActivity` to improve code organization, clarity, and lifecycle management.

Key changes include:
- Extracting the logic for adding polygons and setting up click listeners into dedicated functions (`addMuseumPolygons`, `addZooPolygon`, `setupPolygonClickListener`).
- Switching from a manual `CoroutineScope` to `lifecycleScope` for safer coroutine handling that is tied to the activity's lifecycle.
- Adding extensive KDoc comments to the class, methods, and properties to better document the sample's functionality.
- Using `by lazy` to defer the initialization of polygon coordinate data until first use.

* refactor: Improve code quality of PolylinesActivity

This commit refactors the `PolylinesActivity` to improve code quality, readability, and documentation.

Key changes include:
- Expanded the KDoc for the activity to better explain the sample's purpose and implementation details.
- Extracted logic for adding polylines and setting up click listeners into separate, focused functions.
- Switched from a manually created `CoroutineScope` to the lifecycle-aware `lifecycleScope`.
- Used `by lazy` for deferred initialization of polyline options and trail data, improving performance.
- Simplified the parsing of trail location data using more idiomatic Kotlin.

* build: Loads play-services-maps3d:0.0.3 as an api in the common module

Loading the files locally left as comments for reference

* chore: Add missing license header to HelloMapActivityTest

* feat(models): Add click listener to 3D model

Adds a click listener to the airplane model in the `ModelsActivity` sample. A toast message is shown when the model is clicked to demonstrate the feature.

* chore: Upgrade Gradle and project dependencies

This commit updates the Gradle version and refreshes various project dependencies across the sample applications.

Key changes:
- **Gradle Upgrade:** Upgraded the Gradle wrapper from version 8.11.1 to 9.1.0. This includes updating the `gradlew` and `gradlew.bat` scripts and the wrapper JAR to the versions generated by Gradle 9.1.
- **Dependency Updates:** Updated several key libraries to their latest versions, including:
    - Android Gradle Plugin to 8.13.0
    - Kotlin to 2.2.20
    - Compose BOM to 2025.09.00
    - Hilt to 2.57.1
    - Various AndroidX, KSP, and testing libraries.
- **Build Script Refactor:** In the `ApiDemos` project, the `play-services-maps3d` dependency is now referenced through the version catalog for consistency.

* refactor: Clean up build scripts and Java sample app

This commit introduces several cleanups and refactorings across the API Demos samples, primarily focusing on the Gradle build scripts and the Java sample application.

- **Gradle Build Scripts:**
    - The `sarifOutput` path for lint reports is now consistently configured using the modern `layout.buildDirectory` API across all modules.
    - In the `java-app`, SDK versions (`compileSdk`, `minSdk`, `targetSdk`) are now sourced from the version catalog (`libs.versions`) instead of being hardcoded.

- **Java Sample App (`java-app`):**
    - Removed Kotlin and Jetpack Compose plugins and dependencies, making it a pure Java-based sample.
    - Updated Javadoc comments to follow standard Java conventions, removing Kotlin-style syntax.

- **Kotlin Code:**
    - Corrected a `@StringRes` annotation target in `Units.kt` for better precision.
    - Removed an unused import in `MainActivity.kt`.
    - Enabled `buildConfig` in the `kotlin-app` module.

* feat: Implement edge-to-edge display for Java sample app

This commit updates the Java API Demos app to support edge-to-edge display, allowing the app's UI to draw behind the system status and navigation bars for a more immersive experience.

Key changes:

-   **Theme Updates (`themes.xml`):**
    -   The status and navigation bars are set to transparent.
    -   The theme is configured to allow drawing behind system bars (`windowDrawsSystemBarBackgrounds`) and to render in the display cutout area.

-   **Activity Changes (`MainActivity` & `SampleBaseActivity`):**
    -   `WindowCompat.setDecorFitsSystemWindows(false)` is called to enable edge-to-edge mode.
    -   An `OnApplyWindowInsetsListener` is used to get the system bar insets and apply them as padding to the root view. This ensures that interactive UI elements are not obscured by the system bars.

-   **Refinement:** The inset handling logic in `SampleBaseActivity` has been simplified to use `WindowInsetsCompat.Type.systemBars()` for a cleaner implementation.

* build: Update Maps 3D SDK to version 0.0.3

This commit updates the project's dependencies to use version 0.0.3 of the Maps 3D SDK.

Key changes:
- The `play-services-maps3d` dependency is updated from version 0.0.2 to 0.0.3 in `libs.versions.toml`.
- The SDK is now included as a local AAR file (`play-services-maps3d-0.0.3.aar`) in the `common`, `java-app`, and `kotlin-app` modules.
- A new dependency on `play-services-base` has been added to all modules, as required by the updated SDK.
- The version catalog (`libs.versions.toml`) has been updated to include `play-services-base`, `truth`, and `uiautomator`.

* feat(java-app): Update to latest Maps3D SDK

- Implemented click listeners for markers, polygons, polylines, and models to demonstrate new interactive features.
- Updated Polygon and Polyline options to use the new `path` and `innerPaths` properties, aligning with the latest API.
- Refactored `MarkersActivity` to use a helper method for marker creation, improving code clarity and reducing repetition.
- Added a migration guide to assist users in updating to the new SDK version.

* refactor(java-app): Improve code quality based on review

- Abstracted Toast notifications into a `showToast` helper method in `SampleBaseActivity` to reduce boilerplate in individual activities.
- Replaced hardcoded strings in click listeners with string resources for better maintainability and localization.

* Refactor: Centralize Java sample app resources and simplify code

This commit refactors the Java API Demos sample app by moving shared resources to the `common` module and simplifying code.

Key changes:
-   **Code Simplification in `CameraControlsActivity`:**
    -   The `updateCameraPosition` method now uses a single formatted string resource (`camera_state_format`) instead of manual `StringBuilder` concatenation, making the code cleaner and more localizable.
    -   UI updates are now posted to the main thread using `runOnUiThread` and `view.postDelayed` instead of `new Handler(Looper.getMainLooper())`.

-   **Lifecycle Method Cleanup in `HelloMapActivity`:**
    -   Removed redundant null checks for `map3DView` in lifecycle callback methods (`onResume`, `onPause`, `onDestroy`, etc.), as the view is initialized in `onCreate`.

* build: Update Maps 3D SDK to local AAR and fix lint issues (temporary)

This commit updates the project's dependencies and build configuration.

Key changes:
- **Gradle Build Script:** The `sarifOutput` path in `build.gradle.kts` was updated to use the modern `layout.buildDirectory` API.
- **Lint Fix:** Added a `@param:StringRes` annotation target in `MainActivity.kt` to resolve a lint warning.

* feat: Update Maps 3D SDK to 0.1.0

This commit updates the Maps 3D SDK from a local AAR file to the remote artifact version 0.1.0. It also includes updates to several other libraries.

Key changes:

-   **Maps 3D SDK Update:**
    -   The `libs.versions.toml` files in both `ApiDemos` and `advanced` samples are updated to use `playServicesMaps3d = "0.1.0"`.

-   **Other Dependency Updates:**
    -   In the `advanced` sample, the following dependencies were updated:
        -   `composeBom` to `2025.09.01`
        -   `hilt` to `2.57.2`
        -   `playServicesBase` to `18.9.0`

* feat: Update Maps 3D SDK to 0.1.0 for the advanced samples

* fix: Fixes gradle checksum typo.

* Fix: Resolve build error for API level < 27

Resolves an issue where `android:windowLayoutInDisplayCutoutMode` was used in a theme that supported API levels below 27, causing a build failure.

This attribute is only available on API level 27 and higher. To fix this, the attribute has been moved to a separate theme file in the `values-v27` resource directory.

Also fixes a warning about multiple substitutions in the `camera_state_format` string resource by adding `formatted="false"`.

* fix:remove param from MainActivity.kt

* docs: Add the version number to the migration_guide.md

Author: dkhawk

Maps3DSamples/ApiDemos/common/build.gradle.kts

@@ -22,13 +22,13 @@ plugins {
 
 android {
     lint {
-        sarifOutput = file("$buildDir/reports/lint-results.sarif")
+        sarifOutput = layout.buildDirectory.file("reports/lint-results.sarif").get().asFile
     }
     namespace = "com.example.maps3dcommon"
-    compileSdk = 35
+    compileSdk = libs.versions.compileSdk.get().toInt()
 
     defaultConfig {
-        minSdk = 26
+        minSdk = libs.versions.minSdk.get().toInt()
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
         consumerProguardFiles("consumer-rules.pro")
@@ -48,8 +48,10 @@ android {
         sourceCompatibility = JavaVersion.VERSION_11
         targetCompatibility = JavaVersion.VERSION_11
     }
-    kotlinOptions {
-        jvmTarget = "11"
+    kotlin {
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+        }
     }
 }
 
@@ -67,5 +69,6 @@ dependencies {
 
     implementation(libs.androidx.material3)
 
-    implementation("com.google.android.gms:play-services-maps3d:0.0.1")
+    api(libs.play.services.base)
+    api(libs.play.services.maps3d)
 }

Maps3DSamples/ApiDemos/common/src/main/java/com/example/maps3d/common/Units.kt

@@ -93,7 +93,7 @@ fun Meters.plus(other: Meters) = Meters(value = this.value + other.value)
  * @property value: The numerical value.
  * @property unitsTemplate: The string resource ID for the units.
  */
-data class ValueWithUnitsTemplate(val value: Double, @StringRes val unitsTemplate: Int)
+data class ValueWithUnitsTemplate(val value: Double, @param:StringRes val unitsTemplate: Int)
 
 /** Abstract base class for all units converters. */
 abstract class UnitsConverter {

Maps3DSamples/ApiDemos/common/src/main/res/values/strings.xml

@@ -17,6 +17,9 @@
     <string name="app_name">Maps 3D Samples</string>
     <string name="title_activity_main">MainActivity</string>
 
+    <string name="java_app_name">Java Maps3D Samples</string>
+    <string name="java_title_activity_main">Java Maps3D Samples</string>
+
     <string name="samples_menu_title">3D Maps SDK Samples</string>
 
     <string name="feature_title_overview_hello_3d_map">Hello 3D Maps</string>
@@ -81,5 +84,9 @@
     -->
     <string name="in_kilometers" translatable="false">%1$,.1f km</string>
 
-
+    <string name="camera_state_format" formatted="false">Lat: %.4f, Lng: %.4f, Alt: %.2fm\nHdg: %.2f° (%s), Tlt: %.2f°, Rng: %.2fm</string>
+    <string name="polygon_museum_clicked">Check out the Museum!</string>
+    <string name="polygon_zoo_clicked">Zoo time</string>
+    <string name="polyline_trail_clicked">Hiking time!</string>
+    <string name="model_plane_clicked">Model clicked</string>
 </resources>

Maps3DSamples/ApiDemos/gradle/libs.versions.toml

@@ -1,18 +1,26 @@
 [versions]
-agp = "8.10.1"
+compileSdk = "36"
+minSdk = "26"
+targetSdk = "36"
+
+activityCompose = "1.11.0"
+agp = "8.13.0"
+appcompat = "1.7.1"
+composeBom = "2025.09.00"
+coreKtx = "1.17.0"
 desugar_jdk_libs = "2.1.5"
-kotlin = "2.0.21"
-coreKtx = "1.16.0"
+espressoCore = "3.7.0"
 junit = "4.13.2"
-junitVersion = "1.2.1"
-espressoCore = "3.6.1"
-appcompat = "1.7.1"
-material = "1.12.0"
-lifecycleRuntimeKtx = "2.9.1"
-activityCompose = "1.10.1"
-composeBom = "2025.06.00"
-playServicesMaps3d = "0.0.2"
+junitVersion = "1.3.0"
+kotlin = "2.2.20"
+lifecycleRuntimeKtx = "2.9.4"
+material = "1.13.0"
+
+playServicesBase = "18.8.0"
+playServicesMaps3d = "0.1.0"
 secretsGradlePlugin = "2.0.1"
+truth = "1.4.5"
+uiautomator = "2.3.0"
 
 [libraries]
 androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
@@ -32,7 +40,10 @@ androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-toolin
 androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
 androidx-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
 androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
+play-services-base = { module = "com.google.android.gms:play-services-base", version.ref = "playServicesBase" }
 play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "playServicesMaps3d" }
+truth = { module = "com.google.truth:truth", version.ref = "truth" }
+androidx-uiautomator = { module = "androidx.test.uiautomator:uiautomator", version.ref = "uiautomator" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }

Maps3DSamples/ApiDemos/gradle/wrapper/gradle-wrapper.jar

@@ -1,6 +1,8 @@
-#Mon Apr 28 13:40:25 MDT 2025
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
+distributionSha256Sum=a17ddd85a26b6a7f5ddb71ff8b05fc5104c0202c6e64782429790c933686c806
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists