feature #317 [Twig] Embedded components (kbond)

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

Discussion
----------

[Twig] Embedded components

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Tickets       | Fix #300
| License       | MIT

This adds a `{% component name %}` tag to allow rendering components and overriding their _slots_ (by using twig's native block system).

Example:

```twig
{# templates/components/alert.html.twig #}
<div{{ attributes.defaults({class: 'alert alert-'~type}) }}>
    {% block default %}<strong>{{ type }}</strong> {{ message }}{% endblock %}
</div>

{# "embed" in another template: #}
{% component 'alert' with {message: 'embedded message', class: 'extra-class', role: 'alert'} %}
    {% block default %} {# override "default slot (block)" #}
        {{ parent() }} {# call parent "slot" #}
        Custom stuff...
        {{ this.message }} {# access component properties/methods as normal #}
        {{ computed.someMethod }} {# all component features available #}
    {% endblock %}
{% endcomponent %}

{# can still use the function as normal #}
{{ component('alert', {message: 'some message'}) }}
```

More Advanced Example:

```twig
{# templates/components/dialog.html.twig #}
<div{{ attributes }}>
    <h1>{% block title %}Default Title{% endblock %}</h1>
    <p>{% block body %}Default Body{% endblock %}</p>
    <div>{% block footer %}Default Footer{% endblock %}</div>
</div>

{# "embed" in another template: #}
{% component dialog %} {# quotes can optionally be left off the component name #}
    {% block title %}Custom Title{% endblock %}
    {% block body %}Custom Body{% endblock %}
    {% block footer %}Custom Footer{% endblock %}
{% endcomponent %}
```

Some notes:
1. Most code is copied and modified from twig's native `embed` tag
2. I really wanted to have a default slot to avoid the need for overriding the default block (see first example above) but couldn't figure out how to do this or if it's even possible. Maybe someone with a deeper knowledge of twig internals could help?
3. The `PreRender` event is still dispatched like normal but because of the nature of how this feature works, modifying the template via a listener is not supported.
4. Using with LiveComponent's is not supported and throws an exception if attempted. Perhaps some trickery could be added in the future to achieve but I think this feature adds enough value to stand on its own.
5. This with #283 could add more value I think - it would remove the need for simple components to be _backed by_ a component service.

**TODO:**
- [x] Update changelog
- [x] Tests
- [x] Docs
- [x] Clarify nomenclature, _nested_ components vs _embedded_ components

Commits
-------

b114594 [Twig] Embedded components

Author: weaverryan

src/LiveComponent/src/EventListener/AddLiveAttributesSubscriber.php

@@ -34,6 +34,11 @@ public function onPreRender(PreRenderEvent $event): void
             return;
         }
 
+        if (method_exists($event, 'isEmbedded') && $event->isEmbedded()) {
+            // TODO: remove method_exists once min ux-twig-component version has this method
+            throw new \LogicException('Embedded components cannot be live.');
+        }
+
         $metadata = $event->getMetadata();
         $attributes = $this->getLiveAttributes($event->getMountedComponent(), $metadata);
         $variables = $event->getVariables();

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

@@ -1443,12 +1443,12 @@ You can also trigger a specific "action" instead of a normal re-render:
         #}
     >
 
-Embedded Components
--------------------
+Nested Components
+-----------------
 
-Need to embed one live component inside another one? No problem! As a
+Need to nest one live component inside another one? No problem! As a
 rule of thumb, **each component exists in its own, isolated universe**.
-This means that embedding one component inside another could be really
+This means that nesting one component inside another could be really
 simple or a bit more complex, depending on how inter-connected you want
 your components to be.
 

src/LiveComponent/tests/Fixtures/templates/render_embedded.html.twig

@@ -0,0 +1,2 @@
+{% component component2 %}
+{% endcomponent %}

src/LiveComponent/tests/Integration/EventListener/AddLiveAttributesSubscriberTest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Symfony\UX\LiveComponent\Tests\Integration\EventListener;
+
+use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
+use Symfony\UX\TwigComponent\EventListener\PreRenderEvent;
+use Twig\Environment;
+use Twig\Error\RuntimeError;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+final class AddLiveAttributesSubscriberTest extends KernelTestCase
+{
+    public function testCannotUseEmbeddedComponentAsLive(): void
+    {
+        if (!method_exists(PreRenderEvent::class, 'isEmbedded')) {
+            $this->markTestSkipped('Embedded components not available.');
+        }
+
+        $twig = self::getContainer()->get(Environment::class);
+
+        $this->expectException(RuntimeError::class);
+        $this->expectExceptionMessage('Embedded components cannot be live.');
+
+        $twig->render('render_embedded.html.twig');
+    }
+}

src/TwigComponent/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 2.2
 
 -   Allow to pass stringable object as non mapped component attribute
+-   Add _embedded_ components.
 
 ## 2.1
 

src/TwigComponent/src/ComponentRenderer.php

@@ -37,7 +37,26 @@ public function __construct(
     ) {
     }
 
+    public function createAndRender(string $name, array $props = []): string
+    {
+        return $this->render($this->factory->create($name, $props));
+    }
+
     public function render(MountedComponent $mounted): string
+    {
+        $event = $this->preRender($mounted);
+
+        return $this->twig->render($event->getTemplate(), $event->getVariables());
+    }
+
+    public function embeddedContext(string $name, array $props, array $context): array
+    {
+        $context[PreRenderEvent::EMBEDDED] = true;
+
+        return $this->preRender($this->factory->create($name, $props), $context)->getVariables();
+    }
+
+    private function preRender(MountedComponent $mounted, array $context = []): PreRenderEvent
     {
         if (!$this->safeClassesRegistered) {
             $this->twig->getExtension(EscaperExtension::class)->addSafeClass(ComponentAttributes::class, ['html']);
@@ -48,6 +67,9 @@ public function render(MountedComponent $mounted): string
         $component = $mounted->getComponent();
         $metadata = $this->factory->metadataFor($mounted->getName());
         $variables = array_merge(
+            // first so values can be overridden
+            $context,
+
             // add the component as "this"
             ['this' => $component],
 
@@ -64,7 +86,7 @@ public function render(MountedComponent $mounted): string
 
         $this->dispatcher->dispatch($event);
 
-        return $this->twig->render($event->getTemplate(), $event->getVariables());
+        return $event;
     }
 
     private function exposedVariables(object $component, bool $exposePublicProps): \Iterator

src/TwigComponent/src/DependencyInjection/TwigComponentExtension.php

@@ -24,7 +24,6 @@
 use Symfony\UX\TwigComponent\ComponentRenderer;
 use Symfony\UX\TwigComponent\DependencyInjection\Compiler\TwigComponentPass;
 use Symfony\UX\TwigComponent\Twig\ComponentExtension;
-use Symfony\UX\TwigComponent\Twig\ComponentRuntime;
 
 /**
  * @author Kevin Bond <[email protected]>
@@ -67,14 +66,8 @@ class_exists(AbstractArgument::class) ? new AbstractArgument(sprintf('Added in %
 
         $container->register('ux.twig_component.twig.component_extension', ComponentExtension::class)
             ->addTag('twig.extension')
-        ;
-
-        $container->register('ux.twig_component.twig.component_runtime', ComponentRuntime::class)
-            ->setArguments([
-                new Reference('ux.twig_component.component_factory'),
-                new Reference('ux.twig_component.component_renderer'),
-            ])
-            ->addTag('twig.runtime')
+            ->addTag('container.service_subscriber', ['key' => ComponentRenderer::class, 'id' => 'ux.twig_component.component_renderer'])
+            ->addTag('container.service_subscriber', ['key' => ComponentFactory::class, 'id' => 'ux.twig_component.component_factory'])
         ;
     }
 }

src/TwigComponent/src/EventListener/PreRenderEvent.php

@@ -22,6 +22,9 @@
  */
 final class PreRenderEvent extends Event
 {
+    /** @internal */
+    public const EMBEDDED = '__embedded';
+
     private string $template;
 
     /**
@@ -35,6 +38,11 @@ public function __construct(
         $this->template = $this->metadata->getTemplate();
     }
 
+    public function isEmbedded(): bool
+    {
+        return $this->variables[self::EMBEDDED] ?? false;
+    }
+
     /**
      * @return string The twig template used for the component
      */
@@ -48,6 +56,10 @@ public function getTemplate(): string
      */
     public function setTemplate(string $template): self
     {
+        if ($this->isEmbedded()) {
+            throw new \LogicException('Cannot modify template for embedded components.');
+        }
+
         $this->template = $template;
 
         return $this;

src/TwigComponent/src/Resources/doc/index.rst

@@ -637,14 +637,82 @@ the twig template and twig variables before components are rendered::
         }
     }
 
-Embedded Components
--------------------
+Nested Components
+-----------------
 
-It's totally possible to embed one component into another. When you do
+It's totally possible to nest one component into another. When you do
 this, there's nothing special to know: both components render
 independently. If you're using `Live Components`_, then there
 *are* some guidelines related to how the re-rendering of parent and
-child components works. Read `Live Embedded Components`_.
+child components works. Read `Live Nested Components`_.
+
+Embedded Components
+-------------------
+
+.. versionadded:: 2.2
+
+    Embedded components were added in TwigComponents 2.2.
+
+You can write your component's Twig template with blocks that can be overridden
+when rendering using the ``{% component %}`` syntax. These blocks can be thought of as
+*slots* which you may be familiar with from Vue. The ``component`` tag is very
+similar to Twig's native `embed tag`_.
+
+Consider a data table component. You pass it headers and rows but can expose
+blocks for the cells and an optional footer:
+
+.. code-block:: twig
+
+    {# templates/components/data_table.html.twig #}
+
+    <div{{ attributes.defaults({class: 'data-table'}) }}>
+        <table>
+            <thead>
+                <tr>
+                    {% for header in this.headers %}
+                        <th class="{% block th_class %}data-table-header{% endblock %}">
+                            {{ header }}
+                        </th>
+                    {% endfor %}
+                </tr>
+            </thead>
+            <tbody>
+                {% for row in this.data %}
+                    <tr>
+                        {% for cell in row %}
+                            <td class="{% block td_class %}data-table-cell{% endblock %}">
+                                {{ cell }}
+                            </td>
+                        {% endfor %}
+                    </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+        {% block footer %}{% endblock %}
+    </div>
+
+When rendering, you can override the ``th_class``, ``td_class``, and ``footer`` blocks.
+The ``with`` data is what's mounted on the component object.
+
+.. code-block:: twig
+
+    {# templates/some_page.html.twig #}
+
+    {% component table with {headers: ['key', 'value'], data: [[1, 2], [3, 4]]} %}
+        {% block th_class %}{{ parent() }} text-bold{% endblock %}
+
+        {% block td_class %}{{ parent() }} text-italic{% endblock %}
+
+        {% block footer %}
+            <div class="data-table-footer">
+                My footer
+            </div>
+        {% endblock %}
+    {% endcomponent %}
+
+.. note::
+
+    Embedded components *cannot* currently be used with LiveComponents.
 
 Contributing
 ------------
@@ -665,5 +733,6 @@ meaning it is not bound to Symfony's BC policy for the moment.
 .. _`Live Components`: https://symfony.com/bundles/ux-live-component/current/index.html
 .. _`live component`: https://symfony.com/bundles/ux-live-component/current/index.html
 .. _`Vue`: https://v3.vuejs.org/guide/computed.html
-.. _`Live Embedded Components`: https://symfony.com/bundles/ux-live-component/current/index.html#embedded-components
+.. _`Live Nested Components`: https://symfony.com/bundles/ux-live-component/current/index.html#nested-components
 .. _`experimental`: https://symfony.com/doc/current/contributing/code/experimental.html
+.. _`embed tag`: https://twig.symfony.com/doc/3.x/tags/embed.html

src/TwigComponent/src/Twig/ComponentExtension.php

@@ -11,6 +11,10 @@
 
 namespace Symfony\UX\TwigComponent\Twig;
 
+use Psr\Container\ContainerInterface;
+use Symfony\Contracts\Service\ServiceSubscriberInterface;
+use Symfony\UX\TwigComponent\ComponentFactory;
+use Symfony\UX\TwigComponent\ComponentRenderer;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
@@ -21,12 +25,41 @@
  *
  * @internal
  */
-final class ComponentExtension extends AbstractExtension
+final class ComponentExtension extends AbstractExtension implements ServiceSubscriberInterface
 {
+    public function __construct(private ContainerInterface $container)
+    {
+    }
+
+    public static function getSubscribedServices(): array
+    {
+        return [
+            ComponentRenderer::class,
+            ComponentFactory::class,
+        ];
+    }
+
     public function getFunctions(): array
     {
         return [
-            new TwigFunction('component', [ComponentRuntime::class, 'render'], ['is_safe' => ['all']]),
+            new TwigFunction('component', [$this, 'render'], ['is_safe' => ['all']]),
         ];
     }
+
+    public function getTokenParsers(): array
+    {
+        return [
+            new ComponentTokenParser(fn () => $this->container->get(ComponentFactory::class)),
+        ];
+    }
+
+    public function render(string $name, array $props = []): string
+    {
+        return $this->container->get(ComponentRenderer::class)->createAndRender($name, $props);
+    }
+
+    public function embeddedContext(string $name, array $props, array $context): array
+    {
+        return $this->container->get(ComponentRenderer::class)->embeddedContext($name, $props, $context);
+    }
 }