feature #2863 [Map] Add extra data to Map (Kocal)

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

Discussion
----------

[Map] Add `extra` data to `Map`

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

Replace #2810

Like for `Marker` and cie, `extra` data can now be defined on the `Map` in order to pass extra data from your PHP code to your custom Stimulus Controller, through `ux:map:pre-connect` and `ux:map:connect` events.

Combo-ed with `bridgeOptions` from #2861, it means that you can fully customize the Map creation given extra data given your PHP code (e.g.: injecting some API keys):
```php
$map = new Map(extra: ['vector_layer_api_key' => 'bar']);
// or
$map->extra(['foo' => 'bar']);
```
```js
this.element.addEventListener('ux:map:pre-connect', (event) => {
    const { detail } = event;

    console.log(detail.extra); // {'foo': 'bar'}

    if (detail.extra.foo === 'bar') {
        detail.extra.bridgeOptions = { a_bridge_specific_option: 'foobar' };
    }
});
```

Commits
-------

0363d5d [Map] Add `extra` data to `Map`
b4b7f61 [Map] Reword PHPDoc about "extra" properties

Author: Kocal

src/Map/CHANGELOG.md

@@ -39,6 +39,7 @@ this.element.addEventListener('ux:map:pre-connect', (event) => {
     };
 });
 ```
+-  Add `extra` data support to `Map`, which can be accessed in `ux:map:pre-connect` and `ux:map:connect` events
 
 ## 2.26
 

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

@@ -7,6 +7,7 @@ export type Identifier = string;
 export type WithIdentifier<T extends Record<string, unknown>> = T & {
     '@id': Identifier;
 };
+type ExtraData = Record<string, unknown>;
 export declare const IconTypes: {
     readonly Url: "url";
     readonly Svg: "svg";
@@ -31,6 +32,7 @@ export type MapDefinition<MapOptions, BridgeMapOptions> = {
     zoom: number | null;
     options: MapOptions;
     bridgeOptions?: BridgeMapOptions;
+    extra: ExtraData;
 };
 export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     position: Point;
@@ -39,23 +41,23 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
     icon?: Icon;
     rawOptions?: BridgeMarkerOptions;
     bridgeOptions?: BridgeMarkerOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point> | Array<Array<Point>>;
     title: string | null;
     rawOptions?: BridgePolygonOptions;
     bridgeOptions?: BridgePolygonOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point>;
     title: string | null;
     rawOptions?: BridgePolylineOptions;
     bridgeOptions?: BridgePolylineOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
@@ -64,7 +66,7 @@ export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = Wit
     title: string | null;
     rawOptions?: BridgeCircleOptions;
     bridgeOptions?: BridgeCircleOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
@@ -73,7 +75,7 @@ export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions>
     title: string | null;
     rawOptions?: BridgeRectangleOptions;
     bridgeOptions?: BridgeRectangleOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
     headerContent: string | null;
@@ -83,7 +85,7 @@ export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
     autoClose: boolean;
     rawOptions?: BridgeInfoWindowOptions;
     bridgeOptions?: BridgeInfoWindowOptions;
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 };
 export default abstract class<MapOptions, BridgeMapOptions, BridgeMap, BridgeMarkerOptions, BridgeMarker, BridgeInfoWindowOptions, BridgeInfoWindow, BridgePolygonOptions, BridgePolygon, BridgePolylineOptions, BridgePolyline, BridgeCircleOptions, BridgeCircle, BridgeRectangleOptions, BridgeRectangle> extends Controller<HTMLElement> {
     static values: {
@@ -97,6 +99,7 @@ export default abstract class<MapOptions, BridgeMapOptions, BridgeMap, BridgeMar
         circles: ArrayConstructor;
         rectangles: ArrayConstructor;
         options: ObjectConstructor;
+        extra: ObjectConstructor;
     };
     centerValue: Point | null;
     zoomValue: number | null;
@@ -107,6 +110,7 @@ export default abstract class<MapOptions, BridgeMapOptions, BridgeMap, BridgeMar
     circlesValue: Array<CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions>>;
     rectanglesValue: Array<RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions>>;
     optionsValue: MapOptions;
+    extraValue: Record<string, unknown>;
     hasCenterValue: boolean;
     hasZoomValue: boolean;
     hasFitBoundsToMarkersValue: boolean;
@@ -116,6 +120,7 @@ export default abstract class<MapOptions, BridgeMapOptions, BridgeMap, BridgeMar
     hasCirclesValue: boolean;
     hasRectanglesValue: boolean;
     hasOptionsValue: boolean;
+    hasExtraValue: boolean;
     protected map: BridgeMap;
     protected markers: Map<string, BridgeMarker>;
     protected polygons: Map<string, BridgePolygon>;
@@ -177,3 +182,4 @@ export default abstract class<MapOptions, BridgeMapOptions, BridgeMap, BridgeMar
     private createDrawingFactory;
     private onDrawChanged;
 }
+export {};

src/Map/assets/dist/abstract_map_controller.js

@@ -17,10 +17,12 @@ class default_1 extends Controller {
         this.isConnected = false;
     }
     connect() {
+        const extra = this.hasExtraValue ? this.extraValue : {};
         const mapDefinition = {
             center: this.hasCenterValue ? this.centerValue : null,
             zoom: this.hasZoomValue ? this.zoomValue : null,
             options: this.optionsValue,
+            extra,
         };
         this.dispatchEvent('pre-connect', mapDefinition);
         this.createMarker = this.createDrawingFactory('marker', this.markers, this.doCreateMarker.bind(this));
@@ -45,6 +47,7 @@ class default_1 extends Controller {
             circles: [...this.circles.values()],
             rectangles: [...this.rectangles.values()],
             infoWindows: this.infoWindows,
+            extra,
         });
         this.isConnected = true;
     }
@@ -130,6 +133,7 @@ default_1.values = {
     circles: Array,
     rectangles: Array,
     options: Object,
+    extra: Object,
 };
 
 export { IconTypes, default_1 as default };

src/Map/assets/src/abstract_map_controller.ts

@@ -13,6 +13,8 @@ export type Point = { lat: number; lng: number };
 export type Identifier = string;
 export type WithIdentifier<T extends Record<string, unknown>> = T & { '@id': Identifier };
 
+type ExtraData = Record<string, unknown>;
+
 export const IconTypes = {
     Url: 'url',
     Svg: 'svg',
@@ -46,6 +48,13 @@ export type MapDefinition<MapOptions, BridgeMapOptions> = {
      * These options are specific to the Map Bridge, and can be defined through `ux:map:pre-connect` event.
      */
     bridgeOptions?: BridgeMapOptions;
+    /**
+     * Extra data defined by the developer.
+     * They are not directly used by the Stimulus controller, but they can be used by the developer with event listeners:
+     *    - `ux:map:pre-connect`
+     *    - `ux:map:connect`
+     */
+    extra: ExtraData;
 };
 
 export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = WithIdentifier<{
@@ -69,7 +78,7 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
      *    - `ux:map:marker:before-create`
      *    - `ux:map:marker:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 
 export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
@@ -92,7 +101,7 @@ export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = W
      *    - `ux:map:polygon:before-create`
      *    - `ux:map:polygon:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 
 export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
@@ -115,7 +124,7 @@ export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> =
      *    - `ux:map:polyline:before-create`
      *    - `ux:map:polyline:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 
 export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
@@ -139,7 +148,7 @@ export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = Wit
      *    - `ux:map:circle:before-create`
      *    - `ux:map:circle:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 
 export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
@@ -163,7 +172,7 @@ export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions>
      *    - `ux:map:rectangle:before-create`
      *    - `ux:map:rectangle:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 }>;
 
 export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
@@ -188,7 +197,7 @@ export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
      *    - `ux:map:info-window:before-create`
      *    - `ux:map:info-window:after-create`
      */
-    extra: Record<string, unknown>;
+    extra: ExtraData;
 };
 
 export default abstract class<
@@ -219,6 +228,7 @@ export default abstract class<
         circles: Array,
         rectangles: Array,
         options: Object,
+        extra: Object,
     };
 
     declare centerValue: Point | null;
@@ -230,6 +240,7 @@ export default abstract class<
     declare circlesValue: Array<CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions>>;
     declare rectanglesValue: Array<RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions>>;
     declare optionsValue: MapOptions;
+    declare extraValue: Record<string, unknown>;
 
     declare hasCenterValue: boolean;
     declare hasZoomValue: boolean;
@@ -240,6 +251,7 @@ export default abstract class<
     declare hasCirclesValue: boolean;
     declare hasRectanglesValue: boolean;
     declare hasOptionsValue: boolean;
+    declare hasExtraValue: boolean;
 
     protected map: BridgeMap;
     protected markers = new Map<Identifier, BridgeMarker>();
@@ -259,10 +271,12 @@ export default abstract class<
     protected abstract dispatchEvent(name: string, payload: Record<string, unknown>): void;
 
     connect() {
+        const extra = this.hasExtraValue ? this.extraValue : {};
         const mapDefinition: MapDefinition<MapOptions, BridgeMapOptions> = {
             center: this.hasCenterValue ? this.centerValue : null,
             zoom: this.hasZoomValue ? this.zoomValue : null,
             options: this.optionsValue,
+            extra,
         };
         this.dispatchEvent('pre-connect', mapDefinition);
 
@@ -291,6 +305,7 @@ export default abstract class<
             circles: [...this.circles.values()],
             rectangles: [...this.rectangles.values()],
             infoWindows: this.infoWindows,
+            extra,
         });
 
         this.isConnected = true;

src/Map/doc/index.rst

@@ -713,6 +713,39 @@ On the JavaScript side, you can access your extra data via the
         // ...
     }
 
+.. versionadded:: 2.27
+
+    The ``Map`` class now has an ``extra`` property, which can be accessed in the ``ux:map:pre-connect`` and ``ux:map:connect`` events::
+
+        $map = new Map(/* ... */, extra: [
+            'foo' => 'bar',
+        ]);
+        // or
+        $map->extra([
+            'foo' => 'bar',
+        ]);
+
+    .. code-block:: javascript
+
+        // assets/controllers/mymap_controller.js
+
+        import { Controller } from '@hotwired/stimulus';
+
+        export default class extends Controller {
+
+            // ...
+
+            _onPreConnect(event) {
+                console.log(event.detail.extra);
+                // { foo: 'bar', ... }
+            }
+
+            _onConnect(event) {
+                console.log(event.detail.extra);
+                // { foo: 'bar', ... }
+            }
+        }
+
 .. _map-live-component:
 
 Usage with Live Components

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

@@ -18,10 +18,12 @@ class default_1 extends Controller {
         this.isConnected = false;
     }
     connect() {
+        const extra = this.hasExtraValue ? this.extraValue : {};
         const mapDefinition = {
             center: this.hasCenterValue ? this.centerValue : null,
             zoom: this.hasZoomValue ? this.zoomValue : null,
             options: this.optionsValue,
+            extra,
         };
         this.dispatchEvent('pre-connect', mapDefinition);
         this.createMarker = this.createDrawingFactory('marker', this.markers, this.doCreateMarker.bind(this));
@@ -46,6 +48,7 @@ class default_1 extends Controller {
             circles: [...this.circles.values()],
             rectangles: [...this.rectangles.values()],
             infoWindows: this.infoWindows,
+            extra,
         });
         this.isConnected = true;
     }
@@ -131,6 +134,7 @@ default_1.values = {
     circles: Array,
     rectangles: Array,
     options: Object,
+    extra: Object,
 };
 
 let _google;

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

@@ -188,5 +188,16 @@ public function renderIcon(string $name, array $attributes = []): string
                 ->addMarker(new Marker(position: new Point(45.7640, 4.8357), title: 'Lyon', icon: Icon::ux('fa:map-marker')->width(32)->height(32)))
                 ->addMarker(new Marker(position: new Point(45.8566, 2.3522), title: 'Dijon', icon: Icon::svg('<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24">...</svg>'))),
         ];
+
+        yield 'with map extra data' => [
+            'renderer' => new GoogleRenderer(new StimulusHelper(null), new UxIconRenderer(null), apiKey: 'api_key'),
+            'map' => (new Map())
+                ->center(new Point(48.8566, 2.3522))
+                ->zoom(12)
+                ->extra([
+                    'foo' => 'bar',
+                    'baz' => 42,
+                ]),
+        ];
     }
 }

src/Map/src/Bridge/Google/tests/__snapshots__/GoogleRendererTest__testRenderMap with data set with map extra data__1.txt

@@ -0,0 +1,16 @@
+<!-- This HTML has been prettified for testing purposes, and may not represent the actual HTML output.
+     Run "php vendor/bin/phpunit -d --update-snapshots" to update the snapshot. -->
+<div
+  data-controller="symfony--ux-google-map--map"
+  data-symfony--ux-google-map--map-provider-options-value="{&quot;apiKey&quot;:&quot;api_key&quot;}"
+  data-symfony--ux-google-map--map-center-value="{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522}"
+  data-symfony--ux-google-map--map-zoom-value="12"
+  data-symfony--ux-google-map--map-fit-bounds-to-markers-value="false"
+  data-symfony--ux-google-map--map-options-value="{&quot;mapId&quot;:null,&quot;gestureHandling&quot;:&quot;auto&quot;,&quot;backgroundColor&quot;:null,&quot;disableDoubleClickZoom&quot;:false,&quot;zoomControlOptions&quot;:{&quot;position&quot;:22},&quot;mapTypeControlOptions&quot;:{&quot;mapTypeIds&quot;:[],&quot;position&quot;:14,&quot;style&quot;:0},&quot;streetViewControlOptions&quot;:{&quot;position&quot;:22},&quot;fullscreenControlOptions&quot;:{&quot;position&quot;:20},&quot;@provider&quot;:&quot;google&quot;}"
+  data-symfony--ux-google-map--map-markers-value="[]"
+  data-symfony--ux-google-map--map-polygons-value="[]"
+  data-symfony--ux-google-map--map-polylines-value="[]"
+  data-symfony--ux-google-map--map-circles-value="[]"
+  data-symfony--ux-google-map--map-rectangles-value="[]"
+  data-symfony--ux-google-map--map-extra-value="{&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:42}"
+></div>

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

@@ -19,10 +19,12 @@ class default_1 extends Controller {
         this.isConnected = false;
     }
     connect() {
+        const extra = this.hasExtraValue ? this.extraValue : {};
         const mapDefinition = {
             center: this.hasCenterValue ? this.centerValue : null,
             zoom: this.hasZoomValue ? this.zoomValue : null,
             options: this.optionsValue,
+            extra,
         };
         this.dispatchEvent('pre-connect', mapDefinition);
         this.createMarker = this.createDrawingFactory('marker', this.markers, this.doCreateMarker.bind(this));
@@ -47,6 +49,7 @@ class default_1 extends Controller {
             circles: [...this.circles.values()],
             rectangles: [...this.rectangles.values()],
             infoWindows: this.infoWindows,
+            extra,
         });
         this.isConnected = true;
     }
@@ -132,6 +135,7 @@ default_1.values = {
     circles: Array,
     rectangles: Array,
     options: Object,
+    extra: Object,
 };
 
 class map_controller extends default_1 {