feat: add enableSyntheticElementInternals flag

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';
@@ -75,6 +76,10 @@ export default function ({ types: t }: BabelAPI): Visitor<LwcBabelPluginPass> {
 
         const apiVersion = getAPIVersionFromNumber(state.opts.apiVersion);
 
+        const supportsSyntheticElementInternals = t.booleanLiteral(
+            state.opts.enableSyntheticElementInternals
+        );
+
         // Example:
         //     registerComponent(cmp, {
         //       tmpl: template,
@@ -89,6 +94,10 @@ export default function ({ types: t }: BabelAPI): Visitor<LwcBabelPluginPass> {
                 // 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.objectProperty(
+                    t.identifier(SYNTHETIC_ELEMENT_INTERNALS_KEY),
+                    supportsSyntheticElementInternals
+                ),
             ]),
         ]);
 

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

@@ -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 },
@@ -507,7 +512,7 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
         }
 
         const internals = attachInternals(elm);
-        if (vm.shadowMode === ShadowMode.Synthetic) {
+        if (supportsSyntheticElementInternals(ctor) && vm.shadowMode === ShadowMode.Synthetic) {
             const handler: ProxyHandler<ElementInternals> = {
                 get(target: ElementInternals, prop: keyof ElementInternals) {
                     if (prop === 'shadowRoot') {

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

@@ -24,6 +24,7 @@ type ComponentConstructorMetadata = {
     tmpl: Template;
     sel: string;
     apiVersion: APIVersion;
+    enableSyntheticElementInternals: boolean;
 };
 const registeredComponentMap: Map<LightningElementConstructor, ComponentConstructorMetadata> =
     new Map();
@@ -76,6 +77,12 @@ export function getComponentAPIVersion(Ctor: LightningElementConstructor): APIVe
     return apiVersion;
 }
 
+export function supportsSyntheticElementInternals(
+    Ctor: LightningElementConstructor
+): boolean | undefined {
+    return registeredComponentMap.get(Ctor)?.enableSyntheticElementInternals;
+}
+
 export function getTemplateReactiveObserver(vm: VM): ReactiveObserver {
     const reactiveObserver = createReactiveObserver(() => {
         const { isDirty } = vm;