@lwc/engine-core 6.2.1 → 6.3.1

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

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

package/dist/framework/renderer.d.ts

@@ -42,8 +42,8 @@ export interface RendererAPI {
     isConnected: (node: N) => boolean;
     insertStylesheet: (content: string, target?: ShadowRoot) => void;
     assertInstanceOfHTMLElement: (elm: any, msg: string) => void;
-    createCustomElement: (tagName: string, upgradeCallback: LifecycleCallback, useNativeLifecycle: boolean) => E;
-    defineCustomElement: (tagName: string) => void;
+    createCustomElement: (tagName: string, upgradeCallback: LifecycleCallback, useNativeLifecycle: boolean, isFormAssociated: boolean) => E;
+    defineCustomElement: (tagName: string, isFormAssociated: boolean) => void;
     ownerDocument(elm: E): Document;
     registerContextConsumer: (element: E, adapterContextToken: string, subscriptionPayload: WireContextSubscriptionPayload) => void;
     attachInternals: (elm: E) => ElementInternals;

package/dist/index.cjs.js

@@ -132,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
@@ -140,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();
     };
@@ -798,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);
             },
         }),
@@ -847,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);
             },
         }),
@@ -1599,7 +1598,7 @@ 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)) {
@@ -1668,80 +1667,7 @@ function warnIfInvokedDuringConstruction(vm, methodOrPropName) {
         logError(`this.${methodOrPropName} should not be called during the construction of the custom element for ${getComponentTag(vm)} because the element is not yet in the DOM or has no children yet.`);
     }
 }
-// List of properties on ElementInternals that are formAssociated can be found in the spec:
-// https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements
-const formAssociatedProps = new Set([
-    'setFormValue',
-    'form',
-    'setValidity',
-    'willValidate',
-    'validity',
-    'validationMessage',
-    'checkValidity',
-    'reportValidity',
-    'labels',
-]);
-// Verify that access to a form-associated property of the ElementInternals proxy has formAssociated set in the LWC.
-function verifyPropForFormAssociation(propertyKey, isFormAssociated) {
-    if (shared.isString(propertyKey) && formAssociatedProps.has(propertyKey) && !isFormAssociated) {
-        //Note this error message mirrors Chrome and Firefox error messages, in Safari the error is slightly different.
-        throw new DOMException(`Failed to execute '${propertyKey}' on 'ElementInternals': The target element is not a form-associated custom element.`);
-    }
-}
-const elementInternalsAccessorAllowList = new Set(['shadowRoot', 'role', ...formAssociatedProps]);
-// Prevent access to properties not defined in the HTML spec in case browsers decide to
-// provide new APIs that provide access to form associated properties.
-// This can be removed along with UpgradeableConstructor.
-function isAllowedElementInternalAccessor(propertyKey) {
-    let isAllowedAccessor = false;
-    // As of this writing all ElementInternal property keys as described in the spec are implemented with strings
-    // in Chrome, Firefox, and Safari
-    if (shared.isString(propertyKey)) {
-        // Allow list is based on HTML spec:
-        // https://html.spec.whatwg.org/multipage/custom-elements.html#the-elementinternals-interface
-        isAllowedAccessor =
-            elementInternalsAccessorAllowList.has(propertyKey) || /^aria/.test(propertyKey);
-        if (!isAllowedAccessor && process.env.NODE_ENV !== 'production') {
-            logWarn('Only properties defined in the ElementInternals HTML spec are available.');
-        }
-    }
-    return isAllowedAccessor;
-}
-// Wrap all ElementInternal objects in a proxy to prevent form association when `formAssociated` is not set on an LWC.
-// This is needed because the 1UpgradeableConstructor1 always sets `formAssociated=true`, which means all
-// ElementInternal objects will have form-associated properties set when an LWC is placed in a form.
-// We are doing this to guard against customers taking a dependency on form elements being associated to ElementInternals
-// when 'formAssociated' has not been set on the LWC.
-function createElementInternalsProxy(elementInternals, isFormAssociated) {
-    const elementInternalsProxy = new Proxy(elementInternals, {
-        set(target, propertyKey, newValue) {
-            if (isAllowedElementInternalAccessor(propertyKey)) {
-                // Verify that formAssociated is set for form associated properties
-                verifyPropForFormAssociation(propertyKey, isFormAssociated);
-                return Reflect.set(target, propertyKey, newValue);
-            }
-            // As of this writing ElementInternals do not have non-string properties that can be set.
-            return false;
-        },
-        get(target, propertyKey) {
-            if (
-            // Pass through Object.prototype methods such as toString()
-            shared.hasOwnProperty.call(Object.prototype, propertyKey) ||
-                // As of this writing, ElementInternals only uses Symbol.toStringTag which is called
-                // on Object.hasOwnProperty invocations
-                Symbol.for('Symbol.toStringTag') === propertyKey ||
-                // ElementInternals allow listed properties
-                isAllowedElementInternalAccessor(propertyKey)) {
-                // Verify that formAssociated is set for form associated properties
-                verifyPropForFormAssociation(propertyKey, isFormAssociated);
-                const propertyValue = Reflect.get(target, propertyKey);
-                return shared.isFunction(propertyValue) ? propertyValue.bind(target) : propertyValue;
-            }
-        },
-    });
-    return elementInternalsProxy;
-}
-// @ts-ignore
+// Type assertion because we need to build the prototype before it satisfies the interface.
 LightningElement.prototype = {
     constructor: LightningElement,
     dispatchEvent(event) {
@@ -1834,13 +1760,14 @@ LightningElement.prototype = {
     },
     attachInternals() {
         const vm = getAssociatedVM(this);
-        const { elm, def: { formAssociated }, renderer: { attachInternals }, } = vm;
+        const { elm, apiVersion, renderer: { attachInternals }, } = vm;
+        if (!shared.isAPIFeatureEnabled(8 /* APIFeature.ENABLE_ELEMENT_INTERNALS */, apiVersion)) {
+            throw new Error(`The attachInternals API is only supported in API version 61 and above. To use this API please update the LWC component API version.`);
+        }
         if (vm.shadowMode === 1 /* ShadowMode.Synthetic */) {
-            throw new Error('attachInternals API is not supported in light DOM or synthetic shadow.');
+            throw new Error('attachInternals API is not supported in synthetic shadow.');
         }
-        const internals = attachInternals(elm);
-        // #TODO[2970]: remove proxy once `UpgradeableConstructor` has been removed
-        return createElementInternalsProxy(internals, Boolean(formAssociated));
+        return attachInternals(elm);
     },
     get isConnected() {
         const vm = getAssociatedVM(this);
@@ -1943,6 +1870,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() {
@@ -2182,7 +2112,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 {
@@ -2258,7 +2188,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(),
@@ -2737,7 +2667,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;
     };
@@ -2855,7 +2784,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;
@@ -4312,7 +4241,8 @@ function mountCustomElement(vnode, parent, anchor, renderer) {
     // compatibility, we lower case the tagname here.
     const normalizedTagname = sel.toLowerCase();
     const useNativeLifecycle = shouldUseNativeCustomElementLifecycle(ctor);
-    const elm = createCustomElement(normalizedTagname, upgradeCallback, useNativeLifecycle);
+    const isFormAssociated = Boolean(ctor.formAssociated);
+    const elm = createCustomElement(normalizedTagname, upgradeCallback, useNativeLifecycle, isFormAssociated);
     vnode.elm = elm;
     vnode.vm = vm;
     linkNodeToShadow(elm, owner, renderer);
@@ -5608,9 +5538,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);
@@ -5623,11 +5571,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];
             }
@@ -6535,14 +6478,7 @@ function forceRehydration(vm) {
     }
 }
 function runFormAssociatedCustomElementCallback(vm, faceCb) {
-    const { renderMode, shadowMode, def: { formAssociated }, } = vm;
-    // Technically the UpgradableConstructor always sets `static formAssociated = true` but silently fail here to match browser behavior.
-    if (shared.isUndefined(formAssociated) || shared.isFalse(formAssociated)) {
-        if (process.env.NODE_ENV !== 'production') {
-            logWarn(`Form associated lifecycle methods must have the 'static formAssociated' value set in the component's prototype chain.`);
-        }
-        return;
-    }
+    const { renderMode, shadowMode } = vm;
     if (shadowMode === 1 /* ShadowMode.Synthetic */ && renderMode !== 0 /* RenderMode.Light */) {
         throw new Error('Form associated lifecycle methods are not available in synthetic shadow. Please use native shadow or light DOM.');
     }
@@ -6817,7 +6753,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
@@ -7036,7 +6971,7 @@ function hydrateCustomElement(elm, vnode, renderer) {
     }
     const { sel, mode, ctor, owner } = vnode;
     const { defineCustomElement, getTagName } = renderer;
-    defineCustomElement(shared.StringToLowerCase.call(getTagName(elm)));
+    defineCustomElement(shared.StringToLowerCase.call(getTagName(elm)), Boolean(ctor.formAssociated));
     const vm = createVM(elm, ctor, renderer, {
         mode,
         owner,
@@ -7428,7 +7363,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);
         };
     }
@@ -7656,5 +7591,5 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/** version: 6.2.1 */
+/** version: 6.3.1 */
 //# sourceMappingURL=index.cjs.js.map