feature #472 [Waiting][Live] Doc'ing how to set values via Js, select sync bug & auto-setting data-model values (weaverryan)

This PR was merged into the 2.x branch.

Discussion
----------

[Waiting][Live] Doc'ing how to set values via Js, select sync bug & auto-setting data-model values

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| Tickets       | Fixes #469 Fixes #473
| License       | MIT

This does 3 unrelated things to close #469 and #473

**NOTE: BUILT ON TOP OF #466

A) [X] Documents how to change a "model" field via JavaScript
B) [X] Fixes a problem where a `select` element is rendered without an `empty` option, and so the component data isn't aware of the pre-selected option.
C) [X] Automatically set the `value` of a `data-model` field - #473.

Cheers!

Commits
-------

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

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'])
+    });
 });