[Map] Rework SvgIcon and factory method name, UX Icon to get generated HTML, and icons rendering

Author: Kocal

assets/dist/abstract_map_controller.d.ts

@@ -9,16 +9,23 @@ export type WithIdentifier<T extends Record<string, unknown>> = T & {
 };
 export declare const IconTypes: {
     readonly Url: "url";
-    readonly InlineSvg: "inline-svg";
+    readonly Svg: "svg";
     readonly UxIcon: "ux-icon";
 };
-export type IconType = (typeof IconTypes)[keyof typeof IconTypes];
 export type Icon = {
-    content: string;
-    type: IconType;
     width: number;
     height: number;
-};
+} & ({
+    type: typeof IconTypes.UxIcon;
+    name: string;
+    _generated_html: string;
+} | {
+    type: typeof IconTypes.Url;
+    url: string;
+} | {
+    type: typeof IconTypes.Svg;
+    html: string;
+});
 export type MarkerDefinition<MarkerOptions, InfoWindowOptions> = WithIdentifier<{
     position: Point;
     title: string | null;

assets/dist/abstract_map_controller.js

@@ -2,7 +2,7 @@ import { Controller } from '@hotwired/stimulus';
 
 const IconTypes = {
     Url: 'url',
-    InlineSvg: 'inline-svg',
+    Svg: 'svg',
     UxIcon: 'ux-icon',
 };
 class default_1 extends Controller {

assets/src/abstract_map_controller.ts

@@ -6,16 +6,27 @@ export type WithIdentifier<T extends Record<string, unknown>> = T & { '@id': Ide
 
 export const IconTypes = {
     Url: 'url',
-    InlineSvg: 'inline-svg',
+    Svg: 'svg',
     UxIcon: 'ux-icon',
 } as const;
-export type IconType = (typeof IconTypes)[keyof typeof IconTypes];
 export type Icon = {
-    content: string;
-    type: IconType;
     width: number;
     height: number;
-};
+} & (
+    | {
+          type: typeof IconTypes.UxIcon;
+          name: string;
+          _generated_html: string,
+      }
+    | {
+          type: typeof IconTypes.Url;
+          url: string;
+      }
+    | {
+          type: typeof IconTypes.Svg;
+          html: string;
+      }
+    );
 
 export type MarkerDefinition<MarkerOptions, InfoWindowOptions> = WithIdentifier<{
     position: Point;

doc/index.rst

@@ -141,15 +141,12 @@ Add Marker icons
 
 A ``Marker`` can be customized with an ``Icon`` instance, which can either be an UX Icon, an URL, or a SVG content::
 
-        // It can be a UX Icon (requires `symfony/ux-icons` package)
-        $icon = Icon::ux('fa:map-marker');
-        // Or an URL pointing to an image
-        $icon = Icon::url('https://example.com/marker.png');
-        // Or a plain SVG content
-        $icon = Icon::svg('<svg>(...)</svg>');
-
-        // Configure the icon size with the `width()` and `height()` methods
-        $icon = Icon::ux('fa:map-marker')->width(48)->height(48);
+        // It can be a UX Icon (requires `symfony/ux-icons` package)...
+        $icon = Icon::ux('fa:map-marker')->width(24)->height(24);
+        // ... or an URL pointing to an image
+        $icon = Icon::url('https://example.com/marker.png')->width(24)->height(24);
+        // ... or a plain SVG string
+        $icon = Icon::svg('<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24">...</svg>');
 
         $map->addMarker(new Marker(
             // ...

src/Icon/Icon.php

@@ -22,6 +22,8 @@
 abstract class Icon
 {
     /**
+     * Creates a new icon based on a URL (e.g.: `https://cdn.jsdelivr.net/npm/[email protected]/icons/geo-alt.svg`).
+     *
      * @param non-empty-string $url
      */
     public static function url(string $url): UrlIcon
@@ -30,6 +32,10 @@ public static function url(string $url): UrlIcon
     }
 
     /**
+     * Creates a new icon based on an SVG string (e.g.: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24">...</svg>`).
+     * Using an SVG string may not be the best option if you want to customize the icon afterward,
+     * it would be preferable to use {@see Icon::ux()} or {@see Icon::url()} instead.
+     *
      * @param non-empty-string $html
      */
     public static function svg(string $html): SvgIcon
@@ -38,6 +44,8 @@ public static function svg(string $html): SvgIcon
     }
 
     /**
+     * Creates a new icon based on a UX icon name (e.g.: `fa:map-marker`).
+     *
      * @param non-empty-string $name
      */
     public static function ux(string $name): UxIcon
@@ -56,23 +64,25 @@ protected function __construct(
     ) {
     }
 
+    /**
+     * Sets the width of the icon.
+     *
+     * @param positive-int $width
+     */
     public function width(int $width): static
     {
-        if ($width <= 0) {
-            throw new InvalidArgumentException('Width must be greater than 0.');
-        }
-
         $this->width = $width;
 
         return $this;
     }
 
+    /**
+     * Sets the height of the icon.
+     *
+     * @param positive-int $height
+     */
     public function height(int $height): static
     {
-        if ($height <= 0) {
-            throw new InvalidArgumentException('Height must be greater than 0.');
-        }
-
         $this->height = $height;
 
         return $this;

src/Icon/SvgIcon.php

@@ -23,29 +23,39 @@ class SvgIcon extends Icon
 {
     /**
      * @param non-empty-string $html
-     * @param positive-int     $width
-     * @param positive-int     $height
      */
     protected function __construct(
         protected string $html,
-        int $width = 24,
-        int $height = 24,
     ) {
-        parent::__construct(IconType::Svg, $width, $height);
+        parent::__construct(IconType::Svg);
     }
 
     /**
-     * @param array{ html: string, width: positive-int, height: positive-int } $data
+     * @param array{ html: string } $data
      */
     public static function fromArray(array $data): static
     {
         return new self(
             html: $data['html'],
-            width: $data['width'],
-            height: $data['height'],
         );
     }
 
+    /**
+     * @throws \LogicException the SvgIcon can not be customized
+     */
+    public function width(int $width): never
+    {
+        throw new \LogicException('Unable to configure the SvgIcon width, please configure it in the HTML with the "width" attribute on the root element instead.');
+    }
+
+    /**
+     * @throws \LogicException the SvgIcon can not be customized
+     */
+    public function height(int $height): never
+    {
+        throw new \LogicException('Unable to configure the SvgIcon height, please configure it in the HTML with the "height" attribute on the root element instead.');
+    }
+
     public function toArray(): array
     {
         return [

src/Icon/UxIconRenderer.php

@@ -25,14 +25,18 @@ public function __construct(
     ) {
     }
 
-    public function render(string $name): string
+    /**
+     * @param array<string, string|bool> $attributes
+     */
+    public function render(string $name, array $attributes = []): string
     {
         if (null === $this->renderer) {
             throw new \LogicException('You cannot use an UX Icon as the "UX Icons" package is not installed. Try running "composer require symfony/ux-icons" to install it.');
         }
 
         return $this->renderer->renderIcon($name, [
             'xmlns' => 'http://www.w3.org/2000/svg',
+            ...$attributes,
         ]);
     }
 }

src/Marker.php

@@ -13,6 +13,7 @@
 
 use Symfony\UX\Map\Exception\InvalidArgumentException;
 use Symfony\UX\Map\Icon\Icon;
+use Symfony\UX\Map\Icon\IconType;
 
 /**
  * Represents a marker on a map.
@@ -40,7 +41,7 @@ public function __construct(
      *     position: array{lat: float, lng: float},
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
-     *     icon: Icon|null,
+     *     icon: array{type: value-of<IconType>, width: positive-int, height: positive-int, ...}|null,
      *     extra: array,
      *     id: string|null
      * }
@@ -62,7 +63,7 @@ public function toArray(): array
      *     position: array{lat: float, lng: float},
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
-     *     icon: array<string, mixed>||null,
+     *     icon: array{type: value-of<IconType>, width: positive-int, height: positive-int, ...}|null,
      *     extra: array,
      *     id: string|null
      * } $marker

src/Renderer/AbstractRenderer.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\UX\Map\Renderer;
 
+use Symfony\UX\Map\Icon\IconType;
 use Symfony\UX\Map\Icon\UxIconRenderer;
 use Symfony\UX\Map\Map;
 use Symfony\UX\Map\MapOptionsInterface;
@@ -23,7 +24,7 @@
 {
     public function __construct(
         private StimulusHelper $stimulus,
-        private ?UxIconRenderer $uxIconRenderer = null,
+        private UxIconRenderer $uxIconRenderer,
     ) {
     }
 
@@ -92,9 +93,11 @@ private function getMapAttributes(Map $map): array
 
         foreach ($attrs['markers'] as $key => $marker) {
             $attrs['markers'][$key]['@id'] = $computeId($marker);
-            if (null !== $this->uxIconRenderer && null !== $marker['icon'] && 'ux-icon' === $marker['icon']['type']) {
-                $attrs['markers'][$key]['icon']['content'] = $this->uxIconRenderer->render($marker['icon']['content']);
-                $attrs['markers'][$key]['icon']['type'] = 'inline-svg';
+            if (isset($marker['icon']['type']) && IconType::UxIcon->value === $marker['icon']['type']) {
+                $attrs['markers'][$key]['icon']['_generated_html'] = $this->uxIconRenderer->render($marker['icon']['name'], [
+                    'width' => $marker['icon']['width'],
+                    'height' => $marker['icon']['height'],
+                ]);
             }
         }
         foreach ($attrs['polygons'] as $key => $polygon) {

tests/IconTest.php

@@ -63,4 +63,38 @@ public function testFromArray(Icon $icon, string $expectedInstance, array $expec
     {
         self::assertEquals($icon, Icon::fromArray($expectedToArray));
     }
+
+    public static function dataProviderForTestSvgIconCustomizationMethodsCanNotBeCalled(): iterable
+    {
+        $refl = new \ReflectionClass(SvgIcon::class);
+        $customizationMethods = array_diff(
+            array_map(
+                fn (\ReflectionMethod $method) => $method->name,
+                array_filter($refl->getMethods(\ReflectionMethod::IS_PUBLIC), fn (\ReflectionMethod $method) => SvgIcon::class === $method->getDeclaringClass()->getName())
+            ),
+            ['toArray', 'fromArray']
+        );
+
+        foreach ($customizationMethods as $method) {
+            if (\in_array($method, ['width', 'height'], true)) {
+                yield $method => [$method, 12];
+            } elseif (\in_array($method, $customizationMethods, true)) {
+                throw new \LogicException(\sprintf('The "%s" method is not supposed to be called on the SvgIcon, please modify the test provider.', $method));
+            }
+        }
+    }
+
+    /**
+     * @dataProvider dataProviderForTestSvgIconCustomizationMethodsCanNotBeCalled
+     */
+    public function testSvgIconCustomizationMethodsCanNotBeCalled(string $method, mixed ...$args): void
+    {
+        $this->expectException(\LogicException::class);
+        if (\in_array($method, ['width', 'height'], true)) {
+            $this->expectExceptionMessage(\sprintf('Unable to configure the SvgIcon %s, please configure it in the HTML with the "%s" attribute on the root element instead.', $method, $method));
+        }
+
+        $icon = Icon::svg('<svg></svg>');
+        $icon->{$method}(...$args);
+    }
 }