feature #913 [TwigComponent] [LiveComponent] Add support for embedded live components (sneakyvv)

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

Discussion
----------

[TwigComponent] [LiveComponent] Add support for embedded live components

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

## Context

Using embedded components was introduced in symfony/ux#317, but support for Live embedded components was not added. The issue is that on a re-render of a Live component you lose the blocks defined within an embedded component. This PR solves that issue.

## Example

To explain the solution, take this example:

```twig
{# someTemplate.html.twig #}
{% component Foo %}
  {% block content %}
    Override content
  {% endblock %}
{% endcomponent %}
```
```twig
{# Foo.html.twig #}
<div {{ attributes }}>
  {% block content %}
    Default content
  {% endblock %}
</div>
```

Of course, Foo is a Live component.

This obviously also works with the new Twig syntax.

## Background

1. Each `{% component %}` tag is compiled by `ComponentNode`.
It adds an embedded Template to the Template class compiled for `someTemplate.html.twig`. This is a second class inside the same php file, with a suffix in the form of `___%d`. That number at the end is normally random, and is called the embedded template index.
2. `ComponentNode` would generate Template code which fetches the `embeddedContext` from the `ComponentRenderer` and passed that to the `loadTemplate('Foo.html.twig', $index)->display()`
3. When a component is re-rendered (via an action callback) it uses the template of the component `(Foo.html.twig`), which does not have the original block content, because that's part of the host Template (`someTemplate.html.twig`).

## Solution

We only need to use the embedded Template instead of the component Template to re-render a component.

To make this happen, we need to:

1. Use a deterministic index for an embedded template during compilation.
2. Store info on the rendered component's HTML (via the attributes) about the host template and the embedded template's index.
3. Load the embedded Template during re-render using the info passed along with the other attributes/props.

## Remaining

1. I use `loadTemplate` now in the `ComponentRender`, which is marked as internal in the Twig package. Can we ignore that within this package (as both are "Symfony")?
2. The `PreRenderEvent::EMBEDDED` constant and the `isEmbedded` function were introduced to block live embedded components. Should this PR remove those as well?

### Tasks
- [ ] Remove `isEmbedded`?
- [ ] Remove `PreRenderEvent::EMBEDDED`?
- [ ] Add CHANGELOG

Commits
-------

d9dd3fc4 [TwigComponent] [LiveComponent] Add support for embedded live components

Author: weaverryan

src/ComponentRenderer.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\UX\TwigComponent;
 
+use Composer\InstalledVersions;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;
@@ -38,14 +39,21 @@ public function __construct(
     ) {
     }
 
-    public function createAndRender(string $name, array $props = []): string
+    /**
+     * Allow the render process to be short-circuited.
+     */
+    public function preCreateForRender(string $name, array $props = []): ?string
     {
         $event = new PreCreateForRenderEvent($name, $props);
         $this->dispatcher->dispatch($event);
 
-        // allow the process to be short-circuited
-        if (null !== $rendered = $event->getRenderedString()) {
-            return $rendered;
+        return $event->getRenderedString();
+    }
+
+    public function createAndRender(string $name, array $props = []): string
+    {
+        if ($preRendered = $this->preCreateForRender($name, $props)) {
+            return $preRendered;
         }
 
         return $this->render($this->factory->create($name, $props));
@@ -58,7 +66,15 @@ public function render(MountedComponent $mounted): string
         $event = $this->preRender($mounted);
 
         try {
-            return $this->twig->render($event->getTemplate(), $event->getVariables());
+            if (InstalledVersions::getVersion('twig/twig') < 3) {
+                return $this->twig->loadTemplate($event->getTemplate(), $event->getTemplateIndex())->render($event->getVariables());
+            }
+
+            return $this->twig->loadTemplate(
+                $this->twig->getTemplateClass($event->getTemplate()),
+                $event->getTemplate(),
+                $event->getTemplateIndex(),
+            )->render($event->getVariables());
         } finally {
             $this->componentStack->pop();
 
@@ -67,17 +83,27 @@ public function render(MountedComponent $mounted): string
         }
     }
 
-    public function embeddedContext(string $name, array $props, array $context): array
+    public function embeddedContext(string $name, array $props, array $context, string $hostTemplateName, int $index): array
     {
         $context[PreRenderEvent::EMBEDDED] = true;
 
-        $embeddedContext = $this->preRender($this->factory->create($name, $props), $context)->getVariables();
+        $mounted = $this->factory->create($name, $props);
+        $mounted->addExtraMetadata('hostTemplate', $hostTemplateName);
+        $mounted->addExtraMetadata('embeddedTemplateIndex', $index);
 
-        if (!isset($embeddedContext['outerBlocks'])) {
-            $embeddedContext['outerBlocks'] = new BlockStack();
-        }
+        $this->componentStack->push($mounted);
+
+        try {
+            $embeddedContext = $this->preRender($mounted, $context)->getVariables();
+
+            if (!isset($embeddedContext['outerBlocks'])) {
+                $embeddedContext['outerBlocks'] = new BlockStack();
+            }
 
-        return $embeddedContext;
+            return $embeddedContext;
+        } finally {
+            $this->componentStack->pop();
+        }
     }
 
     private function preRender(MountedComponent $mounted, array $context = []): PreRenderEvent

src/Event/PreRenderEvent.php

@@ -25,6 +25,8 @@ final class PreRenderEvent extends Event
 
     private string $template;
 
+    private ?int $templateIndex = null;
+
     /**
      * @internal
      */
@@ -52,17 +54,22 @@ public function getTemplate(): string
     /**
      * Change the twig template used.
      */
-    public function setTemplate(string $template): self
+    public function setTemplate(string $template, int $index = null): self
     {
-        if ($this->isEmbedded()) {
-            throw new \LogicException('Cannot modify template for embedded components.');
-        }
-
         $this->template = $template;
+        $this->templateIndex = $index;
 
         return $this;
     }
 
+    /**
+     * @return string The twig template index used for the component, in case it's an embedded template
+     */
+    public function getTemplateIndex(): ?int
+    {
+        return $this->templateIndex;
+    }
+
     public function getComponent(): object
     {
         return $this->mounted->getComponent();

src/Twig/ComponentExtension.php

@@ -62,10 +62,19 @@ public function render(string $name, array $props = []): string
         }
     }
 
-    public function embeddedContext(string $name, array $props, array $context): array
+    public function preRender(string $name, array $props): ?string
     {
         try {
-            return $this->container->get(ComponentRenderer::class)->embeddedContext($name, $props, $context);
+            return $this->container->get(ComponentRenderer::class)->preCreateForRender($name, $props);
+        } catch (\Throwable $e) {
+            $this->throwRuntimeError($name, $e);
+        }
+    }
+
+    public function embeddedContext(string $name, array $props, array $context, string $hostTemplateName, int $index): array
+    {
+        try {
+            return $this->container->get(ComponentRenderer::class)->embeddedContext($name, $props, $context, $hostTemplateName, $index);
         } catch (\Throwable $e) {
             $this->throwRuntimeError($name, $e);
         }

src/Twig/ComponentNode.php

@@ -35,15 +35,42 @@ public function compile(Compiler $compiler): void
         $compiler->addDebugInfo($this);
 
         $compiler
-            ->write('$embeddedContext = $this->extensions[')
+            ->write('$preRendered = $this->extensions[')
             ->string(ComponentExtension::class)
-            ->raw(']->embeddedContext(')
+            ->raw(']->preRender(')
             ->string($this->getAttribute('component'))
             ->raw(', ')
             ->raw('twig_to_array(')
             ->subcompile($this->getNode('variables'))
+            ->raw(')')
+            ->raw(");\n")
+        ;
+
+        $compiler
+            ->write('if (null !== $preRendered) {')
+            ->raw("\n")
+            ->indent()
+            ->write('echo $preRendered;')
+            ->raw("\n")
+            ->outdent()
+            ->write('} else {')
+            ->raw("\n")
+            ->indent()
+        ;
+
+        $compiler
+            ->write('$embeddedContext = $this->extensions[')
+            ->string(ComponentExtension::class)
+            ->raw(']->embeddedContext(')
+            ->string($this->getAttribute('component'))
+            ->raw(', twig_to_array(')
+            ->subcompile($this->getNode('variables'))
             ->raw('), ')
             ->raw($this->getAttribute('only') ? '[]' : '$context')
+            ->raw(', ')
+            ->string($this->getAttribute('name'))
+            ->raw(', ')
+            ->raw($this->getAttribute('index'))
             ->raw(");\n")
         ;
 
@@ -57,5 +84,11 @@ public function compile(Compiler $compiler): void
         $this->addGetTemplate($compiler);
         $compiler->raw('->display($embeddedContext, $embeddedBlocks);');
         $compiler->raw("\n");
+
+        $compiler
+            ->outdent()
+            ->write('}')
+            ->raw("\n")
+        ;
     }
 }

src/Twig/ComponentTokenParser.php

@@ -32,6 +32,8 @@ final class ComponentTokenParser extends AbstractTokenParser
     /** @var ComponentFactory|callable():ComponentFactory */
     private $factory;
 
+    private array $lineAndFileCounts = [];
+
     /**
      * @param callable():ComponentFactory $factory
      */
@@ -84,6 +86,9 @@ public function parse(Token $token): Node
 
         $this->parser->embedTemplate($module);
 
+        // use deterministic index for the embedded template, so it can be loaded in a controlled manner
+        $module->setAttribute('index', $this->generateEmbeddedTemplateIndex($stream->getSourceContext()->getName(), $token->getLine()));
+
         $stream->expect(Token::BLOCK_END_TYPE);
 
         return new ComponentNode($componentName, $module->getTemplateName(), $module->getAttribute('index'), $variables, $only, $token->getLine(), $this->getTag());
@@ -136,4 +141,14 @@ private function parseArguments(): array
 
         return [$variables, $only];
     }
+
+    private function generateEmbeddedTemplateIndex(string $file, int $line): int
+    {
+        $fileAndLine = sprintf('%s-%d', $file, $line);
+        if (!isset($this->lineAndFileCounts[$fileAndLine])) {
+            $this->lineAndFileCounts[$fileAndLine] = 0;
+        }
+
+        return crc32($fileAndLine).++$this->lineAndFileCounts[$fileAndLine];
+    }
 }