feat(google-maps): expose the underlying Google Maps objects.

Expose the underlying Google Maps objects so they can be interacted with
when it's necessary to do something unimplemented by
angular/google-maps. As part of this change, update DefinitelyTyped so
that we do not need a custom map object. Also standardize how
underlying objects interact with the components and updates new
components to work correctly when loading from the server.

Author: mbehrlich

package.json

@@ -51,7 +51,7 @@
     "@angular/elements": "^9.0.1",
     "@angular/forms": "^9.0.1",
     "@angular/platform-browser": "^9.0.1",
-    "@types/googlemaps": "^3.37.0",
+    "@types/googlemaps": "^3.39.3",
     "@types/youtube": "^0.0.38",
     "@webcomponents/custom-elements": "^1.1.0",
     "core-js": "^2.6.9",

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

@@ -13,7 +13,6 @@ import {
   DEFAULT_OPTIONS,
   DEFAULT_WIDTH,
   GoogleMap,
-  UpdatedGoogleMap
 } from './google-map';
 
 /** Represents boundaries of a map to be used in tests. */
@@ -32,7 +31,7 @@ const testPosition: google.maps.LatLngLiteral = {
 
 describe('GoogleMap', () => {
   let mapConstructorSpy: jasmine.Spy;
-  let mapSpy: jasmine.SpyObj<UpdatedGoogleMap>;
+  let mapSpy: jasmine.SpyObj<google.maps.Map>;
 
   beforeEach(async(() => {
     TestBed.configureTestingModule({

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

@@ -74,7 +74,13 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
   private readonly _zoom = new BehaviorSubject<number|undefined>(undefined);
   private readonly _destroy = new Subject<void>();
   private _mapEl: HTMLElement;
-  _googleMap: UpdatedGoogleMap;
+
+  /**
+   * The underlying google.maps.Map object
+   *
+   * See developers.google.com/maps/documentation/javascript/reference/map#Map
+   */
+  googleMap?: google.maps.Map;
 
   /** Whether we're currently rendering inside a browser. */
   _isBrowser: boolean;
@@ -258,8 +264,8 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
       this._setSize();
       this._googleMapChanges = this._initializeMap(this._combineOptions());
       this._googleMapChanges.subscribe((googleMap: google.maps.Map) => {
-        this._googleMap = googleMap as UpdatedGoogleMap;
-        this._eventManager.setTarget(this._googleMap);
+        this.googleMap = googleMap;
+        this._eventManager.setTarget(this.googleMap);
       });
 
       this._watchForOptionsChanges();
@@ -282,7 +288,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
       bounds: google.maps.LatLngBounds|google.maps.LatLngBoundsLiteral,
       padding?: number|google.maps.Padding) {
     this._assertInitialized();
-    this._googleMap.fitBounds(bounds, padding);
+    this.googleMap!.fitBounds(bounds, padding);
   }
 
   /**
@@ -291,7 +297,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   panBy(x: number, y: number) {
     this._assertInitialized();
-    this._googleMap.panBy(x, y);
+    this.googleMap!.panBy(x, y);
   }
 
   /**
@@ -300,7 +306,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   panTo(latLng: google.maps.LatLng|google.maps.LatLngLiteral) {
     this._assertInitialized();
-    this._googleMap.panTo(latLng);
+    this.googleMap!.panTo(latLng);
   }
 
   /**
@@ -311,7 +317,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
       latLngBounds: google.maps.LatLngBounds|google.maps.LatLngBoundsLiteral,
       padding?: number|google.maps.Padding) {
     this._assertInitialized();
-    this._googleMap.panToBounds(latLngBounds, padding);
+    this.googleMap!.panToBounds(latLngBounds, padding);
   }
 
   /**
@@ -320,7 +326,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getBounds(): google.maps.LatLngBounds|null {
     this._assertInitialized();
-    return this._googleMap.getBounds() || null;
+    return this.googleMap!.getBounds() || null;
   }
 
   /**
@@ -329,7 +335,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getCenter(): google.maps.LatLng {
     this._assertInitialized();
-    return this._googleMap.getCenter();
+    return this.googleMap!.getCenter();
   }
 
   /**
@@ -338,7 +344,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getClickableIcons(): boolean {
     this._assertInitialized();
-    return this._googleMap.getClickableIcons();
+    return this.googleMap!.getClickableIcons();
   }
 
   /**
@@ -347,7 +353,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getHeading(): number {
     this._assertInitialized();
-    return this._googleMap.getHeading();
+    return this.googleMap!.getHeading();
   }
 
   /**
@@ -356,7 +362,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getMapTypeId(): google.maps.MapTypeId|string {
     this._assertInitialized();
-    return this._googleMap.getMapTypeId();
+    return this.googleMap!.getMapTypeId();
   }
 
   /**
@@ -365,7 +371,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getProjection(): google.maps.Projection|null {
     this._assertInitialized();
-    return this._googleMap.getProjection();
+    return this.googleMap!.getProjection();
   }
 
   /**
@@ -374,7 +380,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getStreetView(): google.maps.StreetViewPanorama {
     this._assertInitialized();
-    return this._googleMap.getStreetView();
+    return this.googleMap!.getStreetView();
   }
 
   /**
@@ -383,7 +389,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getTilt(): number {
     this._assertInitialized();
-    return this._googleMap.getTilt();
+    return this.googleMap!.getTilt();
   }
 
   /**
@@ -392,7 +398,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   getZoom(): number {
     this._assertInitialized();
-    return this._googleMap.getZoom();
+    return this.googleMap!.getZoom();
   }
 
   /**
@@ -401,7 +407,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   get controls(): Array<google.maps.MVCArray<Node>> {
     this._assertInitialized();
-    return this._googleMap.controls;
+    return this.googleMap!.controls;
   }
 
   /**
@@ -410,7 +416,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   get data(): google.maps.Data {
     this._assertInitialized();
-    return this._googleMap.data;
+    return this.googleMap!.data;
   }
 
   /**
@@ -419,7 +425,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   get mapTypes(): google.maps.MapTypeRegistry {
     this._assertInitialized();
-    return this._googleMap.mapTypes;
+    return this.googleMap!.mapTypes;
   }
 
   /**
@@ -428,7 +434,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
    */
   get overlayMapTypes(): google.maps.MVCArray<google.maps.MapType> {
     this._assertInitialized();
-    return this._googleMap.overlayMapTypes;
+    return this.googleMap!.overlayMapTypes;
   }
 
   private _setSize() {
@@ -495,7 +501,7 @@ export class GoogleMap implements OnChanges, OnInit, OnDestroy {
 
   /** Asserts that the map has been initialized. */
   private _assertInitialized() {
-    if (!this._googleMap) {
+    if (!this.googleMap) {
       throw Error('Cannot access Google Map information before the API has been initialized. ' +
                   'Please wait for the API to load before trying to interact with it.');
     }

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

@@ -112,7 +112,7 @@ describe('MapInfoWindow', () => {
 
   it('exposes methods that change the configuration of the info window', () => {
     const fakeMarker = {} as unknown as google.maps.Marker;
-    const fakeMarkerComponent = {_marker: fakeMarker} as unknown as MapMarker;
+    const fakeMarkerComponent = {marker: fakeMarker} as unknown as MapMarker;
     const infoWindowSpy = createInfoWindowSpy({});
     createInfoWindowConstructorSpy(infoWindowSpy).and.callThrough();
 

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

@@ -13,21 +13,22 @@ import {
   Directive,
   ElementRef,
   Input,
+  NgZone,
   OnDestroy,
   OnInit,
   Output,
-  NgZone,
 } from '@angular/core';
 import {BehaviorSubject, combineLatest, Observable, Subject} from 'rxjs';
-import {map, takeUntil} from 'rxjs/operators';
+import {map, take, takeUntil} from 'rxjs/operators';
 
 import {GoogleMap} from '../google-map/google-map';
-import {MapMarker} from '../map-marker/map-marker';
 import {MapEventManager} from '../map-event-manager';
+import {MapMarker} from '../map-marker/map-marker';
 
 /**
  * Angular component that renders a Google Maps info window via the Google Maps JavaScript API.
- * @see developers.google.com/maps/documentation/javascript/reference/info-window
+ *
+ * See developers.google.com/maps/documentation/javascript/reference/info-window
  */
 @Directive({
   selector: 'map-info-window',
@@ -39,7 +40,13 @@ export class MapInfoWindow implements OnInit, OnDestroy {
   private readonly _position =
       new BehaviorSubject<google.maps.LatLngLiteral|google.maps.LatLng|undefined>(undefined);
   private readonly _destroy = new Subject<void>();
-  private _infoWindow?: google.maps.InfoWindow;
+
+  /**
+   * Underlying google.maps.InfoWindow
+   *
+   * See developers.google.com/maps/documentation/javascript/reference/info-window#InfoWindow
+   */
+  infoWindow?: google.maps.InfoWindow;
 
   @Input()
   set options(options: google.maps.InfoWindowOptions) {
@@ -93,20 +100,21 @@ export class MapInfoWindow implements OnInit, OnDestroy {
 
   ngOnInit() {
     if (this._googleMap._isBrowser) {
-      this._combineOptions().pipe(takeUntil(this._destroy)).subscribe(options => {
-        if (this._infoWindow) {
-          this._infoWindow.setOptions(options);
-        } else {
-          // Create the object outside the zone so its events don't trigger change detection.
-          // We'll bring it back in inside the `MapEventManager` only for the events that the
-          // user has subscribed to.
-          this._ngZone.runOutsideAngular(() => {
-            this._infoWindow = new google.maps.InfoWindow(options);
-          });
-
-          this._eventManager.setTarget(this._infoWindow);
-        }
+      const combinedOptionsChanges = this._combineOptions();
+
+      combinedOptionsChanges.pipe(take(1)).subscribe(options => {
+        // Create the object outside the zone so its events don't trigger change detection.
+        // We'll bring it back in inside the `MapEventManager` only for the events that the
+        // user has subscribed to.
+        this._ngZone.runOutsideAngular(() => {
+          this.infoWindow = new google.maps.InfoWindow(options);
+        });
+
+        this._eventManager.setTarget(this.infoWindow);
       });
+
+      this._watchForOptionsChanges();
+      this._watchForPositionChanges();
     }
   }
 
@@ -121,17 +129,17 @@ export class MapInfoWindow implements OnInit, OnDestroy {
    * See developers.google.com/maps/documentation/javascript/reference/info-window#InfoWindow.close
    */
   close() {
-    if (this._infoWindow) {
-      this._infoWindow.close();
-    }
+    this._assertInitialized();
+    this.infoWindow!.close();
   }
 
   /**
    * See
    * developers.google.com/maps/documentation/javascript/reference/info-window#InfoWindow.getContent
    */
   getContent(): string|Node {
-    return this._infoWindow ? this._infoWindow.getContent() : '';
+    this._assertInitialized();
+    return this.infoWindow!.getContent();
   }
 
   /**
@@ -140,27 +148,28 @@ export class MapInfoWindow implements OnInit, OnDestroy {
    * #InfoWindow.getPosition
    */
   getPosition(): google.maps.LatLng|null {
-    return this._infoWindow ? this._infoWindow.getPosition() : null;
+    this._assertInitialized();
+    return this.infoWindow!.getPosition();
   }
 
   /**
    * See
    * developers.google.com/maps/documentation/javascript/reference/info-window#InfoWindow.getZIndex
    */
   getZIndex(): number {
-    return this._infoWindow ? this._infoWindow.getZIndex() : -1;
+    this._assertInitialized();
+    return this.infoWindow!.getZIndex();
   }
 
   /**
    * Opens the MapInfoWindow using the provided MapMarker as the anchor. If the anchor is not set,
    * then the position property of the options input is used instead.
    */
   open(anchor?: MapMarker) {
-    const marker = anchor ? anchor._marker : undefined;
-    if (this._googleMap._googleMap && this._infoWindow) {
-      this._elementRef.nativeElement.style.display = '';
-      this._infoWindow!.open(this._googleMap._googleMap, marker);
-    }
+    this._assertInitialized();
+    const marker = anchor ? anchor.marker : undefined;
+    this._elementRef.nativeElement.style.display = '';
+    this.infoWindow!.open(this._googleMap.googleMap, marker);
   }
 
   private _combineOptions(): Observable<google.maps.InfoWindowOptions> {
@@ -173,4 +182,34 @@ export class MapInfoWindow implements OnInit, OnDestroy {
       return combinedOptions;
     }));
   }
+
+  private _watchForOptionsChanges() {
+    this._options.pipe(takeUntil(this._destroy)).subscribe(options => {
+      this._assertInitialized();
+      this.infoWindow!.setOptions(options);
+    });
+  }
+
+  private _watchForPositionChanges() {
+    this._position.pipe(takeUntil(this._destroy)).subscribe(position => {
+      if (position) {
+        this._assertInitialized();
+        this.infoWindow!.setPosition(position);
+      }
+    });
+  }
+
+  private _assertInitialized() {
+    if (!this._googleMap.googleMap) {
+      throw Error(
+          'Cannot access Google Map information before the API has been initialized. ' +
+          'Please wait for the API to load before trying to interact with it.');
+    }
+    if (!this.infoWindow) {
+      throw Error(
+          'Cannot interact with a Google Map Info Window before it has been ' +
+          'initialized. Please wait for the Info Window to load before trying to interact with ' +
+          'it.');
+    }
+  }
 }