feature #2044 [Map] Add support for libraries for Google Bridge, in…

…ject provider's SDK (`L` or `google`) to dispatched events (Kocal)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[Map] Add support for `libraries` for Google Bridge, inject provider's SDK (`L` or `google`) to dispatched events

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| 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.
 - 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).
-->

Follows #2040.

This PR gives the developper access to `L` (if using Leaflet) or `google` (if using Google Maps) in dispatched events, so the developper can **fully and freely** customize the map, their markers (before and after creation), and info windows (before and after creation).

I've added some use cases/examples in respective documentation, but tell me if a better place fits!

Also, please no quick merge this time (even if I like that :D), I really wants some reviews for this PR! cc `@javiereguiluz`  🙏🏻

# Code and screenshots

On my personal project, I have a map with a lot of markers.

Before UX Map, I was using Google Maps because I've found the "glyph" feature really sexy, but I was not able to use it anymore... until now!

## With Google Maps

Code:
```js
import {Controller} from "`@hotwired`/stimulus";

export default class extends Controller
{
    connect() {
        this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    disconnect() {
        this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    _onMarkerBeforeCreate(event) {
        const { definition, google } = event.detail;

        const pinElement = new google.maps.marker.PinElement({
            glyph: new URL(String(definition.extra['icon_mask_uri'])), // I've filled `extra` parameter from `new Marker()` (PHP) with the icon mask URL
            glyphColor: "white",
        });

        definition.rawOptions = {
            content: pinElement.element,
        }
    }
}
```

Screenshot:
<img width="470" alt="Capture d’écran 2024-08-09 à 22 58 19" src="https://github.com/user-attachments/assets/ace5a033-a423-45c5-bd67-0da68dd188c1">

## With Leaflet

A dumb example taken from the website:

Code:
```js
import {Controller} from "`@hotwired`/stimulus";

export default class extends Controller
{
    connect() {
        this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    disconnect() {
        this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    _onMarkerBeforeCreate(event) {
        const { definition, L } = event.detail;

        const redIcon = L.icon({
            iconUrl: 'https://leafletjs.com/examples/custom-icons/leaf-red.png',
            shadowUrl: 'https://leafletjs.com/examples/custom-icons/leaf-shadow.png',
            iconSize:     [38, 95], // size of the icon
            shadowSize:   [50, 64], // size of the shadow
            iconAnchor:   [22, 94], // point of the icon which will correspond to marker's location
            shadowAnchor: [4, 62],  // the same for the shadow
            popupAnchor:  [-3, -76] // point from which the popup should open relative to the iconAnchor
        })

        definition.rawOptions = {
            icon: redIcon,
        }
    }
}
```

Screenshot:

<img width="495" alt="Capture d’écran 2024-08-09 à 23 19 23" src="https://github.com/user-attachments/assets/e771c133-794a-4693-bfbb-5a3118f5f7f5">

Commits
-------

2dbb169 [Map] Add support for `libraries` for Google Bridge, inject provider's SDK (`L` or `google`) to dispatched events

src/Map/assets/dist/abstract_map_controller.d.ts

@@ -35,7 +35,6 @@ export default abstract class<MapOptions, Map, MarkerOptions, Marker, InfoWindow
     protected map: Map;
     protected markers: Array<Marker>;
     protected infoWindows: Array<InfoWindow>;
-    initialize(): void;
     connect(): void;
     protected abstract doCreateMap({ center, zoom, options, }: {
         center: Point | null;
@@ -53,5 +52,5 @@ export default abstract class<MapOptions, Map, MarkerOptions, Marker, InfoWindow
         marker: Marker;
     }): InfoWindow;
     protected abstract doFitBoundsToMarkers(): void;
-    private dispatchEvent;
+    protected abstract dispatchEvent(name: string, payload: Record<string, unknown>): void;
 }

src/Map/assets/dist/abstract_map_controller.js

@@ -6,7 +6,6 @@ class default_1 extends Controller {
         this.markers = [];
         this.infoWindows = [];
     }
-    initialize() { }
     connect() {
         const { center, zoom, options, markers, fitBoundsToMarkers } = this.viewValue;
         this.dispatchEvent('pre-connect', { options });
@@ -35,9 +34,6 @@ class default_1 extends Controller {
         this.infoWindows.push(infoWindow);
         return infoWindow;
     }
-    dispatchEvent(name, payload = {}) {
-        this.dispatch(name, { prefix: 'ux:map', detail: payload });
-    }
 }
 default_1.values = {
     providerOptions: Object,

src/Map/assets/src/abstract_map_controller.ts

@@ -66,8 +66,6 @@ export default abstract class<
     protected markers: Array<Marker> = [];
     protected infoWindows: Array<InfoWindow> = [];
 
-    initialize() {}
-
     connect() {
         const { center, zoom, options, markers, fitBoundsToMarkers } = this.viewValue;
 
@@ -136,7 +134,5 @@ export default abstract class<
 
     protected abstract doFitBoundsToMarkers(): void;
 
-    private dispatchEvent(name: string, payload: Record<string, unknown> = {}): void {
-        this.dispatch(name, { prefix: 'ux:map', detail: payload });
-    }
+    protected abstract dispatchEvent(name: string, payload: Record<string, unknown>): void;
 }

src/Map/assets/test/abstract_map_controller.test.ts

@@ -2,8 +2,16 @@ import { Application } from '@hotwired/stimulus';
 import { getByTestId, waitFor } from '@testing-library/dom';
 import { clearDOM, mountDOM } from '@symfony/stimulus-testing';
 import AbstractMapController from '../src/abstract_map_controller.ts';
+import * as L from 'leaflet';
 
 class MyMapController extends AbstractMapController {
+    protected dispatchEvent(name: string, payload: Record<string, unknown> = {}): void {
+        this.dispatch(name, {
+            prefix: 'ux:map',
+            detail: payload,
+        });
+    }
+
     doCreateMap({ center, zoom, options }) {
         return { map: 'map', center, zoom, options };
     }

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

@@ -10,19 +10,21 @@ UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default
 # With options
 UX_MAP_DSN=google://GOOGLE_MAPS_API_KEY@default?version=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`                                  |
+| 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 |
 
 ## Map options
 
@@ -78,6 +80,60 @@ $googleOptions = (new GoogleOptions())
 // Add the custom options to the map
 $map->options($googleOptions);
 ```
+## Use cases
+
+Below are some common or advanced use cases when using a map.
+
+### Customize the marker
+
+A common use case is to customize the marker. You can listen to the `ux:map:marker:before-create` event to customize the marker before it is created.
+
+Assuming you have a map with a custom controller:
+```twig
+{{ render_map(map, {'data-controller': 'my-map' }) }}
+```
+
+You can create a Stimulus controller to customize the markers before they are created:
+```js
+// assets/controllers/my_map_controller.js
+import {Controller} from "@hotwired/stimulus";
+
+export default class extends Controller
+{
+    connect() {
+        this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
+    }
+
+    disconnect() {
+        // Always remove listeners when the controller is disconnected
+        this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
+    }
+
+    _onMarkerBeforeCreate(event) {
+        // You can access the marker definition and the google object
+        // Note: `definition.rawOptions` is the raw options object that will be passed to the `google.maps.Marker` constructor. 
+        const { definition, google } = event.detail;
+
+        // 1. To use a custom image for the marker 
+        const beachFlagImg = document.createElement("img");
+        // Note: instead of using an hardcoded URL, you can use the `extra` parameter from `new Marker()` (PHP) and access it here with `definition.extra`.
+        beachFlagImg.src = "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png";
+        definition.rawOptions =  { 
+            content: beachFlagImg
+        }
+
+        // 2. To use a custom glyph for the marker
+        const pinElement = new google.maps.marker.PinElement({
+            // Note: instead of using an hardcoded URL, you can use the `extra` parameter from `new Marker()` (PHP) and access it here with `definition.extra`. 
+            glyph: new URL('https://maps.gstatic.com/mapfiles/place_api/icons/v2/museum_pinlet.svg'), 
+            glyphColor: "white",
+        });
+        definition.rawOptions = {
+            content: pinElement.element,
+        }
+    }
+}
+```
 
 ## Resources
 

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

@@ -7,8 +7,9 @@ export default class extends AbstractMapController<MapOptions, google.maps.Map,
     static values: {
         providerOptions: ObjectConstructor;
     };
-    providerOptionsValue: Pick<LoaderOptions, 'apiKey' | 'id' | 'language' | 'region' | 'nonce' | 'retries' | 'url' | 'version'>;
+    providerOptionsValue: Pick<LoaderOptions, 'apiKey' | 'id' | 'language' | 'region' | 'nonce' | 'retries' | 'url' | 'version' | 'libraries'>;
     connect(): Promise<void>;
+    protected dispatchEvent(name: string, payload?: Record<string, unknown>): void;
     protected doCreateMap({ center, zoom, options, }: {
         center: Point | null;
         zoom: number | null;

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

@@ -1,32 +1,50 @@
 import AbstractMapController from '@symfony/ux-map/abstract-map-controller';
 import { Loader } from '@googlemaps/js-api-loader';
 
-let loader;
-let library;
+let _google;
 class default_1 extends AbstractMapController {
     async connect() {
-        if (!loader) {
-            loader = new Loader(this.providerOptionsValue);
+        if (!_google) {
+            _google = { maps: {} };
+            let { libraries = [], ...loaderOptions } = this.providerOptionsValue;
+            const loader = new Loader(loaderOptions);
+            libraries = ['core', ...libraries.filter((library) => library !== 'core')];
+            const librariesImplementations = await Promise.all(libraries.map((library) => loader.importLibrary(library)));
+            librariesImplementations.map((libraryImplementation, index) => {
+                const library = libraries[index];
+                if (['marker', 'places', 'geometry', 'journeySharing', 'drawing', 'visualization'].includes(library)) {
+                    _google.maps[library] = libraryImplementation;
+                }
+                else {
+                    _google.maps = { ..._google.maps, ...libraryImplementation };
+                }
+            });
         }
-        const { Map: _Map, InfoWindow } = await loader.importLibrary('maps');
-        const { AdvancedMarkerElement } = await loader.importLibrary('marker');
-        library = { _Map, AdvancedMarkerElement, InfoWindow };
         super.connect();
     }
+    dispatchEvent(name, payload = {}) {
+        this.dispatch(name, {
+            prefix: 'ux:map',
+            detail: {
+                ...payload,
+                google: _google,
+            },
+        });
+    }
     doCreateMap({ center, zoom, options, }) {
         options.zoomControl = typeof options.zoomControlOptions !== 'undefined';
         options.mapTypeControl = typeof options.mapTypeControlOptions !== 'undefined';
         options.streetViewControl = typeof options.streetViewControlOptions !== 'undefined';
         options.fullscreenControl = typeof options.fullscreenControlOptions !== 'undefined';
-        return new library._Map(this.element, {
+        return new _google.maps.Map(this.element, {
             ...options,
             center,
             zoom,
         });
     }
     doCreateMarker(definition) {
         const { position, title, infoWindow, extra, rawOptions = {}, ...otherOptions } = definition;
-        const marker = new library.AdvancedMarkerElement({
+        const marker = new _google.maps.marker.AdvancedMarkerElement({
             position,
             title,
             ...otherOptions,
@@ -40,7 +58,7 @@ class default_1 extends AbstractMapController {
     }
     doCreateInfoWindow({ definition, marker, }) {
         const { headerContent, content, extra, rawOptions = {}, ...otherOptions } = definition;
-        const infoWindow = new library.InfoWindow({
+        const infoWindow = new _google.maps.InfoWindow({
             headerContent: this.createTextOrElement(headerContent),
             content: this.createTextOrElement(content),
             ...otherOptions,

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

@@ -28,12 +28,7 @@ type MapOptions = Pick<
     | 'fullscreenControlOptions'
 >;
 
-let loader: Loader;
-let library: {
-    _Map: typeof google.maps.Map;
-    AdvancedMarkerElement: typeof google.maps.marker.AdvancedMarkerElement;
-    InfoWindow: typeof google.maps.InfoWindow;
-};
+let _google: typeof google;
 
 export default class extends AbstractMapController<
     MapOptions,
@@ -47,21 +42,49 @@ export default class extends AbstractMapController<
 
     declare providerOptionsValue: Pick<
         LoaderOptions,
-        'apiKey' | 'id' | 'language' | 'region' | 'nonce' | 'retries' | 'url' | 'version'
+        'apiKey' | 'id' | 'language' | 'region' | 'nonce' | 'retries' | 'url' | 'version' | 'libraries'
     >;
 
     async connect() {
-        if (!loader) {
-            loader = new Loader(this.providerOptionsValue);
+        if (!_google) {
+            _google = { maps: {} };
+
+            let { libraries = [], ...loaderOptions } = this.providerOptionsValue;
+
+            const loader = new Loader(loaderOptions);
+
+            // We could have used `loader.load()` to correctly load libraries, but this method is deprecated in favor of `loader.importLibrary()`.
+            // But `loader.importLibrary()` is not a 1-1 replacement for `loader.load()`, we need to re-build the `google.maps` object ourselves,
+            // see https://github.com/googlemaps/js-api-loader/issues/837 for more information.
+            libraries = ['core', ...libraries.filter((library) => library !== 'core')]; // Ensure 'core' is loaded first
+            const librariesImplementations = await Promise.all(
+                libraries.map((library) => loader.importLibrary(library))
+            );
+            librariesImplementations.map((libraryImplementation, index) => {
+                const library = libraries[index];
+
+                // The following libraries are in a sub-namespace
+                if (['marker', 'places', 'geometry', 'journeySharing', 'drawing', 'visualization'].includes(library)) {
+                    _google.maps[library] = libraryImplementation;
+                } else {
+                    _google.maps = { ..._google.maps, ...libraryImplementation };
+                }
+            });
         }
 
-        const { Map: _Map, InfoWindow } = await loader.importLibrary('maps');
-        const { AdvancedMarkerElement } = await loader.importLibrary('marker');
-        library = { _Map, AdvancedMarkerElement, InfoWindow };
-
         super.connect();
     }
 
+    protected dispatchEvent(name: string, payload: Record<string, unknown> = {}): void {
+        this.dispatch(name, {
+            prefix: 'ux:map',
+            detail: {
+                ...payload,
+                google: _google,
+            },
+        });
+    }
+
     protected doCreateMap({
         center,
         zoom,
@@ -77,7 +100,7 @@ export default class extends AbstractMapController<
         options.streetViewControl = typeof options.streetViewControlOptions !== 'undefined';
         options.fullscreenControl = typeof options.fullscreenControlOptions !== 'undefined';
 
-        return new library._Map(this.element, {
+        return new _google.maps.Map(this.element, {
             ...options,
             center,
             zoom,
@@ -89,7 +112,7 @@ export default class extends AbstractMapController<
     ): google.maps.marker.AdvancedMarkerElement {
         const { position, title, infoWindow, extra, rawOptions = {}, ...otherOptions } = definition;
 
-        const marker = new library.AdvancedMarkerElement({
+        const marker = new _google.maps.marker.AdvancedMarkerElement({
             position,
             title,
             ...otherOptions,
@@ -116,7 +139,7 @@ export default class extends AbstractMapController<
     }): google.maps.InfoWindow {
         const { headerContent, content, extra, rawOptions = {}, ...otherOptions } = definition;
 
-        const infoWindow = new library.InfoWindow({
+        const infoWindow = new _google.maps.InfoWindow({
             headerContent: this.createTextOrElement(headerContent),
             content: this.createTextOrElement(content),
             ...otherOptions,

src/Map/src/Bridge/Google/assets/test/map_controller.test.ts

@@ -40,7 +40,7 @@ describe('GoogleMapsController', () => {
               data-testid="map"
               data-controller="check google" 
               style="height: 700px&#x3B; margin: 10px" 
-              data-google-provider-options-value="{"language":"fr","region":"FR","retries":10,"version":"weekly","apiKey":""}" 
+              data-google-provider-options-value="{"version":"weekly","libraries":["maps","marker"],"apiKey":""}" 
               data-google-view-value="{"center":{"lat":48.8566,"lng":2.3522},"zoom":4,"fitBoundsToMarkers":true,"options":{"mapId":"YOUR_MAP_ID","gestureHandling":"auto","backgroundColor":null,"disableDoubleClickZoom":false,"zoomControl":true,"zoomControlOptions":{"position":22},"mapTypeControl":true,"mapTypeControlOptions":{"mapTypeIds":[],"position":14,"style":0},"streetViewControl":true,"streetViewControlOptions":{"position":22},"fullscreenControl":true,"fullscreenControlOptions":{"position":20}},"markers":[{"position":{"lat":48.8566,"lng":2.3522},"title":"Paris","infoWindow":null},{"position":{"lat":45.764,"lng":4.8357},"title":"Lyon","infoWindow":{"headerContent":"<b>Lyon<\/b>","content":"The French town in the historic Rh\u00f4ne-Alpes region, located at the junction of the Rh\u00f4ne and Sa\u00f4ne rivers.","position":null,"opened":false,"autoClose":true}}]}"
           ></div>
         `);