@stencil/core 2.14.2 → 2.15.0

package/bin/stencil

@@ -18,16 +18,14 @@ if (isNodeLT(minimumVersion)) {
       currentVersion +
       ', however Stencil requires v' +
       minimumVersion +
-      '.0 or greater. It is recommended to use an Active LTS version of Node (https://nodejs.org/en/about/releases/).\n',
+      '.0 or greater. It is recommended to use an Active LTS version of Node (https://nodejs.org/en/about/releases/).\n'
   );
   process.exit(1);
 }
 
 if (isNodeLT(futureDeprecationMinVersion)) {
   console.warn(
-    '\nIn an upcoming major release of Stencil, Node v' +
-    recommendedVersion +
-    '.0 or higher will be required.\n'
+    '\nIn an upcoming major release of Stencil, Node v' + recommendedVersion + '.0 or higher will be required.\n'
   );
 } else if (isNodeLT(recommendedVersion)) {
   console.warn(
@@ -35,7 +33,7 @@ if (isNodeLT(futureDeprecationMinVersion)) {
       currentVersion +
       ", however Stencil's recommendation is v" +
       recommendedVersion +
-      '.0 or greater. Note that future versions of Stencil will eventually remove support for non-LTS Node versions and an Active LTS version is recommended (https://nodejs.org/en/about/releases/).\n',
+      '.0 or greater. Note that future versions of Stencil will eventually remove support for non-LTS Node versions and an Active LTS version is recommended (https://nodejs.org/en/about/releases/).\n'
   );
 }
 
@@ -46,13 +44,14 @@ var nodeSys = nodeApi.createNodeSys({ process: process, logger: nodeLogger });
 
 nodeApi.setupNodeProcess({ process: process, logger: nodeLogger });
 
-cli.run({
-  args: process.argv.slice(2),
-  logger: nodeLogger,
-  sys: nodeSys,
-  checkVersion: nodeApi.checkVersion
-})
-.catch(function (err) {
-  console.error('uncaught error', err);
-  process.exit(1);
-});
+cli
+  .run({
+    args: process.argv.slice(2),
+    logger: nodeLogger,
+    sys: nodeSys,
+    checkVersion: nodeApi.checkVersion,
+  })
+  .catch(function (err) {
+    console.error('uncaught error', err);
+    process.exit(1);
+  });

package/cli/index.cjs

@@ -1,5 +1,5 @@
 /*!
- Stencil CLI (CommonJS) v2.14.2 | MIT Licensed | https://stenciljs.com
+ Stencil CLI (CommonJS) v2.15.0 | MIT Licensed | https://stenciljs.com
  */
 'use strict';
 
@@ -513,7 +513,7 @@ const getNpmConfigEnvArgs = (sys) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.2",
+		version: "2.15.0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",

package/cli/index.js

@@ -1,5 +1,5 @@
 /*!
- Stencil CLI v2.14.2 | MIT Licensed | https://stenciljs.com
+ Stencil CLI v2.15.0 | MIT Licensed | https://stenciljs.com
  */
 const toLowerCase = (str) => str.toLowerCase();
 const dashToPascalCase = (str) => toLowerCase(str)
@@ -489,7 +489,7 @@ const getNpmConfigEnvArgs = (sys) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.2",
+		version: "2.15.0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/cli",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "Stencil CLI.",
   "main": "./index.cjs",
   "module": "./index.js",

package/compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/compiler",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "Stencil Compiler.",
   "main": "./stencil.js",
   "types": "./stencil.d.ts",

package/compiler/stencil.js

@@ -1,5 +1,5 @@
 /*!
- Stencil Compiler v2.14.2 | MIT Licensed | https://stenciljs.com
+ Stencil Compiler v2.15.0 | MIT Licensed | https://stenciljs.com
  */
 (function(exports) {
 'use strict';
@@ -1599,6 +1599,12 @@ const createJsVarName = (fileName) => {
   }
   return fileName;
 };
+/**
+ * Determines if a given file path points to a type declaration file (ending in .d.ts) or not. This function is
+ * case-insensitive in its heuristics.
+ * @param filePath the path to check
+ * @returns `true` if the given `filePath` points to a type declaration file, `false` otherwise
+ */
 const isDtsFile$1 = (filePath) => {
   const parts = filePath.toLowerCase().split('.');
   if (parts.length > 2) {
@@ -3967,7 +3973,7 @@ const createCustomResolverAsync = (sys, inMemoryFs, exts) => {
   };
 };
 
-const buildId = '20220310222720';
+const buildId = '20220328165835';
 const minfyJsId = 'terser5.6.1_7';
 const optimizeCssId = 'autoprefixer10.2.5_postcss8.2.8_7';
 const parse5Version = '6.0.1';
@@ -3975,8 +3981,8 @@ const rollupVersion = '2.42.3';
 const sizzleVersion = '2.42.3';
 const terserVersion = '5.6.1';
 const typescriptVersion = '4.5.4';
-const vermoji = '😃';
-const version$3 = '2.14.2';
+const vermoji = '⛷';
+const version$3 = '2.15.0';
 const versions = {
   stencil: version$3,
   parse5: parse5Version,
@@ -58837,8 +58843,18 @@ const serializeCollectionDependencies = (compilerCtx) => {
   return sortBy(collectionDeps, (item) => item.name);
 };
 
+/**
+ * Update a type declaration file's import declarations using the module `@stencil/core`
+ * @param typesDir the directory where type declaration files are expected to exist
+ * @param dtsFilePath the path of the type declaration file being updated, used to derive the correct import declaration
+ * module
+ * @param dtsContent the content of a type declaration file to update
+ * @returns the updated type declaration file contents
+ */
 const updateStencilTypesImports = (typesDir, dtsFilePath, dtsContent) => {
   const dir = dirname(dtsFilePath);
+  // determine the relative path between the directory of the .d.ts file and the types directory. this value may result
+  // in '.' if they are the same
   const relPath = relative$1(dir, typesDir);
   let coreDtsPath = join(relPath, CORE_FILENAME);
   if (!coreDtsPath.startsWith('.')) {
@@ -58851,6 +58867,12 @@ const updateStencilTypesImports = (typesDir, dtsFilePath, dtsContent) => {
   }
   return dtsContent;
 };
+/**
+ * Writes Stencil core typings file to disk for a dist-* output target
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @returns
+ */
 const copyStencilCoreDts = async (config, compilerCtx) => {
   const typesOutputTargets = config.outputTargets.filter(isOutputTargetDistTypes).filter((o) => o.typesDir);
   const srcStencilDtsPath = join(config.sys.getCompilerExecutingPath(), '..', '..', 'internal', CORE_DTS);
@@ -58933,21 +58955,21 @@ const generatePropTypes = (cmpMeta) => {
 };
 
 /**
- * Generate a string based on the types that are defined within a component.
- *
+ * Generate a string based on the types that are defined within a component
  * @param cmp the metadata for the component that a type definition string is generated for
- * @param importPath the path of the component file
+ * @param areTypesInternal `true` if types being generated are for a project's internal purposes, `false` otherwise
+ * @returns the generated types string alongside additional metadata
  */
-const generateComponentTypes = (cmp, internal) => {
+const generateComponentTypes = (cmp, areTypesInternal) => {
   const tagName = cmp.tagName.toLowerCase();
   const tagNameAsPascal = dashToPascalCase$1(tagName);
   const htmlElementName = `HTML${tagNameAsPascal}Element`;
   const propAttributes = generatePropTypes(cmp);
   const methodAttributes = generateMethodTypes(cmp.methods);
   const eventAttributes = generateEventTypes(cmp.events);
-  const componentAttributes = attributesToMultiLineString([...propAttributes, ...methodAttributes], false, internal);
+  const componentAttributes = attributesToMultiLineString([...propAttributes, ...methodAttributes], false, areTypesInternal);
   const isDep = cmp.isCollectionDependency;
-  const jsxAttributes = attributesToMultiLineString([...propAttributes, ...eventAttributes], true, internal);
+  const jsxAttributes = attributesToMultiLineString([...propAttributes, ...eventAttributes], true, areTypesInternal);
   const element = [
     `    interface ${htmlElementName} extends Components.${tagNameAsPascal}, HTMLStencilElement {`,
     `    }`,
@@ -58989,13 +59011,12 @@ const attributesToMultiLineString = (attributes, jsxAttributes, internal) => {
 };
 
 /**
- * Find all referenced types by a component and add them to the importDataObj and return the newly
- * updated importDataObj
- *
+ * Find all referenced types by a component and add them to the `importDataObj` parameter
  * @param importDataObj key/value of type import file, each value is an array of imported types
- * @param cmpMeta the metadata for the component that is referencing the types
+ * @param allTypes an output parameter containing a map of seen types and the number of times the type has been seen
+ * @param cmp the metadata associated with the component whose types are being inspected
  * @param filePath the path of the component file
- * @param config general config that all of stencil uses
+ * @returns the updated import data
  */
 const updateReferenceTypeImports = (importDataObj, allTypes, cmp, filePath) => {
   const updateImportReferences = updateImportReferenceFactory(allTypes, filePath);
@@ -59052,16 +59073,25 @@ const updateImportReferenceFactory = (allTypes, filePath) => {
   };
 };
 
+/**
+ * Generates and writes a `components.d.ts` file to disk. This file may be written to the `src` directory of a project,
+ * or be written to a directory that is meant to be distributed (e.g. the output directory of `dist-custom-elements`).
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param destination the relative directory in the filesystem to write the type declaration file to
+ * @returns `true` if the type declaration file written to disk has changed, `false` otherwise
+ */
 const generateAppTypes = async (config, compilerCtx, buildCtx, destination) => {
   // only gather components that are still root ts files we've found and have component metadata
   // the compilerCtx cache may still have files that may have been deleted/renamed
   const timespan = buildCtx.createTimeSpan(`generated app types started`, true);
-  const internal = destination === 'src';
+  const areTypesInternal = destination === 'src';
   // Generate d.ts files for component types
-  let componentTypesFileContent = generateComponentTypesFile(config, buildCtx, internal);
+  let componentTypesFileContent = generateComponentTypesFile(config, buildCtx, areTypesInternal);
   // immediately write the components.d.ts file to disk and put it into fs memory
   let componentsDtsFilePath = getComponentsDtsSrcFilePath(config);
-  if (!internal) {
+  if (!areTypesInternal) {
     componentsDtsFilePath = resolve$1(destination, GENERATED_DTS$1);
     componentTypesFileContent = updateStencilTypesImports(destination, componentsDtsFilePath, componentTypesFileContent);
   }
@@ -59077,18 +59107,20 @@ const generateAppTypes = async (config, compilerCtx, buildCtx, destination) => {
   return hasComponentsDtsChanged;
 };
 /**
- * Generate the component.d.ts file that contains types for all components
- * @param config the project build configuration
- * @param options compiler options from tsconfig
+ * Generates a `component.d.ts` file's contents, which contains the typings for all components in a Stencil project
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param buildCtx the context associated with the current build
+ * @param areTypesInternal determines if non-exported type definitions are being generated or not
+ * @returns the contents of the `components.d.ts` file
  */
-const generateComponentTypesFile = (config, buildCtx, internal) => {
+const generateComponentTypesFile = (config, buildCtx, areTypesInternal) => {
   let typeImportData = {};
   const c = [];
   const allTypes = new Map();
   const components = buildCtx.components.filter((m) => !m.isCollectionDependency);
   const modules = components.map((cmp) => {
     typeImportData = updateReferenceTypeImports(typeImportData, allTypes, cmp, cmp.sourceFilePath);
-    return generateComponentTypes(cmp, internal);
+    return generateComponentTypes(cmp, areTypesInternal);
   });
   c.push(COMPONENTS_DTS_HEADER);
   c.push(`import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";`);
@@ -59219,10 +59251,28 @@ const relDts$1 = (fromPath, dtsPath) => {
   return normalizePath$1(dtsPath.replace('.d.ts', ''));
 };
 
+/**
+ * Entrypoint for generating types for one or more `dist-custom-elements` output targets defined in a Stencil project's
+ * configuration
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param distDtsFilePath the path to a type declaration file (.d.ts) that is being generated for the output target.
+ * This path is not necessarily the `components.d.ts` file that is found in the root of a project's `src` directory.
+ */
 const generateCustomElementsTypes = async (config, compilerCtx, buildCtx, distDtsFilePath) => {
   const outputTargets = config.outputTargets.filter(isOutputTargetDistCustomElements);
   await Promise.all(outputTargets.map((outputTarget) => generateCustomElementsTypesOutput(config, compilerCtx, buildCtx, distDtsFilePath, outputTarget)));
 };
+/**
+ * Generates types for a single `dist-custom-elements` output target definition in a Stencil project's configuration
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param distDtsFilePath the path to a type declaration file (.d.ts) that is being generated for the output target.
+ * This path is not necessarily the `components.d.ts` file that is found in the root of a project's `src` directory.
+ * @param outputTarget the output target for which types are being currently generated
+ */
 const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx, distDtsFilePath, outputTarget) => {
   const customElementsDtsPath = join(outputTarget.dir, 'index.d.ts');
   const componentsDtsRelPath = relDts(outputTarget.dir, distDtsFilePath);
@@ -59238,7 +59288,7 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
     ` * "setAssetPath(document.currentScript.src)", or using a bundler's replace plugin to`,
     ` * dynamically set the path at build time, such as "setAssetPath(process.env.ASSET_PATH)".`,
     ` * But do note that this configuration depends on how your script is bundled, or lack of`,
-    ` * bunding, and where your assets can be loaded from. Additionally custom bundling`,
+    ` * bundling, and where your assets can be loaded from. Additionally custom bundling`,
     ` * will have to ensure the static assets are copied to its build directory.`,
     ` */`,
     `export declare const setAssetPath: (path: string) => void;`,
@@ -59273,6 +59323,13 @@ const generateCustomElementsTypesOutput = async (config, compilerCtx, buildCtx,
     await compilerCtx.fs.writeFile(filePath, dtsCode, { outputTargetType: outputTarget.type });
   }));
 };
+/**
+ * Generate a type declaration file for a specific Stencil component
+ * @param componentsDtsRelPath the path to a root type declaration file from which commonly used entities can be
+ * referenced from in the newly generated file
+ * @param cmp the component to generate the type declaration file for
+ * @returns the contents of the type declaration file for the provided `cmp`
+ */
 const generateCustomElementType = (componentsDtsRelPath, cmp) => {
   const tagNameAsPascal = dashToPascalCase$1(cmp.tagName);
   const o = [
@@ -59291,6 +59348,13 @@ const generateCustomElementType = (componentsDtsRelPath, cmp) => {
   ];
   return o.join('\n');
 };
+/**
+ * Determines the relative path between two provided paths. If a type declaration file extension is present on
+ * `dtsPath`, it will be removed from the computed relative path.
+ * @param fromPath the path from which to start at
+ * @param dtsPath the destination path
+ * @returns the relative path from the provided `fromPath` to the `dtsPath`
+ */
 const relDts = (fromPath, dtsPath) => {
   dtsPath = relative$1(fromPath, dtsPath);
   if (!dtsPath.startsWith('.')) {
@@ -59299,13 +59363,28 @@ const relDts = (fromPath, dtsPath) => {
   return normalizePath$1(dtsPath.replace('.d.ts', ''));
 };
 
+/**
+ * For a single output target, generate types, then copy the Stencil core type declaration file
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param outputTarget the output target to generate types for
+ */
 const generateTypes = async (config, compilerCtx, buildCtx, outputTarget) => {
   if (!buildCtx.hasError) {
     await generateTypesOutput(config, compilerCtx, buildCtx, outputTarget);
     await copyStencilCoreDts(config, compilerCtx);
   }
 };
+/**
+ * Generate type definition files and write them to a dist directory
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ * @param outputTarget the output target to generate types for
+ */
 const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget) => {
+  // get all type declaration files in a project's src/ directory
   const srcDirItems = await compilerCtx.fs.readdir(config.srcDir, { recursive: false });
   const srcDtsFiles = srcDirItems.filter((srcItem) => srcItem.isFile && isDtsFile$1(srcItem.absPath));
   // Copy .d.ts files from src to dist
@@ -59327,6 +59406,12 @@ const generateTypesOutput = async (config, compilerCtx, buildCtx, outputTarget)
   }
 };
 
+/**
+ * Entrypoint for generating types for all output targets
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param compilerCtx the current compiler context
+ * @param buildCtx the context associated with the current build
+ */
 const outputTypes = async (config, compilerCtx, buildCtx) => {
   const outputTargets = config.outputTargets.filter(isOutputTargetDistTypes);
   if (outputTargets.length === 0) {
@@ -63978,7 +64063,7 @@ const getComponentPathContent = (componentGraph, outputTarget) => {
 const dependencies = [
 	{
 		name: "@stencil/core",
-		version: "2.14.2",
+		version: "2.15.0",
 		main: "compiler/stencil.js",
 		resources: [
 			"package.json",
@@ -64369,11 +64454,20 @@ const validateCopy = (copy, defaultCopy = []) => {
   return unique(copy, (task) => `${task.src}:${task.dest}:${task.keepDirStructure}`);
 };
 
+/**
+ * Validate one or more `dist-custom-elements` output targets. Validation of an output target may involve back-filling
+ * fields that are omitted with sensible defaults and/or creating additional supporting output targets that were not
+ * explicitly defined by the user
+ * @param config the Stencil configuration associated with the project being compiled
+ * @param userOutputs the output target(s) specified by the user
+ * @returns the validated output target(s)
+ */
 const validateCustomElement = (config, userOutputs) => {
-  return userOutputs.filter(isOutputTargetDistCustomElements).reduce((arr, o) => {
+  const defaultDir = 'dist';
+  return userOutputs.filter(isOutputTargetDistCustomElements).reduce((outputs, o) => {
     const outputTarget = {
       ...o,
-      dir: getAbsolutePath(config, o.dir || 'dist/components'),
+      dir: getAbsolutePath(config, o.dir || join(defaultDir, 'components')),
     };
     if (!isBoolean$1(outputTarget.empty)) {
       outputTarget.empty = true;
@@ -64381,16 +64475,25 @@ const validateCustomElement = (config, userOutputs) => {
     if (!isBoolean$1(outputTarget.externalRuntime)) {
       outputTarget.externalRuntime = true;
     }
+    // unlike other output targets, Stencil does not allow users to define the output location of types at this time
+    if (outputTarget.generateTypeDeclarations) {
+      const typesDirectory = getAbsolutePath(config, join(defaultDir, 'types'));
+      outputs.push({
+        type: DIST_TYPES,
+        dir: outputTarget.dir,
+        typesDir: typesDirectory,
+      });
+    }
     outputTarget.copy = validateCopy(outputTarget.copy, []);
     if (outputTarget.copy.length > 0) {
-      arr.push({
+      outputs.push({
         type: COPY,
         dir: config.rootDir,
         copy: [...outputTarget.copy],
       });
     }
-    arr.push(outputTarget);
-    return arr;
+    outputs.push(outputTarget);
+    return outputs;
   }, []);
 };
 
@@ -65175,7 +65278,7 @@ const validateTesting = (config, diagnostics) => {
      *   - this regex case shall match file names such as `my-cmp.spec.ts`, `test.spec.ts`
      *   - this regex case shall not match file names such as `attest.ts`, `bespec.ts`
      */
-    testing.testRegex = '(/__tests__/.*|(\\.|/)(test|spec|e2e))\\.[jt]sx?';
+    testing.testRegex = '(/__tests__/.*|(\\.|/)(test|spec|e2e))\\.[jt]sx?$';
   }
   if (Array.isArray(testing.testMatch)) {
     delete testing.testRegex;