document embedded components

Author: kbond

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

@@ -646,6 +646,73 @@ 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 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 %}``. 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>
+                            {% block th %}{{ header }}{% endblock %}
+                        </th>
+                    {% endfor %}
+                </tr>
+            </thead>
+            <tbody>
+                {% for row in this.data %}
+                    <tr>
+                        {% for cell in row %}
+                            <td>
+                                {% block td %}{{ cell }}{% endblock %}
+                            </td>
+                        {% endfor %}
+                    </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+        {% if block('footer') is defined %}
+            <div class="data-table-footer">
+                {{ block('footer') }}
+            </div>
+        {% endif %}
+    </div>
+
+When rendering, you can override the ``th``, ``th`` blocks and add a ``footer`` block.
+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 %}custom th ({{ parent() }}){% endblock %}
+        {% block td %}custom td ({{ parent() }}){% endblock %}
+
+        {% block footer %}My footer{% endblock %}
+    {% endcomponent %}
+
+.. note::
+
+    Embedded components *cannot* currently be used with LiveComponents.
+
 Contributing
 ------------
 
@@ -667,3 +734,4 @@ meaning it is not bound to Symfony's BC policy for the moment.
 .. _`Vue`: https://v3.vuejs.org/guide/computed.html
 .. _`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