feat(template-compiler): dynamic components

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

@@ -11,7 +11,7 @@ export {
     TransformOptions,
     StylesheetConfig,
     CustomPropertiesResolution,
-    DynamicComponentConfig,
+    DynamicImportConfig,
     OutputConfig,
 } from './options';
 

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

@@ -19,7 +19,7 @@ const DEFAULT_OPTIONS = {
     disableSyntheticShadowSupport: false,
 };
 
-const DEFAULT_DYNAMIC_CMP_CONFIG: Required<DynamicComponentConfig> = {
+const DEFAULT_DYNAMIC_IMPORT_CONFIG: Required<DynamicImportConfig> = {
     loader: '',
     strictSpecifier: true,
 };
@@ -56,7 +56,7 @@ export interface OutputConfig {
     minify?: boolean;
 }
 
-export interface DynamicComponentConfig {
+export interface DynamicImportConfig {
     loader?: string;
     strictSpecifier?: boolean;
 }
@@ -65,7 +65,13 @@ export interface TransformOptions {
     name?: string;
     namespace?: string;
     stylesheetConfig?: StylesheetConfig;
-    experimentalDynamicComponent?: DynamicComponentConfig;
+    // TODO [#3331]: deprecate / rename this compiler option in 246
+    /* Config applied in usage of dynamic import statements in javascript */
+    experimentalDynamicComponent?: DynamicImportConfig;
+    /* Flag to enable usage of dynamic component(lwc:dynamic) directive in HTML template */
+    experimentalDynamicDirective?: boolean;
+    /* Flag to enable usage of dynamic component(lwc:is) directive in HTML template */
+    enableDynamicComponents?: boolean;
     outputConfig?: OutputConfig;
     isExplicitImport?: boolean;
     preserveHtmlComments?: boolean;
@@ -85,6 +91,9 @@ type RequiredTransformOptions = Omit<
     | 'customRendererConfig'
     | 'enableLwcSpread'
     | 'enableScopedSlots'
+    | 'enableDynamicComponents'
+    | 'experimentalDynamicDirective'
+    | 'experimentalDynamicComponent'
 >;
 export interface NormalizedTransformOptions extends RecursiveRequired<RequiredTransformOptions> {
     name?: string;
@@ -93,6 +102,9 @@ export interface NormalizedTransformOptions extends RecursiveRequired<RequiredTr
     customRendererConfig?: CustomRendererConfig;
     enableLwcSpread?: boolean;
     enableScopedSlots?: boolean;
+    enableDynamicComponents?: boolean;
+    experimentalDynamicDirective?: boolean;
+    experimentalDynamicComponent?: DynamicImportConfig;
 }
 
 export function validateTransformOptions(options: TransformOptions): NormalizedTransformOptions {
@@ -165,8 +177,8 @@ function normalizeOptions(options: TransformOptions): NormalizedTransformOptions
         },
     };
 
-    const experimentalDynamicComponent: Required<DynamicComponentConfig> = {
-        ...DEFAULT_DYNAMIC_CMP_CONFIG,
+    const experimentalDynamicComponent: Required<DynamicImportConfig> = {
+        ...DEFAULT_DYNAMIC_IMPORT_CONFIG,
         ...options.experimentalDynamicComponent,
     };
 

packages/@lwc/compiler/src/transformers/__tests__/transform-html.spec.ts

@@ -123,4 +123,69 @@ describe('transformSync', () => {
         expect(warnings).toHaveLength(0);
         expect(code).not.toMatch('renderer: renderer');
     });
+
+    describe('dynamic components', () => {
+        it('should allow dynamic components when enableDynamicComponents is set to true', () => {
+            const template = `
+                <template>
+                    <lwc:component lwc:is={ctor}></lwc:component>
+                </template>
+            `;
+            const { code, warnings } = transformSync(template, 'foo.html', {
+                enableDynamicComponents: true,
+                ...TRANSFORMATION_OPTIONS,
+            });
+
+            expect(warnings).toHaveLength(0);
+            expect(code).toContain('api_dynamic_component');
+        });
+
+        it('should not allow dynamic components when enableDynamicComponents is set to false', () => {
+            const template = `
+                <template>
+                    <lwc:component lwc:is={ctor}></lwc:component>
+                </template>
+            `;
+            expect(() =>
+                transformSync(template, 'foo.html', {
+                    enableDynamicComponents: false,
+                    ...TRANSFORMATION_OPTIONS,
+                })
+            ).toThrow('LWC1187: Invalid lwc:is usage');
+        });
+
+        it('should allow deprecated dynamic components when experimentalDynamicDirective is set to true', () => {
+            const template = `
+                <template>
+                    <x-dynamic lwc:dynamic={ctor}></x-dynamic>
+                </template>
+            `;
+            const { code, warnings } = transformSync(template, 'foo.html', {
+                experimentalDynamicDirective: true,
+                ...TRANSFORMATION_OPTIONS,
+            });
+
+            expect(warnings).toHaveLength(1);
+            expect(warnings?.[0]).toMatchObject({
+                message: expect.stringContaining('lwc:dynamic directive is deprecated'),
+            });
+            expect(code).toContain('api_deprecated_dynamic_component');
+        });
+
+        it('should not allow dynamic components when experimentalDynamicDirective is set to false', () => {
+            const template = `
+                <template>
+                    <x-dynamic lwc:dynamic={ctor}></x-dynamic>
+                </template>
+            `;
+            expect(() =>
+                transformSync(template, 'foo.html', {
+                    experimentalDynamicDirective: false,
+                    ...TRANSFORMATION_OPTIONS,
+                })
+            ).toThrowErrorMatchingInlineSnapshot(
+                '"LWC1128: Invalid lwc:dynamic usage. The LWC dynamic directive must be enabled in order to use this feature."'
+            );
+        });
+    });
 });

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

@@ -36,7 +36,7 @@ export default function scriptTransform(
             babelrc: false,
             configFile: false,
 
-            // Force Babel to generate new line and whitespaces. This prevent Babel from generating
+            // Force Babel to generate new line and white spaces. This prevent Babel from generating
             // an error when the generated code is over 500KB.
             compact: false,
 

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

@@ -34,8 +34,11 @@ export default function templateTransform(
         customRendererConfig,
         enableLwcSpread,
         enableScopedSlots,
+        enableDynamicComponents,
+        experimentalDynamicDirective: deprecatedDynamicDirective,
     } = options;
-    const experimentalDynamicDirective = Boolean(experimentalDynamicComponent);
+    const experimentalDynamicDirective =
+        deprecatedDynamicDirective ?? Boolean(experimentalDynamicComponent);
 
     let result;
     try {
@@ -46,6 +49,7 @@ export default function templateTransform(
             customRendererConfig,
             enableLwcSpread,
             enableScopedSlots,
+            enableDynamicComponents,
         });
     } catch (e) {
         throw normalizeToCompilerError(TransformerErrors.HTML_TRANSFORMER_ERROR, e, { filename });

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

@@ -533,9 +533,11 @@ function fid(url: string | undefined | null): string | null | undefined {
 }
 
 /**
- * create a dynamic component via `<x-foo lwc:dynamic={Ctor}>`
+ * [ddc] - create a (deprecated) dynamic component via `<x-foo lwc:dynamic={Ctor}>`
+ *
+ * TODO [#3331]: remove usage of lwc:dynamic in 246
  */
-function dc(
+function ddc(
     sel: string,
     Ctor: LightningElementConstructor | null | undefined,
     data: VElementData,
@@ -550,7 +552,7 @@ function dc(
         );
     }
     // null or undefined values should produce a null value in the VNodes
-    if (Ctor == null) {
+    if (isNull(Ctor) || isUndefined(Ctor)) {
         return null;
     }
     if (!isComponentConstructor(Ctor)) {
@@ -560,6 +562,35 @@ function dc(
     return c(sel, Ctor, data, children);
 }
 
+/**
+ * [dc] - create a dynamic component via `<lwc:component lwc:is={Ctor}>`
+ */
+function dc(
+    Ctor: LightningElementConstructor | null | undefined,
+    data: VElementData,
+    children: VNodes = EmptyArray
+): VCustomElement | null {
+    if (process.env.NODE_ENV !== 'production') {
+        assert.isTrue(isObject(data), `dc() 2nd argument data must be an object.`);
+        assert.isTrue(
+            arguments.length === 3 || isArray(children),
+            `dc() 3rd argument data must be an array.`
+        );
+    }
+    // null or undefined values should produce a null value in the VNodes
+    if (isNull(Ctor) || isUndefined(Ctor)) {
+        return null;
+    }
+
+    if (!isComponentConstructor(Ctor)) {
+        throw new Error(
+            `Invalid constructor ${toString(Ctor)} is not a LightningElement constructor.`
+        );
+    }
+
+    return null;
+}
+
 /**
  * slow children collection marking mechanism. this API allows the compiler to signal
  * to the engine that a particular collection of children must be diffed using the slow
@@ -628,6 +659,7 @@ const api = ObjectFreeze({
     fid,
     shc,
     ssf,
+    ddc,
 });
 
 export default api;

packages/@lwc/engine-server/src/__tests__/fixtures.spec.ts

@@ -8,7 +8,7 @@
 import fs from 'fs';
 import path from 'path';
 
-import { rollup } from 'rollup';
+import { rollup, RollupWarning } from 'rollup';
 // @ts-ignore
 import lwcRollupPlugin from '@lwc/rollup-plugin';
 import { isVoidElement, HTML_NAMESPACE } from '@lwc/shared';
@@ -29,6 +29,8 @@ jest.setTimeout(10_000 /* 10 seconds */);
 async function compileFixture({ input, dirname }: { input: string; dirname: string }) {
     const modulesDir = path.resolve(dirname, './modules');
     const outputFile = path.resolve(dirname, './dist/compiled.js');
+    // TODO [#3331]: this is only needed to silence warnings on lwc:dynamic, remove in 246.
+    const warnings: RollupWarning[] = [];
 
     const bundle = await rollup({
         input,
@@ -43,6 +45,9 @@ async function compileFixture({ input, dirname }: { input: string; dirname: stri
                 ],
             }),
         ],
+        onwarn(warning) {
+            warnings.push(warning);
+        },
     });
 
     await bundle.write({

packages/@lwc/errors/src/compiler/error-info/index.ts

@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 /**
- * Next error code: 1183
+ * Next error code: 1190
  */
 
 export * from './compiler';

packages/@lwc/errors/src/compiler/error-info/template-transform.ts

@@ -471,7 +471,7 @@ export const ParserDiagnostics = {
     INVALID_OPTS_LWC_DYNAMIC: {
         code: 1128,
         message:
-            'Invalid lwc:dynamic usage. The LWC dynamic Directive must be enabled in order to use this feature.',
+            'Invalid lwc:dynamic usage. The LWC dynamic directive must be enabled in order to use this feature.',
         level: DiagnosticLevel.Error,
         url: '',
     },
@@ -548,7 +548,7 @@ export const ParserDiagnostics = {
     LWC_INNER_HTML_INVALID_CUSTOM_ELEMENT: {
         code: 1140,
         message:
-            'Invalid lwc:inner-html usage on element "{0}". The directive can\'t be used on a custom element.',
+            'Invalid lwc:inner-html usage on element "{0}". The directive can\'t be used on a custom element or special LWC managed elements denoted with lwc:*.',
         level: DiagnosticLevel.Error,
         url: '',
     },
@@ -846,4 +846,57 @@ export const ParserDiagnostics = {
         level: DiagnosticLevel.Warning,
         url: '',
     },
+
+    LWC_COMPONENT_TAG_WITHOUT_IS_DIRECTIVE: {
+        code: 1183,
+        message: `<lwc:component> must have an 'lwc:is' attribute.`,
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    UNSUPPORTED_LWC_TAG_NAME: {
+        code: 1184,
+        message: '{0} is not a special LWC tag name and will be treated as an HTML element.',
+        level: DiagnosticLevel.Warning,
+        url: '',
+    },
+
+    INVALID_LWC_IS_DIRECTIVE_VALUE: {
+        code: 1185,
+        message:
+            'Invalid lwc:is usage for value {0}. The value assigned to lwc:is must be an expression.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    LWC_IS_INVALID_ELEMENT: {
+        code: 1186,
+        message:
+            'Invalid lwc:is usage for element {0}. The directive can only be used with <lwc:component>',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_OPTS_LWC_ENABLE_DYNAMIC_COMPONENTS: {
+        code: 1187,
+        message:
+            'Invalid lwc:is usage. The LWC dynamic directive must be enabled in order to use this feature.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    DEPRECATED_LWC_DYNAMIC_ATTRIBUTE: {
+        code: 1188,
+        message: `The lwc:dynamic directive is deprecated and will be removed in a future release. Please use lwc:is instead.`,
+        level: DiagnosticLevel.Warning,
+        url: '',
+    },
+
+    LWC_COMPONENT_USED_WITHOUT_OPT: {
+        code: 1189,
+        message:
+            'The dynamic component option has not been enabled, lwc:component will be treated as an HTML element.',
+        level: DiagnosticLevel.Warning,
+        url: '',
+    },
 };

packages/@lwc/rollup-plugin/README.md

@@ -29,7 +29,9 @@ export default {
 -   `modules` (type: `ModuleRecord[]`, default: `[]`) - The [module resolution](https://lwc.dev/guide/es_modules#module-resolution) overrides passed to the `@lwc/module-resolver`.
 -   `stylesheetConfig` (type: `object`, default: `{}`) - The stylesheet compiler configuration to pass to the `@lwc/style-compiler`.
 -   `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`.
--   `experimentalDynamicComponent` (type: `DynamicComponentConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`.
+-   `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`.
+-   `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components.
+-   `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components.
 -   `enableLwcSpread` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`.
 -   `enableScopedSlots` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable scoped slots feature.
 -   `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller output.