Adding a data-model-map to map child models to the parent

Author: weaverryan

src/LiveComponent/README.md

@@ -1141,11 +1141,11 @@ You can also trigger a specific "action" instead of a normal re-render:
 
 ## Embedded Components
 
-Can you embed one live component inside another one? Absolutely! As a rule
+Need to embed one live component inside another one? No problem! As a rule
 of thumb, **each component exists in its own, isolated universe**. This
-means that embedding one component inside another might be really simple...
-or a bit more complex if your components share "model" data or are
-"connected" in other ways.
+means that embedding one component inside another could be really simple
+or a bit more complex, depending on how inter-connected you want your components
+to be.
 
 Here are a few helpful things to know:
 
@@ -1155,11 +1155,11 @@ If a parent component re-renders, the child component will _not_ (most
 of the time) be updated, even though it lives inside the parent. Each
 component is its own, isolated universe.
 
-But... this is not always what you want. For example, suppose a
-parent component holds a form and a child component holds one field.
-When you click a "Save" button on the parent component, it validates
-the form and re-renders with errors - including a new `error` value
-that it passes into the child:
+But this is not always what you want. For example, suppose you have a
+parent component that renders a form and a child component that renders
+one field in that form. When you click a "Save" button on the parent
+component, that validates the form and re-renders with errors - including
+a new `error` value that it passes into the child:
 
 ```twig
 {# templates/components/post_form.html.twig #}
@@ -1172,20 +1172,24 @@ that it passes into the child:
 
 In this situation, when the parent component re-renders after clicking
 "Save", you _do_ want the updated child component (with the validation
-error) to be rendered. And, this _will_ happen because the system detects
-that the parent component has _changed_ how it's rendering the child.
+error) to be rendered. And this _will_ happen automatically. Why? because
+the live component system detects that the **parent component has
+_changed_ how it's rendering the child**.
 
 This may not always be perfect, and if your child component has its own
 `LiveProp` that has changed since it was first rendered, that value will
-be lost when the parent component causes the child to re-render.
+be lost when the parent component causes the child to re-render. If you
+have this situation, use `data-model-map` to map that child `LiveProp` to
+a `LiveProp` in the parent component, and pass it into the child when
+rendering.
 
 ### Actions, methods and model updates in a child do not affect the parent
 
 Again, each component is its own, isolated universe! For example, suppose
 your child component has:
 
 ```html
-<button data-action="live#action" data-action-name="save"></button>
+<button data-action="live#action" data-action-name="save">Save</button>
 ```
 
 When the user clicks that button, it will attempt to call the `save` action
@@ -1209,7 +1213,7 @@ However, sometimes this isn't what you want! Sometimes, in addition
 to updating the child component's model, you _also_ want to update a
 model on the _parent_ component.
 
-To help with this, whenever a model updates, a `live:update-model`
+To help with this, whenever a model updates, a `live:update-model` event
 is dispatched. All components automatically listen to this event. This
 means that, when the `markdown_value` model is updated in the child
 component, _if_ the parent component _also_ has a model called `markdown_value`
@@ -1218,8 +1222,8 @@ it will _also_ be updated. This is done as a "deferred" update
 
 If the model name in your child component (e.g. `markdown_value`) is
 _different_ than the model name in your parent component (e.g. `post.content`),
-you can make sure both are set by leveraging both the `data-model`
-and `name` attributes:
+you have two options. First, you can make sure both are set by
+leveraging both the `data-model` and `name` attributes:
 
 ```twig
 <textarea
@@ -1234,7 +1238,25 @@ component (because `data-model` takes precedence over `name`). But if
 any parent components have a `markdown_value` model _or_ a `post.content`
 model (normalized from `post[content`]`), their model will also be updated.
 
-**NOTE**: If you _change_ a `LiveProp` ofa child component on the server
+A second option is to wrap your child element in a special `data-model-map`
+element:
+
+```twig
+{# templates/components/post_form.html.twig #}
+
+<div data-model-map="from(markdown_value)|post.content">
+    {{ component('textarea_field', {
+        value: this.content,
+        error: this.getError('content')
+    }) }}
+</div>
+```
+
+Thanks to the `data-model-map`, whenever the `markdown_value` model
+updates in the child component, the `post.content` model will be
+updated in the parent component.
+
+**NOTE**: If you _change_ a `LiveProp` of a child component on the server
 (e.g. during re-rendering or via an action), that change will _not_ be
 reflected on any parent components that share that model.
 

src/LiveComponent/assets/src/live_controller.js

@@ -603,19 +603,69 @@ export default class extends Controller {
 
     _handleChildComponentUpdateModel(event) {
         let matchingModelName = null;
+        const mainModelName = event.detail.modelName;
+        const potentialModelNames = [
+            { name: mainModelName, required: false },
+            { name: event.detail.extraModelName, required: false },
+        ]
 
-        if (doesDeepPropertyExist(this.dataValue, event.detail.modelName)) {
-            matchingModelName = event.detail.modelName;
-        } else if (doesDeepPropertyExist(this.dataValue, event.detail.extraModelName)) {
-            matchingModelName = event.detail.extraModelName;
+        const modelMapElement = event.target.closest('[data-model-map]');
+        if (this.element.contains(modelMapElement)) {
+            const directives = parseDirectives(modelMapElement.dataset.modelMap);
+
+            directives.forEach((directive) => {
+                let from = null;
+                directive.modifiers.forEach((modifier) => {
+                    switch (modifier.name) {
+                        case 'from':
+                            if (!modifier.value) {
+                                throw new Error(`The from() modifier requires a model name in data-model-map="${modelMapElement.dataset.modelMap}"`);
+                            }
+                            from = modifier.value;
+
+                            break;
+                        default:
+                            console.warn(`Unknown modifier "${modifier.name}" in data-poll "${rawPollConfig}".`);
+                    }
+                });
+
+                if (!from) {
+                    throw new Error(`Missing from() modifier in data-model-map="${modelMapElement.dataset.modelMap}". The format should be "from(childModelName)|parentModelName"`);
+                }
+
+                // only look maps for the model currently being updated
+                if (from !== mainModelName) {
+                    return;
+                }
+
+                potentialModelNames.push({ name: directive.action, required: true });
+            });
         }
 
-        if (matchingModelName === null) {
+        potentialModelNames.reverse();
+        let foundModelName = null;
+        potentialModelNames.forEach((potentialModel) => {
+            if (foundModelName) {
+                return;
+            }
+
+            if (doesDeepPropertyExist(this.dataValue, potentialModel.name)) {
+                foundModelName = potentialModel.name;
+
+                return;
+            }
+
+            if (potentialModel.required) {
+                throw new Error(`The model name "${potentialModel.name}" does not exist! Found in data-model-map="from(${mainModelName})|${potentialModel.name}"`);
+            }
+        });
+
+        if (!foundModelName) {
             return;
         }
 
         this.$updateModel(
-            matchingModelName,
+            foundModelName,
             event.detail.value,
             false,
             null,

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

@@ -165,6 +165,39 @@ describe('LiveController parent -> child component tests', () => {
         expect(element).toHaveTextContent('Rows in child: not set');
     });
 
+    it('uses data-model-map to map child models to parent models', async () => {
+        const parentTemplateDifferentModel = (data) => `
+            <div
+                ${initLiveComponent('/_components/parent', data)}
+            >
+                <span>Parent textarea content: ${data.textareaContent}</span>
+
+                <div
+                    data-model-map="from(value)|textareaContent"
+                >
+                    ${childTemplate({ value: data.textareaContent, error: null })}
+                </div>
+
+                <button
+                    data-action="live#$render"
+                >Parent Re-render</button>
+            </div>
+        `;
+
+        const data = { textareaContent: 'Original content' };
+        const { element, controller } = await startStimulus(parentTemplateDifferentModel(data));
+
+        // update & re-render the child component
+        const inputElement = getByLabelText(element, 'Content:');
+        await userEvent.clear(inputElement);
+        await userEvent.type(inputElement, 'changed content');
+        mockRerender({value: 'changed content'}, childTemplate);
+
+        await waitFor(() => expect(element).toHaveTextContent('Value in child: changed content'));
+
+        expect(controller.dataValue).toEqual({ textareaContent: 'changed content' });
+   });
+
     // TODO - what if a child component re-renders and comes down with
     // a changed set of data? Should that update the parent's data?
 });