feature #2860 [Map] Deprecate property rawOptions from ux:map:*:before-create events, in favor of bridgeOptions (Kocal)

This PR was merged into the 2.x branch.

Discussion
----------

[Map] Deprecate property `rawOptions` from `ux:map:*:before-create` events, in favor of `bridgeOptions`

| 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 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).
-->

Following #2859, the `rawOptions` does not really reflect its purpose, I find `bridgeOptions` much better.

With the follwing code:
```js
		this.element.addEventListener("ux:map:marker:before-create", (event) => {
			event.detail.definition.rawOptions = { opacity: 0.5};
			event.detail.definition.bridgeOptions = { title: 'Paris!!'};
		});
```

Both options are used, but a deprecation warning is nicely trigged:
<img width="1369" alt="image" src="https://github.com/user-attachments/assets/89ff93df-fca8-4a44-b9b3-21e9c245c96c" />

Commits
-------

9158b93 [Map] Deprecate property `rawOptions` from `ux:map:*:before-create` events, in favor of `bridgeOptions`

Author: Kocal

src/Map/CHANGELOG.md

@@ -1,16 +1,10 @@
 # CHANGELOG
 
-## 2.29
-
--   Add support for creating `Rectangle` by passing two `Point` instances to the `Rectangle` constructor, e.g.:
-```php
-$map->addRectangle(new Rectangle(
-    southWest: new Point(48.856613, 2.352222), // Paris
-    northEast: new Point(48.51238 2.21080) // Gare de Lyon (Paris)
-));
-```
+## 2.27
 
-## 2.28
+-   The `fitBoundsToMarkers` option is not overridden anymore when using the `Map` LiveComponent, but now respects the value you defined.
+    You may encounter unwanted behavior when adding/removing elements to the map.
+    To use the previous behavior, you must call `$this->getMap()->fitBoundsToMarkers(false)` in your LiveComponent's live actions
 
 -   Add support for creating `Circle` by passing a `Point` and a radius (in meters) to the `Circle` constructor, e.g.:
 ```php
@@ -19,11 +13,16 @@ $map->addCircle(new Circle(
     radius: 5_000 // 5km
 ));
 ```
-## 2.27
 
--   The `fitBoundsToMarkers` option is not overridden anymore when using the `Map` LiveComponent, but now respects the value you defined.
-    You may encounter unwanted behavior when adding/removing elements to the map.
-    To use the previous behavior, you must call `$this->getMap()->fitBoundsToMarkers(false)` in your LiveComponent's live actions
+-   Add support for creating `Rectangle` by passing two `Point` instances to the `Rectangle` constructor, e.g.:
+```php
+$map->addRectangle(new Rectangle(
+    southWest: new Point(48.856613, 2.352222), // Paris
+    northEast: new Point(48.51238 2.21080) // Gare de Lyon (Paris)
+));
+```
+
+-   Deprecate property `rawOptions` from `ux:map:*:before-create` events, in favor of `bridgeOptions` instead.
 
 ## 2.26
 

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

@@ -32,36 +32,41 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     icon?: Icon;
     rawOptions?: BridgeMarkerOptions;
+    bridgeOptions?: BridgeMarkerOptions;
     extra: Record<string, unknown>;
 }>;
-export type PolygonDefinition<PolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point> | Array<Array<Point>>;
     title: string | null;
-    rawOptions?: PolygonOptions;
+    rawOptions?: BridgePolygonOptions;
+    bridgeOptions?: BridgePolygonOptions;
     extra: Record<string, unknown>;
 }>;
-export type PolylineDefinition<PolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point>;
     title: string | null;
-    rawOptions?: PolylineOptions;
+    rawOptions?: BridgePolylineOptions;
+    bridgeOptions?: BridgePolylineOptions;
     extra: Record<string, unknown>;
 }>;
-export type CircleDefinition<CircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     center: Point;
     radius: number;
     title: string | null;
-    rawOptions?: CircleOptions;
+    rawOptions?: BridgeCircleOptions;
+    bridgeOptions?: BridgeCircleOptions;
     extra: Record<string, unknown>;
 }>;
-export type RectangleDefinition<RectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     southWest: Point;
     northEast: Point;
     title: string | null;
-    rawOptions?: RectangleOptions;
+    rawOptions?: BridgeRectangleOptions;
+    bridgeOptions?: BridgeRectangleOptions;
     extra: Record<string, unknown>;
 }>;
 export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
@@ -71,6 +76,7 @@ export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
     opened: boolean;
     autoClose: boolean;
     rawOptions?: BridgeInfoWindowOptions;
+    bridgeOptions?: BridgeInfoWindowOptions;
     extra: Record<string, unknown>;
 };
 export default abstract class<MapOptions, BridgeMap, BridgeMarkerOptions, BridgeMarker, BridgeInfoWindowOptions, BridgeInfoWindow, BridgePolygonOptions, BridgePolygon, BridgePolylineOptions, BridgePolyline, BridgeCircleOptions, BridgeCircle, BridgeRectangleOptions, BridgeRectangle> extends Controller<HTMLElement> {

src/Map/assets/dist/abstract_map_controller.js

@@ -93,6 +93,9 @@ class default_1 extends Controller {
         const eventAfter = `${type}:after-create`;
         return ({ definition }) => {
             this.dispatchEvent(eventBefore, { definition });
+            if (typeof definition.rawOptions !== 'undefined') {
+                console.warn(`[Symfony UX Map] The event "${eventBefore}" added a deprecated "rawOptions" property to the definition, it will be removed in a next major version, replace it with "bridgeOptions" instead.`, definition);
+            }
             const drawing = factory({ definition });
             this.dispatchEvent(eventAfter, { [type]: drawing, definition });
             draws.set(definition['@id'], drawing);

src/Map/assets/src/abstract_map_controller.ts

@@ -43,9 +43,15 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     icon?: Icon;
     /**
+     * @deprecated Use "bridgeOptions" instead.
      * Raw options passed to the marker constructor, specific to the map provider (e.g.: `L.marker()` for Leaflet).
      */
     rawOptions?: BridgeMarkerOptions;
+    /**
+     * Additional options passed to the Marker constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:marker:before-create` event.
+     */
+    bridgeOptions?: BridgeMarkerOptions;
     /**
      * 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:
@@ -55,14 +61,20 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
     extra: Record<string, unknown>;
 }>;
 
-export type PolygonDefinition<PolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point> | Array<Array<Point>>;
     title: string | null;
     /**
-     * Raw options passed to the marker constructor, specific to the map provider (e.g.: `L.marker()` for Leaflet).
+     * @deprecated Use "bridgeOptions" instead.
+     * Raw options passed to the polygon constructor, specific to the map provider (e.g.: `L.polygon()` for Leaflet).
+     */
+    rawOptions?: BridgePolygonOptions;
+    /**
+     * Additional options passed to the Polygon constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:polygon:before-create` event.
      */
-    rawOptions?: PolygonOptions;
+    bridgeOptions?: BridgePolygonOptions;
     /**
      * 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:
@@ -72,14 +84,20 @@ export type PolygonDefinition<PolygonOptions, BridgeInfoWindowOptions> = WithIde
     extra: Record<string, unknown>;
 }>;
 
-export type PolylineDefinition<PolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point>;
     title: string | null;
     /**
-     * Raw options passed to the marker constructor, specific to the map provider (e.g.: `L.marker()` for Leaflet).
+     * @deprecated Use "bridgeOptions" instead.
+     * Raw options passed to the polyline constructor, specific to the map provider (e.g.: `L.polyline()` for Leaflet).
+     */
+    rawOptions?: BridgePolylineOptions;
+    /**
+     * Additional options passed to the Polyline constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:polyline:before-create` event.
      */
-    rawOptions?: PolylineOptions;
+    bridgeOptions?: BridgePolylineOptions;
     /**
      * 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:
@@ -89,15 +107,21 @@ export type PolylineDefinition<PolylineOptions, BridgeInfoWindowOptions> = WithI
     extra: Record<string, unknown>;
 }>;
 
-export type CircleDefinition<CircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     center: Point;
     radius: number;
     title: string | null;
     /**
+     * @deprecated Use "bridgeOptions" instead.
      * Raw options passed to the circle constructor, specific to the map provider (e.g.: `L.circle()` for Leaflet).
      */
-    rawOptions?: CircleOptions;
+    rawOptions?: BridgeCircleOptions;
+    /**
+     * Additional options passed to the Circle constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:circle:before-create` event.
+     */
+    bridgeOptions?: BridgeCircleOptions;
     /**
      * 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:
@@ -107,15 +131,21 @@ export type CircleDefinition<CircleOptions, BridgeInfoWindowOptions> = WithIdent
     extra: Record<string, unknown>;
 }>;
 
-export type RectangleDefinition<RectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
+export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     southWest: Point;
     northEast: Point;
     title: string | null;
     /**
+     * @deprecated Use "bridgeOptions" instead.
      * Raw options passed to the rectangle constructor, specific to the map provider (e.g.: `L.rectangle()` for Leaflet).
      */
-    rawOptions?: RectangleOptions;
+    rawOptions?: BridgeRectangleOptions;
+    /**
+     * Additional options passed to the Rectangle constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:rectangle:before-create` event.
+     */
+    bridgeOptions?: BridgeRectangleOptions;
     /**
      * 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:
@@ -132,10 +162,15 @@ export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
     opened: boolean;
     autoClose: boolean;
     /**
-     * Raw options passed to the info window constructor,
-     * specific to the map provider (e.g.: `google.maps.InfoWindow()` for Google Maps).
+     * @deprecated Use "bridgeOptions" instead.
+     * Raw options passed to the info window constructor, specific to the map provider (e.g.: `google.maps.InfoWindow()` for Google Maps).
      */
     rawOptions?: BridgeInfoWindowOptions;
+    /**
+     * Additional options passed to the InfoWindow constructor.
+     * These options are specific to the Map Bridge, and can be defined through `ux:map:info-window:before-create` event.
+     */
+    bridgeOptions?: BridgeInfoWindowOptions;
     /**
      * 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:
@@ -378,6 +413,14 @@ export default abstract class<
         // 'Factory' could be instantiated with an arbitrary type which could be unrelated to '({ definition }: { definition: WithIdentifier<any>; }) => Draw'
         return ({ definition }: { definition: WithIdentifier<any> }) => {
             this.dispatchEvent(eventBefore, { definition });
+
+            if (typeof definition.rawOptions !== 'undefined') {
+                console.warn(
+                    `[Symfony UX Map] The event "${eventBefore}" added a deprecated "rawOptions" property to the definition, it will be removed in a next major version, replace it with "bridgeOptions" instead.`,
+                    definition
+                );
+            }
+
             const drawing = factory({ definition }) as Draw;
             this.dispatchEvent(eventAfter, { [type]: drawing, definition });
 

src/Map/doc/index.rst

@@ -501,7 +501,13 @@ maps and their elements. However, you might occasionally find this
 abstraction limiting and need to configure low-level options directly.
 
 Fortunately, you can customize these low-level options through the UX Map
-events ``ux:map:*:before-create`` using the special ``rawOptions`` property:
+events ``ux:map:*:before-create`` using the special ``bridgeOptions`` property:
+
+.. deprecated:: 2.27
+
+    The ``rawOptions`` property was deprecated in UX Map 2.27, and will be removed in 3.0.
+    Use ``bridgeOptions`` instead, which better reflect the purpose of these options (options that are
+    specific to the renderer bridge).
 
 .. code-block:: javascript
 
@@ -519,55 +525,55 @@ events ``ux:map:*:before-create`` using the special ``rawOptions`` property:
 
         _onMarkerBeforeCreate(event) {
             // When using Google Maps, to configure a `google.maps.AdvancedMarkerElement`
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 gmpDraggable: true,
                 // ...
             };
 
             // When using Leaflet, to configure a `L.Marker` instance
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 riseOnHover: true,
                 // ...
             };
         }
 
         _onInfoWindowBeforeCreate(event) {
             // When using Google Maps, to configure a `google.maps.InfoWindow` instance
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 maxWidth: 200,
                 // ...
             };
 
             // When using Leaflet, to configure a `L.Popup` instance
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 direction: 'left',
                 // ...
             };
         }
 
         _onPolygonBeforeCreate(event) {
             // When using Google Maps, to configure a `google.maps.Polygon`
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 strokeColor: 'red',
                 // ...
             };
 
             // When using Leaflet, to configure a `L.Polygon`
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 color: 'red',
                 // ...
             };
         }
 
         _onPolylineBeforeCreate(event) {
             // When using Google Maps, to configure a `google.maps.Polyline`
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 strokeColor: 'red',
                 // ...
             };
 
             // When using Leaflet, to configure a `L.Polyline`
-            event.detail.definition.rawOptions = {
+            event.detail.definition.bridgeOptions = {
                 color: 'red',
                 // ...
             };

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

@@ -16,7 +16,7 @@
             const bounds = new google.maps.LatLngBounds();
 
             element.getPath().forEach((latLng) => bounds.extend(latLng));
-            definition.infoWindow.rawOptions.position = bounds.getCenter();
+            definition.infoWindow.bridgeOptions.position = bounds.getCenter();
         }
     });
     ```

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

@@ -69,8 +69,8 @@ $map = (new Map())
 $googleOptions = (new GoogleOptions())
     // You can skip this option if you configure "ux_map.google_maps.default_map_id"
     // in your "config/packages/ux_map.yaml".
-    ->mapId('YOUR_MAP_ID') 
-    
+    ->mapId('YOUR_MAP_ID')
+
     ->gestureHandling(GestureHandling::GREEDY)
     ->backgroundColor('#f00')
     ->doubleClickZoom(true)
@@ -133,24 +133,24 @@ export default class extends Controller
 
     _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. 
+        // Note: `definition.bridgeOptions` 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 
+        // 1. To use a custom image for the marker
         const beachFlagImg = document.createElement("img");
         // Note: instead of using a 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 =  { 
+        definition.bridgeOptions =  {
             content: beachFlagImg
         }
-      
+
         // 2. To use a custom glyph for the marker
         const pinElement = new google.maps.marker.PinElement({
-            // Note: instead of using a 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'), 
+            // Note: instead of using a 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 = {
+        definition.bridgeOptions = {
             content: pinElement.element,
         }
     }