[Map] add Circle support

Author: Valmonzo

src/Map/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 2.28
+-   Add support for creating `Circle` by passing a `Point` and a radius in meters to the `Circle` constructor, e.g.:
+```php
+$map->addCircle(new Circle(
+    center: new Point(48.856613, 2.352222), // Paris
+    radius: 5000 // 5 km
+));
+```
 ## 2.27
 
 -   The `fitBoundsToMarkers` option is not overridden anymore when using the `Map` LiveComponent, but now respects the value you defined.

src/Map/assets/src/abstract_map_controller.ts

@@ -80,6 +80,24 @@ export type PolylineDefinition<PolylineOptions, InfoWindowOptions> = WithIdentif
     extra: Record<string, unknown>;
 }>;
 
+export type CircleDefinition<CircleOptions, InfoWindowOptions> = WithIdentifier<{
+    infoWindow?: InfoWindowWithoutPositionDefinition<InfoWindowOptions>;
+    center: Point;
+    radius: number;
+    title: string | null;
+    /**
+     * Raw options passed to the circle constructor, specific to the map provider (e.g.: `L.circle()` for Leaflet).
+     */
+    rawOptions?: CircleOptions;
+    /**
+     * 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:circle:before-create`
+     *    - `ux:map:circle:after-create`
+     */
+    extra: Record<string, unknown>;
+}>;
+
 export type InfoWindowDefinition<InfoWindowOptions> = {
     headerContent: string | null;
     content: string | null;
@@ -116,6 +134,8 @@ export default abstract class<
     Polygon,
     PolylineOptions,
     Polyline,
+    CircleOptions,
+    Circle,
 > extends Controller<HTMLElement> {
     static values = {
         providerOptions: Object,
@@ -125,6 +145,7 @@ export default abstract class<
         markers: Array,
         polygons: Array,
         polylines: Array,
+        circles: Array,
         options: Object,
     };
 
@@ -134,6 +155,7 @@ export default abstract class<
     declare markersValue: Array<MarkerDefinition<MarkerOptions, InfoWindowOptions>>;
     declare polygonsValue: Array<PolygonDefinition<PolygonOptions, InfoWindowOptions>>;
     declare polylinesValue: Array<PolylineDefinition<PolylineOptions, InfoWindowOptions>>;
+    declare circlesValue: Array<CircleDefinition<CircleOptions, InfoWindowOptions>>;
     declare optionsValue: MapOptions;
 
     declare hasCenterValue: boolean;
@@ -142,12 +164,14 @@ export default abstract class<
     declare hasMarkersValue: boolean;
     declare hasPolygonsValue: boolean;
     declare hasPolylinesValue: boolean;
+    declare hasCirclesValue: boolean;
     declare hasOptionsValue: boolean;
 
     protected map: Map;
     protected markers = new Map<Identifier, Marker>();
     protected polygons = new Map<Identifier, Polygon>();
     protected polylines = new Map<Identifier, Polyline>();
+    protected circles = new Map<Identifier, Circle>();
     protected infoWindows: Array<InfoWindow> = [];
 
     private isConnected = false;
@@ -160,6 +184,9 @@ export default abstract class<
     private createPolyline: ({
         definition,
     }: { definition: PolylineDefinition<PolylineOptions, InfoWindowOptions> }) => Polyline;
+    private createCircle: ({
+        definition,
+    }: { definition: CircleDefinition<CircleOptions, InfoWindowOptions> }) => Circle;
 
     protected abstract dispatchEvent(name: string, payload: Record<string, unknown>): void;
 
@@ -171,6 +198,7 @@ export default abstract class<
         this.createMarker = this.createDrawingFactory('marker', this.markers, this.doCreateMarker.bind(this));
         this.createPolygon = this.createDrawingFactory('polygon', this.polygons, this.doCreatePolygon.bind(this));
         this.createPolyline = this.createDrawingFactory('polyline', this.polylines, this.doCreatePolyline.bind(this));
+        this.createCircle = this.createDrawingFactory('circle', this.circles, this.doCreateCircle.bind(this));
 
         this.map = this.doCreateMap({
             center: this.hasCenterValue ? this.centerValue : null,
@@ -180,6 +208,7 @@ export default abstract class<
         this.markersValue.forEach((definition) => this.createMarker({ definition }));
         this.polygonsValue.forEach((definition) => this.createPolygon({ definition }));
         this.polylinesValue.forEach((definition) => this.createPolyline({ definition }));
+        this.circlesValue.forEach((definition) => this.createCircle({ definition }));
 
         if (this.fitBoundsToMarkersValue) {
             this.doFitBoundsToMarkers();
@@ -190,6 +219,7 @@ export default abstract class<
             markers: [...this.markers.values()],
             polygons: [...this.polygons.values()],
             polylines: [...this.polylines.values()],
+            circles: [...this.circles.values()],
             infoWindows: this.infoWindows,
         });
 
@@ -202,7 +232,7 @@ export default abstract class<
         element,
     }: {
         definition: InfoWindowWithoutPositionDefinition<InfoWindowOptions>;
-        element: Marker | Polygon | Polyline;
+        element: Marker | Polygon | Polyline | Circle;
     }): InfoWindow {
         this.dispatchEvent('info-window:before-create', { definition, element });
         const infoWindow = this.doCreateInfoWindow({ definition, element });
@@ -248,6 +278,14 @@ export default abstract class<
         this.onDrawChanged(this.polylines, this.polylinesValue, this.createPolyline, this.doRemovePolyline);
     }
 
+    public circlesValueChanged(): void {
+        if (!this.isConnected) {
+            return;
+        }
+
+        this.onDrawChanged(this.circles, this.circlesValue, this.createCircle, this.doRemoveCircle);
+    }
+
     //endregion
 
     //region Abstract factory methods to be implemented by the concrete classes, they are specific to the map provider
@@ -285,12 +323,20 @@ export default abstract class<
 
     protected abstract doRemovePolyline(polyline: Polyline): void;
 
+    protected abstract doCreateCircle({
+        definition,
+    }: {
+        definition: CircleDefinition<CircleOptions, InfoWindowOptions>;
+    }): Circle;
+
+    protected abstract doRemoveCircle(circle: Circle): void;
+
     protected abstract doCreateInfoWindow({
         definition,
         element,
     }: {
         definition: InfoWindowWithoutPositionDefinition<InfoWindowOptions>;
-        element: Marker | Polygon | Polyline;
+        element: Marker | Polygon | Polyline | Circle;
     }): InfoWindow;
     protected abstract doCreateIcon({
         definition,
@@ -318,11 +364,16 @@ export default abstract class<
         draws: typeof this.polylines,
         factory: typeof this.doCreatePolyline
     ): typeof this.doCreatePolyline;
+    private createDrawingFactory(
+        type: 'circle',
+        draws: typeof this.circles,
+        factory: typeof this.doCreateCircle
+    ): typeof this.doCreateCircle;
     private createDrawingFactory<
-        Factory extends typeof this.doCreateMarker | typeof this.doCreatePolygon | typeof this.doCreatePolyline,
+        Factory extends typeof this.doCreateMarker | typeof this.doCreatePolygon | typeof this.doCreatePolyline | typeof this.doCreateCircle,
         Draw extends ReturnType<Factory>,
     >(
-        type: 'marker' | 'polygon' | 'polyline',
+        type: 'marker' | 'polygon' | 'polyline' | 'circle',
         draws: globalThis.Map<WithIdentifier<any>, Draw>,
         factory: Factory
     ): Factory {
@@ -360,6 +411,12 @@ export default abstract class<
         factory: typeof this.createPolyline,
         remover: typeof this.doRemovePolyline
     ): void;
+    private onDrawChanged(
+        draws: typeof this.circles,
+        newDrawDefinitions: typeof this.circlesValue,
+        factory: typeof this.createCircle,
+        remover: typeof this.doRemoveCircle
+    ): void;
     private onDrawChanged<Draw, DrawDefinition extends WithIdentifier<Record<string, unknown>>>(
         draws: globalThis.Map<WithIdentifier<any>, Draw>,
         newDrawDefinitions: Array<DrawDefinition>,

src/Map/assets/test/abstract_map_controller.test.ts

@@ -44,6 +44,15 @@ class MyMapController extends AbstractMapController {
         return polyline;
     }
 
+    doCreateCircle({ definition }) {
+        const circle = { circle: 'circle', title: definition.title };
+
+        if (definition.infoWindow) {
+            this.createInfoWindow({ definition: definition.infoWindow, element: circle });
+        }
+        return circle;
+    }
+
     doCreateInfoWindow({ definition, element }) {
         if (element.marker) {
             return { infoWindow: 'infoWindow', headerContent: definition.headerContent, marker: element.title };
@@ -54,6 +63,9 @@ class MyMapController extends AbstractMapController {
         if (element.polyline) {
             return { infoWindow: 'infoWindow', headerContent: definition.headerContent, polyline: element.title };
         }
+        if (element.circle) {
+            return { infoWindow: 'infoWindow', headerContent: definition.headerContent, circle: element.title };
+        }
     }
 
     doFitBoundsToMarkers() {
@@ -72,17 +84,18 @@ describe('AbstractMapController', () => {
 
     beforeEach(() => {
         container = mountDOM(`
-            <div 
-                data-testid="map" 
-                data-controller="map" 
-                data-map-provider-options-value="{}" 
-                data-map-center-value="{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522}" 
-                data-map-zoom-value="4" 
-                data-map-fit-bounds-to-markers-value="false" 
-                data-map-options-value="{}" 
-                data-map-markers-value="[{&quot;position&quot;:{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},&quot;title&quot;:&quot;Paris&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Paris&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;a69f13edd2e571f3&quot;},{&quot;position&quot;:{&quot;lat&quot;:45.75,&quot;lng&quot;:4.85},&quot;title&quot;:&quot;Lyon&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Lyon&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;cb9c1a30d562694b&quot;},{&quot;position&quot;:{&quot;lat&quot;:43.6047,&quot;lng&quot;:1.4442},&quot;title&quot;:&quot;Toulouse&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Toulouse&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;e6b3acef1325fb52&quot;}]" 
-                data-map-polygons-value="[{&quot;points&quot;:[{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},{&quot;lat&quot;:45.75,&quot;lng&quot;:4.85},{&quot;lat&quot;:43.6047,&quot;lng&quot;:1.4442}],&quot;title&quot;:null,&quot;infoWindow&quot;:null,&quot;extra&quot;:[],&quot;@id&quot;:&quot;228ae6f5c1b17cfd&quot;},{&quot;points&quot;:[{&quot;lat&quot;:1.4442,&quot;lng&quot;:43.6047},{&quot;lat&quot;:4.85,&quot;lng&quot;:45.75},{&quot;lat&quot;:2.3522,&quot;lng&quot;:48.8566}],&quot;title&quot;:null,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Polygon&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:{&quot;foo&quot;:&quot;bar&quot;}},&quot;extra&quot;:{&quot;fillColor&quot;:&quot;#ff0000&quot;},&quot;@id&quot;:&quot;9874334e4e8caa16&quot;}]" 
+            <div
+                data-testid="map"
+                data-controller="map"
+                data-map-provider-options-value="{}"
+                data-map-center-value="{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522}"
+                data-map-zoom-value="4"
+                data-map-fit-bounds-to-markers-value="false"
+                data-map-options-value="{}"
+                data-map-markers-value="[{&quot;position&quot;:{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},&quot;title&quot;:&quot;Paris&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Paris&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;a69f13edd2e571f3&quot;},{&quot;position&quot;:{&quot;lat&quot;:45.75,&quot;lng&quot;:4.85},&quot;title&quot;:&quot;Lyon&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Lyon&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;cb9c1a30d562694b&quot;},{&quot;position&quot;:{&quot;lat&quot;:43.6047,&quot;lng&quot;:1.4442},&quot;title&quot;:&quot;Toulouse&quot;,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Toulouse&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:[]},&quot;extra&quot;:[],&quot;@id&quot;:&quot;e6b3acef1325fb52&quot;}]"
+                data-map-polygons-value="[{&quot;points&quot;:[{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},{&quot;lat&quot;:45.75,&quot;lng&quot;:4.85},{&quot;lat&quot;:43.6047,&quot;lng&quot;:1.4442}],&quot;title&quot;:null,&quot;infoWindow&quot;:null,&quot;extra&quot;:[],&quot;@id&quot;:&quot;228ae6f5c1b17cfd&quot;},{&quot;points&quot;:[{&quot;lat&quot;:1.4442,&quot;lng&quot;:43.6047},{&quot;lat&quot;:4.85,&quot;lng&quot;:45.75},{&quot;lat&quot;:2.3522,&quot;lng&quot;:48.8566}],&quot;title&quot;:null,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Polygon&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:{&quot;foo&quot;:&quot;bar&quot;}},&quot;extra&quot;:{&quot;fillColor&quot;:&quot;#ff0000&quot;},&quot;@id&quot;:&quot;9874334e4e8caa16&quot;}]"
                 data-map-polylines-value="[{&quot;points&quot;:[{&quot;lat&quot;:48.1173,&quot;lng&quot;:-1.6778},{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},{&quot;lat&quot;:48.2082,&quot;lng&quot;:16.3738}],&quot;title&quot;:null,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Polyline&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:{&quot;foo&quot;:&quot;bar&quot;}},&quot;extra&quot;:{&quot;strokeColor&quot;:&quot;#ff0000&quot;},&quot;@id&quot;:&quot;0fa955da866c7720&quot;}]"
+                data-map-circles-value="[{&quot;center&quot;:{&quot;lat&quot;:48.8566,&quot;lng&quot;:2.3522},&quot;title&quot;:null,&quot;infoWindow&quot;:{&quot;headerContent&quot;:&quot;Circle&quot;,&quot;content&quot;:null,&quot;position&quot;:null,&quot;opened&quot;:false,&quot;autoClose&quot;:true,&quot;extra&quot;:{&quot;foo&quot;:&quot;bar&quot;}},&quot;extra&quot;:{&quot;color&quot;:&quot;#ff0000&quot;, &quot;radii&quot;:1000},&quot;@id&quot;:&quot;7c3e1a9b5f2d4e81&quot;}]"
                 style="height: 600px"
             ></div>
         `);
@@ -92,7 +105,7 @@ describe('AbstractMapController', () => {
         clearDOM();
     });
 
-    it('connect and create map, marker, polygon, polyline and info window', async () => {
+    it('connect and create map, marker, polygon, polyline, circle and info window', async () => {
         const div = getByTestId(container, 'map');
         expect(div).not.toHaveClass('connected');
 
@@ -115,7 +128,7 @@ describe('AbstractMapController', () => {
             ])
         );
         expect(controller.polylines).toEqual(new Map([['0fa955da866c7720', { polyline: 'polyline', title: null }]]));
-        expect(controller.infoWindows).toEqual([
+        expect(controller.circles).toEqual(new Map([['7c3e1a9b5f2d4e81', { circle: 'circle', title: null }]]));        expect(controller.infoWindows).toEqual([
             {
                 headerContent: 'Paris',
                 infoWindow: 'infoWindow',
@@ -141,6 +154,11 @@ describe('AbstractMapController', () => {
                 infoWindow: 'infoWindow',
                 polyline: null,
             },
+            {
+                headerContent: 'Circle',
+                infoWindow: 'infoWindow',
+                circle: null,
+            },
         ]);
     });
 });

src/Map/doc/index.rst

@@ -208,21 +208,37 @@ You can add Polylines, which represents a path made by a series of ``Point`` ins
         ),
     ));
 
+Add Circles
+~~~~~~~~~~
+
+You can add Circles, which represents a circular area defined by a center point and a radius (in meters)::
+
+    $map->addCircle(new Circle(
+        center: new Point(48.8566, 2.3522),
+        radius: 5000, // 5km radius
+        title: 'Paris',
+        infoWindow: new InfoWindow(
+            content: 'A 5km radius circle centered on Paris',
+        ),
+    ));
+
 Remove elements from Map
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is possible to remove elements like ``Marker``, ``Polygon`` and ``Polyline`` instances by using ``Map::remove*()`` methods.
+It is possible to remove elements like ``Marker``, ``Polygon``, ``Polyline`` and ``Circle`` instances by using ``Map::remove*()`` methods.
 It's useful when :ref:`using a Map inside a Live Component <map-live-component>`::
 
     // Add elements
     $map->addMarker($marker = new Marker(/* ... */));
     $map->addPolygon($polygon = new Polygon(/* ... */));
     $map->addPolyline($polyline = new Polyline(/* ... */));
+    $map->addCircle($circle = new Circle(/* ... */));
 
     // And later, remove those elements
     $map->removeMarker($marker);
     $map->removePolygon($polygon);
     $map->removePolyline($polyline);
+    $map->removeCircle($circle);
 
 If you haven't stored the element instance, you can still remove them by passing the identifier string::
 

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

@@ -17,6 +17,7 @@ import type {
     Point,
     PolygonDefinition,
     PolylineDefinition,
+    CircleDefinition,
 } from '@symfony/ux-map';
 
 type MapOptions = Pick<
@@ -49,7 +50,9 @@ export default class extends AbstractMapController<
     google.maps.PolygonOptions,
     google.maps.Polygon,
     google.maps.PolylineOptions,
-    google.maps.Polyline
+    google.maps.Polyline,
+    google.maps.CircleOptions,
+    google.maps.Circle
 > {
     declare providerOptionsValue: Pick<
         LoaderOptions,
@@ -226,6 +229,35 @@ export default class extends AbstractMapController<
         polyline.setMap(null);
     }
 
+    protected doCreateCircle({
+        definition,
+    }: {
+        definition: CircleDefinition<google.maps.CircleOptions, google.maps.InfoWindowOptions>;
+    }): google.maps.Circle {
+        const { '@id': _id, center, radius, title, infoWindow, rawOptions = {} } = definition;
+
+        const circle = new _google.maps.Circle({
+            ...rawOptions,
+            center,
+            radius,
+            map: this.map,
+        });
+
+        if (title) {
+            circle.set('title', title);
+        }
+
+        if (infoWindow) {
+            this.createInfoWindow({ definition: infoWindow, element: circle });
+        }
+
+        return circle;
+    }
+
+    protected doRemoveCircle(circle: google.maps.Circle): void {
+        circle.setMap(null);
+    }
+
     protected doCreateInfoWindow({
         definition,
         element,