@stencil/core 2.14.1 → 2.15.1

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.14.1 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.15.1 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -872,7 +872,7 @@ const normalizeDiagnostic = (compilerCtx, diagnostic) => {
       diagnostic.messageText = diagnostic.messageText.message;
     }
     else if (typeof diagnostic.messageText === 'string' && diagnostic.messageText.indexOf('Error: ') === 0) {
-      diagnostic.messageText = diagnostic.messageText.substr(7);
+      diagnostic.messageText = diagnostic.messageText.slice(7);
     }
   }
   if (diagnostic.messageText) {
@@ -1161,7 +1161,7 @@ const loadRollupDiagnostics = (config, compilerCtx, buildCtx, rollupError) => {
             };
             diagnostic.lineNumber = errorLine.lineNumber;
             diagnostic.columnNumber = errorLine.errorCharStart;
-            const highlightLine = errorLine.text.substr(loc.column);
+            const highlightLine = errorLine.text.slice(loc.column);
             for (let i = 0; i < highlightLine.length; i++) {
               if (charBreak.has(highlightLine.charAt(i))) {
                 break;
@@ -1588,7 +1588,7 @@ const createJsVarName = (fileName) => {
     fileName = fileName.replace(/[|;$%@"<>()+,.{}_\!\/\\]/g, '-');
     fileName = dashToPascalCase$1(fileName);
     if (fileName.length > 1) {
-      fileName = fileName[0].toLowerCase() + fileName.substr(1);
+      fileName = fileName[0].toLowerCase() + fileName.slice(1);
     }
     else {
       fileName = fileName.toLowerCase();
@@ -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) {
@@ -1705,15 +1711,16 @@ const SKIP_DEPS = ['@stencil/core'];
  * @returns an error message if the tag has an invalid name, undefined if the tag name passes all checks
  */
 const validateComponentTag = (tag) => {
+  // we want to check this first since we call some String.prototype methods below
+  if (typeof tag !== 'string') {
+    return `Tag "${tag}" must be a string type`;
+  }
   if (tag !== tag.trim()) {
     return `Tag can not contain white spaces`;
   }
   if (tag !== tag.toLowerCase()) {
     return `Tag can not contain upper case characters`;
   }
-  if (typeof tag !== 'string') {
-    return `Tag "${tag}" must be a string type`;
-  }
   if (tag.length === 0) {
     return `Received empty tag value`;
   }
@@ -3967,7 +3974,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220307172718';
+const buildId = '20220418164701';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.8_7';
 const parse5Version = '6.0.1';
@@ -3975,8 +3982,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.1';
+const vermoji = '🐼';
+const version$3 = '2.15.1';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -4436,7 +4443,7 @@ const createSystem = (c) => {
     const hashArray = Array.from(new Uint8Array(arrayBuffer)); // convert buffer to byte array
     let hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join(''); // convert bytes to hex string
     if (typeof hashLength === 'number') {
-      hashHex = hashHex.substr(0, hashLength);
+      hashHex = hashHex.slice(0, hashLength);
     }
     return hashHex;
   };
@@ -5061,13 +5068,13 @@ const getCssSelectors = (sel) => {
     if (items[i].length === 0)
       continue;
     if (items[i].charAt(0) === '.') {
-      SELECTORS.classNames.push(items[i].substr(1));
+      SELECTORS.classNames.push(items[i].slice(1));
     }
     else if (items[i].charAt(0) === '#') {
-      SELECTORS.ids.push(items[i].substr(1));
+      SELECTORS.ids.push(items[i].slice(1));
     }
     else if (items[i].charAt(0) === '[') {
-      items[i] = items[i].substr(1).split('=')[0].split(']')[0].trim();
+      items[i] = items[i].slice(1).split('=')[0].split(']')[0].trim();
       SELECTORS.attrs.push(items[i].toLowerCase());
     }
     else if (/[a-z]/g.test(items[i].charAt(0))) {
@@ -8656,7 +8663,7 @@ const loadMinifyJsDiagnostics = (sourceText, diagnostics, error) => {
     };
     d.lineNumber = errorLine.lineNumber;
     d.columnNumber = errorLine.errorCharStart;
-    const highlightLine = errorLine.text.substr(d.columnNumber);
+    const highlightLine = errorLine.text.slice(d.columnNumber);
     for (let i = 0; i < highlightLine.length; i++) {
       if (MINIFY_CHAR_BREAK.has(highlightLine.charAt(i))) {
         break;
@@ -9510,7 +9517,7 @@ const standardNormalizeHref = (prerenderConfig, diagnostics, url) => {
         // url should NOT have a trailing slash
         if (href.endsWith('/') && url.pathname !== '/') {
           // this has a trailing slash and it's not the root path
-          href = href.substr(0, href.length - 1);
+          href = href.slice(0, -1);
         }
       }
       return href;
@@ -14361,7 +14368,7 @@ function toDataAttribute(str) {
       .toLowerCase());
 }
 function dashToPascalCase(str) {
-  str = String(str).substr(5);
+  str = String(str).slice(5);
   return str
     .split('-')
     .map((segment, index) => {
@@ -14565,7 +14572,7 @@ function cssCaseToJsCase(str) {
       .split('-')
       .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
       .join('');
-    str = str.substr(0, 1).toLowerCase() + str.substr(1);
+    str = str.slice(0, 1).toLowerCase() + str.slice(1);
   }
   return str;
 }
@@ -16918,6 +16925,17 @@ MockElement.prototype.cloneNode = function (deep) {
   return cloned;
 };
 
+let sharedDocument;
+function parseHtmlToDocument(html, ownerDocument = null) {
+  if (ownerDocument == null) {
+    if (sharedDocument == null) {
+      sharedDocument = new MockDocument();
+    }
+    ownerDocument = sharedDocument;
+  }
+  return parseDocumentUtil(ownerDocument, html);
+}
+
 class MockHeaders {
   constructor(init) {
     this._values = [];
@@ -17125,6 +17143,15 @@ class MockResponse {
   }
 }
 
+class MockDOMParser {
+  parseFromString(htmlToParse, mimeType) {
+    if (mimeType !== 'text/html') {
+      console.error('XML parsing not implemented yet, continuing as html');
+    }
+    return parseHtmlToDocument(htmlToParse);
+  }
+}
+
 function addGlobalsToWindowPrototype(mockWinPrototype) {
   GLOBAL_CONSTRUCTORS.forEach(([cstrName, Cstr]) => {
     Object.defineProperty(mockWinPrototype, cstrName, {
@@ -17147,6 +17174,7 @@ const GLOBAL_CONSTRUCTORS = [
   ['MouseEvent', MockMouseEvent],
   ['Request', MockRequest],
   ['Response', MockResponse],
+  ['DOMParser', MockDOMParser],
   ['HTMLAnchorElement', MockAnchorElement],
   ['HTMLBaseElement', MockBaseElement],
   ['HTMLButtonElement', MockButtonElement],
@@ -54294,31 +54322,55 @@ const getTextOfPropertyName = (propName) => {
   }
   return undefined;
 };
+/**
+ * Generate a series of type references for a given AST node
+ * @param baseNode the AST node to pull type references from
+ * @param sourceFile the source file in which the provided `baseNode` exists
+ * @returns the generated series of type references
+ */
 const getAttributeTypeInfo = (baseNode, sourceFile) => {
   const allReferences = {};
-  getAllTypeReferences(baseNode).forEach((rt) => {
-    allReferences[rt] = getTypeReferenceLocation(rt, sourceFile);
+  getAllTypeReferences(baseNode).forEach((typeName) => {
+    allReferences[typeName] = getTypeReferenceLocation(typeName, sourceFile);
   });
   return allReferences;
 };
+/**
+ * Get the text-based name from a TypeScript `EntityName`, which is an identifier of some form
+ * @param entity a TypeScript `EntityName` to retrieve the name of an entity from
+ * @returns the entity's name
+ */
 const getEntityName = (entity) => {
   if (t.isIdentifier(entity)) {
     return entity.escapedText.toString();
   }
   else {
+    // We have qualified name - e.g. const x: Foo.Bar.Baz;
+    // Recurse until we find the 'base' of the qualified name
     return getEntityName(entity.left);
   }
 };
+/**
+ * Recursively walks the provided AST to collect all TypeScript type references that are found
+ * @param node the node to walk to retrieve type information
+ * @returns the collected type references
+ */
 const getAllTypeReferences = (node) => {
   const referencedTypes = [];
   const visit = (node) => {
+    /**
+     * A type reference node will refer to some type T.
+     * e.g: In `const foo: Bar = {...}` the reference node will contain semantic information about `Bar`.
+     * In TypeScript, types that are also keywords (e.g. `number` in `const foo: number`) are not `TypeReferenceNode`s.
+     */
     if (t.isTypeReferenceNode(node)) {
       referencedTypes.push(getEntityName(node.typeName));
       if (node.typeArguments) {
+        // a type may contain types itself (e.g. generics - Foo<Bar>)
         node.typeArguments
-          .filter((ta) => t.isTypeReferenceNode(ta))
-          .forEach((tr) => {
-          const typeName = tr.typeName;
+          .filter((typeArg) => t.isTypeReferenceNode(typeArg))
+          .forEach((typeRef) => {
+          const typeName = typeRef.typeName;
           if (typeName && typeName.escapedText) {
             referencedTypes.push(typeName.escapedText.toString());
           }
@@ -54339,6 +54391,22 @@ const validateReferences = (diagnostics, references, node) => {
     }
   });
 };
+/**
+ * Determine where a TypeScript type reference originates from. This is accomplished by interrogating the AST node in
+ * which the type's name appears
+ *
+ * A type may originate:
+ * - from the same file where it is used (a type is declared in some file, `foo.ts`, and later used in the same file)
+ * - from another file (I.E. it is imported and should have an import statement somewhere in the file)
+ * - from a global context
+ * - etc.
+ *
+ * The type may be declared using the `type` or `interface` keywords.
+ *
+ * @param typeName the name of the type to find the origination of
+ * @param tsNode the TypeScript AST node being searched for the provided `typeName`
+ * @returns the context stating where the type originates from
+ */
 const getTypeReferenceLocation = (typeName, tsNode) => {
   const sourceFileObj = tsNode.getSourceFile();
   // Loop through all top level imports to find any reference to the type for 'import' reference location
@@ -58837,8 +58905,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('.')) {
@@ -58851,6 +58929,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 the results of writing one or more type declaration files to disk
+ */
 const copyStencilCoreDts = async (config, compilerCtx) => {
   const typesOutputTargets = config.outputTargets.filter(isOutputTargetDistTypes).filter((o) => o.typesDir);
   const srcStencilDtsPath = join(config.sys.getCompilerExecutingPath(), '..', '..', 'internal', CORE_DTS);
@@ -58883,8 +58967,13 @@ const sortImportNames = (a, b) => {
   return 0;
 };
 
-const generateEventTypes = (cmpEvents) => {
-  return cmpEvents.map((cmpEvent) => {
+/**
+ * Generates the individual event types for all @Event() decorated events in a component
+ * @param cmpMeta component runtime metadata for a single component
+ * @returns the generated type metadata
+ */
+const generateEventTypes = (cmpMeta) => {
+  return cmpMeta.events.map((cmpEvent) => {
     const name = `on${toTitleCase(cmpEvent.name)}`;
     const type = cmpEvent.complexType.original
       ? `(event: CustomEvent<${cmpEvent.complexType.original}>) => void`
@@ -58900,8 +58989,13 @@ const generateEventTypes = (cmpEvents) => {
   });
 };
 
-const generateMethodTypes = (cmpMethods) => {
-  return cmpMethods.map((cmpMethod) => ({
+/**
+ * Generates the individual event types for all @Method() decorated events in a component
+ * @param cmpMeta component runtime metadata for a single component
+ * @returns the generated type metadata
+ */
+const generateMethodTypes = (cmpMeta) => {
+  return cmpMeta.methods.map((cmpMethod) => ({
     name: cmpMethod.name,
     type: cmpMethod.complexType.signature,
     optional: false,
@@ -58911,6 +59005,11 @@ const generateMethodTypes = (cmpMethods) => {
   }));
 };
 
+/**
+ * Generates the individual event types for all @Prop() decorated events in a component
+ * @param cmpMeta component runtime metadata for a single component
+ * @returns the generated type metadata
+ */
 const generatePropTypes = (cmpMeta) => {
   return [
     ...cmpMeta.properties.map((cmpProp) => ({
@@ -58933,21 +59032,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 methodAttributes = generateMethodTypes(cmp);
+  const eventAttributes = generateEventTypes(cmp);
+  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 {`,
     `    }`,
@@ -58989,13 +59088,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);
@@ -59052,16 +59150,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);
   }
@@ -59077,18 +59184,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";`);
@@ -59219,10 +59328,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);
@@ -59238,7 +59365,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;`,
@@ -59273,6 +59400,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 = [
@@ -59291,6 +59425,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('.')) {
@@ -59299,13 +59440,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
@@ -59327,6 +59483,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) {
@@ -61981,7 +62143,7 @@ const validateManifestJsonIcon = async (compilerCtx, buildCtx, manifestFilePath,
     return;
   }
   if (iconSrc.startsWith('/')) {
-    iconSrc = iconSrc.substr(1);
+    iconSrc = iconSrc.slice(1);
   }
   const manifestDir = dirname(manifestFilePath);
   const iconPath = join(manifestDir, iconSrc);
@@ -63978,7 +64140,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.1",
+		version: "2.15.1",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -64369,11 +64531,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;
@@ -64381,16 +64552,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;
   }, []);
 };
 
@@ -65164,7 +65344,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;