diff --git a/docs/content/scripts/google-maps.md b/docs/content/scripts/google-maps.md index 93cf292c5..96cf9f14c 100644 --- a/docs/content/scripts/google-maps.md +++ b/docs/content/scripts/google-maps.md @@ -521,160 +521,35 @@ onMounted(() => { ``` -**See the [SFC Playground Example](https://nuxt-scripts-playground.stackblitz.io/third-parties/google-maps/sfcs) for a complete demonstration.** +### Component Hierarchy -### Component Details - -#### ScriptGoogleMapsMarker - -Classic Google Maps marker with icon support. - -**Props:** -- `options` - `google.maps.MarkerOptions` (excluding `map`) - -**Events:** -- Standard marker events: `click`, `mousedown`, `mouseover`, etc. - -#### ScriptGoogleMapsAdvancedMarkerElement - -Modern advanced markers that support HTML content and better customization. - -**Props:** -- `options` - `google.maps.marker.AdvancedMarkerElementOptions` (excluding `map`) - -**Events:** -- Standard marker events: `click`, `drag`, `position_changed`, etc. - -#### ScriptGoogleMapsInfoWindow - -Information windows that display content when triggered. - -**Props:** -- `options` - `google.maps.InfoWindowOptions` - -**Behavior:** -- Automatically opens on parent marker click -- You can use it standalone with an explicit position -- Supports custom HTML content via default slot - -#### ScriptGoogleMapsMarkerClusterer - -Groups nearby markers into clusters for better performance and UX. - -**Props:** -- `options` - `MarkerClustererOptions` (excluding `map`) - -**Dependencies:** -- Requires `@googlemaps/markerclusterer` peer dependency - -#### Other Components - -- **ScriptGoogleMapsPinElement**: Use within AdvancedMarkerElement for customizable pins -- **ScriptGoogleMapsCircle**: Circular overlays with radius and styling -- **ScriptGoogleMapsPolygon/Polyline**: Shape and line overlays -- **ScriptGoogleMapsRectangle**: Rectangular overlays -- **ScriptGoogleMapsHeatmapLayer**: Data visualization with heatmaps - -All components support: -- Reactive `options` prop that updates the basic Google Maps object -- Automatic cleanup on component unmount -- TypeScript support with Google Maps types - -### Best Practices - -#### Performance Considerations - -**Use MarkerClusterer for Many Markers** -```vue - - - - - - - -``` - -**Prefer AdvancedMarkerElement for Modern Apps** -```vue - - - - - - - -``` - -#### Component Hierarchy - -Follow this nesting structure for components: - -``` +```text ScriptGoogleMaps (root) ├── ScriptGoogleMapsMarkerClusterer (optional) -│ └── ScriptGoogleMapsMarker/AdvancedMarkerElement +│ └── ScriptGoogleMapsMarker / ScriptGoogleMapsAdvancedMarkerElement │ └── ScriptGoogleMapsInfoWindow (optional) ├── ScriptGoogleMapsAdvancedMarkerElement │ ├── ScriptGoogleMapsPinElement (optional) │ └── ScriptGoogleMapsInfoWindow (optional) -└── Other overlays (Circle, Polygon, etc.) +└── ScriptGoogleMapsCircle / Polygon / Polyline / Rectangle / HeatmapLayer ``` -#### Reactive Data Patterns - -**Reactive Marker Updates** -```vue - - - -``` - -#### Error Handling - -Always provide error fallbacks and loading states: - -```vue - - - -``` +All SFC components accept an `options` prop matching their Google Maps API options type (excluding `map`, which is injected automatically). Options are reactive - changes update the basic Google Maps object. Components clean up automatically on unmount. + +### Component Reference + +| Component | Options Type | Notes | +|---|---|---| +| `ScriptGoogleMapsMarker` | `google.maps.MarkerOptions` | Classic marker | +| `ScriptGoogleMapsAdvancedMarkerElement` | `google.maps.marker.AdvancedMarkerElementOptions` | Recommended | +| `ScriptGoogleMapsPinElement` | `google.maps.marker.PinElementOptions` | Child of AdvancedMarkerElement | +| `ScriptGoogleMapsInfoWindow` | `google.maps.InfoWindowOptions` | Auto-opens on parent marker click | +| `ScriptGoogleMapsMarkerClusterer` | `MarkerClustererOptions` | Requires `@googlemaps/markerclusterer` | +| `ScriptGoogleMapsCircle` | `google.maps.CircleOptions` | | +| `ScriptGoogleMapsPolygon` | `google.maps.PolygonOptions` | | +| `ScriptGoogleMapsPolyline` | `google.maps.PolylineOptions` | | +| `ScriptGoogleMapsRectangle` | `google.maps.RectangleOptions` | | +| `ScriptGoogleMapsHeatmapLayer` | `google.maps.visualization.HeatmapLayerOptions` | | ## [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps){lang="ts"} diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue index 1e865c6ff..e0d6cd902 100644 --- a/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue +++ b/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue @@ -2,7 +2,7 @@ /// import type { ElementScriptTrigger } from '#nuxt-scripts/types' import type { QueryObject } from 'ufo' -import type { HTMLAttributes, ImgHTMLAttributes, InjectionKey, Ref, ReservedProps, ShallowRef } from 'vue' +import type { HTMLAttributes, ImgHTMLAttributes, Ref, ReservedProps, ShallowRef } from 'vue' import { useScriptTriggerElement } from '#nuxt-scripts/composables/useScriptTriggerElement' import { useScriptGoogleMaps } from '#nuxt-scripts/registry/google-maps' import { scriptRuntimeConfig } from '#nuxt-scripts/utils' @@ -13,10 +13,9 @@ import { withQuery } from 'ufo' import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, watch } from 'vue' import ScriptAriaLoadingIndicator from '../ScriptAriaLoadingIndicator.vue' -export const MAP_INJECTION_KEY = Symbol('map') as InjectionKey<{ - map: ShallowRef - mapsApi: Ref -}> +import { MAP_INJECTION_KEY } from './injectionKeys' + +export { MAP_INJECTION_KEY } from './injectionKeys' diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue index 2aaa65c0d..499a0c2cc 100644 --- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue +++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue @@ -1,13 +1,10 @@ diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue index 63aa2e9af..163687d8d 100644 --- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue +++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue @@ -1,7 +1,6 @@ diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsHeatmapLayer.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsHeatmapLayer.vue index 58c35fb14..5903da59c 100644 --- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsHeatmapLayer.vue +++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsHeatmapLayer.vue @@ -1,37 +1,29 @@