@lwc/engine-core 2.23.6 → 2.25.0

package/dist/engine-core.cjs.js

@@ -111,6 +111,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' && shared.isUndefined(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.
@@ -1441,6 +1455,8 @@ function createBridgeToElementDescriptor(propName, descriptor) {
         },
     };
 }
+const EMPTY_REFS = shared.freeze(shared.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.
@@ -1620,6 +1636,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' &&
+            shared.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 (shared.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 (shared.isUndefined(refs)) {
+            refs = shared.create(null);
+            for (const key of shared.keys(refVNodes)) {
+                refs[key] = refVNodes[key].elm;
+            }
+            shared.freeze(refs);
+            refsCache.set(refVNodes, refs);
+        }
+        return refs;
+    },
+    // For backwards compat, we allow component authors to set `refs` as an expando
+    set refs(value) {
+        shared.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.
@@ -3051,6 +3131,14 @@ function getScopeTokenClass(owner) {
     const { cmpTemplate, context } = owner;
     return (context.hasScopedStyles && (cmpTemplate === null || cmpTemplate === void 0 ? void 0 : cmpTemplate.stylesheetToken)) || null;
 }
+/**
+ * This function returns the host style token for a custom element if it
+ * exists. Otherwise it returns null.
+ */
+function getStylesheetTokenHost(vnode) {
+    const { template: { stylesheetToken }, } = getComponentInternalDef(vnode.ctor);
+    return !shared.isUndefined(stylesheetToken) ? makeHostToken(stylesheetToken) : null;
+}
 function getNearestNativeShadowComponent(vm) {
     const owner = getNearestShadowComponent(vm);
     if (!shared.isNull(owner) && owner.shadowMode === 1 /* ShadowMode.Synthetic */) {
@@ -3168,6 +3256,9 @@ function isVBaseElement(vnode) {
 function isSameVnode(vnode1, vnode2) {
     return vnode1.key === vnode2.key && vnode1.sel === vnode2.sel;
 }
+function isVCustomElement(vnode) {
+    return vnode.type === 3 /* VNodeType.CustomElement */;
+}
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -3223,13 +3314,27 @@ function isLiveBindingProp(sel, key) {
     return sel === 'input' && (key === 'value' || key === 'checked');
 }
 function patchProps(oldVnode, vnode, renderer) {
-    const { props } = vnode.data;
-    if (shared.isUndefined(props)) {
+    let { props } = vnode.data;
+    const { spread } = vnode.data;
+    if (shared.isUndefined(props) && shared.isUndefined(spread)) {
         return;
     }
-    const oldProps = shared.isNull(oldVnode) ? EmptyObject : oldVnode.data.props;
-    if (oldProps === props) {
-        return;
+    let oldProps;
+    if (!shared.isNull(oldVnode)) {
+        oldProps = oldVnode.data.props;
+        const oldSpread = oldVnode.data.spread;
+        if (oldProps === props && oldSpread === spread) {
+            return;
+        }
+        if (shared.isUndefined(oldProps)) {
+            oldProps = EmptyObject;
+        }
+        if (!shared.isUndefined(oldSpread)) {
+            oldProps = shared.assign({}, oldProps, oldSpread);
+        }
+    }
+    if (!shared.isUndefined(spread)) {
+        props = shared.assign({}, props, spread);
     }
     const isFirstPatch = shared.isNull(oldVnode);
     const { elm, sel } = vnode;
@@ -3239,7 +3344,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.
@@ -4303,17 +4410,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 (!shared.isUndefined(ref)) {
+        setRefVNode(vmBeingRendered, ref, vnode);
+    }
+    return vnode;
 }
 // [t]ab[i]ndex function
 function ti(value) {
@@ -4378,7 +4488,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 */,
@@ -4394,6 +4504,9 @@ function c(sel, Ctor, data, children = EmptyArray) {
         vm,
     };
     addVNodeToChildLWC(vnode);
+    if (!shared.isUndefined(ref)) {
+        setRefVNode(vmBeingRendered, ref, vnode);
+    }
     return vnode;
 }
 // [i]terable node
@@ -4922,6 +5035,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 ? shared.create(null) : null;
             // right before producing the vnodes, we clear up all internal references
             // to custom elements from the template.
             vm.velements = [];
@@ -5280,6 +5397,8 @@ function createVM(elm, ctor, renderer, options) {
     tagName,
     mode,
     owner,
+    refVNodes: null,
+    hasRefVNodes: false,
     children: EmptyArray,
     aChildren: EmptyArray,
     velements: EmptyArray,
@@ -6433,6 +6552,7 @@ function validateClassAttr(vnode, elm, renderer) {
     let { className, classMap } = data;
     const { getProperty, getClassList } = renderer;
     const scopedToken = getScopeTokenClass(owner);
+    const stylesheetTokenHost = isVCustomElement(vnode) ? getStylesheetTokenHost(vnode) : null;
     // Classnames for scoped CSS are added directly to the DOM during rendering,
     // or to the VDOM on the server in the case of SSR. As such, these classnames
     // are never present in VDOM nodes in the browser.
@@ -6441,10 +6561,17 @@ function validateClassAttr(vnode, elm, renderer) {
     // are rendered during SSR. This needs to be accounted for when validating.
     if (scopedToken) {
         if (!shared.isUndefined(className)) {
-            className = `${scopedToken} ${className}`;
+            className = shared.isNull(stylesheetTokenHost)
+                ? `${scopedToken} ${className}`
+                : `${scopedToken} ${className} ${stylesheetTokenHost}`;
         }
         else if (!shared.isUndefined(classMap)) {
-            classMap = Object.assign(Object.assign({}, classMap), { [scopedToken]: true });
+            classMap = Object.assign(Object.assign(Object.assign({}, classMap), { [scopedToken]: true }), (shared.isNull(stylesheetTokenHost) ? {} : { [stylesheetTokenHost]: true }));
+        }
+        else {
+            className = shared.isNull(stylesheetTokenHost)
+                ? `${scopedToken}`
+                : `${scopedToken} ${stylesheetTokenHost}`;
         }
     }
     let nodesAreCompatible = true;
@@ -6725,4 +6852,4 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/* version: 2.23.6 */
+/* version: 2.25.0 */

package/dist/engine-core.js

@@ -1,7 +1,7 @@
 /* proxy-compat-disable */
 import { lwcRuntimeFlags } from '@lwc/features';
 export { setFeatureFlag, setFeatureFlagForTest } from '@lwc/features';
-import { seal, create, isFunction as isFunction$1, ArrayPush as ArrayPush$1, isUndefined as isUndefined$1, ArrayIndexOf, ArraySplice, StringToLowerCase, isNull, ArrayJoin, isFrozen, defineProperty, hasOwnProperty as hasOwnProperty$1, assign, forEach, keys, AriaPropNameToAttrNameMap, getPropertyDescriptor, defineProperties, getOwnPropertyNames as getOwnPropertyNames$1, getPrototypeOf as getPrototypeOf$1, setPrototypeOf, isObject, assert, KEY__SYNTHETIC_MODE, isFalse, isTrue, toString as toString$1, getOwnPropertyDescriptor as getOwnPropertyDescriptor$1, LWC_VERSION_COMMENT_REGEX, LWC_VERSION, freeze, htmlPropertyToAttribute, ArraySlice, ArrayMap, isArray as isArray$1, KEY__SCOPED_CSS, StringCharCodeAt, XML_NAMESPACE, XLINK_NAMESPACE, isString, StringSlice, SVG_NAMESPACE, KEY__SHADOW_STATIC, KEY__SHADOW_RESOLVER, isNumber, StringReplace, noop, ArrayUnshift, ArrayCopyWithin, ArrayFill, ArraySort, ArrayReverse, ArrayShift, ArrayPop } from '@lwc/shared';
+import { seal, create, isUndefined as isUndefined$1, isFunction as isFunction$1, ArrayPush as ArrayPush$1, ArrayIndexOf, ArraySplice, StringToLowerCase, isNull, ArrayJoin, isFrozen, defineProperty, hasOwnProperty as hasOwnProperty$1, assign, forEach, keys, AriaPropNameToAttrNameMap, getPropertyDescriptor, defineProperties, getOwnPropertyNames as getOwnPropertyNames$1, getPrototypeOf as getPrototypeOf$1, setPrototypeOf, isObject, freeze, assert, KEY__SYNTHETIC_MODE, isFalse, isTrue, toString as toString$1, getOwnPropertyDescriptor as getOwnPropertyDescriptor$1, LWC_VERSION_COMMENT_REGEX, LWC_VERSION, htmlPropertyToAttribute, ArraySlice, ArrayMap, isArray as isArray$1, KEY__SCOPED_CSS, StringCharCodeAt, XML_NAMESPACE, XLINK_NAMESPACE, isString, StringSlice, SVG_NAMESPACE, KEY__SHADOW_STATIC, KEY__SHADOW_RESOLVER, isNumber, StringReplace, noop, ArrayUnshift, ArrayCopyWithin, ArrayFill, ArraySort, ArrayReverse, ArrayShift, ArrayPop } from '@lwc/shared';
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -108,6 +108,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.
@@ -1438,6 +1452,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.
@@ -1617,6 +1633,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.
@@ -3048,6 +3128,14 @@ function getScopeTokenClass(owner) {
     const { cmpTemplate, context } = owner;
     return (context.hasScopedStyles && (cmpTemplate === null || cmpTemplate === void 0 ? void 0 : cmpTemplate.stylesheetToken)) || null;
 }
+/**
+ * This function returns the host style token for a custom element if it
+ * exists. Otherwise it returns null.
+ */
+function getStylesheetTokenHost(vnode) {
+    const { template: { stylesheetToken }, } = getComponentInternalDef(vnode.ctor);
+    return !isUndefined$1(stylesheetToken) ? makeHostToken(stylesheetToken) : null;
+}
 function getNearestNativeShadowComponent(vm) {
     const owner = getNearestShadowComponent(vm);
     if (!isNull(owner) && owner.shadowMode === 1 /* ShadowMode.Synthetic */) {
@@ -3165,6 +3253,9 @@ function isVBaseElement(vnode) {
 function isSameVnode(vnode1, vnode2) {
     return vnode1.key === vnode2.key && vnode1.sel === vnode2.sel;
 }
+function isVCustomElement(vnode) {
+    return vnode.type === 3 /* VNodeType.CustomElement */;
+}
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -3220,13 +3311,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;
@@ -3236,7 +3341,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.
@@ -4300,17 +4407,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) {
@@ -4375,7 +4485,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 */,
@@ -4391,6 +4501,9 @@ function c(sel, Ctor, data, children = EmptyArray) {
         vm,
     };
     addVNodeToChildLWC(vnode);
+    if (!isUndefined$1(ref)) {
+        setRefVNode(vmBeingRendered, ref, vnode);
+    }
     return vnode;
 }
 // [i]terable node
@@ -4919,6 +5032,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 = [];
@@ -5277,6 +5394,8 @@ function createVM(elm, ctor, renderer, options) {
     tagName,
     mode,
     owner,
+    refVNodes: null,
+    hasRefVNodes: false,
     children: EmptyArray,
     aChildren: EmptyArray,
     velements: EmptyArray,
@@ -6430,6 +6549,7 @@ function validateClassAttr(vnode, elm, renderer) {
     let { className, classMap } = data;
     const { getProperty, getClassList } = renderer;
     const scopedToken = getScopeTokenClass(owner);
+    const stylesheetTokenHost = isVCustomElement(vnode) ? getStylesheetTokenHost(vnode) : null;
     // Classnames for scoped CSS are added directly to the DOM during rendering,
     // or to the VDOM on the server in the case of SSR. As such, these classnames
     // are never present in VDOM nodes in the browser.
@@ -6438,10 +6558,17 @@ function validateClassAttr(vnode, elm, renderer) {
     // are rendered during SSR. This needs to be accounted for when validating.
     if (scopedToken) {
         if (!isUndefined$1(className)) {
-            className = `${scopedToken} ${className}`;
+            className = isNull(stylesheetTokenHost)
+                ? `${scopedToken} ${className}`
+                : `${scopedToken} ${className} ${stylesheetTokenHost}`;
         }
         else if (!isUndefined$1(classMap)) {
-            classMap = Object.assign(Object.assign({}, classMap), { [scopedToken]: true });
+            classMap = Object.assign(Object.assign(Object.assign({}, classMap), { [scopedToken]: true }), (isNull(stylesheetTokenHost) ? {} : { [stylesheetTokenHost]: true }));
+        }
+        else {
+            className = isNull(stylesheetTokenHost)
+                ? `${scopedToken}`
+                : `${scopedToken} ${stylesheetTokenHost}`;
         }
     }
     let nodesAreCompatible = true;
@@ -6685,4 +6812,4 @@ function getComponentConstructor(elm) {
 }
 
 export { LightningElement, profilerControl as __unstable__ProfilerControl, api$1 as api, connectRootElement, createContextProvider, createVM, disconnectRootElement, freezeTemplate, getAssociatedVMIfPresent, getComponentConstructor, getComponentDef, getComponentHtmlPrototype, getUpgradableConstructor, hydrateRoot, isComponentConstructor, parseFragment, parseSVGFragment, readonly, register, registerComponent, registerDecorators, registerTemplate, sanitizeAttribute, setHooks, swapComponent, swapStyle, swapTemplate, track, unwrap, wire };
-/* version: 2.23.6 */
+/* version: 2.25.0 */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lwc/engine-core",
-    "version": "2.23.6",
+    "version": "2.25.0",
     "description": "Core LWC engine APIs.",
     "homepage": "https://lwc.dev/",
     "repository": {
@@ -24,8 +24,8 @@
         "types/"
     ],
     "dependencies": {
-        "@lwc/features": "2.23.6",
-        "@lwc/shared": "2.23.6"
+        "@lwc/features": "2.25.0",
+        "@lwc/shared": "2.25.0"
     },
     "devDependencies": {
         "observable-membrane": "2.0.0"

package/types/framework/base-lightning-element.d.ts

@@ -19,8 +19,12 @@ export interface LightningElementConstructor {
     shadowSupportMode?: ShadowSupportMode;
 }
 declare type HTMLElementTheGoodParts = Pick<Object, 'toString'> & Pick<HTMLElement, 'accessKey' | 'addEventListener' | 'children' | 'childNodes' | 'classList' | 'dir' | 'dispatchEvent' | 'draggable' | 'firstChild' | 'firstElementChild' | 'getAttribute' | 'getAttributeNS' | 'getBoundingClientRect' | 'getElementsByClassName' | 'getElementsByTagName' | 'hasAttribute' | 'hasAttributeNS' | 'hidden' | 'id' | 'isConnected' | 'lang' | 'lastChild' | 'lastElementChild' | 'querySelector' | 'querySelectorAll' | 'removeAttribute' | 'removeAttributeNS' | 'removeEventListener' | 'setAttribute' | 'setAttributeNS' | 'spellcheck' | 'tabIndex' | 'title'>;
+declare type RefNodes = {
+    [name: string]: Element;
+};
 export interface LightningElement extends HTMLElementTheGoodParts, AccessibleElementProperties {
     template: ShadowRoot | null;
+    refs: RefNodes;
     render(): Template;
     connectedCallback?(): void;
     disconnectedCallback?(): void;

package/types/framework/stylesheet.d.ts

@@ -1,6 +1,6 @@
 import { VM } from './vm';
 import { Template } from './template';
-import { VNode } from './vnodes';
+import { VCustomElement, VNode } from './vnodes';
 /**
  * Function producing style based on a host and a shadow selector. This function is invoked by
  * the engine with different values depending on the mode that the component is running on.
@@ -20,4 +20,9 @@ export declare function getStylesheetsContent(vm: VM, template: Template): strin
  * it returns null.
  */
 export declare function getScopeTokenClass(owner: VM): string | null;
+/**
+ * This function returns the host style token for a custom element if it
+ * exists. Otherwise it returns null.
+ */
+export declare function getStylesheetTokenHost(vnode: VCustomElement): string | null;
 export declare function createStylesheet(vm: VM, stylesheets: string[]): VNode[] | null;

package/types/framework/template.d.ts

@@ -12,6 +12,8 @@ export interface Template {
     stylesheetToken?: string;
     /** Render mode for the template. Could be light or undefined (which means it's shadow) */
     renderMode?: 'light';
+    /** True if this template contains template refs, undefined or false otherwise */
+    hasRefs?: boolean;
 }
 export declare let isUpdatingTemplate: boolean;
 export declare function getVMBeingRendered(): VM | null;

package/types/framework/utils.d.ts

@@ -1,4 +1,6 @@
 import { StylesheetFactory, TemplateStylesheetFactories } from './stylesheet';
+import { VM } from './vm';
+import { VBaseElement } from './vnodes';
 declare type Callback = () => void;
 export declare const SPACE_CHAR = 32;
 export declare const EmptyObject: any;
@@ -14,4 +16,5 @@ export declare function cloneAndOmitKey(object: {
     [key: string]: any;
 };
 export declare function flattenStylesheets(stylesheets: TemplateStylesheetFactories): StylesheetFactory[];
+export declare function setRefVNode(vm: VM, ref: string, vnode: VBaseElement): void;
 export {};

package/types/framework/vm.d.ts

@@ -4,7 +4,7 @@ import { ComponentDef } from './def';
 import { LightningElement, LightningElementConstructor } from './base-lightning-element';
 import { ReactiveObserver } from './mutation-tracker';
 import { AccessorReactiveObserver } from './accessor-reactive-observer';
-import { VNodes, VCustomElement, VNode } from './vnodes';
+import { VNodes, VCustomElement, VNode, VBaseElement } from './vnodes';
 declare type ShadowRootMode = 'open' | 'closed';
 export interface TemplateCache {
     [key: string]: any;
@@ -51,6 +51,9 @@ export interface Context {
     /** List of wire hooks that are invoked when the component gets disconnected. */
     wiredDisconnecting: Array<() => void>;
 }
+export declare type RefVNodes = {
+    [name: string]: VBaseElement;
+};
 export interface VM<N = HostNode, E = HostElement> {
     /** The host element */
     readonly elm: HostElement;
@@ -62,6 +65,10 @@ export interface VM<N = HostNode, E = HostElement> {
     readonly context: Context;
     /** The owner VM or null for root elements. */
     readonly owner: VM<N, E> | null;
+    /** References to elements rendered using lwc:ref (template refs) */
+    refVNodes: RefVNodes | null;
+    /** Whether this template has any references to elements (template refs) */
+    hasRefVNodes: boolean;
     /** Whether or not the VM was hydrated */
     readonly hydrated: boolean;
     /** Rendering operations associated with the VM */

package/types/framework/vnodes.d.ts

@@ -72,9 +72,12 @@ export interface VNodeData {
     readonly on?: Readonly<Record<string, (event: Event) => any>>;
     readonly svg?: boolean;
     readonly renderer?: RendererAPI;
+    readonly spread?: Readonly<Record<string, any>>;
 }
 export interface VElementData extends VNodeData {
     readonly key: Key;
+    readonly ref?: string;
 }
 export declare function isVBaseElement(vnode: VNode): vnode is VElement | VCustomElement;
 export declare function isSameVnode(vnode1: VNode, vnode2: VNode): boolean;
+export declare function isVCustomElement(vnode: VBaseElement): vnode is VCustomElement;