fix(types): generate types for dist-custom-elements (#3270)

this commit introduces a new experimental flag,
`generateTypeDeclarations` on the `dist-custom-elements` output target.
when enabled, it allows a user to generate type declaration files for
their stencil project (that uses `dist-custom-elements`) without also
specifying the `dist` output target.

this experimental flag generates types in the `dist/types` directory.
this destination is not configurable at this time to better understand
the needs of users for generating these types

this commit also adds jsdoc, clarifying comments, and minor type updates 
to the codebase.

src/compiler/config/outputs/validate-custom-element.ts

@@ -1,32 +1,63 @@
-import type { Config, OutputTarget, OutputTargetDistCustomElements, OutputTargetCopy } from '../../../declarations';
+import type {
+  Config,
+  OutputTarget,
+  OutputTargetDistCustomElements,
+  OutputTargetDistTypes,
+  OutputTargetCopy,
+} from '../../../declarations';
 import { getAbsolutePath } from '../config-utils';
-import { isBoolean } from '@utils';
-import { COPY, isOutputTargetDistCustomElements } from '../../output-targets/output-utils';
+import { COPY, DIST_TYPES, isOutputTargetDistCustomElements } from '../../output-targets/output-utils';
 import { validateCopy } from '../validate-copy';
+import { isBoolean } from '@utils';
+import { join } from 'path';
 
-export const validateCustomElement = (config: Config, userOutputs: OutputTarget[]) => {
-  return userOutputs.filter(isOutputTargetDistCustomElements).reduce((arr, o) => {
+/**
+ * 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)
+ */
+export const validateCustomElement = (
+  config: Config,
+  userOutputs: ReadonlyArray<OutputTarget>
+): ReadonlyArray<OutputTargetDistCustomElements | OutputTargetDistTypes | OutputTargetCopy> => {
+  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(outputTarget.empty)) {
       outputTarget.empty = true;
     }
     if (!isBoolean(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);
+    outputs.push(outputTarget);
 
-    return arr;
-  }, [] as (OutputTargetDistCustomElements | OutputTargetCopy)[]);
+    return outputs;
+  }, [] as (OutputTargetDistCustomElements | OutputTargetCopy | OutputTargetDistTypes)[]);
 };

src/compiler/config/test/validate-output-dist-custom-element.spec.ts

@@ -0,0 +1,254 @@
+import type * as d from '@stencil/core/declarations';
+import { mockConfig } from '@stencil/core/testing';
+import { COPY, DIST_CUSTOM_ELEMENTS, DIST_TYPES } from '../../output-targets/output-utils';
+import { validateConfig } from '../validate-config';
+import path from 'path';
+
+describe('validate-output-dist-custom-element', () => {
+  describe('validateCustomElement', () => {
+    const rootDir = path.resolve('/');
+    const defaultDistDir = path.join(rootDir, 'dist', 'components');
+    const distCustomElementsDir = 'my-dist-custom-elements';
+    let userConfig: d.Config;
+
+    beforeEach(() => {
+      userConfig = mockConfig();
+    });
+
+    it('generates a default dist-custom-elements output target', () => {
+      const outputTarget: d.OutputTargetDistCustomElements = {
+        type: DIST_CUSTOM_ELEMENTS,
+      };
+      userConfig.outputTargets = [outputTarget];
+
+      const { config } = validateConfig(userConfig);
+      expect(config.outputTargets).toEqual([
+        {
+          type: DIST_CUSTOM_ELEMENTS,
+          copy: [],
+          dir: defaultDistDir,
+          empty: true,
+          externalRuntime: true,
+        },
+      ]);
+    });
+
+    it('uses a provided dir field over a default directory', () => {
+      const outputTarget: d.OutputTargetDistCustomElements = {
+        type: DIST_CUSTOM_ELEMENTS,
+        dir: distCustomElementsDir,
+      };
+      userConfig.outputTargets = [outputTarget];
+
+      const { config } = validateConfig(userConfig);
+      expect(config.outputTargets).toEqual([
+        {
+          type: DIST_CUSTOM_ELEMENTS,
+          copy: [],
+          dir: path.join(rootDir, distCustomElementsDir),
+          empty: true,
+          externalRuntime: true,
+        },
+      ]);
+    });
+
+    describe('"empty" field', () => {
+      it('defaults the "empty" field to true if not provided', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          externalRuntime: false,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: true,
+            externalRuntime: false,
+          },
+        ]);
+      });
+
+      it('defaults the "empty" field to true it\'s not a boolean', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          empty: undefined,
+          externalRuntime: false,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: true,
+            externalRuntime: false,
+          },
+        ]);
+      });
+    });
+
+    describe('"externalRuntime" field', () => {
+      it('defaults the "externalRuntime" field to true if not provided', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          empty: false,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: false,
+            externalRuntime: true,
+          },
+        ]);
+      });
+
+      it('defaults the "externalRuntime" field to true it\'s not a boolean', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          empty: false,
+          externalRuntime: undefined,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: false,
+            externalRuntime: true,
+          },
+        ]);
+      });
+    });
+
+    describe('"generateTypeDeclarations" field', () => {
+      it('creates a types directory when "generateTypeDeclarations" is true', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          empty: false,
+          externalRuntime: false,
+          generateTypeDeclarations: true,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_TYPES,
+            dir: defaultDistDir,
+            typesDir: path.join(rootDir, 'dist', 'types'),
+          },
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: false,
+            externalRuntime: false,
+            generateTypeDeclarations: true,
+          },
+        ]);
+      });
+
+      it('creates a types directory for a custom directory', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          dir: distCustomElementsDir,
+          empty: false,
+          externalRuntime: false,
+          generateTypeDeclarations: true,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_TYPES,
+            dir: path.join(rootDir, distCustomElementsDir),
+            typesDir: path.join(rootDir, 'dist', 'types'),
+          },
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: path.join(rootDir, distCustomElementsDir),
+            empty: false,
+            externalRuntime: false,
+            generateTypeDeclarations: true,
+          },
+        ]);
+      });
+
+      it('doesn\'t create a types directory when "generateTypeDeclarations" is false', () => {
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          empty: false,
+          externalRuntime: false,
+          generateTypeDeclarations: false,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [],
+            dir: defaultDistDir,
+            empty: false,
+            externalRuntime: false,
+            generateTypeDeclarations: false,
+          },
+        ]);
+      });
+    });
+
+    describe('copy tasks', () => {
+      it('copies existing copy tasks over to the output target', () => {
+        const copyOutputTarget: d.CopyTask = {
+          src: 'mock/src',
+          dest: 'mock/dest',
+        };
+        const copyOutputTarget2: d.CopyTask = {
+          src: 'mock/src2',
+          dest: 'mock/dest2',
+        };
+
+        const outputTarget: d.OutputTargetDistCustomElements = {
+          type: DIST_CUSTOM_ELEMENTS,
+          copy: [copyOutputTarget, copyOutputTarget2],
+          dir: distCustomElementsDir,
+          empty: false,
+          externalRuntime: false,
+        };
+        userConfig.outputTargets = [outputTarget];
+
+        const { config } = validateConfig(userConfig);
+        expect(config.outputTargets).toEqual([
+          {
+            type: COPY,
+            dir: rootDir,
+            copy: [copyOutputTarget, copyOutputTarget2],
+          },
+          {
+            type: DIST_CUSTOM_ELEMENTS,
+            copy: [copyOutputTarget, copyOutputTarget2],
+            dir: path.join(rootDir, distCustomElementsDir),
+            empty: false,
+            externalRuntime: false,
+          },
+        ]);
+      });
+    });
+  });
+});