feat(google-maps): DX overhaul for v1

docs/content/scripts/google-maps/.navigation.yml

@@ -0,0 +1 @@
+title: Google Maps

docs/content/scripts/google-maps/1.guides/.navigation.yml

@@ -0,0 +1,2 @@
+title: Guides
+icon: i-ph-book-duotone

docs/content/scripts/google-maps/1.guides/1.performance.md

@@ -0,0 +1,127 @@
+---
+title: Performance
+---
+
+`ScriptGoogleMaps` is optimized by default: the JavaScript API only loads when the user interacts with the map. Before that, a lightweight static image placeholder is shown.
+
+## Loading Strategies
+
+### Default: Lazy (Recommended)
+
+By default, the map loads on `mouseenter`, `mouseover`, or `mousedown`. Most page visitors never interact with the map, so you avoid the Maps JavaScript API charge for those sessions.
+
+```vue
+<template>
+  <!-- Loads JS API on first hover/click -->
+  <ScriptGoogleMaps
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+### Immediate Loading
+
+Forces the JavaScript API to load with the page. Use this only when the map is the primary content and you need it interactive from the start.
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    trigger="immediate"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+::callout{color="amber"}
+Immediate loading charges the Maps JavaScript API ($7/1000) on every page view. Only use this when the map is essential to the page experience.
+::
+
+### Custom Triggers
+
+You can control exactly when the map loads using any [Element Event Trigger](/docs/guides/script-triggers#element-event-triggers).
+
+```vue
+<template>
+  <!-- Only load on explicit click -->
+  <ScriptGoogleMaps trigger="mousedown" />
+
+  <!-- Load when element enters viewport -->
+  <ScriptGoogleMaps trigger="visible" />
+</template>
+```
+
+## Placeholder Optimization
+
+### Above the Fold
+
+When the map is visible without scrolling, mark it for priority loading. This sets the placeholder image to `loading="eager"` and adds a `preconnect` hint.
+
+```vue
+<template>
+  <ScriptGoogleMaps above-the-fold />
+</template>
+```
+
+### Custom Placeholder
+
+Replace the default Google Static Maps image with your own custom image to avoid Static Maps API charges. Useful when you have a screenshot or illustration of the map area.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #placeholder>
+      <img src="/map-preview.webp" alt="Map of Sydney" style="width: 100%; height: 100%; object-fit: cover;">
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+You can also access the generated static map URL if you want to use it with custom styling. Note that rendering the `placeholder` URL still makes a Static Maps API request and incurs charges:
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #placeholder="{ placeholder }">
+      <img :src="placeholder" alt="Map" style="filter: grayscale(1);">
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Loading State
+
+Show a custom indicator while the JavaScript API loads:
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #loading>
+      <div style="display: flex; align-items: center; justify-content: center; height: 100%;">
+        Loading map...
+      </div>
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+## Marker Performance
+
+When rendering many markers, use `ScriptGoogleMapsMarkerClusterer` to group nearby markers. This significantly reduces DOM elements and improves pan/zoom performance.
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="center" :zoom="10">
+    <ScriptGoogleMapsMarkerClusterer>
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-for="place in places"
+        :key="place.id"
+        :position="place.position"
+      />
+    </ScriptGoogleMapsMarkerClusterer>
+  </ScriptGoogleMaps>
+</template>
+```
+
+See [Billing & Permissions](/scripts/google-maps/guides/billing) for a full cost breakdown and optimization strategies.

docs/content/scripts/google-maps/1.guides/2.programmatic-api.md

@@ -0,0 +1,130 @@
+---
+title: Programmatic API
+---
+
+The `ScriptGoogleMaps` component exposes its internal APIs via template ref, giving you full control beyond what the declarative SFC components provide.
+
+## Accessing the API
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+function onReady({ googleMaps, map, createAdvancedMapMarker, resolveQueryToLatLng, importLibrary }) {
+  // All APIs available here
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" @ready="onReady" />
+</template>
+```
+
+### Exposed Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `googleMaps` | `Ref<typeof google.maps>`{lang="html"} | The Google Maps API namespace |
+| `map` | `ShallowRef<google.maps.Map>`{lang="html"} | The map instance |
+| `createAdvancedMapMarker` | `(options?) => Promise<AdvancedMarkerElement>`{lang="html"} | Create a marker programmatically |
+| `resolveQueryToLatLng` | `(query: string) => Promise<LatLng>`{lang="html"} | Geocode a location string |
+| `importLibrary` | `(key: string) => Promise<any>`{lang="html"} | Load an additional Google Maps library |
+
+## Creating Markers Programmatically
+
+For cases where declarative `v-for` markers aren't flexible enough (dynamic data, imperative creation logic), use `createAdvancedMapMarker`:
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function addMarkerAtCenter() {
+  const map = mapRef.value.map.value
+  const center = map.getCenter()
+  const marker = await mapRef.value.createAdvancedMapMarker({
+    position: { lat: center.lat(), lng: center.lng() },
+    title: 'New Marker',
+  })
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" :center="{ lat: -33.8688, lng: 151.2093 }" :zoom="12" />
+  <button @click="addMarkerAtCenter">
+    Add Marker at Center
+  </button>
+</template>
+```
+
+::callout
+For most use cases, prefer the declarative `ScriptGoogleMapsAdvancedMarkerElement` component with `v-for`. Use the programmatic API when you need fine-grained control over marker lifecycle or are integrating with external data sources.
+::
+
+## Geocoding Queries
+
+Convert location strings to coordinates using `resolveQueryToLatLng`. When you enable the registry proxy, this resolves server-side (cheaper, API key hidden). Otherwise it falls back to the client-side Places API.
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function goToLocation(query: string) {
+  const latLng = await mapRef.value.resolveQueryToLatLng(query)
+  mapRef.value.map.value.setCenter(latLng)
+  mapRef.value.map.value.setZoom(15)
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" :center="{ lat: 0, lng: 0 }" :zoom="2" />
+  <button @click="goToLocation('Eiffel Tower, Paris')">
+    Go to Paris
+  </button>
+</template>
+```
+
+## Importing Libraries
+
+Google Maps splits functionality into libraries that load on demand. Use `importLibrary` to access geometry, drawing, places, and visualization APIs:
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function measureDistance(a: google.maps.LatLng, b: google.maps.LatLng) {
+  const geometry = await mapRef.value.importLibrary('geometry')
+  return geometry.spherical.computeDistanceBetween(a, b)
+}
+</script>
+```
+
+Available libraries: `marker`, `places`, `geometry`, `drawing`, `visualization`
+
+## Subscribing to Map Events
+
+Use the `@ready` event to access the map instance and subscribe to native Google Maps events:
+
+```vue
+<script setup lang="ts">
+function onReady({ map }) {
+  watch(map, (m) => {
+    if (!m)
+      return
+    m.addListener('zoom_changed', () => {
+      console.log('Zoom:', m.getZoom())
+    })
+    m.addListener('center_changed', () => {
+      console.log('Center:', m.getCenter()?.toJSON())
+    })
+    m.addListener('idle', () => {
+      // Map finished moving, good time to fetch data for visible bounds
+      const bounds = m.getBounds()
+    })
+  }, { immediate: true })
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps @ready="onReady" />
+</template>
+```

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

@@ -0,0 +1,105 @@
+---
+title: Map Styling
+---
+
+Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Both work with Nuxt Scripts, including the static map placeholder.
+
+## JSON Styles
+
+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.
+
+```vue
+<script setup lang="ts">
+const mapOptions = {
+  styles: [
+    { elementType: 'labels', stylers: [{ visibility: 'off' }, { color: '#f49f53' }] },
+    { featureType: 'landscape', stylers: [{ color: '#f9ddc5' }, { lightness: -7 }] },
+    { featureType: 'road', stylers: [{ color: '#813033' }, { lightness: 43 }] },
+    { featureType: 'water', stylers: [{ color: '#1994bf' }, { saturation: -69 }, { gamma: 0.99 }, { lightness: 43 }] },
+    { featureType: 'poi.park', stylers: [{ color: '#645c20' }, { lightness: 39 }] },
+  ],
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps :map-options="mapOptions" />
+</template>
+```
+
+## Cloud-Based Map IDs
+
+Google's [Map Styling](https://developers.google.com/maps/documentation/cloud-customization) lets you create and manage styles in the Google Cloud Console, then apply them with a map ID.
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-options="{ mapId: 'YOUR_MAP_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+::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.
+::
+
+## Dark Mode / Color Mode
+
+Switch map styles automatically based on the user's color mode preference. Provide a `mapIds` object with light and dark map IDs:
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+This auto-detects `@nuxtjs/color-mode` if installed. You can also control it manually with the `colorMode` prop:
+
+```vue
+<script setup lang="ts">
+const isDark = ref(false)
+</script>
+
+<template>
+  <ScriptGoogleMaps
+    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
+    :color-mode="isDark ? 'dark' : 'light'"
+  />
+  <button @click="isDark = !isDark">
+    Toggle Dark Mode
+  </button>
+</template>
+```
+
+## Combining Styles with Markers
+
+Custom-styled maps pair well with custom marker content for a cohesive look:
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-options="{ mapId: 'DARK_THEME_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="13"
+  >
+    <ScriptGoogleMapsAdvancedMarkerElement
+      v-for="place in places"
+      :key="place.id"
+      :position="place.position"
+    >
+      <template #content>
+        <div style="background: rgba(255,255,255,0.9); padding: 4px 8px; border-radius: 4px; font-size: 12px;">
+          {{ place.label }}
+        </div>
+      </template>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```