@stencil/core 2.14.0 → 2.15.0

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.14.0 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.15.0 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -1599,6 +1599,12 @@ const createJsVarName = (fileName) => {
   }
   return fileName;
 };
+/**
+ * Determines if a given file path points to a type declaration file (ending in .d.ts) or not. This function is
+ * case-insensitive in its heuristics.
+ * @param filePath the path to check
+ * @returns `true` if the given `filePath` points to a type declaration file, `false` otherwise
+ */
 const isDtsFile$1 = (filePath) => {
   const parts = filePath.toLowerCase().split('.');
   if (parts.length > 2) {
@@ -3967,7 +3973,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220214175725';
+const buildId = '20220328165835';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.8_7';
 const parse5Version = '6.0.1';
@@ -3975,8 +3981,8 @@ const rollupVersion = '2.42.3';
 const sizzleVersion = '2.42.3';
 const terserVersion = '5.6.1';
 const typescriptVersion = '4.5.4';
-const vermoji = '💫';
-const version$3 = '2.14.0';
+const vermoji = '⛷';
+const version$3 = '2.15.0';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -40941,9 +40947,24 @@ const createComponentExport = (cmp) => {
   return `export { ${originalClassName} as ${underscoredClassName} } from '${filePath}';`;
 };
 
+/**
+ * Rollup plugin that aids in resolving the entry points (1 or more files) for a Stencil project. For example, a project
+ * using the `dist-custom-elements` output target may have a single 'entry point' for each file containing a component.
+ * Each of those files will be independently resolved and loaded by this plugin for further processing by Rollup later
+ * in the bundling process.
+ * @param entries the Stencil project files to process. It should be noted that the keys in this object may not
+ * necessarily be an absolute or relative path to a file, but may be a Rollup Virtual Module (which begin with \0).
+ * @returns the rollup plugin that loads and process a Stencil project's entry points
+ */
 const loaderPlugin = (entries = {}) => {
   return {
     name: 'stencilLoaderPlugin',
+    /**
+     * A rollup build hook for resolving the imports of individual Stencil project files. This hook only resolves
+     * modules that are contained in the plugin's `entries` argument. [Source](https://rollupjs.org/guide/en/#resolveid)
+     * @param id the importee to resolve
+     * @returns a string that resolves an import to some id, null otherwise
+     */
     resolveId(id) {
       if (id in entries) {
         return {
@@ -40952,6 +40973,12 @@ const loaderPlugin = (entries = {}) => {
       }
       return null;
     },
+    /**
+     * A rollup build hook for loading individual Stencil project files [Source](https://rollupjs.org/guide/en/#load)
+     * @param id the path of the module to load. It should be noted that the keys in this object may not necessarily
+     * be an absolute or relative path to a file, but may be a Rollup Virtual Module.
+     * @returns the module matched, null otherwise
+     */
     load(id) {
       if (id in entries) {
         return entries[id];
@@ -41569,9 +41596,22 @@ const getTsResolveExtension = (p) => {
 };
 const shouldPatchRemoteTypeScript = (compilerExe) => !IS_NODE_ENV && isRemoteUrl(compilerExe);
 
+/**
+ * Rollup plugin that aids in resolving the TypeScript files and performing the transpilation step.
+ * @param compilerCtx the current compiler context
+ * @param bundleOpts Rollup bundling options to apply during TypeScript compilation
+ * @param config the Stencil configuration for the project
+ * @returns the rollup plugin for handling TypeScript files.
+ */
 const typescriptPlugin = (compilerCtx, bundleOpts, config) => {
   return {
     name: `${bundleOpts.id}TypescriptPlugin`,
+    /**
+     * A rollup build hook for loading TypeScript files and their associated source maps (if they exist).
+     * [Source](https://rollupjs.org/guide/en/#load)
+     * @param id the path of the file to load
+     * @returns the module matched (with its sourcemap if it exists), null otherwise
+     */
     load(id) {
       if (isAbsolute$1(id)) {
         const fsFilePath = normalizeFsPath(id);
@@ -41587,6 +41627,13 @@ const typescriptPlugin = (compilerCtx, bundleOpts, config) => {
       }
       return null;
     },
+    /**
+     * Performs TypeScript compilation/transpilation, including applying any transformations against the Abstract Syntax
+     * Tree (AST) specific to stencil
+     * @param _code the code to modify, unused
+     * @param id module's identifier
+     * @returns the transpiled code, with its associated sourcemap. null otherwise
+     */
     transform(_code, id) {
       if (isAbsolute$1(id)) {
         const fsFilePath = normalizeFsPath(id);
@@ -53750,6 +53797,14 @@ const bundleOutput = async (config, compilerCtx, buildCtx, bundleOpts) => {
   }
   return undefined;
 };
+/**
+ * Build the rollup options that will be used to transpile, minify, and otherwise transform a Stencil project
+ * @param config the Stencil configuration for the project
+ * @param compilerCtx the current compiler context
+ * @param buildCtx a context object containing information about the current build
+ * @param bundleOpts Rollup bundling options to apply to the base configuration setup by this function
+ * @returns the rollup options to be used
+ */
 const getRollupOptions = (config, compilerCtx, buildCtx, bundleOpts) => {
   var _a;
   const customResolveOptions = createCustomResolverAsync(config.sys, compilerCtx.fs, [
@@ -54554,11 +54609,46 @@ const addModuleMetadataProxies = (tsSourceFile, moduleFile) => {
 const addComponentMetadataProxy = (compilerMeta) => {
   return t.createStatement(createComponentMetadataProxy(compilerMeta));
 };
+/**
+ * Create a call expression for wrapping a component in a proxy. This call expression takes a form:
+ * ```ts
+ * PROXY_CUSTOM_ELEMENT(ComponentClassName, Metadata);
+ * ```
+ * where
+ * - `PROXY_CUSTOM_ELEMENT` is a Stencil internal identifier that will be replaced with the name of the actual function
+ * name at compile name
+ * - `ComponentClassName` is the name Stencil component's class
+ * - `Metadata` is the compiler metadata associated with the Stencil component
+ *
+ * @param compilerMeta compiler metadata associated with the component to be wrapped in a proxy
+ * @returns the generated call expression
+ */
 const createComponentMetadataProxy = (compilerMeta) => {
   const compactMeta = formatComponentRuntimeMeta(compilerMeta, true);
-  const literalCmpClassName = t.createIdentifier(compilerMeta.componentClassName);
+  const literalCmpClassName = t.factory.createIdentifier(compilerMeta.componentClassName);
+  const literalMeta = convertValueToLiteral(compactMeta);
+  return t.factory.createCallExpression(t.factory.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [literalCmpClassName, literalMeta]);
+};
+/**
+ * Create a call expression for wrapping a component represented as an anonymous class in a proxy. This call expression
+ * takes a form:
+ * ```ts
+ * PROXY_CUSTOM_ELEMENT(Clazz, Metadata);
+ * ```
+ * where
+ * - `PROXY_CUSTOM_ELEMENT` is a Stencil internal identifier that will be replaced with the name of the actual function
+ * name at compile name
+ * - `Clazz` is an anonymous class to be proxied
+ * - `Metadata` is the compiler metadata associated with the Stencil component
+ *
+ * @param compilerMeta compiler metadata associated with the component to be wrapped in a proxy
+ * @param clazz the anonymous class to proxy
+ * @returns the generated call expression
+ */
+const createAnonymousClassMetadataProxy = (compilerMeta, clazz) => {
+  const compactMeta = formatComponentRuntimeMeta(compilerMeta, true);
   const literalMeta = convertValueToLiteral(compactMeta);
-  return t.createCall(t.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [literalCmpClassName, literalMeta]);
+  return t.factory.createCallExpression(t.factory.createIdentifier(PROXY_CUSTOM_ELEMENT), [], [clazz, literalMeta]);
 };
 
 const defineCustomElement = (tsSourceFile, moduleFile, transformOpts) => {
@@ -54833,7 +54923,7 @@ const createConstClass = (transformOpts, classNode, heritageClauses, members) =>
   }
   return t.createVariableStatement(constModifiers, t.createVariableDeclarationList([
     t.createVariableDeclaration(className, undefined, t.createClassExpression(classModifiers, undefined, classNode.typeParameters, heritageClauses, members)),
-  ], t.NodeFlags.Let));
+  ], t.NodeFlags.Const));
 };
 
 const addCreateEvents = (moduleFile, cmp) => {
@@ -55114,16 +55204,9 @@ const addDefineCustomElementFunctions = (compilerCtx, components, outputTarget)
       const newStatements = [];
       const caseStatements = [];
       const tagNames = [];
-      addCoreRuntimeApi(moduleFile, RUNTIME_APIS.proxyCustomElement);
       if (moduleFile.cmps.length) {
         const principalComponent = moduleFile.cmps[0];
         tagNames.push(principalComponent.tagName);
-        // wraps the initial component class in a `proxyCustomElement` wrapper.
-        // This is what will be exported and called from the `defineCustomElement` call.
-        const proxyDefinition = createComponentMetadataProxy(principalComponent);
-        const metaExpression = t.factory.createExpressionStatement(t.factory.createBinaryExpression(t.factory.createIdentifier(principalComponent.componentClassName), t.factory.createToken(t.SyntaxKind.EqualsToken), proxyDefinition));
-        newStatements.push(metaExpression);
-        t.addSyntheticLeadingComment(proxyDefinition, t.SyntaxKind.MultiLineCommentTrivia, '@__PURE__', false);
         // define the current component - `customElements.define(tagName, MyProxiedComponent);`
         const customElementsDefineCallExpression = t.factory.createCallExpression(t.factory.createPropertyAccessExpression(t.factory.createIdentifier('customElements'), 'define'), undefined, [t.factory.createIdentifier('tagName'), t.factory.createIdentifier(principalComponent.componentClassName)]);
         // create a `case` block that defines the current component. We'll add them to our switch statement later.
@@ -55240,6 +55323,71 @@ function createAutoDefinitionExpression(componentName) {
   ]));
 }
 
+/**
+ * Proxy custom elements for the `dist-custom-elements` output target. This function searches for a Stencil component's
+ * class initializer (found on the righthand side of the '=' operator):
+ *
+ * ```ts
+ * const MyComponent = class extends HTMLElement { // Implementation omitted }
+ * ```
+ *
+ * and wraps the initializer into a `proxyCustomElement` call:
+ *
+ * ```ts
+ * const MyComponent = proxyCustomElement(class extends HTMLElement { // Implementation omitted }, componentMetadata);
+ * ```
+ *
+ * This is to work around an issue where treeshaking does not work for webpack users, whose details are captured in full
+ * in [this issue on the webpack GitHub repo](https://github.com/webpack/webpack/issues/14963).
+ *
+ * @param compilerCtx current compiler context
+ * @param transformOpts transpilation options for the current build
+ * @returns a TypeScript AST transformer factory function that performs the above described transformation
+ */
+const proxyCustomElement = (compilerCtx, transformOpts) => {
+  return () => {
+    return (tsSourceFile) => {
+      const moduleFile = getModuleFromSourceFile(compilerCtx, tsSourceFile);
+      if (!moduleFile.cmps.length) {
+        return tsSourceFile;
+      }
+      const principalComponent = moduleFile.cmps[0];
+      for (let [stmtIndex, stmt] of tsSourceFile.statements.entries()) {
+        if (t.isVariableStatement(stmt)) {
+          for (let [declarationIndex, declaration] of stmt.declarationList.declarations.entries()) {
+            if (declaration.name.getText() !== principalComponent.componentClassName) {
+              continue;
+            }
+            // wrap the Stencil component's class declaration in a component proxy
+            const proxyCreationCall = createAnonymousClassMetadataProxy(principalComponent, declaration.initializer);
+            t.addSyntheticLeadingComment(proxyCreationCall, t.SyntaxKind.MultiLineCommentTrivia, '@__PURE__', false);
+            // update the component's variable declaration to use the new initializer
+            const proxiedComponentDeclaration = t.factory.updateVariableDeclaration(declaration, declaration.name, declaration.exclamationToken, declaration.type, proxyCreationCall);
+            // update the declaration list that contains the updated variable declaration
+            const updatedDeclarationList = t.factory.updateVariableDeclarationList(stmt.declarationList, [
+              ...stmt.declarationList.declarations.slice(0, declarationIndex),
+              proxiedComponentDeclaration,
+              ...stmt.declarationList.declarations.slice(declarationIndex + 1),
+            ]);
+            // update the variable statement containing the updated declaration list
+            const updatedVariableStatement = t.factory.updateVariableStatement(stmt, [t.factory.createModifier(t.SyntaxKind.ExportKeyword)], updatedDeclarationList);
+            // update the source file's statements to use the new variable statement
+            tsSourceFile = t.factory.updateSourceFile(tsSourceFile, [
+              ...tsSourceFile.statements.slice(0, stmtIndex),
+              updatedVariableStatement,
+              ...tsSourceFile.statements.slice(stmtIndex + 1),
+            ]);
+            // finally, ensure that the proxyCustomElement function is imported
+            tsSourceFile = addImports(transformOpts, tsSourceFile, [RUNTIME_APIS.proxyCustomElement], transformOpts.coreImportPath);
+            return tsSourceFile;
+          }
+        }
+      }
+      return tsSourceFile;
+    };
+  };
+};
+
 const updateStencilCoreImports = (updatedCoreImportPath) => {
   return () => {
     return (tsSourceFile) => {
@@ -55314,19 +55462,19 @@ const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarge
       id: 'customElements',
       platform: 'client',
       conditionals: getCustomElementsBuildConditionals(config, buildCtx.components),
-      customTransformers: getCustomElementBundleCustomTransformer$1(config, compilerCtx, buildCtx.components, outputTarget),
+      customTransformers: getCustomElementCustomTransformer(config, compilerCtx, buildCtx.components, outputTarget),
       externalRuntime: !!outputTarget.externalRuntime,
       inlineWorkers: true,
       inputs: {
         index: '\0core',
       },
       loader: {
-        '\0core': generateEntryPoint$1(outputTarget, buildCtx),
+        '\0core': generateEntryPoint$1(outputTarget),
       },
       inlineDynamicImports: outputTarget.inlineDynamicImports,
       preserveEntrySignatures: 'allow-extension',
     };
-    addCustomElementInputs(outputTarget, buildCtx, bundleOpts);
+    addCustomElementInputs(buildCtx, bundleOpts);
     const build = await bundleOutput(config, compilerCtx, buildCtx, bundleOpts);
     if (build) {
       const rollupOutput = await build.generate({
@@ -55372,7 +55520,12 @@ const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarge
     catchError(buildCtx.diagnostics, e);
   }
 };
-const addCustomElementInputs = (_outputTarget, buildCtx, bundleOpts) => {
+/**
+ * Create the virtual modules/input modules for the `dist-custom-elements` output target.
+ * @param buildCtx the context for the current build
+ * @param bundleOpts the bundle options to store the virtual modules under. acts as an output parameter
+ */
+const addCustomElementInputs = (buildCtx, bundleOpts) => {
   const components = buildCtx.components;
   components.forEach((cmp) => {
     const exp = [];
@@ -55384,6 +55537,7 @@ const addCustomElementInputs = (_outputTarget, buildCtx, bundleOpts) => {
       exp.push(`export { ${importName} as ${exportName} } from '${cmp.sourceFilePath}';`);
     }
     else {
+      // the `importName` may collide with the `exportName`, alias it just in case it does with `importAs`
       exp.push(`import { ${importName} as ${importAs}, defineCustomElement as cmpDefCustomEle } from '${cmp.sourceFilePath}';`);
       exp.push(`export const ${exportName} = ${importAs};`);
       exp.push(`export const defineCustomElement = cmpDefCustomEle;`);
@@ -55392,16 +55546,29 @@ const addCustomElementInputs = (_outputTarget, buildCtx, bundleOpts) => {
     bundleOpts.loader[coreKey] = exp.join('\n');
   });
 };
-const generateEntryPoint$1 = (outputTarget, _buildCtx) => {
+/**
+ * Generate the entrypoint (`index.ts` file) contents for the `dist-custom-elements` output target
+ * @param outputTarget the output target's configuration
+ * @returns the stringified contents to be placed in the entrypoint
+ */
+const generateEntryPoint$1 = (outputTarget) => {
   const imp = [];
-  const exp = [];
   imp.push(`export { setAssetPath, setPlatformOptions } from '${STENCIL_INTERNAL_CLIENT_ID}';`, `export * from '${USER_INDEX_ENTRY_ID}';`);
   if (outputTarget.includeGlobalScripts !== false) {
     imp.push(`import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';`, `globalScripts();`);
   }
-  return [...imp, ...exp].join('\n') + '\n';
+  return imp.join('\n') + '\n';
 };
-const getCustomElementBundleCustomTransformer$1 = (config, compilerCtx, components, outputTarget) => {
+/**
+ * Get the series of custom transformers that will be applied to a Stencil project's source code during the TypeScript
+ * transpilation process
+ * @param config the configuration for the Stencil project
+ * @param compilerCtx the current compiler context
+ * @param components the components that will be compiled as a part of the current build
+ * @param outputTarget the output target configuration
+ * @returns a list of transformers to use in the transpilation process
+ */
+const getCustomElementCustomTransformer = (config, compilerCtx, components, outputTarget) => {
   const transformOpts = {
     coreImportPath: STENCIL_INTERNAL_CLIENT_ID,
     componentExport: null,
@@ -55415,6 +55582,7 @@ const getCustomElementBundleCustomTransformer$1 = (config, compilerCtx, componen
     addDefineCustomElementFunctions(compilerCtx, components, outputTarget),
     updateStencilCoreImports(transformOpts.coreImportPath),
     nativeComponentTransform(compilerCtx, transformOpts),
+    proxyCustomElement(compilerCtx, transformOpts),
     removeCollectionImports(compilerCtx),
   ];
 };
@@ -58675,8 +58843,18 @@ const serializeCollectionDependencies = (compilerCtx) => {
   return sortBy(collectionDeps, (item) => item.name);
 };
 
+/**
+ * Update a type declaration file's import declarations using the module `@stencil/core`
+ * @param typesDir the directory where type declaration files are expected to exist
+ * @param dtsFilePath the path of the type declaration file being updated, used to derive the correct import declaration
+ * module
+ * @param dtsContent the content of a type declaration file to update
+ * @returns the updated type declaration file contents
+ */
 const updateStencilTypesImports = (typesDir, dtsFilePath, dtsContent) => {
   const dir = dirname(dtsFilePath);
+  // determine the relative path between the directory of the .d.ts file and the types directory. this value may result
+  // in '.' if they are the same
   const relPath = relative$1(dir, typesDir);
   let coreDtsPath = join(relPath, CORE_FILENAME);
   if (!coreDtsPath.startsWith('.')) {
@@ -58689,6 +58867,12 @@ const updateStencilTypesImports = (typesDir, dtsFilePath, dtsContent) => {
   }
   return dtsContent;
 };
+/**
+ * Writes Stencil core typings file to disk for a dist-* output target
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @returns
+ */
 const copyStencilCoreDts = async (config, compilerCtx) => {
   const typesOutputTargets = config.outputTargets.filter(isOutputTargetDistTypes).filter((o) => o.typesDir);
   const srcStencilDtsPath = join(config.sys.getCompilerExecutingPath(), '..', '..', 'internal', CORE_DTS);
@@ -58771,21 +58955,21 @@ const generatePropTypes = (cmpMeta) => {
 };
 
 /**
- * Generate a string based on the types that are defined within a component.
- *
+ * Generate a string based on the types that are defined within a component
  * @param cmp the metadata for the component that a type definition string is generated for
- * @param importPath the path of the component file
+ * @param areTypesInternal `true` if types being generated are for a project's internal purposes, `false` otherwise
+ * @returns the generated types string alongside additional metadata
  */
-const generateComponentTypes = (cmp, internal) => {
+const generateComponentTypes = (cmp, areTypesInternal) => {
   const tagName = cmp.tagName.toLowerCase();
   const tagNameAsPascal = dashToPascalCase$1(tagName);
   const htmlElementName = `HTML${tagNameAsPascal}Element`;
   const propAttributes = generatePropTypes(cmp);
   const methodAttributes = generateMethodTypes(cmp.methods);
   const eventAttributes = generateEventTypes(cmp.events);
-  const componentAttributes = attributesToMultiLineString([...propAttributes, ...methodAttributes], false, internal);
+  const componentAttributes = attributesToMultiLineString([...propAttributes, ...methodAttributes], false, areTypesInternal);
   const isDep = cmp.isCollectionDependency;
-  const jsxAttributes = attributesToMultiLineString([...propAttributes, ...eventAttributes], true, internal);
+  const jsxAttributes = attributesToMultiLineString([...propAttributes, ...eventAttributes], true, areTypesInternal);
   const element = [
     `    interface ${htmlElementName} extends Components.${tagNameAsPascal}, HTMLStencilElement {`,
     `    }`,
@@ -58827,13 +59011,12 @@ const attributesToMultiLineString = (attributes, jsxAttributes, internal) => {
 };
 
 /**
- * Find all referenced types by a component and add them to the importDataObj and return the newly
- * updated importDataObj
- *
+ * Find all referenced types by a component and add them to the `importDataObj` parameter
  * @param importDataObj key/value of type import file, each value is an array of imported types
- * @param cmpMeta the metadata for the component that is referencing the types
+ * @param allTypes an output parameter containing a map of seen types and the number of times the type has been seen
+ * @param cmp the metadata associated with the component whose types are being inspected
  * @param filePath the path of the component file
- * @param config general config that all of stencil uses
+ * @returns the updated import data
  */
 const updateReferenceTypeImports = (importDataObj, allTypes, cmp, filePath) => {
   const updateImportReferences = updateImportReferenceFactory(allTypes, filePath);
@@ -58890,16 +59073,25 @@ const updateImportReferenceFactory = (allTypes, filePath) => {
   };
 };
 
+/**
+ * Generates and writes a `components.d.ts` file to disk. This file may be written to the `src` directory of a project,
+ * or be written to a directory that is meant to be distributed (e.g. the output directory of `dist-custom-elements`).
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param destination the relative directory in the filesystem to write the type declaration file to
+ * @returns `true` if the type declaration file written to disk has changed, `false` otherwise
+ */
 const generateAppTypes = async (config, compilerCtx, buildCtx, destination) => {
   // only gather components that are still root ts files we've found and have component metadata
   // the compilerCtx cache may still have files that may have been deleted/renamed
   const timespan = buildCtx.createTimeSpan(`generated app types started`, true);
-  const internal = destination === 'src';
+  const areTypesInternal = destination === 'src';
   // Generate d.ts files for component types
-  let componentTypesFileContent = generateComponentTypesFile(config, buildCtx, internal);
+  let componentTypesFileContent = generateComponentTypesFile(config, buildCtx, areTypesInternal);
   // immediately write the components.d.ts file to disk and put it into fs memory
   let componentsDtsFilePath = getComponentsDtsSrcFilePath(config);
-  if (!internal) {
+  if (!areTypesInternal) {
     componentsDtsFilePath = resolve$1(destination, GENERATED_DTS$1);
     componentTypesFileContent = updateStencilTypesImports(destination, componentsDtsFilePath, componentTypesFileContent);
   }
@@ -58915,18 +59107,20 @@ const generateAppTypes = async (config, compilerCtx, buildCtx, destination) => {
   return hasComponentsDtsChanged;
 };
 /**
- * Generate the component.d.ts file that contains types for all components
- * @param config the project build configuration
- * @param options compiler options from tsconfig
+ * Generates a `component.d.ts` file's contents, which contains the typings for all components in a Stencil project
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param buildCtx the context associated with the current build
+ * @param areTypesInternal determines if non-exported type definitions are being generated or not
+ * @returns the contents of the `components.d.ts` file
  */
-const generateComponentTypesFile = (config, buildCtx, internal) => {
+const generateComponentTypesFile = (config, buildCtx, areTypesInternal) => {
   let typeImportData = {};
   const c = [];
   const allTypes = new Map();
   const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
   const modules = components.map((cmp) => {
     typeImportData = updateReferenceTypeImports(typeImportData, allTypes, cmp, cmp.sourceFilePath);
-    return generateComponentTypes(cmp, internal);
+    return generateComponentTypes(cmp, areTypesInternal);
   });
   c.push(COMPONENTS_DTS_HEADER);
   c.push(`import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";`);
@@ -59057,10 +59251,28 @@ const relDts$1 = (fromPath, dtsPath) => {
   return normalizePath$1(dtsPath.replace('.d.ts', ''));
 };
 
+/**
+ * Entrypoint for generating types for one or more `dist-custom-elements` output targets defined in a Stencil project's
+ * configuration
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param distDtsFilePath the path to a type declaration file (.d.ts) that is being generated for the output target.
+ * This path is not necessarily the `components.d.ts` file that is found in the root of a project's `src` directory.
+ */
 const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, distDtsFilePath) => {
   const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, distDtsFilePath, outputTarget)));
 };
+/**
+ * Generates types for a single `dist-custom-elements` output target definition in a Stencil project's configuration
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param distDtsFilePath the path to a type declaration file (.d.ts) that is being generated for the output target.
+ * This path is not necessarily the `components.d.ts` file that is found in the root of a project's `src` directory.
+ * @param outputTarget the output target for which types are being currently generated
+ */
 const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, distDtsFilePath, outputTarget) => {
   const customElementsDtsPath = join(outputTarget.dir, 'index.d.ts');
   const componentsDtsRelPath = relDts(outputTarget.dir, distDtsFilePath);
@@ -59076,7 +59288,7 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
     ` * "setAssetPath(document.currentScript.src)", or using a bundler's replace plugin to`,
     ` * dynamically set the path at build time, such as "setAssetPath(process.env.ASSET_PATH)".`,
     ` * But do note that this configuration depends on how your script is bundled, or lack of`,
-    ` * bunding, and where your assets can be loaded from. Additionally custom bundling`,
+    ` * bundling, and where your assets can be loaded from. Additionally custom bundling`,
     ` * will have to ensure the static assets are copied to its build directory.`,
     ` */`,
     `export declare const setAssetPath: (path: string) => void;`,
@@ -59111,6 +59323,13 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
     await compilerCtx.fs.writeFile(filePath, dtsCode, { outputTargetType: outputTarget.type });
   }));
 };
+/**
+ * Generate a type declaration file for a specific Stencil component
+ * @param componentsDtsRelPath the path to a root type declaration file from which commonly used entities can be
+ * referenced from in the newly generated file
+ * @param cmp the component to generate the type declaration file for
+ * @returns the contents of the type declaration file for the provided `cmp`
+ */
 const generateCustomElementType = (componentsDtsRelPath, cmp) => {
   const tagNameAsPascal = dashToPascalCase$1(cmp.tagName);
   const o = [
@@ -59129,6 +59348,13 @@ const generateCustomElementType = (componentsDtsRelPath, cmp) => {
   ];
   return o.join('\n');
 };
+/**
+ * Determines the relative path between two provided paths. If a type declaration file extension is present on
+ * `dtsPath`, it will be removed from the computed relative path.
+ * @param fromPath the path from which to start at
+ * @param dtsPath the destination path
+ * @returns the relative path from the provided `fromPath` to the `dtsPath`
+ */
 const relDts = (fromPath, dtsPath) => {
   dtsPath = relative$1(fromPath, dtsPath);
   if (!dtsPath.startsWith('.')) {
@@ -59137,13 +59363,28 @@ const relDts = (fromPath, dtsPath) => {
   return normalizePath$1(dtsPath.replace('.d.ts', ''));
 };
 
+/**
+ * For a single output target, generate types, then copy the Stencil core type declaration file
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param outputTarget the output target to generate types for
+ */
 const generateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
   if (!buildCtx.hasError) {
     await generateTypesOutput(config, compilerCtx, buildCtx, outputTarget);
     await copyStencilCoreDts(config, compilerCtx);
   }
 };
+/**
+ * Generate type definition files and write them to a dist directory
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param outputTarget the output target to generate types for
+ */
 const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget) => {
+  // get all type declaration files in a project's src/ directory
   const srcDirItems = await compilerCtx.fs.readdir(config.srcDir, { recursive: false });
   const srcDtsFiles = srcDirItems.filter((srcItem) => srcItem.isFile && isDtsFile$1(srcItem.absPath));
   // Copy .d.ts files from src to dist
@@ -59165,6 +59406,12 @@ const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget)
   }
 };
 
+/**
+ * Entrypoint for generating types for all output targets
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ */
 const outputTypes = async (config, compilerCtx, buildCtx) => {
   const outputTargets = config.outputTargets.filter(isOutputTargetDistTypes);
   if (outputTargets.length === 0) {
@@ -63816,7 +64063,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.0",
+		version: "2.15.0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -64207,11 +64454,20 @@ const validateCopy = (copy, defaultCopy = []) => {
   return unique(copy, (task) => `${task.src}:${task.dest}:${task.keepDirStructure}`);
 };
 
+/**
+ * Validate one or more `dist-custom-elements` output targets. Validation of an output target may involve back-filling
+ * fields that are omitted with sensible defaults and/or creating additional supporting output targets that were not
+ * explicitly defined by the user
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param userOutputs the output target(s) specified by the user
+ * @returns the validated output target(s)
+ */
 const validateCustomElement = (config, userOutputs) => {
-  return userOutputs.filter(isOutputTargetDistCustomElements).reduce((arr, o) => {
+  const defaultDir = 'dist';
+  return userOutputs.filter(isOutputTargetDistCustomElements).reduce((outputs, o) => {
     const outputTarget = {
       ...o,
-      dir: getAbsolutePath(config, o.dir || 'dist/components'),
+      dir: getAbsolutePath(config, o.dir || join(defaultDir, 'components')),
     };
     if (!isBoolean$1(outputTarget.empty)) {
       outputTarget.empty = true;
@@ -64219,16 +64475,25 @@ const validateCustomElement = (config, userOutputs) => {
     if (!isBoolean$1(outputTarget.externalRuntime)) {
       outputTarget.externalRuntime = true;
     }
+    // unlike other output targets, Stencil does not allow users to define the output location of types at this time
+    if (outputTarget.generateTypeDeclarations) {
+      const typesDirectory = getAbsolutePath(config, join(defaultDir, 'types'));
+      outputs.push({
+        type: DIST_TYPES,
+        dir: outputTarget.dir,
+        typesDir: typesDirectory,
+      });
+    }
     outputTarget.copy = validateCopy(outputTarget.copy, []);
     if (outputTarget.copy.length > 0) {
-      arr.push({
+      outputs.push({
         type: COPY,
         dir: config.rootDir,
         copy: [...outputTarget.copy],
       });
     }
-    arr.push(outputTarget);
-    return arr;
+    outputs.push(outputTarget);
+    return outputs;
   }, []);
 };
 
@@ -65002,7 +65267,18 @@ const validateTesting = (config, diagnostics) => {
     testing.pixelmatchThreshold = DEFAULT_PIXEL_MATCH_THRESHOLD;
   }
   if (testing.testRegex === undefined) {
-    testing.testRegex = '(/__tests__/.*|\\.?(test|spec|e2e))\\.(tsx?|ts?|jsx?|js?)$';
+    /**
+     * The test regex covers cases of:
+     * - files under a `__tests__` directory
+     * - the case where a test file has a name such as `test.ts`, `spec.ts` or `e2e.ts`.
+     *   - these files can use any of the following file extensions: .ts, .tsx, .js, .jsx.
+     *   - this regex only handles the entire path of a file, e.g. `/some/path/e2e.ts`
+     * - the case where a test file ends with `.test.ts`, `.spec.ts`, or `.e2e.ts`.
+     *   - these files can use any of the following file extensions: .ts, .tsx, .js, .jsx.
+     *   - this regex case shall match file names such as `my-cmp.spec.ts`, `test.spec.ts`
+     *   - this regex case shall not match file names such as `attest.ts`, `bespec.ts`
+     */
+    testing.testRegex = '(/__tests__/.*|(\\.|/)(test|spec|e2e))\\.[jt]sx?$';
   }
   if (Array.isArray(testing.testMatch)) {
     delete testing.testRegex;