fix(google-maps): handle marker + mapOptions.styles conflict (#719)

Author: harlan-zw

docs/content/scripts/google-maps/1.guides/2.map-styling.md

@@ -8,7 +8,11 @@ Google Maps supports two styling approaches: legacy JSON styles and cloud-based
 
 Use the `mapOptions.styles` prop with a JSON style array. You can find pre-made styles on [Snazzy Maps](https://snazzymaps.com/).
 
-Styles automatically apply to both the static map placeholder and the interactive map.
+Styles apply to both the static map placeholder and the interactive map.
+
+::callout{color="amber"}
+JSON `styles` cannot combine with `ScriptGoogleMapsMarker`. `AdvancedMarkerElement` requires a `mapId`, and Google Maps treats `styles` and `mapId` as mutually exclusive. If the map contains markers, use [cloud-based map IDs](#cloud-based-map-ids) instead.
+::
 
 ```vue
 <script setup lang="ts">
@@ -63,7 +67,7 @@ Google's [Map Styling](https://developers.google.com/maps/documentation/cloud-cu
 ```
 
 ::callout{color="amber"}
-JSON `styles` and `mapId` are mutually exclusive. When you provide both, the component ignores `mapId` and applies `styles`. Note that `AdvancedMarkerElement` requires a map ID to function; legacy `Marker` works without one.
+JSON `styles` and `mapId` are mutually exclusive. When both are set, Google Maps keeps `mapId` and ignores `styles`. Because `ScriptGoogleMapsMarker` uses `AdvancedMarkerElement` (which requires a `mapId`), cloud-based map IDs are the only way to style a map that contains markers.
 ::
 
 ## Dark Mode / Color Mode

packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue

@@ -223,12 +223,11 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 })
 
 const options = computed(() => {
-  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
-  // Precedence (defu merges left-to-right, leftmost wins):
-  // 1. centerOverride: resolved query result, always wins for center
-  // 2. mapOptions: preferred public API
-  // 3. deprecated top-level: legacy fallback for center/zoom
-  // 4. defaults: { zoom: 15 } when nothing else is set
+  // JSON `styles` and `mapId` are mutually exclusive in Google Maps. When the user
+  // sets `styles`, we drop `mapId` so styles apply. Otherwise fall back to a map ID
+  // so `AdvancedMarkerElement` can function. The marker component warns if markers
+  // are mounted against a styled (mapId-less) map.
+  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'DEMO_MAP_ID')
   return defu(
     { center: centerOverride.value, mapId },
     props.mapOptions,

packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue

@@ -57,6 +57,9 @@ let gmpClickHandler: ((e: any) => void) | undefined
 const advancedMarkerElement = useGoogleMapsResource<google.maps.marker.AdvancedMarkerElement>({
   ready: () => !slots.content || !!markerContent.value,
   async create({ mapsApi, map }) {
+    if (import.meta.dev && !map.get('mapId')) {
+      console.warn('[nuxt-scripts] <ScriptGoogleMapsMarker> requires the parent <ScriptGoogleMaps> to have a `mapId` set, but none was found. This usually happens when `mapOptions.styles` (JSON styles) is set, since Google Maps treats `styles` and `mapId` as mutually exclusive. Use cloud-based map styling instead: https://scripts.nuxt.com/scripts/google-maps/guides/map-styling')
+    }
     await mapsApi.importLibrary('marker')
     const marker = new mapsApi.marker.AdvancedMarkerElement({
       ...props.options,