Merge remote-tracking branch 'origin/main'

Author: harlan-zw

docs/content/scripts/google-maps/1.guides/6.marker-clustering.md

@@ -135,6 +135,36 @@ const locations = [
 </template>
 ```
 
+## Custom Cluster Renderer
+
+Use the `#renderer` slot on the clusterer to fully customize cluster visuals with Vue templates.
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="{ lat: -33.863, lng: 151.210 }" :zoom="13">
+    <ScriptGoogleMapsMarkerClusterer>
+      <template #renderer="{ cluster }">
+        <div
+          class="bg-blue-600 text-white rounded-full w-10 h-10 flex items-center justify-center font-bold text-sm shadow-lg"
+        >
+          {{ cluster.count }}
+        </div>
+      </template>
+
+      <ScriptGoogleMapsMarker
+        v-for="loc in locations"
+        :key="loc.id"
+        :position="loc.position"
+      >
+        <ScriptGoogleMapsInfoWindow>
+          <strong>{{ loc.name }}</strong>
+        </ScriptGoogleMapsInfoWindow>
+      </ScriptGoogleMapsMarker>
+    </ScriptGoogleMapsMarkerClusterer>
+  </ScriptGoogleMaps>
+</template>
+```
+
 ## Clustering with Custom Markers
 
 Custom HTML markers cluster the same way as default pins.

docs/content/scripts/google-maps/2.api/4.marker-clusterer.md

@@ -71,9 +71,9 @@ function addLocation(position: google.maps.LatLngLiteral) {
 </template>
 ```
 
-### Custom Algorithm & Renderer
+### Custom Algorithm
 
-Pass `algorithm` and `renderer` through `options` to customize clustering behavior. See the [`@googlemaps/markerclusterer` documentation](https://googlemaps.github.io/js-markerclusterer/) for available algorithms.
+Pass `algorithm` through `options` to customize clustering behavior. See the [`@googlemaps/markerclusterer` documentation](https://googlemaps.github.io/js-markerclusterer/) for available algorithms.
 
 ```vue
 <script setup lang="ts">
@@ -97,6 +97,44 @@ const clustererOptions = {
 </template>
 ```
 
+### Custom Cluster Renderer
+
+Use the `#renderer` slot to customize how clusters look using Vue templates. The slot receives `cluster` (with `count`, `position`, `markers`), `stats`, and `map` (the Google Maps instance).
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsMarkerClusterer>
+      <template #renderer="{ cluster }">
+        <div
+          style="
+            background: #4285f4;
+            color: white;
+            border-radius: 50%;
+            width: 40px;
+            height: 40px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-weight: bold;
+          "
+        >
+          {{ cluster.count }}
+        </div>
+      </template>
+
+      <ScriptGoogleMapsMarker
+        v-for="loc in locations"
+        :key="loc.id"
+        :position="loc.position"
+      />
+    </ScriptGoogleMapsMarkerClusterer>
+  </ScriptGoogleMaps>
+</template>
+```
+
+The `#renderer` slot overrides the `renderer` option. Each cluster gets its own `AdvancedMarkerElement` with the slot content as its visual.
+
 ::callout
 The clusterer only renders its default slot after the clusterer instance is ready. This prevents child markers from mounting before the clusterer can receive them.
 ::

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

@@ -1,6 +1,6 @@
 <script lang="ts">
 import type { InjectionKey, ShallowRef } from 'vue'
-import { inject, provide, shallowRef, watch } from 'vue'
+import { getCurrentInstance, h, inject, onBeforeUnmount, provide, shallowRef, useSlots, render as vueRender, watch } from 'vue'
 import { bindGoogleMapsEvents, MAP_INJECTION_KEY, useGoogleMapsResource } from './useGoogleMapsResource'
 
 // Inline types to avoid requiring @googlemaps/markerclusterer as a build-time dependency
@@ -19,6 +19,22 @@ export interface MarkerClustererOptions {
   onClusterClick?: unknown
 }
 
+export interface Cluster {
+  marker: google.maps.marker.AdvancedMarkerElement
+  markers?: google.maps.marker.AdvancedMarkerElement[]
+  position: google.maps.LatLng
+  bounds: google.maps.LatLngBounds | undefined
+  count: number
+}
+
+export interface ClusterStats {
+  markers: { sum: number }
+  clusters: {
+    count: number
+    markers: { min: number, max: number, mean: number, sum: number }
+  }
+}
+
 export interface MarkerClustererContext {
   markerClusterer: ShallowRef<MarkerClustererInstance | undefined>
   requestRerender: () => void
@@ -59,17 +75,64 @@ const markerClustererEvents = [
   'clusteringend',
 ] as const
 
+const slots = useSlots()
+const instance = getCurrentInstance()
 const mapContext = inject(MAP_INJECTION_KEY, undefined)
 const clusteringVersion = shallowRef(0)
 
+// Track containers for Vue-rendered cluster content so we can unmount them
+const renderedContainers: HTMLElement[] = []
+
+function cleanupRenderedClusters() {
+  for (const container of renderedContainers) {
+    vueRender(null, container)
+  }
+  renderedContainers.length = 0
+}
+
+onBeforeUnmount(cleanupRenderedClusters)
+
 const markerClusterer = useGoogleMapsResource<MarkerClustererInstance>({
-  async create({ map }) {
+  async create({ map, mapsApi }) {
     const { MarkerClusterer } = await import('@googlemaps/markerclusterer')
+
+    // Pre-load marker library so the synchronous renderer can use AdvancedMarkerElement
+    if (slots.renderer) {
+      await mapsApi.importLibrary('marker')
+    }
+
     const clusterer = new MarkerClusterer({
       map,
       ...props.options,
+      ...(slots.renderer
+        ? {
+            renderer: {
+              render(cluster: Cluster, stats: ClusterStats) {
+                const container = document.createElement('div')
+                const vnode = h({
+                  render: () => slots.renderer?.({ cluster, stats, map }),
+                })
+                if (instance) {
+                  vnode.appContext = instance.appContext
+                }
+                vueRender(vnode, container)
+                renderedContainers.push(container)
+
+                const marker = new mapsApi.marker.AdvancedMarkerElement({
+                  position: cluster.position,
+                  content: container.firstElementChild as HTMLElement || container,
+                })
+                return marker
+              },
+            },
+          }
+        : {}),
     } as any) as MarkerClustererInstance
+
     bindGoogleMapsEvents(clusterer, emit, { withPayload: markerClustererEvents })
+    clusterer.addListener('clusteringbegin', () => {
+      cleanupRenderedClusters()
+    })
     clusterer.addListener('clusteringend', () => {
       clusteringVersion.value++
     })
@@ -78,6 +141,7 @@ const markerClusterer = useGoogleMapsResource<MarkerClustererInstance>({
   cleanup(clusterer, { mapsApi }) {
     mapsApi.event.clearInstanceListeners(clusterer)
     clusterer.setMap(null)
+    cleanupRenderedClusters()
   },
 })
 

test/unit/google-maps-components.test.ts

@@ -228,6 +228,78 @@ describe('google Maps SFC Components Logic', () => {
     })
   })
 
+  describe('marker Clusterer #renderer Slot', () => {
+    it('should create clusterer with custom renderer when #renderer slot is provided', async () => {
+      const { MarkerClusterer } = await import('@googlemaps/markerclusterer')
+
+      // Simulate what the component does when #content slot exists
+      const mockMap = {}
+      const rendererFn = vi.fn((_cluster: any, _stats: any) => {
+        const container = document.createElement('div')
+        container.innerHTML = '<span>5</span>'
+        return container
+      })
+
+      const renderer = {
+        render(cluster: any, stats: any) {
+          const content = rendererFn(cluster, stats)
+          const marker = new mocks.mockMapsApi.marker.AdvancedMarkerElement({
+            position: cluster.position,
+            content,
+          })
+          return marker
+        },
+      }
+
+      // eslint-disable-next-line no-new
+      new MarkerClusterer({
+        map: mockMap,
+        renderer,
+      })
+
+      expect(MarkerClusterer).toHaveBeenCalledWith(
+        expect.objectContaining({ renderer }),
+      )
+
+      // Simulate a cluster render call
+      const cluster = { position: { lat: 1, lng: 2 }, count: 5, markers: [] }
+      const stats = { clusters: [], markers: [] }
+      const marker = renderer.render(cluster, stats)
+
+      expect(rendererFn).toHaveBeenCalledWith(cluster, stats)
+      expect(mocks.mockMapsApi.marker.AdvancedMarkerElement).toHaveBeenCalledWith(
+        expect.objectContaining({ position: cluster.position }),
+      )
+      expect(marker).toBeDefined()
+    })
+
+    it('should pre-load marker library when #renderer slot is used', async () => {
+      // Simulate the pre-loading that happens when slots.content exists
+      await mocks.mockMapsApi.importLibrary('marker')
+
+      expect(mocks.mockMapsApi.importLibrary).toHaveBeenCalledWith('marker')
+    })
+
+    it('should clean up rendered containers on clusteringbegin', () => {
+      // Simulate the cleanup pattern used in the component
+      const containers: HTMLElement[] = []
+
+      // Create some containers (as would happen during render)
+      for (let i = 0; i < 3; i++) {
+        const container = document.createElement('div')
+        container.innerHTML = `<span>${i}</span>`
+        containers.push(container)
+      }
+
+      expect(containers).toHaveLength(3)
+
+      // Simulate clusteringbegin cleanup
+      containers.length = 0
+
+      expect(containers).toHaveLength(0)
+    })
+  })
+
   describe('google Maps API Types and Integration', () => {
     it('should work with LatLng objects', () => {
       const lat = -33.8688