[Map][Google] Introduce provider parameter "libraries"

Author: Kocal

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,63 @@ $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.
+
+> **Note**:
+> As the UX Map component is new, there are not too many examples for the moment.
+
+### 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 controller to customize the marker before it is 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(String('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,7 +7,7 @@ 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 doCreateMap({ center, zoom, options, }: {
         center: Point | null;

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

@@ -1,32 +1,29 @@
 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) {
+            const loader = new Loader(this.providerOptionsValue);
+            _google = await loader.load();
         }
-        const { Map: _Map, InfoWindow } = await loader.importLibrary('maps');
-        const { AdvancedMarkerElement } = await loader.importLibrary('marker');
-        library = { _Map, AdvancedMarkerElement, InfoWindow };
         super.connect();
     }
     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 +37,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,18 +42,15 @@ 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) {
+            const loader = new Loader(this.providerOptionsValue);
+            _google = await loader.load();
         }
 
-        const { Map: _Map, InfoWindow } = await loader.importLibrary('maps');
-        const { AdvancedMarkerElement } = await loader.importLibrary('marker');
-        library = { _Map, AdvancedMarkerElement, InfoWindow };
-
         super.connect();
     }
 
@@ -77,7 +69,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 +81,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 +108,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>
         `);

src/Map/src/Bridge/Google/src/Renderer/GoogleRenderer.php

@@ -37,6 +37,10 @@ public function __construct(
         private ?int $retries = null,
         private ?string $url = null,
         private ?string $version = null,
+        /**
+         * @var array<'core' | 'maps' | 'places' | 'geocoding' | 'routes' | 'marker' | 'geometry' | 'elevation' | 'streetView' | 'journeySharing' | 'drawing' | 'visualization'>
+         */
+        private array $libraries = [],
     ) {
         parent::__construct($stimulusHelper);
     }
@@ -56,6 +60,7 @@ protected function getProviderOptions(): array
             'retries' => $this->retries,
             'url' => $this->url,
             'version' => $this->version,
+            'libraries' => $this->libraries,
         ]) + ['apiKey' => $this->apiKey];
     }
 
@@ -77,6 +82,7 @@ public function __toString(): string
                 'retries' => $this->retries,
                 'url' => $this->url,
                 'version' => $this->version,
+                'libraries' => $this->libraries,
             ]))
         );
     }

src/Map/src/Bridge/Google/src/Renderer/GoogleRendererFactory.php

@@ -41,6 +41,7 @@ public function create(Dsn $dsn): RendererInterface
             retries: $dsn->getOption('retries'),
             url: $dsn->getOption('url'),
             version: $dsn->getOption('version', 'weekly'),
+            libraries: ['maps', 'marker', ...$dsn->getOption('libraries', [])],
         );
     }
 

src/Map/src/Bridge/Google/tests/GoogleRendererFactoryTest.php

@@ -32,14 +32,19 @@ public static function supportsRenderer(): iterable
     public static function createRenderer(): iterable
     {
         yield [
-            'google://*******************@default/?version=weekly',
+            'google://*******************@default/?version=weekly&libraries%5B0%5D=maps&libraries%5B1%5D=marker',
             'google://GOOGLE_MAPS_API_KEY@default',
         ];
 
         yield [
-            'google://*******************@default/?version=quartly',
+            'google://*******************@default/?version=quartly&libraries%5B0%5D=maps&libraries%5B1%5D=marker',
             'google://GOOGLE_MAPS_API_KEY@default?version=quartly',
         ];
+
+        yield [
+            'google://*******************@default/?version=quartly&libraries%5B0%5D=maps&libraries%5B1%5D=marker&libraries%5B2%5D=geometry',
+            'google://GOOGLE_MAPS_API_KEY@default?version=quartly&libraries[]=geometry',
+        ];
     }
 
     public static function unsupportedSchemeRenderer(): iterable