Adding section about data-live-id

Author: weaverryan

src/LiveComponent/doc/index.rst

@@ -2350,6 +2350,8 @@ a model in a child updates, it won't also update that model in its parent
 The parent-child system is *smart*. And with a few tricks, you can make
 it behave exactly like you need.
 
+.. _child-component-independent-rerender:
+
 Each component re-renders independent of one another
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2631,6 +2633,8 @@ Notice that ``MarkdownTextarea`` allows a dynamic ``name``
 attribute to be passed in. This makes that component re-usable in any
 form.
 
+.. _rendering-loop-of-elements:
+
 Rendering Quirks with List of Elements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2648,6 +2652,8 @@ each element
         </div>
     {% endfor %}
 
+.. _key-prop:
+
 Rendering Quirks with List of Embedded Components
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2678,6 +2684,8 @@ 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.
 
+.. _rendering-loop-new-element:
+
 Tricks with a Loop + a "New" Item
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2831,6 +2839,40 @@ The system doesn't handle every edge case, so here are some things to keep in mi
   that change is **lost**: the element will be re-added in its original location
   during the next re-render.
 
+The Mystical data-live-id Attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``data-live-id`` attribute is mentioned several times throughout the documentation
+to solve various problems. It's usually not needed, but can be the key to solving
+certain complex problems. But what is it?
+
+.. note::
+
+    The :ref:`key prop <key-prop>` is used to create a ``data-live-id`` attribute
+    on child components. So everything in this section applies equally to the
+    ``key`` prop.
+
+The ``data-live-id`` attribute is a unique identifier for an element or a component.
+It's used when a component re-renders and helps Live Components "connect" elements
+or components in the existing HTML with the new HTML. The logic works like this:
+
+Suppose an element or component in the new HTML has a ``data-live-id="some-id`` attribute.
+Then:
+
+A) If there **is** an element or component with ``data-live-id="some-id"`` in the
+   existing HTML, then the old and new elements/components are considered to be the
+   "same". For elements, the new element will be used to update the old element even
+   if the two elements appear in different places - e.g. like if :ref:`elements are moved <rendering-loop-of-elements>`
+   or re-ordered. For components, because child components render independently
+   from their parent, the existing component will be "left alone" and not re-rendered
+   (unless some ``updateFromParent`` props have changed - see :ref:`child-component-independent-rerender`).
+
+B) If there is **not** an element or component with ``data-live-id="some-id"`` in
+   the existing HTML, then the new element or component is considered to be "new".
+   In both cases, the new element or component will be added to the page. If there
+   is a component/element with a ``data-live-id`` attribute that is *not* in the
+   new HTML, that component/element will be removed from the page.
+
 Skipping Updating Certain Elements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~