From 8b6cf5586f6f0194135a3c31a095a5c4c547d48f Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 10 Apr 2026 00:49:01 +1000
Subject: [PATCH] refactor(google-maps)!: OverlayView class extraction and
 reactive position rendering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Internal restructure of <ScriptGoogleMapsOverlayView> with one
behaviour-visible side effect (DOM structure change).

Highlights:

- Reactive position. Position updates from `draw()` write to a
  `overlayPosition` shallowRef that the template binds via `:style` on
  the anchor element. Vue's patcher updates the moved DOM node, so
  imperative `el.style.left/top/visibility/...` writes are gone. The
  `data-state` attribute is also a reactive template binding now,
  removing the imperative `setDataState` helper that previously
  propagated state to both the wrapper and its first child.
- Anchor + content split. The overlay renders a two-element structure:
  the anchor div (positioned, moved into a Google Maps pane) wraps the
  content div (carries `data-state` + forwarded `class`/attrs + the
  slot). This is the DOM-level breaking change; consumers that target
  `[data-state]` on the slot's first child should move that class to
  the OverlayView component itself.
- Class factory. The `CustomOverlay extends mapsApi.OverlayView`
  declaration is lifted out of `useGoogleMapsResource`'s `create()`
  callback into a `makeOverlayClass(mapsApi, map)` factory at script
  setup top level, so the `create()` callback is just wiring.
- Playground demo update. `overlay-animated.vue` moves the
  `.overlay-popup` class from a slot child div onto the
  `<ScriptGoogleMapsOverlayView>` itself and uses `:deep()` in scoped
  styles to reach the now-internal content element.

Tests:

Five new mount-based tests in google-maps-overlay-view.nuxt.test.ts
covering the anchor → content → slot DOM hierarchy, the projected
pixel position landing on the anchor's inline style, the reactive
visibility transition when the controlled `open` prop flips to false,
the anchor staying in the DOM during the close path (so CSS
animations targeting `[data-state="closed"]` can run), and data-state
exposure on the content div for CSS targeting.

All v1 protected behaviours remain green:

- skip-if-equal setCenter watcher
- map.setOptions exclusion of zoom/center
- defineModel('open', { default: undefined })
- data-state="open"/"closed" toggling
- InfoWindow group close

100/100 google-maps-* tests pass; lint and typecheck clean.
---
 .../docs/4.migration-guide/1.v0-to-v1.md      |  25 +++
 .../ScriptGoogleMapsOverlayView.vue           | 200 ++++++++++--------
 .../google-maps/overlay-animated.vue          |  55 ++---
 .../google-maps-overlay-view.nuxt.test.ts     | 106 ++++++++++
 4 files changed, 269 insertions(+), 117 deletions(-)

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
index a4d0f404..5e49c411 100644
--- 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
index e1e79147..113f8420 100644
--- 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
index b9f1db21..e978a96b 100644
--- a/playground/pages/third-parties/google-maps/overlay-animated.vue
+++ b/playground/pages/third-parties/google-maps/overlay-animated.vue
@@ -45,33 +45,32 @@ 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>
@@ -79,7 +78,13 @@ function close(id: number) {
 </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;
@@ -87,11 +92,11 @@ function close(id: number) {
   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
index 830bdba7..e8212436 100644
--- a/test/nuxt-runtime/google-maps-overlay-view.nuxt.test.ts
+++ b/test/nuxt-runtime/google-maps-overlay-view.nuxt.test.ts
@@ -241,4 +241,110 @@ describe('scriptGoogleMapsOverlayView', () => {
       expect(mocks.mockMapsApi.LatLng).toHaveBeenCalledWith(33.8688, 151.2093)
     })
   })
+
+  describe('reactive position rendering (PR E refactor)', () => {
+    // Guards the migration from imperative `el.style.left/top` writes to a
+    // reactive `overlayPosition` shallowRef bound through Vue's `:style`
+    // patcher. The behaviours below are what consumers actually rely on:
+    //   1. The DOM has an anchor → content → slot structure
+    //   2. The anchor's inline style reflects the projected pixel position
+    //   3. data-state on the content div toggles via Vue reactivity, not
+    //      imperative dataset writes
+
+    function getOverlayElements(overlayWrapper: any) {
+      const anchor = overlayWrapper.vm.$refs['overlay-anchor'] as HTMLElement
+      const content = anchor.firstElementChild as HTMLElement
+      return { anchor, content }
+    }
+
+    it('renders the anchor → content → slot DOM structure', async () => {
+      const { overlayWrapper } = await mountOverlay({ position: { lat: 10, lng: 20 } })
+
+      // Anchor wraps the content; content wraps the slot. The hierarchy is
+      // load-bearing because Google Maps reparents the anchor into a pane on
+      // `onAdd()` while the content stays as the styling target for users.
+      const { anchor, content } = getOverlayElements(overlayWrapper)
+      expect(anchor).toBeTruthy()
+      expect(content).toBeTruthy()
+      expect(anchor.firstElementChild).toBe(content)
+      // The slot's first child must be a descendant of the content div
+      expect(content.firstElementChild).toBeTruthy()
+    })
+
+    it('writes the projected pixel position to the anchor inline style', async () => {
+      const { overlayWrapper } = await mountOverlay({
+        position: { lat: 10, lng: 20 },
+        offset: { x: 5, y: -10 },
+      })
+
+      const { anchor } = getOverlayElements(overlayWrapper)
+      // Mock projection returns { x: 100, y: 200 }; offset adds 5/-10
+      expect(anchor.style.left).toBe('105px')
+      expect(anchor.style.top).toBe('190px')
+      expect(anchor.style.position).toBe('absolute')
+      expect(anchor.style.visibility).toBe('visible')
+    })
+
+    it('reactively updates anchor visibility when open prop toggles to false', async () => {
+      const mocks = createOverlayMocks()
+      const Provider = createMapProvider(mocks)
+      const openState = shallowRef<boolean | undefined>(true)
+
+      const wrapper = await mountSuspended(Provider, {
+        slots: {
+          default: () => h(
+            ScriptGoogleMapsOverlayView,
+            {
+              'position': { lat: 10, lng: 20 },
+              'open': openState.value,
+              'onUpdate:open': (v: boolean) => { openState.value = v },
+            },
+            () => h('div'),
+          ),
+        },
+      })
+      await nextTick()
+      await nextTick()
+      await nextTick()
+
+      const overlayWrapper = wrapper.findComponent(ScriptGoogleMapsOverlayView)
+      const { anchor } = getOverlayElements(overlayWrapper)
+
+      // Initially open
+      expect((overlayWrapper.vm as any).dataState).toBe('open')
+      expect(anchor.style.visibility).toBe('visible')
+
+      // Toggle controlled `open` to false; the reactive style binding should
+      // patch visibility:hidden without any imperative DOM write.
+      openState.value = false
+      await wrapper.setProps({}) // re-render to flush the prop change
+      await nextTick()
+      await nextTick()
+
+      expect((overlayWrapper.vm as any).dataState).toBe('closed')
+      expect(anchor.style.visibility).toBe('hidden')
+    })
+
+    it('keeps the anchor element in the DOM when overlay closes (animation-friendly)', async () => {
+      const { overlayWrapper } = await mountOverlay({
+        position: { lat: 10, lng: 20 },
+        defaultOpen: false,
+      })
+
+      const { anchor, content } = getOverlayElements(overlayWrapper)
+      // Element exists in DOM (even when closed); CSS animations targeting
+      // [data-state="closed"] need the element present to run.
+      expect(anchor).toBeTruthy()
+      expect(anchor.style.visibility).toBe('hidden')
+      // The data-state attribute is on the content child, not the anchor
+      expect(content.dataset.state).toBe('closed')
+    })
+
+    it('exposes data-state on the content div for CSS targeting', async () => {
+      const { overlayWrapper } = await mountOverlay({ position: { lat: 10, lng: 20 } })
+
+      const { content } = getOverlayElements(overlayWrapper)
+      expect(content.dataset.state).toBe('open')
+    })
+  })
 })