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,
+    isVScopedSlotFragment,
+    VScopedSlotFragment,
 } 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(slotName: string, factory: (value: any) => VNodes): VScopedSlotFragment {
+    return {
+        type: VNodeType.ScopedSlotFragment,
+        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 && isVScopedSlotFragment(vnode)) {
+                const vmBeingRenderedInception = getVMBeingRendered();
+                let children: VNodes = [];
+                // Evaluate in the scope of the slot content's owner
+                // if a slotset is provided, there will always be an owner. The only case where owner is
+                // undefined is for root components, but root components cannot accept slotted content
+                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,
+    isVScopedSlotFragment,
 } 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 (isVScopedSlotFragment(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,
+    ScopedSlotFragment,
 }
 
-export type VNode = VText | VComment | VElement | VCustomElement | VStatic | VFragment;
+export type VNode =
+    | VText
+    | VComment
+    | VElement
+    | VCustomElement
+    | VStatic
+    | VFragment
+    | VScopedSlotFragment;
 export type VParentElement = VElement | VCustomElement | VFragment;
 export type VNodes = Readonly<Array<VNode | null>>;
 
@@ -35,6 +43,12 @@ export interface BaseVNode {
     owner: VM;
 }
 
+export interface VScopedSlotFragment extends BaseVNode {
+    factory: (value: any) => VNodes;
+    type: VNodeType.ScopedSlotFragment;
+    slotName: string;
+}
+
 export interface VStatic extends BaseVNode {
     type: VNodeType.Static;
     sel: undefined;
@@ -106,6 +120,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 +135,7 @@ export function isSameVnode(vnode1: VNode, vnode2: VNode): boolean {
 export function isVCustomElement(vnode: VBaseElement): vnode is VCustomElement {
     return vnode.type === VNodeType.CustomElement;
 }
+
+export function isVScopedSlotFragment(vnode: VNode): vnode is VScopedSlotFragment {
+    return vnode.type === VNodeType.ScopedSlotFragment;
+}

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

@@ -34,6 +34,7 @@ async function compileFixture({ input, dirname }: { input: string; dirname: stri
         external: ['lwc'],
         plugins: [
             lwcRollupPlugin({
+                enableScopedSlots: true,
                 modules: [
                     {
                         dir: modulesDir,

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/expected.html

@@ -0,0 +1,11 @@
+<x-basic-parent>
+  <template shadowroot="open">
+    <x-basic-child>
+      <div>
+        <span>
+          99 - ssr
+        </span>
+      </div>
+    </x-basic-child>
+  </template>
+</x-basic-parent>

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/index.js

@@ -0,0 +1,2 @@
+export const tagName = 'x-basic-parent';
+export { default } from 'x/basicParent';

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/modules/x/basicChild/basicChild.html

@@ -0,0 +1,5 @@
+<template lwc:render-mode="light">
+    <div>
+        <slot lwc:slot-bind={item}>Default slot content</slot>
+    </div>
+</template>

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/modules/x/basicChild/basicChild.js

@@ -0,0 +1,6 @@
+import { LightningElement } from 'lwc';
+
+export default class Child extends LightningElement {
+    static renderMode = 'light';
+    item = {id: 99, name: 'ssr'}
+}

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/modules/x/basicParent/basicParent.html

@@ -0,0 +1,7 @@
+<template>
+    <x-basic-child>
+        <template lwc:slot-data="data">
+            <span>{data.id} - {data.name}</span>
+        </template>
+    </x-basic-child>
+</template>

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/basic/modules/x/basicParent/basicParent.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class Parent extends LightningElement {}

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/for-each/expected.html

@@ -0,0 +1,21 @@
+<x-parent-of-child-with-for-each>
+  <template shadowroot="open">
+    <style type="text/css">
+      span {background-color: blue;}
+    </style>
+    <x-child-with-for-each>
+      <ul>
+        <li>
+          <span>
+            39 - Audio
+          </span>
+        </li>
+        <li>
+          <span>
+            40 - Video
+          </span>
+        </li>
+      </ul>
+    </x-child-with-for-each>
+  </template>
+</x-parent-of-child-with-for-each>

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/for-each/index.js

@@ -0,0 +1,2 @@
+export const tagName = 'x-parent-of-child-with-for-each';
+export { default } from 'x/parentOfChildWithForEach';

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/for-each/modules/x/childWithForEach/childWithForEach.html

@@ -0,0 +1,9 @@
+<template lwc:render-mode="light">
+    <ul>
+        <template for:each={items} for:item="item">
+            <li key={item.id}>
+                <slot lwc:slot-bind={item}></slot>
+            </li>
+        </template>
+    </ul>
+</template>

packages/@lwc/engine-server/src/__tests__/fixtures/scoped-slots/for-each/modules/x/childWithForEach/childWithForEach.js

@@ -0,0 +1,9 @@
+import { LightningElement } from 'lwc';
+
+export default class extends LightningElement {
+    static renderMode = 'light';
+    items = [
+        { id: 39, name: 'Audio' },
+        { id: 40, name: 'Video' },
+    ];
+}