feat(template-compiler): implement handling for scoped slot directives in template

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

@@ -72,18 +72,25 @@ export interface TransformOptions {
     enableStaticContentOptimization?: boolean;
     customRendererConfig?: CustomRendererConfig;
     enableLwcSpread?: boolean;
+    enableScopedSlots?: boolean;
 }
 
 type RequiredTransformOptions = Omit<
     TransformOptions,
-    'name' | 'namespace' | 'scopedStyles' | 'customRendererConfig' | 'enableLwcSpread'
+    | 'name'
+    | 'namespace'
+    | 'scopedStyles'
+    | 'customRendererConfig'
+    | 'enableLwcSpread'
+    | 'enableScopedSlots'
 >;
 export interface NormalizedTransformOptions extends RecursiveRequired<RequiredTransformOptions> {
     name?: string;
     namespace?: string;
     scopedStyles?: boolean;
     customRendererConfig?: CustomRendererConfig;
     enableLwcSpread?: boolean;
+    enableScopedSlots?: boolean;
 }
 
 export function validateTransformOptions(options: TransformOptions): NormalizedTransformOptions {

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

@@ -33,6 +33,7 @@ export default function templateTransform(
         enableStaticContentOptimization,
         customRendererConfig,
         enableLwcSpread,
+        enableScopedSlots,
     } = options;
     const experimentalDynamicDirective = Boolean(experimentalDynamicComponent);
 
@@ -44,6 +45,7 @@ export default function templateTransform(
             enableStaticContentOptimization,
             customRendererConfig,
             enableLwcSpread,
+            enableScopedSlots,
         });
     } catch (e) {
         throw normalizeToCompilerError(TransformerErrors.HTML_TRANSFORMER_ERROR, e, { filename });

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

@@ -21,12 +21,13 @@ import {
     isUndefined,
     StringReplace,
     toString,
+    ArrayConcat,
 } from '@lwc/shared';
 
 import { logError } from '../shared/logger';
 
 import { invokeEventListener } from './invoker';
-import { getVMBeingRendered } from './template';
+import { getVMBeingRendered, setVMBeingRendered } from './template';
 import { EmptyArray, setRefVNode } from './utils';
 import { isComponentConstructor } from './def';
 import { ShadowMode, SlotSet, VM, RenderMode } from './vm';
@@ -44,6 +45,8 @@ import {
     VStatic,
     Key,
     VFragment,
+    isVScopedSlotContent,
+    VScopedSlotContent,
 } from './vnodes';
 
 const SymbolIterator: typeof Symbol.iterator = Symbol.iterator;
@@ -52,6 +55,19 @@ function addVNodeToChildLWC(vnode: VCustomElement) {
     ArrayPush.call(getVMBeingRendered()!.velements, vnode);
 }
 
+// [s]coped [s]lot [f]actory
+function ssf(factory: (value: any) => VNodes, slotName?: string): VScopedSlotContent {
+    return {
+        type: VNodeType.ScopedSlotContent,
+        factory,
+        owner: getVMBeingRendered()!,
+        elm: undefined,
+        sel: undefined,
+        key: undefined,
+        slotName,
+    };
+}
+
 // [st]atic node
 function st(fragment: Element, key: Key): VStatic {
     return {
@@ -169,10 +185,30 @@ function s(
     }
     if (
         !isUndefined(slotset) &&
-        !isUndefined(slotset[slotName]) &&
-        slotset[slotName].length !== 0
+        !isUndefined(slotset.slotAssignments) &&
+        !isUndefined(slotset.slotAssignments[slotName]) &&
+        slotset.slotAssignments[slotName].length !== 0
     ) {
-        children = slotset[slotName];
+        children = slotset.slotAssignments[slotName].reduce((acc, vnode) => {
+            // If the passed slot content is factory, evaluate it and use the produced vnodes
+            if (vnode && isVScopedSlotContent(vnode)) {
+                const vmBeingRenderedInception = getVMBeingRendered();
+                let children: VNodes = [];
+                if (!isUndefined(slotset.owner)) {
+                    // Evaluate in the scope of the slot content's owner
+                    setVMBeingRendered(slotset.owner);
+                }
+                try {
+                    children = vnode.factory(data.slotData);
+                } finally {
+                    setVMBeingRendered(vmBeingRenderedInception);
+                }
+                return ArrayConcat.call(acc, children);
+            } else {
+                // If the slot content is a static list of child nodes provided by the parent, nothing to do
+                return ArrayConcat.call(acc, vnode);
+            }
+        }, [] as VNodes);
     }
     const vmBeingRendered = getVMBeingRendered()!;
     const { renderMode, shadowMode } = vmBeingRendered;
@@ -571,6 +607,7 @@ const api = ObjectFreeze({
     gid,
     fid,
     shc,
+    ssf,
 });
 
 export default api;

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

@@ -53,6 +53,7 @@ import {
     VNodeType,
     VStatic,
     VFragment,
+    isVScopedSlotContent,
 } from './vnodes';
 
 import { patchAttributes } from './modules/attrs';
@@ -576,7 +577,7 @@ export function allocateChildren(vnode: VCustomElement, vm: VM) {
     const { renderMode, shadowMode } = vm;
     if (shadowMode === ShadowMode.Synthetic || renderMode === RenderMode.Light) {
         // slow path
-        allocateInSlot(vm, children);
+        allocateInSlot(vm, children, vnode.owner);
         // save the allocated children in case this vnode is reused.
         vnode.aChildren = children;
         // every child vnode is now allocated, and the host should receive none directly, it receives them via the shadow!
@@ -611,9 +612,12 @@ function createViewModelHook(elm: HTMLElement, vnode: VCustomElement, renderer:
     return vm;
 }
 
-function allocateInSlot(vm: VM, children: VNodes) {
-    const { cmpSlots: oldSlots } = vm;
-    const cmpSlots = (vm.cmpSlots = create(null));
+function allocateInSlot(vm: VM, children: VNodes, owner: VM) {
+    const {
+        cmpSlots: { slotAssignments: oldSlotsMapping },
+    } = vm;
+    const cmpSlotsMapping = create(null);
+    vm.cmpSlots = { owner, slotAssignments: cmpSlotsMapping };
     for (let i = 0, len = children.length; i < len; i += 1) {
         const vnode = children[i];
         if (isNull(vnode)) {
@@ -622,29 +626,34 @@ function allocateInSlot(vm: VM, children: VNodes) {
 
         let slotName = '';
         if (isVBaseElement(vnode)) {
-            slotName = (vnode.data.attrs?.slot as string) || '';
+            slotName = (vnode.data.attrs?.slot as string) ?? '';
+        } else if (isVScopedSlotContent(vnode)) {
+            slotName = vnode.slotName ?? '';
         }
 
-        const vnodes: VNodes = (cmpSlots[slotName] = cmpSlots[slotName] || []);
+        const vnodes: VNodes = (cmpSlotsMapping[slotName] = cmpSlotsMapping[slotName] || []);
         ArrayPush.call(vnodes, vnode);
     }
     if (isFalse(vm.isDirty)) {
         // We need to determine if the old allocation is really different from the new one
         // and mark the vm as dirty
-        const oldKeys = keys(oldSlots);
-        if (oldKeys.length !== keys(cmpSlots).length) {
+        const oldKeys = keys(oldSlotsMapping);
+        if (oldKeys.length !== keys(cmpSlotsMapping).length) {
             markComponentAsDirty(vm);
             return;
         }
         for (let i = 0, len = oldKeys.length; i < len; i += 1) {
             const key = oldKeys[i];
-            if (isUndefined(cmpSlots[key]) || oldSlots[key].length !== cmpSlots[key].length) {
+            if (
+                isUndefined(cmpSlotsMapping[key]) ||
+                oldSlotsMapping[key].length !== cmpSlotsMapping[key].length
+            ) {
                 markComponentAsDirty(vm);
                 return;
             }
-            const oldVNodes = oldSlots[key];
-            const vnodes = cmpSlots[key];
-            for (let j = 0, a = cmpSlots[key].length; j < a; j += 1) {
+            const oldVNodes = oldSlotsMapping[key];
+            const vnodes = cmpSlotsMapping[key];
+            for (let j = 0, a = cmpSlotsMapping[key].length; j < a; j += 1) {
                 if (oldVNodes[j] !== vnodes[j]) {
                     markComponentAsDirty(vm);
                     return;

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

@@ -77,12 +77,12 @@ function validateSlots(vm: VM, html: Template) {
     const { cmpSlots } = vm;
     const { slots = EmptyArray } = html;
 
-    for (const slotName in cmpSlots) {
+    for (const slotName in cmpSlots.slotAssignments) {
         // eslint-disable-next-line @lwc/lwc-internal/no-production-assert
         assert.isTrue(
-            isArray(cmpSlots[slotName]),
+            isArray(cmpSlots.slotAssignments[slotName]),
             `Slots can only be set to an array, instead received ${toString(
-                cmpSlots[slotName]
+                cmpSlots.slotAssignments[slotName]
             )} for slot "${slotName}" in ${vm}.`
         );
 

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

@@ -50,7 +50,9 @@ export interface TemplateCache {
 }
 
 export interface SlotSet {
-    [key: string]: VNodes;
+    // Slot assignments by name
+    slotAssignments: { [key: string]: VNodes };
+    owner?: VM;
 }
 
 export const enum VMState {
@@ -135,7 +137,8 @@ export interface VM<N = HostNode, E = HostElement> {
     velements: VCustomElement[];
     /** The component public properties. */
     cmpProps: { [name: string]: any };
-    /** The mapping between the slot names and the slotted VNodes. */
+    /** Contains information about the mapping between the slot names and the slotted VNodes, and
+     *  the owner of the slot content. */
     cmpSlots: SlotSet;
     /** The component internal reactive properties. */
     cmpFields: { [name: string]: any };
@@ -301,7 +304,7 @@ export function createVM<HostNode, HostElement>(
         velements: EmptyArray,
         cmpProps: create(null),
         cmpFields: create(null),
-        cmpSlots: create(null),
+        cmpSlots: { slotAssignments: create(null) },
         oar: create(null),
         cmpTemplate: null,
         hydrated: Boolean(hydrated),

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

@@ -17,9 +17,17 @@ export const enum VNodeType {
     CustomElement,
     Static,
     Fragment,
+    ScopedSlotContent,
 }
 
-export type VNode = VText | VComment | VElement | VCustomElement | VStatic | VFragment;
+export type VNode =
+    | VText
+    | VComment
+    | VElement
+    | VCustomElement
+    | VStatic
+    | VFragment
+    | VScopedSlotContent;
 export type VParentElement = VElement | VCustomElement | VFragment;
 export type VNodes = Readonly<Array<VNode | null>>;
 
@@ -35,6 +43,13 @@ export interface BaseVNode {
     owner: VM;
 }
 
+export interface VScopedSlotContent extends BaseVNode {
+    // TODO [#9999]: should the factory return a VFragment instead?
+    factory: (value: any) => VNodes;
+    type: VNodeType.ScopedSlotContent;
+    slotName?: string;
+}
+
 export interface VStatic extends BaseVNode {
     type: VNodeType.Static;
     sel: undefined;
@@ -106,6 +121,7 @@ export interface VElementData extends VNodeData {
     // Similar to above, all props are readonly
     readonly key: Key;
     readonly ref?: string;
+    readonly slotData?: any;
 }
 
 export function isVBaseElement(vnode: VNode): vnode is VElement | VCustomElement {
@@ -120,3 +136,7 @@ export function isSameVnode(vnode1: VNode, vnode2: VNode): boolean {
 export function isVCustomElement(vnode: VBaseElement): vnode is VCustomElement {
     return vnode.type === VNodeType.CustomElement;
 }
+
+export function isVScopedSlotContent(vnode: VNode): vnode is VScopedSlotContent {
+    return vnode.type === VNodeType.ScopedSlotContent;
+}

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: 1167
+ * Next error code: 1179
  */
 
 export * from './compiler';