feature #109 Introduce stimulus_controller to ease Stimulus Values API usage (tgalopin)

This PR was merged into the main branch.

Discussion
----------

Introduce stimulus_controller to ease Stimulus Values API usage

This PR introduces a `stimulus_controller` helper to ease the usage of [Stimulus Values API](https://stimulus.hotwire.dev/reference/values).

The Values API is very useful as it allows developers to store state on the DOM node and thus persist it, share it across controllers and build reusable controllers. Using the Values API as a way to configure a controller using data attributes is a very common pattern that we should encourage ("build primitive reusable and composable controllers instead of building a controller per page").

However it has a few drawbacks:

1/ It introduces a duplication of the scoped attributes:

```html
<div data-controller="symfony--ux-chartjs-chart"
    data-symfony--ux-chartjs-chart-data-value="..."
    data-symfony--ux-chartjs-chart-options-value="..."
....>
</div>
```

This can quickly become cumbersome and difficult to track.

2/ It creates its own convention on naming, if you declare a value using camel case, it will need to be passed using kebab case in the HTML:

```javascript
export default class extends Controller {
    static values = {
        myMessage: String,
    }

    connect() {
        this.element.textContent = this.myMessageValue;
    }
}
```

```html
<div data-controller="hello" data-hello-my-message-value="Hello"></div>
```

3/ It requires to manually encode nested structure in JSON in order to pass them to the controller

This PR improves upon these drawbacks: it introduces a helper you can use in your DOM node to render the controller to use, with optional values for this controller. These values will be encoded properly to be read by Stimulus natively (https://stimulus.hotwire.dev/reference/values#properties-and-attributes).

With a single controller:

```twig
<div {{ stimulus_controller({ 'chart': { 'data': [1, 2, 3, 4] } }) }}>
    Hello
</div>
```

With multiple controllers:

```twig
<div {{ stimulus_controller({
    'chart': {
        'data': [1, 2, 3, 4],
        'labels': ['January', 'February', 'March', 'April'],
    },
    'another-controller': {}
}) }}>
    Hello
</div>
```

It introduces a "standard" way to transfer data to Stimulus controllers that map well with the Values API and thus work out of the box.

Commits
-------

cfc0e50 Introduce stimulus_controller to ease Stimulus Values API usage

Author: weaverryan

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) {