lwc 2.23.6 → 2.24.0

package/dist/engine-dom/esm/es2017/engine-dom.js

@@ -299,9 +299,9 @@ function htmlPropertyToAttribute(propName) {
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 // Increment whenever the LWC template compiler changes
-const LWC_VERSION = "2.23.6";
+const LWC_VERSION = "2.24.0";
 const LWC_VERSION_COMMENT_REGEX = /\/\*LWC compiler v([\d.]+)\*\/\s*}/;
-/** version: 2.23.6 */
+/** version: 2.24.0 */
 
 /**
  * Copyright (C) 2018 salesforce.com, inc.
@@ -383,7 +383,7 @@ for (let i = 0, len = ElementPrototypeAriaPropertyNames.length; i < len; i += 1)
         patch$1(propName);
     }
 }
-/** version: 2.23.6 */
+/** version: 2.24.0 */
 
 /**
  * Copyright (C) 2018 salesforce.com, inc.
@@ -462,7 +462,7 @@ function setFeatureFlagForTest(name, value) {
         setFeatureFlag(name, value);
     }
 }
-/** version: 2.23.6 */
+/** version: 2.24.0 */
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -596,6 +596,20 @@ function flattenStylesheets(stylesheets) {
     }
     return list;
 }
+// Set a ref (lwc:ref) on a VM, from a template API
+function setRefVNode(vm, ref, vnode) {
+    if (process.env.NODE_ENV !== 'production' && isUndefined$1(vm.refVNodes)) {
+        throw new Error('refVNodes must be defined when setting a ref');
+    }
+    // If this method is called, then vm.refVNodes is set as the template has refs.
+    // If not, then something went wrong and we threw an error above.
+    const refVNodes = vm.refVNodes;
+    // In cases of conflict (two elements with the same ref), prefer, the last one,
+    // in depth-first traversal order.
+    if (!(ref in refVNodes) || refVNodes[ref].key < vnode.key) {
+        refVNodes[ref] = vnode;
+    }
+}
 
 /*
  * Copyright (c) 2019, salesforce.com, inc.
@@ -1912,6 +1926,8 @@ function createBridgeToElementDescriptor(propName, descriptor) {
         },
     };
 }
+const EMPTY_REFS = freeze(create(null));
+const refsCache = new WeakMap();
 /**
  * This class is the base class for any LWC element.
  * Some elements directly extends this class, others implement it via inheritance.
@@ -2091,6 +2107,70 @@ LightningElement.prototype = {
         }
         return vm.shadowRoot;
     },
+    get refs() {
+        const vm = getAssociatedVM(this);
+        if (isUpdatingTemplate) {
+            if (process.env.NODE_ENV !== 'production') {
+                logError(`this.refs should not be called while ${getComponentTag(vm)} is rendering. Use this.refs only when the DOM is stable, e.g. in renderedCallback().`);
+            }
+            // If the template is in the process of being updated, then we don't want to go through the normal
+            // process of returning the refs and caching them, because the state of the refs is unstable.
+            // This can happen if e.g. a template contains `<div class={foo}></div>` and `foo` is computed
+            // based on `this.refs.bar`.
+            return;
+        }
+        if (process.env.NODE_ENV !== 'production') {
+            warnIfInvokedDuringConstruction(vm, 'refs');
+        }
+        const { refVNodes, hasRefVNodes, cmpTemplate } = vm;
+        // If the `cmpTemplate` is null, that means that the template has not been rendered yet. Most likely this occurs
+        // if `this.refs` is called during the `connectedCallback` phase. The DOM elements have not been rendered yet,
+        // so log a warning. Note we also check `isBeingConstructed()` to avoid a double warning (due to
+        // `warnIfInvokedDuringConstruction` above).
+        if (process.env.NODE_ENV !== 'production' &&
+            isNull(cmpTemplate) &&
+            !isBeingConstructed(vm)) {
+            logError(`this.refs is undefined for ${getComponentTag(vm)}. This is either because the attached template has no "lwc:ref" directive, or this.refs was ` +
+                `invoked before renderedCallback(). Use this.refs only when the referenced HTML elements have ` +
+                `been rendered to the DOM, such as within renderedCallback() or disconnectedCallback().`);
+        }
+        // For backwards compatibility with component written before template refs
+        // were introduced, we return undefined if the template has no refs defined
+        // anywhere. This fixes components that may want to add an expando called `refs`
+        // and are checking if it exists with `if (this.refs)`  before adding it.
+        // Note it is not sufficient to just check if `refVNodes` is null or empty,
+        // because a template may have `lwc:ref` defined within a falsy `if:true` block.
+        if (!hasRefVNodes) {
+            return;
+        }
+        // For templates that are using `lwc:ref`, if there are no refs currently available
+        // (e.g. refs inside of a falsy `if:true` block), we return an empty object.
+        if (isNull(refVNodes)) {
+            return EMPTY_REFS;
+        }
+        // The refNodes can be cached based on the refVNodes, since the refVNodes
+        // are recreated from scratch every time the template is rendered.
+        // This happens with `vm.refVNodes = null` in `template.ts` in `@lwc/engine-core`.
+        let refs = refsCache.get(refVNodes);
+        if (isUndefined$1(refs)) {
+            refs = create(null);
+            for (const key of keys(refVNodes)) {
+                refs[key] = refVNodes[key].elm;
+            }
+            freeze(refs);
+            refsCache.set(refVNodes, refs);
+        }
+        return refs;
+    },
+    // For backwards compat, we allow component authors to set `refs` as an expando
+    set refs(value) {
+        defineProperty(this, 'refs', {
+            configurable: true,
+            enumerable: true,
+            writable: true,
+            value,
+        });
+    },
     get shadowRoot() {
         // From within the component instance, the shadowRoot is always reported as "closed".
         // Authors should rely on this.template instead.
@@ -3679,13 +3759,27 @@ function isLiveBindingProp(sel, key) {
     return sel === 'input' && (key === 'value' || key === 'checked');
 }
 function patchProps(oldVnode, vnode, renderer) {
-    const { props } = vnode.data;
-    if (isUndefined$1(props)) {
+    let { props } = vnode.data;
+    const { spread } = vnode.data;
+    if (isUndefined$1(props) && isUndefined$1(spread)) {
         return;
     }
-    const oldProps = isNull(oldVnode) ? EmptyObject : oldVnode.data.props;
-    if (oldProps === props) {
-        return;
+    let oldProps;
+    if (!isNull(oldVnode)) {
+        oldProps = oldVnode.data.props;
+        const oldSpread = oldVnode.data.spread;
+        if (oldProps === props && oldSpread === spread) {
+            return;
+        }
+        if (isUndefined$1(oldProps)) {
+            oldProps = EmptyObject;
+        }
+        if (!isUndefined$1(oldSpread)) {
+            oldProps = assign({}, oldProps, oldSpread);
+        }
+    }
+    if (!isUndefined$1(spread)) {
+        props = assign({}, props, spread);
     }
     const isFirstPatch = isNull(oldVnode);
     const { elm, sel } = vnode;
@@ -3695,7 +3789,9 @@ function patchProps(oldVnode, vnode, renderer) {
         // Set the property if it's the first time is is patched or if the previous property is
         // different than the one previously set.
         if (isFirstPatch ||
-            cur !== (isLiveBindingProp(sel, key) ? getProperty(elm, key) : oldProps[key])) {
+            cur !== (isLiveBindingProp(sel, key) ? getProperty(elm, key) : oldProps[key]) ||
+            !(key in oldProps) // this is required because the above case will pass when `cur` is `undefined` and key is missing in `oldProps`
+        ) {
             // Additional verification if properties are supported by the element
             // Validation relies on html properties and public properties being defined on the element,
             // SSR has its own custom validation.
@@ -4755,17 +4851,20 @@ function h(sel, data, children = EmptyArray) {
             }
         });
     }
-    let elm;
-    const { key } = data;
-    return {
+    const { key, ref } = data;
+    const vnode = {
         type: 2 /* VNodeType.Element */,
         sel,
         data,
         children,
-        elm,
+        elm: undefined,
         key,
         owner: vmBeingRendered,
     };
+    if (!isUndefined$1(ref)) {
+        setRefVNode(vmBeingRendered, ref, vnode);
+    }
+    return vnode;
 }
 // [t]ab[i]ndex function
 function ti(value) {
@@ -4830,7 +4929,7 @@ function c(sel, Ctor, data, children = EmptyArray) {
             });
         }
     }
-    const { key } = data;
+    const { key, ref } = data;
     let elm, aChildren, vm;
     const vnode = {
         type: 3 /* VNodeType.CustomElement */,
@@ -4846,6 +4945,9 @@ function c(sel, Ctor, data, children = EmptyArray) {
         vm,
     };
     addVNodeToChildLWC(vnode);
+    if (!isUndefined$1(ref)) {
+        setRefVNode(vmBeingRendered, ref, vnode);
+    }
     return vnode;
 }
 // [i]terable node
@@ -5374,6 +5476,10 @@ function evaluateTemplate(vm, html) {
                 // add the VM to the list of host VMs that can be re-rendered if html is swapped
                 setActiveVM(vm);
             }
+            // reset the refs; they will be set during the tmpl() instantiation
+            const hasRefVNodes = Boolean(html.hasRefs);
+            vm.hasRefVNodes = hasRefVNodes;
+            vm.refVNodes = hasRefVNodes ? create(null) : null;
             // right before producing the vnodes, we clear up all internal references
             // to custom elements from the template.
             vm.velements = [];
@@ -5732,6 +5838,8 @@ function createVM(elm, ctor, renderer, options) {
     tagName,
     mode,
     owner,
+    refVNodes: null,
+    hasRefVNodes: false,
     children: EmptyArray,
     aChildren: EmptyArray,
     velements: EmptyArray,
@@ -7134,7 +7242,7 @@ function getComponentConstructor(elm) {
     }
     return ctor;
 }
-/* version: 2.23.6 */
+/* version: 2.24.0 */
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -7338,7 +7446,7 @@ function rendererFactory(baseRenderer) {
     function isNull(obj) {
         return obj === null;
     }
-    /** version: 2.23.6 */
+    /** version: 2.24.0 */
 
     /*
      * Copyright (c) 2018, salesforce.com, inc.
@@ -7957,6 +8065,6 @@ defineProperty(LightningElement, 'CustomElementConstructor', {
 });
 freeze(LightningElement);
 seal(LightningElement.prototype);
-/* version: 2.23.6 */
+/* version: 2.24.0 */
 
 export { LightningElement, profilerControl as __unstable__ProfilerControl, api$1 as api, deprecatedBuildCustomElementConstructor as buildCustomElementConstructor, createContextProvider, createElement, freezeTemplate, getComponentConstructor, getComponentDef, hydrateComponent, isComponentConstructor, isNodeShadowed as isNodeFromTemplate, parseFragment, parseSVGFragment, readonly, register, registerComponent, registerDecorators, registerTemplate, renderer, rendererFactory, sanitizeAttribute, setFeatureFlag, setFeatureFlagForTest, setHooks, swapComponent, swapStyle, swapTemplate, track, unwrap, wire };

package/dist/engine-dom/iife/es2017/engine-dom.js

@@ -302,9 +302,9 @@ var LWC = (function (exports) {
    * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
    */
   // Increment whenever the LWC template compiler changes
-  const LWC_VERSION = "2.23.6";
+  const LWC_VERSION = "2.24.0";
   const LWC_VERSION_COMMENT_REGEX = /\/\*LWC compiler v([\d.]+)\*\/\s*}/;
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -386,7 +386,7 @@ var LWC = (function (exports) {
           patch$1(propName);
       }
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -465,7 +465,7 @@ var LWC = (function (exports) {
           setFeatureFlag(name, value);
       }
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /*
    * Copyright (c) 2018, salesforce.com, inc.
@@ -599,6 +599,20 @@ var LWC = (function (exports) {
       }
       return list;
   }
+  // Set a ref (lwc:ref) on a VM, from a template API
+  function setRefVNode(vm, ref, vnode) {
+      if (process.env.NODE_ENV !== 'production' && isUndefined$1(vm.refVNodes)) {
+          throw new Error('refVNodes must be defined when setting a ref');
+      }
+      // If this method is called, then vm.refVNodes is set as the template has refs.
+      // If not, then something went wrong and we threw an error above.
+      const refVNodes = vm.refVNodes;
+      // In cases of conflict (two elements with the same ref), prefer, the last one,
+      // in depth-first traversal order.
+      if (!(ref in refVNodes) || refVNodes[ref].key < vnode.key) {
+          refVNodes[ref] = vnode;
+      }
+  }
 
   /*
    * Copyright (c) 2019, salesforce.com, inc.
@@ -1915,6 +1929,8 @@ var LWC = (function (exports) {
           },
       };
   }
+  const EMPTY_REFS = freeze(create(null));
+  const refsCache = new WeakMap();
   /**
    * This class is the base class for any LWC element.
    * Some elements directly extends this class, others implement it via inheritance.
@@ -2094,6 +2110,70 @@ var LWC = (function (exports) {
           }
           return vm.shadowRoot;
       },
+      get refs() {
+          const vm = getAssociatedVM(this);
+          if (isUpdatingTemplate) {
+              if (process.env.NODE_ENV !== 'production') {
+                  logError(`this.refs should not be called while ${getComponentTag(vm)} is rendering. Use this.refs only when the DOM is stable, e.g. in renderedCallback().`);
+              }
+              // If the template is in the process of being updated, then we don't want to go through the normal
+              // process of returning the refs and caching them, because the state of the refs is unstable.
+              // This can happen if e.g. a template contains `<div class={foo}></div>` and `foo` is computed
+              // based on `this.refs.bar`.
+              return;
+          }
+          if (process.env.NODE_ENV !== 'production') {
+              warnIfInvokedDuringConstruction(vm, 'refs');
+          }
+          const { refVNodes, hasRefVNodes, cmpTemplate } = vm;
+          // If the `cmpTemplate` is null, that means that the template has not been rendered yet. Most likely this occurs
+          // if `this.refs` is called during the `connectedCallback` phase. The DOM elements have not been rendered yet,
+          // so log a warning. Note we also check `isBeingConstructed()` to avoid a double warning (due to
+          // `warnIfInvokedDuringConstruction` above).
+          if (process.env.NODE_ENV !== 'production' &&
+              isNull(cmpTemplate) &&
+              !isBeingConstructed(vm)) {
+              logError(`this.refs is undefined for ${getComponentTag(vm)}. This is either because the attached template has no "lwc:ref" directive, or this.refs was ` +
+                  `invoked before renderedCallback(). Use this.refs only when the referenced HTML elements have ` +
+                  `been rendered to the DOM, such as within renderedCallback() or disconnectedCallback().`);
+          }
+          // For backwards compatibility with component written before template refs
+          // were introduced, we return undefined if the template has no refs defined
+          // anywhere. This fixes components that may want to add an expando called `refs`
+          // and are checking if it exists with `if (this.refs)`  before adding it.
+          // Note it is not sufficient to just check if `refVNodes` is null or empty,
+          // because a template may have `lwc:ref` defined within a falsy `if:true` block.
+          if (!hasRefVNodes) {
+              return;
+          }
+          // For templates that are using `lwc:ref`, if there are no refs currently available
+          // (e.g. refs inside of a falsy `if:true` block), we return an empty object.
+          if (isNull(refVNodes)) {
+              return EMPTY_REFS;
+          }
+          // The refNodes can be cached based on the refVNodes, since the refVNodes
+          // are recreated from scratch every time the template is rendered.
+          // This happens with `vm.refVNodes = null` in `template.ts` in `@lwc/engine-core`.
+          let refs = refsCache.get(refVNodes);
+          if (isUndefined$1(refs)) {
+              refs = create(null);
+              for (const key of keys(refVNodes)) {
+                  refs[key] = refVNodes[key].elm;
+              }
+              freeze(refs);
+              refsCache.set(refVNodes, refs);
+          }
+          return refs;
+      },
+      // For backwards compat, we allow component authors to set `refs` as an expando
+      set refs(value) {
+          defineProperty(this, 'refs', {
+              configurable: true,
+              enumerable: true,
+              writable: true,
+              value,
+          });
+      },
       get shadowRoot() {
           // From within the component instance, the shadowRoot is always reported as "closed".
           // Authors should rely on this.template instead.
@@ -3682,13 +3762,27 @@ var LWC = (function (exports) {
       return sel === 'input' && (key === 'value' || key === 'checked');
   }
   function patchProps(oldVnode, vnode, renderer) {
-      const { props } = vnode.data;
-      if (isUndefined$1(props)) {
+      let { props } = vnode.data;
+      const { spread } = vnode.data;
+      if (isUndefined$1(props) && isUndefined$1(spread)) {
           return;
       }
-      const oldProps = isNull(oldVnode) ? EmptyObject : oldVnode.data.props;
-      if (oldProps === props) {
-          return;
+      let oldProps;
+      if (!isNull(oldVnode)) {
+          oldProps = oldVnode.data.props;
+          const oldSpread = oldVnode.data.spread;
+          if (oldProps === props && oldSpread === spread) {
+              return;
+          }
+          if (isUndefined$1(oldProps)) {
+              oldProps = EmptyObject;
+          }
+          if (!isUndefined$1(oldSpread)) {
+              oldProps = assign({}, oldProps, oldSpread);
+          }
+      }
+      if (!isUndefined$1(spread)) {
+          props = assign({}, props, spread);
       }
       const isFirstPatch = isNull(oldVnode);
       const { elm, sel } = vnode;
@@ -3698,7 +3792,9 @@ var LWC = (function (exports) {
           // Set the property if it's the first time is is patched or if the previous property is
           // different than the one previously set.
           if (isFirstPatch ||
-              cur !== (isLiveBindingProp(sel, key) ? getProperty(elm, key) : oldProps[key])) {
+              cur !== (isLiveBindingProp(sel, key) ? getProperty(elm, key) : oldProps[key]) ||
+              !(key in oldProps) // this is required because the above case will pass when `cur` is `undefined` and key is missing in `oldProps`
+          ) {
               // Additional verification if properties are supported by the element
               // Validation relies on html properties and public properties being defined on the element,
               // SSR has its own custom validation.
@@ -4758,17 +4854,20 @@ var LWC = (function (exports) {
               }
           });
       }
-      let elm;
-      const { key } = data;
-      return {
+      const { key, ref } = data;
+      const vnode = {
           type: 2 /* VNodeType.Element */,
           sel,
           data,
           children,
-          elm,
+          elm: undefined,
           key,
           owner: vmBeingRendered,
       };
+      if (!isUndefined$1(ref)) {
+          setRefVNode(vmBeingRendered, ref, vnode);
+      }
+      return vnode;
   }
   // [t]ab[i]ndex function
   function ti(value) {
@@ -4833,7 +4932,7 @@ var LWC = (function (exports) {
               });
           }
       }
-      const { key } = data;
+      const { key, ref } = data;
       let elm, aChildren, vm;
       const vnode = {
           type: 3 /* VNodeType.CustomElement */,
@@ -4849,6 +4948,9 @@ var LWC = (function (exports) {
           vm,
       };
       addVNodeToChildLWC(vnode);
+      if (!isUndefined$1(ref)) {
+          setRefVNode(vmBeingRendered, ref, vnode);
+      }
       return vnode;
   }
   // [i]terable node
@@ -5377,6 +5479,10 @@ var LWC = (function (exports) {
                   // add the VM to the list of host VMs that can be re-rendered if html is swapped
                   setActiveVM(vm);
               }
+              // reset the refs; they will be set during the tmpl() instantiation
+              const hasRefVNodes = Boolean(html.hasRefs);
+              vm.hasRefVNodes = hasRefVNodes;
+              vm.refVNodes = hasRefVNodes ? create(null) : null;
               // right before producing the vnodes, we clear up all internal references
               // to custom elements from the template.
               vm.velements = [];
@@ -5735,6 +5841,8 @@ var LWC = (function (exports) {
       tagName,
       mode,
       owner,
+      refVNodes: null,
+      hasRefVNodes: false,
       children: EmptyArray,
       aChildren: EmptyArray,
       velements: EmptyArray,
@@ -7137,7 +7245,7 @@ var LWC = (function (exports) {
       }
       return ctor;
   }
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   /*
    * Copyright (c) 2018, salesforce.com, inc.
@@ -7341,7 +7449,7 @@ var LWC = (function (exports) {
       function isNull(obj) {
           return obj === null;
       }
-      /** version: 2.23.6 */
+      /** version: 2.24.0 */
 
       /*
        * Copyright (c) 2018, salesforce.com, inc.
@@ -7960,7 +8068,7 @@ var LWC = (function (exports) {
   });
   freeze(LightningElement);
   seal(LightningElement.prototype);
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   exports.LightningElement = LightningElement;
   exports.__unstable__ProfilerControl = profilerControl;