[Map] Deprecate option title from Polygon, Polyline, Rectangle and Circle in favor of infoWindow

While writing E2E tests for Map, I found that our `title` option from `Polygon`, `Polyline`, `Rectangle` and `Circle` was wrongly used, and does not make sense.

Using `title` won't add an HTML attribute `title` as I expected, it's not something supported by Google nor Leaflet.
Instead, we used it to display a popup, like the `infoWindow` (which is more complete).

I suggest deprecating `title` from 2.x and remove it in 3.0.

Author: Kocal

package.json

@@ -26,6 +26,5 @@
         "tinyglobby": "^0.2.14",
         "tsup": "^8.5.0",
         "vitest": "^3.2.4"
-    },
-    "version": "2.27.0"
+    }
 }

src/Map/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.30
+
+-  Deprecate option `title` from `Polygon`, `Polyline`, `Rectangle` and `Circle` in favor of `infoWindow`
+
 ## 2.29.0
 
 -  Add Symfony 8 support

src/Map/assets/src/abstract_map_controller.ts

@@ -65,7 +65,7 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     icon?: Icon;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, use "bridgeOptions" instead.
      * Raw options passed to the marker constructor, specific to the map provider (e.g.: `L.marker()` for Leaflet).
      */
     rawOptions?: BridgeMarkerOptions;
@@ -86,9 +86,12 @@ export type MarkerDefinition<BridgeMarkerOptions, BridgeInfoWindowOptions> = Wit
 export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point> | Array<Array<Point>>;
+    /**
+     * @deprecated since Symfony UX Map 2.29, use "infoWindow" instead
+     */
     title: string | null;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, use "bridgeOptions" instead.
      * Raw options passed to the polygon constructor, specific to the map provider (e.g.: `L.polygon()` for Leaflet).
      */
     rawOptions?: BridgePolygonOptions;
@@ -109,9 +112,12 @@ export type PolygonDefinition<BridgePolygonOptions, BridgeInfoWindowOptions> = W
 export type PolylineDefinition<BridgePolylineOptions, BridgeInfoWindowOptions> = WithIdentifier<{
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     points: Array<Point>;
+    /**
+     * @deprecated since Symfony UX Map 2.29, use "infoWindow" instead
+     */
     title: string | null;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, use "bridgeOptions" instead.
      * Raw options passed to the polyline constructor, specific to the map provider (e.g.: `L.polyline()` for Leaflet).
      */
     rawOptions?: BridgePolylineOptions;
@@ -133,9 +139,12 @@ export type CircleDefinition<BridgeCircleOptions, BridgeInfoWindowOptions> = Wit
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     center: Point;
     radius: number;
+    /**
+     * @deprecated since Symfony UX Map 2.29, use "infoWindow" instead
+     */
     title: string | null;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, use "bridgeOptions" instead.
      * Raw options passed to the circle constructor, specific to the map provider (e.g.: `L.circle()` for Leaflet).
      */
     rawOptions?: BridgeCircleOptions;
@@ -157,9 +166,12 @@ export type RectangleDefinition<BridgeRectangleOptions, BridgeInfoWindowOptions>
     infoWindow?: Omit<InfoWindowDefinition<BridgeInfoWindowOptions>, 'position'>;
     southWest: Point;
     northEast: Point;
+    /**
+     * @deprecated since Symfony UX Map 2.29, use "infoWindow" instead
+     */
     title: string | null;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, use "bridgeOptions" instead.
      * Raw options passed to the rectangle constructor, specific to the map provider (e.g.: `L.rectangle()` for Leaflet).
      */
     rawOptions?: BridgeRectangleOptions;
@@ -184,7 +196,7 @@ export type InfoWindowDefinition<BridgeInfoWindowOptions> = {
     opened: boolean;
     autoClose: boolean;
     /**
-     * @deprecated Use "bridgeOptions" instead.
+     * @deprecated since Symfony UX Map 2.27, 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;

src/Map/doc/index.rst

@@ -237,7 +237,6 @@ You can add Circles, which represents a circular area defined by a center point
     $map->addCircle(new Circle(
         center: new Point(48.8566, 2.3522),
         radius: 5_000, // 5km
-        title: 'Paris',
         infoWindow: new InfoWindow(
             content: 'A 5km radius circle centered on Paris',
         ),
@@ -251,7 +250,6 @@ You can add Rectangles, which represents a rectangular area defined by two corne
     $map->addRectangle(new Rectangle(
         southWest: new Point(48.8566, 2.3522), // Paris
         northEast: new Point(50.6292, 3.0573), // Lille
-        title: 'Paris to Lille',
         infoWindow: new InfoWindow(
             content: 'A rectangle from Paris to Lille',
         ),
@@ -504,7 +502,7 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
          */
         _onPolygonBeforeCreate(event) {
             console.log(event.detail.definition);
-            // { title: 'My polygon', points: [ { lat: 48.8566, lng: 2.3522 }, { lat: 45.7640, lng: 4.8357 }, { lat: 43.2965, lng: 5.3698 }, ... ], ... }
+            // { points: [ { lat: 48.8566, lng: 2.3522 }, { lat: 45.7640, lng: 4.8357 }, { lat: 43.2965, lng: 5.3698 }, ... ], ... }
         }
 
         /**
@@ -522,7 +520,7 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
          */
         _onPolylineBeforeCreate(event) {
             console.log(event.detail.definition);
-            // { title: 'My polyline', points: [ { lat: 48.8566, lng: 2.3522 }, { lat: 45.7640, lng: 4.8357 }, { lat: 43.2965, lng: 5.3698 }, ... ], ... }
+            // {  points: [ { lat: 48.8566, lng: 2.3522 }, { lat: 45.7640, lng: 4.8357 }, { lat: 43.2965, lng: 5.3698 }, ... ], ... }
         }
 
         /**
@@ -536,7 +534,7 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
 
         _onCircleBeforeCreate(event) {
             console.log(event.detail.definition);
-            // { title: 'My circle', center: { lat: 48.8566, lng: 2.3522 }, radius: 1000, ... }
+            // { center: { lat: 48.8566, lng: 2.3522 }, radius: 1000, ... }
         }
 
         _onCircleAfterCreate(event) {
@@ -546,7 +544,7 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
 
         _onRectangleBeforeCreate(event) {
             console.log(event.detail.definition);
-            // { title: 'My rectangle', southWest: { lat: 48.8566, lng: 2.3522 }, northEast: { lat: 45.7640, lng: 4.8357 }, ... }
+            // { southWest: { lat: 48.8566, lng: 2.3522 }, northEast: { lat: 45.7640, lng: 4.8357 }, ... }
         }
 
         _onRectangleAfterCreate(event) {

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

@@ -212,6 +212,9 @@ export default class extends AbstractMapController<
             ...bridgeOptions,
         });
 
+        /**
+         * @deprecated since Symfony UX Map 2.29, will be removed in 3.0
+         */
         if (title) {
             polygon.set('title', title);
         }
@@ -241,6 +244,9 @@ export default class extends AbstractMapController<
             ...bridgeOptions,
         });
 
+        /**
+         * @deprecated since Symfony UX Map 2.29, will be removed in 3.0
+         */
         if (title) {
             polyline.set('title', title);
         }
@@ -267,6 +273,9 @@ export default class extends AbstractMapController<
             ...bridgeOptions,
         });
 
+        /**
+         * @deprecated since Symfony UX Map 2.29, will be removed in 3.0
+         */
         if (title) {
             circle.set('title', title);
         }
@@ -296,6 +305,9 @@ export default class extends AbstractMapController<
             ...bridgeOptions,
         });
 
+        /**
+         * @deprecated since Symfony UX Map 2.29, will be removed in 3.0
+         */
         if (title) {
             rectangle.set('title', title);
         }

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

@@ -169,6 +169,9 @@ export default class extends AbstractMapController<
 
         const polygon = L.polygon(points, { ...rawOptions, ...bridgeOptions }).addTo(this.map);
 
+        /**
+         * @deprecated since Symfony UX Map 2.29
+         */
         if (title) {
             polygon.bindPopup(title);
         }
@@ -189,6 +192,9 @@ export default class extends AbstractMapController<
 
         const polyline = L.polyline(points, { ...rawOptions, ...bridgeOptions }).addTo(this.map);
 
+        /**
+         * @deprecated since Symfony UX Map 2.29
+         */
         if (title) {
             polyline.bindPopup(title);
         }
@@ -209,6 +215,9 @@ export default class extends AbstractMapController<
 
         const circle = L.circle(center, { radius, ...rawOptions, ...bridgeOptions }).addTo(this.map);
 
+        /**
+         * @deprecated since Symfony UX Map 2.29
+         */
         if (title) {
             circle.bindPopup(title);
         }
@@ -235,6 +244,9 @@ export default class extends AbstractMapController<
             { ...rawOptions, ...bridgeOptions }
         ).addTo(this.map);
 
+        /**
+         * @deprecated since Symfony UX Map 2.29
+         */
         if (title) {
             rectangle.bindPopup(title);
         }

src/Map/src/Circle.php

@@ -34,6 +34,10 @@ public function __construct(
         public readonly array $extra = [],
         public readonly ?string $id = null,
     ) {
+        if (null !== $title) {
+            trigger_deprecation('symfony/ux-map', '2.30', 'The "title" parameter is deprecated and will be removed in 3.0. Use "infoWindow" instead.');
+        }
+
         if ($radius <= 0) {
             throw new InvalidArgumentException(\sprintf('Radius must be greater than 0, "%s" given.', $radius));
         }

src/Map/src/Polygon.php

@@ -33,6 +33,9 @@ public function __construct(
         private readonly array $extra = [],
         public readonly ?string $id = null,
     ) {
+        if (null !== $title) {
+            trigger_deprecation('symfony/ux-map', '2.30', 'The "title" parameter is deprecated and will be removed in 3.0. Use "infoWindow" instead.');
+        }
     }
 
     /**

src/Map/src/Polyline.php

@@ -32,6 +32,9 @@ public function __construct(
         private readonly array $extra = [],
         public readonly ?string $id = null,
     ) {
+        if (null !== $title) {
+            trigger_deprecation('symfony/ux-map', '2.30', 'The "title" parameter is deprecated and will be removed in 3.0. Use "infoWindow" instead.');
+        }
     }
 
     /**

src/Map/src/Rectangle.php

@@ -33,6 +33,9 @@ public function __construct(
         public readonly array $extra = [],
         public readonly ?string $id = null,
     ) {
+        if (null !== $title) {
+            trigger_deprecation('symfony/ux-map', '2.30', 'The "title" parameter is deprecated and will be removed in 3.0. Use "infoWindow" instead.');
+        }
     }
 
     /**