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

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

@@ -21,7 +21,7 @@ import {
     htmlPropertyToAttribute,
 } from '@lwc/shared';
 import { applyAriaReflection } from '@lwc/aria-reflection';
-import { logError } from '../shared/logger';
+import { logError, logWarn } from '../shared/logger';
 import { getAssociatedVM } from './vm';
 import { getReadOnlyProxy } from './membrane';
 import { HTMLElementConstructor } from './html-element';
@@ -161,6 +161,16 @@ export function HTMLBridgeElementFactory(
         },
     };
 
+    descriptors.formAssociated = {
+        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,8 +300,6 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
     }
 }
 
-const supportsElementInternals = typeof ElementInternals !== 'undefined';
-
 // @ts-ignore
 LightningElement.prototype = {
     constructor: LightningElement,
@@ -470,12 +472,7 @@ LightningElement.prototype = {
             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.'
             );

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;
@@ -156,6 +174,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;
@@ -168,6 +190,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;
 
@@ -185,10 +212,15 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
         template,
         renderMode,
         shadowSupportMode,
+        formAssociated,
         connectedCallback,
         disconnectedCallback,
-        renderedCallback,
         errorCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback,
+        renderedCallback,
         render,
     };
 
@@ -283,6 +315,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;

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

@@ -22,7 +22,7 @@ import {
 } from '@lwc/shared';
 
 import { addErrorComponentStack } from '../shared/error';
-import { logError, logWarnOnce } from '../shared/logger';
+import { logError, logWarn, logWarnOnce } from '../shared/logger';
 
 import { HostNode, HostElement, RendererAPI } from './renderer';
 import { renderComponent, markComponentAsDirty, getTemplateReactiveObserver } from './component';
@@ -840,3 +840,65 @@ export function forceRehydration(vm: VM) {
         scheduleRehydration(vm);
     }
 }
+
+export function runFormAssociatedCustomElementCallback(vm: VM, faceCb: () => void) {
+    const {
+        renderMode,
+        shadowMode,
+        def: { formAssociated },
+    } = vm;
+
+    // Technically the UpgradableConstructor always sets `static formAssociated = true` but silently fail here to match browser behavior.
+    if (isUndefined(formAssociated) || 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 === ShadowMode.Synthetic && renderMode !== 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);
+}
+
+export function runFormAssociatedCallback(elm: HTMLElement) {
+    const vm = getAssociatedVM(elm);
+    const { formAssociatedCallback } = vm.def;
+
+    if (!isUndefined(formAssociatedCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formAssociatedCallback);
+    }
+}
+
+export function runFormDisabledCallback(elm: HTMLElement) {
+    const vm = getAssociatedVM(elm);
+    const { formDisabledCallback } = vm.def;
+
+    if (!isUndefined(formDisabledCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formDisabledCallback);
+    }
+}
+
+export function runFormResetCallback(elm: HTMLElement) {
+    const vm = getAssociatedVM(elm);
+    const { formResetCallback } = vm.def;
+
+    if (!isUndefined(formResetCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formResetCallback);
+    }
+}
+
+export function runFormStateRestoreCallback(elm: HTMLElement) {
+    const vm = getAssociatedVM(elm);
+    const { formStateRestoreCallback } = vm.def;
+
+    if (!isUndefined(formStateRestoreCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formStateRestoreCallback);
+    }
+}

packages/@lwc/engine-dom/src/apis/create-element.ts

@@ -20,6 +20,10 @@ import {
     disconnectRootElement,
     LightningElement,
     LifecycleCallback,
+    runFormAssociatedCallback,
+    runFormDisabledCallback,
+    runFormResetCallback,
+    runFormStateRestoreCallback,
 } from '@lwc/engine-core';
 import { renderer } from '../renderer';
 
@@ -133,6 +137,10 @@ export function createElement(
 
     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) => {
@@ -141,13 +149,29 @@ export function createElement(
         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);
+        };
     }
 
     const element = createCustomElement(
         tagName,
         upgradeCallback,
         connectedCallback,
-        disconnectedCallback
+        disconnectedCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback
     );
     return element;
 }