feat(google-maps): overlay view panning, cluster auto-hide, and render guard (#663)

Author: harlan-zw

docs/content/scripts/google-maps/2.api/13.overlay-view.md

@@ -94,6 +94,42 @@ For simple cases where remounting is acceptable, `v-if` also works:
 </template>
 ```
 
+## Map Panning
+
+When an overlay opens, the map automatically pans so the overlay is fully visible, matching the native `InfoWindow` behavior. The default padding is 40px from the map edge.
+
+To customize the padding or disable panning:
+
+```vue
+<!-- Custom padding -->
+<ScriptGoogleMapsOverlayView :pan-on-open="60">
+  ...
+</ScriptGoogleMapsOverlayView>
+
+<!-- Disable panning -->
+<ScriptGoogleMapsOverlayView :pan-on-open="false">
+  ...
+</ScriptGoogleMapsOverlayView>
+```
+
+## Cluster Awareness
+
+When used inside a `ScriptGoogleMapsMarkerClusterer`, overlay views automatically hide when their parent marker joins a cluster on zoom out. This prevents orphaned overlays from floating over cluster icons.
+
+When its marker is clustered, the overlay updates `v-model:open` to `false`. The user will need to reopen the overlay (e.g. click the marker again) after zooming back in.
+
+To disable this behavior:
+
+```vue
+<ScriptGoogleMapsMarkerClusterer>
+  <ScriptGoogleMapsAdvancedMarkerElement :position="markerPosition">
+    <ScriptGoogleMapsOverlayView :hide-when-clustered="false">
+      ...
+    </ScriptGoogleMapsOverlayView>
+  </ScriptGoogleMapsAdvancedMarkerElement>
+</ScriptGoogleMapsMarkerClusterer>
+```
+
 ::callout
 The `blockMapInteraction` prop (default `true`) calls `google.maps.OverlayView.preventMapHitsAndGesturesFrom()`{lang="ts"} to stop clicks, taps, and drags from propagating through the overlay to the map. Set it to `false` for non-interactive overlays like labels.
 ::

src/runtime/components/GoogleMaps/ScriptGoogleMapsMarkerClusterer.vue

@@ -1,7 +1,8 @@
 <script lang="ts">
 import type { InjectionKey, ShallowRef } from 'vue'
-import { provide, shallowRef, watch } from 'vue'
+import { inject, provide, shallowRef, watch } from 'vue'
 import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
+import { MAP_INJECTION_KEY } from './injectionKeys'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 // Inline types to avoid requiring @googlemaps/markerclusterer as a build-time dependency
@@ -20,10 +21,14 @@ export interface MarkerClustererOptions {
   onClusterClick?: unknown
 }
 
-export const MARKER_CLUSTERER_INJECTION_KEY = Symbol('marker-clusterer') as InjectionKey<{
+export interface MarkerClustererContext {
   markerClusterer: ShallowRef<MarkerClustererInstance | undefined>
   requestRerender: () => void
-}>
+  /** Increments after each clustering cycle; watch to detect cluster membership changes */
+  clusteringVersion: ShallowRef<number>
+}
+
+export const MARKER_CLUSTERER_INJECTION_KEY = Symbol('marker-clusterer') as InjectionKey<MarkerClustererContext>
 </script>
 
 <script setup lang="ts">
@@ -56,6 +61,9 @@ const markerClustererEvents = [
   'clusteringend',
 ] as const
 
+const mapContext = inject(MAP_INJECTION_KEY, undefined)
+const clusteringVersion = shallowRef(0)
+
 const markerClusterer = useGoogleMapsResource<MarkerClustererInstance>({
   async create({ map }) {
     const { MarkerClusterer } = await import('@googlemaps/markerclusterer')
@@ -64,6 +72,9 @@ const markerClusterer = useGoogleMapsResource<MarkerClustererInstance>({
       ...props.options,
     } as any) as MarkerClustererInstance
     bindGoogleMapsEvents(clusterer, emit, { withPayload: markerClustererEvents })
+    clusterer.addListener('clusteringend', () => {
+      clusteringVersion.value++
+    })
     return clusterer
   },
   cleanup(clusterer, { mapsApi }) {
@@ -83,6 +94,11 @@ watch(
   (ready) => {
     if (!ready)
       return
+    // Guard: map projection must be ready, otherwise MarkerClusterer.render()
+    // throws "Cannot read properties of null (reading 'fromLatLngToDivPixel')"
+    // Keep rerenderPending true so the request isn't lost
+    if (!mapContext?.map.value?.getProjection())
+      return
     rerenderPending.value = false
     try {
       markerClusterer.value!.render()
@@ -100,6 +116,7 @@ provide(
   {
     markerClusterer,
     requestRerender,
+    clusteringVersion,
   },
 )
 </script>

src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { inject, useTemplateRef, watch } from 'vue'
 import { ADVANCED_MARKER_ELEMENT_INJECTION_KEY, MARKER_INJECTION_KEY } from './injectionKeys'
+import { MARKER_CLUSTERER_INJECTION_KEY } from './ScriptGoogleMapsMarkerClusterer.vue'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 type OverlayAnchor = 'center' | 'top-left' | 'top-center' | 'top-right'
@@ -40,16 +41,31 @@ const props = withDefaults(defineProps<{
    * @default true
    */
   blockMapInteraction?: boolean
+  /**
+   * Pan the map so the overlay is fully visible when opened, similar to InfoWindow behavior.
+   * Set to `true` for default 40px padding, or a number for custom padding.
+   * @default true
+   */
+  panOnOpen?: boolean | number
+  /**
+   * Automatically hide the overlay when its parent marker joins a cluster (on zoom out).
+   * Only applies when nested inside a ScriptGoogleMapsMarkerClusterer.
+   * @default true
+   */
+  hideWhenClustered?: boolean
 }>(), {
   anchor: 'bottom-center',
   pane: 'floatPane',
   blockMapInteraction: true,
+  panOnOpen: true,
+  hideWhenClustered: true,
 })
 
 const open = defineModel<boolean>('open', { default: undefined })
 
 const markerContext = inject(MARKER_INJECTION_KEY, undefined)
 const advancedMarkerElementContext = inject(ADVANCED_MARKER_ELEMENT_INJECTION_KEY, undefined)
+const markerClustererContext = inject(MARKER_CLUSTERER_INJECTION_KEY, undefined)
 
 // Read position fresh each call — NOT a computed, because Google Maps object
 // internal state (marker.getPosition()) is invisible to Vue's reactivity.
@@ -91,6 +107,26 @@ const overlayContent = useTemplateRef('overlay-content')
 // Track all event listeners for clean teardown
 const listeners: google.maps.MapsEventListener[] = []
 
+function panMapToFitOverlay(el: HTMLElement, map: google.maps.Map, padding: number) {
+  const child = el.firstElementChild
+  if (!child)
+    return
+  const overlayRect = child.getBoundingClientRect()
+  const mapRect = map.getDiv().getBoundingClientRect()
+  let panX = 0
+  let panY = 0
+  if (overlayRect.top - padding < mapRect.top)
+    panY = overlayRect.top - mapRect.top - padding
+  if (overlayRect.bottom + padding > mapRect.bottom)
+    panY = overlayRect.bottom - mapRect.bottom + padding
+  if (overlayRect.left - padding < mapRect.left)
+    panX = overlayRect.left - mapRect.left - padding
+  else if (overlayRect.right + padding > mapRect.right)
+    panX = overlayRect.right - mapRect.right + padding
+  if (panX !== 0 || panY !== 0)
+    map.panBy(panX, panY)
+}
+
 const overlay = useGoogleMapsResource<google.maps.OverlayView>({
   // ready condition accesses .value on ShallowRefs — tracked by whenever() in useGoogleMapsResource
   ready: () => !!overlayContent.value
@@ -106,6 +142,13 @@ const overlay = useGoogleMapsResource<google.maps.OverlayView>({
           if (props.blockMapInteraction)
             mapsApi.OverlayView.preventMapHitsAndGesturesFrom(el)
         }
+        if (props.panOnOpen) {
+          // Wait for draw() to position the element, then pan
+          const padding = typeof props.panOnOpen === 'number' ? props.panOnOpen : 40
+          requestAnimationFrame(() => {
+            panMapToFitOverlay(el, map, padding)
+          })
+        }
       }
 
       override draw() {
@@ -217,6 +260,29 @@ watch([() => props.pane, () => props.blockMapInteraction], () => {
   }
 })
 
+// Auto-hide overlay when its parent marker joins a cluster
+if (markerClustererContext && (markerContext || advancedMarkerElementContext)) {
+  watch(
+    () => markerClustererContext.clusteringVersion.value,
+    () => {
+      if (!props.hideWhenClustered || open.value === false)
+        return
+      const clusterer = markerClustererContext.markerClusterer.value as any
+      if (!clusterer?.clusters)
+        return
+      const parentMarker = advancedMarkerElementContext?.advancedMarkerElement.value
+        ?? markerContext?.marker.value
+      if (!parentMarker)
+        return
+      const isClustered = clusterer.clusters.some(
+        (cluster: any) => cluster.count > 1 && cluster.markers?.includes(parentMarker),
+      )
+      if (isClustered)
+        open.value = false
+    },
+  )
+}
+
 defineExpose({ overlay })
 </script>