feature #1143 Add deferred live components (jakubtobiasz)

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

Discussion
----------

Add deferred live components

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

Initially this feature was called `lazy loading`, but this name could be misleading, as my solution doesn't provide **real** lazy loading. So, I named it `deferred live components`, I guess this name fits better.

How to use it?

```twig
<twig:MyComponent defer />
```

In such case we'll get an empty div. Once `live:connect` event called, it'll load the component in the background. We can also define a template to be rendered while loading (e.g. a cool spinner or some text).

```twig
<twig:MyComponent defer defer-loading-template="my_cool_spinner.html.twig" />
```

I'm open for any suggestions 🙌🏼!

Commits
-------

d93cc29 Add deferred live components

Author: weaverryan

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.13.0
+
+-   Add deferred rendering of Live Components
+
 ## 2.12.0
 
 -   Add support for (de)hydrating DTO classes in `LiveProp`.

src/LiveComponent/doc/index.rst

@@ -2220,6 +2220,32 @@ To validate only on "change", use the ``on(change)`` modifier:
         class="{{ _errors.has('post.content') ? 'is-invalid' : '' }}"
     >
 
+Deferring the Loading
+---------------------
+
+Certain components might be heavy to load. You can defer the loading of these components
+until after the rest of the page has loaded. To do this, use the ``defer`` attribute:
+
+.. code-block:: twig
+
+    {{ component('SomeHeavyComponent', { defer: true }) }}
+
+Doing so will render an empty "placeholder" tag with the live attributes. Once the ``live:connect`` event is triggered,
+the component will be rendered asynchronously.
+
+By default the rendered tag is a ``div``. You can change this by specifying the ``loading-tag`` attribute:
+
+.. code-block:: twig
+
+    {{ component('SomeHeavyComponent', { defer: true, loading-tag: 'span' }) }}
+
+If you need to signify that the component is loading, use the ``loading-template`` attribute.
+This lets you provide a Twig template that will render inside the "placeholder" tag:
+
+.. code-block:: twig
+
+    {{ component('SomeHeavyComponent', { defer: true, loading-template: 'spinning-wheel.html.twig' }) }}
+
 Polling
 -------
 

src/LiveComponent/src/DependencyInjection/LiveComponentExtension.php

@@ -25,6 +25,7 @@
 use Symfony\UX\LiveComponent\Controller\BatchActionController;
 use Symfony\UX\LiveComponent\EventListener\AddLiveAttributesSubscriber;
 use Symfony\UX\LiveComponent\EventListener\DataModelPropsSubscriber;
+use Symfony\UX\LiveComponent\EventListener\DeferLiveComponentSubscriber;
 use Symfony\UX\LiveComponent\EventListener\InterceptChildComponentRenderSubscriber;
 use Symfony\UX\LiveComponent\EventListener\LiveComponentSubscriber;
 use Symfony\UX\LiveComponent\EventListener\ResetDeterministicIdSubscriber;
@@ -215,6 +216,14 @@ function (ChildDefinition $definition, AsLiveComponent $attribute) {
             ->addTag('container.service_subscriber', ['key' => LiveControllerAttributesCreator::class, 'id' => 'ux.live_component.live_controller_attributes_creator'])
         ;
 
+        $container->register('ux.live_component.defer_live_component_subscriber', DeferLiveComponentSubscriber::class)
+            ->setArguments([
+                new Reference('ux.twig_component.component_stack'),
+                new Reference('ux.live_component.live_controller_attributes_creator'),
+            ])
+            ->addTag('kernel.event_subscriber')
+        ;
+
         $container->register('ux.live_component.deterministic_id_calculator', DeterministicTwigIdCalculator::class);
         $container->register('ux.live_component.fingerprint_calculator', FingerprintCalculator::class)
             ->setArguments(['%kernel.secret%']);

src/LiveComponent/src/EventListener/DeferLiveComponentSubscriber.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symfony\UX\LiveComponent\EventListener;
+
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\UX\TwigComponent\Event\PostMountEvent;
+use Symfony\UX\TwigComponent\Event\PreRenderEvent;
+
+final class DeferLiveComponentSubscriber implements EventSubscriberInterface
+{
+    private const DEFAULT_LOADING_TAG = 'div';
+
+    private const DEFAULT_LOADING_TEMPLATE = null;
+
+    public function onPostMount(PostMountEvent $event): void
+    {
+        $data = $event->getData();
+        if (\array_key_exists('defer', $data)) {
+            $event->addExtraMetadata('defer', true);
+            unset($event->getData()['defer']);
+        }
+
+        if (\array_key_exists('loading-template', $data)) {
+            $event->addExtraMetadata('loading-template', $data['loading-template']);
+            unset($event->getData()['loading-template']);
+        }
+
+        if (\array_key_exists('loading-tag', $data)) {
+            $event->addExtraMetadata('loading-tag', $data['loading-tag']);
+            unset($event->getData()['loading-tag']);
+        }
+
+        $event->setData($data);
+    }
+
+    public function onPreRender(PreRenderEvent $event): void
+    {
+        $mountedComponent = $event->getMountedComponent();
+
+        if (!$mountedComponent->hasExtraMetadata('defer')) {
+            return;
+        }
+
+        $event->setTemplate('@LiveComponent/deferred.html.twig');
+
+        $variables = $event->getVariables();
+        $variables['loadingTemplate'] = self::DEFAULT_LOADING_TEMPLATE;
+        $variables['loadingTag'] = self::DEFAULT_LOADING_TAG;
+
+        if ($mountedComponent->hasExtraMetadata('loading-template')) {
+            $variables['loadingTemplate'] = $mountedComponent->getExtraMetadata('loading-template');
+        }
+
+        if ($mountedComponent->hasExtraMetadata('loading-tag')) {
+            $variables['loadingTag'] = $mountedComponent->getExtraMetadata('loading-tag');
+        }
+
+        $event->setVariables($variables);
+    }
+
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            PostMountEvent::class => ['onPostMount'],
+            PreRenderEvent::class => ['onPreRender'],
+        ];
+    }
+}

src/LiveComponent/templates/deferred.html.twig

@@ -0,0 +1,7 @@
+<{{ loadingTag }} {{ attributes }} data-action="live:connect->live#$render">
+    {% block loadingContent %}
+        {% if loadingTemplate != null %}
+            {{ include(loadingTemplate) }}
+        {% endif %}
+    {% endblock %}
+</{{ loadingTag }}>

src/LiveComponent/tests/Fixtures/Component/DeferredComponent.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symfony\UX\LiveComponent\Tests\Fixtures\Component;
+
+use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+use Symfony\UX\LiveComponent\DefaultActionTrait;
+
+#[AsLiveComponent('deferred_component')]
+final class DeferredComponent
+{
+    use DefaultActionTrait;
+
+    public function getLongAwaitedData(): string
+    {
+        return 'Long awaited data';
+    }
+}

src/LiveComponent/tests/Fixtures/templates/components/deferred_component.html.twig

@@ -0,0 +1 @@
+<div {{ attributes }}>{{ computed.longAwaitedData }}</div>

src/LiveComponent/tests/Fixtures/templates/dummy/loading.html.twig

@@ -0,0 +1 @@
+I'm loading a reaaaally slow live component

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

@@ -0,0 +1 @@
+<twig:deferred_component defer />

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

@@ -0,0 +1 @@
+<twig:deferred_component defer loading-tag='li' />