lwc 2.23.6 → 2.24.0

package/dist/engine-dom/umd/es2017/engine-dom_debug.js

@@ -294,7 +294,7 @@
       CACHED_PROPERTY_ATTRIBUTE_MAPPING.set(propName, attributeName);
       return attributeName;
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -376,7 +376,7 @@
           patch$1(propName);
       }
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -504,6 +504,17 @@
       }
       return result;
   }
+  // Set a ref (lwc:ref) on a VM, from a template API
+  function setRefVNode(vm, ref, vnode) {
+      // 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.
@@ -1365,6 +1376,8 @@
           },
       };
   }
+  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.
@@ -1502,6 +1515,53 @@
           const vm = getAssociatedVM(this);
           return vm.shadowRoot;
       },
+      get refs() {
+          const vm = getAssociatedVM(this);
+          if (isUpdatingTemplate) {
+              // 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;
+          }
+          const { refVNodes, hasRefVNodes, cmpTemplate } = vm;
+          // 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.
@@ -2602,13 +2662,27 @@
       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;
@@ -2618,7 +2692,9 @@
           // 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`
+          ) {
               setProperty(elm, key, cur);
           }
       }
@@ -3580,17 +3656,20 @@
   // [h]tml node
   function h(sel, data, children = EmptyArray) {
       const vmBeingRendered = getVMBeingRendered();
-      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) {
@@ -3622,7 +3701,7 @@
   // [c]ustom element node
   function c(sel, Ctor, data, children = EmptyArray) {
       const vmBeingRendered = getVMBeingRendered();
-      const { key } = data;
+      const { key, ref } = data;
       let elm, aChildren, vm;
       const vnode = {
           type: 3 /* VNodeType.CustomElement */,
@@ -3638,6 +3717,9 @@
           vm,
       };
       addVNodeToChildLWC(vnode);
+      if (!isUndefined$1(ref)) {
+          setRefVNode(vmBeingRendered, ref, vnode);
+      }
       return vnode;
   }
   // [i]terable node
@@ -4010,6 +4092,10 @@
                           : createStylesheet(vm, stylesheetsContent);
               }
               if ("production" !== 'production') ;
+              // 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 = [];
@@ -4321,6 +4407,8 @@
       tagName,
       mode,
       owner,
+      refVNodes: null,
+      hasRefVNodes: false,
       children: EmptyArray,
       aChildren: EmptyArray,
       velements: EmptyArray,
@@ -5500,7 +5588,7 @@
       }
       return ctor;
   }
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   /*
    * Copyright (c) 2018, salesforce.com, inc.
@@ -5695,7 +5783,7 @@
       function isNull(obj) {
           return obj === null;
       }
-      /** version: 2.23.6 */
+      /** version: 2.24.0 */
 
       /*
        * Copyright (c) 2018, salesforce.com, inc.
@@ -6306,7 +6394,7 @@
   });
   freeze(LightningElement);
   seal(LightningElement.prototype);
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   exports.LightningElement = LightningElement;
   exports.__unstable__ProfilerControl = profilerControl;

package/dist/engine-dom/umd/es5/engine-dom.js

@@ -368,9 +368,9 @@
   // Increment whenever the LWC template compiler changes
 
 
-  var LWC_VERSION = "2.23.6";
+  var LWC_VERSION = "2.24.0";
   var LWC_VERSION_COMMENT_REGEX = /\/\*LWC compiler v([\d.]+)\*\/\s*}/;
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -464,7 +464,7 @@
       patch$1(propName);
     }
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /**
    * Copyright (C) 2018 salesforce.com, inc.
@@ -557,7 +557,7 @@
       setFeatureFlag(name, value);
     }
   }
-  /** version: 2.23.6 */
+  /** version: 2.24.0 */
 
   /*
    * Copyright (c) 2018, salesforce.com, inc.
@@ -735,6 +735,22 @@
     }
 
     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.
+
+
+    var 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.
@@ -2397,13 +2413,15 @@
       }
     };
   }
+
+  var EMPTY_REFS = freeze(create(null));
+  var refsCache = new WeakMap();
   /**
    * This class is the base class for any LWC element.
    * Some elements directly extends this class, others implement it via inheritance.
    **/
   // @ts-ignore
 
-
   var LightningElement = function LightningElement() {
     // This should be as performant as possible, while any initialization should be done lazily
     if (isNull(vmBeingConstructed)) {
@@ -2630,6 +2648,91 @@
       return vm.shadowRoot;
     },
 
+    get refs() {
+      var vm = getAssociatedVM(this);
+
+      if (isUpdatingTemplate) {
+        if (process.env.NODE_ENV !== 'production') {
+          logError("this.refs should not be called while ".concat(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');
+      }
+
+      var refVNodes = vm.refVNodes,
+          hasRefVNodes = vm.hasRefVNodes,
+          cmpTemplate = vm.cmpTemplate; // 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 ".concat(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`.
+
+
+      var refs = refsCache.get(refVNodes);
+
+      if (isUndefined$1(refs)) {
+        refs = create(null);
+
+        var _iterator3 = _createForOfIteratorHelper(keys(refVNodes)),
+            _step3;
+
+        try {
+          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+            var key = _step3.value;
+            refs[key] = refVNodes[key].elm;
+          }
+        } catch (err) {
+          _iterator3.e(err);
+        } finally {
+          _iterator3.f();
+        }
+
+        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: value
+      });
+    },
+
     get shadowRoot() {
       // From within the component instance, the shadowRoot is always reported as "closed".
       // Authors should rely on this.template instead.
@@ -4545,15 +4648,33 @@
 
   function patchProps(oldVnode, vnode, renderer) {
     var props = vnode.data.props;
+    var spread = vnode.data.spread;
 
-    if (isUndefined$1(props)) {
+    if (isUndefined$1(props) && isUndefined$1(spread)) {
       return;
     }
 
-    var oldProps = isNull(oldVnode) ? EmptyObject : oldVnode.data.props;
+    var oldProps;
 
-    if (oldProps === props) {
-      return;
+    if (!isNull(oldVnode)) {
+      oldProps = oldVnode.data.props;
+      var 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);
     }
 
     var isFirstPatch = isNull(oldVnode);
@@ -4566,7 +4687,8 @@
       var cur = props[key]; // 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])) {
+      if (isFirstPatch || 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.
@@ -5634,19 +5756,25 @@
       });
     }
 
-    var elm;
-    var key = data.key;
-    return {
+    var key = data.key,
+        ref = data.ref;
+    var vnode = {
       type: 2
       /* VNodeType.Element */
       ,
       sel: sel,
       data: data,
       children: children,
-      elm: elm,
+      elm: undefined,
       key: key,
       owner: vmBeingRendered
     };
+
+    if (!isUndefined$1(ref)) {
+      setRefVNode(vmBeingRendered, ref, vnode);
+    }
+
+    return vnode;
   } // [t]ab[i]ndex function
 
 
@@ -5727,7 +5855,8 @@
       }
     }
 
-    var key = data.key;
+    var key = data.key,
+        ref = data.ref;
     var elm, aChildren, vm;
     var vnode = {
       type: 3
@@ -5745,6 +5874,11 @@
       vm: vm
     };
     addVNodeToChildLWC(vnode);
+
+    if (!isUndefined$1(ref)) {
+      setRefVNode(vmBeingRendered, ref, vnode);
+    }
+
     return vnode;
   } // [i]terable node
 
@@ -6399,10 +6533,14 @@
           validateSlots(vm, html); // add the VM to the list of host VMs that can be re-rendered if html is swapped
 
           setActiveVM(vm);
-        } // right before producing the vnodes, we clear up all internal references
-        // to custom elements from the template.
+        } // reset the refs; they will be set during the tmpl() instantiation
 
 
+        var 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 = []; // Set the global flag that template is being updated
 
         isUpdatingTemplate = true;
@@ -6814,6 +6952,8 @@
       tagName: tagName,
       mode: mode,
       owner: owner,
+      refVNodes: null,
+      hasRefVNodes: false,
       children: EmptyArray,
       aChildren: EmptyArray,
       velements: EmptyArray,
@@ -8275,12 +8415,12 @@
   function warnOnArrayMutation(stylesheets) {
     // We can't handle users calling Array.prototype.slice.call(tmpl.stylesheets), but
     // we can at least warn when they use the most common mutation methods.
-    var _iterator3 = _createForOfIteratorHelper(ARRAY_MUTATION_METHODS),
-        _step3;
+    var _iterator4 = _createForOfIteratorHelper(ARRAY_MUTATION_METHODS),
+        _step4;
 
     try {
       var _loop2 = function _loop2() {
-        var prop = _step3.value;
+        var prop = _step4.value;
         var originalArrayMethod = getOriginalArrayMethod(prop);
 
         stylesheets[prop] = function arrayMutationWarningWrapper() {
@@ -8290,13 +8430,13 @@
         };
       };
 
-      for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
         _loop2();
       }
     } catch (err) {
-      _iterator3.e(err);
+      _iterator4.e(err);
     } finally {
-      _iterator3.f();
+      _iterator4.f();
     }
   } // TODO [#2782]: eventually freezeTemplate() will _actually_ freeze the tmpl object. Today it
   // just warns on mutation.
@@ -8308,12 +8448,12 @@
         warnOnArrayMutation(tmpl.stylesheets);
       }
 
-      var _iterator4 = _createForOfIteratorHelper(TEMPLATE_PROPS),
-          _step4;
+      var _iterator5 = _createForOfIteratorHelper(TEMPLATE_PROPS),
+          _step5;
 
       try {
         var _loop3 = function _loop3() {
-          var prop = _step4.value;
+          var prop = _step5.value;
           var value = tmpl[prop];
           defineProperty(tmpl, prop, {
             enumerable: true,
@@ -8331,13 +8471,13 @@
           });
         };
 
-        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+        for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
           _loop3();
         }
       } catch (err) {
-        _iterator4.e(err);
+        _iterator5.e(err);
       } finally {
-        _iterator4.f();
+        _iterator5.f();
       }
 
       var originalDescriptor = getOwnPropertyDescriptor$1(tmpl, 'stylesheetTokens');
@@ -8382,7 +8522,7 @@
 
     return ctor;
   }
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   /*
    * Copyright (c) 2018, salesforce.com, inc.
@@ -8610,7 +8750,7 @@
       function isNull(obj) {
         return obj === null;
       }
-      /** version: 2.23.6 */
+      /** version: 2.24.0 */
 
       /*
        * Copyright (c) 2018, salesforce.com, inc.
@@ -8759,18 +8899,18 @@
           var wrapperTags = topLevelWrappingMap[getTagName(html)];
 
           if (!isUndefined(wrapperTags)) {
-            var _iterator5 = _createForOfIteratorHelper(wrapperTags),
-                _step5;
+            var _iterator6 = _createForOfIteratorHelper(wrapperTags),
+                _step6;
 
             try {
-              for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
-                var wrapperTag = _step5.value;
+              for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
+                var wrapperTag = _step6.value;
                 html = "<".concat(wrapperTag, ">").concat(html, "</").concat(wrapperTag, ">");
               }
             } catch (err) {
-              _iterator5.e(err);
+              _iterator6.e(err);
             } finally {
-              _iterator5.f();
+              _iterator6.f();
             }
           } // For IE11, the document title must not be undefined, but it can be an empty string
           // https://developer.mozilla.org/en-US/docs/Web/API/DOMImplementation/createHTMLDocument#browser_compatibility
@@ -9340,7 +9480,7 @@
   });
   freeze(LightningElement);
   seal(LightningElement.prototype);
-  /* version: 2.23.6 */
+  /* version: 2.24.0 */
 
   exports.LightningElement = LightningElement;
   exports.__unstable__ProfilerControl = profilerControl;