@lwc/template-compiler 6.2.0 → 6.3.0

package/dist/index.d.ts

@@ -3,6 +3,18 @@ import { TemplateCompileResult, TemplateParseResult } from './shared/types';
 export * from './shared/types';
 export { CustomRendererConfig, CustomRendererElementConfig } from './shared/renderer-hooks';
 export { Config } from './config';
+/**
+ * Parses HTML markup into an AST
+ * @param source HTML markup to parse
+ * @param config HTML template compilation config
+ * @returns Object containing the AST
+ */
 export declare function parse(source: string, config?: Config): TemplateParseResult;
 export { compile };
+/**
+ * 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.
+ */
 export default function compile(source: string, config: Config): TemplateCompileResult;

package/dist/index.js

@@ -54,7 +54,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
@@ -78,6 +78,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);
@@ -86,6 +87,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:');
@@ -10132,6 +10134,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();
@@ -10144,11 +10148,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)) {
@@ -10163,8 +10166,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) {
@@ -10275,8 +10277,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 {
@@ -10313,18 +10314,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 generateCompilerError(errorInfo, {
@@ -10336,18 +10347,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(generateCompilerDiagnostic(errorInfo, {
@@ -10568,22 +10588,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;
@@ -10595,8 +10617,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
@@ -10660,7 +10682,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);
         }
     }
@@ -10693,7 +10715,7 @@ class TemplateHtmlTokenizer extends Tokenizer {
             this.currentCharacterToken = null;
         }
         else {
-            // @ts-ignore
+            // @ts-expect-error private method
             super._stateData(codePoint);
         }
     }
@@ -10747,11 +10769,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;
@@ -11131,6 +11151,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);
@@ -11259,6 +11280,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);
@@ -11454,7 +11479,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
@@ -12410,6 +12451,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) => {
@@ -12427,6 +12470,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)) {
@@ -12601,6 +12645,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, '\\${');
@@ -12706,21 +12751,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();
@@ -12984,6 +13031,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);
@@ -12996,6 +13046,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]);
@@ -13029,9 +13081,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++;
@@ -13081,6 +13132,7 @@ class CodeGen {
     }
     /**
      * Searches the scopes to find an identifier with a matching name.
+     * @param identifier
      */
     isLocalIdentifier(identifier) {
         let scope = this.scope;
@@ -13096,6 +13148,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)) {
@@ -13108,6 +13161,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
@@ -13277,6 +13333,7 @@ function kebabcaseToCamelcase(name) {
  *   };
  * }
  * ```
+ * @param templateFn
  */
 function optimizeStaticExpressions(templateFn) {
     const result = [];
@@ -13359,7 +13416,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';
@@ -13538,7 +13596,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
@@ -13906,16 +13963,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);
@@ -13944,5 +14013,5 @@ function compile(source, config) {
 }
 
 export { ElementDirectiveName, LWCDirectiveDomMode, LWCDirectiveRenderMode, LwcTagName, RootDirectiveName, TemplateDirectiveName, compile, compile as default, parse };
-/** version: 6.2.0 */
+/** version: 6.3.0 */
 //# sourceMappingURL=index.js.map