fix(checkout): CHECKOUT-10026 Add new Places API support for Google Autocomplete with legacy fallback

packages/core/src/app/address/googleAutocomplete/GoogleAutocomplete.tsx

@@ -5,6 +5,7 @@ import { Autocomplete, type AutocompleteItem } from '@bigcommerce/checkout/ui';
 
 import GoogleAutocompleteService from './GoogleAutocompleteService';
 import { type GoogleAutocompleteOptionTypes } from './googleAutocompleteTypes';
+import { mapToAutocompleteItems, mapToGeocoderAddressComponent } from './utils';
 import './GoogleAutocomplete.scss';
 
 export interface GoogleAutocompleteProps {
@@ -21,17 +22,6 @@ export interface GoogleAutocompleteProps {
     onChange?(value: string, isOpen: boolean): void;
 }
 
-const toAutocompleteItems = (
-    results?: google.maps.places.AutocompletePrediction[],
-): AutocompleteItem[] => {
-    return (results || []).map((result) => ({
-        label: result.description,
-        value: result.structured_formatting.main_text,
-        highlightedSlices: result.matched_substrings,
-        id: result.place_id,
-    }));
-};
-
 const GoogleAutocomplete: React.FC<GoogleAutocompleteProps> = ({
     initialValue,
     onToggleOpen = noop,
@@ -53,26 +43,26 @@ const GoogleAutocomplete: React.FC<GoogleAutocompleteProps> = ({
         googleAutocompleteServiceRef.current = new GoogleAutocompleteService(apiKey);
     }
 
-    const onSelectHandler = (item: AutocompleteItem) => {
+    const handleSelect = (item: AutocompleteItem) => {
         const service = googleAutocompleteServiceRef.current;
 
         if (!service) return;
 
-        service.getPlacesServices().then((placesService) => {
-            placesService.getDetails(
-                {
-                    placeId: item.id,
-                    fields: fields || ['address_components', 'name'],
-                },
-                (result) => {
-                    if (nextElement) {
-                        nextElement.focus();
-                    }
-
-                    onSelect(result, item);
-                },
-            );
-        });
+        service
+            .getPlaceDetails(item.id, fields || ['addressComponents', 'displayName'])
+            .then((place) => {
+                const placeResult: google.maps.places.PlaceResult = {
+                    address_components: place.addressComponents?.map(mapToGeocoderAddressComponent),
+                    name: place.displayName ?? '',
+                };
+
+                if (nextElement) {
+                    nextElement.focus();
+                }
+
+                onSelect(placeResult, item);
+            })
+            .catch(() => resetAutocomplete());
     };
 
     const resetAutocomplete = (): void => {
@@ -95,23 +85,13 @@ const GoogleAutocomplete: React.FC<GoogleAutocompleteProps> = ({
 
         if (!service) return;
 
-        service.getAutocompleteService().then((autocompleteService) => {
-            autocompleteService.getPlacePredictions(
-                {
-                    input,
-                    types: types || ['geocode'],
-                    componentRestrictions,
-                },
-                (results) => {
-                    const autocompleteItems = toAutocompleteItems(results ?? undefined);
-
-                    setItems(autocompleteItems);
-                },
-            );
-        });
+        service
+            .getSuggestions(input, types || ['geocode'], componentRestrictions)
+            .then((suggestions) => setItems(mapToAutocompleteItems(suggestions)))
+            .catch(() => setItems([]));
     };
 
-    const onChangeHandler = (input: string) => {
+    const handleChange = (input: string) => {
         onChange(input, false);
 
         if (!isAutocompleteEnabled) {
@@ -133,8 +113,8 @@ const GoogleAutocomplete: React.FC<GoogleAutocompleteProps> = ({
             }}
             items={items}
             listTestId="address-autocomplete-suggestions"
-            onChange={onChangeHandler}
-            onSelect={onSelectHandler}
+            onChange={handleChange}
+            onSelect={handleSelect}
             onToggleOpen={onToggleOpen}
         >
             <div className="co-googleAutocomplete-footer" />

packages/core/src/app/address/googleAutocomplete/GoogleAutocompleteScriptLoader.ts

@@ -1,59 +1,26 @@
 import { getScriptLoader, type ScriptLoader } from '@bigcommerce/script-loader';
 
-import { type GoogleAutocompleteWindow, type GoogleMapsSdk } from './googleAutocompleteTypes';
+export class GoogleAutocompleteScriptLoader {
+    private _scriptLoader: ScriptLoader = getScriptLoader();
+    private _placesPromise?: Promise<google.maps.PlacesLibrary>;
 
-export default class GoogleAutocompleteScriptLoader {
-    private _scriptLoader: ScriptLoader;
-    private _googleAutoComplete?: Promise<GoogleMapsSdk>;
-
-    constructor() {
-        this._scriptLoader = getScriptLoader();
-    }
-
-    loadMapsSdk(apiKey: string): Promise<GoogleMapsSdk> {
-        if (this._googleAutoComplete) {
-            return this._googleAutoComplete;
+    loadPlacesLibrary(apiKey: string): Promise<google.maps.PlacesLibrary> {
+        if (this._placesPromise) {
+            return this._placesPromise;
         }
 
-        this._googleAutoComplete = new Promise((resolve, reject) => {
-            const callbackName = 'initAutoComplete';
-            const params = [
-                'language=en',
-                `key=${apiKey}`,
-                'libraries=places',
-                `callback=${callbackName}`,
-            ].join('&');
+        const params = ['language=en', `key=${apiKey}`, 'loading=async'].join('&');
 
-            (window as GoogleCallbackWindow)[callbackName] = () => {
-                if (isAutocompleteWindow(window)) {
-                    resolve(window.google.maps);
-                }
+        const promise = this._scriptLoader
+            .loadScript(`//maps.googleapis.com/maps/api/js?${params}`)
+            .then(() => google.maps.importLibrary('places') as Promise<google.maps.PlacesLibrary>)
+            .catch((e) => {
+                this._placesPromise = undefined;
+                throw e;
+            });
 
-                reject(new Error('Failed to initialize Google Maps Autocomplete SDK.'));
-            };
+        this._placesPromise = promise;
 
-            this._scriptLoader
-                .loadScript(`//maps.googleapis.com/maps/api/js?${params}`)
-                .catch((e) => {
-                    this._googleAutoComplete = undefined;
-                    throw e;
-                });
-        });
-
-        return this._googleAutoComplete;
+        return promise;
     }
 }
-
-function isAutocompleteWindow(window: Window): window is GoogleAutocompleteWindow {
-    const autocompleteWindow = window as GoogleAutocompleteWindow;
-
-    return Boolean(
-        autocompleteWindow.google &&
-            autocompleteWindow.google.maps &&
-            autocompleteWindow.google.maps.places,
-    );
-}
-
-export interface GoogleCallbackWindow extends Window {
-    initAutoComplete?(): void;
-}

packages/core/src/app/address/googleAutocomplete/GoogleAutocompleteService.test.ts

@@ -0,0 +1,96 @@
+import { type GoogleAutocompleteScriptLoader } from './GoogleAutocompleteScriptLoader';
+import GoogleAutocompleteService from './GoogleAutocompleteService';
+
+const mockSuggestions = [
+    { placePrediction: { placeId: 'place-1' } },
+] as google.maps.places.AutocompleteSuggestion[];
+
+const mockPlace = {
+    fetchFields: jest.fn().mockResolvedValue(undefined),
+    addressComponents: [],
+    displayName: '123 Main St',
+} as google.maps.places.Place;
+
+const mockPlacesLibrary = {
+    AutocompleteSuggestion: {
+        fetchAutocompleteSuggestions: jest.fn().mockResolvedValue({ suggestions: mockSuggestions }),
+    },
+    Place: jest.fn().mockImplementation(() => mockPlace),
+} as google.maps.PlacesLibrary;
+
+const mockScriptLoader = {
+    loadPlacesLibrary: jest.fn().mockResolvedValue(mockPlacesLibrary),
+} as unknown as GoogleAutocompleteScriptLoader;
+
+describe('GoogleAutocompleteService', () => {
+    let service: GoogleAutocompleteService;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        service = new GoogleAutocompleteService('test-api-key', mockScriptLoader);
+    });
+
+    describe('#getSuggestions()', () => {
+        it('returns suggestions from the API', async () => {
+            const result = await service.getSuggestions('123 Main', ['address']);
+
+            expect(result).toBe(mockSuggestions);
+        });
+
+        it('passes input and types to fetchAutocompleteSuggestions', async () => {
+            await service.getSuggestions('123 Main', ['address']);
+
+            expect(
+                mockPlacesLibrary.AutocompleteSuggestion.fetchAutocompleteSuggestions,
+            ).toHaveBeenCalledWith(
+                expect.objectContaining({ input: '123 Main', includedPrimaryTypes: ['address'] }),
+            );
+        });
+
+        it('maps a string country restriction to includedRegionCodes array', async () => {
+            await service.getSuggestions('123 Main', ['address'], { country: 'US' });
+
+            expect(
+                mockPlacesLibrary.AutocompleteSuggestion.fetchAutocompleteSuggestions,
+            ).toHaveBeenCalledWith(expect.objectContaining({ includedRegionCodes: ['US'] }));
+        });
+
+        it('maps an array country restriction to includedRegionCodes', async () => {
+            await service.getSuggestions('123 Main', ['address'], { country: ['US', 'CA'] });
+
+            expect(
+                mockPlacesLibrary.AutocompleteSuggestion.fetchAutocompleteSuggestions,
+            ).toHaveBeenCalledWith(expect.objectContaining({ includedRegionCodes: ['US', 'CA'] }));
+        });
+
+        it('omits includedRegionCodes when no componentRestrictions provided', async () => {
+            await service.getSuggestions('123 Main', ['address']);
+
+            expect(
+                mockPlacesLibrary.AutocompleteSuggestion.fetchAutocompleteSuggestions,
+            ).toHaveBeenCalledWith(expect.objectContaining({ includedRegionCodes: undefined }));
+        });
+    });
+
+    describe('#getPlaceDetails()', () => {
+        it('constructs a Place with the given placeId', async () => {
+            await service.getPlaceDetails('place-1', ['addressComponents', 'displayName']);
+
+            expect(mockPlacesLibrary.Place).toHaveBeenCalledWith({ id: 'place-1' });
+        });
+
+        it('calls fetchFields with the given fields', async () => {
+            await service.getPlaceDetails('place-1', ['addressComponents', 'displayName']);
+
+            expect(mockPlace.fetchFields).toHaveBeenCalledWith({
+                fields: ['addressComponents', 'displayName'],
+            });
+        });
+
+        it('returns the place after fetching fields', async () => {
+            const result = await service.getPlaceDetails('place-1', ['addressComponents']);
+
+            expect(result).toBe(mockPlace);
+        });
+    });
+});

packages/core/src/app/address/googleAutocomplete/GoogleAutocompleteService.ts

@@ -1,46 +1,43 @@
 import getGoogleAutocompleteScriptLoader from './getGoogleAutocompleteScriptLoader';
-import type GoogleAutocompleteScriptLoader from './GoogleAutocompleteScriptLoader';
+import { type GoogleAutocompleteScriptLoader } from './GoogleAutocompleteScriptLoader';
 
 export default class GoogleAutocompleteService {
-    private _autocompletePromise?: Promise<google.maps.places.AutocompleteService>;
-    private _placesPromise?: Promise<google.maps.places.PlacesService>;
-
     constructor(
         private _apiKey: string,
         private _scriptLoader: GoogleAutocompleteScriptLoader = getGoogleAutocompleteScriptLoader(),
     ) {}
 
-    getAutocompleteService(): Promise<google.maps.places.AutocompleteService> {
-        if (!this._autocompletePromise) {
-            this._autocompletePromise = this._scriptLoader
-                .loadMapsSdk(this._apiKey)
-                .then((googleMapsSdk) => {
-                    if (!googleMapsSdk.places.AutocompleteService) {
-                        throw new Error('`AutocompleteService` is undefined');
-                    }
-
-                    return new googleMapsSdk.places.AutocompleteService();
-                });
-        }
+    private convertToRegionCodes(
+        country: string | string[] | null | undefined,
+    ): string[] | undefined {
+        if (!country) return undefined;
 
-        return this._autocompletePromise;
+        return Array.isArray(country) ? country : [country];
     }
 
-    getPlacesServices(): Promise<google.maps.places.PlacesService> {
-        const node = document.createElement('div');
+    async getSuggestions(
+        input: string,
+        types: string[],
+        componentRestrictions?: google.maps.places.ComponentRestrictions,
+    ): Promise<google.maps.places.AutocompleteSuggestion[]> {
+        const { AutocompleteSuggestion } = await this._scriptLoader.loadPlacesLibrary(this._apiKey);
+        const includedRegionCodes = this.convertToRegionCodes(componentRestrictions?.country);
+
+        const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions({
+            input,
+            includedPrimaryTypes: types,
+            includedRegionCodes,
+        });
+
+        return suggestions;
+    }
 
-        if (!this._placesPromise) {
-            this._placesPromise = this._scriptLoader
-                .loadMapsSdk(this._apiKey)
-                .then((googleMapsSdk) => {
-                    if (!googleMapsSdk.places.PlacesService) {
-                        throw new Error('`PlacesService` is undefined');
-                    }
+    async getPlaceDetails(placeId: string, fields: string[]): Promise<google.maps.places.Place> {
+        const { Place } = await this._scriptLoader.loadPlacesLibrary(this._apiKey);
+        const place = new Place({ id: placeId });
 
-                    return new googleMapsSdk.places.PlacesService(node);
-                });
-        }
+        await place.fetchFields({ fields });
 
-        return this._placesPromise;
+        return place;
     }
 }