From a62c813a365e92f5f85dafc299aea8649764240d Mon Sep 17 00:00:00 2001
From: sneakyvv <bart.vanderstukken@gmail.com>
Date: Thu, 24 Aug 2023 22:29:39 +0200
Subject: [PATCH] [TwigComponent][LiveComponent] Add Embedded Live Components
 doc

---
 src/LiveComponent/doc/index.rst | 31 +++++++++++++++++++++++++++++++
 src/TwigComponent/doc/index.rst | 13 +++++++++----
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/src/LiveComponent/doc/index.rst b/src/LiveComponent/doc/index.rst
index eb884847698..ae76306647a 100644
--- a/src/LiveComponent/doc/index.rst
+++ b/src/LiveComponent/doc/index.rst
@@ -2911,6 +2911,36 @@ To fix this, you have two options:
         }
     }
 
+.. _passing-blocks:
+
+Passing Content (Blocks) to Components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Passing content via blocks to Live components works completely the same way you would `pass content to Twig Components`_.
+Except with one important difference: when a component is re-rendered, any variables defined only in the
+"outside" template will not be available. For example, this won't work:
+
+.. code-block:: twig
+
+    {# templates/some_page.html.twig #}
+    {% set message = 'Variables from the outer part of the template are only available during  the initial render' %}
+
+    {% component Alert %}
+        {% block content %}{{ message }}{% endblock %}
+    {% endcomponent %}
+
+Local variables do remain available:
+
+.. code-block:: twig
+
+    {# templates/some_page.html.twig #}
+    {% component Alert %}
+        {% block content %}
+            {% set message = 'this works during re-rendering!' %}
+            {{ message }}
+        {% endblock %}
+    {% endcomponent %}
+
 Advanced Functionality
 ----------------------
 
@@ -3127,3 +3157,4 @@ bound to Symfony's BC policy for the moment.
 .. _`the traditional collection type`: https://symfony.com/doc/current/form/form_themes.html#fragment-naming-for-collections
 .. _`How to Work with Form Themes`: https://symfony.com/doc/current/form/form_themes.html
 .. _`Symfony's built-in form theming techniques`: https://symfony.com/doc/current/form/form_themes.html
+.. _`pass content to Twig Components`: https://symfony.com/bundles/ux-twig-component/current/index.html#passing-blocks
diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst
index 2cd8c8137e9..dfca8b8172b 100644
--- a/src/TwigComponent/doc/index.rst
+++ b/src/TwigComponent/doc/index.rst
@@ -830,9 +830,11 @@ The ``with`` data is what's mounted on the component object.
         {% endblock %}
     {% endcomponent %}
 
-.. note::
+.. versionadded:: 2.11
 
-    The ``{% component %}`` syntax *cannot* currently be used with LiveComponents.
+    The ``{% component %}`` syntax can also be used with LiveComponents since 2.11.
+    However, there are some caveats related to the context between parent and child
+    components during re-rending. Read `Passing Blocks to Live Components`_.
 
 Inheritance & Forwarding "Outer Blocks"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1004,8 +1006,10 @@ This requires Twig 3.7.0 or higher:
 
     <twig:Alert{{ ...myAttributes }} />
 
-Passing Blocks to your Component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _passing-blocks:
+
+Passing Content (Blocks) to Components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also pass content directly to your component:
 
@@ -1121,5 +1125,6 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`live component`: https://symfony.com/bundles/ux-live-component/current/index.html
 .. _`Vue`: https://v3.vuejs.org/guide/computed.html
 .. _`Live Nested Components`: https://symfony.com/bundles/ux-live-component/current/index.html#nested-components
+.. _`Passing Blocks to Live Components`: https://symfony.com/bundles/ux-live-component/current/index.html#passing-blocks
 .. _`embed tag`: https://twig.symfony.com/doc/3.x/tags/embed.html
 .. _`Stimulus controller`: https://symfony.com/bundles/StimulusBundle/current/index.html