feat: add controls for light and dark modes (#548)

Author: jokerttu

README.md

@@ -95,7 +95,7 @@ in an unbounded widget will cause the application to throw a Flutter exception.
 
 You can also add a bare GoogleMapsMapView that works as a normal map view without navigation functionality.
 
-### Add a navigation view
+### Add a navigation view and start a navigation session
 
 ```dart
 import 'package:flutter/material.dart';
@@ -199,7 +199,7 @@ This parameter has only an effect on Android.
 
 ```
 
-#### Using Map IDs
+### Using Map IDs
 You can configure your map by providing a `mapId` parameter during map initialization. Map IDs are created in the [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/studio/maps) and allow you to [enable various Google Maps Platform features](https://developers.google.com/maps/documentation/android-sdk/map-ids/mapid-over#features-available), such as cloud-based map styling.
 
 > [!NOTE]
@@ -262,6 +262,89 @@ Widget build(BuildContext context) {
 }
 ```
 
+### Controlling Light and Dark Mode
+
+The SDK provides two different settings to control the appearance of maps and navigation UI: `mapColorScheme` and `forceNightMode`. Which setting to use depends on whether navigation UI is enabled or disabled.
+
+These settings can be configured both during initialization and dynamically changed after initialization using the view controllers.
+
+#### For Navigation Views (GoogleMapsNavigationView)
+
+**When navigation UI is enabled:**
+- Use `forceNightMode` (or `initialForceNightMode` during initialization) to control both the navigation UI elements and the map tile colors.
+- The `mapColorScheme` setting is ignored when navigation UI is enabled.
+
+> [!TIP]
+> When navigation guidance is running, it's recommended to use `NavigationForceNightMode.auto` (the default). This allows the Navigation SDK to automatically determine the appropriate day or night mode based on the user's location and local time, which may differ from the device's system settings.
+
+```dart
+GoogleMapsNavigationView(
+  initialForceNightMode: NavigationForceNightMode.auto,
+  initialMapColorScheme: MapColorScheme.dark, // IGNORED when navigation UI is enabled
+)
+```
+
+To manually force a specific mode:
+```dart
+GoogleMapsNavigationView(
+  initialForceNightMode: NavigationForceNightMode.forceNight,
+)
+```
+
+You can also change the setting dynamically after initialization:
+
+```dart
+// Change after initialization when navigation UI is enabled
+await navigationViewController.setForceNightMode(NavigationForceNightMode.forceNight);
+```
+
+**When navigation UI is disabled:**
+- Use `mapColorScheme` (or `initialMapColorScheme` during initialization) to control the map tile colors.
+- The `forceNightMode` setting has no effect when navigation UI is disabled.
+
+```dart
+GoogleMapsNavigationView(
+  initialNavigationUIEnabledPreference: NavigationUIEnabledPreference.disabled,
+  initialMapColorScheme: MapColorScheme.dark, 
+  initialForceNightMode: NavigationForceNightMode.forceDay // IGNORED when navigation UI is disabled
+)
+```
+
+You can also change the setting dynamically after initialization:
+
+```dart
+// Change after initialization when navigation UI is disabled
+await navigationViewController.setMapColorScheme(MapColorScheme.dark);
+```
+
+#### For Map Views (GoogleMapsMapView)
+
+Map views only support `mapColorScheme` to control the map tile colors:
+
+```dart
+GoogleMapsMapView(
+  initialMapColorScheme: MapColorScheme.dark,
+)
+```
+
+You can also change the setting dynamically after initialization:
+
+```dart
+// Change after initialization
+await mapViewController.setMapColorScheme(MapColorScheme.dark);
+```
+
+#### Available Options
+
+- `NavigationForceNightMode`: 
+  - `auto` (default and recommended) - SDK determines day/night mode based on user's location and local time
+  - `forceDay` - Force day mode regardless of time or location
+  - `forceNight` - Force night mode regardless of time or location
+- `MapColorScheme`: 
+  - `followSystem` (default) - Follow device system settings
+  - `light` - Force light color scheme
+  - `dark` - Force dark color scheme
+
 ## Support for Android Auto and Apple CarPlay
 This plugin is compatible with both Android Auto and Apple CarPlay infotainment systems. For more details, please refer to the respective platform documentation:
 

android/src/main/kotlin/com/google/maps/flutter/navigation/Convert.kt

@@ -28,6 +28,7 @@ import com.google.android.gms.maps.model.Gap
 import com.google.android.gms.maps.model.JointType
 import com.google.android.gms.maps.model.LatLng
 import com.google.android.gms.maps.model.LatLngBounds
+import com.google.android.gms.maps.model.MapColorScheme
 import com.google.android.gms.maps.model.PatternItem
 import com.google.android.gms.maps.model.Polygon
 import com.google.android.gms.maps.model.Polyline
@@ -41,6 +42,7 @@ import com.google.android.libraries.mapsplatform.turnbyturn.model.NavState
 import com.google.android.libraries.mapsplatform.turnbyturn.model.StepInfo
 import com.google.android.libraries.navigation.AlternateRoutesStrategy
 import com.google.android.libraries.navigation.DisplayOptions
+import com.google.android.libraries.navigation.ForceNightMode
 import com.google.android.libraries.navigation.NavigationRoadStretchRenderingData
 import com.google.android.libraries.navigation.NavigationTrafficData
 import com.google.android.libraries.navigation.Navigator
@@ -82,6 +84,7 @@ object Convert {
     options.minZoomPreference?.let { googleMapOptions.minZoomPreference(it.toFloat()) }
     options.maxZoomPreference?.let { googleMapOptions.maxZoomPreference(it.toFloat()) }
     googleMapOptions.zoomControlsEnabled(options.zoomControlsEnabled)
+    googleMapOptions.mapColorScheme(convertMapColorSchemeFromDto(options.mapColorScheme))
     options.mapId?.let { googleMapOptions.mapId(it) }
 
     return MapOptions(googleMapOptions, options.padding)
@@ -114,7 +117,8 @@ object Convert {
 
     return NavigationViewOptions(
       navigationUiEnabledPreference =
-        convertNavigationUIEnabledPreferenceFromDto(options.navigationUIEnabledPreference)
+        convertNavigationUIEnabledPreferenceFromDto(options.navigationUIEnabledPreference),
+      forceNightMode = convertNavigationForceNightModeFromDto(options.forceNightMode),
     )
   }
 
@@ -279,6 +283,63 @@ object Convert {
     }
   }
 
+  /**
+   * Converts pigeon [MapColorSchemeDto] to [MapColorScheme].
+   *
+   * @param mapColorScheme pigeon [MapColorSchemeDto].
+   * @return [MapColorScheme].
+   */
+  fun convertMapColorSchemeFromDto(mapColorScheme: MapColorSchemeDto): Int {
+    return when (mapColorScheme) {
+      MapColorSchemeDto.FOLLOW_SYSTEM -> MapColorScheme.FOLLOW_SYSTEM
+      MapColorSchemeDto.LIGHT -> MapColorScheme.LIGHT
+      MapColorSchemeDto.DARK -> MapColorScheme.DARK
+    }
+  }
+
+  /**
+   * Converts [MapColorScheme] to pigeon [MapColorSchemeDto].
+   *
+   * @param mapColorScheme [MapColorScheme].
+   * @return pigeon [MapColorSchemeDto].
+   */
+  fun convertMapColorSchemeToDto(mapColorScheme: Int): MapColorSchemeDto {
+    return when (mapColorScheme) {
+      MapColorScheme.LIGHT -> MapColorSchemeDto.LIGHT
+      MapColorScheme.DARK -> MapColorSchemeDto.DARK
+      else -> MapColorSchemeDto.FOLLOW_SYSTEM
+    }
+  }
+
+  /**
+   * Converts pigeon [NavigationForceNightModeDto] to [ForceNightMode].
+   *
+   * @param forceNightMode pigeon [NavigationForceNightModeDto].
+   * @return [ForceNightMode].
+   */
+  fun convertNavigationForceNightModeFromDto(forceNightMode: NavigationForceNightModeDto): Int {
+    return when (forceNightMode) {
+      NavigationForceNightModeDto.AUTO -> ForceNightMode.AUTO
+      NavigationForceNightModeDto.FORCE_DAY -> ForceNightMode.FORCE_DAY
+      NavigationForceNightModeDto.FORCE_NIGHT -> ForceNightMode.FORCE_NIGHT
+    }
+  }
+
+  /**
+   * Converts [ForceNightMode] to pigeon [NavigationForceNightModeDto].
+   *
+   * @param forceNightMode [ForceNightMode].
+   * @return pigeon [NavigationForceNightModeDto].
+   */
+  fun convertNavigationForceNightModeToDto(forceNightMode: Int): NavigationForceNightModeDto {
+    return when (forceNightMode) {
+      ForceNightMode.AUTO -> NavigationForceNightModeDto.AUTO
+      ForceNightMode.FORCE_DAY -> NavigationForceNightModeDto.FORCE_DAY
+      ForceNightMode.FORCE_NIGHT -> NavigationForceNightModeDto.FORCE_NIGHT
+      else -> throw FlutterError("convertError", "Unknown ForceNightMode: $forceNightMode")
+    }
+  }
+
   /**
    * Converts pigeon [NavigationWaypointDto] to Google Navigation [Waypoint].
    *

android/src/main/kotlin/com/google/maps/flutter/navigation/GoogleMapsBaseMapView.kt

@@ -1055,4 +1055,12 @@ abstract class GoogleMapsBaseMapView(
   fun getPadding(): MapPaddingDto {
     return _mapOptions?.padding ?: MapPaddingDto(0, 0, 0, 0)
   }
+
+  fun getMapColorScheme(): Int {
+    return getMap().mapColorScheme
+  }
+
+  fun setMapColorScheme(mapColorScheme: Int) {
+    getMap().mapColorScheme = mapColorScheme
+  }
 }

android/src/main/kotlin/com/google/maps/flutter/navigation/GoogleMapsNavigationView.kt

@@ -20,6 +20,7 @@ import android.content.Context
 import android.content.res.Configuration
 import android.view.View
 import com.google.android.gms.maps.CameraUpdateFactory
+import com.google.android.libraries.navigation.ForceNightMode
 import com.google.android.libraries.navigation.NavigationView
 import com.google.android.libraries.navigation.OnNavigationUiChangedListener
 import com.google.android.libraries.navigation.PromptVisibilityChangedListener
@@ -38,6 +39,7 @@ internal constructor(
   private val _navigationView: NavigationView = NavigationView(context, mapOptions.googleMapOptions)
 
   /// Default values for UI features.
+  private var _forceNightMode: Int = ForceNightMode.AUTO
   private var _isNavigationTripProgressBarEnabled: Boolean = false
   private var _isNavigationHeaderEnabled: Boolean = true
   private var _isNavigationFooterEnabled: Boolean = true
@@ -76,6 +78,12 @@ internal constructor(
     }
     _navigationView.isNavigationUiEnabled = navigationViewEnabled
 
+    // Initialize force night mode if provided
+    navigationOptions?.forceNightMode?.let { forceNightMode ->
+      _forceNightMode = forceNightMode
+      _navigationView.setForceNightMode(forceNightMode)
+    }
+
     viewRegistry.registerNavigationView(viewId, this)
 
     _navigationView.getMapAsync { map ->
@@ -288,4 +296,13 @@ internal constructor(
   fun showRouteOverview() {
     _navigationView.showRouteOverview()
   }
+
+  fun getForceNightMode(): Int {
+    return _forceNightMode
+  }
+
+  fun setForceNightMode(forceNightMode: Int) {
+    _forceNightMode = forceNightMode
+    _navigationView.setForceNightMode(forceNightMode)
+  }
 }

android/src/main/kotlin/com/google/maps/flutter/navigation/GoogleMapsViewMessageHandler.kt

@@ -519,4 +519,24 @@ class GoogleMapsViewMessageHandler(private val viewRegistry: GoogleMapsViewRegis
   override fun getPadding(viewId: Long): MapPaddingDto {
     return getView(viewId.toInt()).getPadding()
   }
+
+  override fun getMapColorScheme(viewId: Long): MapColorSchemeDto {
+    val colorScheme = getView(viewId.toInt()).getMapColorScheme()
+    return Convert.convertMapColorSchemeToDto(colorScheme)
+  }
+
+  override fun setMapColorScheme(viewId: Long, mapColorScheme: MapColorSchemeDto) {
+    val colorScheme = Convert.convertMapColorSchemeFromDto(mapColorScheme)
+    getView(viewId.toInt()).setMapColorScheme(colorScheme)
+  }
+
+  override fun getForceNightMode(viewId: Long): NavigationForceNightModeDto {
+    val forceNightMode = getNavigationView(viewId.toInt()).getForceNightMode()
+    return Convert.convertNavigationForceNightModeToDto(forceNightMode)
+  }
+
+  override fun setForceNightMode(viewId: Long, forceNightMode: NavigationForceNightModeDto) {
+    val nightMode = Convert.convertNavigationForceNightModeFromDto(forceNightMode)
+    getNavigationView(viewId.toInt()).setForceNightMode(nightMode)
+  }
 }

android/src/main/kotlin/com/google/maps/flutter/navigation/NavigationViewConfiguration.kt

@@ -26,4 +26,7 @@ enum class NavigationUIEnabledPreference {
 }
 
 /** Class for navigation view configuration options. */
-data class NavigationViewOptions(val navigationUiEnabledPreference: NavigationUIEnabledPreference?)
+data class NavigationViewOptions(
+  val navigationUiEnabledPreference: NavigationUIEnabledPreference?,
+  val forceNightMode: Int?,
+)