[Live] Fixing a bug where data-original-data was lost on child components

Author: weaverryan

src/LiveComponent/assets/dist/live_controller.js

@@ -1024,6 +1024,7 @@ class default_1 extends Controller {
         this.pollingIntervals = [];
         this.isWindowUnloaded = false;
         this.originalDataJSON = '{}';
+        this.mutationObserver = null;
         this.markAsWindowUnloaded = () => {
             this.isWindowUnloaded = true;
         };
@@ -1042,6 +1043,7 @@ class default_1 extends Controller {
             this._initiatePolling(this.element.dataset.poll);
         }
         window.addEventListener('beforeunload', this.markAsWindowUnloaded);
+        this._startAttributesMutationObserver();
         this.element.addEventListener('live:update-model', (event) => {
             if (event.target === this.element) {
                 return;
@@ -1055,6 +1057,9 @@ class default_1 extends Controller {
             clearInterval(interval);
         });
         window.removeEventListener('beforeunload', this.markAsWindowUnloaded);
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+        }
     }
     update(event) {
         this._updateModelFromElement(event.target, this._getValueFromElement(event.target), true);
@@ -1517,6 +1522,19 @@ class default_1 extends Controller {
         }
         this.element.dataset.originalData = this.originalDataJSON;
     }
+    _startAttributesMutationObserver() {
+        this.mutationObserver = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+                if (mutation.type === 'attributes' && !this.element.dataset.originalData) {
+                    this.originalDataJSON = JSON.stringify(this.dataValue);
+                    this._exposeOriginalData();
+                }
+            });
+        });
+        this.mutationObserver.observe(this.element, {
+            attributes: true
+        });
+    }
 }
 default_1.values = {
     url: String,

src/LiveComponent/assets/src/live_controller.ts

@@ -60,6 +60,8 @@ export default class extends Controller {
 
     originalDataJSON = '{}';
 
+    mutationObserver: MutationObserver|null = null;
+
     initialize() {
         this.markAsWindowUnloaded = this.markAsWindowUnloaded.bind(this);
         this.originalDataJSON = JSON.stringify(this.dataValue);
@@ -82,6 +84,8 @@ export default class extends Controller {
 
         window.addEventListener('beforeunload', this.markAsWindowUnloaded);
 
+        this._startAttributesMutationObserver();
+
         this.element.addEventListener('live:update-model', (event) => {
             // ignore events that we dispatched
             if (event.target === this.element) {
@@ -100,6 +104,10 @@ export default class extends Controller {
         });
 
         window.removeEventListener('beforeunload', this.markAsWindowUnloaded);
+
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+        }
     }
 
     /**
@@ -790,6 +798,34 @@ export default class extends Controller {
 
         this.element.dataset.originalData = this.originalDataJSON;
     }
+
+    /**
+     * Re-establishes the data-original-data attribute if missing.
+     *
+     * This happens if a parent component re-renders a child component
+     * and morphdom *updates* child. This commonly happens if a parent
+     * component is around a list of child components, and changing
+     * something in the parent causes the list to change. In that case,
+     * the a child component might be removed while another is added.
+     * But to morphdom, this sometimes looks like an "update". The result
+     * is that the child component is re-rendered, but the child component
+     * is not re-initialized. And so, the data-original-data attribute
+     * is missing and never re-established.
+     */
+    _startAttributesMutationObserver() {
+        this.mutationObserver = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+                if (mutation.type === 'attributes' && !this.element.dataset.originalData) {
+                    this.originalDataJSON = JSON.stringify(this.dataValue);
+                    this._exposeOriginalData();
+                }
+            });
+        });
+
+        this.mutationObserver.observe(this.element, {
+            attributes: true
+        });
+    }
 }
 
 /**

src/LiveComponent/assets/test/controller/child.test.ts

@@ -193,4 +193,44 @@ describe('LiveController parent -> child component tests', () => {
 
         expect(controller.dataValue).toEqual({ textareaContent: 'changed content' });
    });
+
+    it('updates child data-original-data on parent re-render', async () => {
+        const parentTemplateListOfChildren = (data) => `
+            <div
+                ${initLiveComponent('/_components/parent', data)}
+            >
+                <ul>
+                    ${data.children.map((child) => {
+                        return `
+                            <li ${initLiveComponent('/_components/child', child)}>
+                               ${child.name}
+                            </li>
+                        `
+                    })}
+                </ul>
+
+                <button
+                    data-action="live#$render"
+                >Parent Re-render</button>
+            </div>
+        `;
+
+        const data = { children: [{name: 'child1'}, {name: 'child2'}, {name: 'child3'}] };
+        const { element, controller } = await startStimulus(parentTemplateListOfChildren(data));
+
+        // mock a re-render where "child2" disappears
+        mockRerender(data, parentTemplateListOfChildren, (returnedData) => {
+            returnedData.children = [{name: 'child1'}, {name: 'child3'}];
+        });
+        getByText(element, 'Parent Re-render').click();
+
+        await waitFor(() => expect(element).not.toHaveTextContent('child2'));
+        const secondLi = element.querySelectorAll('li').item(1);
+        expect(secondLi).not.toBeNull();
+        // the 2nd li was just "updated" by the parent component, which
+        // would have eliminated its data-original-data attribute. Check
+        // that it was re-established to the 3rd child's data.
+        // see MutationObserver in live_controller for more details.
+        expect(secondLi.dataset.originalData).toEqual(JSON.stringify({name: 'child3'}));
+   });
 });

src/LiveComponent/src/Resources/doc/index.rst

@@ -1655,6 +1655,20 @@ form. But it also makes sure that when the ``textarea`` changes, both
 the ``value`` model in ``MarkdownTextareaComponent`` *and* the
 ``post.content`` model in ``EditPostcomponent`` will be updated.
 
+Rendering Quirks with List of Embedded Components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imagine your component renders a list of embedded components and
+that list is updated as the user types into a search box. Most of the
+time, this works *fine*. But in some cases, as the list of items
+changes, a child component will re-render even though it was there
+before *and* after the list changed. This can cause that child component
+to lose some state (i.e. it re-renders with its original live props data).
+
+To fix this, add a unique ``id`` attribute to the root component of each
+child element. This will helps LiveComponent identify each item in the
+list and correctly determine if a re-render is necessary, or not.
+
 Skipping Updating Certain Elements
 ----------------------------------