@lwc/engine-core 3.4.0 → 3.5.0

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

@@ -17,6 +17,7 @@ export interface LightningElementConstructor {
     readonly CustomElementConstructor: HTMLElementConstructor;
     delegatesFocus?: boolean;
     renderMode?: 'light' | 'shadow';
+    formAssociated?: boolean;
     shadowSupportMode?: ShadowSupportMode;
     stylesheets: TemplateStylesheetFactories;
 }
@@ -32,6 +33,10 @@ export interface LightningElement extends HTMLElementTheGoodParts, AccessibleEle
     disconnectedCallback?(): void;
     renderedCallback?(): void;
     errorCallback?(error: any, stack: string): void;
+    formAssociatedCallback?(): void;
+    formResetCallback?(): void;
+    formDisabledCallback?(): void;
+    formStateRestoreCallback?(): void;
 }
 /**
  * This class is the base class for any LWC element.

package/dist/framework/def.d.ts

@@ -20,12 +20,17 @@ export interface ComponentDef {
     template: Template;
     renderMode: RenderMode;
     shadowSupportMode: ShadowSupportMode;
+    formAssociated: boolean | undefined;
     ctor: LightningElementConstructor;
     bridge: HTMLElementConstructor;
     connectedCallback?: LightningElement['connectedCallback'];
     disconnectedCallback?: LightningElement['disconnectedCallback'];
     renderedCallback?: LightningElement['renderedCallback'];
     errorCallback?: LightningElement['errorCallback'];
+    formAssociatedCallback?: LightningElement['formAssociatedCallback'];
+    formResetCallback?: LightningElement['formResetCallback'];
+    formDisabledCallback?: LightningElement['formDisabledCallback'];
+    formStateRestoreCallback?: LightningElement['formStateRestoreCallback'];
     render: LightningElement['render'];
 }
 /**

package/dist/framework/main.d.ts

@@ -1,5 +1,5 @@
 export { getComponentHtmlPrototype } from './def';
-export { RenderMode, ShadowMode, connectRootElement, createVM, disconnectRootElement, getAssociatedVMIfPresent, computeShadowAndRenderMode, } from './vm';
+export { RenderMode, ShadowMode, connectRootElement, createVM, disconnectRootElement, getAssociatedVMIfPresent, computeShadowAndRenderMode, runFormAssociatedCallback, runFormDisabledCallback, runFormResetCallback, runFormStateRestoreCallback, } from './vm';
 export { createContextProviderWithRegister } from './wiring';
 export { parseFragment, parseSVGFragment } from './template';
 export { hydrateRoot } from './hydration';

package/dist/framework/renderer.d.ts

@@ -41,7 +41,7 @@ export interface RendererAPI {
     isConnected: (node: N) => boolean;
     insertStylesheet: (content: string, target?: ShadowRoot) => void;
     assertInstanceOfHTMLElement: (elm: any, msg: string) => void;
-    createCustomElement: (tagName: string, upgradeCallback: LifecycleCallback, connectedCallback?: LifecycleCallback, disconnectedCallback?: LifecycleCallback) => E;
+    createCustomElement: (tagName: string, upgradeCallback: LifecycleCallback, connectedCallback?: LifecycleCallback, disconnectedCallback?: LifecycleCallback, formAssociatedCallback?: LifecycleCallback, formDisabledCallback?: LifecycleCallback, formResetCallback?: LifecycleCallback, formStateRestoreCallback?: LifecycleCallback) => E;
     ownerDocument(elm: E): Document;
     registerContextConsumer: (element: E, adapterContextToken: string, subscriptionPayload: WireContextSubscriptionPayload) => void;
     attachInternals: (elm: E) => ElementInternals;

package/dist/framework/vm.d.ts

@@ -166,4 +166,9 @@ export declare function resetComponentRoot(vm: VM): void;
 export declare function scheduleRehydration(vm: VM): void;
 export declare function runWithBoundaryProtection(vm: VM, owner: VM | null, pre: () => void, job: () => void, post: () => void): void;
 export declare function forceRehydration(vm: VM): void;
+export declare function runFormAssociatedCustomElementCallback(vm: VM, faceCb: () => void): void;
+export declare function runFormAssociatedCallback(elm: HTMLElement): void;
+export declare function runFormDisabledCallback(elm: HTMLElement): void;
+export declare function runFormResetCallback(elm: HTMLElement): void;
+export declare function runFormStateRestoreCallback(elm: HTMLElement): void;
 export {};

package/dist/index.cjs.js

@@ -523,8 +523,8 @@ function lockDomMutation() {
     assertNotProd(); // this method should never leak to prod
     isDomMutationAllowed = false;
 }
-function logMissingPortalError(name, type) {
-    return logError(`The \`${name}\` ${type} is available only on elements that use the \`lwc:dom="manual"\` directive.`);
+function logMissingPortalWarn(name, type) {
+    return logWarn(`The \`${name}\` ${type} is available only on elements that use the \`lwc:dom="manual"\` directive.`);
 }
 function patchElementWithRestrictions(elm, options) {
     assertNotProd(); // this method should never leak to prod
@@ -549,14 +549,14 @@ function patchElementWithRestrictions(elm, options) {
         shared.assign(descriptors, {
             appendChild: generateDataDescriptor({
                 value(aChild) {
-                    logMissingPortalError('appendChild', 'method');
+                    logMissingPortalWarn('appendChild', 'method');
                     return appendChild.call(this, aChild);
                 },
             }),
             insertBefore: generateDataDescriptor({
                 value(newNode, referenceNode) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('insertBefore', 'method');
+                        logMissingPortalWarn('insertBefore', 'method');
                     }
                     return insertBefore.call(this, newNode, referenceNode);
                 },
@@ -564,14 +564,14 @@ function patchElementWithRestrictions(elm, options) {
             removeChild: generateDataDescriptor({
                 value(aChild) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('removeChild', 'method');
+                        logMissingPortalWarn('removeChild', 'method');
                     }
                     return removeChild.call(this, aChild);
                 },
             }),
             replaceChild: generateDataDescriptor({
                 value(newChild, oldChild) {
-                    logMissingPortalError('replaceChild', 'method');
+                    logMissingPortalWarn('replaceChild', 'method');
                     return replaceChild.call(this, newChild, oldChild);
                 },
             }),
@@ -581,7 +581,7 @@ function patchElementWithRestrictions(elm, options) {
                 },
                 set(value) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('nodeValue', 'property');
+                        logMissingPortalWarn('nodeValue', 'property');
                     }
                     originalNodeValueDescriptor.set.call(this, value);
                 },
@@ -591,7 +591,7 @@ function patchElementWithRestrictions(elm, options) {
                     return originalTextContentDescriptor.get.call(this);
                 },
                 set(value) {
-                    logMissingPortalError('textContent', 'property');
+                    logMissingPortalWarn('textContent', 'property');
                     originalTextContentDescriptor.set.call(this, value);
                 },
             }),
@@ -600,7 +600,7 @@ function patchElementWithRestrictions(elm, options) {
                     return originalInnerHTMLDescriptor.get.call(this);
                 },
                 set(value) {
-                    logMissingPortalError('innerHTML', 'property');
+                    logMissingPortalWarn('innerHTML', 'property');
                     return originalInnerHTMLDescriptor.set.call(this, value);
                 },
             }),
@@ -1458,7 +1458,51 @@ 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.`);
     }
 }
-const supportsElementInternals = typeof ElementInternals !== 'undefined';
+// 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 assertFormAssociatedPropertySet(propertyKey, isFormAssociated) {
+    if (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.`);
+    }
+}
+// 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) {
+            // ElementInternals implementation uses strings as property keys exclusively in chrome, firefox, and safari
+            assertFormAssociatedPropertySet(propertyKey, isFormAssociated);
+            return Reflect.set(target, propertyKey, newValue);
+        },
+        get(target, propertyKey) {
+            // ElementInternals implementation uses strings as property keys exclusively in chrome, firefox, and safari
+            assertFormAssociatedPropertySet(propertyKey, isFormAssociated);
+            const internalsPropertyValue = Reflect.get(target, propertyKey);
+            // Bind the property value to the target so that function invocations are called with the
+            // correct context ('this' value).
+            return typeof internalsPropertyValue === 'function'
+                ? internalsPropertyValue.bind(target)
+                : internalsPropertyValue;
+        },
+    });
+    return elementInternalsProxy;
+}
 // @ts-ignore
 LightningElement.prototype = {
     constructor: LightningElement,
@@ -1552,15 +1596,13 @@ LightningElement.prototype = {
     },
     attachInternals() {
         const vm = getAssociatedVM(this);
-        const { elm, renderer: { attachInternals }, } = vm;
-        if (shared.isFalse(supportsElementInternals)) {
-            // Browsers that don't support attachInternals will need to be polyfilled before LWC is loaded.
-            throw new Error('attachInternals API is not supported in this browser environment.');
-        }
-        if (vm.renderMode === 0 /* RenderMode.Light */ || vm.shadowMode === 1 /* ShadowMode.Synthetic */) {
+        const { elm, def: { formAssociated }, renderer: { attachInternals }, } = vm;
+        if (vm.shadowMode === 1 /* ShadowMode.Synthetic */) {
             throw new Error('attachInternals API is not supported in light DOM or synthetic shadow.');
         }
-        return attachInternals(elm);
+        const internals = attachInternals(elm);
+        // #TODO[2970]: remove proxy once `UpgradeableConstructor` has been removed
+        return createElementInternalsProxy(internals, Boolean(formAssociated));
     },
     get isConnected() {
         const vm = getAssociatedVM(this);
@@ -2641,9 +2683,26 @@ function HTMLBridgeElementFactory(SuperClass, publicProperties, methods, observe
     };
     // To avoid leaking private component details, accessing internals from outside a component is not allowed.
     descriptors.attachInternals = {
+        set() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('attachInternals cannot be accessed outside of a component. Use this.attachInternals instead.');
+            }
+        },
         get() {
             if (process.env.NODE_ENV !== 'production') {
-                logError('attachInternals cannot be accessed outside of a component. Use this.attachInternals instead.');
+                logWarn('attachInternals cannot be accessed outside of a component. Use this.attachInternals instead.');
+            }
+        },
+    };
+    descriptors.formAssociated = {
+        set() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('formAssociated cannot be accessed outside of a component. Set the value within the component class.');
+            }
+        },
+        get() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('formAssociated cannot be accessed outside of a component. Set the value within the component class.');
             }
         },
     };
@@ -2955,7 +3014,7 @@ function getCtorProto(Ctor) {
     return proto;
 }
 function createComponentDef(Ctor) {
-    const { shadowSupportMode: ctorShadowSupportMode, renderMode: ctorRenderMode } = Ctor;
+    const { shadowSupportMode: ctorShadowSupportMode, renderMode: ctorRenderMode, formAssociated: ctorFormAssociated, } = Ctor;
     if (process.env.NODE_ENV !== 'production') {
         const ctorName = Ctor.name;
         // Removing the following assert until https://bugs.webkit.org/show_bug.cgi?id=190140 is fixed.
@@ -2979,7 +3038,7 @@ function createComponentDef(Ctor) {
     const decoratorsMeta = getDecoratorsMeta(Ctor);
     const { apiFields, apiFieldsConfig, apiMethods, wiredFields, wiredMethods, observedFields } = decoratorsMeta;
     const proto = Ctor.prototype;
-    let { connectedCallback, disconnectedCallback, renderedCallback, errorCallback, render } = proto;
+    let { connectedCallback, disconnectedCallback, renderedCallback, errorCallback, formAssociatedCallback, formResetCallback, formDisabledCallback, formStateRestoreCallback, render, } = proto;
     const superProto = getCtorProto(Ctor);
     const superDef = superProto !== LightningElement ? getComponentInternalDef(superProto) : lightingElementDef;
     const bridge = HTMLBridgeElementFactory(superDef.bridge, shared.keys(apiFields), shared.keys(apiMethods), shared.keys(observedFields), proto);
@@ -2991,6 +3050,10 @@ function createComponentDef(Ctor) {
     disconnectedCallback = disconnectedCallback || superDef.disconnectedCallback;
     renderedCallback = renderedCallback || superDef.renderedCallback;
     errorCallback = errorCallback || superDef.errorCallback;
+    formAssociatedCallback = formAssociatedCallback || superDef.formAssociatedCallback;
+    formResetCallback = formResetCallback || superDef.formResetCallback;
+    formDisabledCallback = formDisabledCallback || superDef.formDisabledCallback;
+    formStateRestoreCallback = formStateRestoreCallback || superDef.formStateRestoreCallback;
     render = render || superDef.render;
     let shadowSupportMode = superDef.shadowSupportMode;
     if (!shared.isUndefined(ctorShadowSupportMode)) {
@@ -3000,6 +3063,10 @@ function createComponentDef(Ctor) {
     if (!shared.isUndefined(ctorRenderMode)) {
         renderMode = ctorRenderMode === 'light' ? 0 /* RenderMode.Light */ : 1 /* RenderMode.Shadow */;
     }
+    let formAssociated = superDef.formAssociated;
+    if (!shared.isUndefined(ctorFormAssociated)) {
+        formAssociated = ctorFormAssociated;
+    }
     const template = getComponentRegisteredTemplate(Ctor) || superDef.template;
     const name = Ctor.name || superDef.name;
     // installing observed fields into the prototype.
@@ -3015,10 +3082,15 @@ function createComponentDef(Ctor) {
         template,
         renderMode,
         shadowSupportMode,
+        formAssociated,
         connectedCallback,
         disconnectedCallback,
-        renderedCallback,
         errorCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback,
+        renderedCallback,
         render,
     };
     // This is a no-op unless Lightning DevTools are enabled.
@@ -3095,6 +3167,7 @@ const lightingElementDef = {
     methods: EmptyObject,
     renderMode: 1 /* RenderMode.Shadow */,
     shadowSupportMode: "reset" /* ShadowSupportMode.Default */,
+    formAssociated: undefined,
     wire: EmptyObject,
     bridge: BaseBridgeElement,
     template: defaultEmptyTemplate,
@@ -3804,6 +3877,10 @@ function mountCustomElement(vnode, parent, anchor, renderer) {
     };
     let connectedCallback;
     let disconnectedCallback;
+    let formAssociatedCallback;
+    let formDisabledCallback;
+    let formResetCallback;
+    let formStateRestoreCallback;
     if (lwcRuntimeFlags.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
         connectedCallback = (elm) => {
             connectRootElement(elm);
@@ -3811,13 +3888,25 @@ function mountCustomElement(vnode, parent, anchor, renderer) {
         disconnectedCallback = (elm) => {
             disconnectRootElement(elm);
         };
+        formAssociatedCallback = (elm) => {
+            runFormAssociatedCallback(elm);
+        };
+        formDisabledCallback = (elm) => {
+            runFormDisabledCallback(elm);
+        };
+        formResetCallback = (elm) => {
+            runFormResetCallback(elm);
+        };
+        formStateRestoreCallback = (elm) => {
+            runFormStateRestoreCallback(elm);
+        };
     }
     // Should never get a tag with upper case letter at this point; the compiler
     // should produce only tags with lowercase letters. However, the Java
     // compiler may generate tagnames with uppercase letters so - for backwards
     // compatibility, we lower case the tagname here.
     const normalizedTagname = sel.toLowerCase();
-    const elm = createCustomElement(normalizedTagname, upgradeCallback, connectedCallback, disconnectedCallback);
+    const elm = createCustomElement(normalizedTagname, upgradeCallback, connectedCallback, disconnectedCallback, formAssociatedCallback, formDisabledCallback, formResetCallback, formStateRestoreCallback);
     vnode.elm = elm;
     vnode.vm = vm;
     linkNodeToShadow(elm, owner, renderer);
@@ -5945,6 +6034,48 @@ function forceRehydration(vm) {
         scheduleRehydration(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;
+    }
+    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.');
+    }
+    invokeComponentCallback(vm, faceCb);
+}
+function runFormAssociatedCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formAssociatedCallback } = vm.def;
+    if (!shared.isUndefined(formAssociatedCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formAssociatedCallback);
+    }
+}
+function runFormDisabledCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formDisabledCallback } = vm.def;
+    if (!shared.isUndefined(formDisabledCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formDisabledCallback);
+    }
+}
+function runFormResetCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formResetCallback } = vm.def;
+    if (!shared.isUndefined(formResetCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formResetCallback);
+    }
+}
+function runFormStateRestoreCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formStateRestoreCallback } = vm.def;
+    if (!shared.isUndefined(formStateRestoreCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formStateRestoreCallback);
+    }
+}
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -6857,7 +6988,7 @@ function trackMutations(tmpl) {
 }
 function addLegacyStylesheetTokensShim(tmpl) {
     // When ENABLE_FROZEN_TEMPLATE is false, then we shim stylesheetTokens on top of stylesheetToken for anyone who
-    // is accessing the old internal API (backwards compat). Details: https://salesforce.quip.com/v1rmAFu2cKAr
+    // is accessing the old internal API (backwards compat). Details: W-14210169
     shared.defineProperty(tmpl, 'stylesheetTokens', {
         enumerable: true,
         configurable: true,
@@ -6982,6 +7113,10 @@ exports.readonly = readonly;
 exports.registerComponent = registerComponent;
 exports.registerDecorators = registerDecorators;
 exports.registerTemplate = registerTemplate;
+exports.runFormAssociatedCallback = runFormAssociatedCallback;
+exports.runFormDisabledCallback = runFormDisabledCallback;
+exports.runFormResetCallback = runFormResetCallback;
+exports.runFormStateRestoreCallback = runFormStateRestoreCallback;
 exports.sanitizeAttribute = sanitizeAttribute;
 exports.setHooks = setHooks;
 exports.swapComponent = swapComponent;
@@ -6990,5 +7125,5 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/** version: 3.4.0 */
+/** version: 3.5.0 */
 //# sourceMappingURL=index.cjs.js.map