@stencil/core 2.16.0 → 2.17.0

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.16.0 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.17.0 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -717,7 +717,7 @@ const computeListenerFlags = (listener) => {
 };
 const trimFalsy = (data) => {
   const arr = data;
-  for (var i = arr.length - 1; i >= 0; i--) {
+  for (let i = arr.length - 1; i >= 0; i--) {
     if (arr[i]) {
       break;
     }
@@ -826,136 +826,15 @@ const isGlob = (str) => {
 };
 
 /**
- * Checks if the path is the OS root path, such as "/" or "C:\"
+ * Checks if the path is the Operating System (OS) root path, such as "/" or "C:\". This function does not take the OS
+ * the code is running on into account when performing this evaluation.
+ * @param p the path to check
+ * @returns `true` if the path is an OS root path, `false` otherwise
  */
 const isRootPath = (p) => p === '/' || windowsPathRegex.test(p);
 // https://github.com/nodejs/node/blob/5883a59b21a97e8b7339f435c977155a2c29ba8d/lib/path.js#L43
 const windowsPathRegex = /^(?:[a-zA-Z]:|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)?[\\/]$/;
 
-/**
- * Iterate through a series of diagnostics to provide minor fix-ups for various edge cases, deduplicate messages, etc.
- * @param compilerCtx the current compiler context
- * @param diagnostics the diagnostics to normalize
- * @returns the normalize documents
- */
-const normalizeDiagnostics = (compilerCtx, diagnostics) => {
-  const normalizedErrors = [];
-  const normalizedOthers = [];
-  const dups = new Set();
-  for (let i = 0; i < diagnostics.length; i++) {
-    const d = normalizeDiagnostic(compilerCtx, diagnostics[i]);
-    const key = d.absFilePath + d.code + d.messageText + d.type;
-    if (dups.has(key)) {
-      continue;
-    }
-    dups.add(key);
-    const total = normalizedErrors.length + normalizedOthers.length;
-    if (d.level === 'error') {
-      normalizedErrors.push(d);
-    }
-    else if (total < MAX_ERRORS) {
-      normalizedOthers.push(d);
-    }
-  }
-  return [...normalizedErrors, ...normalizedOthers];
-};
-/**
- * Perform post-processing on a `Diagnostic` to handle a few message edge cases, massaging error message text and
- * updating build failure contexts
- * @param compilerCtx the current compiler
- * @param diagnostic the diagnostic to normalize
- * @returns the altered diagnostic
- */
-const normalizeDiagnostic = (compilerCtx, diagnostic) => {
-  if (diagnostic.messageText) {
-    if (typeof diagnostic.messageText.message === 'string') {
-      diagnostic.messageText = diagnostic.messageText.message;
-    }
-    else if (typeof diagnostic.messageText === 'string' && diagnostic.messageText.indexOf('Error: ') === 0) {
-      diagnostic.messageText = diagnostic.messageText.slice(7);
-    }
-  }
-  if (diagnostic.messageText) {
-    if (diagnostic.messageText.includes(`Cannot find name 'h'`)) {
-      diagnostic.header = `Missing "h" import for JSX types`;
-      diagnostic.messageText = `In order to load accurate JSX types for components, the "h" function must be imported from "@stencil/core" by each component using JSX. For example: import { Component, h } from '@stencil/core';`;
-      try {
-        const sourceText = compilerCtx.fs.readFileSync(diagnostic.absFilePath);
-        const srcLines = splitLineBreaks(sourceText);
-        for (let i = 0; i < srcLines.length; i++) {
-          const srcLine = srcLines[i];
-          if (srcLine.includes('@stencil/core')) {
-            const msgLines = [];
-            const beforeLineIndex = i - 1;
-            if (beforeLineIndex > -1) {
-              const beforeLine = {
-                lineIndex: beforeLineIndex,
-                lineNumber: beforeLineIndex + 1,
-                text: srcLines[beforeLineIndex],
-                errorCharStart: -1,
-                errorLength: -1,
-              };
-              msgLines.push(beforeLine);
-            }
-            const errorLine = {
-              lineIndex: i,
-              lineNumber: i + 1,
-              text: srcLine,
-              errorCharStart: 0,
-              errorLength: -1,
-            };
-            msgLines.push(errorLine);
-            diagnostic.lineNumber = errorLine.lineNumber;
-            diagnostic.columnNumber = srcLine.indexOf('}');
-            const afterLineIndex = i + 1;
-            if (afterLineIndex < srcLines.length) {
-              const afterLine = {
-                lineIndex: afterLineIndex,
-                lineNumber: afterLineIndex + 1,
-                text: srcLines[afterLineIndex],
-                errorCharStart: -1,
-                errorLength: -1,
-              };
-              msgLines.push(afterLine);
-            }
-            diagnostic.lines = msgLines;
-            break;
-          }
-        }
-      }
-      catch (e) { }
-    }
-  }
-  return diagnostic;
-};
-/**
- * Split a corpus by newlines. Carriage returns are treated a newlines.
- * @param sourceText the corpus to split
- * @returns the split text
- */
-const splitLineBreaks = (sourceText) => {
-  if (typeof sourceText !== 'string')
-    return [];
-  sourceText = sourceText.replace(/\\r/g, '\n');
-  return sourceText.split('\n');
-};
-const escapeHtml = (unsafe) => {
-  if (unsafe === undefined)
-    return 'undefined';
-  if (unsafe === null)
-    return 'null';
-  if (typeof unsafe !== 'string') {
-    unsafe = unsafe.toString();
-  }
-  return unsafe
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#039;');
-};
-const MAX_ERRORS = 25;
-
 /**
  * Builds a template `Diagnostic` entity for a build error. The created `Diagnostic` is returned, and have little
  * detail attached to it regarding the specifics of the error - it is the responsibility of the caller of this method
@@ -1120,6 +999,130 @@ const shouldIgnoreError = (msg) => {
 };
 const TASK_CANCELED_MSG = `task canceled`;
 
+/**
+ * Iterate through a series of diagnostics to provide minor fix-ups for various edge cases, deduplicate messages, etc.
+ * @param compilerCtx the current compiler context
+ * @param diagnostics the diagnostics to normalize
+ * @returns the normalize documents
+ */
+const normalizeDiagnostics = (compilerCtx, diagnostics) => {
+  const maxErrorsToNormalize = 25;
+  const normalizedErrors = [];
+  const normalizedOthers = [];
+  const dups = new Set();
+  for (let i = 0; i < diagnostics.length; i++) {
+    const d = normalizeDiagnostic(compilerCtx, diagnostics[i]);
+    const key = d.absFilePath + d.code + d.messageText + d.type;
+    if (dups.has(key)) {
+      continue;
+    }
+    dups.add(key);
+    const total = normalizedErrors.length + normalizedOthers.length;
+    if (d.level === 'error') {
+      normalizedErrors.push(d);
+    }
+    else if (total < maxErrorsToNormalize) {
+      normalizedOthers.push(d);
+    }
+  }
+  return [...normalizedErrors, ...normalizedOthers];
+};
+/**
+ * Perform post-processing on a `Diagnostic` to handle a few message edge cases, massaging error message text and
+ * updating build failure contexts
+ * @param compilerCtx the current compiler
+ * @param diagnostic the diagnostic to normalize
+ * @returns the altered diagnostic
+ */
+const normalizeDiagnostic = (compilerCtx, diagnostic) => {
+  if (diagnostic.messageText) {
+    if (typeof diagnostic.messageText.message === 'string') {
+      diagnostic.messageText = diagnostic.messageText.message;
+    }
+    else if (typeof diagnostic.messageText === 'string' && diagnostic.messageText.indexOf('Error: ') === 0) {
+      diagnostic.messageText = diagnostic.messageText.slice(7);
+    }
+  }
+  if (diagnostic.messageText) {
+    if (diagnostic.messageText.includes(`Cannot find name 'h'`)) {
+      diagnostic.header = `Missing "h" import for JSX types`;
+      diagnostic.messageText = `In order to load accurate JSX types for components, the "h" function must be imported from "@stencil/core" by each component using JSX. For example: import { Component, h } from '@stencil/core';`;
+      try {
+        const sourceText = compilerCtx.fs.readFileSync(diagnostic.absFilePath);
+        const srcLines = splitLineBreaks(sourceText);
+        for (let i = 0; i < srcLines.length; i++) {
+          const srcLine = srcLines[i];
+          if (srcLine.includes('@stencil/core')) {
+            const msgLines = [];
+            const beforeLineIndex = i - 1;
+            if (beforeLineIndex > -1) {
+              const beforeLine = {
+                lineIndex: beforeLineIndex,
+                lineNumber: beforeLineIndex + 1,
+                text: srcLines[beforeLineIndex],
+                errorCharStart: -1,
+                errorLength: -1,
+              };
+              msgLines.push(beforeLine);
+            }
+            const errorLine = {
+              lineIndex: i,
+              lineNumber: i + 1,
+              text: srcLine,
+              errorCharStart: 0,
+              errorLength: -1,
+            };
+            msgLines.push(errorLine);
+            diagnostic.lineNumber = errorLine.lineNumber;
+            diagnostic.columnNumber = srcLine.indexOf('}');
+            const afterLineIndex = i + 1;
+            if (afterLineIndex < srcLines.length) {
+              const afterLine = {
+                lineIndex: afterLineIndex,
+                lineNumber: afterLineIndex + 1,
+                text: srcLines[afterLineIndex],
+                errorCharStart: -1,
+                errorLength: -1,
+              };
+              msgLines.push(afterLine);
+            }
+            diagnostic.lines = msgLines;
+            break;
+          }
+        }
+      }
+      catch (e) { }
+    }
+  }
+  return diagnostic;
+};
+/**
+ * Split a corpus by newlines. Carriage returns are treated a newlines.
+ * @param sourceText the corpus to split
+ * @returns the split text
+ */
+const splitLineBreaks = (sourceText) => {
+  if (typeof sourceText !== 'string')
+    return [];
+  sourceText = sourceText.replace(/\\r/g, '\n');
+  return sourceText.split('\n');
+};
+const escapeHtml = (unsafe) => {
+  if (unsafe === undefined)
+    return 'undefined';
+  if (unsafe === null)
+    return 'null';
+  if (typeof unsafe !== 'string') {
+    unsafe = unsafe.toString();
+  }
+  return unsafe
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+};
+
 const loadRollupDiagnostics = (config, compilerCtx, buildCtx, rollupError) => {
   const formattedCode = formatErrorCode(rollupError.code);
   const diagnostic = {
@@ -1258,6 +1261,8 @@ const formatErrorCode = (errorCode) => {
  * Forward-slash paths can be used in Windows as long as they're not
  * extended-length paths and don't contain any non-ascii characters.
  * This was created since the path methods in Node.js outputs \\ paths on Windows.
+ * @param path the Windows-based path to convert
+ * @returns the converted path
  */
 const normalizePath$1 = (path) => {
   if (typeof path !== 'string') {
@@ -1393,8 +1398,10 @@ const pathComponents = (path, rootLength) => {
   return [root, ...rest];
 };
 /**
- * Same as normalizePath(), expect it'll also strip any querystrings
+ * Same as normalizePath(), expect it'll also strip any query strings
  * from the path name. So /dir/file.css?tag=cmp-a becomes /dir/file.css
+ * @param p the path to normalize
+ * @returns the normalized path, sans any query strings
  */
 const normalizeFsPath = (p) => normalizePath$1(p.split('?')[0].replace(/\0/g, ''));
 const normalizeFsPathQuery = (importPath) => {
@@ -1570,6 +1577,15 @@ const flattenDiagnosticMessageText = (tsDiagnostic, diag) => {
   return result.trim();
 };
 
+/**
+ * Determines whether a string should be considered a remote url or not.
+ *
+ * This helper only checks the provided string to evaluate is one of a few pre-defined schemes, and should not be
+ * considered all-encompassing
+ *
+ * @param p the string to evaluate
+ * @returns `true` if the provided string is a remote url, `false` otherwise
+ */
 const isRemoteUrl = (p) => {
   if (isString$1(p)) {
     p = p.toLowerCase();
@@ -1639,12 +1655,23 @@ ${docs.tags
     .map((tag) => `@${tag.name} ${(tag.text || '').replace(lineBreakRegex, ' ')}`)
     .join('\n')}`.trim();
 }
+/**
+ * Retrieve a project's dependencies from the current build context
+ * @param buildCtx the current build context to query for a specific package
+ * @returns a list of package names the project is dependent on
+ */
 const getDependencies = (buildCtx) => {
   if (buildCtx.packageJson != null && buildCtx.packageJson.dependencies != null) {
     return Object.keys(buildCtx.packageJson.dependencies).filter((pkgName) => !SKIP_DEPS.includes(pkgName));
   }
   return [];
 };
+/**
+ * Utility to determine whether a project has a dependency on a package
+ * @param buildCtx the current build context to query for a specific package
+ * @param depName the name of the dependency/package
+ * @returns `true` if the project has a dependency a packaged with the provided name, `false` otherwise
+ */
 const hasDependency = (buildCtx, depName) => {
   return getDependencies(buildCtx).includes(depName);
 };
@@ -1670,38 +1697,30 @@ const readPackageJson = async (config, compilerCtx, buildCtx) => {
     }
   }
 };
+/**
+ * Parse a string read from a `package.json` file
+ * @param pkgJsonStr the string read from a `package.json` file
+ * @param pkgJsonFilePath the path to the already read `package.json` file
+ * @returns the results of parsing the provided contents of the `package.json` file
+ */
 const parsePackageJson = (pkgJsonStr, pkgJsonFilePath) => {
-  if (isString$1(pkgJsonFilePath)) {
-    return parseJson(pkgJsonStr, pkgJsonFilePath);
-  }
-  return null;
-};
-const parseJson = (jsonStr, filePath) => {
-  const rtn = {
+  const parseResult = {
     diagnostic: null,
     data: null,
-    filePath,
+    filePath: pkgJsonFilePath,
   };
-  if (isString$1(jsonStr)) {
-    try {
-      rtn.data = JSON.parse(jsonStr);
-    }
-    catch (e) {
-      rtn.diagnostic = buildError();
-      rtn.diagnostic.absFilePath = filePath;
-      rtn.diagnostic.header = `Error Parsing JSON`;
-      if (e instanceof Error) {
-        rtn.diagnostic.messageText = e.message;
-      }
-    }
+  try {
+    parseResult.data = JSON.parse(pkgJsonStr);
   }
-  else {
-    rtn.diagnostic = buildError();
-    rtn.diagnostic.absFilePath = filePath;
-    rtn.diagnostic.header = `Error Parsing JSON`;
-    rtn.diagnostic.messageText = `Invalid JSON input to parse`;
+  catch (e) {
+    parseResult.diagnostic = buildError();
+    parseResult.diagnostic.absFilePath = isString$1(pkgJsonFilePath) ? pkgJsonFilePath : undefined;
+    parseResult.diagnostic.header = `Error Parsing JSON`;
+    if (e instanceof Error) {
+      parseResult.diagnostic.messageText = e.message;
+    }
   }
-  return rtn;
+  return parseResult;
 };
 const SKIP_DEPS = ['@stencil/core'];
 
@@ -4000,7 +4019,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220531163847';
+const buildId = '20220621172432';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.13_7';
 const parse5Version = '6.0.1';
@@ -4008,8 +4027,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.16.0';
+const vermoji = '🚂';
+const version$3 = '2.17.0';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -10959,6 +10978,16 @@ MagicString$2.prototype.trimStart = function trimStart (charType) {
 	return this;
 };
 
+/**
+ * Parse CSS docstrings that Stencil supports, as documented here:
+ * https://stenciljs.com/docs/docs-json#css-variables
+ *
+ * Docstrings found in the supplied style text will be added to the
+ * `styleDocs` param
+ *
+ * @param styleDocs the array to hold formatted CSS docstrings
+ * @param styleText the CSS text we're working with
+ */
 function parseStyleDocs(styleDocs, styleText) {
   if (typeof styleText !== 'string') {
     return;
@@ -10975,10 +11004,18 @@ function parseStyleDocs(styleDocs, styleText) {
     styleText = styleText.substring(endIndex + CSS_DOC_END.length);
   }
 }
+/**
+ * Parse a CSS comment string and insert it into the provided array of
+ * style docstrings.
+ *
+ * @param styleDocs an array which will be modified with the docstring
+ * @param comment the comment string
+ */
 function parseCssComment(styleDocs, comment) {
   /**
    * @prop --max-width: Max width of the alert
    */
+  // (the above is an example of what these comments might look like)
   const lines = comment.split(/\r?\n/).map((line) => {
     line = line.trim();
     while (line.startsWith('*')) {
@@ -11006,11 +11043,19 @@ function parseCssComment(styleDocs, comment) {
       styleDocs.push(cssDoc);
     }
   });
-  return styleDocs;
 }
-const CSS_DOC_START = `/**`;
-const CSS_DOC_END = `*/`;
-const CSS_PROP_ANNOTATION = `@prop`;
+/**
+ * Opening syntax for a CSS docstring
+ */
+const CSS_DOC_START = '/**';
+/**
+ * Closing syntax for a CSS docstring
+ */
+const CSS_DOC_END = '*/';
+/**
+ * The `@prop` annotation we support within CSS docstrings
+ */
+const CSS_PROP_ANNOTATION = '@prop';
 
 /**
  * @license
@@ -11499,6 +11544,53 @@ const stripCssComments = (input) => {
   return returnValue;
 };
 
+/**
+ * A regular expression for matching CSS import statements
+ *
+ * According to https://developer.mozilla.org/en-US/docs/Web/CSS/@import
+ * the formal grammar for CSS import statements is:
+ *
+ * ```
+ * @import [ <url> | <string> ]
+ *     [ supports( [ <supports-condition> | <declaration> ] ) ]?
+ *     <media-query-list>? ;
+ * ```
+ *
+ * Thus the string literal `"@import"` will be followed by a `<url>` or a
+ * `<string>`, where a `<url>` may be a relative or absolute URL _or_ a `url()`
+ * function.
+ *
+ * Thus the regular expression needs to match:
+ *
+ * - the string `"@import
+ * - any amount of whitespace
+ * - a URL, comprised of:
+ *   - an optional `url(` function opener
+ *   - a non-greedy match on any characters (to match the argument to the URL
+ *   function)
+ *   - an optional `)` closing paren on the `url()` function
+ * - trailing characters after the URL, given by anything which doesn't match
+ *   the line-terminator `;`
+ *   - this can match media queries, support conditions, and so on
+ * - a line-terminating semicolon
+ *
+ * The regex has 4 capture groups:
+ *
+ * 1. `@import`
+ * 2. `url(`
+ * 3. characters after `url(`
+ * 4. all characters other than `;`, greedily matching
+ *
+ * We typically only care about group 4 here.
+ */
+const CSS_IMPORT_RE = /(@import)\s+(url\()?\s?(.*?)\s?\)?([^;]*);?/gi;
+/**
+ * Our main entry point to this module. This performs an async transformation
+ * of CSS input to ESM.
+ *
+ * @param input CSS input to be transformed to ESM
+ * @returns a promise wrapping transformed ESM output
+ */
 const transformCssToEsm = async (input) => {
   const results = transformCssToEsmModule(input);
   const optimizeResults = await optimizeCss$1({
@@ -11515,10 +11607,22 @@ const transformCssToEsm = async (input) => {
   results.styleText = optimizeResults.output;
   return generateTransformCssToEsm(input, results);
 };
+/**
+ * A sync function for transforming input CSS to ESM
+ *
+ * @param input the input CSS we're going to transform
+ * @returns transformed ESM output
+ */
 const transformCssToEsmSync = (input) => {
   const results = transformCssToEsmModule(input);
   return generateTransformCssToEsm(input, results);
 };
+/**
+ * Performs the actual transformation from CSS to ESM
+ *
+ * @param input input CSS to be transformed
+ * @returns ESM output
+ */
 const transformCssToEsmModule = (input) => {
   const results = {
     styleText: input.input,
@@ -11563,6 +11667,14 @@ const transformCssToEsmModule = (input) => {
   }
   return results;
 };
+/**
+ * Updated the `output` property on `results` with appropriate import statements for
+ * the CSS import tree and the module type.
+ *
+ * @param input the CSS to ESM transform input
+ * @param results the corresponding output
+ * @returns the modified ESM output
+ */
 const generateTransformCssToEsm = (input, results) => {
   const s = new MagicString$2('');
   if (input.module === 'cjs') {
@@ -11592,6 +11704,15 @@ const generateTransformCssToEsm = (input, results) => {
   results.output = s.toString();
   return results;
 };
+/**
+ * Get all of the CSS imports in a file
+ *
+ * @param varNames a set into which new names will be added
+ * @param cssText the CSS text in question
+ * @param filePath the file path to the file in question
+ * @param modeName the current mode name
+ * @returns an array of import objects
+ */
 const getCssToEsmImports = (varNames, cssText, filePath, modeName) => {
   const cssImports = [];
   if (!cssText.includes('@import')) {
@@ -11633,10 +11754,22 @@ const getCssToEsmImports = (varNames, cssText, filePath, modeName) => {
   }
   return cssImports;
 };
-const CSS_IMPORT_RE = /(@import)\s+(url\()?\s?(.*?)\s?\)?([^;]*);?/gi;
+/**
+ * Check if a module URL is a css node module
+ *
+ * @param url to check
+ * @returns whether or not it's a Css node module
+ */
 const isCssNodeModule$1 = (url) => {
   return url.startsWith('~');
 };
+/**
+ * Check if a given import is a local import or not (i.e. check that it
+ * is not importing from some other domain)
+ *
+ * @param srcImport the import to check
+ * @returns whether it's local or not
+ */
 const isLocalCssImport$1 = (srcImport) => {
   srcImport = srcImport.toLowerCase();
   if (srcImport.includes('url(')) {
@@ -11649,6 +11782,13 @@ const isLocalCssImport$1 = (srcImport) => {
   }
   return true;
 };
+/**
+ * Given a file path and a mode name, create an appropriate variable name
+ *
+ * @param filePath the path we want to use
+ * @param modeName the name for the current style mode (i.e. `md` or `ios` on Ionic)
+ * @returns an appropriate Css var name
+ */
 const createCssVarName = (filePath, modeName) => {
   let varName = path$5.basename(filePath);
   if (modeName && modeName !== DEFAULT_STYLE_MODE && !varName.includes(modeName)) {
@@ -11670,7 +11810,7 @@ const createWorkerMessageHandler = (sys) => {
     const fnArgs = msgToWorker.args.slice(1);
     const fn = workerCtx[fnName];
     if (typeof fn === 'function') {
-      return fn.apply(null, fnArgs);
+      return fn(...fnArgs);
     }
   };
 };
@@ -13785,8 +13925,8 @@ function generateBuildStats(config, buildCtx) {
 /**
  * Writes the files from the stats config to the file system
  * @param config the project build configuration
- * @param buildCtx An instance of the build which holds the details about the build
- * @returns
+ * @param data the information to write out to disk (as specified by each stats output target specified in the provided
+ * config)
  */
 async function writeBuildStats(config, data) {
   const statsTargets = config.outputTargets.filter(isOutputTargetStats);
@@ -15636,6 +15776,9 @@ class MockElement extends MockNode {
     this.shadowRoot = shadowRoot;
     return shadowRoot;
   }
+  blur() {
+    /**/
+  }
   get shadowRoot() {
     return this.__shadowRoot || null;
   }
@@ -15704,6 +15847,7 @@ class MockElement extends MockNode {
   get firstElementChild() {
     return this.children[0] || null;
   }
+  focus(_options) { }
   getAttribute(attrName) {
     if (attrName === 'style') {
       if (this.__style != null && this.__style.length > 0) {
@@ -16607,7 +16751,28 @@ function createElementNS(ownerDocument, namespaceURI, tagName) {
     return createElement(ownerDocument, tagName);
   }
   else if (namespaceURI === 'http://www.w3.org/2000/svg') {
-    return new MockSVGElement(ownerDocument, tagName);
+    switch (tagName.toLowerCase()) {
+      case 'text':
+      case 'tspan':
+      case 'tref':
+      case 'altglyph':
+      case 'textpath':
+        return new MockSVGTextContentElement(ownerDocument, tagName);
+      case 'circle':
+      case 'ellipse':
+      case 'image':
+      case 'line':
+      case 'path':
+      case 'polygon':
+      case 'polyline':
+      case 'rect':
+      case 'use':
+        return new MockSVGGraphicsElement(ownerDocument, tagName);
+      case 'svg':
+        return new MockSVGSVGElement(ownerDocument, tagName);
+      default:
+        return new MockSVGElement(ownerDocument, tagName);
+    }
   }
   else {
     return new MockElement(ownerDocument, tagName);
@@ -16754,6 +16919,98 @@ class MockScriptElement extends MockHTMLElement {
 patchPropAttributes(MockScriptElement.prototype, {
   type: String,
 });
+class MockDOMMatrix {
+  constructor() {
+    this.a = 1;
+    this.b = 0;
+    this.c = 0;
+    this.d = 1;
+    this.e = 0;
+    this.f = 0;
+    this.m11 = 1;
+    this.m12 = 0;
+    this.m13 = 0;
+    this.m14 = 0;
+    this.m21 = 0;
+    this.m22 = 1;
+    this.m23 = 0;
+    this.m24 = 0;
+    this.m31 = 0;
+    this.m32 = 0;
+    this.m33 = 1;
+    this.m34 = 0;
+    this.m41 = 0;
+    this.m42 = 0;
+    this.m43 = 0;
+    this.m44 = 1;
+    this.is2D = true;
+    this.isIdentity = true;
+  }
+  static fromMatrix() {
+    return new MockDOMMatrix();
+  }
+  inverse() {
+    return new MockDOMMatrix();
+  }
+  flipX() {
+    return new MockDOMMatrix();
+  }
+  flipY() {
+    return new MockDOMMatrix();
+  }
+  multiply() {
+    return new MockDOMMatrix();
+  }
+  rotate() {
+    return new MockDOMMatrix();
+  }
+  rotateAxisAngle() {
+    return new MockDOMMatrix();
+  }
+  rotateFromVector() {
+    return new MockDOMMatrix();
+  }
+  scale() {
+    return new MockDOMMatrix();
+  }
+  scaleNonUniform() {
+    return new MockDOMMatrix();
+  }
+  skewX() {
+    return new MockDOMMatrix();
+  }
+  skewY() {
+    return new MockDOMMatrix();
+  }
+  toJSON() { }
+  toString() { }
+  transformPoint() {
+    return new MockDOMPoint();
+  }
+  translate() {
+    return new MockDOMMatrix();
+  }
+}
+class MockDOMPoint {
+  constructor() {
+    this.w = 1;
+    this.x = 0;
+    this.y = 0;
+    this.z = 0;
+  }
+  toJSON() { }
+  matrixTransform() {
+    return new MockDOMMatrix();
+  }
+}
+class MockSVGRect {
+  constructor() {
+    this.height = 10;
+    this.width = 10;
+    this.x = 0;
+    this.y = 0;
+  }
+}
 class MockStyleElement extends MockHTMLElement {
   constructor(ownerDocument) {
     super(ownerDocument, 'style');
@@ -16786,9 +17043,6 @@ class MockSVGElement extends MockElement {
   get viewportElement() {
     return null;
   }
-  focus() {
-    /**/
-  }
   onunload() {
     /**/
   }
@@ -16806,6 +17060,27 @@ class MockSVGElement extends MockElement {
     return 0;
   }
 }
+class MockSVGGraphicsElement extends MockSVGElement {
+  getBBox(_options) {
+    return new MockSVGRect();
+  }
+  getCTM() {
+    return new MockDOMMatrix();
+  }
+  getScreenCTM() {
+    return new MockDOMMatrix();
+  }
+}
+class MockSVGSVGElement extends MockSVGGraphicsElement {
+  createSVGPoint() {
+    return new MockDOMPoint();
+  }
+}
+class MockSVGTextContentElement extends MockSVGGraphicsElement {
+  getComputedTextLength() {
+    return 0;
+  }
+}
 class MockBaseElement extends MockHTMLElement {
   constructor(ownerDocument) {
     super(ownerDocument, 'base');
@@ -41026,6 +41301,7 @@ const createComponentExport = (cmp) => {
  * 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
@@ -41194,9 +41470,9 @@ const fetchUrlSync = (url) => {
   return undefined;
 };
 
-const patchTsSystemFileSystem = (config, stencilSys, inMemoryFs, tsSys) => {
+const patchTsSystemFileSystem = (config, compilerSys, inMemoryFs, tsSys) => {
   const realpath = (path) => {
-    const rp = stencilSys.realpathSync(path);
+    const rp = compilerSys.realpathSync(path);
     if (isString$1(rp)) {
       return rp;
     }
@@ -41204,7 +41480,7 @@ const patchTsSystemFileSystem = (config, stencilSys, inMemoryFs, tsSys) => {
   };
   const getAccessibleFileSystemEntries = (path) => {
     try {
-      const entries = stencilSys.readDirSync(path || '.').sort();
+      const entries = compilerSys.readDirSync(path || '.').sort();
       const files = [];
       const directories = [];
       for (const absPath of entries) {
@@ -41229,13 +41505,13 @@ const patchTsSystemFileSystem = (config, stencilSys, inMemoryFs, tsSys) => {
     }
   };
   tsSys.createDirectory = (p) => {
-    stencilSys.createDirSync(p, { recursive: true });
+    compilerSys.createDirSync(p, { recursive: true });
   };
   tsSys.directoryExists = (p) => {
     const s = inMemoryFs.statSync(p);
     return s.isDirectory;
   };
-  tsSys.exit = stencilSys.exit;
+  tsSys.exit = compilerSys.exit;
   tsSys.fileExists = (p) => {
     let filePath = p;
     if (isRemoteUrl(p)) {
@@ -41244,17 +41520,17 @@ const patchTsSystemFileSystem = (config, stencilSys, inMemoryFs, tsSys) => {
     const s = inMemoryFs.statSync(filePath);
     return !!(s && s.isFile);
   };
-  tsSys.getCurrentDirectory = stencilSys.getCurrentDirectory;
-  tsSys.getExecutingFilePath = stencilSys.getCompilerExecutingPath;
+  tsSys.getCurrentDirectory = compilerSys.getCurrentDirectory;
+  tsSys.getExecutingFilePath = compilerSys.getCompilerExecutingPath;
   tsSys.getDirectories = (p) => {
-    const items = stencilSys.readDirSync(p);
+    const items = compilerSys.readDirSync(p);
     return items.filter((itemPath) => {
       const s = inMemoryFs.statSync(itemPath);
       return !!(s && s.exists && s.isDirectory);
     });
   };
   tsSys.readDirectory = (path, extensions, exclude, include, depth) => {
-    const cwd = stencilSys.getCurrentDirectory();
+    const cwd = compilerSys.getCurrentDirectory();
     // TODO(STENCIL-344): Replace `matchFiles` with a function that is publicly exposed
     return t.matchFiles(path, extensions, exclude, include, IS_CASE_SENSITIVE_FILE_NAMES, cwd, depth, getAccessibleFileSystemEntries, realpath);
   };
@@ -41281,9 +41557,9 @@ const patchTsSystemFileSystem = (config, stencilSys, inMemoryFs, tsSys) => {
   tsSys.writeFile = (p, data) => inMemoryFs.writeFile(p, data);
   return tsSys;
 };
-const patchTsSystemWatch = (stencilSys, tsSys) => {
+const patchTsSystemWatch = (compilerSystem, tsSys) => {
   tsSys.watchDirectory = (p, cb, recursive) => {
-    const watcher = stencilSys.watchDirectory(p, (filePath) => {
+    const watcher = compilerSystem.watchDirectory(p, (filePath) => {
       cb(filePath);
     }, recursive);
     return {
@@ -41293,7 +41569,7 @@ const patchTsSystemWatch = (stencilSys, tsSys) => {
     };
   };
   tsSys.watchFile = (p, cb) => {
-    const watcher = stencilSys.watchFile(p, (filePath, eventKind) => {
+    const watcher = compilerSystem.watchFile(p, (filePath, eventKind) => {
       if (eventKind === 'fileAdd') {
         cb(filePath, t.FileWatcherEventKind.Created);
       }
@@ -55436,6 +55712,7 @@ const addDefineCustomElementFunction = (tagNames, newStatements, caseStatements)
  * ```typescript
  * defineCustomElement(MyPrincipalComponent);
  * ```
+ * @param componentName the component's class name to use as the first argument to `defineCustomElement`
  * @returns the expression statement described above
  */
 function createAutoDefinitionExpression(componentName) {
@@ -55545,6 +55822,9 @@ const updateStencilCoreImports = (updatedCoreImportPath) => {
     };
   };
 };
+/**
+ * A set of imports which we don't want to remove from an output file
+ */
 const KEEP_IMPORTS = new Set([
   'h',
   'setMode',
@@ -55564,37 +55844,75 @@ const KEEP_IMPORTS = new Set([
   'setErrorHandler',
 ]);
 
+/**
+ * Main output target function for `dist-custom-elements`. This function just
+ * does some organizational work to call the other functions in this module,
+ * which do actual work of generating the rollup configuration, creating an
+ * entry chunk, running, the build, etc.
+ *
+ * @param config the user-supplied compiler configuration we're using
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @returns an empty Promise which won't resolve until the work is done!
+ */
 const outputCustomElements = async (config, compilerCtx, buildCtx) => {
+  var _a;
   if (!config.buildDist) {
     return;
   }
-  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
+  const outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
   if (outputTargets.length === 0) {
     return;
   }
   const bundlingEventMessage = 'generate custom elements';
   const timespan = buildCtx.createTimeSpan(`${bundlingEventMessage} started`);
-  await Promise.all(outputTargets.map((o) => bundleCustomElements$1(config, compilerCtx, buildCtx, o)));
+  await Promise.all(outputTargets.map((target) => bundleCustomElements$1(config, compilerCtx, buildCtx, target)));
   timespan.finish(`${bundlingEventMessage} finished`);
 };
+/**
+ * Get bundle options for our current build and compiler context which we'll use
+ * to generate a Rollup build and so on.
+ *
+ * @param config user-supplied Stencil configuration
+ * @param buildCtx the current build context
+ * @param compilerCtx the current compiler context
+ * @param outputTarget the outputTarget we're currently dealing with
+ * @returns bundle options suitable for generating a rollup configuration
+ */
+const getBundleOptions = (config, buildCtx, compilerCtx, outputTarget) => ({
+  id: 'customElements',
+  platform: 'client',
+  conditionals: getCustomElementsBuildConditionals(config, buildCtx.components),
+  customTransformers: getCustomElementCustomTransformer(config, compilerCtx, buildCtx.components, outputTarget),
+  externalRuntime: !!outputTarget.externalRuntime,
+  inlineWorkers: true,
+  inputs: {
+    // Here we prefix our index chunk with '\0' to tell Rollup that we're
+    // going to be using virtual modules with this module. A leading '\0'
+    // prevents other plugins from messing with the module. We generate a
+    // string for the index chunk below in the `loader` property.
+    //
+    // @see {@link https://rollupjs.org/guide/en/#conventions} for more info.
+    index: '\0core',
+  },
+  loader: {
+    '\0core': generateEntryPoint$1(outputTarget),
+  },
+  inlineDynamicImports: outputTarget.inlineDynamicImports,
+  preserveEntrySignatures: 'allow-extension',
+});
+/**
+ * Get bundle options for rollup, run the rollup build, optionally minify the
+ * output, and write files to disk.
+ * @param config user-supplied Stencil configuration
+ * @param buildCtx the current build context
+ * @param compilerCtx the current compiler context
+ * @param outputTarget the outputTarget we're currently dealing with
+ * @returns an empty promise
+ */
 const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarget) => {
   try {
-    const bundleOpts = {
-      id: 'customElements',
-      platform: 'client',
-      conditionals: getCustomElementsBuildConditionals(config, buildCtx.components),
-      customTransformers: getCustomElementCustomTransformer(config, compilerCtx, buildCtx.components, outputTarget),
-      externalRuntime: !!outputTarget.externalRuntime,
-      inlineWorkers: true,
-      inputs: {
-        index: '\0core',
-      },
-      loader: {
-        '\0core': generateEntryPoint$1(outputTarget),
-      },
-      inlineDynamicImports: outputTarget.inlineDynamicImports,
-      preserveEntrySignatures: 'allow-extension',
-    };
+    const bundleOpts = getBundleOptions(config, buildCtx, compilerCtx, outputTarget);
     addCustomElementInputs(buildCtx, bundleOpts);
     const build = await bundleOutput(config, compilerCtx, buildCtx, bundleOpts);
     if (build) {
@@ -55607,6 +55925,18 @@ const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarge
         hoistTransitiveImports: false,
         preferConst: true,
       });
+      // the output target should have been validated at this point - as a result, we expect this field
+      // to have been backfilled if it wasn't provided
+      const outputTargetDir = outputTarget.dir;
+      // besides, if it isn't here we do a diagnostic and an early return
+      if (!isString$1(outputTargetDir)) {
+        buildCtx.diagnostics.push({
+          level: 'error',
+          type: 'build',
+          messageText: 'dist-custom-elements output target provided with no output target directory!',
+        });
+        return;
+      }
       const minify = outputTarget.externalRuntime || outputTarget.minify !== true ? false : config.minifyJs;
       const files = rollupOutput.output.map(async (bundle) => {
         if (bundle.type === 'chunk') {
@@ -55621,15 +55951,15 @@ const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarge
           buildCtx.diagnostics.push(...optimizeResults.diagnostics);
           if (!hasError(optimizeResults.diagnostics) && typeof optimizeResults.output === 'string') {
             code = optimizeResults.output;
-            sourceMap = optimizeResults.sourceMap;
           }
-          if (sourceMap) {
+          if (optimizeResults.sourceMap) {
+            sourceMap = optimizeResults.sourceMap;
             code = code + getSourceMappingUrlForEndOfFile(bundle.fileName);
-            await compilerCtx.fs.writeFile(join(outputTarget.dir, bundle.fileName + '.map'), JSON.stringify(sourceMap), {
+            await compilerCtx.fs.writeFile(join(outputTargetDir, bundle.fileName + '.map'), JSON.stringify(sourceMap), {
               outputTargetType: outputTarget.type,
             });
           }
-          await compilerCtx.fs.writeFile(join(outputTarget.dir, bundle.fileName), code, {
+          await compilerCtx.fs.writeFile(join(outputTargetDir, bundle.fileName), code, {
             outputTargetType: outputTarget.type,
           });
         }
@@ -55648,6 +55978,8 @@ const bundleCustomElements$1 = async (config, compilerCtx, buildCtx, outputTarge
  */
 const addCustomElementInputs = (buildCtx, bundleOpts) => {
   const components = buildCtx.components;
+  // an array to store the imports of these modules that we're going to add to our entry chunk
+  const indexImports = [];
   components.forEach((cmp) => {
     const exp = [];
     const exportName = dashToPascalCase$1(cmp.tagName);
@@ -55656,16 +55988,25 @@ const addCustomElementInputs = (buildCtx, bundleOpts) => {
     const coreKey = `\0${exportName}`;
     if (cmp.isPlain) {
       exp.push(`export { ${importName} as ${exportName} } from '${cmp.sourceFilePath}';`);
+      indexImports.push(`export { {${exportName} } from '${coreKey}';`);
     }
     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;`);
+      // Here we push an export (with a rename for `defineCustomElement` for
+      // this component onto our array which references the `coreKey` (prefixed
+      // with `\0`). We have to do this so that our import is referencing the
+      // correct virtual module, if we instead referenced, for instance,
+      // `cmp.sourceFilePath`, we would end up with duplicated modules in our
+      // output.
+      indexImports.push(`export { ${exportName}, defineCustomElement as defineCustomElement${exportName} } from '${coreKey}';`);
     }
     bundleOpts.inputs[cmp.tagName] = coreKey;
     bundleOpts.loader[coreKey] = exp.join('\n');
   });
+  bundleOpts.loader['\0core'] += indexImports.join('\n');
 };
 /**
  * Generate the entrypoint (`index.ts` file) contents for the `dist-custom-elements` output target
@@ -55683,6 +56024,7 @@ const generateEntryPoint$1 = (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
@@ -56811,9 +57153,15 @@ const addLazyElementGetter = (classMembers, moduleFile, cmp) => {
 
 /**
  * Adds static "style" getter within the class
+ * ```typescript
  * const MyComponent = class {
  *   static get style() { return "styles"; }
  * }
+ * ```
+ * @param classMembers a class to existing members of a class. **this parameter will be mutated** rather than returning
+ * a cloned version
+ * @param cmp the metadata associated with the component being evaluated
+ * @param commentOriginalSelector if `true`, add a comment with the original CSS selector to the style.
  */
 const addStaticStyleGetterWithinClass = (classMembers, cmp, commentOriginalSelector) => {
   const styleLiteral = getStyleLiteral(cmp, commentOriginalSelector);
@@ -56823,11 +57171,15 @@ const addStaticStyleGetterWithinClass = (classMembers, cmp, commentOriginalSelec
 };
 /**
  * Adds static "style" property to the class variable.
+ * ```typescript
  * const MyComponent = class {}
  * MyComponent.style = "styles";
+ * ```
+ * @param styleStatements a list of statements containing style assignments to a class
+ * @param cmp the metadata associated with the component being evaluated
  */
-const addStaticStylePropertyToClass = (styleStatements, cmp, commentOriginalSelector) => {
-  const styleLiteral = getStyleLiteral(cmp, commentOriginalSelector);
+const addStaticStylePropertyToClass = (styleStatements, cmp) => {
+  const styleLiteral = getStyleLiteral(cmp, false);
   if (styleLiteral) {
     const statement = t.createStatement(t.createAssignment(t.createPropertyAccess(t.createIdentifier(cmp.componentClassName), 'style'), styleLiteral));
     styleStatements.push(statement);
@@ -57429,7 +57781,7 @@ const updateLazyComponentMembers = (transformOpts, styleStatements, classNode, m
   addWatchers(classMembers, cmp);
   transformHostData(classMembers, moduleFile);
   if (transformOpts.style === 'static') {
-    addStaticStylePropertyToClass(styleStatements, cmp, false);
+    addStaticStylePropertyToClass(styleStatements, cmp);
   }
   return classMembers;
 };
@@ -59664,29 +60016,38 @@ const relDts$1 = (fromPath, dtsPath) => {
  * @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 typesDir the path to the directory where type declarations are saved
  */
-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)));
+const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, typesDir) => {
+  var _a;
+  const outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
+  await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, typesDir, 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 typesDir path to the directory where type declarations are saved
  * @param outputTarget the output target for which types are being currently generated
  */
-const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, distDtsFilePath, outputTarget) => {
+const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, typesDir, outputTarget) => {
+  // the path where we're going to write the typedef for the whole dist-custom-elements output
   const customElementsDtsPath = join(outputTarget.dir, 'index.d.ts');
-  const componentsDtsRelPath = relDts(outputTarget.dir, distDtsFilePath);
+  // the directory where types for the individual components are written
+  const componentsTypeDirectoryPath = relative$1(outputTarget.dir, join(typesDir, 'components'));
+  const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
   const code = [
     `/* ${config.namespace} custom elements */`,
-    ``,
-    `import type { Components, JSX } from "${componentsDtsRelPath}";`,
+    ...components.map((component) => {
+      const exportName = dashToPascalCase$1(component.tagName);
+      const importName = component.componentClassName;
+      // typedefs for individual components can be found under paths like
+      // $TYPES_DIR/components/my-component/my-component.d.ts
+      const componentDTSPath = join(componentsTypeDirectoryPath, component.tagName, component.tagName);
+      return `export { ${importName} as ${exportName} } from '${componentDTSPath}';`;
+    }),
     ``,
     `/**`,
     ` * Used to manually set the base path where assets can be found.`,
@@ -59706,10 +60067,8 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
     `  rel?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;`,
     `}`,
     `export declare const setPlatformOptions: (opts: SetPlatformOptions) => void;`,
-    ``,
-    `export type { Components, JSX };`,
-    ``,
   ];
+  const componentsDtsRelPath = relDts(outputTarget.dir, join(typesDir, 'components.d.ts'));
   const usersIndexJsPath = join(config.srcDir, 'index.ts');
   const hasUserIndex = await compilerCtx.fs.access(usersIndexJsPath);
   if (hasUserIndex) {
@@ -59722,7 +60081,6 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
   await compilerCtx.fs.writeFile(customElementsDtsPath, code.join('\n') + `\n`, {
     outputTargetType: outputTarget.type,
   });
-  const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
   await Promise.all(components.map(async (cmp) => {
     const dtsCode = generateCustomElementType(componentsDtsRelPath, cmp);
     const fileName = `${cmp.tagName}.d.ts`;
@@ -59796,20 +60154,21 @@ const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget)
   const srcDtsFiles = srcDirItems.filter((srcItem) => srcItem.isFile && isDtsFile$1(srcItem.absPath));
   // Copy .d.ts files from src to dist
   // In addition, all references to @stencil/core are replaced
-  let distDtsFilePath;
-  await Promise.all(srcDtsFiles.map(async (srcDtsFile) => {
+  const copiedDTSFilePaths = await Promise.all(srcDtsFiles.map(async (srcDtsFile) => {
     const relPath = relative$1(config.srcDir, srcDtsFile.absPath);
     const distPath = join(outputTarget.typesDir, relPath);
     const originalDtsContent = await compilerCtx.fs.readFile(srcDtsFile.absPath);
     const distDtsContent = updateStencilTypesImports(outputTarget.typesDir, distPath, originalDtsContent);
     await compilerCtx.fs.writeFile(distPath, distDtsContent);
-    distDtsFilePath = distPath;
+    return distPath;
   }));
+  const distDtsFilePath = copiedDTSFilePaths.slice(-1)[0];
   const distPath = outputTarget.typesDir;
   await generateAppTypes(config, compilerCtx, buildCtx, distPath);
+  const { typesDir } = outputTarget;
   if (distDtsFilePath) {
-    await generateCustomElementsTypes(config, compilerCtx, buildCtx, distDtsFilePath);
     await generateCustomElementsBundleTypes(config, compilerCtx, buildCtx, distDtsFilePath);
+    await generateCustomElementsTypes(config, compilerCtx, buildCtx, typesDir);
   }
 };
 
@@ -62280,7 +62639,7 @@ const getRelativeDts = (config, srcPath, emitDtsPath) => {
     emitDtsPath = join(emitDtsPath, '..');
     srcPath = normalizePath$1(join(srcPath, '..'));
   }
-  return join.apply(null, parts.reverse());
+  return join(...parts.reverse());
 };
 
 const outputServiceWorkers = async (config, buildCtx) => {
@@ -62758,9 +63117,16 @@ const createInMemoryFs = (sys) => {
     return data.exists;
   };
   /**
-   * Synchronous!!! Do not use!!!
+   * **Synchronous!!! Do not use!!!**
    * (Only typescript transpiling is allowed to use)
-   * @param filePath
+   *
+   * Synchronously get information about a file from a provided path. This function will attempt to use an in-memory
+   * cache before performing a blocking read.
+   *
+   * In the event of a cache hit, the content from the cache will be returned and skip the read.
+   *
+   * @param filePath the path to the file to read
+   * @returns `true` if the file exists, `false` otherwise
    */
   const accessSync = (filePath) => {
     const item = getItem(filePath);
@@ -62932,9 +63298,19 @@ const createInMemoryFs = (sys) => {
     return fileText;
   };
   /**
-   * Synchronous!!! Do not use!!!
+   * **Synchronous!!! Do not use!!!**
    * (Only typescript transpiling is allowed to use)
-   * @param filePath
+   *
+   * Synchronously read a file from a provided path. This function will attempt to use an in-memory cache before
+   * performing a blocking read in the following circumstances:
+   * - no `opts` are provided
+   * - the `useCache` member on `opts` is set to `true`, or is not set
+   *
+   * In the event of a cache hit, the content from the cache will be returned and skip the read.
+   *
+   * @param filePath the path to the file to read
+   * @param opts a configuration to use when reading a file
+   * @returns the contents of the file (read from either disk or the cache).
    */
   const readFileSync = (filePath, opts) => {
     if (opts == null || opts.useCache === true || opts.useCache === undefined) {
@@ -63027,10 +63403,13 @@ const createInMemoryFs = (sys) => {
     };
   };
   /**
-   * Synchronous!!! Do not use!!!
-   * Always returns an object, does not throw errors.
+   * **Synchronous!!! Do not use!!!**
    * (Only typescript transpiling is allowed to use)
-   * @param itemPath
+   *
+   * Searches an in-memory cache for an item at the provided path. Always returns an object, **does not throw errors**.
+   *
+   * @param itemPath the path to the file to read
+   * @returns an object describing the item found at the provided `itemPath`
    */
   const statSync = (itemPath) => {
     const item = getItem(itemPath);
@@ -63584,37 +63963,76 @@ const filesChanged = (buildCtx) => {
   // files changed include updated, added and deleted
   return unique([...buildCtx.filesUpdated, ...buildCtx.filesAdded, ...buildCtx.filesDeleted]).sort();
 };
-const scriptsAdded = (buildCtx) => {
-  // collect all the scripts that were added
-  return buildCtx.filesAdded
-    .filter((f) => {
-    return SCRIPT_EXT.some((ext) => f.endsWith(ext.toLowerCase()));
-  })
-    .map((f) => basename(f));
-};
-const scriptsDeleted = (buildCtx) => {
-  // collect all the scripts that were deleted
-  return buildCtx.filesDeleted
-    .filter((f) => {
-    return SCRIPT_EXT.some((ext) => f.endsWith(ext.toLowerCase()));
-  })
-    .map((f) => basename(f));
-};
-const hasScriptChanges = (buildCtx) => {
-  return buildCtx.filesChanged.some((f) => {
-    const ext = getExt(f);
-    return SCRIPT_EXT.includes(ext);
-  });
-};
-const hasStyleChanges = (buildCtx) => {
-  return buildCtx.filesChanged.some((f) => {
-    const ext = getExt(f);
-    return STYLE_EXT.includes(ext);
-  });
-};
+/**
+ * Unary helper function mapping string to string and wrapping `basename`,
+ * which normally takes two string arguments. This means it cannot be passed
+ * to `Array.prototype.map`, but this little helper can!
+ *
+ * @param filePath a filepath to check out
+ * @returns the basename for that filepath
+ */
+const unaryBasename = (filePath) => basename(filePath);
+/**
+ * Get the file extension for a path
+ *
+ * @param filePath a path
+ * @returns the file extension (well, characters after the last `'.'`)
+ */
 const getExt = (filePath) => filePath.split('.').pop().toLowerCase();
+/**
+ * Script extensions which we want to be able to recognize
+ */
 const SCRIPT_EXT = ['ts', 'tsx', 'js', 'jsx'];
+/**
+ * Helper to check if a filepath has a script extension
+ *
+ * @param filePath a file extension
+ * @returns whether the filepath has a script extension or not
+ */
+const hasScriptExt = (filePath) => SCRIPT_EXT.includes(getExt(filePath));
 const STYLE_EXT = ['css', 'scss', 'sass', 'pcss', 'styl', 'stylus', 'less'];
+/**
+ * Helper to check if a filepath has a style extension
+ *
+ * @param filePath a file extension to check
+ * @returns whether the filepath has a style extension or not
+ */
+const hasStyleExt = (filePath) => STYLE_EXT.includes(getExt(filePath));
+/**
+ * Get all scripts from a build context that were added
+ *
+ * @param buildCtx the build context
+ * @returns an array of filepaths that were added
+ */
+const scriptsAdded = (buildCtx) => buildCtx.filesAdded.filter(hasScriptExt).map(unaryBasename);
+/**
+ * Get all scripts from a build context that were deleted
+ *
+ * @param buildCtx the build context
+ * @returns an array of deleted filepaths
+ */
+const scriptsDeleted = (buildCtx) => buildCtx.filesDeleted.filter(hasScriptExt).map(unaryBasename);
+/**
+ * Check whether a build has script changes
+ *
+ * @param buildCtx the build context
+ * @returns whether or not there are script changes
+ */
+const hasScriptChanges = (buildCtx) => buildCtx.filesChanged.some(hasScriptExt);
+/**
+ * Check whether a build has style changes
+ *
+ * @param buildCtx the build context
+ * @returns whether or not there are style changes
+ */
+const hasStyleChanges = (buildCtx) => buildCtx.filesChanged.some(hasStyleExt);
+/**
+ * Check whether a build has html changes
+ *
+ * @param config the current config
+ * @param buildCtx the build context
+ * @returns whether or not HTML files were changed
+ */
 const hasHtmlChanges = (config, buildCtx) => {
   const anyHtmlChanged = buildCtx.filesChanged.some((f) => f.toLowerCase().endsWith('.html'));
   if (anyHtmlChanged) {
@@ -64541,7 +64959,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.16.0",
+		version: "2.17.0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -65919,7 +66337,7 @@ const validateConfig = (userConfig = {}) => {
   setBooleanConfig(config, 'sourceMap', null, typeof config.sourceMap === 'undefined' ? false : config.sourceMap);
   setBooleanConfig(config, 'watch', 'watch', false);
   setBooleanConfig(config, 'buildDocs', 'docs', !config.devMode);
-  setBooleanConfig(config, 'buildDist', null, !config.devMode || config.buildEs5);
+  setBooleanConfig(config, 'buildDist', 'esm', !config.devMode || config.buildEs5);
   setBooleanConfig(config, 'profile', 'profile', config.devMode);
   setBooleanConfig(config, 'writeLog', 'log', false);
   setBooleanConfig(config, 'buildAppCore', null, true);
@@ -66139,6 +66557,21 @@ const createDefaultTsConfig = (config) => JSON.stringify({
 const hasSrcDirectoryInclude = (includeProp, src) => Array.isArray(includeProp) && includeProp.includes(src);
 const hasStencilConfigInclude = (includeProp) => Array.isArray(includeProp) && includeProp.includes('stencil.config.ts');
 
+/**
+ * Load and validate a configuration to use throughout the lifetime of any Stencil task (build, test, etc.).
+ *
+ * Users can provide configurations multiple ways simultaneously:
+ * - as an object of the `init` argument to this function
+ * - through a path to a configuration file that exists on disk
+ *
+ * In the case of both being present, the two configurations will be merged. The fields of the former will take precedence
+ * over the fields of the latter.
+ *
+ * @param init the initial configuration provided by the user (or generated by Stencil) used to bootstrap configuration
+ * loading and validation
+ * @returns the results of loading a configuration
+ * @public
+ */
 const loadConfig = async (init = {}) => {
   const results = {
     config: null,
@@ -66210,6 +66643,15 @@ const loadConfig = async (init = {}) => {
   }
   return results;
 };
+/**
+ * Load a Stencil configuration file from disk
+ * @param sys the underlying System entity to use to interact with the operating system
+ * @param diagnostics a series of diagnostics used to track errors & warnings throughout the loading process. Entries
+ * may be added to this list in the event of an error.
+ * @param configPath the path to the configuration file to load
+ * @returns an unvalidated configuration. In the event of an error, additional diagnostics may be pushed to the
+ * provided `diagnostics` argument and `null` will be returned.
+ */
 const loadConfigFile = async (sys, diagnostics, configPath) => {
   let config = null;
   if (isString$1(configPath)) {
@@ -66229,6 +66671,15 @@ const loadConfigFile = async (sys, diagnostics, configPath) => {
   }
   return config;
 };
+/**
+ * Load the configuration file, based on the environment that Stencil is being run in
+ * @param sys the underlying System entity to use to interact with the operating system
+ * @param diagnostics a series of diagnostics used to track errors & warnings throughout the loading process. Entries
+ * may be added to this list in the event of an error.
+ * @param configFilePath the path to the configuration file to load
+ * @returns an unvalidated configuration. In the event of an error, additional diagnostics may be pushed to the
+ * provided `diagnostics` argument and `null` will be returned.
+ */
 const evaluateConfigFile = async (sys, diagnostics, configFilePath) => {
   let configFileData = null;
   try {
@@ -66253,6 +66704,16 @@ const evaluateConfigFile = async (sys, diagnostics, configFilePath) => {
   }
   return configFileData;
 };
+/**
+ * Transpiles the provided TypeScript source text into JavaScript.
+ *
+ * This function is intended to be used on a `stencil.config.ts` file
+ *
+ * @param diagnostics a collection of compiler diagnostics to check as a part of the compilation process
+ * @param sourceText the text to transpile
+ * @param filePath the name of the file to transpile
+ * @returns the transpiled text. If there are any diagnostics in the provided collection, the provided source is returned
+ */
 const transpileTypedConfig = (diagnostics, sourceText, filePath) => {
   // let's transpile an awesome stencil.config.ts file into
   // a boring stencil.config.js file
@@ -66454,6 +66915,10 @@ const convertStaticToMeta = (config, compilerCtx, buildCtx, typeChecker, collect
 
 /**
  * Stand-alone compiling of a single string
+ * @param config the Stencil configuration to use in the compilation process
+ * @param input the string to compile
+ * @param transformOpts a configuration object for how the string is compiled
+ * @returns the results of compiling the provided input string
  */
 const transpileModule = (config, input, transformOpts) => {
   if (!config.logger) {