feat: enable face lifecycle methods and wrap ElementInternals in a proxy

packages/@lwc/engine-core/src/framework/base-bridge-element.ts

@@ -24,7 +24,7 @@ import {
     isNull,
 } from '@lwc/shared';
 import { applyAriaReflection } from '@lwc/aria-reflection';
-import { logError, logWarn } from '../shared/logger';
+import { logWarn } from '../shared/logger';
 import { getAssociatedVM } from './vm';
 import { getReadOnlyProxy } from './membrane';
 import { HTMLElementConstructor, HTMLElementPrototype } from './html-element';
@@ -204,15 +204,39 @@ export function HTMLBridgeElementFactory(
 
     // 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(
+                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.'
+                );
+            }
+        },
+    };
+
     // Specify attributes for which we want to reflect changes back to their corresponding
     // properties via attributeChangedCallback.
     defineProperty(HTMLBridgeElement, 'observedAttributes', {

packages/@lwc/engine-core/src/framework/base-lightning-element.ts

@@ -18,7 +18,6 @@ import {
     defineProperties,
     defineProperty,
     freeze,
-    isFalse,
     isFunction,
     isNull,
     isObject,
@@ -136,6 +135,7 @@ export interface LightningElementConstructor {
 
     delegatesFocus?: boolean;
     renderMode?: 'light' | 'shadow';
+    formAssociated?: boolean;
     shadowSupportMode?: ShadowSupportMode;
     stylesheets: TemplateStylesheetFactories;
 }
@@ -193,6 +193,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;
 }
 
 /**
@@ -296,7 +300,59 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
     }
 }
 
-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: string, isFormAssociated: boolean) {
+    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: ElementInternals,
+    isFormAssociated: boolean
+) {
+    const elementInternalsProxy = new Proxy(elementInternals, {
+        set(target, propertyKey, newValue) {
+            // ElementInternals implementation uses strings as property keys exclusively in chrome, firefox, and safari
+            assertFormAssociatedPropertySet(propertyKey as string, 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 as string, 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 = {
@@ -467,21 +523,19 @@ LightningElement.prototype = {
         const vm = getAssociatedVM(this);
         const {
             elm,
+            def: { formAssociated },
             renderer: { attachInternals },
         } = vm;
 
-        if (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 === RenderMode.Light || vm.shadowMode === ShadowMode.Synthetic) {
+        if (vm.shadowMode === 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(): boolean {

packages/@lwc/engine-core/src/framework/def.ts

@@ -58,12 +58,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'];
 }
 
@@ -96,7 +101,11 @@ function getCtorProto(Ctor: LightningElementConstructor): LightningElementConstr
 }
 
 function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
-    const { shadowSupportMode: ctorShadowSupportMode, renderMode: ctorRenderMode } = Ctor;
+    const {
+        shadowSupportMode: ctorShadowSupportMode,
+        renderMode: ctorRenderMode,
+        formAssociated: ctorFormAssociated,
+    } = Ctor;
 
     if (process.env.NODE_ENV !== 'production') {
         const ctorName = Ctor.name;
@@ -137,8 +146,17 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
         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;
@@ -162,6 +180,10 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
     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;
@@ -174,6 +196,11 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
         renderMode = ctorRenderMode === 'light' ? RenderMode.Light : RenderMode.Shadow;
     }
 
+    let formAssociated = superDef.formAssociated;
+    if (!isUndefined(ctorFormAssociated)) {
+        formAssociated = ctorFormAssociated;
+    }
+
     const template = getComponentRegisteredTemplate(Ctor) || superDef.template;
     const name = Ctor.name || superDef.name;
 
@@ -191,10 +218,15 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
         template,
         renderMode,
         shadowSupportMode,
+        formAssociated,
         connectedCallback,
         disconnectedCallback,
-        renderedCallback,
         errorCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback,
+        renderedCallback,
         render,
     };
 
@@ -289,6 +321,7 @@ const lightingElementDef: ComponentDef = {
     methods: EmptyObject,
     renderMode: RenderMode.Shadow,
     shadowSupportMode: ShadowSupportMode.Default,
+    formAssociated: undefined,
     wire: EmptyObject,
     bridge: BaseBridgeElement,
     template: defaultEmptyTemplate,

packages/@lwc/engine-core/src/framework/main.ts

@@ -15,6 +15,10 @@ export {
     disconnectRootElement,
     getAssociatedVMIfPresent,
     computeShadowAndRenderMode,
+    runFormAssociatedCallback,
+    runFormDisabledCallback,
+    runFormResetCallback,
+    runFormStateRestoreCallback,
 } from './vm';
 export { createContextProviderWithRegister } from './wiring';
 

packages/@lwc/engine-core/src/framework/renderer.ts

@@ -65,7 +65,11 @@ export interface RendererAPI {
         tagName: string,
         upgradeCallback: LifecycleCallback,
         connectedCallback?: LifecycleCallback,
-        disconnectedCallback?: LifecycleCallback
+        disconnectedCallback?: LifecycleCallback,
+        formAssociatedCallback?: LifecycleCallback,
+        formDisabledCallback?: LifecycleCallback,
+        formResetCallback?: LifecycleCallback,
+        formStateRestoreCallback?: LifecycleCallback
     ) => E;
     ownerDocument(elm: E): Document;
     registerContextConsumer: (

packages/@lwc/engine-core/src/framework/rendering.ts

@@ -39,6 +39,10 @@ import {
     RenderMode,
     rerenderVM,
     runConnectedCallback,
+    runFormAssociatedCallback,
+    runFormDisabledCallback,
+    runFormResetCallback,
+    runFormStateRestoreCallback,
     ShadowMode,
     VM,
     VMState,
@@ -319,6 +323,10 @@ function mountCustomElement(
 
     let connectedCallback: LifecycleCallback | undefined;
     let disconnectedCallback: LifecycleCallback | undefined;
+    let formAssociatedCallback: LifecycleCallback | undefined;
+    let formDisabledCallback: LifecycleCallback | undefined;
+    let formResetCallback: LifecycleCallback | undefined;
+    let formStateRestoreCallback: LifecycleCallback | undefined;
 
     if (lwcRuntimeFlags.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
         connectedCallback = (elm: HTMLElement) => {
@@ -327,6 +335,18 @@ function mountCustomElement(
         disconnectedCallback = (elm: HTMLElement) => {
             disconnectRootElement(elm);
         };
+        formAssociatedCallback = (elm: HTMLElement) => {
+            runFormAssociatedCallback(elm);
+        };
+        formDisabledCallback = (elm: HTMLElement) => {
+            runFormDisabledCallback(elm);
+        };
+        formResetCallback = (elm: HTMLElement) => {
+            runFormResetCallback(elm);
+        };
+        formStateRestoreCallback = (elm: HTMLElement) => {
+            runFormStateRestoreCallback(elm);
+        };
     }
 
     // Should never get a tag with upper case letter at this point; the compiler
@@ -338,7 +358,11 @@ function mountCustomElement(
         normalizedTagname,
         upgradeCallback,
         connectedCallback,
-        disconnectedCallback
+        disconnectedCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback
     );
 
     vnode.elm = elm;