feature #220 [WIP][TwigComponent] add component attribute system/helper (kbond)

This PR was merged into the 2.x branch.

Discussion
----------

[WIP][TwigComponent] add component attribute system/helper

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Tickets       | n/a
| License       | MIT

A common pattern with other component library's (ie blade components/vue) is to pass html attributes to your component that are set on the component's root node. This proposal adds a way to do this with twig components. Enable on your component by adding the `HasAttributesTrait`. Attributes are any data passed to `component()` that cannot be mounted on the component itself. This extra data is added to a `ComponentAttributes` object that lives as a public property on your component (available as `attributes` in your component's template).

This should all work out-of-the box with live components.

Todo:
- [x] Tests
- [x] Documentation
- [x] #240
- [x] #241
- [x] Merge `init_live_component()` into attributes when available
- [x] Document `PreRender` event.
- [x] Adjust `ComponentAttributes` api (defaults instead of merge)
- [ ] `attributes` always available in normal twig component templates (not sure about this - it would effectively make attributes _native_ but it a lame way)
- [x] replace `init_live_component()` with `attributes` in docs
- [x] Finalize docs (versionadded tags)

## Usage

To use, add the `HasAttributesTrait` to your component:

```php
#[AsTwigComponent('my_component')]
class MyComponent
{
    use HasAttributesTrait;
}
```

Then, in your component's template:

```twig
{# templates/components/my_component.html.twig #}

<div{{ attributes }}>
  My Component!
</div>
```

When rendering the component, you can pass an array of html attributes to add:

```twig
{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div class="foo" style="color:red">
  My Component!
</div>
```

### Defaults & Merging

In your component template, you can set defaults that are merged with
passed attributes. The passed attributes override the default with
the exception of *class*. For class, the defaults are prepended:

```twig
{# templates/components/my_component.html.twig #}

<button{{ attributes.defaults({ class: 'bar', type: 'button' }) }}>
  My Component!
</button>

{# render component #}
{{ component('my_component', { style: 'color:red' }) }}
{{ component('my_component', { class: 'foo', type: 'submit' }) }}

{# renders as: #}
<div class="bar" style="color:red">
  My Component!
</div>
<div class="bar foo" type="submit">
  My Component!
</div>
```

### Only

```twig
{# templates/components/my_component.html.twig #}

<div{{ attributes.only('class')) }}>
  My Component!
</div>

{# render component #}
{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div class="foo">
  My Component!
</div>
```

### Without

```twig
{# templates/components/my_component.html.twig #}

<div{{ attributes.without('class')) }}>
  My Component!
</div>

{# render component #}
{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div style="color:red">
  My Component!
</div>
```

### Live Components

We removed the `init_live_component()` twig function (**BC BREAK**) and replaced with the `attributes` variable which is always available (even if your component doesn't use `HasAttributesTrait`).

To upgrade, replace all calls to `init_live_component()` with `attributes`:

```diff
- <div {{ init_live_component() }}>
+ <div {{ attributes }}>
```

Commits
-------

d638782 [Twig][Live] add html attributes system

Author: weaverryan

src/LiveComponent/CHANGELOG.md

@@ -7,6 +7,12 @@
 
 -   Send live action arguments to backend
 
+-   [BC BREAK] Remove `init_live_component()` twig function, use `{{ attributes }}` instead:
+    ```diff
+    - <div {{ init_live_component() }}>
+    + <div {{ attributes }}>
+    ```
+
 ## 2.0.0
 
 -   Support for `stimulus` version 2 was removed and support for `@hotwired/stimulus`

src/LiveComponent/composer.json

@@ -27,7 +27,7 @@
     },
     "require": {
         "php": ">=8.0",
-        "symfony/ux-twig-component": "^2.0"
+        "symfony/ux-twig-component": "^2.1"
     },
     "require-dev": {
         "doctrine/annotations": "^1.0",

src/LiveComponent/src/DependencyInjection/LiveComponentExtension.php

@@ -21,6 +21,7 @@
 use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
 use Symfony\UX\LiveComponent\ComponentValidator;
 use Symfony\UX\LiveComponent\ComponentValidatorInterface;
+use Symfony\UX\LiveComponent\EventListener\AddLiveAttributesSubscriber;
 use Symfony\UX\LiveComponent\EventListener\LiveComponentSubscriber;
 use Symfony\UX\LiveComponent\LiveComponentHydrator;
 use Symfony\UX\LiveComponent\PropertyHydratorInterface;
@@ -46,6 +47,7 @@ function (ChildDefinition $definition, AsLiveComponent $attribute) {
                         'key' => $attribute->name,
                         'template' => $attribute->template,
                         'default_action' => $attribute->defaultAction,
+                        'live' => true,
                     ]))
                     ->addTag('controller.service_arguments')
                 ;
@@ -78,6 +80,7 @@ function (ChildDefinition $definition, AsLiveComponent $attribute) {
 
         $container->register('ux.live_component.twig.component_runtime', LiveComponentRuntime::class)
             ->setArguments([
+                new Reference('twig'),
                 new Reference('ux.live_component.component_hydrator'),
                 new Reference('ux.twig_component.component_factory'),
                 new Reference(UrlGeneratorInterface::class),
@@ -90,6 +93,11 @@ function (ChildDefinition $definition, AsLiveComponent $attribute) {
             ->addTag('container.service_subscriber', ['key' => 'validator', 'id' => 'validator'])
         ;
 
+        $container->register('ux.live_component.add_attributes_subscriber', AddLiveAttributesSubscriber::class)
+            ->addTag('kernel.event_subscriber')
+            ->addTag('container.service_subscriber', ['key' => LiveComponentRuntime::class, 'id' => 'ux.live_component.twig.component_runtime'])
+        ;
+
         $container->setAlias(ComponentValidatorInterface::class, ComponentValidator::class);
     }
 }

src/LiveComponent/src/EventListener/AddLiveAttributesSubscriber.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Symfony\UX\LiveComponent\EventListener;
+
+use Psr\Container\ContainerInterface;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Contracts\Service\ServiceSubscriberInterface;
+use Symfony\UX\LiveComponent\Twig\LiveComponentRuntime;
+use Symfony\UX\TwigComponent\ComponentAttributes;
+use Symfony\UX\TwigComponent\EventListener\PreRenderEvent;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+final class AddLiveAttributesSubscriber implements EventSubscriberInterface, ServiceSubscriberInterface
+{
+    public function __construct(private ContainerInterface $container)
+    {
+    }
+
+    public function onPreRender(PreRenderEvent $event): void
+    {
+        if (!$event->getMetadata()->get('live', false)) {
+            // not a live component, skip
+            return;
+        }
+
+        /** @var ComponentAttributes $attributes */
+        $attributes = $this->container->get(LiveComponentRuntime::class)
+            ->getLiveAttributes($event->getComponent(), $event->getMetadata())
+        ;
+
+        $variables = $event->getVariables();
+
+        if (isset($variables['attributes']) && $variables['attributes'] instanceof ComponentAttributes) {
+            // merge with existing attributes if available
+            $attributes = $attributes->defaults($variables['attributes']->all());
+        }
+
+        $variables['attributes'] = $attributes;
+
+        $event->setVariables($variables);
+    }
+
+    public static function getSubscribedEvents(): array
+    {
+        return [PreRenderEvent::class => 'onPreRender'];
+    }
+
+    public static function getSubscribedServices(): array
+    {
+        return [
+            LiveComponentRuntime::class,
+        ];
+    }
+}

src/LiveComponent/src/EventListener/LiveComponentSubscriber.php

@@ -31,6 +31,7 @@
 use Symfony\UX\LiveComponent\Attribute\LiveArg;
 use Symfony\UX\LiveComponent\LiveComponentHydrator;
 use Symfony\UX\TwigComponent\ComponentFactory;
+use Symfony\UX\TwigComponent\ComponentMetadata;
 use Symfony\UX\TwigComponent\ComponentRenderer;
 
 /**
@@ -73,24 +74,28 @@ public function onKernelRequest(RequestEvent $event): void
         $componentName = (string) $request->get('component');
 
         try {
-            $config = $this->container->get(ComponentFactory::class)->configFor($componentName);
+            /** @var ComponentMetadata $metadata */
+            $metadata = $this->container->get(ComponentFactory::class)->metadataFor($componentName);
         } catch (\InvalidArgumentException $e) {
             throw new NotFoundHttpException(sprintf('Component "%s" not found.', $componentName), $e);
         }
 
-        $request->attributes->set('_component_template', $config['template']);
+        if (!$metadata->get('live', false)) {
+            throw new NotFoundHttpException(sprintf('"%s" (%s) is not a Live Component.', $metadata->getClass(), $componentName));
+        }
+
+        $request->attributes->set('_component_metadata', $metadata);
 
         if ('get' === $action) {
-            $defaultAction = trim($config['default_action'] ?? '__invoke', '()');
-            $componentClass = $config['class'];
+            $defaultAction = trim($metadata->get('default_action', '__invoke'), '()');
 
-            if (!method_exists($componentClass, $defaultAction)) {
+            if (!method_exists($metadata->getClass(), $defaultAction)) {
                 // todo should this check be in a compiler pass to ensure fails at compile time?
-                throw new \LogicException(sprintf('Live component "%s" requires the default action method "%s".%s', $componentClass, $defaultAction, '__invoke' === $defaultAction ? ' Either add this method or use the DefaultActionTrait' : ''));
+                throw new \LogicException(sprintf('Live component "%s" (%s) requires the default action method "%s".%s', $metadata->getClass(), $componentName, $defaultAction, '__invoke' === $defaultAction ? ' Either add this method or use the DefaultActionTrait' : ''));
             }
 
             // set default controller for "default" action
-            $request->attributes->set('_controller', sprintf('%s::%s', $config['service_id'], $defaultAction));
+            $request->attributes->set('_controller', sprintf('%s::%s', $metadata->getServiceId(), $defaultAction));
             $request->attributes->set('_component_default_action', true);
 
             return;
@@ -106,7 +111,7 @@ public function onKernelRequest(RequestEvent $event): void
             throw new BadRequestHttpException('Invalid CSRF token.');
         }
 
-        $request->attributes->set('_controller', sprintf('%s::%s', $config['service_id'], $action));
+        $request->attributes->set('_controller', sprintf('%s::%s', $metadata->getServiceId(), $action));
     }
 
     public function onKernelController(ControllerEvent $event): void
@@ -232,7 +237,7 @@ private function createResponse(object $component, Request $request): Response
 
         $html = $this->container->get(ComponentRenderer::class)->render(
             $component,
-            $request->attributes->get('_component_template')
+            $request->attributes->get('_component_metadata')
         );
 
         return new Response($html);

src/LiveComponent/src/Resources/doc/index.rst

@@ -43,10 +43,15 @@ A real-time product search component might look like this::
     The ability to reference local variables in the template (e.g. ``query``) was added in TwigComponents 2.1.
     Previously, all data needed to be referenced through ``this`` (e.g. ``this.query``).
 
+.. versionadded:: 2.1
+
+    The ability to initialize live component with the ``attributes`` twig variable was added in LiveComponents
+    2.1. Previously, the ``init_live_component()`` function was required (this function was removed in 2.1).
+
 .. code-block:: twig
 
     {# templates/components/product_search.html.twig #}
-    <div {{ init_live_component(this) }}>
+    <div {{ attributes }}>
         <input
             type="search"
             name="query"
@@ -159,13 +164,13 @@ re-rendered live on the frontend), replace the component's
       }
 
 Then, in the template, make sure there is *one* HTML element around your
-entire component and use the ``{{ init_live_component() }}`` function to
-initialize the Stimulus controller:
+entire component and use the ``{{ attributes }}`` variable to initialize
+the Stimulus controller:
 
 .. code-block:: diff
 
     - <div>
-    + <div {{ init_live_component(this) }}>
+    + <div {{ attributes }}>
           <strong>{{ this.randomNumber }}</strong>
       </div>
 
@@ -176,7 +181,7 @@ and give the user a new random number:
 
 .. code-block:: twig
 
-    <div {{ init_live_component(this) }}>
+    <div {{ attributes }}>
         <strong>{{ this.randomNumber }}</strong>
 
         <button
@@ -239,6 +244,44 @@ exceptions being properties that hold services (these don't need to be
 stateful because they will be autowired each time before the component
 is rendered) and `properties used for computed properties`_.
 
+Component Attributes
+--------------------
+
+.. versionadded:: 2.1
+
+    The ``HasAttributes`` trait was added in TwigComponents 2.1.
+
+`Component attributes`_ allows you to render your components with extra
+props that are are converted to html attributes and made available in
+your component's template as an ``attributes`` variable. When used on
+live components, these props are persisted between renders. You can enable
+this feature by having your live component use the ``HasAttributesTrait``:
+
+.. code-block:: diff
+
+      // ...
+      use Symfony\UX\LiveComponent\Attribute\LiveProp;
+    + use Symfony\UX\TwigComponent\HasAttributesTrait;
+
+      #[AsLiveComponent('random_number')]
+      class RandomNumberComponent
+      {
+    +     use HasAttributesTrait;
+
+          #[LiveProp]
+          public int $min = 0;
+
+Now, when rendering your component, you can pass html attributes
+as props and these will be added to ``attributes``:
+
+.. code-block:: twig
+
+    {{ component('random_number', { min: 5, max: 500, class: 'widget', style: 'color: black;' }) }}
+
+    {# renders as: #}
+    <div class="widget" style="color: black;" <!-- other live attributes -->>
+        <!-- ... -->
+
 data-action=“live#update”: Re-rendering on LiveProp Change
 ----------------------------------------------------------
 
@@ -251,7 +294,7 @@ Let's add two inputs to our template:
 .. code-block:: twig
 
     {# templates/components/random_number.html.twig #}
-    <div {{ init_live_component(this) }}>
+    <div {{ attributes }}>
         <input
             type="number"
             value="{{ min }}"
@@ -368,7 +411,7 @@ property. The following code works identically to the previous example:
 
 .. code-block:: diff
 
-      <div {{ init_live_component(this)>
+      <div {{ attributes }}>
           <input
               type="number"
               value="{{ min }}"
@@ -791,7 +834,7 @@ as ``this.form`` thanks to the trait:
 
     {# templates/components/post_form.html.twig #}
     <div
-        {{ init_live_component(this) }}
+        {{ attributes }}
         {#
             Automatically catch all "change" events from the fields
             below and re-render the component.
@@ -815,8 +858,7 @@ as ``this.form`` thanks to the trait:
     </div>
 
 Mostly, this is a pretty boring template! It includes the normal
-``init_live_component(this)`` and then you render the form however you
-want.
+``attributes`` and then you render the form however you want.
 
 But the result is incredible! As you finish changing each field, the
 component automatically re-renders - including showing any validation
@@ -1024,7 +1066,7 @@ section above) is to add:
 .. code-block:: diff
 
       <div
-          {{ init_live_component(this) }}
+          {{ attributes }}
     +     data-action="change->live#update"
       >
 
@@ -1056,7 +1098,7 @@ rendered the ``content`` through a Markdown filter from the
 
 .. code-block:: twig
 
-    <div {{init_live_component(this)}}>
+    <div {{ attributes }}>
         <input
             type="text"
             value="{{ post.title }}"
@@ -1221,7 +1263,7 @@ You can also use “polling” to continually refresh a component. On the
 .. code-block:: diff
 
       <div
-          {{ init_live_component(this) }}
+          {{ attributes }}
     +     data-poll
       >
 
@@ -1233,7 +1275,7 @@ delay for 500ms:
 .. code-block:: twig
 
     <div
-        {{ init_live_component(this) }}
+        {{ attributes }}
         data-poll="delay(500)|$render"
     >
 
@@ -1242,7 +1284,7 @@ You can also trigger a specific “action” instead of a normal re-render:
 .. code-block:: twig
 
     <div
-        {{ init_live_component(this) }}
+        {{ attributes }}
 
         data-poll="save"
         {#
@@ -1437,7 +1479,7 @@ In the ``EditPostComponent`` template, you render the
 .. code-block:: twig
 
     {# templates/components/edit_post.html.twig #}
-    <div {{ init_live_component(this) }}>
+    <div {{ attributes }}>
         <input
             type="text"
             name="post[title]"
@@ -1459,7 +1501,7 @@ In the ``EditPostComponent`` template, you render the
 
 .. code-block:: twig
 
-    <div {{ init_live_component(this) }} class="mb-3">
+    <div {{ attributes }} class="mb-3">
         <textarea
             name="{{ name }}"
             data-model="value"
@@ -1496,3 +1538,4 @@ bound to Symfony's BC policy for the moment.
 .. _`experimental`: https://symfony.com/doc/current/contributing/code/experimental.html
 .. _`dependent form fields`: https://symfony.com/doc/current/form/dynamic_form_modification.html#dynamic-generation-for-submitted-forms
 .. _`Symfony UX configured in your app`: https://symfony.com/doc/current/frontend/ux.html
+.. _`Component attributes`: https://symfony.com/bundles/ux-twig-component/current/index.html#component-attributes

src/LiveComponent/src/Twig/LiveComponentExtension.php

@@ -24,7 +24,6 @@ final class LiveComponentExtension extends AbstractExtension
     public function getFunctions(): array
     {
         return [
-            new TwigFunction('init_live_component', [LiveComponentRuntime::class, 'renderLiveAttributes'], ['needs_environment' => true, 'is_safe' => ['html_attr']]),
             new TwigFunction('component_url', [LiveComponentRuntime::class, 'getComponentUrl']),
         ];
     }