doc'ing how to set values via JS, auto-set "value" of model elements, sync empty select fields

2 features/bugs mixed together:

1) Auto-setting "value" of data-model elements from component data

2) Fixing bug where select element without a blank doesn't sync value back to component

Fixing a few model-related rendering bugs

A) Only re-set values after re-render for models that have fully changed,
not just fields that have been modified (but show value may not be synced
back to the value store yet)

B) When setting the value property on an input, skip any models that we
know are in an unsynced state (i.e. we know they have a field that has
changed, but the value hasn't been set onto the value store yet)

Author: weaverryan

src/LiveComponent/CHANGELOG.md

@@ -9,6 +9,23 @@
     it finishes. Then, all queued changes (potentially multiple model updates
     or actions) will be sent all at once on the next request.
 
+-   [BEHAVIOR CHANGE] Fields with `data-model` will now have their `value` set
+    automatically when the component initially loads and re-renders. For example,
+    previously you needed to manually set the value in your component template:
+
+    ```twig
+    <!-- BEFORE -->
+    <input data-model="firstName" value="{{ firstName }}">
+    ```
+
+    This is no longer necessary: Live Components will now set the value on load,
+    which allows you to simply have the following in your template:
+
+    ```twig
+    <!-- AFTER -->
+    <input data-model="firstName">
+    ```
+
 ## 2.4.0
 
 -   [BC BREAK] Previously, the `id` attribute was used with `morphdom` as the

src/LiveComponent/assets/dist/live_controller.js

@@ -1,3 +1,11 @@
+/**
+ * Tracks field & models whose values are "unsynced".
+ *
+ * Unsynced means that the value has been updated inside of
+ * a field (e.g. an input), but that this new value hasn't
+ * yet been set onto the actual model data. It is "unsynced"
+ * from the underlying model data.
+ */
 export default class UnsyncedInputContainer {
     #mappedFields: Map<string, HTMLElement>;
     #unmappedFields: Array<HTMLElement> = [];
@@ -20,11 +28,11 @@ export default class UnsyncedInputContainer {
         return [...this.#unmappedFields, ...this.#mappedFields.values()]
     }
 
-    allMappedFields(): Map<string, HTMLElement> {
-        return this.#mappedFields;
+    markModelAsSynced(modelName: string): void {
+        this.#mappedFields.delete(modelName);
     }
 
-    remove(modelName: string) {
-        this.#mappedFields.delete(modelName);
+    getModifiedModels(): string[] {
+        return Array.from(this.#mappedFields.keys());
     }
 }

src/LiveComponent/assets/src/UnsyncedInputContainer.ts

@@ -11,10 +11,10 @@ import { normalizeModelName } from './string_utils';
  * elements. In those cases, it will return the "full", final value
  * for the model, which includes previously-selected values.
  */
-export function getValueFromInput(element: HTMLElement, valueStore: ValueStore): string|string[]|null {
+export function getValueFromElement(element: HTMLElement, valueStore: ValueStore): string|string[]|null {
     if (element instanceof HTMLInputElement) {
         if (element.type === 'checkbox') {
-            const modelNameData = getModelDirectiveFromInput(element);
+            const modelNameData = getModelDirectiveFromElement(element);
             if (modelNameData === null) {
                 return null;
             }
@@ -46,7 +46,7 @@ export function getValueFromInput(element: HTMLElement, valueStore: ValueStore):
 
     // e.g. a textarea
     if ('value' in element) {
-        // the "as" is a cheap way to hint to TypeScript that the value propery exists
+        // the "as" is a cheap way to hint to TypeScript that the value property exists
         return (element as HTMLInputElement).value;
     }
 
@@ -57,7 +57,61 @@ export function getValueFromInput(element: HTMLElement, valueStore: ValueStore):
     return null;
 }
 
-export function getModelDirectiveFromInput(element: HTMLElement, throwOnMissing = true): null|Directive {
+/**
+ * Adapted from https://github.com/livewire/livewire
+ */
+export function setValueOnElement(element: HTMLElement, value: any): void {
+    if (element instanceof HTMLInputElement) {
+        if (element.type === 'file') {
+            return;
+        }
+
+        if (element.type === 'radio') {
+            element.checked = element.value == value
+
+            return;
+        }
+
+        if (element.type === 'checkbox') {
+            if (Array.isArray(value)) {
+                // I'm purposely not using Array.includes here because it's
+                // strict, and because of Numeric/String mis-casting, I
+                // want the "includes" to be "fuzzy".
+                let valueFound = false
+                value.forEach(val => {
+                    if (val == element.value) {
+                        valueFound = true
+                    }
+                })
+
+                element.checked = valueFound
+            } else {
+                element.checked = element.value == value;
+            }
+
+            return;
+        }
+    }
+
+    if (element instanceof HTMLSelectElement) {
+        const arrayWrappedValue = [].concat(value).map(value => {
+            return value + ''
+        })
+
+        Array.from(element.options).forEach(option => {
+            option.selected = arrayWrappedValue.includes(option.value)
+        })
+
+        return;
+    }
+
+    value = value === undefined ? '' : value;
+
+    // silencing the typescript warning
+    (element as HTMLInputElement).value = value
+}
+
+export function getModelDirectiveFromElement(element: HTMLElement, throwOnMissing = true): null|Directive {
     if (element.dataset.model) {
         const directives = parseDirectives(element.dataset.model);
         const directive = directives[0];

src/LiveComponent/assets/src/dom_utils.ts

@@ -5,7 +5,15 @@ import { combineSpacedArray, normalizeModelName } from './string_utils';
 import { haveRenderedValuesChanged } from './have_rendered_values_changed';
 import { normalizeAttributesForComparison } from './normalize_attributes_for_comparison';
 import ValueStore from './ValueStore';
-import { elementBelongsToThisController, getModelDirectiveFromInput, getValueFromInput, cloneHTMLElement, htmlToElement, getElementAsTagText } from './dom_utils';
+import {
+    elementBelongsToThisController,
+    getModelDirectiveFromElement,
+    getValueFromElement,
+    cloneHTMLElement,
+    htmlToElement,
+    getElementAsTagText,
+    setValueOnElement
+} from './dom_utils';
 import UnsyncedInputContainer from './UnsyncedInputContainer';
 
 interface ElementLoadingDirectives {
@@ -88,6 +96,7 @@ export default class extends Controller implements LiveController {
         this.originalDataJSON = this.valueStore.asJson();
         this.unsyncedInputs = new UnsyncedInputContainer();
         this._exposeOriginalData();
+        this.synchronizeValueOfModelFields();
     }
 
     connect() {
@@ -198,7 +207,7 @@ export default class extends Controller implements LiveController {
                 // if so, to be safe, slightly delay the action so that the
                 // change/input listener on LiveController can process the
                 // model change *before* sending the action
-                if (getModelDirectiveFromInput(event.currentTarget, false)) {
+                if (getModelDirectiveFromElement(event.currentTarget, false)) {
                     this.pendingActionTriggerModelElement = event.currentTarget;
                     this.#clearRequestDebounceTimeout();
                     window.setTimeout(() => {
@@ -234,7 +243,7 @@ export default class extends Controller implements LiveController {
             throw new Error('Could not update model for non HTMLElement');
         }
 
-        const modelDirective = getModelDirectiveFromInput(element, false);
+        const modelDirective = getModelDirectiveFromElement(element, false);
         if (eventName === 'input') {
             const modelName = modelDirective ? modelDirective.action : null;
             // track any inputs that are "unsynced"
@@ -300,7 +309,7 @@ export default class extends Controller implements LiveController {
             }
         }
 
-        const finalValue = getValueFromInput(element, this.valueStore);
+        const finalValue = getValueFromElement(element, this.valueStore);
 
         this.$updateModel(
             modelDirective.action,
@@ -368,6 +377,9 @@ export default class extends Controller implements LiveController {
         // the string "4" - back into an array with [id=4, title=new_title].
         this.valueStore.set(modelName, value);
 
+        // the model's data is no longer unsynced
+        this.unsyncedInputs.markModelAsSynced(modelName);
+
         // skip rendering if there is an action Ajax call processing
         if (shouldRender) {
             let debounce: number = this.getDefaultDebounce();
@@ -376,6 +388,9 @@ export default class extends Controller implements LiveController {
             }
 
             this.#clearRequestDebounceTimeout();
+            // debouncing even with a 0 value is enough to allow any other potential
+            // events happening right now (e.g. from custom user JavaScript) to
+            // finish setting other models before making the request.
             this.requestDebounceTimeout = window.setTimeout(() => {
                 this.requestDebounceTimeout = null;
                 this.isRerenderRequested = true;
@@ -405,15 +420,6 @@ export default class extends Controller implements LiveController {
         // we're making a request NOW, so no need to make another one after debouncing
         this.#clearRequestDebounceTimeout();
 
-        // check if any unsynced inputs are now "in sync": their value matches what's in the store
-        // if they ARE, then they are on longer "unsynced", which means that any
-        // potential new values from the server *should* now be respected and used
-        this.unsyncedInputs.allMappedFields().forEach((element, modelName) => {
-            if (getValueFromInput(element, this.valueStore) === this.valueStore.get(modelName)) {
-                this.unsyncedInputs.remove(modelName);
-            }
-        });
-
         const fetchOptions: RequestInit = {};
         fetchOptions.headers = {
             'Accept': 'application/vnd.live-component+html',
@@ -506,16 +512,14 @@ export default class extends Controller implements LiveController {
         }
 
         /**
-         * If this re-render contains "mapped" fields that were updated after
-         * the Ajax call started, then we need those "unsynced" values to
-         * take precedence over the (out-of-date) values returned by the server.
+         * For any models modified since the last request started, grab
+         * their value now: we will re-set them after the new data from
+         * the server has been processed.
          */
         const modifiedModelValues: any = {};
-        if (this.unsyncedInputs.allMappedFields().size > 0) {
-            for (const [modelName] of this.unsyncedInputs.allMappedFields()) {
-                modifiedModelValues[modelName] = this.valueStore.get(modelName);
-            }
-        }
+        this.valueStore.updatedModels.forEach((modelName) => {
+            modifiedModelValues[modelName] = this.valueStore.get(modelName);
+        });
 
         // merge/patch in the new HTML
         this._executeMorphdom(html, this.unsyncedInputs.all());
@@ -524,6 +528,8 @@ export default class extends Controller implements LiveController {
         Object.keys(modifiedModelValues).forEach((modelName) => {
             this.valueStore.set(modelName, modifiedModelValues[modelName]);
         });
+
+        this.synchronizeValueOfModelFields();
     }
 
     _onLoadingStart() {
@@ -694,9 +700,10 @@ export default class extends Controller implements LiveController {
                     return false;
                 }
 
-                // if this field has been modified since this HTML was requested, do not update it
+                // if this field's value has been modified since this HTML was
+                // requested, set the toEl's value to match the fromEl
                 if (modifiedElements.includes(fromEl)) {
-                    return false;
+                    setValueOnElement(toEl, getValueFromElement(fromEl, this.valueStore))
                 }
 
                 // https://github.com/patrick-steele-idem/morphdom#can-i-make-morphdom-blaze-through-the-dom-tree-even-faster-yes
@@ -1080,6 +1087,51 @@ export default class extends Controller implements LiveController {
             this.requestDebounceTimeout = null;
         }
     }
+
+    /**
+     * Sets the "value" of all model fields to the component data.
+     *
+     * This is called when the component initializes and after re-render.
+     * Take the following element:
+     *
+     *      <input data-model="firstName">
+     *
+     * This method will set the "value" of that element to the value of
+     * the "firstName" model.
+     */
+    private synchronizeValueOfModelFields(): void {
+        this.element.querySelectorAll('[data-model]').forEach((element) => {
+            if (!(element instanceof HTMLElement)) {
+                throw new Error('Invalid element using data-model.');
+            }
+
+            if (element instanceof HTMLFormElement) {
+                return;
+            }
+
+            const modelDirective = getModelDirectiveFromElement(element);
+            if (!modelDirective) {
+                return;
+            }
+
+            const modelName = modelDirective.action;
+
+            // skip any elements whose model name is currently in an unsynced state
+            if (this.unsyncedInputs.getModifiedModels().includes(modelName)) {
+                return;
+            }
+
+            if (this.valueStore.has(modelName)) {
+                setValueOnElement(element, this.valueStore.get(modelName))
+            }
+
+            // for select elements without a blank value, one might be selected automatically
+            // https://github.com/symfony/ux/issues/469
+            if (element instanceof HTMLSelectElement && !element.multiple) {
+                this.valueStore.set(modelName, getValueFromElement(element, this.valueStore));
+            }
+        })
+    }
 }
 
 class BackendRequest {

src/LiveComponent/assets/src/live_controller.ts

@@ -12,7 +12,7 @@ describe('UnsyncedInputContainer', () => {
         expect(container.all()).toEqual([element1, element2]);
     });
 
-    it('removes items added to it', () => {
+    it('markModelAsSynced removes items added to it', () => {
         const container = new UnsyncedInputContainer();
         const element1 = htmlToElement('<span>element1</span');
         const element2 = htmlToElement('<span>element2</span');
@@ -21,8 +21,21 @@ describe('UnsyncedInputContainer', () => {
         container.add(element2, 'some_model2');
         container.add(element3, 'some_model3');
 
-        container.remove('some_model2');
+        container.markModelAsSynced('some_model2');
 
         expect(container.all()).toEqual([element1, element3]);
     });
+
+    it('returns modified models via getModifiedModels()', () => {
+        const container = new UnsyncedInputContainer();
+        const element1 = htmlToElement('<span>element1</span');
+        const element2 = htmlToElement('<span>element2</span');
+        const element3 = htmlToElement('<span>element3</span');
+        container.add(element1);
+        container.add(element2, 'some_model2');
+        container.add(element3, 'some_model3');
+
+        container.markModelAsSynced('some_model2');
+        expect(container.getModifiedModels()).toEqual(['some_model3'])
+    });
 });