feature #1515 [LiveComponent] Lazy load LiveComponent (smnandre)

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

Discussion
----------

[LiveComponent] Lazy load LiveComponent

# UPDATED COMMENT

This PR add loading support for LiveComponent

* `loading="defer"` to load the component on page load
* `loading="lazy"`  to load the component when the component is visible

```twig
{# HTML Syntax #}
<twig:HeavyComponent loading="lazy" />

{# Twig Syntax #}
{{ component('HeavyComponent, { loading: "lazy" }) }}
```

The `defer`attribute is deprecated for this solution.

See more details in the document.

---

# ORIGINAL PR:

I have some live component stuff in progress, so let's post this one now to start the discussion.

This PR implements a _volontarely-minimal_ `loading="lazy"` mode on LiveComponents, based on top of the `defer` one.

## ⚠️  Live Component

This feature is dedicated to Live Component (as there is some particularities due to keeping "state").

(if you need some lazy loading with classic twig components, there are already methods out there to handle such things)

## Defer ? Lazy ?

Both defer and lazy attributes allow to ... defer the full rendering of the component. So when the page first renders, it contains only a skeletton / empty component.

Then, depending of the attribute used, the component will fetch its content via a fetch request:

* `defer`:  when the page loads (it react to the "connect" Stimulus)
* `lazy`: when the component enters the viewport (so as soon it's at least 1px **visible** in it)

I precise "**visible**" because if you use some tabbed content,  horizontal sliders, etc... the "intersect" is not triggered until the component is actually.... visible.

## Usage

```twig
<twig:Acme foo="bar" lazy />
```

Note: `lazy` implies `defer`, so this is equivalent to

```twig
<twig:Acme foo="bar" defer lazy />
```

## So.. defer or lazy ?

As i see it:
* `defer` should be used for any content that will 100% be visible in the main content, but too heavy to be computed with the original request (think Facebook/Insta first results of the timeline)
* `Lazy` should be used for anything really not in the viewport, and that you're not sure will be rendered to the user (comments, tabbed content, ...)

In both situation, this is not a good idea to have too many lazy live components in the page, it's probably a sign that you should use Turbo instead!

(i'll add some doc about defer/lazy and layout shift too, but the idea is: better "keep the space you'll need")

## Rendering

### IntersectionObserver

The loading is triggered with a dedicated intersection observer.

It happens only once and the the element in unregistered.

No settings allowed (as images, iframes, etc.. in the browser)

TODO: optimize threesholds.

### Loading=lazy

I chose to use the `loading="lazy"`  attribute tag on the rendered HTML, as the goal is to have the same behaviour on the browser side.

```html
<div
    loading="lazy"
    data-....
    class="foo"
>
```

It is standard for image, iframes, maybe portals soon, and i think it's self-explanatory.

Example: https://web.dev/articles/browser-level-image-lazy-loading

For browsers and for seo , this seems to be a good way to hint what this div is (i'll see aria stuff later as it touches many things on the codebase)

## DX

### Boolean attribute values

This is how we document the defer feature

```twig
{# expression can be a bool, a var, .... #}
{{ component('acme', {foo: "bar, defer: expression}) }}
```

For better DX, i add a small bool cast for both lazy and defer attributes values. It allows to have some dynamism on the calling side with HTML syntax too.

```twig
{# Defer: true #}
<twig:Acme foo="bar" defer />
<twig:Acme foo="bar" defer="defer" />
<twig:Acme foo="bar" defer="true" />
<twig:Acme foo="bar" defer="{{ 8 < 42 }}" />
<twig:Acme foo="bar" :defer="true" />

{# Also defer: true ! #}
<twig:Acme foo="bar" defer="false" />

{# Defer: false #}
<twig:Acme foo="bar" defer="" />
<twig:Acme foo="bar" defer="{{ 8 > 42 }}" />
<twig:Acme foo="bar" :defer="false" />
```

(Tests / doc incoming, demo(s) in progress)

-- IN PROGRESS --

Commits
-------

b0b4cda [LiveComponent] Lazy load LiveComponent

Author: weaverryan

UPGRADE.md

@@ -1,5 +1,9 @@
 # UPGRADE
 
+## FROM 2.16 to 2.17
+
+-   **Live Components**: Change `defer` attribute to `loading="defer"` #1515.
+
 ## FROM 2.15 to 2.16
 
 -   **Live Components**: Change `data-action-name` attribute to `data-live-action-param`

src/LiveComponent/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 -   Add `modifier` option in `LiveProp` so options can be modified at runtime.
 -   Fix collections hydration with serializer in LiveComponents
+-   Add `loading` attribute to defer the rendering on the component after the
+    page is rendered, either when the page loads (`loading="defer"`) or when
+    the component becomes visible in the viewport (`loading="lazy"`).
+-   Deprecate the `defer` attribute.
 
 ## 2.16.0
 

src/LiveComponent/assets/dist/Component/plugins/LazyPlugin.d.ts

@@ -0,0 +1,7 @@
+import { PluginInterface } from './PluginInterface';
+import Component from '../index';
+export default class implements PluginInterface {
+    private intersectionObserver;
+    attachToComponent(component: Component): void;
+    private getObserver;
+}

src/LiveComponent/assets/dist/live_controller.js

@@ -2914,6 +2914,38 @@ class ChildComponentPlugin {
     }
 }
 
+class LazyPlugin {
+    constructor() {
+        this.intersectionObserver = null;
+    }
+    attachToComponent(component) {
+        var _a;
+        if ('lazy' !== ((_a = component.element.attributes.getNamedItem('loading')) === null || _a === void 0 ? void 0 : _a.value)) {
+            return;
+        }
+        component.on('connect', () => {
+            this.getObserver().observe(component.element);
+        });
+        component.on('disconnect', () => {
+            var _a;
+            (_a = this.intersectionObserver) === null || _a === void 0 ? void 0 : _a.unobserve(component.element);
+        });
+    }
+    getObserver() {
+        if (!this.intersectionObserver) {
+            this.intersectionObserver = new IntersectionObserver((entries, observer) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        entry.target.dispatchEvent(new CustomEvent('live:appear'));
+                        observer.unobserve(entry.target);
+                    }
+                });
+            });
+        }
+        return this.intersectionObserver;
+    }
+}
+
 class LiveControllerDefault extends Controller {
     constructor() {
         super(...arguments);
@@ -3063,6 +3095,7 @@ class LiveControllerDefault extends Controller {
         }
         const plugins = [
             new LoadingPlugin(),
+            new LazyPlugin(),
             new ValidatedFieldsPlugin(),
             new PageUnloadingPlugin(),
             new PollingPlugin(),

src/LiveComponent/assets/src/Component/plugins/LazyPlugin.ts

@@ -0,0 +1,33 @@
+import {PluginInterface} from './PluginInterface';
+import Component from '../index';
+
+export default class implements PluginInterface {
+    private intersectionObserver:  IntersectionObserver | null = null;
+
+    attachToComponent(component: Component): void {
+        if ('lazy' !== component.element.attributes.getNamedItem('loading')?.value) {
+            return;
+        }
+        component.on('connect', () => {
+            this.getObserver().observe(component.element);
+        });
+        component.on('disconnect', () => {
+            this.intersectionObserver?.unobserve(component.element);
+        });
+    }
+
+    private getObserver(): IntersectionObserver {
+        if (!this.intersectionObserver) {
+            this.intersectionObserver = new IntersectionObserver((entries, observer) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        entry.target.dispatchEvent(new CustomEvent('live:appear'));
+                        observer.unobserve(entry.target);
+                    }
+                });
+            });
+        }
+
+        return this.intersectionObserver;
+    }
+}

src/LiveComponent/assets/src/live_controller.ts

@@ -14,6 +14,7 @@ import getModelBinding from './Directive/get_model_binding';
 import QueryStringPlugin from './Component/plugins/QueryStringPlugin';
 import ChildComponentPlugin from './Component/plugins/ChildComponentPlugin';
 import getElementAsTagText from './Util/getElementAsTagText';
+import LazyPlugin from './Component/plugins/LazyPlugin';
 
 export { Component };
 export { getComponent } from './ComponentRegistry';
@@ -295,6 +296,7 @@ export default class LiveControllerDefault extends Controller<HTMLElement> imple
 
         const plugins: PluginInterface[] = [
             new LoadingPlugin(),
+            new LazyPlugin(),
             new ValidatedFieldsPlugin(),
             new PageUnloadingPlugin(),
             new PollingPlugin(),

src/LiveComponent/assets/test/dom_utils.test.ts

@@ -9,7 +9,6 @@ import {
 import ValueStore from '../src/Component/ValueStore';
 import Component from '../src/Component';
 import Backend from '../src/Backend/Backend';
-import {StimulusElementDriver} from '../src/Component/ElementDriver';
 import { noopElementDriver } from './tools';
 
 const createStore = function(props: any = {}): ValueStore {

src/LiveComponent/assets/test/tools.ts

@@ -487,7 +487,7 @@ export class noopElementDriver implements ElementDriver {
         throw new Error('Method not implemented.');
     }
 
-    getModelName(element: HTMLElement): string | null {
+    getModelName(): string | null {
         throw new Error('Method not implemented.');
     }
 }

src/LiveComponent/doc/index.rst

@@ -2258,37 +2258,88 @@ To validate only on "change", use the ``on(change)`` modifier:
 Deferring / Lazy Loading Components
 -----------------------------------
 
+When a page loads, all components are rendered immediately. If a component is
+heavy to render, you can defer its rendering until after the page has loaded.
+This is done by making an Ajax call to load the component's real content either
+as soon as the page loads (``defer``) or when the component becomes visible
+(``lazy``).
+
+.. note::
+
+    Behind the scenes, your component *is* created & mounted during the initial
+    page load, but its template isn't rendered. So keep your heavy work to
+    methods in your component (e.g. ``getProducts()``) that are only called
+    from the component's template.
+
+Loading "defer" (Ajax on Load)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. versionadded:: 2.13.0
 
     The ability to defer loading a component was added in Live Components 2.13.
 
 If a component is heavy to render, you can defer rendering it until after
-the page has loaded. To do this, add the ``defer`` option:
+the page has loaded. To do this, add a ``loading="defer"`` attribute:
 
 .. code-block:: html+twig
 
-    {# With the HTML syntax #}
-    <twig:SomeHeavyComponent defer />
-
     {# With the component function #}
-    {{ component('SomeHeavyComponent', { defer: true }) }}
+    <twig:SomeHeavyComponent loading="defer" />
+
+.. code-block:: twig
+
+    {# With the HTML syntax #}
+    {{ component('SomeHeavyComponent', { loading: 'defer' }) }}
 
 This renders an empty ``<div>`` tag, but triggers an Ajax call to render the
 real component once the page has loaded.
 
-.. note::
+Loading "lazy" (Ajax when Visible)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    Behind the scenes, your component *is* created & mounted during the initial
-    page load, but it isn't rendered. So keep your heavy work to methods in
-    your component (e.g. ``getProducts()``) that are only called when rendering.
+.. versionadded:: 2.17.0
+
+    The ability to load a component "lazily" was added in Live Components 2.17.
+
+The ``lazy`` option is similar to ``defer``, but it defers the loading of
+the component until it's in the viewport. This is useful for components that
+are far down the page and are not needed until the user scrolls to them.
+
+To use this, set a ``loading="lazy"`` attribute to your component:
+
+.. code-block:: html+twig
+
+    {# With the HTML syntax #}
+    <twig:Acme foo="bar" loading="lazy" />
+
+.. code-block:: twig
+
+    {# With the Twig syntax #}
+    {{ component('SomeHeavyComponent', { loading: 'lazy' }) }}
+
+This renders an empty ``<div>`` tag. The real component is only rendered when
+it appears in the viewport.
+
+Defer or Lazy?
+~~~~~~~~~~~~~~
+
+The ``defer`` and ``lazy`` options may seem similar, but they serve different
+purposes:
+* ``defer`` is useful for components that are heavy to render but are required
+    when the page loads.
+* ``lazy`` is useful for components that are not needed until the user scrolls
+    to them (and may even never be rendered).
+
+Loading content
+~~~~~~~~~~~~~~~
 
 You can define some content to be rendered while the component is loading, either
 inside the component template (the ``placeholder`` macro) or from the calling template
 (the ``loading-template`` attribute and the ``loadingContent`` block).
 
-.. versionadded:: 2.17.0
+.. versionadded:: 2.16.0
 
-    Defining a placeholder macro into the component template was added in Live Components 2.17.0.
+    Defining a placeholder macro into the component template was added in Live Components 2.16.0.
 
 In the component template, define a ``placeholder`` macro, outside of the
 component's main content. This macro will be called when the component is deferred:
@@ -2317,7 +2368,7 @@ number of rows:
 .. code-block:: html+twig
 
     {# In the calling template #}
-    <twig:RecommendedProducts size="3" defer />
+    <twig:RecommendedProducts size="3" loading="defer" />
 
 .. code-block:: html+twig
 
@@ -2336,22 +2387,22 @@ the ``loading-template`` option to point to a template:
 .. code-block:: html+twig
 
     {# With the HTML syntax #}
-    <twig:SomeHeavyComponent defer loading-template="spinning-wheel.html.twig" />
+    <twig:SomeHeavyComponent loading="defer" loading-template="spinning-wheel.html.twig" />
 
     {# With the component function #}
-    {{ component('SomeHeavyComponent', { defer: true, loading-template: 'spinning-wheel.html.twig' }) }}
+    {{ component('SomeHeavyComponent', { loading: 'defer', loading-template: 'spinning-wheel.html.twig' }) }}
 
 Or override the ``loadingContent`` block:
 
 .. code-block:: html+twig
 
     {# With the HTML syntax #}
-    <twig:SomeHeavyComponent defer>
+    <twig:SomeHeavyComponent loading="defer">
         <twig:block name="loadingContent">Custom Loading Content...</twig:block>
     </twig:SomeHeavyComponent>
 
     {# With the component tag #}
-    {% component SomeHeavyComponent with { defer: true } %}
+    {% component SomeHeavyComponent with { loading: 'defer' } %}
         {% block loadingContent %}Loading...{% endblock %}
     {% endcomponent %}
 
@@ -2362,7 +2413,7 @@ To change the initial tag from a ``div`` to something else, use the ``loading-ta
 
 .. code-block:: twig
 
-    {{ component('SomeHeavyComponent', { defer: true, loading-tag: 'span' }) }}
+    {{ component('SomeHeavyComponent', { loading: 'defer', loading-tag: 'span' }) }}
 
 Polling
 -------

src/LiveComponent/src/EventListener/DeferLiveComponentSubscriber.php

@@ -31,11 +31,29 @@ final class DeferLiveComponentSubscriber implements EventSubscriberInterface
     public function onPostMount(PostMountEvent $event): void
     {
         $data = $event->getData();
+
         if (\array_key_exists('defer', $data)) {
-            $event->addExtraMetadata('defer', true);
+            trigger_deprecation('symfony/ux-live-component', '2.17', 'The "defer" attribute is deprecated and will be removed in 3.0. Use the "loading" attribute instead set to the value "defer".');
+            if ($data['defer']) {
+                $event->addExtraMetadata('loading', 'defer');
+            }
             unset($data['defer']);
         }
 
+        if (\array_key_exists('loading', $data)) {
+            // Ignored values: false / null / ''
+            if ($loading = $data['loading']) {
+                if (!\is_scalar($loading)) {
+                    throw new \InvalidArgumentException(sprintf('The "loading" attribute value must be scalar, "%s" passed.', get_debug_type($loading)));
+                }
+                if (!\in_array($loading, ['defer', 'lazy'], true)) {
+                    throw new \InvalidArgumentException(sprintf('Invalid "loading" attribute value "%s". Accepted values: "defer" and "lazy".', $loading));
+                }
+                $event->addExtraMetadata('loading', $loading);
+            }
+            unset($data['loading']);
+        }
+
         if (\array_key_exists('loading-template', $data)) {
             $event->addExtraMetadata('loading-template', $data['loading-template']);
             unset($data['loading-template']);
@@ -53,7 +71,10 @@ public function onPreRender(PreRenderEvent $event): void
     {
         $mountedComponent = $event->getMountedComponent();
 
-        if (!$mountedComponent->hasExtraMetadata('defer')) {
+        if (!$mountedComponent->hasExtraMetadata('loading')) {
+            return;
+        }
+        if (!\in_array($mountedComponent->getExtraMetadata('loading'), ['defer', 'lazy'], true)) {
             return;
         }
 
@@ -63,6 +84,7 @@ public function onPreRender(PreRenderEvent $event): void
         $variables = $event->getVariables();
         $variables['loadingTemplate'] = self::DEFAULT_LOADING_TEMPLATE;
         $variables['loadingTag'] = self::DEFAULT_LOADING_TAG;
+        $variables['loading'] = $mountedComponent->getExtraMetadata('loading');
 
         if ($mountedComponent->hasExtraMetadata('loading-template')) {
             $variables['loadingTemplate'] = $mountedComponent->getExtraMetadata('loading-template');

src/LiveComponent/templates/deferred.html.twig

@@ -1,4 +1,10 @@
-<{{ loadingTag }} {{ attributes }} data-action="live:connect->live#$render">
+<{{ loadingTag }} {{ attributes }}
+    {% if 'lazy' == loading %}
+        data-action="live:appear->live#$render" loading="lazy"
+    {% else %}
+        data-action="live:connect->live#$render"
+    {% endif %}
+>
     {% block loadingContent %}
         {% if loadingTemplate != null %}
             {{ include(loadingTemplate) }}

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

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symfony\UX\LiveComponent\Tests\Fixtures\Component;
+
+use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+use Symfony\UX\LiveComponent\Attribute\LiveAction;
+use Symfony\UX\LiveComponent\Attribute\LiveProp;
+use Symfony\UX\LiveComponent\DefaultActionTrait;
+
+#[AsLiveComponent('tally_component')]
+final class TallyComponent
+{
+    use DefaultActionTrait;
+
+    #[LiveProp]
+    public int $count = 0;
+
+    #[LiveAction]
+    public function click(): void
+    {
+        $this->count++;
+    }
+
+    #[LiveAction]
+    public function reset(): void
+    {
+        $this->count = 0;
+    }
+}

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

@@ -0,0 +1,9 @@
+<div {{ attributes }}>
+
+    <data id="count" value="{{ count }}">{{ count }}</data>
+
+    <button id="click" type="button" data-action="live#action" data-action-name="click">Click</button>
+
+    <button id="reset" type="button" data-action="live#action" data-action-name="reset">Reset</button>
+
+</div>

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

@@ -1 +1 @@
-<twig:deferred_component defer />
+<twig:deferred_component loading="defer" />

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

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