feat: add support for ElementInternals in synthetic shadow (#5519)

* feat: add support for ElementInternals in synthetic shadow

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

Co-authored-by: Will Harney <62956339+wjhsf@users.noreply.github.com>

* chore: update in response to review comments

* test: add test for setting readonly props in ElementInternals

* Update packages/@lwc/integration-not-karma/test/component/LightningElement.attachInternals/elementInternals/formAssociated/index.spec.js

Co-authored-by: Will Harney <62956339+wjhsf@users.noreply.github.com>

* Update packages/@lwc/integration-not-karma/test/component/LightningElement.attachInternals/elementInternals/formAssociated/index.spec.js

Co-authored-by: Will Harney <62956339+wjhsf@users.noreply.github.com>

* fix: fix test

* feat: add enableSyntheticElementInternals flag

* chore: post-review updates

* Update packages/@lwc/babel-plugin-component/src/component.ts

Co-authored-by: Will Harney <62956339+wjhsf@users.noreply.github.com>

* chore: empty commit

* chore: increase max engine-dom bundle size to 24.81KB

* fix: enableSyntheticElementInternals for rollup

* fix: re-add error message for form lifecycle methods when not available

---------

Co-authored-by: Will Harney <62956339+wjhsf@users.noreply.github.com>

Author: roxanne-baker

packages/@lwc/babel-plugin-component/src/__tests__/fixtures/component/enable-synthetic-element-internals/actual.js

@@ -0,0 +1,3 @@
+import { LightningElement as Component } from "lwc";
+
+export default class Test extends Component {}

packages/@lwc/babel-plugin-component/src/__tests__/fixtures/component/enable-synthetic-element-internals/config.json

@@ -0,0 +1,3 @@
+{
+    "enableSyntheticElementInternals": true
+}

packages/@lwc/babel-plugin-component/src/__tests__/fixtures/component/enable-synthetic-element-internals/error.json

@@ -0,0 +1,12 @@
+import _tmpl from "./test.html";
+import { LightningElement as Component, registerComponent as _registerComponent } from "lwc";
+class Test extends Component {
+  /*LWC compiler vX.X.X*/
+}
+const __lwc_component_class_internal = _registerComponent(Test, {
+  tmpl: _tmpl,
+  sel: "lwc-test",
+  apiVersion: 9999999,
+  enableSyntheticElementInternals: true
+});
+export default __lwc_component_class_internal;

packages/@lwc/babel-plugin-component/src/__tests__/fixtures/component/enable-synthetic-element-internals/expected.js

@@ -14,6 +14,7 @@ import {
     TEMPLATE_KEY,
     API_VERSION_KEY,
     COMPONENT_CLASS_ID,
+    SYNTHETIC_ELEMENT_INTERNALS_KEY,
 } from './constants';
 import type { types, NodePath, Visitor } from '@babel/core';
 import type { BabelAPI, BabelTypes, LwcBabelPluginPass } from './types';
@@ -81,15 +82,25 @@ export default function ({ types: t }: BabelAPI): Visitor<LwcBabelPluginPass> {
         //       sel: 'x-foo',
         //       apiVersion: '58'
         //     })
+        const properties = [
+            t.objectProperty(t.identifier(TEMPLATE_KEY), templateIdentifier),
+            t.objectProperty(t.identifier(COMPONENT_NAME_KEY), componentRegisteredName),
+            // It's important that, at this point, we have an APIVersion rather than just a number.
+            // The client needs to trust the server that it's providing an actual known API version
+            t.objectProperty(t.identifier(API_VERSION_KEY), t.numericLiteral(apiVersion)),
+        ];
+        // Only include enableSyntheticElementInternals if set to true
+        if (state.opts.enableSyntheticElementInternals === true) {
+            properties.push(
+                t.objectProperty(
+                    t.identifier(SYNTHETIC_ELEMENT_INTERNALS_KEY),
+                    t.booleanLiteral(true)
+                )
+            );
+        }
         const registerComponentExpression = t.callExpression(registerComponentId, [
             node as types.Expression,
-            t.objectExpression([
-                t.objectProperty(t.identifier(TEMPLATE_KEY), templateIdentifier),
-                t.objectProperty(t.identifier(COMPONENT_NAME_KEY), componentRegisteredName),
-                // It's important that, at this point, we have an APIVersion rather than just a number.
-                // The client needs to trust the server that it's providing an actual known API version
-                t.objectProperty(t.identifier(API_VERSION_KEY), t.numericLiteral(apiVersion)),
-            ]),
+            t.objectExpression(properties),
         ]);
 
         // Example:

packages/@lwc/babel-plugin-component/src/component.ts

@@ -34,6 +34,7 @@ const TEMPLATE_KEY = 'tmpl';
 const COMPONENT_NAME_KEY = 'sel';
 const API_VERSION_KEY = 'apiVersion';
 const COMPONENT_CLASS_ID = '__lwc_component_class_internal';
+const SYNTHETIC_ELEMENT_INTERNALS_KEY = 'enableSyntheticElementInternals';
 
 export {
     DECORATOR_TYPES,
@@ -46,4 +47,5 @@ export {
     COMPONENT_NAME_KEY,
     API_VERSION_KEY,
     COMPONENT_CLASS_ID,
+    SYNTHETIC_ELEMENT_INTERNALS_KEY,
 };

packages/@lwc/babel-plugin-component/src/constants.ts

@@ -21,6 +21,7 @@ export interface LwcBabelPluginOptions {
     name: string;
     instrumentation?: InstrumentationObject;
     apiVersion?: number;
+    enableSyntheticElementInternals?: boolean;
 }
 
 export interface LwcBabelPluginPass extends PluginPass {

packages/@lwc/babel-plugin-component/src/types.ts

@@ -108,6 +108,8 @@ export interface TransformOptions {
     experimentalDynamicDirective?: boolean;
     /** Flag to enable usage of dynamic component(lwc:is) directive in HTML template */
     enableDynamicComponents?: boolean;
+    /** Flag to enable usage of ElementInternals in synthetic shadow DOM */
+    enableSyntheticElementInternals?: boolean;
     // TODO [#3370]: remove experimental template expression flag
     /** Flag to enable use of (a subset of) JavaScript expressions in place of template bindings. Passed to `@lwc/template-compiler`. */
     experimentalComplexExpressions?: boolean;
@@ -153,6 +155,7 @@ type OptionalTransformKeys =
     | 'enableLwcOn'
     | 'enableLightningWebSecurityTransforms'
     | 'enableDynamicComponents'
+    | 'enableSyntheticElementInternals'
     | 'experimentalDynamicDirective'
     | 'experimentalDynamicComponent'
     | 'instrumentation';

packages/@lwc/compiler/src/options.ts

@@ -33,6 +33,7 @@ export default function scriptTransform(
 ): TransformResult {
     const {
         isExplicitImport,
+        enableSyntheticElementInternals,
         // TODO [#5031]: Unify dynamicImports and experimentalDynamicComponent options
         experimentalDynamicComponent: dynamicImports,
         outputConfig: { sourcemap },
@@ -46,6 +47,7 @@ export default function scriptTransform(
     const lwcBabelPluginOptions: LwcBabelPluginOptions = {
         isExplicitImport,
         dynamicImports,
+        enableSyntheticElementInternals,
         namespace,
         name,
         instrumentation,

packages/@lwc/compiler/src/transformers/javascript.ts

@@ -38,7 +38,11 @@ import {
 } from '../libs/reflection';
 
 import { HTMLElementOriginalDescriptors } from './html-properties';
-import { getComponentAPIVersion, getWrappedComponentsListener } from './component';
+import {
+    getComponentAPIVersion,
+    getWrappedComponentsListener,
+    supportsSyntheticElementInternals,
+} from './component';
 import { isBeingConstructed, isInvokingRender, vmBeingConstructed } from './invoker';
 import { associateVM, getAssociatedVM, RenderMode, ShadowMode } from './vm';
 import { componentValueObserved } from './mutation-tracker';
@@ -493,6 +497,7 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
     attachInternals(): ElementInternals {
         const vm = getAssociatedVM(this);
         const {
+            def: { ctor },
             elm,
             apiVersion,
             renderer: { attachInternals },
@@ -506,11 +511,28 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
             );
         }
 
-        if (vm.shadowMode === ShadowMode.Synthetic) {
+        const internals = attachInternals(elm);
+        if (vm.shadowMode === ShadowMode.Synthetic && supportsSyntheticElementInternals(ctor)) {
+            const handler: ProxyHandler<ElementInternals> = {
+                get(target: ElementInternals, prop: keyof ElementInternals) {
+                    if (prop === 'shadowRoot') {
+                        return vm.shadowRoot;
+                    }
+                    const value = Reflect.get(target, prop);
+                    if (typeof value === 'function') {
+                        return value.bind(target);
+                    }
+                    return value;
+                },
+                set(target: ElementInternals, prop: keyof ElementInternals, value: any) {
+                    return Reflect.set(target, prop, value);
+                },
+            };
+            return new Proxy(internals, handler);
+        } else if (vm.shadowMode === ShadowMode.Synthetic) {
             throw new Error('attachInternals API is not supported in synthetic shadow.');
         }
-
-        return attachInternals(elm);
+        return internals;
     },
 
     get isConnected(): boolean {