Adding explanations to the invoice live demo

Author: weaverryan

ux.symfony.com/assets/styles/_type.scss

@@ -224,3 +224,8 @@ h4.ubuntu {
     color: $n-300;
     font-weight: lighter;
 }
+
+blockquote {
+    border-left: 5px solid $n-200;
+    padding-left: 1rem;
+}

ux.symfony.com/templates/components/InvoiceCreatorLineItem.html.twig

@@ -8,7 +8,10 @@
             >
                 <option value="" {{ not product ? 'selected' }}>Choose a Product</option>
                 {% for productOption in products %}
-                    <option value="{{ productOption.id }}" {% if productOption == product %}selected{% endif %}>
+                    <option
+                        value="{{ productOption.id }}"
+                        {% if productOption == product %}selected{% endif %}
+                    >
                         {{ productOption.name }} ({{ productOption.priceInCents|format_currency('USD') }})
                     </option>
                 {% endfor %}

ux.symfony.com/templates/live_component_demo/invoice.html.twig

@@ -1,12 +1,55 @@
 {% extends 'liveDemoBase.html.twig' %}
 
 {% block code_block_full %}
-    <twig:TabbedCodeBlocks :files="[
-       'src/Twig/InvoiceCreator.php',
-       'templates/components/InvoiceCreator.html.twig',
-       'src/Twig/InvoiceCreatorLineItem.php',
-       'templates/components/InvoiceCreatorLineItem.html.twig',
-    ]" />
+    <twig:CodeWithExplanationRow filename="src/Twig/InvoiceCreator.php">
+This main component keeps track of the `Invoice` (which may be new) and
+a list of the "invoice items" - stored on a `LiveProp` called `$lineItems`.
+
+Because `LiveProp` values need to be (mostly) simple, the `$lineItems` are
+stored as a raw array of data, which we add to or remove from when line
+items are added/removed.
+
+This components listens to several events that the child
+`InvoiceCreatorLineItem` components emits. For example, the child emits
+`removeLineItem` when the user clicks the "x" button on a line item.
+This triggers the `removeLineItem()` method on this component, which
+removes the line item from the `$lineItems` array.
+    </twig:CodeWithExplanationRow>
+
+    <twig:CodeWithExplanationRow filename="templates/components/InvoiceCreator.html.twig" reversed>
+The template is fairly simple: rendering form fields with `data-model` to
+bind to writable `LiveProp`'s along with their validation errors.
+
+Most importantly, this loops over `$lineItems` and renders the
+`InvoiceCreatorLineItem` child component for each one passing the
+data: `productId`, `quantity`, and `isEditing`. It also passes a `key`,
+which is needed so LiveComponents can track which row is which.
+    </twig:CodeWithExplanationRow>
+
+    <twig:CodeWithExplanationRow filename="src/Twig/InvoiceCreatorLineItem.php">
+The child component for each "line item". This handles validating, saving,
+and changing the "edit" state of the line item.
+
+But all of the line item data ultimately needs to be stored on the parent
+component so that we can wait to save everything to the database. This
+component communicates the new data (or "edit" state change) to the parent
+by emitting events - e.g. `line_item:save`.
+
+> Note: it would be simpler to manage the `isEditing` state directly on this
+> component, instead of passing it to the parent. It was done this way so that
+> the parent component can know how many of its children are currently in
+> "edit" mode.
+    </twig:CodeWithExplanationRow>
+
+    <twig:CodeWithExplanationRow filename="templates/components/InvoiceCreatorLineItem.html.twig" reversed>
+Nothing too fancy here: some `data-model` elements and `data-action="live#action"`
+buttons.
+
+The most interesting part is the "X" button to remove a line item: this uses
+`data-action="live#emitUp"` to emit the `removeLineItem` event to the parent component.
+In this case, instead of triggering a `LiveAction` that *then* emits the event,
+we emit the event directly.
+    </twig:CodeWithExplanationRow>
 {% endblock %}
 
 {% block demo_content %}

ux.symfony.com/templates/live_component_demo/product_form.html.twig

@@ -10,7 +10,7 @@ Live component with a form, `ValidatableComponentTrait` and a
 `saveProduct()` LiveAction for instant validation & an AJAX submit.
 
 The real magic comes from `#[LiveListener('category:created')`. This
-is emitted by the [NewCategoryForm](#NewCategoryForm.php) component (which opens
+is emitted by the `NewCategoryForm` component (which opens
 in a modal) when a new category is created.
 
 Note: the `category:created` event emits `category` as an *integer*.
@@ -20,7 +20,7 @@ Symfony uses that id to query for the `Category` object.
     </twig:CodeWithExplanationRow>
 
     <twig:CodeWithExplanationRow filename="templates/components/NewProductForm.html.twig" reversed>
-Near the bottom, this renders the [BootstrapModal](#BootstrapModal.php) component with another
+Near the bottom, this renders the `BootstrapModal` component with another
 component - `NewCategoryForm` - inside of it. Opening the modal is done entirely
 with normal Bootstrap logic: an `a` tag with `data-bs-toggle="modal"`
 and `data-bs-target="#new-category-modal"`.
@@ -31,9 +31,9 @@ This component opens up in the modal! It has a `#[LiveAction]` that saves
 the new `Category` to the database and then does two important things:
 
 1. Emits the `category:created` event with the new `Category`'s id (see
-   [NewProductForm.php](#NewProductForm.php)).
+   `NewProductForm.php`).
 1. Dispatches a browser event called `modal:closed` to close the modal
-   (see [bootstrap-modal-controller.js](#bootstrap-modal-controller.js)).
+   (see `bootstrap-modal-controller.js`).
     </twig:CodeWithExplanationRow>