refactor(google-maps)!: OverlayView class extraction and reactive position rendering (#697)

harlan-zw · web-flow · commit c33473c16e70 · 2026-04-10T01:07:22.000+10:00
diff --git a/docs/content/docs/4.migration-guide/1.v0-to-v1.md b/docs/content/docs/4.migration-guide/1.v0-to-v1.md
@@ -414,6 +414,31 @@ The same rename applies to `<ScriptGoogleMapsOverlayView>`{lang="html"}: its exp
  })
 ```
 
+#### `<ScriptGoogleMapsOverlayView>`{lang="html"} DOM Structure
+
+The overlay view now renders an extra wrapper element. The structure is `anchor div → content div → slot`, where the anchor handles positioning (Google Maps reparents it into a pane on mount) and the content div carries `data-state` plus any forwarded `class`/attrs.
+
+CSS that targets `[data-state="open"]` on the slot's root element should move to a class on the `<ScriptGoogleMapsOverlayView>`{lang="html"} itself, since the data-state attribute now lives on the internal content div rather than propagating into the slot's first child.
+
+```diff
+ <template>
+-  <ScriptGoogleMapsOverlayView v-model:open="open">
+-    <div class="overlay-popup">
+-      ...
+-    </div>
+-  </ScriptGoogleMapsOverlayView>
++  <ScriptGoogleMapsOverlayView class="overlay-popup" v-model:open="open">
++    ...
++  </ScriptGoogleMapsOverlayView>
+ </template>
+
+ <style scoped>
+-.overlay-popup[data-state="open"] { animation: ... }
++/* Use :deep() in scoped styles since the class lands on a child component's element */
++:deep(.overlay-popup[data-state="open"]) { animation: ... }
+ </style>
+```
+
 ### Google Maps Static Placeholder ([#673](https://github.com/nuxt/scripts/pull/673))
 
 v1 extracts the built-in static map placeholder into a standalone [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) component. This removes the following props from `<ScriptGoogleMaps>`{lang="html"}:
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
@@ -90,7 +90,7 @@ export interface ScriptGoogleMapsOverlayViewExpose {
 </script>
 
 <script setup lang="ts">
-import { computed, inject, ref, useTemplateRef, watch } from 'vue'
+import { computed, inject, shallowRef, useTemplateRef, watch } from 'vue'
 import { MARKER_CLUSTERER_INJECTION_KEY } from './types'
 import { defineDeprecatedAlias, MARKER_INJECTION_KEY, normalizeLatLng, useGoogleMapsResource } from './useGoogleMapsResource'
 
@@ -159,30 +159,45 @@ const ANCHOR_TRANSFORMS: Record<ScriptGoogleMapsOverlayAnchor, string> = {
   'right-center': 'translate(-100%, -50%)',
 }
 
-const overlayContent = useTemplateRef('overlay-content')
+const overlayAnchor = useTemplateRef('overlay-anchor')
 
-// Reactive open/closed state for CSS animations via data-state attribute.
-// Tracks whether the overlay content is positioned and should be visually open.
-const isPositioned = ref(false)
-const dataState = computed(() => isPositioned.value ? 'open' : 'closed')
+// Reactive pixel position written by `draw()`. The template style binding
+// on the anchor element reads it, so position updates flow through Vue's
+// reactivity instead of imperative `el.style.left/top` writes.
+const overlayPosition = shallowRef<{ x: number, y: number } | undefined>(undefined)
 
-// Track all event listeners for clean teardown
-const listeners: google.maps.MapsEventListener[] = []
+// `dataState` reflects the visible/hidden state of the overlay. It is bound
+// directly on the content element so CSS animations targeting `[data-state]`
+// react without any imperative DOM writes.
+const dataState = computed<'open' | 'closed'>(() =>
+  open.value !== false && overlayPosition.value !== undefined ? 'open' : 'closed',
+)
 
-function setDataState(el: HTMLElement, state: 'open' | 'closed') {
-  el.dataset.state = state
-  // Propagate to the slot's root element imperatively (Vue template bindings
-  // don't reliably patch elements that have been moved to Google Maps panes)
-  const child = el.firstElementChild as HTMLElement | null
-  if (child)
-    child.dataset.state = state
-}
+// Computed style for the anchor element. Vue patches the moved DOM node via
+// this binding even after Google Maps has reparented it into a pane.
+const overlayStyle = computed<Record<string, string | undefined>>(() => {
+  const visible = open.value !== false && overlayPosition.value !== undefined
+  if (!visible) {
+    return {
+      position: 'absolute',
+      visibility: 'hidden',
+      pointerEvents: 'none',
+    }
+  }
+  const { x, y } = overlayPosition.value!
+  return {
+    position: 'absolute',
+    left: `${x + (offset?.x ?? 0)}px`,
+    top: `${y + (offset?.y ?? 0)}px`,
+    transform: ANCHOR_TRANSFORMS[anchor],
+    zIndex: zIndex !== undefined ? String(zIndex) : undefined,
+    visibility: 'visible',
+    pointerEvents: 'auto',
+  }
+})
 
-function hideElement(el: HTMLElement) {
-  el.style.visibility = 'hidden'
-  el.style.pointerEvents = 'none'
-  setDataState(el, 'closed')
-}
+// 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
@@ -204,87 +219,76 @@ function panMapToFitOverlay(el: HTMLElement, map: google.maps.Map, padding: numb
     map.panBy(panX, panY)
 }
 
-const overlay = useGoogleMapsResource<google.maps.OverlayView>({
-  // ready condition accesses .value on ShallowRefs — tracked by whenever() in useGoogleMapsResource
-  ready: () => !!overlayContent.value
-    && !!(position || markerContext?.advancedMarkerElement.value),
-  create({ mapsApi, map }) {
-    const el = overlayContent.value!
-
-    class CustomOverlay extends mapsApi.OverlayView {
-      override onAdd() {
-        const panes = this.getPanes()
-        if (panes) {
-          panes[pane].appendChild(el)
-          if (blockMapInteraction)
-            mapsApi.OverlayView.preventMapHitsAndGesturesFrom(el)
-        }
-        if (panOnOpen) {
-          // Wait for draw() to position the element, then pan
-          const padding = typeof panOnOpen === 'number' ? panOnOpen : 40
-          requestAnimationFrame(() => {
-            panMapToFitOverlay(el, map, padding)
-          })
-        }
+// Factory that builds the OverlayView subclass. Lifted out of `create()`
+// so the create callback stays focused on wiring (instantiation, listeners).
+// The class still has to extend `mapsApi.OverlayView`, which is only
+// available after the script loads, so this stays a function rather than
+// a top-level class declaration.
+function makeOverlayClass(mapsApi: typeof google.maps, map: google.maps.Map) {
+  return class CustomOverlay extends mapsApi.OverlayView {
+    override onAdd() {
+      const panes = this.getPanes()
+      const el = overlayAnchor.value
+      if (panes && el) {
+        panes[pane].appendChild(el)
+        if (blockMapInteraction)
+          mapsApi.OverlayView.preventMapHitsAndGesturesFrom(el)
       }
-
-      override draw() {
-        // v-model:open support: hide when explicitly closed
-        if (open.value === false) {
-          isPositioned.value = false
-          hideElement(el)
-          return
-        }
-
-        const resolvedPosition = getResolvedPosition()
-        if (!resolvedPosition) {
-          isPositioned.value = false
-          hideElement(el)
-          return
-        }
-        const projection = this.getProjection()
-        if (!projection) {
-          isPositioned.value = false
-          hideElement(el)
-          return
-        }
-        const pos = projection.fromLatLngToDivPixel(
-          new mapsApi.LatLng(resolvedPosition.lat, resolvedPosition.lng),
-        )
-        if (!pos) {
-          isPositioned.value = false
-          hideElement(el)
-          return
-        }
-
-        el.style.position = 'absolute'
-        el.style.left = `${pos.x + (offset?.x ?? 0)}px`
-        el.style.top = `${pos.y + (offset?.y ?? 0)}px`
-        el.style.transform = ANCHOR_TRANSFORMS[anchor]
-        if (zIndex !== undefined)
-          el.style.zIndex = String(zIndex)
-        el.style.visibility = 'visible'
-        el.style.pointerEvents = 'auto'
-        setDataState(el, 'open')
-        isPositioned.value = true
+      if (panOnOpen) {
+        // Wait for draw() to position the element, then pan
+        const padding = typeof panOnOpen === 'number' ? panOnOpen : 40
+        requestAnimationFrame(() => {
+          if (overlayAnchor.value)
+            panMapToFitOverlay(overlayAnchor.value, map, padding)
+        })
       }
+    }
 
-      override onRemove() {
-        el.parentNode?.removeChild(el)
+    override draw() {
+      if (open.value === false) {
+        overlayPosition.value = undefined
+        return
+      }
+      const resolvedPosition = getResolvedPosition()
+      if (!resolvedPosition) {
+        overlayPosition.value = undefined
+        return
+      }
+      const projection = this.getProjection()
+      if (!projection) {
+        overlayPosition.value = undefined
+        return
+      }
+      const pos = projection.fromLatLngToDivPixel(
+        new mapsApi.LatLng(resolvedPosition.lat, resolvedPosition.lng),
+      )
+      if (!pos) {
+        overlayPosition.value = undefined
+        return
       }
+      overlayPosition.value = { x: pos.x, y: pos.y }
     }
 
-    // Prevent flash: hide until first draw() positions content
-    el.style.visibility = 'hidden'
-    el.style.pointerEvents = 'none'
+    override onRemove() {
+      const el = overlayAnchor.value
+      el?.parentNode?.removeChild(el)
+    }
+  }
+}
 
+const overlay = useGoogleMapsResource<google.maps.OverlayView>({
+  // ready condition accesses .value on ShallowRefs — tracked by whenever() in useGoogleMapsResource
+  ready: () => !!overlayAnchor.value
+    && !!(position || markerContext?.advancedMarkerElement.value),
+  create({ mapsApi, map }) {
+    const CustomOverlay = makeOverlayClass(mapsApi, map)
     const ov = new CustomOverlay()
     ov.setMap(map)
 
-    // Follow parent marker position changes
+    // Follow parent marker position changes. AdvancedMarkerElement fires
+    // `drag` continuously during drag, so the overlay tracks live.
     if (markerContext?.advancedMarkerElement.value) {
       const ame = markerContext.advancedMarkerElement.value
-      // AdvancedMarkerElement fires drag continuously during drag
       listeners.push(
         ame.addListener('drag', () => ov.draw()),
         ame.addListener('dragend', () => ov.draw()),
@@ -386,8 +390,20 @@ defineExpose<ScriptGoogleMapsOverlayViewExpose>(exposed)
 
 <template>
   <div style="display: none;">
-    <div ref="overlay-content" :data-state="dataState" v-bind="$attrs">
-      <slot />
+    <!--
+      Two-element structure:
+        - `overlay-anchor` is moved into a Google Maps pane on `onAdd()`. Its
+          inline style is reactively bound to `overlayStyle`, so position
+          updates from `draw()` flow through Vue's patcher even after the node
+          has been reparented out of the component tree.
+        - `overlay-content` carries `data-state`, attribute-based animations,
+          and forwards parent attrs (e.g. `class`) so consumers can target it
+          directly with `[data-state]` selectors.
+    -->
+    <div ref="overlay-anchor" :style="overlayStyle">
+      <div :data-state="dataState" v-bind="$attrs">
+        <slot />
+      </div>
     </div>
   </div>
 </template>
diff --git a/playground/pages/third-parties/google-maps/overlay-animated.vue b/playground/pages/third-parties/google-maps/overlay-animated.vue
@@ -45,53 +45,58 @@ function close(id: number) {
         @click="toggle(place.id)"
       >
         <ScriptGoogleMapsOverlayView
+          class="overlay-popup"
           :open="isOpen(place.id)"
           anchor="bottom-center"
           :offset="{ x: 0, y: -50 }"
           @update:open="(v: boolean) => { if (!v) close(place.id) }"
         >
-            <div class="overlay-popup">
-              <div class="flex items-start justify-between gap-2">
-                <h3 class="text-sm font-semibold text-gray-900">
-                  {{ place.name }}
-                </h3>
-                <button
-                  class="shrink-0 rounded-full p-0.5 text-gray-400 hover:bg-gray-100 hover:text-gray-600"
-                  @click.stop="close(place.id)"
-                >
-                  <svg xmlns="http://www.w3.org/2000/svg" class="size-4" viewBox="0 0 20 20" fill="currentColor">
-                    <path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd" />
-                  </svg>
-                </button>
-              </div>
-              <div class="mt-1 flex items-center gap-1 text-xs text-gray-500">
-                <span class="font-medium text-yellow-500">★ {{ place.rating }}</span>
-                <span>({{ place.reviews }} reviews)</span>
-              </div>
-              <p class="mt-2 text-xs leading-relaxed text-gray-600">
-                {{ place.desc }}
-              </p>
-            </div>
+          <div class="flex items-start justify-between gap-2">
+            <h3 class="text-sm font-semibold text-gray-900">
+              {{ place.name }}
+            </h3>
+            <button
+              class="shrink-0 rounded-full p-0.5 text-gray-400 hover:bg-gray-100 hover:text-gray-600"
+              @click.stop="close(place.id)"
+            >
+              <svg xmlns="http://www.w3.org/2000/svg" class="size-4" viewBox="0 0 20 20" fill="currentColor">
+                <path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd" />
+              </svg>
+            </button>
+          </div>
+          <div class="mt-1 flex items-center gap-1 text-xs text-gray-500">
+            <span class="font-medium text-yellow-500">★ {{ place.rating }}</span>
+            <span>({{ place.reviews }} reviews)</span>
+          </div>
+          <p class="mt-2 text-xs leading-relaxed text-gray-600">
+            {{ place.desc }}
+          </p>
         </ScriptGoogleMapsOverlayView>
       </ScriptGoogleMapsMarker>
     </ScriptGoogleMaps>
   </div>
 </template>
 
 <style scoped>
-.overlay-popup {
+/*
+ * `.overlay-popup` is forwarded onto the OverlayView's internal content div
+ * (via `v-bind="$attrs"`). Scoped styles need `:deep()` to reach across the
+ * component boundary, since the rendered element belongs to the
+ * `<ScriptGoogleMapsOverlayView>` component, not this page.
+ */
+:deep(.overlay-popup) {
   width: 16rem;
   border-radius: 0.75rem;
   background: white;
   padding: 1rem;
   box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
 }
 
-.overlay-popup[data-state="open"] {
+:deep(.overlay-popup[data-state="open"]) {
   animation: overlayIn 200ms ease-out forwards;
 }
 
-.overlay-popup[data-state="closed"] {
+:deep(.overlay-popup[data-state="closed"]) {
   animation: overlayOut 150ms ease-in forwards;
 }
 
diff --git a/test/nuxt-runtime/google-maps-overlay-view.nuxt.test.ts b/test/nuxt-runtime/google-maps-overlay-view.nuxt.test.ts
