@stencil/core 2.14.2 → 2.15.2

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.14.2 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.15.2 | 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,16 +3974,16 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220310222720';
+const buildId = '20220509165949';
 const minfyJsId = 'terser5.6.1_7';
-const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.8_7';
+const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.13_7';
 const parse5Version = '6.0.1';
 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.2';
+const vermoji = '🎢';
+const version$3 = '2.15.2';
 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,74 @@ const updateStencilTypesImports = (typesDir, dtsFilePath, dtsContent) => {
   }
   return dtsContent;
 };
+/**
+ * Utility for ensuring that naming collisions do not appear in type declaration files for a component's class members
+ * decorated with @Prop, @Event, and @Method
+ * @param typeReferences all type names used by a component class member
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @param sourceFilePath the path to the source file of a component using the type being inspected
+ * @param initialType the name of the type that may be updated
+ * @returns the updated type name, which may be the same as the initial type name provided as an argument to this
+ * function
+ */
+const updateTypeIdentifierNames = (typeReferences, typeImportData, sourceFilePath, initialType) => {
+  let currentTypeName = initialType;
+  // iterate over each of the type references, as there may be >1 reference to inspect
+  for (let typeReference of Object.values(typeReferences)) {
+    const importResolvedFile = getTypeImportPath(typeReference.path, sourceFilePath);
+    if (!typeImportData.hasOwnProperty(importResolvedFile)) {
+      continue;
+    }
+    for (let typesImportDatumElement of typeImportData[importResolvedFile]) {
+      currentTypeName = updateTypeName(currentTypeName, typesImportDatumElement);
+    }
+  }
+  return currentTypeName;
+};
+/**
+ * Determine the path of a given type reference, relative to the path of a source file
+ * @param importResolvedFile the path to the file containing the resolve type. may be absolute or relative
+ * @param sourceFilePath the component source file path to resolve against
+ * @returns the path of the type import
+ */
+const getTypeImportPath = (importResolvedFile, sourceFilePath) => {
+  const isPathRelative = importResolvedFile && importResolvedFile.startsWith('.');
+  if (isPathRelative) {
+    importResolvedFile = resolve$1(dirname(sourceFilePath), importResolvedFile);
+  }
+  return importResolvedFile;
+};
+/**
+ * Determine whether the string representation of a type should be replaced with an alias
+ * @param currentTypeName the current string representation of a type
+ * @param typeAlias a type member and a potential different name associated with the type member
+ * @returns the updated string representation of a type. If the type is not updated, the original type name is returned
+ */
+const updateTypeName = (currentTypeName, typeAlias) => {
+  if (!typeAlias.importName) {
+    return currentTypeName;
+  }
+  // TODO(STENCIL-419): Update this functionality to no longer use a regex
+  // negative lookahead specifying that quotes that designate a string in JavaScript cannot follow some expression
+  const endingStrChar = '(?!("|\'|`))';
+  /**
+   * A regular expression that looks at type names along a [word boundary](https://www.regular-expressions.info/wordboundaries.html).
+   * This is used as the best approximation for replacing type collisions, as this stage of compilation has only
+   * 'flattened' type information in the form of a String.
+   *
+   * This regex should be expected to capture types that are found in generics, unions, intersections, etc., but not
+   * those in string literals. We do not check for a starting quote (" | ' | `) here as some browsers do not support
+   * negative lookbehind. This works "well enough" until STENCIL-419 is completed.
+   */
+  const typeNameRegex = new RegExp(`${typeAlias.localName}\\b${endingStrChar}`, 'g');
+  return currentTypeName.replace(typeNameRegex, typeAlias.importName);
+};
+/**
+ * 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,12 +59029,16 @@ 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
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @returns the generated type metadata
+ */
+const generateEventTypes = (cmpMeta, typeImportData) => {
+  return cmpMeta.events.map((cmpEvent) => {
     const name = `on${toTitleCase(cmpEvent.name)}`;
-    const type = cmpEvent.complexType.original
-      ? `(event: CustomEvent<${cmpEvent.complexType.original}>) => void`
-      : `CustomEvent`;
+    const type = getEventType$1(cmpEvent, typeImportData, cmpMeta.sourceFilePath);
     return {
       name,
       type,
@@ -58899,23 +59049,59 @@ const generateEventTypes = (cmpEvents) => {
     };
   });
 };
+/**
+ * Determine the correct type name for all type(s) used by a class member annotated with `@Event()`
+ * @param cmpEvent the compiler metadata for a single `@Event()`
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @param componentSourcePath the path to the component on disk
+ * @returns the type associated with a `@Event()`
+ */
+const getEventType$1 = (cmpEvent, typeImportData, componentSourcePath) => {
+  if (!cmpEvent.complexType.original) {
+    return 'CustomEvent';
+  }
+  const updatedTypeName = updateTypeIdentifierNames(cmpEvent.complexType.references, typeImportData, componentSourcePath, cmpEvent.complexType.original);
+  return `(event: CustomEvent<${updatedTypeName}>) => void`;
+};
 
-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
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @returns the generated type metadata
+ */
+const generateMethodTypes = (cmpMeta, typeImportData) => {
+  return cmpMeta.methods.map((cmpMethod) => ({
     name: cmpMethod.name,
-    type: cmpMethod.complexType.signature,
+    type: getType$1(cmpMethod, typeImportData, cmpMeta.sourceFilePath),
     optional: false,
     required: false,
     internal: cmpMethod.internal,
     jsdoc: getTextDocs(cmpMethod.docs),
   }));
 };
+/**
+ * Determine the correct type name for all type(s) used by a class member annotated with `@Method()`
+ * @param cmpMethod the compiler metadata for a single `@Method()`
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @param componentSourcePath the path to the component on disk
+ * @returns the type associated with a `@Method()`
+ */
+function getType$1(cmpMethod, typeImportData, componentSourcePath) {
+  return updateTypeIdentifierNames(cmpMethod.complexType.references, typeImportData, componentSourcePath, cmpMethod.complexType.signature);
+}
 
-const generatePropTypes = (cmpMeta) => {
+/**
+ * Generates the individual event types for all @Prop() decorated events in a component
+ * @param cmpMeta component runtime metadata for a single component
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @returns the generated type metadata
+ */
+const generatePropTypes = (cmpMeta, typeImportData) => {
   return [
     ...cmpMeta.properties.map((cmpProp) => ({
       name: cmpProp.name,
-      type: cmpProp.complexType.original,
+      type: getType(cmpProp, typeImportData, cmpMeta.sourceFilePath),
       optional: cmpProp.optional,
       required: cmpProp.required,
       internal: cmpProp.internal,
@@ -58931,23 +59117,34 @@ const generatePropTypes = (cmpMeta) => {
     })),
   ];
 };
+/**
+ * Determine the correct type name for all type(s) used by a class member annotated with `@Prop()`
+ * @param cmpProp the compiler metadata for a single `@Prop()`
+ * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @param componentSourcePath the path to the component on disk
+ * @returns the type associated with a `@Prop()`
+ */
+function getType(cmpProp, typeImportData, componentSourcePath) {
+  return updateTypeIdentifierNames(cmpProp.complexType.references, typeImportData, componentSourcePath, cmpProp.complexType.original);
+}
 
 /**
- * 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 typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
+ * @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, typeImportData, 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 propAttributes = generatePropTypes(cmp, typeImportData);
+  const methodAttributes = generateMethodTypes(cmp, typeImportData);
+  const eventAttributes = generateEventTypes(cmp, typeImportData);
+  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,79 +59186,99 @@ const attributesToMultiLineString = (attributes, jsxAttributes, internal) => {
 };
 
 /**
- * Find all referenced types by a component and add them to the importDataObj and return the newly
- * updated importDataObj
- *
- * @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
+ * Find all referenced types by a component and add them to the `importDataObj` parameter
+ * @param importDataObj an output parameter that contains the imported types seen thus far by the compiler
+ * @param typeCounts 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);
+const updateReferenceTypeImports = (importDataObj, typeCounts, cmp, filePath) => {
+  const updateImportReferences = updateImportReferenceFactory(typeCounts, filePath);
   return [...cmp.properties, ...cmp.events, ...cmp.methods]
     .filter((cmpProp) => cmpProp.complexType && cmpProp.complexType.references)
-    .reduce((obj, cmpProp) => {
-    return updateImportReferences(obj, cmpProp.complexType.references);
+    .reduce((typesImportData, cmpProp) => {
+    return updateImportReferences(typesImportData, cmpProp.complexType.references);
   }, importDataObj);
 };
-const updateImportReferenceFactory = (allTypes, filePath) => {
+/**
+ * Factory function to create an `ImportReferenceUpdater` instance
+ * @param typeCounts a key-value store of seen type names and the number of times the type name has been seen
+ * @param filePath the path of the file containing the component whose imports are being inspected
+ * @returns an `ImportReferenceUpdater` instance for updating import references in the provided `filePath`
+ */
+const updateImportReferenceFactory = (typeCounts, filePath) => {
+  /**
+   * Determines the number of times that a type identifier (name) has been used. If an identifier has been used before,
+   * append the number of times the identifier has been seen to its name to avoid future naming collisions
+   * @param name the identifier name to check for previous usages
+   * @returns the identifier name, potentially with an integer appended to its name if it has been seen before.
+   */
   function getIncrementTypeName(name) {
-    const counter = allTypes.get(name);
+    const counter = typeCounts.get(name);
     if (counter === undefined) {
-      allTypes.set(name, 1);
+      typeCounts.set(name, 1);
       return name;
     }
-    allTypes.set(name, counter + 1);
+    typeCounts.set(name, counter + 1);
     return `${name}${counter}`;
   }
-  return (obj, typeReferences) => {
+  return (existingTypeImportData, typeReferences) => {
     Object.keys(typeReferences)
       .map((typeName) => {
       return [typeName, typeReferences[typeName]];
     })
-      .forEach(([typeName, type]) => {
-      let importFileLocation;
+      .forEach(([typeName, typeReference]) => {
+      let importResolvedFile;
       // If global then there is no import statement needed
-      if (type.location === 'global') {
+      if (typeReference.location === 'global') {
         return;
         // If local then import location is the current file
       }
-      else if (type.location === 'local') {
-        importFileLocation = filePath;
+      else if (typeReference.location === 'local') {
+        importResolvedFile = filePath;
       }
-      else if (type.location === 'import') {
-        importFileLocation = type.path;
+      else if (typeReference.location === 'import') {
+        importResolvedFile = typeReference.path;
       }
       // If this is a relative path make it absolute
-      if (importFileLocation.startsWith('.')) {
-        importFileLocation = resolve$1(dirname(filePath), importFileLocation);
+      if (importResolvedFile.startsWith('.')) {
+        importResolvedFile = resolve$1(dirname(filePath), importResolvedFile);
       }
-      obj[importFileLocation] = obj[importFileLocation] || [];
+      existingTypeImportData[importResolvedFile] = existingTypeImportData[importResolvedFile] || [];
       // If this file already has a reference to this type move on
-      if (obj[importFileLocation].find((df) => df.localName === typeName)) {
+      if (existingTypeImportData[importResolvedFile].find((df) => df.localName === typeName)) {
         return;
       }
       const newTypeName = getIncrementTypeName(typeName);
-      obj[importFileLocation].push({
+      existingTypeImportData[importResolvedFile].push({
         localName: typeName,
         importName: newTypeName,
       });
     });
-    return obj;
+    return existingTypeImportData;
   };
 };
 
+/**
+ * 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,21 +59294,30 @@ 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) => {
+    /**
+     * Generate a key-value store that uses the path to the file where an import is defined as the key, and an object
+     * containing the import's original name and any 'new' name we give it to avoid collisions. We're generating this
+     * data structure for each Stencil component in series, therefore the memory footprint of this entity will likely
+     * grow as more components (with additional types) are processed.
+     */
     typeImportData = updateReferenceTypeImports(typeImportData, allTypes, cmp, cmp.sourceFilePath);
-    return generateComponentTypes(cmp, internal);
+    return generateComponentTypes(cmp, typeImportData, areTypesInternal);
   });
   c.push(COMPONENTS_DTS_HEADER);
   c.push(`import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";`);
+  // write the import statements for our type declaration file
   c.push(...Object.keys(typeImportData).map((filePath) => {
     const typeData = typeImportData[filePath];
     let importFilePath;
@@ -59219,10 +59445,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 +59482,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 +59517,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 +59542,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 +59557,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 +59600,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 +62260,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 +64257,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.2",
+		version: "2.15.2",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -64369,11 +64648,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 +64669,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;
   }, []);
 };
 
@@ -64417,9 +64714,19 @@ const validateCustomOutput = (config, diagnostics, userOutputs) => {
   });
 };
 
+/**
+ * Validate that the "dist" output targets are valid and ready to go.
+ *
+ * This function will also add in additional output targets to its output, based on the input supplied.
+ *
+ * @param config the compiler config, what else?
+ * @param userOutputs a user-supplied list of output targets.
+ * @returns a list of OutputTargets which have been validated for us.
+ */
 const validateDist = (config, userOutputs) => {
   const distOutputTargets = userOutputs.filter(isOutputTargetDist);
   return distOutputTargets.reduce((outputs, o) => {
+    var _a;
     const distOutputTarget = validateOutputTargetDist(config, o);
     outputs.push(distOutputTarget);
     const namespace = config.fsNamespace || 'app';
@@ -64439,7 +64746,7 @@ const validateDist = (config, userOutputs) => {
       type: COPY,
       dir: lazyDir,
       copyAssets: 'dist',
-      copy: [...distOutputTarget.copy],
+      copy: ((_a = distOutputTarget.copy) !== null && _a !== void 0 ? _a : []).concat(),
     });
     outputs.push({
       type: DIST_GLOBAL_STYLES,
@@ -64449,7 +64756,6 @@ const validateDist = (config, userOutputs) => {
       type: DIST_TYPES,
       dir: distOutputTarget.dir,
       typesDir: distOutputTarget.typesDir,
-      empty: distOutputTarget.empty,
     });
     if (config.buildDist) {
       if (distOutputTarget.collectionDir) {
@@ -64494,39 +64800,44 @@ const validateDist = (config, userOutputs) => {
     return outputs;
   }, []);
 };
+/**
+ * Validate that an OutputTargetDist object has what it needs to do it's job.
+ * To enforce this, we have this function return
+ * `Required<d.OutputTargetDist>`, giving us a compile-time check that all
+ * properties are defined (with either user-supplied or default values).
+ *
+ * @param config the current config
+ * @param o the OutputTargetDist object we want to validate
+ * @returns `Required<d.OutputTargetDist>`, i.e. `d.OutputTargetDist` with all
+ * optional properties rendered un-optional.
+ */
 const validateOutputTargetDist = (config, o) => {
+  var _a;
+  // we need to create an object with a bunch of default values here so that
+  // the typescript compiler can infer their types correctly
   const outputTarget = {
     ...o,
     dir: getAbsolutePath(config, o.dir || DEFAULT_DIR),
+    buildDir: isString$1(o.buildDir) ? o.buildDir : DEFAULT_BUILD_DIR,
+    collectionDir: o.collectionDir !== undefined ? o.collectionDir : DEFAULT_COLLECTION_DIR,
+    typesDir: o.typesDir || DEFAULT_TYPES_DIR,
+    esmLoaderPath: o.esmLoaderPath || DEFAULT_ESM_LOADER_DIR,
+    copy: validateCopy((_a = o.copy) !== null && _a !== void 0 ? _a : [], []),
+    polyfills: isBoolean$1(o.polyfills) ? o.polyfills : undefined,
+    empty: isBoolean$1(o.empty) ? o.empty : true,
   };
-  if (!isString$1(outputTarget.buildDir)) {
-    outputTarget.buildDir = DEFAULT_BUILD_DIR;
-  }
   if (!isAbsolute$1(outputTarget.buildDir)) {
     outputTarget.buildDir = join(outputTarget.dir, outputTarget.buildDir);
   }
-  if (outputTarget.collectionDir === undefined) {
-    outputTarget.collectionDir = DEFAULT_COLLECTION_DIR;
-  }
   if (outputTarget.collectionDir && !isAbsolute$1(outputTarget.collectionDir)) {
     outputTarget.collectionDir = join(outputTarget.dir, outputTarget.collectionDir);
   }
-  if (!outputTarget.esmLoaderPath) {
-    outputTarget.esmLoaderPath = DEFAULT_ESM_LOADER_DIR;
-  }
   if (!isAbsolute$1(outputTarget.esmLoaderPath)) {
     outputTarget.esmLoaderPath = resolve$1(outputTarget.dir, outputTarget.esmLoaderPath);
   }
-  if (!outputTarget.typesDir) {
-    outputTarget.typesDir = DEFAULT_TYPES_DIR;
-  }
   if (!isAbsolute$1(outputTarget.typesDir)) {
     outputTarget.typesDir = join(outputTarget.dir, outputTarget.typesDir);
   }
-  if (!isBoolean$1(outputTarget.empty)) {
-    outputTarget.empty = true;
-  }
-  outputTarget.copy = validateCopy(outputTarget.copy, []);
   return outputTarget;
 };
 const DEFAULT_DIR = 'dist';
@@ -65175,7 +65486,7 @@ const validateTesting = (config, diagnostics) => {
      *   - 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?';
+    testing.testRegex = '(/__tests__/.*|(\\.|/)(test|spec|e2e))\\.[jt]sx?$';
   }
   if (Array.isArray(testing.testMatch)) {
     delete testing.testRegex;