feature #3036 [Map] Deprecate option title from Polygon, Polyline, Rectangle and Circle in favor of infoWindow (Kocal)

This PR was merged into the 2.x branch.

Discussion
----------

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

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

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.

Commits
-------

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

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/Bridge/Leaflet/tests/LeafletRendererTest.php

@@ -103,7 +103,7 @@ public static function provideTestRenderMap(): iterable
             'map' => (new Map())
                 ->center(new Point(48.8566, 2.3522))
                 ->zoom(12)
-                ->addCircle(new Circle(center: new Point(48.8566, 2.3522), radius: 1000000, title: 'Paris', id: 'circle1'))
+                ->addCircle(new Circle(center: new Point(48.8566, 2.3522), radius: 1000000, id: 'circle1'))
                 ->addCircle(new Circle(center: new Point(1.1, 2.2), radius: 500, infoWindow: new InfoWindow(content: 'Circle'), id: 'circle2')),
         ];
 
@@ -115,7 +115,6 @@ public static function provideTestRenderMap(): iterable
                 ->addRectangle(new Rectangle(
                     southWest: new Point(48.8566, 2.3522),
                     northEast: new Point(48.8566, 2.3522),
-                    title: 'Rectangle',
                     id: 'rectangle1'
                 ))
                 ->addRectangle(new Rectangle(

src/Map/src/Bridge/Leaflet/tests/__snapshots__/LeafletRendererTest__testRenderMap with data set with circles and infoWindows__1.txt

@@ -10,6 +10,6 @@
   data-symfony--ux-leaflet-map--map-markers-value="[]"
   data-symfony--ux-leaflet-map--map-polygons-value="[]"
   data-symfony--ux-leaflet-map--map-polylines-value="[]"
-  data-symfony--ux-leaflet-map--map-circles-value="[{"center":{"lat":48.8566,"lng":2.3522},"radius":1000000,"title":"Paris","infoWindow":null,"extra":[],"id":"circle1","@id":"b12929e5dc57d558"},{"center":{"lat":1.1,"lng":2.2},"radius":500,"title":null,"infoWindow":{"headerContent":null,"content":"Circle","position":null,"opened":false,"autoClose":true,"extra":[]},"extra":[],"id":"circle2","@id":"4953b5cc1d5759f4"}]"
+  data-symfony--ux-leaflet-map--map-circles-value="[{"center":{"lat":48.8566,"lng":2.3522},"radius":1000000,"title":null,"infoWindow":null,"extra":[],"id":"circle1","@id":"ead7389af3a04828"},{"center":{"lat":1.1,"lng":2.2},"radius":500,"title":null,"infoWindow":{"headerContent":null,"content":"Circle","position":null,"opened":false,"autoClose":true,"extra":[]},"extra":[],"id":"circle2","@id":"4953b5cc1d5759f4"}]"
   data-symfony--ux-leaflet-map--map-rectangles-value="[]"
 ></div>

src/Map/src/Bridge/Leaflet/tests/__snapshots__/LeafletRendererTest__testRenderMap with data set with rectangles and infoWindows__1.txt

@@ -11,5 +11,5 @@
   data-symfony--ux-leaflet-map--map-polygons-value="[]"
   data-symfony--ux-leaflet-map--map-polylines-value="[]"
   data-symfony--ux-leaflet-map--map-circles-value="[]"
-  data-symfony--ux-leaflet-map--map-rectangles-value="[{"southWest":{"lat":48.8566,"lng":2.3522},"northEast":{"lat":48.8566,"lng":2.3522},"title":"Rectangle","infoWindow":null,"extra":[],"id":"rectangle1","@id":"4cde1a021a127686"},{"southWest":{"lat":1.1,"lng":2.2},"northEast":{"lat":3.3,"lng":4.4},"title":null,"infoWindow":{"headerContent":null,"content":"Rectangle","position":null,"opened":false,"autoClose":true,"extra":[]},"extra":[],"id":"rectangle2","@id":"2549f5a73ef6bee7"}]"
+  data-symfony--ux-leaflet-map--map-rectangles-value="[{"southWest":{"lat":48.8566,"lng":2.3522},"northEast":{"lat":48.8566,"lng":2.3522},"title":null,"infoWindow":null,"extra":[],"id":"rectangle1","@id":"2ee3f2ebdef84b13"},{"southWest":{"lat":1.1,"lng":2.2},"northEast":{"lat":3.3,"lng":4.4},"title":null,"infoWindow":{"headerContent":null,"content":"Rectangle","position":null,"opened":false,"autoClose":true,"extra":[]},"extra":[],"id":"rectangle2","@id":"2549f5a73ef6bee7"}]"
 ></div>

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));
         }