[Map] Improve polygones-with-holes code and documentation

Author: Kocal

src/Map/CHANGELOG.md

@@ -2,7 +2,27 @@
 
 ## 2.26
 
-- Add MultiPolygon support. A MultiPolygon allows you to represent multiple polygons (possibly with holes or separate areas) as a single map element. See documentation for usage.
+-  Add support for creating `Polygon` with holes, by passing an array of `array<Point>` as `points` parameter to the `Polygon` constructor, e.g.:
+```php
+// Draw a polygon with a hole in it, on the French map
+$map->addPolygon(new Polygon(points: [
+    // First path, the outer boundary of the polygon
+    [
+        new Point(48.117266, -1.677792), // Rennes
+        new Point(50.629250, 3.057256), // Lille
+        new Point(48.573405, 7.752111), // Strasbourg
+        new Point(43.296482, 5.369780), // Marseille
+        new Point(44.837789, -0.579180), // Bordeaux
+    ],
+    // Second path, it will make a hole in the previous one
+    [
+        new Point(45.833619, 1.261105), // Limoges
+        new Point(45.764043, 4.835659), // Lyon
+        new Point(49.258329, 4.031696), // Reims
+        new Point(48.856613, 2.352222), // Paris
+    ],
+]));
+```
 
 ## 2.25
 

src/Map/doc/index.rst

@@ -71,7 +71,7 @@ Start by creating a new map instance::
     use Symfony\UX\Map\Map;
 
     // Create a new map instance
-    $myMap = (new Map());
+    $map = new Map();
 
 Center and zoom
 ~~~~~~~~~~~~~~~
@@ -81,7 +81,7 @@ You can set the center and zoom of the map using the ``center()`` and ``zoom()``
     use Symfony\UX\Map\Map;
     use Symfony\UX\Map\Point;
 
-    $myMap
+    $map
         // Explicitly set the center and zoom
         ->center(new Point(46.903354, 1.888334))
         ->zoom(6)
@@ -95,7 +95,7 @@ Add markers
 
 You can add markers to a map using the ``addMarker()`` method::
 
-    $myMap
+    $map
         ->addMarker(new Marker(
             position: new Point(48.8566, 2.3522),
             title: 'Paris'
@@ -154,7 +154,7 @@ Add Polygons
 
 You can also add Polygons, which represents an area enclosed by a series of ``Point`` instances::
 
-    $myMap->addPolygon(new Polygon(
+    $map->addPolygon(new Polygon(
         points: [
             new Point(48.8566, 2.3522),
             new Point(45.7640, 4.8357),
@@ -168,33 +168,35 @@ You can also add Polygons, which represents an area enclosed by a series of ``Po
 
 .. versionadded:: 2.26
 
-    ``MultiPolygon`` is available since UX Map 2.26.
+    `Polygon` with holes is available since UX Map 2.26.
 
-You can also add a MultiPolygon. A MultiPolygon allows you to represent multiple polygons (possibly with holes or separate areas) as a single map element::
+Since UX Map 2.26, you can also create polygons with holes in them, by passing an array of `array<Point>` to `points` parameter::
 
-    $myMap->addPolygon(new Polygon(
-        points: [
-          [
-              new Point(-180, 90),
-              new Point(180, 90),
-              new Point(180, -90),
-              new Point(-180, -90),
-          ],
-          [
-              new Point(48.8566, 2.3522),
-              new Point(45.7640, 4.8357),
-              new Point(43.2965, 5.3698),
-              new Point(44.8378, -0.5792),
-          ]
+    // Draw a polygon with a hole in it, on the French map
+    $map->addPolygon(new Polygon(points: [
+        // First path, the outer boundary of the polygon
+        [
+            new Point(48.117266, -1.677792), // Rennes
+            new Point(50.629250, 3.057256), // Lille
+            new Point(48.573405, 7.752111), // Strasbourg
+            new Point(43.296482, 5.369780), // Marseille
+            new Point(44.837789, -0.579180), // Bordeaux
         ],
-    ));
+        // Second path, it will make a hole in the previous one
+        [
+            new Point(45.833619, 1.261105), // Limoges
+            new Point(45.764043, 4.835659), // Lyon
+            new Point(49.258329, 4.031696), // Reims
+            new Point(48.856613, 2.352222), // Paris
+        ],
+    ]));
 
 Add Polylines
 ~~~~~~~~~~~~~
 
 You can add Polylines, which represents a path made by a series of ``Point`` instances::
 
-    $myMap->addPolyline(new Polyline(
+    $map->addPolyline(new Polyline(
         points: [
             new Point(48.8566, 2.3522),
             new Point(45.7640, 4.8357),

src/Map/src/Polygon.php

@@ -21,8 +21,8 @@
 final class Polygon implements Element
 {
     /**
-     * @param array<array<Point>|array<array<Point>>> $points Points of the polygon. Each point can be a single Point or an array of Points.
-     * @param array<string, mixed>                    $extra  Extra data, can be used by the developer to store additional information and use them later JavaScript side
+     * @param array<Point>|array<array<Point>> $points A list of point representing the polygon, or a list of paths (each path is an array of points) representing a polygon with holes.
+     * @param array<string, mixed>             $extra  Extra data, can be used by the developer to store additional information and use them later JavaScript side
      */
     public function __construct(
         private readonly array $points,
@@ -37,7 +37,7 @@ public function __construct(
      * Convert the polygon to an array representation.
      *
      * @return array{
-     *     points: array<array{lat: float, lng: float}|array<array{lat: float, lng: float}>>,
+     *     points: array<array{lat: float, lng: float}>|array<array{lat: float, lng: float}>,
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
      *     extra: array,
@@ -47,7 +47,9 @@ public function __construct(
     public function toArray(): array
     {
         return [
-            'points' => array_map(fn ($pointOrList) => \is_array($pointOrList) ? array_map(fn (Point $point) => $point->toArray(), $pointOrList) : $pointOrList->toArray(), $this->points),
+            'points' => current($this->points) instanceof Point
+                ? array_map(fn (Point $point) => $point->toArray(), $this->points)
+                : array_map(fn (array $path) => array_map(fn (Point $point) => $point->toArray(), $path), $this->points),
             'title' => $this->title,
             'infoWindow' => $this->infoWindow?->toArray(),
             'extra' => $this->extra,
@@ -72,8 +74,9 @@ public static function fromArray(array $polygon): self
             throw new InvalidArgumentException('The "points" parameter is required.');
         }
 
-        $isSinglePoint = isset($polygon['points'][0]['lat'], $polygon['points'][0]['lng']);
-        $polygon['points'] = array_map(fn ($pointOrList) => $isSinglePoint ? Point::fromArray($pointOrList) : array_map(Point::fromArray(...), $pointOrList), $polygon['points']);
+        $polygon['points'] = isset($polygon['points'][0]['lat'], $polygon['points'][0]['lng'])
+            ? array_map(Point::fromArray(...), $polygon['points'])
+            : array_map(fn(array $points) => array_map(Point::fromArray(...), $points), $polygon['points']);
 
         if (isset($polygon['infoWindow'])) {
             $polygon['infoWindow'] = InfoWindow::fromArray($polygon['infoWindow']);