@lwc/template-compiler 6.6.2 → 7.0.0-alpha.0

package/LICENSE.md

@@ -15,7 +15,27 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 ## @parse5/tools
 
-MIT license defined in package.json in v0.4.0.
+The MIT License (MIT)
+
+Copyright © 2024 James Garbutt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
 
 ## entities
 

package/README.md

@@ -13,6 +13,7 @@ yarn add --dev @lwc/template-compiler
 ```js
 import { compile } from '@lwc/template-compiler';
 
+const filename = 'component.html';
 const options = {};
 const { code, warnings } = compile(
     `
@@ -20,6 +21,7 @@ const { code, warnings } = compile(
         <h1>Hello World!</h1>
     </template>
 `,
+    filename,
     options
 );
 
@@ -44,10 +46,13 @@ const { code, warnings } = compile(`<template><h1>Hello World!</h1></template>`,
 **Parameters:**
 
 -   `source` (string, required) - the HTML template source to compile.
+-   `filename` (string, required) - the source filename with extension.
 -   `options` (object, required) - the options to used to compile the HTML template source.
 
 **Options:**
 
+-   `name` (type: `string`, optional, `undefined` by default) - name of the component, e.g. `foo` in `x/foo`.
+-   `namespace` (type: `string`, optional, `undefined` by default) - namespace of the component, e.g. `x` in `x/foo`.
 -   `experimentalComputedMemberExpression` (boolean, optional, `false` by default) - set to `true` to enable computed member expression in the template, eg: `{list[0].name}`.
 -   `experimentalComplexExpressions` (boolean, optional, `false` by default) - set to `true` to enable use of (a subset of) JavaScript expressions in place of template bindings.
 -   `experimentalDynamicDirective` (boolean, optional, `false` by default) - set to `true` to allow the usage of `lwc:dynamic` directives in the template.

package/dist/codegen/codegen.d.ts

@@ -68,6 +68,8 @@ export default class CodeGen {
     genFlatten(children: t.Expression[]): import("estree").CallExpression;
     genScopedId(id: string | t.Expression): t.CallExpression;
     genScopedFragId(id: string | t.Expression): t.CallExpression;
+    genClassExpression(value: Expression): import("estree").Expression;
+    genNormalizeClassName(className: t.Expression): t.CallExpression;
     /**
      * Generates childs vnodes when slot content is static.
      * @param slotName

package/dist/config.d.ts

@@ -1,6 +1,10 @@
 import { InstrumentationObject } from '@lwc/errors';
 import { CustomRendererConfig } from './shared/renderer-hooks';
 export interface Config {
+    /** The name of the component. For example, the name in `<my-component>` is `"component"`. */
+    name?: string;
+    /** The namespace of the component. For example, the namespace in `<my-component>` is `"my"`. */
+    namespace?: string;
     /**
      * Specification to use to determine which nodes in the template require custom renderer hooks.
      */
@@ -61,5 +65,9 @@ export interface Config {
      */
     apiVersion?: number;
 }
-export type NormalizedConfig = Required<Omit<Config, 'customRendererConfig' | 'instrumentation'>> & Partial<Pick<Config, 'customRendererConfig' | 'instrumentation'>>;
+type OptionalConfigNames = 'customRendererConfig' | 'instrumentation' | 'namespace' | 'name';
+type RequiredConfigOptions = Required<Omit<Config, OptionalConfigNames>>;
+type OptionalConfigOptions = Partial<Pick<Config, OptionalConfigNames>>;
+export type NormalizedConfig = RequiredConfigOptions & OptionalConfigOptions;
 export declare function normalizeConfig(config: Config): NormalizedConfig;
+export {};

package/dist/index.cjs.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var errors = require('@lwc/errors');
+var path = require('path');
 var shared = require('@lwc/shared');
 var he = require('he');
 var acorn = require('acorn');
@@ -31,6 +32,70 @@ function _interopNamespaceDefault(e) {
 var he__namespace = /*#__PURE__*/_interopNamespaceDefault(he);
 var astring__namespace = /*#__PURE__*/_interopNamespaceDefault(astring);
 
+/*
+ * 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
+ */
+// The reason this hash code implementation [1] is chosen is because:
+// 1. It has a very low hash collision rate - testing a list of 466,551 English words [2], it generates no collisions
+// 2. It is fast - it can hash those 466k words in 70ms (Node 16, 2020 MacBook Pro)
+// 3. The output size is reasonable (32-bit - this can be base-32 encoded at 10-11 characters)
+//
+// Also note that the reason we're hashing rather than generating a random number is because
+// we want the output to be predictable given the input, which helps with caching.
+//
+// [1]: https://stackoverflow.com/a/52171480
+// [2]: https://github.com/dwyl/english-words/blob/a77cb15f4f5beb59c15b945f2415328a6b33c3b0/words.txt
+function generateHashCode(str) {
+    const seed = 0;
+    let h1 = 0xdeadbeef ^ seed;
+    let h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0, ch; i < str.length; i++) {
+        ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+function escapeScopeToken(input) {
+    // Minimal escape for strings containing the "@" and "#" characters, which are disallowed
+    // in certain cases in attribute names
+    return input.replace(/@/g, '___at___').replace(/#/g, '___hash___');
+}
+function generateScopeTokens(filename, namespace, name) {
+    const uniqueToken = `${namespace}-${name}_${path.basename(filename, path.extname(filename))}`;
+    // This scope token is all lowercase so that it works correctly in case-sensitive namespaces (e.g. SVG).
+    // It is deliberately designed to discourage people from relying on it by appearing somewhat random.
+    // (But not totally random, because it's nice to have stable scope tokens for our own tests.)
+    // Base-32 is chosen because it is not case-sensitive (0-v), and generates short strings with the given hash
+    // code implementation (10-11 characters).
+    const hashCode = generateHashCode(uniqueToken);
+    const scopeToken = `lwc-${hashCode.toString(32)}`;
+    // TODO [#3733]: remove support for legacy scope tokens
+    // This scope token is based on the namespace and name, and contains a mix of uppercase/lowercase chars
+    const legacyScopeToken = escapeScopeToken(uniqueToken);
+    const cssScopeTokens = [
+        scopeToken,
+        `${scopeToken}-host`, // implicit scope token created by `makeHostToken()` in `@lwc/engine-core`
+        // The legacy tokens must be returned as well since we technically don't know what we're going to render
+        // This is not strictly required since this is only used for Jest serialization (as of this writing),
+        // and people are unlikely to set runtime flags in Jest, but it is technically correct to include this.
+        legacyScopeToken,
+        `${legacyScopeToken}-host`,
+    ];
+    return {
+        scopeToken,
+        legacyScopeToken,
+        cssScopeTokens,
+    };
+}
+
 /*
  * Copyright (c) 2018, salesforce.com, inc.
  * All rights reserved.
@@ -38,7 +103,7 @@ var astring__namespace = /*#__PURE__*/_interopNamespaceDefault(astring);
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 let State$1 = class State {
-    constructor(config) {
+    constructor(config, filename) {
         this.config = config;
         this.crElmToConfigMap = config.customRendererConfig
             ? Object.fromEntries(config.customRendererConfig.elements.map((element) => {
@@ -48,6 +113,8 @@ let State$1 = class State {
             : {};
         this.crDirectives = new Set(config.customRendererConfig?.directives);
         this.crCheckedElements = new Map();
+        this.filename = filename;
+        this.scopeTokens = generateScopeTokens(filename, config.namespace, config.name);
     }
 };
 
@@ -56,6 +123,10 @@ const PARSE_FRAGMENT_METHOD_NAME = 'parseFragment';
 const PARSE_SVG_FRAGMENT_METHOD_NAME = 'parseSVGFragment';
 const RENDERER = 'renderer';
 const LWC_MODULE_NAME = 'lwc';
+const FREEZE_TEMPLATE = 'freezeTemplate';
+const IMPLICIT_STYLESHEETS = '_implicitStylesheets';
+const IMPLICIT_SCOPED_STYLESHEETS = '_implicitScopedStylesheets';
+const IMPLICIT_STYLESHEET_IMPORTS = [IMPLICIT_STYLESHEETS, IMPLICIT_SCOPED_STYLESHEETS];
 const TEMPLATE_FUNCTION_NAME = 'tmpl';
 const TEMPLATE_PARAMS = {
     INSTANCE: '$cmp',
@@ -137,6 +208,8 @@ const AVAILABLE_OPTION_NAMES = new Set([
     'enableDynamicComponents',
     'preserveHtmlComments',
     'instrumentation',
+    'namespace',
+    'name',
 ]);
 function normalizeCustomRendererConfig(config) {
     const tagNames = [];
@@ -8826,6 +8899,14 @@ function functionDeclaration(id, params, body, config) {
         ...config,
     };
 }
+function ifStatement(test, consequent, alternate) {
+    return {
+        type: 'IfStatement',
+        test,
+        consequent,
+        alternate,
+    };
+}
 function blockStatement(body, config) {
     return {
         type: 'BlockStatement',
@@ -12792,8 +12873,6 @@ function generateTemplateMetadata(codeGen) {
         const slotsMetadata = assignmentExpression('=', slotsProperty, slotsArray);
         metadataExpressions.push(expressionStatement(slotsMetadata));
     }
-    const stylesheetsMetadata = assignmentExpression('=', memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier('stylesheets')), arrayExpression([]));
-    metadataExpressions.push(expressionStatement(stylesheetsMetadata));
     // ignore when shadow because we don't want to modify template unnecessarily
     if (codeGen.renderMode === exports.LWCDirectiveRenderMode.light) {
         const renderModeMetadata = assignmentExpression('=', memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier('renderMode')), literal$1('light'));
@@ -12803,8 +12882,57 @@ function generateTemplateMetadata(codeGen) {
         const refsMetadata = assignmentExpression('=', memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier('hasRefs')), literal$1(true));
         metadataExpressions.push(expressionStatement(refsMetadata));
     }
+    const stylesheetsMetadata = assignmentExpression('=', memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier('stylesheets')), arrayExpression([]));
+    metadataExpressions.push(expressionStatement(stylesheetsMetadata));
+    const stylesheetTokens = generateStylesheetTokens(codeGen);
+    metadataExpressions.push(...stylesheetTokens);
+    const implicitStylesheetImports = generateImplicitStylesheetImports();
+    metadataExpressions.push(...implicitStylesheetImports);
     return metadataExpressions;
 }
+// Generates conditional statements to insert stylesheets into the
+// tmpl.stylesheets metadata.
+function generateImplicitStylesheetImports() {
+    // tmpl.stylesheets
+    const tmplStylesheetsExpr = memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier('stylesheets'));
+    // tmpl.stylesheets.push.apply
+    const tmplStylesheetPushApplyExpr = memberExpression(memberExpression(tmplStylesheetsExpr, identifier('push')), identifier('apply'));
+    // Generates conditional logic to the imported styleSheet, ex:
+    // if (_implicitStylesheets) {
+    //  tmpl.stylesheets.push.apply(tmpl.stylesheets, _implicitStylesheets);
+    // }
+    const implicitStyleSheets = IMPLICIT_STYLESHEET_IMPORTS.map((styleSheetName) => ifStatement(identifier(styleSheetName), blockStatement([
+        expressionStatement(callExpression(tmplStylesheetPushApplyExpr, [
+            tmplStylesheetsExpr,
+            identifier(styleSheetName),
+        ])),
+    ])));
+    return implicitStyleSheets;
+}
+function generateStylesheetTokens(codeGen) {
+    const { apiVersion, state: { scopeTokens: { scopeToken, legacyScopeToken }, }, } = codeGen;
+    const generateStyleTokenAssignmentExpr = (styleToken, styleTokenName) => {
+        // tmpl.stylesheetToken | tmpl.legacyStylesheetToken
+        const styleTokenExpr = memberExpression(identifier(TEMPLATE_FUNCTION_NAME), identifier(styleToken));
+        return expressionStatement(assignmentExpression('=', styleTokenExpr, literal$1(styleTokenName)));
+    };
+    const styleTokens = [];
+    if (shared.isAPIFeatureEnabled(0 /* APIFeature.LOWERCASE_SCOPE_TOKENS */, apiVersion)) {
+        // Include both the new and legacy tokens, so that the runtime can decide based on a flag whether
+        // we need to render the legacy one. This is designed for cases where the legacy one is required
+        // for backwards compat (e.g. global stylesheets that rely on the legacy format for a CSS selector).
+        // tmpl.stylesheetToken = "{scopeToken}"
+        styleTokens.push(generateStyleTokenAssignmentExpr('stylesheetToken', scopeToken));
+        // tmpl.legacyStylesheetToken = "{legacyScopeToken}"
+        styleTokens.push(generateStyleTokenAssignmentExpr('legacyStylesheetToken', legacyScopeToken));
+    }
+    else {
+        // In old API versions, we can just keep doing what we always did
+        // tmpl.stylesheetToken = "{legacyScopeToken}"
+        styleTokens.push(generateStyleTokenAssignmentExpr('stylesheetToken', legacyScopeToken));
+    }
+    return styleTokens;
+}
 const DECLARATION_DELIMITER = /;(?![^(]*\))/g;
 const PROPERTY_DELIMITER = /:(.+)/;
 // Borrowed from Vue template compiler.
@@ -13355,6 +13483,7 @@ const RENDER_APIS = {
     staticPart: { name: 'sp', alias: 'api_static_part' },
     tabindex: { name: 'ti', alias: 'api_tab_index' },
     text: { name: 't', alias: 'api_text' },
+    normalizeClassName: { name: 'ncls', alias: 'api_normalize_class_name' },
 };
 class CodeGen {
     constructor({ root, state, scopeFragmentId, }) {
@@ -13464,6 +13593,17 @@ class CodeGen {
         }
         return this._renderApiCall(RENDER_APIS.scopedFragId, [id]);
     }
+    genClassExpression(value) {
+        let classExpression = this.bindExpression(value);
+        const isClassNameObjectBindingEnabled = shared.isAPIFeatureEnabled(9 /* APIFeature.TEMPLATE_CLASS_NAME_OBJECT_BINDING */, this.state.config.apiVersion);
+        if (isClassNameObjectBindingEnabled) {
+            classExpression = this.genNormalizeClassName(classExpression);
+        }
+        return classExpression;
+    }
+    genNormalizeClassName(className) {
+        return this._renderApiCall(RENDER_APIS.normalizeClassName, [className]);
+    }
     /**
      * Generates childs vnodes when slot content is static.
      * @param slotName
@@ -13745,7 +13885,7 @@ class CodeGen {
                         }
                         else if (name === 'class') {
                             partToken = `${"c" /* STATIC_PART_TOKEN_ID.CLASS */}${partId}`;
-                            databag.push(property$1(identifier('className'), this.bindExpression(value)));
+                            databag.push(property$1(identifier('className'), this.genClassExpression(value)));
                         }
                         else {
                             partToken = `${"a" /* STATIC_PART_TOKEN_ID.ATTRIBUTE */}${partId}:${name}`;
@@ -13919,13 +14059,21 @@ function generateComponentImports(codeGen) {
     });
 }
 function generateLwcApisImport(codeGen) {
-    const imports = Array.from(codeGen.usedLwcApis)
-        .sort()
-        .map((name) => {
+    // freezeTemplate will always be needed and is called once it has been created.
+    const imports = [...codeGen.usedLwcApis, FREEZE_TEMPLATE].sort().map((name) => {
         return importSpecifier(identifier(name), identifier(name));
     });
     return importDeclaration(imports, literal$1(LWC_MODULE_NAME));
 }
+function generateStylesheetImports(codeGen) {
+    const { state: { filename }, } = codeGen;
+    const relPath = `./${path.basename(filename, path.extname(filename))}`;
+    const imports = IMPLICIT_STYLESHEET_IMPORTS.map((stylesheet) => {
+        const extension = stylesheet === IMPLICIT_STYLESHEETS ? '.css' : '.scoped.css?scoped=true';
+        return importDeclaration([importDefaultSpecifier(identifier(stylesheet))], literal$1(`${relPath}${extension}`));
+    });
+    return imports;
+}
 function generateHoistedNodes(codegen) {
     return codegen.hoistedNodes.map(({ identifier, expr }) => {
         return variableDeclaration('const', [variableDeclarator(identifier, expr)]);
@@ -13953,7 +14101,11 @@ function generateHoistedNodes(codegen) {
  */
 function format(templateFn, codeGen) {
     codeGen.usedLwcApis.add(SECURE_REGISTER_TEMPLATE_METHOD_NAME);
-    const imports = [...generateComponentImports(codeGen), generateLwcApisImport(codeGen)];
+    const imports = [
+        ...generateStylesheetImports(codeGen),
+        ...generateComponentImports(codeGen),
+        generateLwcApisImport(codeGen),
+    ];
     const hoistedNodes = generateHoistedNodes(codeGen);
     const metadata = generateTemplateMetadata(codeGen);
     const optimizedTemplateDeclarations = optimizeStaticExpressions(templateFn);
@@ -13963,7 +14115,15 @@ function format(templateFn, codeGen) {
             identifier(TEMPLATE_FUNCTION_NAME),
         ])),
     ];
-    return program([...imports, ...hoistedNodes, ...templateBody, ...metadata]);
+    const freezeTemplate = expressionStatement(callExpression(identifier(FREEZE_TEMPLATE), [identifier(TEMPLATE_FUNCTION_NAME)]));
+    return program([
+        ...imports,
+        ...hoistedNodes,
+        ...templateBody,
+        ...metadata,
+        // At this point, no more expando props should be added to `tmpl`.
+        freezeTemplate,
+    ]);
 }
 
 /*
@@ -14290,8 +14450,7 @@ function transform(codeGen) {
                     // - string values are parsed and turned into a `classMap` object associating
                     //   each individual class name with a `true` boolean.
                     if (isExpression$1(value)) {
-                        const classExpression = codeGen.bindExpression(value);
-                        data.push(property$1(identifier('className'), classExpression));
+                        data.push(property$1(identifier('className'), codeGen.genClassExpression(value)));
                     }
                     else if (isStringLiteral(value)) {
                         const classNames = parseClassNames(value.value);
@@ -14449,18 +14608,22 @@ function generate (root, state) {
  */
 function parse(source, config = {}) {
     const options = normalizeConfig(config);
-    const state = new State$1(options);
+    // The file name is never used in this function, defaulting it to an empty string.
+    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 filename HTML filename
  * @param config HTML template compilation config
  * @returns Object containing the compiled code and any warnings that occurred.
  */
-function compile(source, config) {
+function compile(source, filename, config) {
     const options = normalizeConfig(config);
-    const state = new State$1(options);
+    // Note the file name is required to generate implicit css imports and style tokens.
+    // It is not part of the config because all values in the config are optional by convention.
+    const state = new State$1(options, filename);
     let code = '';
     let root;
     const warnings = [];
@@ -14478,10 +14641,12 @@ function compile(source, config) {
         diagnostic.message = `Unexpected compilation error: ${diagnostic.message}`;
         warnings.push(diagnostic);
     }
+    const { scopeTokens: { cssScopeTokens }, } = state;
     return {
         code,
         root,
         warnings,
+        cssScopeTokens,
     };
 }
 
@@ -14490,5 +14655,5 @@ exports.default = compile;
 exports.kebabcaseToCamelcase = kebabcaseToCamelcase;
 exports.parse = parse;
 exports.toPropertyName = toPropertyName;
-/** version: 6.6.2 */
+/** version: 7.0.0-alpha.0 */
 //# sourceMappingURL=index.cjs.js.map