feat(google-maps): add advanced marker (#28525)

* feat(google-maps): add advanced marker

This commit introduces the advanced-marker feature to the map package, enabling users to add custom, interactive markers to their maps.

Related #25897

* feat(google-maps): remove default value for mapId and correct z-index description property for advanced markers

* feat(google-maps): generate api report file for google-maps

Author: OgiSss

src/dev-app/google-map/google-map-demo.html

@@ -20,6 +20,13 @@
             (mapClick)="clickMarker(marker)"></map-marker>
         }
       </map-marker-clusterer>
+      <map-advanced-marker
+        #secondMarker="mapAdvancedMarker"
+        (mapClick)="clickAdvancedMarker(secondMarker)"
+        title="Advanced Marker"
+        [gmpDraggable]="false"
+        [position]="mapAdvancedMarkerPosition"
+      ></map-advanced-marker>
       <map-info-window>Testing 1 2 3</map-info-window>
       @if (isPolylineDisplayed) {
         <map-polyline [options]="polylineOptions"></map-polyline>

src/dev-app/google-map/google-map-demo.ts

@@ -25,6 +25,7 @@ import {
   MapRectangle,
   MapTrafficLayer,
   MapTransitLayer,
+  MapAdvancedMarker,
 } from '@angular/google-maps';
 
 const POLYLINE_PATH: google.maps.LatLngLiteral[] = [
@@ -72,6 +73,7 @@ let apiLoadingPromise: Promise<unknown> | null = null;
     MapKmlLayer,
     MapMarker,
     MapMarkerClusterer,
+    MapAdvancedMarker,
     MapPolygon,
     MapPolyline,
     MapRectangle,
@@ -87,6 +89,7 @@ export class GoogleMapDemo {
   @ViewChild(MapCircle) circle: MapCircle;
 
   center = {lat: 24, lng: 12};
+  mapAdvancedMarkerPosition = {lat: 24, lng: 16};
   markerOptions = {draggable: false};
   markerPositions: google.maps.LatLngLiteral[] = [];
   zoom = 4;
@@ -173,6 +176,13 @@ export class GoogleMapDemo {
     this.infoWindow.open(marker);
   }
 
+  clickAdvancedMarker(advancedMarker: MapAdvancedMarker) {
+    this.infoWindow.openAdvancedMarkerElement(
+      advancedMarker.advancedMarker,
+      advancedMarker.advancedMarker.title,
+    );
+  }
+
   handleRightclick() {
     this.markerPositions.pop();
   }

src/google-maps/google-map/google-map.spec.ts

@@ -114,7 +114,11 @@ describe('GoogleMap', () => {
   });
 
   it('sets center and zoom of the map', () => {
-    const options = {center: {lat: 3, lng: 5}, zoom: 7, mapTypeId: DEFAULT_OPTIONS.mapTypeId};
+    const options = {
+      center: {lat: 3, lng: 5},
+      zoom: 7,
+      mapTypeId: DEFAULT_OPTIONS.mapTypeId,
+    };
     mapSpy = createMapSpy(options);
     mapConstructorSpy = createMapConstructorSpy(mapSpy);
 
@@ -140,6 +144,7 @@ describe('GoogleMap', () => {
       zoom: 7,
       draggable: false,
       mapTypeId: DEFAULT_OPTIONS.mapTypeId,
+      mapId: '123',
     };
     mapSpy = createMapSpy(options);
     mapConstructorSpy = createMapConstructorSpy(mapSpy);
@@ -194,12 +199,13 @@ describe('GoogleMap', () => {
   });
 
   it('gives precedence to center and zoom over options', () => {
-    const inputOptions = {center: {lat: 3, lng: 5}, zoom: 7, heading: 170};
+    const inputOptions = {center: {lat: 3, lng: 5}, zoom: 7, heading: 170, mapId: '123'};
     const correctedOptions = {
       center: {lat: 12, lng: 15},
       zoom: 5,
       heading: 170,
       mapTypeId: DEFAULT_OPTIONS.mapTypeId,
+      mapId: '123',
     };
     mapSpy = createMapSpy(correctedOptions);
     mapConstructorSpy = createMapConstructorSpy(mapSpy);

src/google-maps/google-map/google-map.ts

@@ -83,6 +83,12 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
   /** Width of the map. Set this to `null` if you'd like to control the width through CSS. */
   @Input() width: string | number | null = DEFAULT_WIDTH;
 
+  /**
+   * The Map ID of the map. This parameter cannot be set or changed after a map is instantiated.
+   * See: https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions.mapId
+   */
+  @Input() mapId: string | undefined;
+
   /**
    * Type of map that should be rendered. E.g. hybrid map, terrain map etc.
    * See: https://developers.google.com/maps/documentation/javascript/reference/map#MapTypeId

src/google-maps/google-maps-module.ts

@@ -24,6 +24,7 @@ import {MapRectangle} from './map-rectangle/map-rectangle';
 import {MapTrafficLayer} from './map-traffic-layer/map-traffic-layer';
 import {MapTransitLayer} from './map-transit-layer/map-transit-layer';
 import {MapHeatmapLayer} from './map-heatmap-layer/map-heatmap-layer';
+import {MapAdvancedMarker} from './map-advanced-marker/map-advanced-marker';
 
 const COMPONENTS = [
   GoogleMap,
@@ -36,6 +37,7 @@ const COMPONENTS = [
   MapInfoWindow,
   MapKmlLayer,
   MapMarker,
+  MapAdvancedMarker,
   MapMarkerClusterer,
   MapPolygon,
   MapPolyline,

src/google-maps/map-advanced-marker/map-advanced-marker.spec.ts

@@ -0,0 +1,182 @@
+import {Component, ViewChild} from '@angular/core';
+import {TestBed, fakeAsync, flush} from '@angular/core/testing';
+
+import {DEFAULT_OPTIONS, GoogleMap} from '../google-map/google-map';
+import {
+  createAdvancedMarkerConstructorSpy,
+  createAdvancedMarkerSpy,
+  createMapConstructorSpy,
+  createMapSpy,
+} from '../testing/fake-google-map-utils';
+import {DEFAULT_MARKER_OPTIONS, MapAdvancedMarker} from './map-advanced-marker';
+
+describe('MapAdvancedMarker', () => {
+  let mapSpy: jasmine.SpyObj<google.maps.Map>;
+
+  beforeEach(() => {
+    mapSpy = createMapSpy(DEFAULT_OPTIONS);
+    createMapConstructorSpy(mapSpy);
+  });
+
+  afterEach(() => {
+    (window.google as any) = undefined;
+  });
+
+  it('initializes a Google Map advanced marker', fakeAsync(() => {
+    const advancedMarkerSpy = createAdvancedMarkerSpy(DEFAULT_MARKER_OPTIONS);
+    const advancedMarkerConstructorSpy = createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.detectChanges();
+    flush();
+    expect(advancedMarkerConstructorSpy).toHaveBeenCalledWith({
+      ...DEFAULT_MARKER_OPTIONS,
+      title: undefined,
+      content: undefined,
+      gmpDraggable: undefined,
+      zIndex: undefined,
+      map: mapSpy,
+    });
+  }));
+
+  it('sets advanced marker inputs', fakeAsync(() => {
+    const options: google.maps.marker.AdvancedMarkerElementOptions = {
+      position: {lat: 3, lng: 5},
+      title: 'marker title',
+      map: mapSpy,
+      content: undefined,
+      gmpDraggable: true,
+      zIndex: 1,
+    };
+    const advancedMarkerSpy = createAdvancedMarkerSpy(options);
+    const advancedMarkerConstructorSpy = createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.position = options.position;
+    fixture.componentInstance.title = options.title;
+    fixture.componentInstance.content = options.content;
+    fixture.componentInstance.gmpDraggable = options.gmpDraggable;
+    fixture.componentInstance.zIndex = options.zIndex;
+
+    fixture.detectChanges();
+    flush();
+
+    expect(advancedMarkerConstructorSpy).toHaveBeenCalledWith(options);
+  }));
+
+  it('sets marker options, ignoring map', fakeAsync(() => {
+    const options: google.maps.marker.AdvancedMarkerElementOptions = {
+      position: {lat: 3, lng: 5},
+      title: 'marker title',
+      content: undefined,
+      gmpDraggable: true,
+      zIndex: 1,
+    };
+    const advancedMarkerSpy = createAdvancedMarkerSpy(options);
+    const advancedMarkerConstructorSpy = createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.options = options;
+    fixture.detectChanges();
+    flush();
+
+    expect(advancedMarkerConstructorSpy).toHaveBeenCalledWith({...options, map: mapSpy});
+  }));
+
+  it('gives precedence to specific inputs over options', fakeAsync(() => {
+    const options: google.maps.marker.AdvancedMarkerElementOptions = {
+      position: {lat: 3, lng: 5},
+      title: 'marker title',
+      content: undefined,
+      gmpDraggable: true,
+      zIndex: 1,
+    };
+
+    const expectedOptions: google.maps.marker.AdvancedMarkerElementOptions = {
+      position: {lat: 4, lng: 6},
+      title: 'marker title 2',
+      content: undefined,
+      gmpDraggable: false,
+      zIndex: 999,
+      map: mapSpy,
+    };
+    const advancedMarkerSpy = createAdvancedMarkerSpy(options);
+    const advancedMarkerConstructorSpy = createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.position = expectedOptions.position;
+    fixture.componentInstance.title = expectedOptions.title;
+    fixture.componentInstance.content = expectedOptions.content;
+    fixture.componentInstance.gmpDraggable = expectedOptions.gmpDraggable;
+    fixture.componentInstance.zIndex = expectedOptions.zIndex;
+    fixture.componentInstance.options = options;
+
+    fixture.detectChanges();
+    flush();
+
+    expect(advancedMarkerConstructorSpy).toHaveBeenCalledWith(expectedOptions);
+  }));
+
+  it('initializes marker event handlers', fakeAsync(() => {
+    const advancedMarkerSpy = createAdvancedMarkerSpy(DEFAULT_MARKER_OPTIONS);
+    createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const addSpy = advancedMarkerSpy.addListener;
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.detectChanges();
+    flush();
+
+    expect(addSpy).toHaveBeenCalledWith('click', jasmine.any(Function));
+    expect(addSpy).not.toHaveBeenCalledWith('drag', jasmine.any(Function));
+    expect(addSpy).not.toHaveBeenCalledWith('dragend', jasmine.any(Function));
+    expect(addSpy).not.toHaveBeenCalledWith('dragstart', jasmine.any(Function));
+  }));
+
+  it('should be able to add an event listener after init', fakeAsync(() => {
+    const advancedMarkerSpy = createAdvancedMarkerSpy(DEFAULT_MARKER_OPTIONS);
+    createAdvancedMarkerConstructorSpy(advancedMarkerSpy);
+
+    const addSpy = advancedMarkerSpy.addListener;
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.detectChanges();
+    flush();
+
+    expect(addSpy).not.toHaveBeenCalledWith('drag', jasmine.any(Function));
+
+    // Pick an event that isn't bound in the template.
+    const subscription = fixture.componentInstance.advancedMarker.mapDrag.subscribe();
+    fixture.detectChanges();
+
+    expect(addSpy).toHaveBeenCalledWith('drag', jasmine.any(Function));
+    subscription.unsubscribe();
+  }));
+});
+
+@Component({
+  selector: 'test-app',
+  template: `
+    <google-map>
+      <map-advanced-marker
+        [title]="title"
+        [position]="position"
+        [content]="content"
+        [gmpDraggable]="gmpDraggable"
+        [zIndex]="zIndex"
+        (mapClick)="handleClick()"
+        [options]="options" />
+    </google-map>
+  `,
+  standalone: true,
+  imports: [GoogleMap, MapAdvancedMarker],
+})
+class TestApp {
+  @ViewChild(MapAdvancedMarker) advancedMarker: MapAdvancedMarker;
+  title?: string | null;
+  position?: google.maps.LatLng | google.maps.LatLngLiteral | null;
+  content?: Node | google.maps.marker.PinElement | null;
+  gmpDraggable?: boolean | null;
+  zIndex?: number | null;
+  options: google.maps.marker.AdvancedMarkerElementOptions;
+
+  handleClick() {}
+}