feat(animations): Add map steady check for better animations (#20)

* feat(animations): Add map steady check for smoother animations

Introduces a mechanism to wait for the map to be fully loaded and idle (isMapSteady) before initiating camera animations. This prevents animations from starting on a partially rendered or moving map, resulting in a smoother and more professional user experience.

- Adds awaitMapSteady() to Map3dViewModel to suspend execution until the map is stable, with an optional timeout.
- Creates a new WaitUntilTheMapIsSteadyStep for use in declarative animation sequences.
- Refactors ThreeDMap, ScenarioScreen, and CameraControlDemoScreen to pass the ViewModel directly, simplifying state management and removing the need for onMap3dViewReady and onReleaseMap callbacks.
- Integrates the steady check into existing animation scenarios to ensure they begin from a stable map state.

* fix: remove param from @stringres parameter

Author: dkhawk

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, @param:StringRes val unitsTemplate: Int)
+data class ValueWithUnitsTemplate(val value: Double, @StringRes val unitsTemplate: Int)
 
 /** Abstract base class for all units converters. */
 abstract class UnitsConverter {

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/common/Map3dViewModel.kt

@@ -44,12 +44,16 @@ import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.callbackFlow
 import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeout
 import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
 
 abstract class Map3dViewModel : ViewModel() {
   abstract val TAG: String
@@ -68,6 +72,9 @@ abstract class Map3dViewModel : ViewModel() {
   private val _cameraRestriction = MutableStateFlow<CameraRestriction?>(null)
   val cameraRestriction = _cameraRestriction.asStateFlow()
 
+  private val _isMapSteady = MutableStateFlow(false)
+  val isMapSteady = _isMapSteady.asStateFlow()
+
   private val _mapMode = MutableStateFlow(Map3DMode.SATELLITE)
   val mapMode = _mapMode.asStateFlow()
 
@@ -292,6 +299,32 @@ abstract class Map3dViewModel : ViewModel() {
     _mapMode.value = mode
   }
 
+  fun onMapSteadyChange(isSteady: Boolean) {
+    _isMapSteady.value = isSteady
+  }
+
+  /**
+   * Suspends until the map has entered a steady state, meaning it is not moving and has
+   * finished loading. This is useful to ensure that camera animations start from a stable
+   * and predictable state.
+   *
+   * @param timeoutMillis The maximum time to wait in milliseconds. A value of 0 means no timeout.
+   */
+  @OptIn(ExperimentalTime::class)
+  suspend fun awaitMapSteady(timeoutMillis: Long) {
+    if (timeoutMillis > 0) {
+      try {
+        withTimeout(timeoutMillis) {
+          isMapSteady.first { it }
+        }
+      } catch (_: TimeoutCancellationException) {
+        Log.w("Map3dViewModel", "awaitMapSteady timed out after $timeoutMillis ms")
+      }
+    } else {
+      isMapSteady.first { it }
+    }
+  }
+
   override fun onCleared() {
     _googleMap3D.value = null
     super.onCleared()

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/Animations.kt

@@ -28,6 +28,18 @@ data class DelayStep(val durationMillis: Long) : AnimationStep {
   }
 }
 
+/**
+ * An [AnimationStep] that waits until the map is fully loaded and idle before proceeding
+ * to the next step in the animation sequence.
+ *
+ * @param timeoutMillis The maximum time to wait in milliseconds. A value of 0 means no timeout.
+ */
+data class WaitUntilTheMapIsSteadyStep(val timeoutMillis: Long = 0) : AnimationStep {
+  override suspend fun invoke(viewModel: ScenariosViewModel) {
+    viewModel.awaitMapSteady(timeoutMillis)
+  }
+}
+
 data class FlyToStep(val flyToOptions: FlyToOptions) : AnimationStep {
   override suspend operator fun invoke(viewModel: ScenariosViewModel) {
     viewModel.awaitFlyTo(flyToOptions)

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/CameraAttributesScreen.kt

@@ -48,8 +48,7 @@ private val rollSliderRange = -360f..360f
  * which changes based on the currently selected [attribute].
  *
  * @param scenario The scenario providing options for the map.
- * @param onMap3dViewReady A callback function invoked when the [GoogleMap3D] view is ready.
- * @param onReleaseMap A callback function invoked when the map should be released.
+ * @param viewModel The view model that manages the map's state.
  * @param modifier The modifier to be applied to the composable.
  * @param heading The current heading value of the camera.
  * @param tilt The current tilt value of the camera.
@@ -60,8 +59,7 @@ private val rollSliderRange = -360f..360f
 @Composable
 fun CameraControlDemoScreen(
   scenario: Scenario,
-  onMap3dViewReady: (GoogleMap3D) -> Unit,
-  onReleaseMap: () -> Unit,
+  viewModel: ScenariosViewModel,
   modifier: Modifier = Modifier,
   heading: Float,
   tilt: Float,
@@ -74,8 +72,7 @@ fun CameraControlDemoScreen(
       ThreeDMap(
         modifier = Modifier.fillMaxWidth().weight(1f),
         options = scenario.mapsOptions,
-        onMap3dViewReady = onMap3dViewReady,
-        onReleaseMap = onReleaseMap,
+        viewModel = viewModel,
       )
       Spacer(modifier = Modifier.height(16.dp))
       Crossfade(

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/Scenario.kt

@@ -14,7 +14,6 @@
 
 package com.example.advancedmaps3dsamples.scenarios
 
-import android.util.Log // Import Log
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.res.stringResource
 import com.google.android.gms.maps3d.Map3DOptions
@@ -39,7 +38,6 @@ data class Scenario(
   @Composable fun getTitle() = stringResource(titleId)
 
   fun reset(viewModel: ScenariosViewModel) {
-    Log.d("ScenarioReset", "Resetting scenario: $name")
     viewModel.setCamera(mapsOptions.toCamera()) // Set initial camera
     viewModel.setMapMode(mapsOptions.mapMode)
 
@@ -60,8 +58,6 @@ data class Scenario(
     polygons.forEach { polygon ->
       viewModel.addPolygon(polygon)
     }
-
-    Log.d("ScenarioReset", "Reset complete for scenario: $name")
   }
 }