@stencil/core 2.17.0 → 2.17.2

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.17.0 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.17.2 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -727,12 +727,27 @@ const trimFalsy = (data) => {
   return arr;
 };
 
-const toLowerCase = (str) => str.toLowerCase();
-const toDashCase = (str) => toLowerCase(str
-  .replace(/([A-Z0-9])/g, (g) => ' ' + g[0])
+/**
+ * Convert a string from PascalCase to dash-case
+ *
+ * @param str the string to convert
+ * @returns a converted string
+ */
+const toDashCase = (str) => str
+  .replace(/([A-Z0-9])/g, (match) => ` ${match[0]}`)
   .trim()
-  .replace(/ /g, '-'));
-const dashToPascalCase$1 = (str) => toLowerCase(str)
+  .split(' ')
+  .join('-')
+  .toLowerCase();
+/**
+ * Convert a string from dash-case / kebab-case to PascalCase (or CamelCase,
+ * or whatever you call it!)
+ *
+ * @param str a string to convert
+ * @returns a converted string
+ */
+const dashToPascalCase$1 = (str) => str
+  .toLowerCase()
   .split('-')
   .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
   .join('');
@@ -789,8 +804,8 @@ const pluck = (obj, keys) => {
     return final;
   }, {});
 };
-const isBoolean$1 = (v) => typeof v === 'boolean';
 const isDefined = (v) => v !== null && v !== undefined;
+const isBoolean$1 = (v) => typeof v === 'boolean';
 const isFunction = (v) => typeof v === 'function';
 const isNumber$1 = (v) => typeof v === 'number';
 const isObject$4 = (val) => val != null && typeof val === 'object' && Array.isArray(val) === false;
@@ -883,24 +898,37 @@ const buildWarn = (diagnostics) => {
   diagnostics.push(diagnostic);
   return diagnostic;
 };
-const buildJsonFileError = (compilerCtx, diagnostics, jsonFilePath, msg, pkgKey) => {
+/**
+ * Create a diagnostic message suited for representing an error in a JSON
+ * file. This includes information about the exact lines in the JSON file which
+ * caused the error and the path to the file.
+ *
+ * @param compilerCtx the current compiler context
+ * @param diagnostics a list of diagnostics used as a return param
+ * @param jsonFilePath the path to the JSON file where the error occurred
+ * @param msg the error message
+ * @param jsonField the key for the field which caused the error, used for finding
+ * the error line in the original JSON file
+ * @returns a reference to the newly-created diagnostic
+ */
+const buildJsonFileError = (compilerCtx, diagnostics, jsonFilePath, msg, jsonField) => {
   const err = buildError(diagnostics);
   err.messageText = msg;
   err.absFilePath = jsonFilePath;
-  if (typeof pkgKey === 'string') {
+  if (typeof jsonField === 'string') {
     try {
       const jsonStr = compilerCtx.fs.readFileSync(jsonFilePath);
       const lines = jsonStr.replace(/\r/g, '\n').split('\n');
       for (let i = 0; i < lines.length; i++) {
         const txtLine = lines[i];
-        const txtIndex = txtLine.indexOf(pkgKey);
+        const txtIndex = txtLine.indexOf(jsonField);
         if (txtIndex > -1) {
           const warnLine = {
             lineIndex: i,
             lineNumber: i + 1,
             text: txtLine,
             errorCharStart: txtIndex,
-            errorLength: pkgKey.length,
+            errorLength: jsonField.length,
           };
           err.lineNumber = warnLine.lineNumber;
           err.columnNumber = txtIndex + 1;
@@ -1631,7 +1659,7 @@ const isDtsFile$1 = (filePath) => {
 /**
  * Generate the preamble to be placed atop the main file of the build
  * @param config the Stencil configuration file
- * @return the generated preamble
+ * @returns the generated preamble
  */
 const generatePreamble = (config) => {
   const { preamble } = config;
@@ -2026,10 +2054,14 @@ const buildEvents = () => {
   };
 };
 
+/**
+ * Creates an instance of a logger
+ * @returns the new logger instance
+ */
 const createLogger = () => {
   let useColors = IS_BROWSER_ENV;
   let level = 'info';
-  const logger = {
+  return {
     enableColors: (uc) => (useColors = uc),
     getLevel: () => level,
     setLevel: (l) => (level = l),
@@ -2056,7 +2088,6 @@ const createLogger = () => {
       diagnostics.forEach((diagnostic) => logDiagnostic(diagnostic, useColors));
     },
   };
-  return logger;
 };
 const logDiagnostic = (diagnostic, useColors) => {
   let color = BLUE;
@@ -2346,8 +2377,16 @@ const getPackageDirPath = (p, moduleId) => {
   return null;
 };
 
+/**
+ * A fetch wrapper which dispatches to `sys.fetch` if present, and otherwise
+ * uses `global.fetch`.
+ *
+ * @param sys a compiler system object
+ * @param input a `RequestInfo` object
+ * @param init an optional `RequestInit` object
+ * @returns a Promise wrapping a response
+ */
 const httpFetch = (sys, input, init) => {
-  console.trace(input);
   if (sys && isFunction(sys.fetch)) {
     return sys.fetch(input, init);
   }
@@ -2355,10 +2394,16 @@ const httpFetch = (sys, input, init) => {
 };
 const packageVersions = new Map();
 const known404Urls = new Set();
-const getStencilRootUrl = (compilerExe) => new URL('../', compilerExe).href;
-const getStencilModuleUrl = (compilerExe, p) => {
-  p = normalizePath$1(p);
-  let parts = p.split('/');
+/**
+ * Get the URL for a Stencil module given the path to the compiler
+ *
+ * @param compilerExe the path to the compiler executable
+ * @param path the path to the module or file in question
+ * @returns a URL for the file of interest
+ */
+const getStencilModuleUrl = (compilerExe, path) => {
+  path = normalizePath$1(path);
+  let parts = path.split('/');
   const nmIndex = parts.lastIndexOf('node_modules');
   if (nmIndex > -1 && nmIndex < parts.length - 1) {
     parts = parts.slice(nmIndex + 1);
@@ -2368,9 +2413,10 @@ const getStencilModuleUrl = (compilerExe, p) => {
     else {
       parts = parts.slice(1);
     }
-    p = parts.join('/');
+    path = parts.join('/');
   }
-  return new URL('./' + p, getStencilRootUrl(compilerExe)).href;
+  const stencilRootUrl = new URL('../', compilerExe).href;
+  return new URL('./' + path, stencilRootUrl).href;
 };
 const getCommonDirUrl = (sys, pkgVersions, dirPath, fileName) => getNodeModuleFetchUrl(sys, pkgVersions, dirPath) + '/' + fileName;
 const getNodeModuleFetchUrl = (sys, pkgVersions, filePath) => {
@@ -4019,7 +4065,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220621172432';
+const buildId = '20220801155719';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.13_7';
 const parse5Version = '6.0.1';
@@ -4027,8 +4073,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.17.0';
+const vermoji = '🍤';
+const version$3 = '2.17.2';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -4577,6 +4623,17 @@ const createSystem = (c) => {
 };
 
 let cssProcessor;
+/**
+ * Autoprefix a CSS string, adding vendor prefixes to make sure that what
+ * is written in the CSS will render correctly in our range of supported browsers.
+ * This function uses PostCSS in compbination with the Autoprefix plugin to
+ * automatically add vendor prefixes based on a list of browsers which we want
+ * to support.
+ *
+ * @param cssText the text to be prefixed
+ * @param opts an optional param with options for Autoprefixer
+ * @returns a Promise wrapping some prefixed CSS as well as diagnostics
+ */
 const autoprefixCss = async (cssText, opts) => {
   const output = {
     output: cssText,
@@ -4586,7 +4643,7 @@ const autoprefixCss = async (cssText, opts) => {
     return output;
   }
   try {
-    const autoprefixerOpts = opts != null && typeof opts === 'object' ? opts : DEFAULT_AUTOPREFIX_LEGACY;
+    const autoprefixerOpts = opts != null && typeof opts === 'object' ? opts : DEFAULT_AUTOPREFIX_OPTIONS;
     const processor = getProcessor(autoprefixerOpts);
     const result = await processor.process(cssText, { map: null });
     result.warnings().forEach((warning) => {
@@ -4642,6 +4699,12 @@ const autoprefixCss = async (cssText, opts) => {
   }
   return output;
 };
+/**
+ * Get the processor for PostCSS and the Autoprefixer plugin
+ *
+ * @param autoprefixerOpts Options for Autoprefixer
+ * @returns postCSS with the Autoprefixer plugin applied
+ */
 const getProcessor = (autoprefixerOpts) => {
   const { postcss, autoprefixer } = requireFunc('../sys/node/autoprefixer.js');
   if (!cssProcessor) {
@@ -4649,7 +4712,19 @@ const getProcessor = (autoprefixerOpts) => {
   }
   return cssProcessor;
 };
-const DEFAULT_AUTOPREFIX_LEGACY = {
+/**
+ * Default options for the Autoprefixer PostCSS plugin. See the documentation:
+ * https://github.com/postcss/autoprefixer#options for a complete list.
+ *
+ * This default option set will:
+ *
+ * - override the default browser list (`overrideBrowserslist`)
+ * - turn off the visual cascade (`cascade`)
+ * - disable auto-removing outdated prefixes (`remove`)
+ * - set `flexbox` to `"no-2009"`, which limits prefixing for flexbox to the
+ *   final and IE 10 versions of the specification
+ */
+const DEFAULT_AUTOPREFIX_OPTIONS = {
   overrideBrowserslist: ['last 2 versions', 'iOS >= 9', 'Android >= 4.4', 'Explorer >= 11', 'ExplorerMobile >= 11'],
   cascade: false,
   remove: false,
@@ -5445,6 +5520,13 @@ const resolveStylesheetUrl = async (nodes, resolveUrl, resolved) => {
   }
 };
 
+/**
+ * Optimize a CSS file, optionally running an autoprefixer and a minifier
+ * depending on the options set on the input options argument.
+ *
+ * @param inputOpts input CSS options
+ * @returns a promise wrapping the optimized output
+ */
 const optimizeCss$1 = async (inputOpts) => {
   let result = {
     output: inputOpts.input,
@@ -11508,6 +11590,12 @@ const parseImportPath = (importPath) => {
   return parsedPath;
 };
 
+/**
+ * Strip out comments from some CSS
+ *
+ * @param input the string we'd like to de-comment
+ * @returns de-commented CSS!
+ */
 const stripCssComments = (input) => {
   let isInsideString = null;
   let currentCharacter = '';
@@ -14864,6 +14952,25 @@ class MockMouseEvent extends MockEvent {
     }
   }
 }
+class MockUIEvent extends MockEvent {
+  constructor(type, uiEventInitDic) {
+    super(type);
+    this.detail = null;
+    this.view = null;
+    if (uiEventInitDic != null) {
+      Object.assign(this, uiEventInitDic);
+    }
+  }
+}
+class MockFocusEvent extends MockUIEvent {
+  constructor(type, focusEventInitDic) {
+    super(type);
+    this.relatedTarget = null;
+    if (focusEventInitDic != null) {
+      Object.assign(this, focusEventInitDic);
+    }
+  }
+}
 class MockEventListener {
   constructor(type, handler) {
     this.type = type;
@@ -15777,7 +15884,7 @@ class MockElement extends MockNode {
     return shadowRoot;
   }
   blur() {
-    /**/
+    dispatchEvent(this, new MockFocusEvent('blur', { relatedTarget: null, bubbles: true, cancelable: true, composed: true }));
   }
   get shadowRoot() {
     return this.__shadowRoot || null;
@@ -15847,7 +15954,9 @@ class MockElement extends MockNode {
   get firstElementChild() {
     return this.children[0] || null;
   }
-  focus(_options) { }
+  focus(_options) {
+    dispatchEvent(this, new MockFocusEvent('focus', { relatedTarget: null, bubbles: true, cancelable: true, composed: true }));
+  }
   getAttribute(attrName) {
     if (attrName === 'style') {
       if (this.__style != null && this.__style.length > 0) {
@@ -16192,6 +16301,9 @@ class MockElement extends MockNode {
   set title(value) {
     this.setAttributeNS(null, 'title', value);
   }
+  animate() {
+    /**/
+  }
   onanimationstart() {
     /**/
   }
@@ -16456,6 +16568,18 @@ class MockElement extends MockNode {
   onwheel() {
     /**/
   }
+  requestFullscreen() {
+    /**/
+  }
+  scrollBy() {
+    /**/
+  }
+  scrollTo() {
+    /**/
+  }
+  scrollIntoView() {
+    /**/
+  }
   toString(opts) {
     return serializeNodeToHtml(this, opts);
   }
@@ -17497,6 +17621,7 @@ const GLOBAL_CONSTRUCTORS = [
   ['CustomEvent', MockCustomEvent],
   ['Event', MockEvent],
   ['Headers', MockHeaders],
+  ['FocusEvent', MockFocusEvent],
   ['KeyboardEvent', MockKeyboardEvent],
   ['MouseEvent', MockMouseEvent],
   ['Request', MockRequest],
@@ -18828,48 +18953,88 @@ const emptyOutputTargets = async (config, compilerCtx, buildCtx) => {
   timeSpan.finish('cleaning dirs finished');
 };
 
+/**
+ * Parse CSS imports into an object which contains a manifest of imports and a
+ * stylesheet with all imports resolved and concatenated.
+ *
+ * @param config the current config
+ * @param compilerCtx the compiler context (we need filesystem access)
+ * @param buildCtx the build context, we'll need access to diagnostics
+ * @param srcFilePath the source filepath
+ * @param resolvedFilePath the resolved filepath
+ * @param styleText style text we start with
+ * @param styleDocs optional array of style document objects
+ * @returns an object with concatenated styleText and imports
+ */
 const parseCssImports = async (config, compilerCtx, buildCtx, srcFilePath, resolvedFilePath, styleText, styleDocs) => {
   const isCssEntry = resolvedFilePath.toLowerCase().endsWith('.css');
   const allCssImports = [];
-  const concatStyleText = await updateCssImports(config, compilerCtx, buildCtx, isCssEntry, srcFilePath, resolvedFilePath, styleText, allCssImports, new Set(), styleDocs);
+  // a Set of previously-resolved file paths that we add to as we traverse the
+  // import tree (to avoid a possible circular dependency and infinite loop)
+  const resolvedFilePaths = new Set();
+  const concatStyleText = await resolveAndFlattenImports(srcFilePath, resolvedFilePath, styleText);
   return {
     imports: allCssImports,
     styleText: concatStyleText,
   };
-};
-const updateCssImports = async (config, compilerCtx, buildCtx, isCssEntry, srcFilePath, resolvedFilePath, styleText, allCssImports, noLoop, styleDocs) => {
-  if (noLoop.has(resolvedFilePath)) {
-    return styleText;
-  }
-  noLoop.add(resolvedFilePath);
-  if (styleDocs != null) {
-    parseStyleDocs(styleDocs, styleText);
-  }
-  const cssImports = await getCssImports(config, compilerCtx, buildCtx, resolvedFilePath, styleText);
-  if (cssImports.length === 0) {
-    return styleText;
-  }
-  for (const cssImport of cssImports) {
-    if (!allCssImports.includes(cssImport.filePath)) {
-      allCssImports.push(cssImport.filePath);
+  /**
+   * Resolve and flatten all imports for a given CSS file, recursively crawling
+   * the tree of imports to resolve them all and produce a concatenated
+   * stylesheet. We declare this function here, within `parseCssImports`, in order
+   * to get access to `compilerCtx`, `buildCtx`, and more without having to pass
+   * a whole bunch of arguments.
+   *
+   * @param srcFilePath the source filepath
+   * @param resolvedFilePath the resolved filepath
+   * @param styleText style text we start with*
+   * @returns concatenated styles assembled from the various imported stylesheets
+   */
+  async function resolveAndFlattenImports(srcFilePath, resolvedFilePath, styleText) {
+    // if we've seen this path before we early return
+    if (resolvedFilePaths.has(resolvedFilePath)) {
+      return styleText;
     }
-  }
-  await Promise.all(cssImports.map(async (cssImportData) => {
-    await concatCssImport(config, compilerCtx, buildCtx, isCssEntry, srcFilePath, cssImportData, allCssImports, noLoop, styleDocs);
-  }));
-  return replaceImportDeclarations(styleText, cssImports, isCssEntry);
-};
-const concatCssImport = async (config, compilerCtx, buildCtx, isCssEntry, srcFilePath, cssImportData, allCssImports, noLoop, styleDocs) => {
-  cssImportData.styleText = await loadStyleText(compilerCtx, cssImportData);
-  if (typeof cssImportData.styleText === 'string') {
-    cssImportData.styleText = await updateCssImports(config, compilerCtx, buildCtx, isCssEntry, cssImportData.filePath, cssImportData.filePath, cssImportData.styleText, allCssImports, noLoop, styleDocs);
-  }
-  else {
-    const err = buildError(buildCtx.diagnostics);
-    err.messageText = `Unable to read css import: ${cssImportData.srcImport}`;
-    err.absFilePath = srcFilePath;
+    resolvedFilePaths.add(resolvedFilePath);
+    if (styleDocs != null) {
+      parseStyleDocs(styleDocs, styleText);
+    }
+    const cssImports = await getCssImports(config, compilerCtx, buildCtx, resolvedFilePath, styleText);
+    if (cssImports.length === 0) {
+      return styleText;
+    }
+    // add any newly-found imports to the 'global' list
+    for (const cssImport of cssImports) {
+      if (!allCssImports.includes(cssImport.filePath)) {
+        allCssImports.push(cssImport.filePath);
+      }
+    }
+    // Recur down the tree of CSS imports, resolving all the imports in
+    // the children of the current file (and, by extension, in their children
+    // and so on)
+    await Promise.all(cssImports.map(async (cssImportData) => {
+      cssImportData.styleText = await loadStyleText(compilerCtx, cssImportData);
+      if (typeof cssImportData.styleText === 'string') {
+        cssImportData.styleText = await resolveAndFlattenImports(cssImportData.filePath, cssImportData.filePath, cssImportData.styleText);
+      }
+      else {
+        // we had some error loading the file from disk, so write a diagnostic
+        const err = buildError(buildCtx.diagnostics);
+        err.messageText = `Unable to read css import: ${cssImportData.srcImport}`;
+        err.absFilePath = srcFilePath;
+      }
+    }));
+    // replace import statements with the actual CSS code in children modules
+    return replaceImportDeclarations(styleText, cssImports, isCssEntry);
   }
 };
+/**
+ * Load the style text for a CSS file from disk, based on the filepaths set in
+ * our import data.
+ *
+ * @param compilerCtx the compiler context
+ * @param cssImportData the import data for the file we want to read
+ * @returns the contents of the file, if it can be read without error
+ */
 const loadStyleText = async (compilerCtx, cssImportData) => {
   let styleText = null;
   try {
@@ -18885,7 +19050,18 @@ const loadStyleText = async (compilerCtx, cssImportData) => {
   }
   return styleText;
 };
+/**
+ * Get a manifest of all the CSS imports in a given CSS file
+ *
+ * @param config the current config
+ * @param compilerCtx the compiler context (we need the filesystem)
+ * @param buildCtx the build context, in case we need to set a diagnostic
+ * @param filePath the filepath we're working with
+ * @param styleText the CSS for which we want to retrieve import data
+ * @returns a Promise wrapping a list of CSS import data objects
+ */
 const getCssImports = async (config, compilerCtx, buildCtx, filePath, styleText) => {
+  var _a;
   const imports = [];
   if (!styleText.includes('@import')) {
     // no @import at all, so don't bother
@@ -18893,13 +19069,14 @@ const getCssImports = async (config, compilerCtx, buildCtx, filePath, styleText)
   }
   styleText = stripCssComments(styleText);
   const dir = dirname(filePath);
-  const importeeExt = filePath.split('.').pop().toLowerCase();
+  const importeeExt = ((_a = filePath.split('.').pop()) !== null && _a !== void 0 ? _a : '').toLowerCase();
   let r;
   const IMPORT_RE = /(@import)\s+(url\()?\s?(.*?)\s?\)?([^;]*);?/gi;
   while ((r = IMPORT_RE.exec(styleText))) {
     const cssImportData = {
       srcImport: r[0],
       url: r[4].replace(/[\"\'\)]/g, ''),
+      filePath: '',
     };
     if (!isLocalCssImport(cssImportData.srcImport)) {
       // do nothing for @import url(http://external.css)
@@ -18926,7 +19103,10 @@ const getCssImports = async (config, compilerCtx, buildCtx, filePath, styleText)
         cssImportData.altFilePath = normalizePath$1(join(dirPath, fileName));
       }
     }
-    if (typeof cssImportData.filePath === 'string') {
+    // we set `filePath` to `""` when the object is created above, so if it
+    // hasn't been changed in the intervening conditionals then we didn't resolve
+    // a filepath for it.
+    if (cssImportData.filePath !== '') {
       imports.push(cssImportData);
     }
   }
@@ -18968,6 +19148,16 @@ const isLocalCssImport = (srcImport) => {
   }
   return true;
 };
+/**
+ * Replace import declarations (like '@import "foobar";') with the actual CSS
+ * written in the imported module, allowing us to produce a single file from a
+ * tree of stylesheets.
+ *
+ * @param styleText the text within which we want to replace @import statements
+ * @param cssImports information about imported modules
+ * @param isCssEntry whether we're dealing with a CSS file
+ * @returns an updated string with the requisite substitutions
+ */
 const replaceImportDeclarations = (styleText, cssImports, isCssEntry) => {
   for (const cssImport of cssImports) {
     if (isCssEntry) {
@@ -41777,7 +41967,7 @@ const createCustomResolverSync = (sys, inMemoryFs, exts) => {
  * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/d121716ed123957f6a86f8985eb013fcaddab345/types/node/globals.d.ts#L183-L188
  * in mind.
  * @param err the entity to check the type of
- * @return true if the provided value is an instance of `ErrnoException`, `false` otherwise
+ * @returns true if the provided value is an instance of `ErrnoException`, `false` otherwise
  */
 function isErrnoException(err) {
   return err instanceof Error && err.hasOwnProperty('code');
@@ -54447,6 +54637,23 @@ const isMemberPrivate = (member) => {
   }
   return false;
 };
+/**
+ * Convert a JavaScript value to the TypeScript Intermediate Representation
+ * (IR) for a literal Abstract Syntax Tree (AST) node with that same value. The
+ * value to convert may be a primitive type like `string`, `boolean`, etc or
+ * may be an `Object`, `Array`, etc.
+ *
+ * Note that this function takes a param (`refs`) with a default value,
+ * normally a value should _not_ be passed for this parameter since it is
+ * intended to be used for recursive calls.
+ *
+ * @param val the value to convert
+ * @param refs a set of references, used in recursive calls to avoid
+ * circular references when creating object literal IR instances. **note that
+ * you shouldn't pass this parameter unless you know what you're doing!**
+ * @returns TypeScript IR for a literal corresponding to the JavaScript value
+ * with which the function was called
+ */
 const convertValueToLiteral = (val, refs = null) => {
   if (refs == null) {
     refs = new WeakSet();
@@ -54477,12 +54684,39 @@ const convertValueToLiteral = (val, refs = null) => {
   }
   return t.createLiteral(val);
 };
+/**
+ * Convert a JavaScript Array instance to TypeScript's Intermediate
+ * Representation (IR) for an array literal. This is done by recursively using
+ * {@link convertValueToLiteral} to create a new array consisting of the
+ * TypeScript IR of each element in the array to be converted, and then creating
+ * the TypeScript IR for _that_ array.
+ *
+ * @param list the array instance to convert
+ * @param refs a set of references to objects, used when converting objects to
+ * avoid circular references
+ * @returns TypeScript IR for the array we want to convert
+ */
 const arrayToArrayLiteral = (list, refs) => {
   const newList = list.map((l) => {
     return convertValueToLiteral(l, refs);
   });
   return t.createArrayLiteral(newList);
 };
+/**
+ * Convert a JavaScript object (i.e. an object existing at runtime) to the
+ * corresponding TypeScript Intermediate Representation (IR)
+ * ({@see ts.ObjectLiteralExpression}) for an object literal. This function
+ * takes an argument holding a `WeakSet` of references to objects which is
+ * used to avoid circular references. Objects that are converted in this
+ * function are added to the set, and if an object is already present then an
+ * `undefined` literal (in TypeScript IR) is returned instead of another
+ * object literal, as continuing to convert a circular reference would, well,
+ * never end!
+ *
+ * @param obj the JavaScript object to convert to TypeScript IR
+ * @param refs a set of references to objects, used to avoid circular references
+ * @returns a TypeScript object literal expression
+ */
 const objectToObjectLiteral = (obj, refs) => {
   if (refs.has(obj)) {
     return t.createIdentifier('undefined');
@@ -55850,17 +56084,16 @@ const KEEP_IMPORTS = new Set([
  * 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 config the validated 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 = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
+  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   if (outputTargets.length === 0) {
     return;
   }
@@ -55873,7 +56106,7 @@ const outputCustomElements = async (config, compilerCtx, buildCtx) => {
  * 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 config a validated Stencil configuration object
  * @param buildCtx the current build context
  * @param compilerCtx the current compiler context
  * @param outputTarget the outputTarget we're currently dealing with
@@ -55904,9 +56137,10 @@ const getBundleOptions = (config, buildCtx, compilerCtx, outputTarget) => ({
 /**
  * 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 config the validated Stencil configuration we're using
  * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
  * @param outputTarget the outputTarget we're currently dealing with
  * @returns an empty promise
  */
@@ -55995,7 +56229,7 @@ const addCustomElementInputs = (buildCtx, bundleOpts) => {
       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
+      // 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,
@@ -57816,6 +58050,16 @@ const lazyComponentTransform = (compilerCtx, transformOpts) => {
   };
 };
 
+/**
+ * Generate rollup output based on a rollup build and a series of options.
+ *
+ * @param build a rollup build
+ * @param options output options for rollup
+ * @param config a user-supplied configuration object
+ * @param entryModules a list of entry modules, for checking which chunks
+ * contain components
+ * @returns a Promise wrapping either build results or `null`
+ */
 const generateRollupOutput = async (build, options, config, entryModules) => {
   if (build == null) {
     return null;
@@ -57823,7 +58067,7 @@ const generateRollupOutput = async (build, options, config, entryModules) => {
   const { output } = await build.generate(options);
   return output.map((chunk) => {
     if (chunk.type === 'chunk') {
-      const isCore = Object.keys(chunk.modules).some((m) => m.includes('@stencil/core'));
+      const isCore = Object.keys(chunk.modules).some((m) => m.includes(STENCIL_CORE_ID));
       return {
         type: 'chunk',
         fileName: chunk.fileName,
@@ -58322,7 +58566,8 @@ const getSystemLoader = async (config, compilerCtx, corePath, includePolyfills)
 
   var resourcesUrl = scriptElm ? scriptElm.getAttribute('data-resources-url') || scriptElm.src : '';
   var start = function() {
-    var url = new URL('${corePath}', new URL(resourcesUrl, window.location.origin));
+    // if src is not present then origin is "null", and new URL() throws TypeError: Failed to construct 'URL': Invalid base URL
+    var url = new URL('${corePath}', new URL(resourcesUrl, window.location.origin !== 'null' ? window.location.origin : undefined));
     System.import(url.href);
   };
 
@@ -60019,8 +60264,7 @@ const relDts$1 = (fromPath, dtsPath) => {
  * @param typesDir the path to the directory where type declarations are saved
  */
 const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, typesDir) => {
-  var _a;
-  const outputTargets = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).filter(isOutputTargetDistCustomElements);
+  const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, typesDir, outputTarget)));
 };
 /**
@@ -60036,7 +60280,7 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
   // 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');
   // the directory where types for the individual components are written
-  const componentsTypeDirectoryPath = relative$1(outputTarget.dir, join(typesDir, 'components'));
+  const componentsTypeDirectoryRelPath = relative$1(outputTarget.dir, typesDir);
   const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
   const code = [
     `/* ${config.namespace} custom elements */`,
@@ -60045,7 +60289,14 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
       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);
+      //
+      // To construct this path we:
+      //
+      // - get the relative path to the component's source file from the source directory
+      // - join that relative path to the relative path from the `index.d.ts` file to the
+      //   directory where typedefs are saved
+      const componentSourceRelPath = relative$1(config.srcDir, component.sourceFilePath).replace('.tsx', '');
+      const componentDTSPath = join(componentsTypeDirectoryRelPath, componentSourceRelPath);
       return `export { ${importName} as ${exportName} } from '${componentDTSPath}';`;
     }),
     ``,
@@ -61948,6 +62199,16 @@ const parseModuleImport = (config, compilerCtx, buildCtx, moduleFile, dirPath, i
   }
 };
 
+/**
+ * Update an instance of TypeScript's Intermediate Representation (IR) for a
+ * class declaration ({@link ts.ClassDeclaration}) with a static getter for the
+ * compiler metadata that we produce as part of the compilation process.
+ *
+ * @param cmpNode an instance of the TypeScript IR for a class declaration (i.e.
+ * a stencil component) to be updated
+ * @param cmpMeta the component metadata corresponding to that component
+ * @returns the updated typescript class declaration
+ */
 const addComponentMetaStatic = (cmpNode, cmpMeta) => {
   const publicCompilerMeta = getPublicCompilerMeta(cmpMeta);
   const cmpMetaStaticProp = createStaticGetter('COMPILER_META', convertValueToLiteral(publicCompilerMeta));
@@ -62079,6 +62340,14 @@ const parseStaticEvents = (staticMembers) => {
   });
 };
 
+/**
+ * Parse a list of {@link ts.ClassElement} objects representing static props
+ * into a list of our own Intermediate Representation (IR) of properties on
+ * components.
+ *
+ * @param staticMembers TypeScript IR for the properties on our component
+ * @returns a manifest of compiler properties in our own Stencil IR
+ */
 const parseStaticProps = (staticMembers) => {
   const parsedProps = getStaticValue(staticMembers, 'properties');
   if (!parsedProps) {
@@ -62315,7 +62584,22 @@ const setComponentBuildConditionals = (cmpMeta) => {
     !cmpMeta.hasMember && !cmpMeta.hasStyle && !cmpMeta.hasLifecycle && !cmpMeta.hasListener && !cmpMeta.hasVdomRender;
 };
 
-const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile, nodeMap, transformOpts) => {
+/**
+ * Given an instance of TypeScript's Intermediate Representation (IR) for a
+ * class declaration ({@see ts.ClassDeclaration}) which represents a Stencil
+ * component class declaration, parse and format various pieces of data about
+ * static class members which we use in the compilation process
+ *
+ * @param compilerCtx the current compiler context
+ * @param typeChecker a TypeScript type checker instance
+ * @param cmpNode the TypeScript class declaration for the component
+ * @param moduleFile Stencil's IR for a module, used here as an out param
+ * @param transformOpts options which control various aspects of the
+ * transformation
+ * @returns the TypeScript class declaration IR instance with which the
+ * function was called
+ */
+const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile, transformOpts) => {
   if (cmpNode.members == null) {
     return cmpNode;
   }
@@ -62432,7 +62716,7 @@ const parseStaticComponentMeta = (compilerCtx, typeChecker, cmpNode, moduleFile,
   // add to module map
   moduleFile.cmps.push(cmp);
   // add to node map
-  nodeMap.set(cmpNode, cmp);
+  compilerCtx.nodeMap.set(cmpNode, cmp);
   return cmpNode;
 };
 const parseVirtualProps = (docs) => {
@@ -62500,7 +62784,7 @@ const updateModule = (config, compilerCtx, buildCtx, tsSourceFile, sourceFileTex
   compilerCtx.changedModules.add(moduleFile.sourceFilePath);
   const visitNode = (node) => {
     if (t.isClassDeclaration(node)) {
-      parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, compilerCtx.nodeMap);
+      parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile);
       return;
     }
     else if (t.isImportDeclaration(node)) {
@@ -62661,6 +62945,15 @@ const outputServiceWorkers = async (config, buildCtx) => {
   }
 };
 
+/**
+ * Validate the package.json file for a project, checking that various fields
+ * are set correctly for the currently-configured output targets.
+ *
+ * @param config the user-supplied Stencil config
+ * @param compilerCtx the compiler context
+ * @param buildCtx the build context
+ * @returns an empty Promise
+ */
 const validateBuildPackageJson = async (config, compilerCtx, buildCtx) => {
   if (config.watch) {
     return;
@@ -62668,26 +62961,41 @@ const validateBuildPackageJson = async (config, compilerCtx, buildCtx) => {
   if (buildCtx.packageJson == null) {
     return;
   }
-  const outputTargets = config.outputTargets.filter(isOutputTargetDistCollection);
+  const distCollectionOutputTargets = config.outputTargets.filter(isOutputTargetDistCollection);
   const typesOutputTargets = config.outputTargets.filter(isOutputTargetDistTypes);
   await Promise.all([
-    ...outputTargets.map((outputsTarget) => {
-      return validatePackageJsonOutput(config, compilerCtx, buildCtx, outputsTarget);
-    }),
-    ...typesOutputTargets.map((outputTarget) => {
-      return validateTypes(config, compilerCtx, buildCtx, outputTarget);
-    }),
+    ...distCollectionOutputTargets.map((distCollectionOT) => validateDistCollectionPkgJson(config, compilerCtx, buildCtx, distCollectionOT)),
+    ...typesOutputTargets.map((typesOT) => validateTypes(config, compilerCtx, buildCtx, typesOT)),
+    validateModule(config, compilerCtx, buildCtx),
   ]);
 };
-const validatePackageJsonOutput = async (config, compilerCtx, buildCtx, outputTarget) => {
+/**
+ * Validate package.json contents for the `DIST_COLLECTION` output target,
+ * checking that various fields like `files`, `main`, and so on are set
+ * correctly.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
+const validateDistCollectionPkgJson = async (config, compilerCtx, buildCtx, outputTarget) => {
   await Promise.all([
     validatePackageFiles(config, compilerCtx, buildCtx, outputTarget),
     validateMain(config, compilerCtx, buildCtx, outputTarget),
-    validateModule(config, compilerCtx, buildCtx, outputTarget),
     validateCollection$1(config, compilerCtx, buildCtx, outputTarget),
     validateBrowser(config, compilerCtx, buildCtx),
   ]);
 };
+/**
+ * Validate that the `files` field in `package.json` contains directories and
+ * files that are necessary for the `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validatePackageFiles = async (config, compilerCtx, buildCtx, outputTarget) => {
   if (!config.devMode && Array.isArray(buildCtx.packageJson.files)) {
     const actualDistDir = normalizePath$1(relative$1(config.rootDir, outputTarget.dir));
@@ -62711,6 +63019,15 @@ const validatePackageFiles = async (config, compilerCtx, buildCtx, outputTarget)
     }));
   }
 };
+/**
+ * Check that the `main` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateMain = (config, compilerCtx, buildCtx, outputTarget) => {
   const mainAbs = join(outputTarget.dir, 'index.cjs.js');
   const mainRel = relative$1(config.rootDir, mainAbs);
@@ -62723,26 +63040,76 @@ const validateMain = (config, compilerCtx, buildCtx, outputTarget) => {
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"main"`);
   }
 };
-const validateModule = (config, compilerCtx, buildCtx, outputTarget) => {
-  const customElementsOutput = config.outputTargets.find(isOutputTargetDistCustomElementsBundle);
+/**
+ * Validate the package.json 'module' field, taking into account output targets
+ * and other configuration details. This will look for a value for the `module`
+ * field. If not present it will set a relevant warning message with an
+ * output-target specific recommended value. If it is present and is not equal
+ * to that recommended value it will set a different warning message.
+ *
+ * @param config the current user-supplied configuration
+ * @param compilerCtx the compiler context
+ * @param buildCtx the build context
+ * @returns an empty Promise
+ */
+const validateModule = async (config, compilerCtx, buildCtx) => {
   const currentModule = buildCtx.packageJson.module;
-  const distAbs = join(outputTarget.dir, 'index.js');
-  const distRel = relative$1(config.rootDir, distAbs);
-  let recommendedRelPath = distRel;
-  if (customElementsOutput) {
-    const customElementsAbs = join(customElementsOutput.dir, 'index.js');
-    recommendedRelPath = relative$1(config.rootDir, customElementsAbs);
-  }
+  const recommendedRelPath = recommendedModulePath(config);
   if (!isString$1(currentModule)) {
-    const msg = `package.json "module" property is required when generating a distribution. It's recommended to set the "module" property to: ${recommendedRelPath}`;
+    let msg = 'package.json "module" property is required when generating a distribution.';
+    if (recommendedRelPath !== null) {
+      msg += ` It's recommended to set the "module" property to: ${normalizePath$1(recommendedRelPath)}`;
+    }
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"module"`);
+    return;
   }
-  else if (normalizePath$1(currentModule) !== normalizePath$1(recommendedRelPath) &&
-    normalizePath$1(currentModule) !== normalizePath$1(distRel)) {
-    const msg = `package.json "module" property is set to "${currentModule}". It's recommended to set the "module" property to: ${recommendedRelPath}`;
+  if (recommendedRelPath !== null && normalizePath$1(recommendedRelPath) !== normalizePath$1(currentModule)) {
+    const msg = `package.json "module" property is set to "${currentModule}". It's recommended to set the "module" property to: ${normalizePath$1(recommendedRelPath)}`;
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"module"`);
   }
 };
+/**
+ * Get the recommended `"module"` path for `package.json` given the output
+ * targets that a user has set on their config.
+ *
+ * @param config the user-supplied Stencil configuration
+ * @returns a recommended module path or a null value to indicate no default
+ * value is supplied
+ */
+function recommendedModulePath(config) {
+  const customElementsBundleOT = config.outputTargets.find(isOutputTargetDistCustomElementsBundle);
+  const customElementsOT = config.outputTargets.find(isOutputTargetDistCustomElements);
+  const distCollectionOT = config.outputTargets.find(isOutputTargetDistCollection);
+  // If we're using `dist-custom-elements` then the preferred "module" field
+  // value is `$OUTPUT_DIR/components/index.js`
+  //
+  // Additionally, the `DIST_CUSTOM_ELEMENTS` output target should override
+  // `DIST_CUSTOM_ELEMENTS_BUNDLE` and `DIST_COLLECTION` output targets if
+  // they're also set, so we return first with this one.
+  if (customElementsOT) {
+    const componentsIndexAbs = join(customElementsOT.dir, 'components', 'index.js');
+    return relative$1(config.rootDir, componentsIndexAbs);
+  }
+  if (customElementsBundleOT) {
+    const customElementsAbs = join(customElementsBundleOT.dir, 'index.js');
+    return relative$1(config.rootDir, customElementsAbs);
+  }
+  if (distCollectionOT) {
+    return relative$1(config.rootDir, join(distCollectionOT.dir, 'index.js'));
+  }
+  // if no output target for which we define a recommended output target is set
+  // we return `null`
+  return null;
+}
+/**
+ * Check that the `types` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
   const typesAbs = getComponentsDtsTypesFilePath(outputTarget);
   const recommendedPath = relative$1(config.rootDir, typesAbs);
@@ -62766,6 +63133,15 @@ const validateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
     }
   }
 };
+/**
+ * Check that the `collection` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param outputTarget a DIST_COLLECTION output target
+ */
 const validateCollection$1 = (config, compilerCtx, buildCtx, outputTarget) => {
   if (outputTarget.collectionDir) {
     const collectionRel = join(relative$1(config.rootDir, outputTarget.collectionDir), COLLECTION_MANIFEST_FILE_NAME);
@@ -62775,19 +63151,51 @@ const validateCollection$1 = (config, compilerCtx, buildCtx, outputTarget) => {
     }
   }
 };
+/**
+ * Check that the `browser` field is set correctly in `package.json` for the
+ * `DIST_COLLECTION` output target.
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ */
 const validateBrowser = (config, compilerCtx, buildCtx) => {
   if (isString$1(buildCtx.packageJson.browser)) {
     const msg = `package.json "browser" property is set to "${buildCtx.packageJson.browser}". However, for maximum compatibility with all bundlers it's recommended to not set the "browser" property and instead ensure both "module" and "main" properties are set.`;
     packageJsonWarn(config, compilerCtx, buildCtx, msg, `"browser"`);
   }
 };
-const packageJsonError = (config, compilerCtx, buildCtx, msg, warnKey) => {
-  const err = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, warnKey);
+/**
+ * Build a diagnostic for an error resulting from a particular field in a
+ * package.json file
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param msg an error string
+ * @param jsonField the key for the field which caused the error, used for
+ * finding the error line in the original JSON file
+ * @returns a diagnostic object
+ */
+const packageJsonError = (config, compilerCtx, buildCtx, msg, jsonField) => {
+  const err = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, jsonField);
   err.header = `Package Json`;
   return err;
 };
-const packageJsonWarn = (config, compilerCtx, buildCtx, msg, warnKey) => {
-  const warn = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, warnKey);
+/**
+ * Build a diagnostic for a warning resulting from a particular field in a
+ * package.json file
+ *
+ * @param config the stencil config
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the current build context
+ * @param msg an error string
+ * @param jsonField the key for the field which caused the error, used for
+ * finding the error line in the original JSON file
+ * @returns a diagnostic object
+ */
+const packageJsonWarn = (config, compilerCtx, buildCtx, msg, jsonField) => {
+  const warn = buildJsonFileError(compilerCtx, buildCtx.diagnostics, config.packageJsonFilePath, msg, jsonField);
   warn.header = `Package Json`;
   warn.level = 'warn';
   return warn;
@@ -64246,16 +64654,38 @@ const updateCompilerCtxCache = (config, compilerCtx, path, kind) => {
   }
 };
 
+/**
+ * All the Boolean options supported by the Stencil CLI
+ */
+/**
+ * Helper function for initializing a `ConfigFlags` object. Provide any overrides
+ * for default values and off you go!
+ *
+ * @param init an object with any overrides for default values
+ * @returns a complete CLI flag object
+ */
+const createConfigFlags = (init = {}) => {
+  const flags = {
+    task: null,
+    args: [],
+    knownArgs: [],
+    unknownArgs: [],
+    ...init,
+  };
+  return flags;
+};
+
 const getConfig = (userConfig) => {
-  const config = { ...userConfig };
-  if (!config.logger) {
-    config.logger = createLogger();
-  }
-  if (!config.sys) {
-    config.sys = createSystem({ logger: config.logger });
-  }
+  var _a, _b, _c, _d;
+  const logger = (_a = userConfig.logger) !== null && _a !== void 0 ? _a : createLogger();
+  const config = {
+    ...userConfig,
+    flags: createConfigFlags((_b = userConfig.flags) !== null && _b !== void 0 ? _b : {}),
+    logger,
+    outputTargets: (_c = userConfig.outputTargets) !== null && _c !== void 0 ? _c : [],
+    sys: (_d = userConfig.sys) !== null && _d !== void 0 ? _d : createSystem({ logger }),
+  };
   setPlatformPath(config.sys.platformPath);
-  config.flags = config.flags || {};
   if (config.flags.debug || config.flags.verbose) {
     config.logLevel = 'debug';
   }
@@ -64276,14 +64706,15 @@ const patchFs = (userSys) => {
 
 /**
  * Generate a Stencil compiler instance
- * @param config a Stencil configuration to apply to the compiler instance
+ * @param userConfig a user-provided Stencil configuration to apply to the compiler instance
  * @returns a new instance of a Stencil compiler
+ * @public
  */
-const createCompiler = async (config) => {
+const createCompiler = async (userConfig) => {
   // actual compiler code
   // could be in a web worker on the browser
   // or the main thread in node
-  config = getConfig(config);
+  const config = getConfig(userConfig);
   const diagnostics = [];
   const sys = config.sys;
   const compilerCtx = new CompilerContext();
@@ -64959,7 +65390,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.17.0",
+		version: "2.17.2",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -65131,11 +65562,11 @@ const getUserConfigName = (config, correctConfigName) => {
 };
 
 const validateDevServer = (config, diagnostics) => {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e;
   if ((config.devServer === null || config.devServer) === false) {
     return undefined;
   }
-  const flags = (_a = config.flags) !== null && _a !== void 0 ? _a : {};
+  const { flags } = config;
   const devServer = { ...config.devServer };
   if (flags.address && isString$1(flags.address)) {
     devServer.address = flags.address;
@@ -65193,14 +65624,14 @@ const validateDevServer = (config, diagnostics) => {
   if (!isBoolean$1(devServer.websocket)) {
     devServer.websocket = true;
   }
-  if ((_b = config === null || config === void 0 ? void 0 : config.flags) === null || _b === void 0 ? void 0 : _b.ssr) {
+  if (flags.ssr) {
     devServer.ssr = true;
   }
   else {
     devServer.ssr = !!devServer.ssr;
   }
   if (devServer.ssr) {
-    const wwwOutput = ((_c = config.outputTargets) !== null && _c !== void 0 ? _c : []).find(isOutputTargetWww);
+    const wwwOutput = ((_a = config.outputTargets) !== null && _a !== void 0 ? _a : []).find(isOutputTargetWww);
     devServer.prerenderConfig = wwwOutput === null || wwwOutput === void 0 ? void 0 : wwwOutput.prerenderConfig;
   }
   if (isString$1(config.srcIndexHtml)) {
@@ -65226,15 +65657,15 @@ const validateDevServer = (config, diagnostics) => {
   }
   let serveDir;
   let basePath;
-  const wwwOutputTarget = ((_d = config.outputTargets) !== null && _d !== void 0 ? _d : []).find(isOutputTargetWww);
+  const wwwOutputTarget = ((_b = config.outputTargets) !== null && _b !== void 0 ? _b : []).find(isOutputTargetWww);
   if (wwwOutputTarget) {
-    const baseUrl = new URL((_e = wwwOutputTarget.baseUrl) !== null && _e !== void 0 ? _e : '', 'http://config.stenciljs.com');
+    const baseUrl = new URL((_c = wwwOutputTarget.baseUrl) !== null && _c !== void 0 ? _c : '', 'http://config.stenciljs.com');
     basePath = baseUrl.pathname;
-    serveDir = (_f = wwwOutputTarget.appDir) !== null && _f !== void 0 ? _f : '';
+    serveDir = (_d = wwwOutputTarget.appDir) !== null && _d !== void 0 ? _d : '';
   }
   else {
     basePath = '';
-    serveDir = (_g = config.rootDir) !== null && _g !== void 0 ? _g : '';
+    serveDir = (_e = config.rootDir) !== null && _e !== void 0 ? _e : '';
   }
   if (!isString$1(basePath) || basePath.trim() === '') {
     basePath = `/`;
@@ -65368,11 +65799,19 @@ const validateHydrated = (config) => {
   return hydratedFlag;
 };
 
+/**
+ * Validate and return DIST_COLLECTION output targets, ensuring that the `dir`
+ * property is set on them.
+ *
+ * @param config the user-supplied configuration object
+ * @param userOutputs an array of output targets
+ * @returns an array of validated DIST_COLLECTION output targets
+ */
 const validateCollection = (config, userOutputs) => {
-  return userOutputs.filter(isOutputTargetDistCollection).map((o) => {
+  return userOutputs.filter(isOutputTargetDistCollection).map((outputTarget) => {
     return {
-      ...o,
-      dir: getAbsolutePath(config, o.dir || 'dist/collection'),
+      ...outputTarget,
+      dir: getAbsolutePath(config, outputTarget.dir || 'dist/collection'),
     };
   });
 };
@@ -65706,7 +66145,7 @@ const validateHydrateScript = (config, userOutputs) => {
     // we don't already have a hydrate output target
     // let's still see if we require one because of other output targets
     const hasWwwOutput = userOutputs.filter(isOutputTargetWww).some((o) => isString$1(o.indexHtml));
-    const shouldBuildHydrate = (config === null || config === void 0 ? void 0 : config.flags.prerender) || (config === null || config === void 0 ? void 0 : config.flags.ssr);
+    const shouldBuildHydrate = config.flags.prerender || config.flags.ssr;
     if (hasWwwOutput && shouldBuildHydrate) {
       // we're prerendering a www output target, so we'll need a hydrate app
       let hydrateDir;
@@ -65782,7 +66221,7 @@ const validateStats = (userConfig, userOutputs) => {
 };
 
 const validatePrerender = (config, diagnostics, outputTarget) => {
-  if (!config.flags || (!config.flags.ssr && !config.flags.prerender && config.flags.task !== 'prerender')) {
+  if (!config.flags.ssr && !config.flags.prerender && config.flags.task !== 'prerender') {
     return;
   }
   outputTarget.baseUrl = normalizePath$1(outputTarget.baseUrl);
@@ -65807,8 +66246,6 @@ const validatePrerender = (config, diagnostics, outputTarget) => {
   }
 };
 
-const HOST_CONFIG_FILENAME = 'host.config.json';
-
 const validateServiceWorker = (config, outputTarget) => {
   if (outputTarget.serviceWorker === false) {
     return;
@@ -65861,14 +66298,15 @@ const validateServiceWorker = (config, outputTarget) => {
   }
 };
 const addGlobIgnores = (config, globIgnores) => {
-  globIgnores.push(`**/${HOST_CONFIG_FILENAME}`, `**/*.system.entry.js`, `**/*.system.js`, `**/${config.fsNamespace}.js`, `**/${config.fsNamespace}.esm.js`, `**/${config.fsNamespace}.css`);
+  globIgnores.push(`**/host.config.json`, // the filename of the host configuration
+  `**/*.system.entry.js`, `**/*.system.js`, `**/${config.fsNamespace}.js`, `**/${config.fsNamespace}.esm.js`, `**/${config.fsNamespace}.css`);
 };
 const DEFAULT_GLOB_PATTERNS = ['*.html', '**/*.{js,css,json}'];
 const DEFAULT_FILENAME = 'sw.js';
 
 const validateWww = (config, diagnostics, userOutputs) => {
   const hasOutputTargets = userOutputs.length > 0;
-  const hasE2eTests = !!(config.flags && config.flags.e2e);
+  const hasE2eTests = !!config.flags.e2e;
   const userWwwOutputs = userOutputs.filter(isOutputTargetWww);
   if (!hasOutputTargets ||
     (hasE2eTests && !userOutputs.some(isOutputTargetWww) && !userOutputs.some(isOutputTargetDist))) {
@@ -66122,7 +66560,7 @@ const DEFAULT_ROLLUP_CONFIG = {
 const validateTesting = (config, diagnostics) => {
   var _a;
   const testing = (config.testing = Object.assign({}, config.testing || {}));
-  if (!config.flags || (!config.flags.e2e && !config.flags.spec)) {
+  if (!config.flags.e2e && !config.flags.spec) {
     return;
   }
   let configPathDir = config.configPath;
@@ -66160,7 +66598,7 @@ const validateTesting = (config, diagnostics) => {
   else {
     testing.rootDir = config.rootDir;
   }
-  if (config.flags && typeof config.flags.screenshotConnector === 'string') {
+  if (typeof config.flags.screenshotConnector === 'string') {
     testing.screenshotConnector = config.flags.screenshotConnector;
   }
   if (typeof testing.screenshotConnector === 'string') {
@@ -66282,13 +66720,11 @@ const validateWorkers = (config) => {
   if (typeof config.maxConcurrentWorkers !== 'number') {
     config.maxConcurrentWorkers = 8;
   }
-  if (config.flags) {
-    if (typeof config.flags.maxWorkers === 'number') {
-      config.maxConcurrentWorkers = config.flags.maxWorkers;
-    }
-    else if (config.flags.ci) {
-      config.maxConcurrentWorkers = 4;
-    }
+  if (typeof config.flags.maxWorkers === 'number') {
+    config.maxConcurrentWorkers = config.flags.maxWorkers;
+  }
+  else if (config.flags.ci) {
+    config.maxConcurrentWorkers = 4;
   }
   config.maxConcurrentWorkers = Math.max(Math.min(config.maxConcurrentWorkers, 16), 0);
   if (config.devServer) {
@@ -66302,111 +66738,122 @@ const validateWorkers = (config) => {
  * `UnvalidatedConfig` to a `Config`.
  *
  * @param userConfig an unvalidated config that we've gotten from a user
+ * @param bootstrapConfig the initial configuration provided by the user (or generated by Stencil) used to bootstrap
+ * configuration loading and validation
  * @returns an object with config and diagnostics props
  */
-const validateConfig = (userConfig = {}) => {
-  const config = Object.assign({}, userConfig || {}); // not positive it's json safe
+const validateConfig = (userConfig = {}, bootstrapConfig) => {
+  var _a, _b, _c;
+  const config = Object.assign({}, userConfig); // not positive it's json safe
   const diagnostics = [];
-  // copy flags (we know it'll be json safe)
-  config.flags = JSON.parse(JSON.stringify(config.flags || {}));
+  const logger = bootstrapConfig.logger || config.logger || createLogger();
+  const validatedConfig = {
+    ...config,
+    // flags _should_ be JSON safe
+    flags: JSON.parse(JSON.stringify(config.flags || {})),
+    logger,
+    outputTargets: (_a = config.outputTargets) !== null && _a !== void 0 ? _a : [],
+    sys: (_c = (_b = config.sys) !== null && _b !== void 0 ? _b : bootstrapConfig.sys) !== null && _c !== void 0 ? _c : createSystem({ logger }),
+  };
   // default devMode false
-  if (config.flags.prod) {
-    config.devMode = false;
-  }
-  else if (config.flags.dev) {
-    config.devMode = true;
-  }
-  else if (!isBoolean$1(config.devMode)) {
-    config.devMode = DEFAULT_DEV_MODE;
-  }
-  config.extras = config.extras || {};
-  config.extras.appendChildSlotFix = !!config.extras.appendChildSlotFix;
-  config.extras.cloneNodeFix = !!config.extras.cloneNodeFix;
-  config.extras.cssVarsShim = !!config.extras.cssVarsShim;
-  config.extras.dynamicImportShim = !!config.extras.dynamicImportShim;
-  config.extras.lifecycleDOMEvents = !!config.extras.lifecycleDOMEvents;
-  config.extras.safari10 = !!config.extras.safari10;
-  config.extras.scriptDataOpts = !!config.extras.scriptDataOpts;
-  config.extras.shadowDomShim = !!config.extras.shadowDomShim;
-  config.extras.slotChildNodesFix = !!config.extras.slotChildNodesFix;
-  config.extras.initializeNextTick = !!config.extras.initializeNextTick;
-  config.extras.tagNameTransform = !!config.extras.tagNameTransform;
-  config.buildEs5 = config.buildEs5 === true || (!config.devMode && config.buildEs5 === 'prod');
-  setBooleanConfig(config, 'minifyCss', null, !config.devMode);
-  setBooleanConfig(config, 'minifyJs', null, !config.devMode);
-  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', 'esm', !config.devMode || config.buildEs5);
-  setBooleanConfig(config, 'profile', 'profile', config.devMode);
-  setBooleanConfig(config, 'writeLog', 'log', false);
-  setBooleanConfig(config, 'buildAppCore', null, true);
-  setBooleanConfig(config, 'autoprefixCss', null, config.buildEs5);
-  setBooleanConfig(config, 'validateTypes', null, !config._isTesting);
-  setBooleanConfig(config, 'allowInlineScripts', null, true);
-  if (!isString$1(config.taskQueue)) {
-    config.taskQueue = 'async';
+  if (validatedConfig.flags.prod) {
+    validatedConfig.devMode = false;
+  }
+  else if (validatedConfig.flags.dev) {
+    validatedConfig.devMode = true;
+  }
+  else if (!isBoolean$1(validatedConfig.devMode)) {
+    validatedConfig.devMode = DEFAULT_DEV_MODE;
+  }
+  validatedConfig.extras = validatedConfig.extras || {};
+  validatedConfig.extras.appendChildSlotFix = !!validatedConfig.extras.appendChildSlotFix;
+  validatedConfig.extras.cloneNodeFix = !!validatedConfig.extras.cloneNodeFix;
+  validatedConfig.extras.cssVarsShim = !!validatedConfig.extras.cssVarsShim;
+  validatedConfig.extras.dynamicImportShim = !!validatedConfig.extras.dynamicImportShim;
+  validatedConfig.extras.lifecycleDOMEvents = !!validatedConfig.extras.lifecycleDOMEvents;
+  validatedConfig.extras.safari10 = !!validatedConfig.extras.safari10;
+  validatedConfig.extras.scriptDataOpts = !!validatedConfig.extras.scriptDataOpts;
+  validatedConfig.extras.shadowDomShim = !!validatedConfig.extras.shadowDomShim;
+  validatedConfig.extras.slotChildNodesFix = !!validatedConfig.extras.slotChildNodesFix;
+  validatedConfig.extras.initializeNextTick = !!validatedConfig.extras.initializeNextTick;
+  validatedConfig.extras.tagNameTransform = !!validatedConfig.extras.tagNameTransform;
+  validatedConfig.buildEs5 =
+    validatedConfig.buildEs5 === true || (!validatedConfig.devMode && validatedConfig.buildEs5 === 'prod');
+  setBooleanConfig(validatedConfig, 'minifyCss', null, !validatedConfig.devMode);
+  setBooleanConfig(validatedConfig, 'minifyJs', null, !validatedConfig.devMode);
+  setBooleanConfig(validatedConfig, 'sourceMap', null, typeof validatedConfig.sourceMap === 'undefined' ? false : validatedConfig.sourceMap);
+  setBooleanConfig(validatedConfig, 'watch', 'watch', false);
+  setBooleanConfig(validatedConfig, 'buildDocs', 'docs', !validatedConfig.devMode);
+  setBooleanConfig(validatedConfig, 'buildDist', 'esm', !validatedConfig.devMode || validatedConfig.buildEs5);
+  setBooleanConfig(validatedConfig, 'profile', 'profile', validatedConfig.devMode);
+  setBooleanConfig(validatedConfig, 'writeLog', 'log', false);
+  setBooleanConfig(validatedConfig, 'buildAppCore', null, true);
+  setBooleanConfig(validatedConfig, 'autoprefixCss', null, validatedConfig.buildEs5);
+  setBooleanConfig(validatedConfig, 'validateTypes', null, !validatedConfig._isTesting);
+  setBooleanConfig(validatedConfig, 'allowInlineScripts', null, true);
+  if (!isString$1(validatedConfig.taskQueue)) {
+    validatedConfig.taskQueue = 'async';
   }
   // hash file names
-  if (!isBoolean$1(config.hashFileNames)) {
-    config.hashFileNames = !config.devMode;
+  if (!isBoolean$1(validatedConfig.hashFileNames)) {
+    validatedConfig.hashFileNames = !validatedConfig.devMode;
   }
-  if (!isNumber$1(config.hashedFileNameLength)) {
-    config.hashedFileNameLength = DEFAULT_HASHED_FILENAME_LENTH;
+  if (!isNumber$1(validatedConfig.hashedFileNameLength)) {
+    validatedConfig.hashedFileNameLength = DEFAULT_HASHED_FILENAME_LENTH;
   }
-  if (config.hashedFileNameLength < MIN_HASHED_FILENAME_LENTH) {
+  if (validatedConfig.hashedFileNameLength < MIN_HASHED_FILENAME_LENTH) {
     const err = buildError(diagnostics);
-    err.messageText = `config.hashedFileNameLength must be at least ${MIN_HASHED_FILENAME_LENTH} characters`;
+    err.messageText = `validatedConfig.hashedFileNameLength must be at least ${MIN_HASHED_FILENAME_LENTH} characters`;
   }
-  if (config.hashedFileNameLength > MAX_HASHED_FILENAME_LENTH) {
+  if (validatedConfig.hashedFileNameLength > MAX_HASHED_FILENAME_LENTH) {
     const err = buildError(diagnostics);
-    err.messageText = `config.hashedFileNameLength cannot be more than ${MAX_HASHED_FILENAME_LENTH} characters`;
+    err.messageText = `validatedConfig.hashedFileNameLength cannot be more than ${MAX_HASHED_FILENAME_LENTH} characters`;
   }
-  if (!config.env) {
-    config.env = {};
+  if (!validatedConfig.env) {
+    validatedConfig.env = {};
   }
   // get a good namespace
-  validateNamespace(config, diagnostics);
+  validateNamespace(validatedConfig, diagnostics);
   // figure out all of the config paths and absolute paths
-  validatePaths(config);
+  validatePaths(validatedConfig);
   // outputTargets
-  validateOutputTargets(config, diagnostics);
+  validateOutputTargets(validatedConfig, diagnostics);
   // plugins
-  validatePlugins(config, diagnostics);
+  validatePlugins(validatedConfig, diagnostics);
   // rollup config
-  validateRollupConfig(config);
+  validateRollupConfig(validatedConfig);
   // dev server
-  config.devServer = validateDevServer(config, diagnostics);
+  validatedConfig.devServer = validateDevServer(validatedConfig, diagnostics);
   // testing
-  validateTesting(config, diagnostics);
+  validateTesting(validatedConfig, diagnostics);
   // hydrate flag
-  config.hydratedFlag = validateHydrated(config);
+  validatedConfig.hydratedFlag = validateHydrated(validatedConfig);
   // bundles
-  if (Array.isArray(config.bundles)) {
-    config.bundles = sortBy(config.bundles, (a) => a.components.length);
+  if (Array.isArray(validatedConfig.bundles)) {
+    validatedConfig.bundles = sortBy(validatedConfig.bundles, (a) => a.components.length);
   }
   else {
-    config.bundles = [];
+    validatedConfig.bundles = [];
   }
   // validate how many workers we can use
-  validateWorkers(config);
+  validateWorkers(validatedConfig);
   // default devInspector to whatever devMode is
-  setBooleanConfig(config, 'devInspector', null, config.devMode);
-  if (!config._isTesting) {
-    validateDistNamespace(config, diagnostics);
+  setBooleanConfig(validatedConfig, 'devInspector', null, validatedConfig.devMode);
+  if (!validatedConfig._isTesting) {
+    validateDistNamespace(validatedConfig, diagnostics);
   }
-  setBooleanConfig(config, 'enableCache', 'cache', true);
-  if (!Array.isArray(config.watchIgnoredRegex) && config.watchIgnoredRegex != null) {
-    config.watchIgnoredRegex = [config.watchIgnoredRegex];
+  setBooleanConfig(validatedConfig, 'enableCache', 'cache', true);
+  if (!Array.isArray(validatedConfig.watchIgnoredRegex) && validatedConfig.watchIgnoredRegex != null) {
+    validatedConfig.watchIgnoredRegex = [validatedConfig.watchIgnoredRegex];
   }
-  config.watchIgnoredRegex = (config.watchIgnoredRegex || []).reduce((arr, reg) => {
+  validatedConfig.watchIgnoredRegex = (validatedConfig.watchIgnoredRegex || []).reduce((arr, reg) => {
     if (reg instanceof RegExp) {
       arr.push(reg);
     }
     return arr;
   }, []);
   return {
-    config,
+    config: validatedConfig,
     diagnostics,
   };
 };
@@ -66573,6 +67020,7 @@ const hasStencilConfigInclude = (includeProp) => Array.isArray(includeProp) && i
  * @public
  */
 const loadConfig = async (init = {}) => {
+  var _a;
   const results = {
     config: null,
     diagnostics: [],
@@ -66585,30 +67033,33 @@ const loadConfig = async (init = {}) => {
       extends: null,
     },
   };
+  const unknownConfig = {};
   try {
-    const sys = init.sys || createSystem();
     const config = init.config || {};
     let configPath = init.configPath || config.configPath;
+    // Pull the {@link CompilerSystem} out of the initialization object, or create one if it does not exist.
+    // This entity is needed to load the project's configuration (and therefore needs to be created before it can be
+    // attached to a configuration entity, validated or otherwise)
+    const sys = (_a = init.sys) !== null && _a !== void 0 ? _a : createSystem();
     const loadedConfigFile = await loadConfigFile(sys, results.diagnostics, configPath);
     if (hasError(results.diagnostics)) {
       return results;
     }
-    if (loadedConfigFile != null) {
+    if (loadedConfigFile !== null) {
       // merge the user's config object into their loaded config file
       configPath = loadedConfigFile.configPath;
-      results.config = { ...loadedConfigFile, ...config };
-      results.config.configPath = configPath;
-      results.config.rootDir = normalizePath$1(dirname(configPath));
+      unknownConfig.config = { ...loadedConfigFile, ...config };
+      unknownConfig.config.configPath = configPath;
+      unknownConfig.config.rootDir = normalizePath$1(dirname(configPath));
     }
     else {
       // no stencil.config.ts or .js file, which is fine
-      // #0CJS ¯\_(ツ)_/¯
-      results.config = { ...config };
-      results.config.configPath = null;
-      results.config.rootDir = normalizePath$1(sys.getCurrentDirectory());
+      unknownConfig.config = { ...config };
+      unknownConfig.config.configPath = null;
+      unknownConfig.config.rootDir = normalizePath$1(sys.getCurrentDirectory());
     }
-    results.config.sys = sys;
-    const validated = validateConfig(results.config);
+    unknownConfig.config.sys = sys;
+    const validated = validateConfig(unknownConfig.config, init);
     results.diagnostics.push(...validated.diagnostics);
     if (hasError(results.diagnostics)) {
       return results;
@@ -66623,7 +67074,6 @@ const loadConfig = async (init = {}) => {
     else if (typeof results.config.logLevel !== 'string') {
       results.config.logLevel = 'info';
     }
-    results.config.logger = init.logger || results.config.logger || createLogger();
     results.config.logger.setLevel(results.config.logLevel);
     if (!hasError(results.diagnostics)) {
       const tsConfigResults = await validateTsConfig(results.config, sys, init);
@@ -66882,7 +67332,7 @@ const convertStaticToMeta = (config, compilerCtx, buildCtx, typeChecker, collect
     let moduleFile;
     const visitNode = (node) => {
       if (t.isClassDeclaration(node)) {
-        return parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, compilerCtx.nodeMap, transformOpts);
+        return parseStaticComponentMeta(compilerCtx, typeChecker, node, moduleFile, transformOpts);
       }
       else if (t.isImportDeclaration(node)) {
         parseModuleImport(config, compilerCtx, buildCtx, moduleFile, dirPath, node, !transformOpts.isolatedModules);