@lwc/template-compiler 6.2.0 → 6.3.0

package/dist/codegen/codegen.d.ts

@@ -69,10 +69,15 @@ export default class CodeGen {
     genScopedFragId(id: string | t.Expression): t.CallExpression;
     /**
      * Generates childs vnodes when slot content is static.
+     * @param slotName
+     * @param data
+     * @param children
      */
     getSlot(slotName: string, data: t.ObjectExpression, children: t.Expression): import("estree").CallExpression;
     /**
      * Generates a factory function that inturn generates child vnodes for scoped slot content.
+     * @param callback
+     * @param slotName
      */
     getScopedSlotFactory(callback: t.FunctionExpression, slotName: t.Expression | t.SimpleLiteral): import("estree").CallExpression;
     genTabIndex(children: [t.Expression]): import("estree").CallExpression;
@@ -84,9 +89,8 @@ export default class CodeGen {
      * This routine generates an expression that avoids
      * computing the sanitized html of a raw html if it does not change
      * between renders.
-     *
      * @param expr
-     * @returns sanitizedHtmlExpr
+     * @returns The generated expression
      */
     genSanitizedHtmlExpr(expr: t.Expression): import("estree").ConditionalExpression | import("estree").LogicalExpression;
     private _renderApiCall;
@@ -96,12 +100,14 @@ export default class CodeGen {
     declareIdentifier(identifier: t.Identifier): void;
     /**
      * Searches the scopes to find an identifier with a matching name.
+     * @param identifier
      */
     isLocalIdentifier(identifier: t.Identifier): boolean;
     /**
      * Bind the passed expression to the component instance. It applies the following transformation to the expression:
      * - {value} --> {$cmp.value}
      * - {value[index]} --> {$cmp.value[$cmp.index]}
+     * @param expression
      */
     bindExpression(expression: Expression | Literal | ComplexExpression): t.Expression;
     genStaticElement(element: StaticElement, slotParentName?: string): t.Expression;

package/dist/codegen/expression.d.ts

@@ -4,20 +4,22 @@ import type CodeGen from './codegen';
 /**
  * Bind the passed expression to the component instance. It applies the following
  * transformation to the expression:
- *    {value} --> {$cmp.value}
- *    {value[index]} --> {$cmp.value[$cmp.index]}
- *    {foo ?? bar} --> {$cmp.foo ?? $cmp.bar}
- *    {foo?.bar} --> {$cmp.foo?.bar}
+ * - `{value}` --> `{$cmp.value}`
+ * - `{value[index]}` --> `{$cmp.value[$cmp.index]}`
+ * - `{foo ?? bar}` --> `{$cmp.foo ?? $cmp.bar}`
+ * - `{foo?.bar}` --> `{$cmp.foo?.bar}`
  *
  * However, parameter variables are not be transformed in this way. For example,
  * the following transformations do not happen:
- *    {(foo) => foo && bar} -> {(foo) => $cmp.foo && $cmp.bar}
- *    {(foo) => foo && bar} -> {($cmp.foo) => foo && $cmp.bar}
- *    {(foo) => foo && bar} -> {($cmp.foo) => $cmp.foo && $cmp.bar}
+ * - `{(foo) => foo && bar}` --> `{(foo) => $cmp.foo && $cmp.bar}`
+ * - `{(foo) => foo && bar}` --> `{($cmp.foo) => foo && $cmp.bar}`
+ * - `{(foo) => foo && bar}` --> `{($cmp.foo) => $cmp.foo && $cmp.bar}`
  *
  * Instead, the scopes are respected:
- *    {(foo) => foo && $cmp.bar}
+ * - `{(foo) => foo && $cmp.bar}`
  *
  * Similar checks occur for local identifiers introduced via for:each or similar.
+ * @param expression
+ * @param codeGen
  */
 export declare function bindComplexExpression(expression: ComplexExpression, codeGen: CodeGen): t.Expression;

package/dist/codegen/formatters/module.d.ts

@@ -4,7 +4,8 @@ import CodeGen from '../codegen';
  * Generate an ES module AST from a template ESTree AST. The generated module imports the dependent
  * LWC components via import statements and expose the template function via a default export
  * statement.
- *
+ * @param templateFn
+ * @param codeGen
  * @example
  * ```js
  * import { registerTemplate } from 'lwc';

package/dist/codegen/helpers.d.ts

@@ -10,10 +10,13 @@ export declare function objectToAST(obj: object, valueMapper: (key: string) => t
  *
  * This function searches through the children to determine if flattening needs to occur in the runtime.
  * Children should be flattened if they contain an iterator, a dynamic directive or a slot inside a light dom element.
+ * @param codeGen
+ * @param children
  */
 export declare function shouldFlatten(codeGen: CodeGen, children: ChildNode[]): boolean;
 /**
  * Returns true if the AST element or any of its descendants use an id attribute.
+ * @param node
  */
 export declare function hasIdAttribute(node: Node): boolean;
 export declare function memorizeHandler(codeGen: CodeGen, componentHandler: t.Expression, handler: t.Expression): t.Expression;

package/dist/codegen/optimize.d.ts

@@ -29,5 +29,6 @@ import * as t from '../shared/estree';
  *   };
  * }
  * ```
+ * @param templateFn
  */
 export declare function optimizeStaticExpressions(templateFn: t.FunctionDeclaration): Array<t.FunctionDeclaration | t.VariableDeclaration>;

package/dist/config.d.ts

@@ -6,23 +6,24 @@ export interface Config {
      */
     customRendererConfig?: CustomRendererConfig;
     /**
-     * Enable computed member expression in the template. eg:
-     *    <template>
-     *        {list[0].name}
-     *    </template>
+     * Enable computed member expression in the template.
+     * @example
+     * <template>
+     *     {list[0].name}
+     * </template>
      */
     experimentalComputedMemberExpression?: boolean;
     /**
      * Enable use of (a subset of) JavaScript expressions in place of template bindings.
-     *
-     *    <template>
-     *        <input
-     *            attr={complex ?? expressions()}
-     *            onchange={({ target }) => componentMethod(target.value)}
-     *        >
-     *            Hey there {inAustralia ? 'mate' : 'friend'}
-     *        </input>
-     *    </template>
+     * @example
+     * <template>
+     *     <input
+     *         attr={complex ?? expressions()}
+     *         onchange={({ target }) => componentMethod(target.value)}
+     *     >
+     *         Hey there {inAustralia ? 'mate' : 'friend'}
+     *     </input>
+     * </template>
      */
     experimentalComplexExpressions?: boolean;
     /**

package/dist/index.cjs.js

@@ -78,7 +78,7 @@ const DASHED_TAGNAME_ELEMENT_SET = new Set([
 const STATIC_SAFE_DIRECTIVES = new Set(['Ref']);
 
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -102,6 +102,7 @@ function toPropertyName(attr) {
  * Test if given tag name is a custom element.
  * @param tagName element tag name to test
  * @returns true if given tag name represents a custom element, false otherwise.
+ * @example isCustomElementTag("my-component") // true
  */
 function isCustomElementTag(tagName) {
     return tagName.includes('-') && !DASHED_TAGNAME_ELEMENT_SET.has(tagName);
@@ -110,6 +111,7 @@ function isCustomElementTag(tagName) {
  * Test if given tag name is a custom LWC tag denoted lwc:*.
  * @param tagName element tag name to test
  * @returns true if given tag name represents a custom LWC tag, false otherwise.
+ * @example isLwcElementTag("my-component") // false
  */
 function isLwcElementTag(tagName) {
     return tagName.startsWith('lwc:');
@@ -10156,6 +10158,8 @@ class ParserCtx {
     }
     /**
      * This method flattens the scopes into a single array for traversal.
+     * @param element
+     * @yields Each node in the scope and its parent.
      */
     *ancestors(element) {
         const ancestors = this.elementScopes.flat();
@@ -10168,11 +10172,10 @@ class ParserCtx {
      * This method returns an iterator over ancestor nodes, starting at the parent and ending at the root node.
      *
      * Note: There are instances when we want to terminate the traversal early, such as searching for a ForBlock parent.
-     *
-     * @param {ParentNode} startNode - Starting node to begin search, defaults to the tail of the current scope.
-     * @param {function} predicate - This callback is called once for each ancestor until it finds one where predicate returns true.
-     * @param {function} traversalCond - This callback is called after predicate and will terminate the traversal if it returns false.
+     * @param predicate This callback is called once for each ancestor until it finds one where predicate returns true.
+     * @param traversalCond This callback is called after predicate and will terminate the traversal if it returns false.
      * traversalCond is ignored if no value is provided.
+     * @param startNode Starting node to begin search, defaults to the tail of the current scope.
      */
     findAncestor(predicate, traversalCond = () => true, startNode) {
         for (const { current, parent } of this.ancestors(startNode)) {
@@ -10187,8 +10190,7 @@ class ParserCtx {
     }
     /**
      * This method searchs the current scope and returns the value that satisfies the predicate.
-     *
-     * @param {function} predicate - This callback is called once for each sibling in the current scope
+     * @param predicate This callback is called once for each sibling in the current scope
      * until it finds one where predicate returns true.
      */
     findInCurrentElementScope(predicate) {
@@ -10299,8 +10301,7 @@ class ParserCtx {
     /**
      * This method recovers from diagnostic errors that are encountered when fn is invoked.
      * All other errors are considered compiler errors and can not be recovered from.
-     *
-     * @param fn - method to be invoked.
+     * @param fn method to be invoked.
      */
     withErrorRecovery(fn) {
         try {
@@ -10337,18 +10338,28 @@ class ParserCtx {
     }
     /**
      * This method throws a diagnostic error with the node's location.
+     * @param errorInfo
+     * @param node
+     * @param messageArgs
      */
     throwOnNode(errorInfo, node, messageArgs) {
         this.throw(errorInfo, messageArgs, node.location);
     }
     /**
      * This method throws a diagnostic error with location information.
+     * @param errorInfo
+     * @param location
+     * @param messageArgs
      */
     throwAtLocation(errorInfo, location, messageArgs) {
         this.throw(errorInfo, messageArgs, location);
     }
     /**
      * This method throws a diagnostic error and will immediately exit the current routine.
+     * @param errorInfo
+     * @param messageArgs
+     * @param location
+     * @throws
      */
     throw(errorInfo, messageArgs, location) {
         throw errors.generateCompilerError(errorInfo, {
@@ -10360,18 +10371,27 @@ class ParserCtx {
     }
     /**
      * This method logs a diagnostic warning with the node's location.
+     * @param errorInfo
+     * @param node
+     * @param messageArgs
      */
     warnOnNode(errorInfo, node, messageArgs) {
         this.warn(errorInfo, messageArgs, node.location);
     }
     /**
      * This method logs a diagnostic warning with location information.
+     * @param errorInfo
+     * @param location
+     * @param messageArgs
      */
     warnAtLocation(errorInfo, location, messageArgs) {
         this.warn(errorInfo, messageArgs, location);
     }
     /**
      * This method logs a diagnostic warning and will continue execution of the current routine.
+     * @param errorInfo
+     * @param messageArgs
+     * @param location
      */
     warn(errorInfo, messageArgs, location) {
         this.addDiagnostic(errors.generateCompilerDiagnostic(errorInfo, {
@@ -10592,22 +10612,24 @@ function getTrailingChars(str) {
  * This function checks for "unbalanced" extraneous parentheses surrounding the expression.
  *
  * Examples of balanced extraneous parentheses (validation passes):
- *   {(foo.bar)}        <-- the MemberExpressions does not account for the surrounding parens
- *   {(foo())}          <-- the CallExpression does not account for the surrounding parens
- *   {((foo ?? bar)())} <-- the CallExpression does not account for the surrounding parens
+ * - `{(foo.bar)}`        <-- the MemberExpressions does not account for the surrounding parens
+ * - `{(foo())}`          <-- the CallExpression does not account for the surrounding parens
+ * - `{((foo ?? bar)())}` <-- the CallExpression does not account for the surrounding parens
  *
  * Examples of unbalanced extraneous parentheses (validation fails):
- *   {(foo.bar))}       <-- there is an extraneous trailing paren
- *   {foo())}           <-- there is an extraneous trailing paren
+ * - `{(foo.bar))}`       <-- there is an extraneous trailing paren
+ * - `{foo())}`           <-- there is an extraneous trailing paren
  *
  * Examples of no extraneous parentheses (validation passes):
- *   {foo()}            <-- the CallExpression accounts for the trailing paren
- *   {(foo ?? bar).baz} <-- the outer MemberExpression accounts for the leading paren
- *   {(foo).bar}        <-- the outer MemberExpression accounts for the leading paren
+ * - `{foo()}`            <-- the CallExpression accounts for the trailing paren
+ * - `{(foo ?? bar).baz}` <-- the outer MemberExpression accounts for the leading paren
+ * - `{(foo).bar}`        <-- the outer MemberExpression accounts for the leading paren
  *
  * Notably, no examples of extraneous leading parens could be found - these result in a
  * parsing error in Acorn. However, this function still checks, in case there is an
  * unknown expression that would parse with an extraneous leading paren.
+ * @param leadingChars
+ * @param trailingChars
  */
 function validateMatchingExtraParens(leadingChars, trailingChars) {
     const numLeadingParens = leadingChars.split('(').length - 1;
@@ -10619,8 +10641,8 @@ function validateMatchingExtraParens(leadingChars, trailingChars) {
  *
  * Its behavior diverges from that specified in the WHATWG HTML spec
  * in two places:
- *   - 13.2.5.38 - unquoted attribute values
- *   - 13.2.5.1 - the "data" state, which corresponds to parsing outside of tags
+ * - 13.2.5.38 - unquoted attribute values
+ * - 13.2.5.1 - the "data" state, which corresponds to parsing outside of tags
  *
  * Specifically, this tokenizer defers to Acorn's JavaScript parser when
  * encountering a `{` character for an attribute value or within a text
@@ -10684,7 +10706,7 @@ class TemplateHtmlTokenizer extends Tokenizer {
             // coming later in an unquoted attr value should not be considered
             // the beginning of a template expression.
             this.checkedAttrs.add(this.currentAttr);
-            // @ts-ignore
+            // @ts-expect-error private method
             super._stateAttributeValueUnquoted(codePoint);
         }
     }
@@ -10717,7 +10739,7 @@ class TemplateHtmlTokenizer extends Tokenizer {
             this.currentCharacterToken = null;
         }
         else {
-            // @ts-ignore
+            // @ts-expect-error private method
             super._stateData(codePoint);
         }
     }
@@ -10771,11 +10793,9 @@ class TemplateHtmlParser extends Parser {
 /**
  * Parse the LWC template using a customized parser & lexer that allow
  * for template expressions to be parsed correctly.
- *
- * @param      {string}               source  raw template markup
- * @param      {ParseFragmentConfig}  config
- *
- * @return     {DocumentFragment}     the parsed document
+ * @param               source  raw template markup
+ * @param  config
+ * @returns     the parsed document
  */
 function parseFragment(source, config) {
     const { ctx, sourceCodeLocationInfo = true, onParseError } = config;
@@ -11155,6 +11175,7 @@ function isTemplateDirective(attrName) {
 }
 /**
  * Convert attribute name from kebab case to camel case property name
+ * @param attrName
  */
 function attributeToPropertyName(attrName) {
     return ATTRS_PROPS_TRANFORMS[attrName] || toPropertyName(attrName);
@@ -11283,6 +11304,10 @@ function parseRoot(ctx, parse5Elm) {
  *
  * Note: Not every node in the hierarchy is guaranteed to be created, for example,
  * <div></div> will only create an Element node.
+ * @param ctx
+ * @param parse5Elm
+ * @param parentNode
+ * @param parse5ParentLocation
  */
 function parseElement(ctx, parse5Elm, parentNode, parse5ParentLocation) {
     const parse5ElmLocation = parseElementLocation(ctx, parse5Elm, parse5ParentLocation);
@@ -11478,7 +11503,23 @@ function parseText(ctx, parse5Text) {
     }
     // Extract the raw source to avoid HTML entity decoding done by parse5
     const rawText = cleanTextNode(ctx.getSource(location.startOffset, location.endOffset));
-    if (!rawText.trim().length) {
+    /*
+    The original job of this if-block was to discard the whitespace between HTML tags, HTML
+    comments, and HTML tags and HTML comments. The whitespace inside the text content of HTML tags
+    would never be considered here because they would not be parsed into individual text nodes until
+    later (several lines below).
+
+    ["Hello {first} {last}!"] => ["Hello ", "{first}", " ", "{last}", "!"]
+
+    With the implementation of complex template expressions, whitespace that shouldn't be discarded
+    has already been parsed into individual text nodes at this point so we only discard when
+    experimentalComplexExpressions is disabled.
+
+    When removing the experimentalComplexExpressions flag, we need to figure out how to best discard
+    the HTML whitespace while preserving text content whitespace, while also taking into account how
+    comments are sometimes preserved (in which case we need to keep the HTML whitespace).
+    */
+    if (!rawText.trim().length && !ctx.config.experimentalComplexExpressions) {
         return parsedTextNodes;
     }
     // TODO [#3370]: remove experimental template expression flag
@@ -12434,6 +12475,8 @@ function objectToAST(obj, valueMapper) {
  *
  * This function searches through the children to determine if flattening needs to occur in the runtime.
  * Children should be flattened if they contain an iterator, a dynamic directive or a slot inside a light dom element.
+ * @param codeGen
+ * @param children
  */
 function shouldFlatten(codeGen, children) {
     return children.some((child) => {
@@ -12451,6 +12494,7 @@ function shouldFlatten(codeGen, children) {
 }
 /**
  * Returns true if the AST element or any of its descendants use an id attribute.
+ * @param node
  */
 function hasIdAttribute(node) {
     if (isBaseElement(node)) {
@@ -12625,6 +12669,7 @@ const rawContentElements = new Set([
 /**
  * Escape all the characters that could break a JavaScript template string literal: "`" (backtick),
  * "${" (dollar + open curly) and "\" (backslash).
+ * @param str
  */
 function templateStringEscape(str) {
     return str.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
@@ -12730,21 +12775,23 @@ function serializeStaticElement(element, preserveComments) {
 /**
  * Bind the passed expression to the component instance. It applies the following
  * transformation to the expression:
- *    {value} --> {$cmp.value}
- *    {value[index]} --> {$cmp.value[$cmp.index]}
- *    {foo ?? bar} --> {$cmp.foo ?? $cmp.bar}
- *    {foo?.bar} --> {$cmp.foo?.bar}
+ * - `{value}` --> `{$cmp.value}`
+ * - `{value[index]}` --> `{$cmp.value[$cmp.index]}`
+ * - `{foo ?? bar}` --> `{$cmp.foo ?? $cmp.bar}`
+ * - `{foo?.bar}` --> `{$cmp.foo?.bar}`
  *
  * However, parameter variables are not be transformed in this way. For example,
  * the following transformations do not happen:
- *    {(foo) => foo && bar} -> {(foo) => $cmp.foo && $cmp.bar}
- *    {(foo) => foo && bar} -> {($cmp.foo) => foo && $cmp.bar}
- *    {(foo) => foo && bar} -> {($cmp.foo) => $cmp.foo && $cmp.bar}
+ * - `{(foo) => foo && bar}` --> `{(foo) => $cmp.foo && $cmp.bar}`
+ * - `{(foo) => foo && bar}` --> `{($cmp.foo) => foo && $cmp.bar}`
+ * - `{(foo) => foo && bar}` --> `{($cmp.foo) => $cmp.foo && $cmp.bar}`
  *
  * Instead, the scopes are respected:
- *    {(foo) => foo && $cmp.bar}
+ * - `{(foo) => foo && $cmp.bar}`
  *
  * Similar checks occur for local identifiers introduced via for:each or similar.
+ * @param expression
+ * @param codeGen
  */
 function bindComplexExpression(expression, codeGen) {
     const expressionScopes = new ExpressionScopes();
@@ -13008,6 +13055,9 @@ class CodeGen {
     }
     /**
      * Generates childs vnodes when slot content is static.
+     * @param slotName
+     * @param data
+     * @param children
      */
     getSlot(slotName, data, children) {
         this.slotNames.add(slotName);
@@ -13020,6 +13070,8 @@ class CodeGen {
     }
     /**
      * Generates a factory function that inturn generates child vnodes for scoped slot content.
+     * @param callback
+     * @param slotName
      */
     getScopedSlotFactory(callback, slotName) {
         return this._renderApiCall(RENDER_APIS.scopedSlotFactory, [slotName, callback]);
@@ -13053,9 +13105,8 @@ class CodeGen {
      * This routine generates an expression that avoids
      * computing the sanitized html of a raw html if it does not change
      * between renders.
-     *
      * @param expr
-     * @returns sanitizedHtmlExpr
+     * @returns The generated expression
      */
     genSanitizedHtmlExpr(expr) {
         const instance = this.innerHtmlInstances++;
@@ -13105,6 +13156,7 @@ class CodeGen {
     }
     /**
      * Searches the scopes to find an identifier with a matching name.
+     * @param identifier
      */
     isLocalIdentifier(identifier) {
         let scope = this.scope;
@@ -13120,6 +13172,7 @@ class CodeGen {
      * Bind the passed expression to the component instance. It applies the following transformation to the expression:
      * - {value} --> {$cmp.value}
      * - {value[index]} --> {$cmp.value[$cmp.index]}
+     * @param expression
      */
     bindExpression(expression) {
         if (isIdentifier(expression)) {
@@ -13132,6 +13185,9 @@ class CodeGen {
         }
         // TODO [#3370]: remove experimental template expression flag
         if (this.state.config.experimentalComplexExpressions) {
+            // Cloning here is necessary because `this.replace()` is destructive, and we might use the
+            // node later during static content optimization
+            expression = doStructuredClone(expression);
             return bindComplexExpression(expression, this);
         }
         // We need access to both this `this` and the walker's `this` in the walker
@@ -13301,6 +13357,7 @@ function kebabcaseToCamelcase(name) {
  *   };
  * }
  * ```
+ * @param templateFn
  */
 function optimizeStaticExpressions(templateFn) {
     const result = [];
@@ -13383,7 +13440,8 @@ function generateHoistedNodes(codegen) {
  * Generate an ES module AST from a template ESTree AST. The generated module imports the dependent
  * LWC components via import statements and expose the template function via a default export
  * statement.
- *
+ * @param templateFn
+ * @param codeGen
  * @example
  * ```js
  * import { registerTemplate } from 'lwc';
@@ -13562,7 +13620,6 @@ function transform(codeGen) {
     }
     /**
      * Transforms an IfBlock or ElseifBlock along with both its direct descendants and its 'else' descendants.
-     *
      * @param conditionalParentBlock The IfBlock or ElseifBlock to transform into a conditional expression
      * @param key The key to use for this chain of IfBlock/ElseifBlock branches, if applicable
      * @returns A conditional expression representing the full conditional tree with conditionalParentBlock as the root node
@@ -13930,16 +13987,28 @@ function generate (root, state) {
 }
 
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
+/**
+ * Parses HTML markup into an AST
+ * @param source HTML markup to parse
+ * @param config HTML template compilation config
+ * @returns Object containing the AST
+ */
 function parse(source, config = {}) {
     const options = normalizeConfig(config);
     const state = new State$1(options);
     return parse$1(source, state);
 }
+/**
+ * Compiles a LWC template to JavaScript source code consumable by the engine.
+ * @param source HTML markup to compile
+ * @param config HTML template compilation config
+ * @returns Object containing the compiled code and any warnings that occurred.
+ */
 function compile(source, config) {
     const options = normalizeConfig(config);
     const state = new State$1(options);
@@ -13970,5 +14039,5 @@ function compile(source, config) {
 exports.compile = compile;
 exports.default = compile;
 exports.parse = parse;
-/** version: 6.2.0 */
+/** version: 6.3.0 */
 //# sourceMappingURL=index.cjs.js.map