feature #2117 [Map] Render map from Twig with ux_map() and <twig:ux:map /> (smnandre)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[Map] Render map from Twig with `ux_map()` and  `<twig:ux:map />`

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Issues        | Fix #...
| License       | MIT

* ~~add an MapFactory (internal)~~
* allow `ux_map` Twig function to render map from named arguments
* add basic TwigComponent `<twig:ux:map ... />`

### Create Map from Twig

```twig

{{ ux_map(
    center: [51.5074, 0.1278],
    zoom: 3,
    markers:  [
        { position: [51.5074, 0.1278], title: 'London' },
        { position: [48.8566, 2.3522], title: 'Paris' },
        {
            position: [40.7128, -74.0060],
            title: 'New York',
            infoWindow: { content: 'Welcom to <b>New York</b>' }
        },
    ],
    attributes: {
        class: 'foo',
        style: 'height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;',
    }
) }}

```

![ux-map](https://github.com/user-attachments/assets/2d127863-c159-4024-9266-c12609460534)

Commits
-------

92f89d3 [Map] Render map from Twig with `ux_map()` and  `<twig:ux:map />`

Author: Kocal

src/Map/CHANGELOG.md

@@ -2,8 +2,11 @@
 
 ## 2.20
 
--   Rename `render_map` Twig function `ux_map`
--   Deprecate `render_map` Twig function
+-   Deprecate `render_map` Twig function (will be removed in 2.21). Use 
+    `ux_map` or the `<twig:ux:map />` Twig component instead.
+-   Add `ux_map` Twig function (replaces `render_map` with a more flexible 
+    interface)
+-   Add `<twig:ux:map />` Twig component
 
 ## 2.19
 

src/Map/composer.json

@@ -39,7 +39,8 @@
         "symfony/asset-mapper": "^6.4|^7.0",
         "symfony/framework-bundle": "^6.4|^7.0",
         "symfony/phpunit-bridge": "^6.4|^7.0",
-        "symfony/twig-bundle": "^6.4|^7.0"
+        "symfony/twig-bundle": "^6.4|^7.0",
+        "symfony/ux-twig-component": "^2.18"
     },
     "extra": {
         "thanks": {

src/Map/config/services.php

@@ -15,6 +15,7 @@
 use Symfony\UX\Map\Renderer\Renderer;
 use Symfony\UX\Map\Renderer\Renderers;
 use Symfony\UX\Map\Twig\MapExtension;
+use Symfony\UX\Map\Twig\MapRuntime;
 
 /*
  * @author Hugo Alliaume <[email protected]>
@@ -26,7 +27,6 @@
             ->args([
                 abstract_arg('renderers configuration'),
             ])
-            ->tag('twig.runtime')
 
         ->set('ux_map.renderer_factory.abstract', AbstractRendererFactory::class)
             ->abstract()
@@ -41,5 +41,11 @@
 
         ->set('ux_map.twig_extension', MapExtension::class)
             ->tag('twig.extension')
+
+        ->set('ux_map.twig_runtime', MapRuntime::class)
+            ->args([
+                service('ux_map.renderers'),
+            ])
+            ->tag('twig.runtime')
     ;
 };

src/Map/config/twig_component.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use Symfony\UX\Map\Twig\UXMapComponent;
+use Symfony\UX\Map\Twig\UXMapComponentListener;
+use Symfony\UX\TwigComponent\Event\PreCreateForRenderEvent;
+
+return static function (ContainerConfigurator $container): void {
+    $container->services()
+        ->set('.ux_map.twig_component_listener', UXMapComponentListener::class)
+            ->args([
+                service('ux_map.twig_runtime'),
+            ])
+            ->tag('kernel.event_listener', [
+                'event' => PreCreateForRenderEvent::class,
+                'method' => 'onPreCreateForRender',
+            ])
+
+        ->set('.ux_map.twig_component.map', UXMapComponent::class)
+            ->tag('twig.component', ['key' => 'UX:Map'])
+    ;
+};

src/Map/src/InfoWindow.php

@@ -19,7 +19,8 @@
 final readonly class InfoWindow
 {
     /**
-     * @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<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 ?string $headerContent = null,
@@ -31,6 +32,16 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @return array{
+     *     headerContent: string|null,
+     *     content: string|null,
+     *     position: array{lat: float, lng: float}|null,
+     *     opened: bool,
+     *     autoClose: bool,
+     *     extra: object,
+     * }
+     */
     public function toArray(): array
     {
         return [
@@ -42,4 +53,25 @@ public function toArray(): array
             'extra' => (object) $this->extra,
         ];
     }
+
+    /**
+     * @param array{
+     *     headerContent: string|null,
+     *     content: string|null,
+     *     position: array{lat: float, lng: float}|null,
+     *     opened: bool,
+     *     autoClose: bool,
+     *     extra: object,
+     * } $data
+     *
+     * @internal
+     */
+    public static function fromArray(array $data): self
+    {
+        if (isset($data['position'])) {
+            $data['position'] = Point::fromArray($data['position']);
+        }
+
+        return new self(...$data);
+    }
 }

src/Map/src/Map.php

@@ -103,4 +103,36 @@ public function toArray(): array
             'markers' => array_map(static fn (Marker $marker) => $marker->toArray(), $this->markers),
         ];
     }
+
+    /**
+     * @param array{
+     *     center?: array{lat: float, lng: float},
+     *     zoom?: float,
+     *     markers?: list<array>,
+     *     fitBoundsToMarkers?: bool,
+     *     options?: object,
+     * } $map
+     *
+     * @internal
+     */
+    public static function fromArray(array $map): self
+    {
+        $map['fitBoundsToMarkers'] = true;
+
+        if (isset($map['center'])) {
+            $map['center'] = Point::fromArray($map['center']);
+        }
+
+        if (isset($map['zoom']) || isset($map['center'])) {
+            $map['fitBoundsToMarkers'] = false;
+        }
+
+        $map['markers'] ??= [];
+        if (!\is_array($map['markers'])) {
+            throw new InvalidArgumentException('The "markers" parameter must be an array.');
+        }
+        $map['markers'] = array_map(Marker::fromArray(...), $map['markers']);
+
+        return new self(...$map);
+    }
 }

src/Map/src/Marker.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\UX\Map;
 
+use Symfony\UX\Map\Exception\InvalidArgumentException;
+
 /**
  * Represents a marker on a map.
  *
@@ -19,7 +21,8 @@
 final readonly class Marker
 {
     /**
-     * @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<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 Point $position,
@@ -29,6 +32,14 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @return array{
+     *     position: array{lat: float, lng: float},
+     *     title: string|null,
+     *     infoWindow: array<string, mixed>|null,
+     *     extra: object,
+     * }
+     */
     public function toArray(): array
     {
         return [
@@ -38,4 +49,28 @@ public function toArray(): array
             'extra' => (object) $this->extra,
         ];
     }
+
+    /**
+     * @param array{
+     *     position: array{lat: float, lng: float},
+     *     title: string|null,
+     *     infoWindow: array<string, mixed>|null,
+     *     extra: object,
+     * } $marker
+     *
+     * @internal
+     */
+    public static function fromArray(array $marker): self
+    {
+        if (!isset($marker['position'])) {
+            throw new InvalidArgumentException('The "position" parameter is required.');
+        }
+        $marker['position'] = Point::fromArray($marker['position']);
+
+        if (isset($marker['infoWindow'])) {
+            $marker['infoWindow'] = InfoWindow::fromArray($marker['infoWindow']);
+        }
+
+        return new self(...$marker);
+    }
 }

src/Map/src/Point.php

@@ -43,4 +43,16 @@ public function toArray(): array
             'lng' => $this->longitude,
         ];
     }
+
+    /**
+     * @param array{lat: float, lng: float}|array{0: float, 1: float} $point
+     */
+    public static function fromArray(array $point): self
+    {
+        if (isset($point['lat'], $point['lng'])) {
+            return new self($point['lat'], $point['lng']);
+        }
+
+        return new self(...$point);
+    }
 }

src/Map/src/Twig/MapExtension.php

@@ -11,7 +11,6 @@
 
 namespace Symfony\UX\Map\Twig;
 
-use Symfony\UX\Map\Renderer\Renderers;
 use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
@@ -26,13 +25,13 @@ final class MapExtension extends AbstractExtension
     public function getFunctions(): array
     {
         return [
-            new TwigFunction('render_map', [Renderers::class, 'renderMap'], [
+            new TwigFunction('render_map', [MapRuntime::class, 'renderMap'], [
                 'is_safe' => ['html'],
                 ...(class_exists(DeprecatedCallableInfo::class)
                     ? ['deprecation_info' => new DeprecatedCallableInfo('symfony/ux-map', '2.20', 'ux_map')]
                     : ['deprecated' => '2.20', 'deprecating_package' => 'symfony/ux-map', 'alternative' => 'ux_map']),
             ]),
-            new TwigFunction('ux_map', [Renderers::class, 'renderMap'], ['is_safe' => ['html']]),
+            new TwigFunction('ux_map', [MapRuntime::class, 'renderMap'], ['is_safe' => ['html']]),
         ];
     }
 }

src/Map/src/Twig/MapRuntime.php

@@ -0,0 +1,64 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Twig;
+
+use Symfony\UX\Map\Map;
+use Symfony\UX\Map\Marker;
+use Symfony\UX\Map\Point;
+use Symfony\UX\Map\Renderer\RendererInterface;
+use Twig\Extension\RuntimeExtensionInterface;
+
+/**
+ * @author Simon André <[email protected]>
+ *
+ * @internal
+ */
+final class MapRuntime implements RuntimeExtensionInterface
+{
+    public function __construct(
+        private readonly RendererInterface $renderer,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $attributes
+     * @param array<string, mixed> $markers
+     */
+    public function renderMap(
+        ?Map $map = null,
+        array $attributes = [],
+        ?array $markers = null,
+        ?array $center = null,
+        ?float $zoom = null,
+    ): string {
+        if ($map instanceof Map) {
+            if (null !== $center || null !== $zoom || $markers) {
+                throw new \InvalidArgumentException('You cannot set "center", "markers" or "zoom" on an existing Map.');
+            }
+
+            return $this->renderer->renderMap($map, $attributes);
+        }
+
+        $map = new Map();
+        foreach ($markers ?? [] as $marker) {
+            $map->addMarker(Marker::fromArray($marker));
+        }
+        if (null !== $center) {
+            $map->center(Point::fromArray($center));
+        }
+        if (null !== $zoom) {
+            $map->zoom($zoom);
+        }
+
+        return $this->renderer->renderMap($map, $attributes);
+    }
+}