@lwc/engine-core 6.2.0 → 6.3.0

package/dist/index.cjs.js

@@ -27,8 +27,7 @@ let enabled$1 = false;
 const reportingControl = {
     /**
      * Attach a new reporting control (aka dispatcher).
-     *
-     * @param dispatcher - reporting control
+     * @param dispatcher reporting control
      */
     attachDispatcher(dispatcher) {
         enabled$1 = true;
@@ -71,7 +70,7 @@ function onReportingEnabled(callback) {
 /**
  * Report to the current dispatcher, if there is one.
  * @param reportingEventId
- * @param payload - data to report
+ * @param payload data to report
  */
 function report(reportingEventId, payload) {
     if (enabled$1) {
@@ -133,7 +132,7 @@ function addErrorComponentStack(vm, error) {
 }
 
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -141,7 +140,6 @@ function addErrorComponentStack(vm, error) {
 const alreadyLoggedMessages = new Set();
 // Only used in LWC's Karma tests
 if (process.env.NODE_ENV === 'test-karma-lwc') {
-    // @ts-ignore
     window.__lwcResetAlreadyLoggedMessages = () => {
         alreadyLoggedMessages.clear();
     };
@@ -799,7 +797,7 @@ function getShadowRootRestrictionsDescriptors(sr) {
                     logError('The `addEventListener` method on ShadowRoot does not support any options.', getAssociatedVMIfPresent(this));
                 }
                 // Typescript does not like it when you treat the `arguments` object as an array
-                // @ts-ignore type-mismatch
+                // @ts-expect-error type-mismatch
                 return originalAddEventListener.apply(this, arguments);
             },
         }),
@@ -848,7 +846,7 @@ function getCustomElementRestrictionsDescriptors(elm) {
                     logError('The `addEventListener` method in `LightningElement` does not support any options.', getAssociatedVMIfPresent(this));
                 }
                 // Typescript does not like it when you treat the `arguments` object as an array
-                // @ts-ignore type-mismatch
+                // @ts-expect-error type-mismatch
                 return originalAddEventListener.apply(this, arguments);
             },
         }),
@@ -1434,6 +1432,7 @@ const reactiveMembrane = new ObservableMembrane({
  * EXPERIMENTAL: This function implements an unwrap mechanism that
  * works for observable membrane objects. This API is subject to
  * change or being removed.
+ * @param value
  */
 function unwrap(value) {
     // On the server side, we don't need mutation tracking. Skipping it improves performance.
@@ -1547,6 +1546,8 @@ function applyShadowMigrateMode(shadowRoot) {
  * that a Custom Element can support (including AOM properties), which
  * determines what kind of capabilities the Base Lightning Element should support. When producing the new descriptors
  * for the Base Lightning Element, it also include the reactivity bit, so the standard property is reactive.
+ * @param propName
+ * @param descriptor
  */
 function createBridgeToElementDescriptor(propName, descriptor) {
     const { get, set, enumerable, configurable } = descriptor;
@@ -1596,8 +1597,8 @@ 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.
- **/
-// @ts-ignore
+ */
+// @ts-expect-error When exported, it will conform, but we need to build it first!
 const LightningElement = function () {
     // This should be as performant as possible, while any initialization should be done lazily
     if (shared.isNull(vmBeingConstructed)) {
@@ -1739,7 +1740,7 @@ function createElementInternalsProxy(elementInternals, isFormAssociated) {
     });
     return elementInternalsProxy;
 }
-// @ts-ignore
+// Type assertion because we need to build the prototype before it satisfies the interface.
 LightningElement.prototype = {
     constructor: LightningElement,
     dispatchEvent(event) {
@@ -1941,6 +1942,9 @@ LightningElement.prototype = {
         if (process.env.NODE_ENV !== 'production') {
             warnIfInvokedDuringConstruction(vm, 'childNodes');
         }
+        // getChildNodes returns a NodeList, which has `item(index: number): Node | null`.
+        // NodeListOf<T> extends NodeList, but claims to not return null. That seems inaccurate,
+        // but these are built-in types, so ultimately not our problem.
         return renderer.getChildNodes(vm.elm);
     },
     get firstChild() {
@@ -2180,7 +2184,7 @@ function createConfigWatcher(component, configCallback, callbackWhenConfigIsRead
         ro.observe(() => (config = configCallback(component)));
         // eslint-disable-next-line @lwc/lwc-internal/no-invalid-todo
         // TODO: dev-mode validation of config based on the adapter.configSchema
-        // @ts-ignore it is assigned in the observe() callback
+        // @ts-expect-error it is assigned in the observe() callback
         callbackWhenConfigIsReady(config);
     };
     return {
@@ -2256,7 +2260,7 @@ function createConnector(vm, name, wireDef) {
         });
     }
     return {
-        // @ts-ignore the boundary protection executes sync, connector is always defined
+        // @ts-expect-error the boundary protection executes sync, connector is always defined
         connector,
         computeConfigAndUpdate,
         resetConfigWatcher: () => ro.reset(),
@@ -2465,9 +2469,11 @@ function internalTrackDecorator(key) {
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 /**
- * @wire decorator to wire fields and methods to a wire adapter in
+ * The @wire decorator wires fields and methods to a wire adapter in
  * LWC Components. This function implements the internals of this
  * decorator.
+ * @param _adapter
+ * @param _config
  */
 function wire(_adapter, _config) {
     if (process.env.NODE_ENV !== 'production') {
@@ -2578,6 +2584,8 @@ function validateMethodDecoratedWithApi(Ctor, methodName, descriptor) {
 /**
  * INTERNAL: This function can only be invoked by compiled code. The compiler
  * will prevent this function from being imported by user-land code.
+ * @param Ctor
+ * @param meta
  */
 function registerDecorators(Ctor, meta) {
     const proto = Ctor.prototype;
@@ -2731,7 +2739,6 @@ function getDecoratorsMeta(Ctor) {
 let warned = false;
 // Only used in LWC's Karma tests
 if (process.env.NODE_ENV === 'test-karma-lwc') {
-    // @ts-ignore
     window.__lwcResetWarnedOnVersionMismatch = () => {
         warned = false;
     };
@@ -2766,6 +2773,7 @@ function isTemplateRegistered(tpl) {
 /**
  * INTERNAL: This function can only be invoked by compiled code. The compiler
  * will prevent this function from being imported by userland code.
+ * @param tpl
  */
 function registerTemplate(tpl) {
     if (process.env.NODE_ENV !== 'production') {
@@ -2779,6 +2787,10 @@ function registerTemplate(tpl) {
 /**
  * EXPERIMENTAL: This function acts like a hook for Lightning Locker Service and other similar
  * libraries to sanitize vulnerable attributes.
+ * @param tagName
+ * @param namespaceUri
+ * @param attrName
+ * @param attrValue
  */
 function sanitizeAttribute(tagName, namespaceUri, attrName, attrValue) {
     // locker-service patches this function during runtime to sanitize vulnerable attributes. When
@@ -2844,7 +2856,7 @@ function createAttributeChangedCallback(attributeToPropMap, superAttributeChange
             if (!shared.isUndefined(superAttributeChangedCallback)) {
                 // delegate unknown attributes to the super.
                 // Typescript does not like it when you treat the `arguments` object as an array
-                // @ts-ignore type-mismatch
+                // @ts-expect-error type-mismatch
                 superAttributeChangedCallback.apply(this, arguments);
             }
             return;
@@ -3364,6 +3376,7 @@ function createComponentDef(Ctor) {
 /**
  * EXPERIMENTAL: This function allows for the identification of LWC constructors. This API is
  * subject to change or being removed.
+ * @param ctor
  */
 function isComponentConstructor(ctor) {
     if (!shared.isFunction(ctor)) {
@@ -3437,6 +3450,7 @@ const lightingElementDef = {
 /**
  * EXPERIMENTAL: This function allows for the collection of internal component metadata. This API is
  * subject to change or being removed.
+ * @param Ctor
  */
 function getComponentDef(Ctor) {
     const def = getComponentInternalDef(Ctor);
@@ -3633,6 +3647,8 @@ function getNearestShadowComponent(vm) {
  * If the component that is currently being rendered uses scoped styles,
  * this returns the unique token for that scoped stylesheet. Otherwise
  * it returns null.
+ * @param owner
+ * @param legacy
  */
 // TODO [#3733]: remove support for legacy scope tokens
 function getScopeTokenClass(owner, legacy) {
@@ -3646,6 +3662,7 @@ function getScopeTokenClass(owner, legacy) {
  * exists. Otherwise it returns null.
  *
  * A host style token is applied to the component if scoped styles are used.
+ * @param vnode
  */
 function getStylesheetTokenHost(vnode) {
     const { template } = getComponentInternalDef(vnode.ctor);
@@ -4054,11 +4071,9 @@ function traverseAndSetElements(root, parts, renderer) {
 }
 /**
  * Given an array of static parts, do all the mounting required for these parts.
- *
- * @param root - the root element
- * @param vnode - the parent VStatic
- * @param renderer - the renderer to use
- * @param mount - true this is a first (mount) render as opposed to a subsequent (patch) render
+ * @param root the root element
+ * @param vnode the parent VStatic
+ * @param renderer the renderer to use
  */
 function mountStaticParts(root, vnode, renderer) {
     // On the server, we don't support ref (because it relies on renderedCallback), nor do we
@@ -4083,9 +4098,8 @@ function mountStaticParts(root, vnode, renderer) {
 }
 /**
  * Mounts elements to the newly generated VStatic node
- *
- * @param n1 - the previous VStatic vnode
- * @param n2 - the current VStatic vnode
+ * @param n1 the previous VStatic vnode
+ * @param n2 the current VStatic vnode
  */
 function patchStaticParts(n1, n2) {
     // On the server, we don't support ref (because it relies on renderedCallback), nor do we
@@ -4600,6 +4614,7 @@ function allocateChildren(vnode, vm) {
  * With the delimiters removed, the contents are marked dynamic so they are diffed correctly.
  *
  * This function is used for slotted VFragments to avoid the text delimiters interfering with slotting functionality.
+ * @param children
  */
 function flattenFragmentsInChildren(children) {
     const flattenedChildren = [];
@@ -5213,6 +5228,7 @@ function i(iterable, factory) {
 }
 /**
  * [f]lattening
+ * @param items
  */
 function f(items) {
     if (process.env.NODE_ENV !== 'production') {
@@ -5329,6 +5345,10 @@ function fid(url) {
  * [ddc] - create a (deprecated) dynamic component via `<x-foo lwc:dynamic={Ctor}>`
  *
  * TODO [#3331]: remove usage of lwc:dynamic in 246
+ * @param sel
+ * @param Ctor
+ * @param data
+ * @param children
  */
 function ddc(sel, Ctor, data, children = EmptyArray) {
     if (process.env.NODE_ENV !== 'production') {
@@ -5347,6 +5367,9 @@ function ddc(sel, Ctor, data, children = EmptyArray) {
 }
 /**
  * [dc] - create a dynamic component via `<lwc:component lwc:is={Ctor}>`
+ * @param Ctor
+ * @param data
+ * @param children
  */
 function dc(Ctor, data, children = EmptyArray) {
     if (process.env.NODE_ENV !== 'production') {
@@ -5374,13 +5397,13 @@ function dc(Ctor, data, children = EmptyArray) {
  * to the engine that a particular collection of children must be diffed using the slow
  * algo based on keys due to the nature of the list. E.g.:
  *
- *   - slot element's children: the content of the slot has to be dynamic when in synthetic
- *                              shadow mode because the `vnode.children` might be the slotted
- *                              content vs default content, in which case the size and the
- *                              keys are not matching.
- *   - children that contain dynamic components
- *   - children that are produced by iteration
- *
+ * - slot element's children: the content of the slot has to be dynamic when in synthetic
+ * shadow mode because the `vnode.children` might be the slotted
+ * content vs default content, in which case the size and the
+ * keys are not matching.
+ * - children that contain dynamic components
+ * - children that are produced by iteration
+ * @param vnodes
  */
 function sc(vnodes) {
     if (process.env.NODE_ENV !== 'production') {
@@ -5404,6 +5427,7 @@ let sanitizeHtmlContentHook = () => {
 };
 /**
  * Sets the sanitizeHtmlContentHook.
+ * @param newHookImpl
  */
 function setSanitizeHtmlContentHook(newHookImpl) {
     sanitizeHtmlContentHook = newHookImpl;
@@ -5585,9 +5609,27 @@ function validateLightDomTemplate(template, vm) {
         }
     }
 }
+// This should be a no-op outside of LWC's Karma tests, where it's not needed
+let registerFragmentCache = shared.noop;
+// Only used in LWC's Karma tests
+if (process.env.NODE_ENV === 'test-karma-lwc') {
+    // Keep track of fragmentCaches, so we can clear them in LWC's Karma tests
+    const fragmentCaches = [];
+    registerFragmentCache = (fragmentCache) => {
+        fragmentCaches.push(fragmentCache);
+    };
+    window.__lwcResetFragmentCaches = () => {
+        for (const fragmentCache of fragmentCaches) {
+            for (const key of shared.keys(fragmentCache)) {
+                delete fragmentCache[key];
+            }
+        }
+    };
+}
 function buildParseFragmentFn(createFragmentFn) {
     return (strings, ...keys) => {
         const cache = shared.create(null);
+        registerFragmentCache(cache);
         return function () {
             const { context: { hasScopedStyles, stylesheetToken, legacyStylesheetToken }, shadowMode, renderer, } = getVMBeingRendered();
             const hasStyleToken = !shared.isUndefined(stylesheetToken);
@@ -5600,11 +5642,6 @@ function buildParseFragmentFn(createFragmentFn) {
             if (hasStyleToken && isSyntheticShadow) {
                 cacheKey |= 2 /* FragmentCache.SHADOW_MODE_SYNTHETIC */;
             }
-            if (hasLegacyToken) {
-                // This isn't strictly required for prod, but it's required for our karma tests
-                // since the lwcRuntimeFlag may change over time
-                cacheKey |= 4 /* FragmentCache.HAS_LEGACY_SCOPE_TOKEN */;
-            }
             if (!shared.isUndefined(cache[cacheKey])) {
                 return cache[cacheKey];
             }
@@ -5845,6 +5882,8 @@ const registeredComponentMap = new Map();
 /**
  * INTERNAL: This function can only be invoked by compiled code. The compiler
  * will prevent this function from being imported by userland code.
+ * @param Ctor
+ * @param metadata
  */
 function registerComponent(
 // We typically expect a LightningElementConstructor, but technically you can call this with anything
@@ -6202,7 +6241,7 @@ function computeShadowMode(def, owner, renderer, hydrated) {
     return shadowMode;
 }
 function assertIsVM(obj) {
-    if (shared.isNull(obj) || !shared.isObject(obj) || !('renderRoot' in obj)) {
+    if (!shared.isObject(obj) || shared.isNull(obj) || !('renderRoot' in obj)) {
         throw new TypeError(`${obj} is not a VM.`);
     }
 }
@@ -6395,6 +6434,7 @@ function runLightChildNodesDisconnectedCallback(vm) {
  * need to continue into its children because by attempting to disconnect the
  * custom element itself will trigger the removal of anything slotted or anything
  * defined on its shadow.
+ * @param vnodes
  */
 function recursivelyDisconnectChildren(vnodes) {
     for (let i = 0, len = vnodes.length; i < len; i += 1) {
@@ -6791,7 +6831,6 @@ function enableDetection() {
                 throw new Error('detect-non-standard-aria.ts loaded before @lwc/aria-reflection');
             }
         }
-        // @ts-ignore
         const { get, set } = descriptor;
         // It's important for this defineProperty call to happen _after_ ARIA accessors are applied to the
         // BaseBridgeElement and LightningElement prototypes. Otherwise, we will log/report for access of non-standard
@@ -7402,7 +7441,7 @@ function warnOnArrayMutation(stylesheets) {
         const originalArrayMethod = getOriginalArrayMethod(prop);
         stylesheets[prop] = function arrayMutationWarningWrapper() {
             reportTemplateViolation('stylesheets');
-            // @ts-ignore
+            // @ts-expect-error can't properly determine the right `this`
             return originalArrayMethod.apply(this, arguments);
         };
     }
@@ -7550,6 +7589,7 @@ function freezeTemplate(tmpl) {
 /**
  * EXPERIMENTAL: This function provides access to the component constructor, given an HTMLElement.
  * This API is subject to change or being removed.
+ * @param elm
  */
 function getComponentConstructor(elm) {
     let ctor = null;
@@ -7574,6 +7614,7 @@ function getComponentConstructor(elm) {
  * EXPERIMENTAL: This function allows you to create a reactive readonly
  * membrane around any object value. This API is subject to change or
  * being removed.
+ * @param obj
  */
 function readonly(obj) {
     if (process.env.NODE_ENV !== 'production') {
@@ -7628,5 +7669,5 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/** version: 6.2.0 */
+/** version: 6.3.0 */
 //# sourceMappingURL=index.cjs.js.map