feature #3115 [Map][Google] Upgrade @googlemaps/js-api-loader to ^2.0 (Kocal)

This PR was merged into the 3.x branch.

Discussion
----------

[Map][Google] Upgrade `@googlemaps`/js-api-loader to ^2.0

| Q              | A
| -------------- | ---
| Bug fix?       | no
| New feature?   | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations?  | no <!-- if yes, also update UPGRADE-*.md and src/**/CHANGELOG.md -->
| Documentation? | no <!-- required for new features, or documentation updates -->
| Issues         | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License        | MIT

<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Update/add documentation as required (we can help!)
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->
Let's take advantage of the upcoming 3.0 to upgrade ``@googlemaps`/js-api-loader` to [^2.0.0](https://github.com/googlemaps/js-api-loader/releases/tag/v2.0.0).

It is possible to backport it on UX 2.x, but requires much work for no added-value.

Commits
-------

c958639 [Map][Google] Upgrade `@googlemaps`/js-api-loader to ^2.0

Author: Kocal

UPGRADE-3.0.md

@@ -31,6 +31,12 @@ class MyLiveComponent {
 *  The Twig function `render_map()` has been removed, use `ux_map()` instead
 *  The option `title` from `Polygon`, `Polyline`, `Rectangle` and `Circle`, has been removed, use option `infoWindow` instead
 *  The property `rawOptions` from `ux:map:*:before-create` events has been removed, use `bridgeOptions` instead
+*  The Google Map Bridge has been upgraded to use `@googlemaps/js-api-loader` version `^2.0.0`:
+    * If you use Symfony AssetMapper without Symfony Flex, run `bin/console importmap:require @googlemaps/js-api-loader@^2.0`
+    * Options configurable through `UX_MAP_DSN` query params have changed:
+        * Option `version` has been renamed to `v`
+        * Options `authReferrerPolicy`, `mapIds`, `channel`, `solutionChannel` have been added
+        * Options `ìd`, `nonce`, `retries`, `url` have been removed
 
 ## Swup
 

pnpm-lock.yaml

@@ -4,6 +4,12 @@
 
 -   Minimum required Symfony version is now 6.4
 -   Minimum required PHP version is now 8.2
+-   Upgrade `@googlemaps/js-api-loader` JavaScript package from `^1.16.6` to `^2.0.0`:
+    - If you use Symfony AssetMapper without Symfony Flex, run `bin/console importmap:require @googlemaps/js-api-loader@^2.0`
+    - Options configurable through `UX_MAP_DSN` query params have changed:
+        - Option `version` has been renamed to `v`
+        - Options `authReferrerPolicy`, `mapIds`, `channel`, `solutionChannel` have been added
+        - Options `ìd`, `nonce`, `retries`, `url` have been removed
 
 ## 2.31
 

src/Map/src/Bridge/Google/CHANGELOG.md

@@ -26,24 +26,24 @@ npm run watch
 ```dotenv
 UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default
 
-# With options
-UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?version=weekly
+# With
+UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?v=weekly
 UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?language=fr&region=FR
 UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?libraries[]=geometry&libraries[]=places
 ```
 
 Available options:
 
-| Option      | Description                                                                                                                        | Default                                                     |
-|-------------|------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
-| `id`        | The id of the script tag                                                                                                           | `__googleMapsScriptId`                                      |
-| `language`  | Force language, see [list of supported languages](https://developers.google.com/maps/faq#languagesupport) specified in the browser | The user's preferred language                               |
-| `region`    | Unicode region subtag identifiers compatible with [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)                           |                                                             |
-| `nonce`     | Use a cryptographic nonce attribute                                                                                                |                                                             |
-| `retries`   | The number of script load retries                                                                                                  | 3                                                           |
-| `url`       | Custom url to load the Google Maps API script                                                                                      | `https://maps.googleapis.com/maps/api/js`                   |
-| `version`   | The release channels or version numbers                                                                                            | `weekly`                                                    |
-| `libraries` | The additional libraries to load, see [list of supported libraries](https://googlemaps.github.io/js-api-loader/types/Library.html) | `['maps', 'marker']`, those two libraries are always loaded |
+| Option               | Description                                                                                                                                                            | Default                                                     |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
+| `v`                  | The version of the Maps JavaScript API to load, could be a [release channels](https://developers.google.com/maps/documentation/javascript/versions) or version numbers | `weekly`                                                    |
+| `language`           | The language to use, see [list of supported languages](https://developers.google.com/maps/faq#languagesupport) specified in the browser                                | The user's preferred language                               |
+| `region`             | The region code to use, unicode region subtag identifiers compatible with [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)                                       |                                                             |
+| `libraries`          | Additional libraries to load, see [list of supported libraries](https://developers.google.com/maps/documentation/javascript/libraries#available-libraries)             | `['maps', 'marker']`, those two libraries are always loaded |
+| `authReferrerPolicy` | Set the referrer policy for the API requests                                                                                                                           |                                                             |
+| `mapIds`             | An array of map IDs to preload                                                                                                                                         |                                                             |
+| `channel`            | Can be used to track your usage                                                                                                                                        |                                                             |
+| `solutionChannel`    | Used by the Google Maps Platform to track adoption and usage of examples and solutions                                                                                 |                                                             |
 
 ## Map options
 

src/Map/src/Bridge/Google/README.md

@@ -1,9 +1,9 @@
-import { LoaderOptions } from '@googlemaps/js-api-loader';
+import { APIOptions } from '@googlemaps/js-api-loader';
 import AbstractMapController, { MapDefinition, MarkerDefinition, PolygonDefinition, PolylineDefinition, CircleDefinition, RectangleDefinition, InfoWindowDefinition, Icon } from '@symfony/ux-map';
 
 type MapOptions = Pick<google.maps.MapOptions, 'mapId' | 'gestureHandling' | 'backgroundColor' | 'disableDoubleClickZoom' | 'zoomControl' | 'zoomControlOptions' | 'mapTypeControl' | 'mapTypeControlOptions' | 'streetViewControl' | 'streetViewControlOptions' | 'fullscreenControl' | 'fullscreenControlOptions'>;
 declare class export_default extends AbstractMapController<MapOptions, google.maps.MapOptions, google.maps.Map, google.maps.marker.AdvancedMarkerElementOptions, google.maps.marker.AdvancedMarkerElement, google.maps.InfoWindowOptions, google.maps.InfoWindow, google.maps.PolygonOptions, google.maps.Polygon, google.maps.PolylineOptions, google.maps.Polyline, google.maps.CircleOptions, google.maps.Circle, google.maps.RectangleOptions, google.maps.Rectangle> {
-    providerOptionsValue: Pick<LoaderOptions, 'apiKey' | 'id' | 'language' | 'region' | 'nonce' | 'retries' | 'url' | 'version' | 'libraries'>;
+    providerOptionsValue: Pick<APIOptions, 'key' | 'v' | 'language' | 'region' | 'libraries' | 'authReferrerPolicy' | 'mapIds' | 'channel' | 'solutionChannel'>;
     map: google.maps.Map;
     connect(): Promise<void>;
     centerValueChanged(): void;

src/Map/src/Bridge/Google/assets/dist/map_controller.d.ts

@@ -1,5 +1,5 @@
 // src/map_controller.ts
-import { Loader } from "@googlemaps/js-api-loader";
+import { importLibrary, setOptions } from "@googlemaps/js-api-loader";
 
 // ../../../../assets/dist/abstract_map_controller.js
 import { Controller } from "@hotwired/stimulus";
@@ -146,7 +146,6 @@ abstract_map_controller_default.values = {
 };
 
 // src/map_controller.ts
-var _google;
 var _loading = false;
 var _loaded = false;
 var _onLoadedCallbacks = [];
@@ -163,22 +162,10 @@ var map_controller_default = class extends abstract_map_controller_default {
       return;
     }
     _loading = true;
-    _google = { maps: {} };
     let { libraries = [], ...loaderOptions } = this.providerOptionsValue;
-    const loader = new Loader(loaderOptions);
+    setOptions(loaderOptions);
     libraries = ["core", ...libraries.filter((library) => library !== "core")];
-    const librariesImplementations = await Promise.all(libraries.map((library) => loader.importLibrary(library)));
-    librariesImplementations.map((libraryImplementation, index) => {
-      if (typeof libraryImplementation !== "object" || libraryImplementation === null) {
-        return;
-      }
-      const library = libraries[index];
-      if (["marker", "places", "geometry", "journeySharing", "drawing", "visualization"].includes(library)) {
-        _google.maps[library] = libraryImplementation;
-      } else {
-        _google.maps = { ..._google.maps, ...libraryImplementation };
-      }
-    });
+    await Promise.all(libraries.map((library) => importLibrary(library)));
     _loading = false;
     _loaded = true;
     onLoaded();
@@ -206,7 +193,7 @@ var map_controller_default = class extends abstract_map_controller_default {
     }
   }
   dispatchEvent(name, payload = {}) {
-    payload.google = _google;
+    payload.google = google;
     this.dispatch(name, {
       prefix: "ux:map",
       detail: payload
@@ -218,7 +205,7 @@ var map_controller_default = class extends abstract_map_controller_default {
     options.mapTypeControl = typeof options.mapTypeControlOptions !== "undefined";
     options.streetViewControl = typeof options.streetViewControlOptions !== "undefined";
     options.fullscreenControl = typeof options.fullscreenControlOptions !== "undefined";
-    return new _google.maps.Map(this.element, {
+    return new google.maps.Map(this.element, {
       center,
       zoom,
       minZoom,
@@ -231,7 +218,7 @@ var map_controller_default = class extends abstract_map_controller_default {
     definition
   }) {
     const { "@id": _id, position, title, infoWindow, icon, bridgeOptions = {} } = definition;
-    const marker = new _google.maps.marker.AdvancedMarkerElement({
+    const marker = new google.maps.marker.AdvancedMarkerElement({
       position,
       title,
       map: this.map,
@@ -255,7 +242,7 @@ var map_controller_default = class extends abstract_map_controller_default {
     definition
   }) {
     const { "@id": _id, points, infoWindow, bridgeOptions = {} } = definition;
-    const polygon = new _google.maps.Polygon({
+    const polygon = new google.maps.Polygon({
       paths: points,
       map: this.map,
       ...bridgeOptions
@@ -272,7 +259,7 @@ var map_controller_default = class extends abstract_map_controller_default {
     definition
   }) {
     const { "@id": _id, points, infoWindow, bridgeOptions = {} } = definition;
-    const polyline = new _google.maps.Polyline({
+    const polyline = new google.maps.Polyline({
       path: points,
       map: this.map,
       ...bridgeOptions
@@ -287,7 +274,7 @@ var map_controller_default = class extends abstract_map_controller_default {
   }
   doCreateCircle({ definition }) {
     const { "@id": _id, center, radius, infoWindow, bridgeOptions = {} } = definition;
-    const circle = new _google.maps.Circle({
+    const circle = new google.maps.Circle({
       center,
       radius,
       map: this.map,
@@ -305,8 +292,8 @@ var map_controller_default = class extends abstract_map_controller_default {
     definition
   }) {
     const { northEast, southWest, infoWindow, bridgeOptions = {} } = definition;
-    const rectangle = new _google.maps.Rectangle({
-      bounds: new _google.maps.LatLngBounds(southWest, northEast),
+    const rectangle = new google.maps.Rectangle({
+      bounds: new google.maps.LatLngBounds(southWest, northEast),
       map: this.map,
       ...bridgeOptions
     });
@@ -336,7 +323,7 @@ var map_controller_default = class extends abstract_map_controller_default {
       position,
       ...bridgeOptions
     };
-    const infoWindow = new _google.maps.InfoWindow(infoWindowOptions);
+    const infoWindow = new google.maps.InfoWindow(infoWindowOptions);
     element.addListener("click", (event) => {
       if (autoClose) {
         this.closeInfoWindowsExcept(infoWindow);

src/Map/src/Bridge/Google/assets/dist/map_controller.js

@@ -36,12 +36,12 @@
         },
         "importmap": {
             "@hotwired/stimulus": "^3.0.0",
-            "@googlemaps/js-api-loader": "^1.16.6",
+            "@googlemaps/js-api-loader": "^2.0.0",
             "@symfony/ux-google-map": "path:%PACKAGE%/dist/map_controller.js"
         }
     },
     "peerDependencies": {
-        "@googlemaps/js-api-loader": "^1.16.6",
+        "@googlemaps/js-api-loader": "^2.0.0",
         "@hotwired/stimulus": "^3.0.0"
     },
     "peerDependenciesMeta": {
@@ -50,7 +50,7 @@
         }
     },
     "devDependencies": {
-        "@googlemaps/js-api-loader": "^1.16.6",
+        "@googlemaps/js-api-loader": "^2.0.0",
         "@hotwired/stimulus": "^3.0.0",
         "@testing-library/dom": "^10.4.0",
         "@testing-library/jest-dom": "^6.6.3",