[Live] Adding more detail about dealing with loops

Author: weaverryan

src/LiveComponent/doc/index.rst

@@ -2631,6 +2631,23 @@ Notice that ``MarkdownTextarea`` allows a dynamic ``name``
 attribute to be passed in. This makes that component re-usable in any
 form.
 
+Rendering Quirks with List of Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're rendering a list of elements in your component, to help LiveComponents
+understand which element is which between re-renders (i.e. if something re-orders
+or removes some of those elements), you can add a ``data-live-id`` attribute to
+each element
+
+.. code-block:: twig
+
+    {# templates/components/Invoice.html.twig #}
+    {% for lineItem in lineItems %}
+        <div data-live-id="{{ lineItem.id }}">
+            {{ lineItem.name }}
+        </div>
+    {% endfor %}
+
 Rendering Quirks with List of Embedded Components
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2650,8 +2667,8 @@ to that component:
 
     {# templates/components/Invoice.html.twig #}
     {% for lineItem in lineItems %}
-        {{ component('invoice_line_item', {
-            productId: lineItem.productId,
+        {{ component('InvoiceLineItem', {
+            lineItem: lineItem,
             key: lineItem.id,
         }) }}
     {% endfor %}
@@ -2661,6 +2678,125 @@ which will be used to identify each child component. You can
 also pass in a ``data-live-id`` attribute directly, but ``key`` is
 a bit more convenient.
 
+Tricks with a Loop + a "New" Item
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's get fancier. Suppose you're rendering all of the line items
+inside of an `InvoiceCreator` component. After the loop, you might
+decide to render one more component to create a *new* line item.
+In that case, you can pass in a ``key`` set to something like ``new_line_item``:
+
+.. code-block:: twig
+
+    {{ component('InvoiceLineItem', {
+        key: 'new_line_item',
+    }) }}
+
+Imagine you also have a ``LiveAction`` inside of ``InvoiceLineItem``
+that saves the new line item to the database. To be extra fancy,
+it emits a ``lineItem:created`` event to the parent::
+
+    // src/Twig/InvoiceLineItem.php
+    // ...
+
+    #[AsLiveComponent]
+    final class InvoiceLineItem
+    {
+        // ...
+
+        #[LiveProp]
+        #[Valid]
+        public InvoiceLineItem $lineItem;
+
+        #[PostMount]
+        public function postMount(): void
+        {
+            if(!$this->lineItem) {
+                $this->lineItem = new InvoiceLineItem();
+            }
+        }
+
+        #[LiveAction]
+        public function save(EntityManagerInterface $entityManager)
+        {
+            if (!$this->lineItem->getId()) {
+                $this->emit('lineItem:created', $this->lineItem);
+            }
+
+            $entityManager->persist($this->lineItem);
+            $entityManager->flush();
+        }
+    }
+
+Finally, the parent ``InvoiceCreator`` component listens to this
+so that it can re-render the line items (which will now contain the
+newly-saved item)::
+
+    // src/Twig/InvoiceCreator.php
+    // ...
+
+    #[AsLiveComponent]
+    final class InvoiceCreator
+    {
+        // ...
+
+        #[LiveListener('lineItem:created')]
+        public function addLineItem()
+        {
+            // no need to do anything here: the component will re-render
+        }
+    }
+
+This will work beautifully: when a new line item is saved, the ``InvoiceCreator``
+component will re-render and the newly saved line item will be displayed along
+with the extra ``new_line_item`` component at the bottom.
+
+But something surprising might happen: the ``new_line_item`` component won't
+update! It will *keep* the data and props that were there a moment ago (i.e. the
+form fields will still have data in them) instead of rendering a fresh, empty component.
+
+Why? When live components re-renders, it thinks the existing ``key: new_line_item``
+component on the page is the *same* new component that it's about to render. And
+because the props passed into that component haven't changed, it doesn't see any
+reason to re-render it.
+
+To fix this, you haev two options:
+
+1. Make the ``key`` dynamic so it will be different after adding a new item::
+
+.. code-block:: twig
+
+    {{ component('InvoiceLineItem', {
+        key: 'new_line_item_' lineItems|length,
+    }) }}
+
+2. Reset the state of the ``InvoiceLineItem`` component after it's saved::
+
+    // src/Twig/InvoiceLineItem.php
+
+    // ...
+    class InvoiceLineItem
+    {
+        // ...
+
+        #[LiveAction]
+        public function save(EntityManagerInterface $entityManager)
+        {
+            $isNew = null === $this->lineItem->getId();
+
+            $entityManager->persist($this->lineItem);
+            $entityManager->flush();
+
+            if ($isNew) {
+                // reset the state of this component
+                $this->emit('lineItem:created', $this->lineItem);
+                $this->lineItem = new InvoiceLineItem();
+                // if you're using ValidatableComponentTrait
+                $this->clearValidation();
+            }
+        }
+    }
+
 Advanced Functionality
 ----------------------