feat(google-maps): add geocoder wrapper (#21832)

Adds a wrapper around the Google Maps Geocoder API.
Also exports `MapDirectionsResponse` which wasn't exposed in a previous PR.

Fixes #21665.

Author: crisbeto

src/google-maps/README.md

@@ -113,6 +113,11 @@ export class GoogleMapsDemoComponent {
 - [`MapDirectionsRenderer`](./map-directions-renderer/README.md)
 - [`MapHeatmapLayer`](./map-heatmap-layer/README.md)
 
+## Services
+
+- [`MapGeocoder`](./map-geocoder/README.md)
+
+
 ## The Options Input
 
 The Google Maps components implement all of the options for their respective objects from the

src/google-maps/map-geocoder/README.md

@@ -0,0 +1,43 @@
+# MapGeocoder
+
+The `MapGeocoder`, like the `google.maps.Geocoder`, has a single method, `geocode`. Normally, the
+`google.maps.Geocoder` takes two arguments, a `google.maps.GeocoderRequest` and a callback that
+takes the `google.maps.GeocoderResult` and `google.maps.GeocoderStatus` as arguments.
+The `MapGeocoder.geocode` method takes takes the `google.maps.GeocoderRequest` as the single
+argument, and returns an `Observable` of a `MapGeocoderResponse`, which is an interface defined as
+follows:
+
+```typescript
+export interface MapGeocoderResponse {
+  status: google.maps.GeocoderStatus;
+  results: google.maps.GeocoderResult[];
+}
+```
+
+## Loading the Library
+
+Using the `MapGeocoder` requires the Geocoding API to be enabled in Google Cloud Console on the
+same project as the one set up for the Google Maps JavaScript API, and requires an API key that
+has billing enabled. See [here](https://developers.google.com/maps/documentation/javascript/geocoding#GetStarted) for details.
+
+## Example
+
+```typescript
+// google-maps-demo.component.ts
+import {Component} from '@angular/core';
+import {MapGeocoder} from '@angular/google-maps';
+
+@Component({
+  selector: 'google-map-demo',
+  templateUrl: 'google-map-demo.html',
+})
+export class GoogleMapDemo {
+  constructor(geocoder: MapGeocoder) {
+    geocoder.geocode({
+      address: '1600 Amphitheatre Parkway, Mountain View, CA'
+    }).subscribe(({results}) => {
+      console.log(results);
+    });
+  }
+}
+```

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

@@ -0,0 +1,40 @@
+import {TestBed} from '@angular/core/testing';
+import {MapGeocoderResponse, MapGeocoder} from './map-geocoder';
+import {GoogleMapsModule} from '../google-maps-module';
+import {createGeocoderConstructorSpy, createGeocoderSpy} from '../testing/fake-google-map-utils';
+
+describe('MapGeocoder', () => {
+  let geocoder: MapGeocoder;
+  let geocoderConstructorSpy: jasmine.Spy;
+  let geocoderSpy: jasmine.SpyObj<google.maps.Geocoder>;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [GoogleMapsModule],
+    });
+
+    geocoderSpy = createGeocoderSpy();
+    geocoderConstructorSpy = createGeocoderConstructorSpy(geocoderSpy).and.callThrough();
+    geocoder = TestBed.inject(MapGeocoder);
+  });
+
+  afterEach(() => {
+    (window.google as any) = undefined;
+  });
+
+  it('initializes the Google Maps Geocoder', () => {
+    expect(geocoderConstructorSpy).toHaveBeenCalled();
+  });
+
+  it('calls geocode on inputs', () => {
+    const results: google.maps.GeocoderResult[] = [];
+    const status = 'OK';
+    geocoderSpy.geocode.and.callFake((_: google.maps.GeocoderRequest, callback: Function) => {
+      callback(results, status);
+    });
+    const request: google.maps.DirectionsRequest = {};
+    geocoder.geocode(request).subscribe(response => {
+      expect(response).toEqual({results, status} as MapGeocoderResponse);
+    });
+  });
+});

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

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// Workaround for: https://github.com/bazelbuild/rules_nodejs/issues/1265
+/// <reference types="googlemaps" />
+
+import {Injectable, NgZone} from '@angular/core';
+import {Observable} from 'rxjs';
+
+export interface MapGeocoderResponse {
+  status: google.maps.GeocoderStatus;
+  results: google.maps.GeocoderResult[];
+}
+
+/**
+ * Angular service that wraps the Google Maps Geocoder from the Google Maps JavaScript API.
+ * See developers.google.com/maps/documentation/javascript/reference/geocoder#Geocoder
+ */
+@Injectable({providedIn: 'root'})
+export class MapGeocoder {
+  private readonly _geocoder: google.maps.Geocoder;
+
+  constructor(private readonly _ngZone: NgZone) {
+    this._geocoder = new google.maps.Geocoder();
+  }
+
+  /**
+   * See developers.google.com/maps/documentation/javascript/reference/geocoder#Geocoder.geocode
+   */
+  geocode(request: google.maps.GeocoderRequest): Observable<MapGeocoderResponse> {
+    return new Observable(observer => {
+      this._geocoder.geocode(request, (results, status) => {
+        this._ngZone.run(() => {
+          observer.next({results, status});
+          observer.complete();
+        });
+      });
+    });
+  }
+}

src/google-maps/public-api.ts

@@ -13,7 +13,10 @@ export {MapBaseLayer} from './map-base-layer';
 export {MapBicyclingLayer} from './map-bicycling-layer/map-bicycling-layer';
 export {MapCircle} from './map-circle/map-circle';
 export {MapDirectionsRenderer} from './map-directions-renderer/map-directions-renderer';
-export {MapDirectionsService} from './map-directions-renderer/map-directions-service';
+export {
+  MapDirectionsService,
+  MapDirectionsResponse,
+} from './map-directions-renderer/map-directions-service';
 export {MapGroundOverlay} from './map-ground-overlay/map-ground-overlay';
 export {MapInfoWindow} from './map-info-window/map-info-window';
 export {MapKmlLayer} from './map-kml-layer/map-kml-layer';
@@ -25,3 +28,4 @@ export {MapRectangle} from './map-rectangle/map-rectangle';
 export {MapTrafficLayer} from './map-traffic-layer/map-traffic-layer';
 export {MapTransitLayer} from './map-transit-layer/map-transit-layer';
 export {MapHeatmapLayer, HeatmapData} from './map-heatmap-layer/map-heatmap-layer';
+export {MapGeocoder, MapGeocoderResponse} from './map-geocoder/map-geocoder';

src/google-maps/testing/fake-google-map-utils.ts

@@ -34,6 +34,7 @@ export interface TestingWindow extends Window {
       visualization?: {
         HeatmapLayer?: jasmine.Spy;
       }
+      Geocoder?: jasmine.Spy;
     };
   };
   MarkerClusterer?: jasmine.Spy;
@@ -562,3 +563,25 @@ export function createLatLngConstructorSpy(
   }
   return latLngConstructorSpy;
 }
+
+/** Creates a jasmine.SpyObj for the Geocoder */
+export function createGeocoderSpy(): jasmine.SpyObj<google.maps.Geocoder> {
+  return jasmine.createSpyObj('google.maps.Geocoder', ['geocode']);
+}
+
+/** Creates a jasmine.Spy to watch for the constructor of the Geocoder. */
+export function createGeocoderConstructorSpy(
+    geocoderSpy: jasmine.SpyObj<google.maps.Geocoder>): jasmine.Spy {
+  const geocoderConstructorSpy = jasmine.createSpy('Geocoder constructor', () => geocoderSpy);
+  const testingWindow: TestingWindow = window;
+  if (testingWindow.google && testingWindow.google.maps) {
+    testingWindow.google.maps['Geocoder'] = geocoderConstructorSpy;
+  } else {
+    testingWindow.google = {
+      maps: {
+        'Geocoder': geocoderConstructorSpy,
+      },
+    };
+  }
+  return geocoderConstructorSpy;
+}

tools/public_api_guard/google-maps/google-maps.d.ts

@@ -130,13 +130,30 @@ export declare class MapDirectionsRenderer implements OnInit, OnChanges, OnDestr
     static ɵfac: i0.ɵɵFactoryDef<MapDirectionsRenderer, never>;
 }
 
+export interface MapDirectionsResponse {
+    result?: google.maps.DirectionsResult;
+    status: google.maps.DirectionsStatus;
+}
+
 export declare class MapDirectionsService {
     constructor(_ngZone: NgZone);
     route(request: google.maps.DirectionsRequest): Observable<MapDirectionsResponse>;
     static ɵfac: i0.ɵɵFactoryDef<MapDirectionsService, never>;
     static ɵprov: i0.ɵɵInjectableDef<MapDirectionsService>;
 }
 
+export declare class MapGeocoder {
+    constructor(_ngZone: NgZone);
+    geocode(request: google.maps.GeocoderRequest): Observable<MapGeocoderResponse>;
+    static ɵfac: i0.ɵɵFactoryDef<MapGeocoder, never>;
+    static ɵprov: i0.ɵɵInjectableDef<MapGeocoder>;
+}
+
+export interface MapGeocoderResponse {
+    results: google.maps.GeocoderResult[];
+    status: google.maps.GeocoderStatus;
+}
+
 export declare class MapGroundOverlay implements OnInit, OnDestroy {
     get bounds(): google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral;
     set bounds(bounds: google.maps.LatLngBounds | google.maps.LatLngBoundsLiteral);