chore: comments and some light cleanup

Author: divmain

packages/@lwc/ssr-compiler/src/compile-template/context.ts

@@ -43,6 +43,8 @@ export function createNewContext(templateOptions: TemplateOpts): {
     const previouslyHoistedStatementKeysTmpl = new Set<unknown>();
 
     const hoist = {
+        // Anything added here will be inserted at the top of the compiled template's
+        // JS module.
         module(stmt: EsStatement, optionalDedupeKey?: unknown) {
             if (optionalDedupeKey) {
                 if (previouslyHoistedStatementKeysMod.has(optionalDedupeKey)) {
@@ -52,6 +54,8 @@ export function createNewContext(templateOptions: TemplateOpts): {
             }
             hoistedStatements.module.push(stmt);
         },
+        // Anything added here will be inserted at the top of the JavaScript function
+        // corresponding to the template (typically named `__lwcTmpl`).
         templateFn(stmt: EsStatement, optionalDedupeKey?: unknown) {
             if (optionalDedupeKey) {
                 if (previouslyHoistedStatementKeysTmpl.has(optionalDedupeKey)) {
@@ -66,6 +70,10 @@ export function createNewContext(templateOptions: TemplateOpts): {
     const shadowSlotToFnName = new Map<string, string>();
     let fnNameUniqueId = 0;
 
+    // At present, we only track shadow-slotted content. This is because the functions
+    // corresponding to shadow-slotted content are deduped and hoisted to the top of
+    // the template function, whereas light-dom-slotted content is inlined. It may be
+    // desirable to also track light-dom-slotted content at some future point in time.
     const slots = {
         shadow: {
             isDuplicate(uniqueNodeId: string) {

packages/@lwc/ssr-compiler/src/compile-template/index.ts

@@ -126,7 +126,14 @@ export default function compileTemplate(
     }
 
     let tmplDecl = bExportTemplate(
-        optimizeAdjacentYieldStmts([...cxt.hoistedStatements.templateFn, ...statements])
+        optimizeAdjacentYieldStmts([
+            // Deep in the compiler, we may choose to hoist statements and declarations
+            // to the top of the template function. After `templateIrToEsTree`, these
+            // hoisted statements/declarations are prepended to the template function's
+            // body.
+            ...cxt.hoistedStatements.templateFn,
+            ...statements,
+        ])
     );
     // Ideally, we'd just do ${LWC_VERSION_COMMENT} in the code template,
     // but placeholders have a special meaning for `esTemplate`.
@@ -139,7 +146,18 @@ export default function compileTemplate(
         ];
     });
 
-    let program = b.program([...getImports(), ...cxt.hoistedStatements.module, tmplDecl], 'module');
+    let program = b.program(
+        [
+            // All import declarations come first...
+            ...getImports(),
+            // ... followed by any statements or declarations that need to be hoisted
+            // to the top of the module scope...
+            ...cxt.hoistedStatements.module,
+            // ... followed by the template function declaration itself.
+            tmplDecl,
+        ],
+        'module'
+    );
 
     addScopeTokenDeclarations(program, filename, options.namespace, options.name);
 

packages/@lwc/ssr-compiler/src/compile-template/transformers/component/slotted-content.ts

@@ -39,6 +39,10 @@ import type {
 } from '@lwc/template-compiler';
 import type { TransformerContext } from '../../types';
 
+// This function will be defined once and hoisted to the top of the template function. It'll be
+// referenced deeper in the call stack where the function is called or passed as a parameter.
+// It is a higher-order function that curries local variables that may be referenced by the
+// shadow slot content.
 const bGenerateShadowSlottedContent = esTemplateWithYield`
     const ${/* function name */ is.identifier} = (${/* local vars */ is.identifier}) => async function* ${/* function name */ 0}(contextfulParent) {
         // The 'contextfulParent' variable is shadowed here so that a contextful relationship
@@ -47,17 +51,20 @@ const bGenerateShadowSlottedContent = esTemplateWithYield`
         ${/* shadow slot content */ is.statement}
     };
 `<EsVariableDeclaration>;
+// By passing in the set of local variables (which correspond 1:1 to the variables expected by
+// the referenced function), `shadowSlottedContent` will be curried function that can generate
+// shadow-slotted content.
 const bGenerateShadowSlottedContentRef = esTemplateWithYield`
     const shadowSlottedContent = ${/* reference to hoisted fn */ is.identifier}(${/* local vars */ is.identifier});
 `<EsVariableDeclaration>;
 const bNullishGenerateShadowSlottedContent = esTemplateWithYield`
     const shadowSlottedContent = null;
 `<EsVariableDeclaration>;
 
-const bContentMap = esTemplateWithYield`
+const blightSlottedContentMap = esTemplateWithYield`
     const ${/* name of the content map */ is.identifier} = Object.create(null);
 `<EsVariableDeclaration>;
-const bNullishContentMap = esTemplateWithYield`
+const bNullishLightSlottedContentMap = esTemplateWithYield`
     const ${/* name of the content map */ is.identifier} = null;
 `<EsVariableDeclaration>;
 
@@ -298,11 +305,11 @@ export function getSlottedContent(
           )
         : bNullishGenerateShadowSlottedContent();
     const lightSlottedContentMap = hasLightSlottedContent
-        ? bContentMap(b.identifier('lightSlottedContentMap'))
-        : bNullishContentMap(b.identifier('lightSlottedContentMap'));
+        ? blightSlottedContentMap(b.identifier('lightSlottedContentMap'))
+        : bNullishLightSlottedContentMap(b.identifier('lightSlottedContentMap'));
     const scopedSlottedContentMap = hasScopedSlottedContent
-        ? bContentMap(b.identifier('scopedSlottedContentMap'))
-        : bNullishContentMap(b.identifier('scopedSlottedContentMap'));
+        ? blightSlottedContentMap(b.identifier('scopedSlottedContentMap'))
+        : bNullishLightSlottedContentMap(b.identifier('scopedSlottedContentMap'));
 
     return bGenerateSlottedContent(
         shadowSlottedContentFn,