Introduce stimulus_controller to ease Stimulus Values API usage

Author: tgalopin

src/Resources/config/services.xml

@@ -36,6 +36,10 @@
             </argument>
         </service>
 
+        <service id="webpack_encore.twig_stimulus_extension" class="Symfony\WebpackEncoreBundle\Twig\StimulusTwigExtension">
+            <tag name="twig.extension" />
+        </service>
+
         <service id="webpack_encore.entrypoint_lookup.cache_warmer" class="Symfony\WebpackEncoreBundle\CacheWarmer\EntrypointCacheWarmer">
             <tag name="kernel.cache_warmer" />
             <argument /> <!-- build list of entrypoint paths -->

src/Twig/StimulusTwigExtension.php

@@ -0,0 +1,77 @@
+<?php
+
+/*
+ * This file is part of the Symfony WebpackEncoreBundle 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\WebpackEncoreBundle\Twig;
+
+use Twig\Environment;
+use Twig\Extension\AbstractExtension;
+use Twig\TwigFunction;
+
+final class StimulusTwigExtension extends AbstractExtension
+{
+    public function getFunctions()
+    {
+        return [
+            new TwigFunction('stimulus_controller', [$this, 'renderStimulusController'], ['needs_environment' => true, 'is_safe' => ['all']]),
+        ];
+    }
+
+    public function renderStimulusController(Environment $env, array $data): string
+    {
+        if (!$data) {
+            return '';
+        }
+
+        $controllers = [];
+        $values = [];
+
+        foreach ($data as $controllerName => $controllerValues) {
+            $controllerName = twig_escape_filter($env, $this->normalizeControllerName($controllerName), 'html_attr');
+            $controllers[] = $controllerName;
+
+            foreach ($controllerValues as $key => $value) {
+                if (!is_scalar($value)) {
+                    $value = json_encode($value);
+                }
+
+                $key = twig_escape_filter($env, $this->normalizeKeyName($key), 'html_attr');
+                $value = twig_escape_filter($env, $value, 'html_attr');
+
+                $values[] = 'data-'.$controllerName.'-'.$key.'-value="'.$value.'"';
+            }
+        }
+
+        return rtrim('data-controller="'.implode(' ', $controllers).'" '.implode(' ', $values));
+    }
+
+    /**
+     * Normalize a Stimulus controller name into its HTML equivalent (no special character and / becomes --).
+     *
+     * @see https://stimulus.hotwire.dev/reference/controllers
+     */
+    private function normalizeControllerName(string $str): string
+    {
+        return preg_replace('/^@/', '', str_replace('_', '-', str_replace('/', '--', $str)));
+    }
+
+    /**
+     * Normalize a Stimulus Value API key into its HTML equivalent ("kebab case").
+     * Backport features from symfony/string.
+     *
+     * @see https://stimulus.hotwire.dev/reference/values
+     */
+    private function normalizeKeyName(string $str): string
+    {
+        // Adapted from ByteString::camel
+        $str = ucfirst(str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $str))));
+
+        // Adapted from ByteString::snake
+        return strtolower(preg_replace(['/([A-Z]+)([A-Z][a-z])/', '/([a-z\d])([A-Z])/'], '\1-\2', $str));
+    }
+}

tests/IntegrationTest.php

@@ -28,6 +28,7 @@
 use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;
 use Symfony\WebpackEncoreBundle\Asset\TagRenderer;
 use Symfony\WebpackEncoreBundle\CacheWarmer\EntrypointCacheWarmer;
+use Symfony\WebpackEncoreBundle\Twig\StimulusTwigExtension;
 use Symfony\WebpackEncoreBundle\WebpackEncoreBundle;
 
 class IntegrationTest extends TestCase
@@ -178,6 +179,84 @@ public function testAutowireDefaultBuildArgument()
         $this->assertTrue(true);
     }
 
+    public function provideRenderStimulusController()
+    {
+        yield 'empty' => [
+            'data' => [],
+            'expected' => '',
+        ];
+
+        yield 'single-controller-no-data' => [
+            'data' => [
+                'my-controller' => [],
+            ],
+            'expected' => 'data-controller="my-controller"',
+        ];
+
+        yield 'single-controller-scalar-data' => [
+            'data' => [
+                'my-controller' => [
+                    'myValue' => 'scalar-value',
+                ],
+            ],
+            'expected' => 'data-controller="my-controller" data-my-controller-my-value-value="scalar-value"',
+        ];
+
+        yield 'single-controller-typed-data' => [
+            'data' => [
+                'my-controller' => [
+                    'boolean' => true,
+                    'number' => 4,
+                    'string' => 'str',
+                ],
+            ],
+            'expected' => 'data-controller="my-controller" data-my-controller-boolean-value="1" data-my-controller-number-value="4" data-my-controller-string-value="str"',
+        ];
+
+        yield 'single-controller-nested-data' => [
+            'data' => [
+                'my-controller' => [
+                    'myValue' => ['nested' => 'array'],
+                ],
+            ],
+            'expected' => 'data-controller="my-controller" data-my-controller-my-value-value="{"nested":"array"}"',
+        ];
+
+        yield 'multiple-controllers-scalar-data' => [
+            'data' => [
+                'my-controller' => [
+                    'myValue' => 'scalar-value',
+                ],
+                'another-controller' => [
+                    'anotherValue' => 'scalar-value 2',
+                ],
+            ],
+            'expected' => 'data-controller="my-controller another-controller" data-my-controller-my-value-value="scalar-value" data-another-controller-another-value-value="scalar-value 2"',
+        ];
+
+        yield 'normalize-names' => [
+            'data' => [
+                '@symfony/ux-dropzone/dropzone' => [
+                    'my"Key"' => true,
+                ],
+            ],
+            'expected' => 'data-controller="symfony--ux-dropzone--dropzone" data-symfony--ux-dropzone--dropzone-my-key-value="1"',
+        ];
+    }
+
+    /**
+     * @dataProvider provideRenderStimulusController
+     */
+    public function testRenderStimulusController(array $data, string $expected)
+    {
+        $kernel = new WebpackEncoreIntegrationTestKernel(true);
+        $kernel->boot();
+        $twig = $this->getTwigEnvironmentFromBootedKernel($kernel);
+
+        $extension = new StimulusTwigExtension();
+        $this->assertSame($expected, $extension->renderStimulusController($twig, $data));
+    }
+
     private function getContainerFromBootedKernel(WebpackEncoreIntegrationTestKernel $kernel)
     {
         if ($kernel::VERSION_ID >= 40100) {