@stencil/angular-output-target 0.4.0-3 → 0.5.0

package/README.md

@@ -1,3 +1,51 @@
 # @stencil/angular-output-target
 
-This is an output plugin for stencil.
+Stencil can generate Angular component wrappers for your web components. This allows your Stencil components to be used within an Angular application. The benefits of using Stencil's component wrappers over the standard web components include:
+
+- Angular component wrappers will be detached from change detection, preventing unnecessary repaints of your web component.
+- Web component events will be converted to RxJS observables to align with Angular's @Output() and will not emit across component boundaries.
+- Optionally, form control web components can be used as control value accessors with Angular's reactive forms or [ngModel].
+
+For a detailed guide on how to add the angular output target to a project, visit: https://stenciljs.com/docs/angular.
+
+## Installation
+
+```bash
+npm install @stencil/angular-output-target
+```
+
+## Usage
+
+In your `stencil.config.ts` add the following configuration to the `outputTargets` section:
+
+```ts
+import { Config } from '@stencil/core';
+import { angularOutputTarget } from '@stencil/angular-output-target';
+
+export const config: Config = {
+  namespace: 'demo',
+  outputTargets: [
+    angularOutputTarget({
+      componentCorePackage: 'component-library',
+      directivesProxyFile: '../component-library-angular/src/directives/proxies.ts',
+      directivesArrayFile: '../component-library-angular/src/directives/index.ts',
+    }),
+    {
+      type: 'dist',
+      esmLoaderPath: '../loader',
+    },
+  ],
+};
+```
+
+## Config Options
+
+| Property                      | Description                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `componentCorePackage`        | The NPM package name of your Stencil component library. This package is used as a dependency for your Angular wrappers.                                                                                                                                                                                                          |
+| `directivesProxyFile`         | The output file of all the component wrappers generated by the output target. This file path should point to a location within your Angular library/project.                                                                                                                                                                     |
+| `directivesArrayFile`         | The output file of a constant of all the generated component wrapper classes. Used for easily declaring and exporting the generated components from an `NgModule`. This file path should point to a location within your Angular library/project.                                                                                |
+| `valueAccessorConfigs`        | The configuration object for how individual web components behave with Angular control value accessors.                                                                                                                                                                                                                          |
+| `excludeComponents`           | An array of tag names to exclude from generating component wrappers for. This is helpful when have a custom framework implementation of a specific component or need to extend the base component wrapper behavior.                                                                                                              |
+| `includeImportCustomElements` | If `true`, the output target will import the custom element instance and register it with the Custom Elements Registry when the component is imported inside of a user's app. This can only be used with the [Custom Elements Bundle](https://stenciljs.com/docs/custom-elements) and will not work with lazy loaded components. |
+| `customElementsDir`           | This is the directory where the custom elements are imported from when using the [Custom Elements Bundle](https://stenciljs.com/docs/custom-elements). Defaults to the `components` directory. Only applies when `includeImportCustomElements` is `true`.                                                                        |

package/angular-component-lib/utils.ts

@@ -4,46 +4,40 @@ import { fromEvent } from 'rxjs';
 
 export const proxyInputs = (Cmp: any, inputs: string[]) => {
   const Prototype = Cmp.prototype;
-  inputs.forEach(item => {
+  inputs.forEach((item) => {
     Object.defineProperty(Prototype, item, {
       get() {
         return this.el[item];
       },
       set(val: any) {
         this.z.runOutsideAngular(() => (this.el[item] = val));
-      }
+      },
     });
   });
 };
 
 export const proxyMethods = (Cmp: any, methods: string[]) => {
   const Prototype = Cmp.prototype;
-  methods.forEach(methodName => {
+  methods.forEach((methodName) => {
     Prototype[methodName] = function () {
       const args = arguments;
-      return this.z.runOutsideAngular(() =>
-        this.el[methodName].apply(this.el, args)
-      );
+      return this.z.runOutsideAngular(() => this.el[methodName].apply(this.el, args));
     };
   });
 };
 
 export const proxyOutputs = (instance: any, el: any, events: string[]) => {
-  events.forEach(eventName => instance[eventName] = fromEvent(el, eventName));
-}
+  events.forEach((eventName) => (instance[eventName] = fromEvent(el, eventName)));
+};
 
 export const defineCustomElement = (tagName: string, customElement: any) => {
-  if (
-    customElement !== undefined &&
-    typeof customElements !== 'undefined' &&
-    !customElements.get(tagName)
-  ) {
+  if (customElement !== undefined && typeof customElements !== 'undefined' && !customElements.get(tagName)) {
     customElements.define(tagName, customElement);
   }
-}
+};
 
 // tslint:disable-next-line: only-arrow-functions
-export function ProxyCmp(opts: { defineCustomElementFn?: () => void, inputs?: any; methods?: any }) {
+export function ProxyCmp(opts: { defineCustomElementFn?: () => void; inputs?: any; methods?: any }) {
   const decorator = function (cls: any) {
     const { defineCustomElementFn, inputs, methods } = opts;
 

package/dist/generate-angular-component.d.ts

@@ -1,2 +1,22 @@
-import type { ComponentCompilerMeta } from '@stencil/core/internal';
-export declare const createComponentDefinition: (componentCorePackage: string, distTypesDir: string, rootDir: string, includeImportCustomElements?: boolean, customElementsDir?: string) => (cmpMeta: ComponentCompilerMeta) => string;
+import type { ComponentCompilerEvent } from '@stencil/core/internal';
+/**
+ * Creates an Angular component declaration from formatted Stencil compiler metadata.
+ *
+ * @param tagName The tag name of the component.
+ * @param inputs The inputs of the Stencil component (e.g. ['myInput']).
+ * @param outputs The outputs/events of the Stencil component. (e.g. ['myOutput']).
+ * @param methods The methods of the Stencil component. (e.g. ['myMethod']).
+ * @param includeImportCustomElements Whether to define the component as a custom element.
+ * @returns The component declaration as a string.
+ */
+export declare const createAngularComponentDefinition: (tagName: string, inputs: readonly string[], outputs: readonly string[], methods: readonly string[], includeImportCustomElements?: boolean) => string;
+/**
+ * Creates the component interface type definition.
+ * @param tagNameAsPascal The tag name as PascalCase.
+ * @param events The events to generate the interface properties for.
+ * @param componentCorePackage The component core package.
+ * @param includeImportCustomElements Whether to include the import for the custom element definition.
+ * @param customElementsDir The custom elements directory.
+ * @returns The component interface type definition as a string.
+ */
+export declare const createComponentTypeDefinition: (tagNameAsPascal: string, events: readonly ComponentCompilerEvent[], componentCorePackage: string, includeImportCustomElements?: boolean, customElementsDir?: string | undefined) => string;

package/dist/generate-angular-component.js

@@ -1,101 +1,134 @@
-import { dashToPascalCase, normalizePath } from './utils';
-export const createComponentDefinition = (componentCorePackage, distTypesDir, rootDir, includeImportCustomElements = false, customElementsDir = 'components') => (cmpMeta) => {
-    // Collect component meta
-    const inputs = [
-        ...cmpMeta.properties.filter((prop) => !prop.internal).map((prop) => prop.name),
-        ...cmpMeta.virtualProperties.map((prop) => prop.name),
-    ].sort();
-    const outputs = cmpMeta.events.filter((ev) => !ev.internal).map((prop) => prop);
-    const methods = cmpMeta.methods.filter((method) => !method.internal).map((prop) => prop.name);
-    // Process meta
+import { createComponentEventTypeImports, dashToPascalCase, formatToQuotedList } from './utils';
+/**
+ * Creates an Angular component declaration from formatted Stencil compiler metadata.
+ *
+ * @param tagName The tag name of the component.
+ * @param inputs The inputs of the Stencil component (e.g. ['myInput']).
+ * @param outputs The outputs/events of the Stencil component. (e.g. ['myOutput']).
+ * @param methods The methods of the Stencil component. (e.g. ['myMethod']).
+ * @param includeImportCustomElements Whether to define the component as a custom element.
+ * @returns The component declaration as a string.
+ */
+export const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false) => {
+    const tagNameAsPascal = dashToPascalCase(tagName);
+    const hasInputs = inputs.length > 0;
     const hasOutputs = outputs.length > 0;
-    // Generate Angular @Directive
-    const directiveOpts = [
-        `selector: \'${cmpMeta.tagName}\'`,
-        `changeDetection: ChangeDetectionStrategy.OnPush`,
-        `template: '<ng-content></ng-content>'`,
-    ];
-    if (inputs.length > 0) {
-        directiveOpts.push(`inputs: ['${inputs.join(`', '`)}']`);
+    const hasMethods = methods.length > 0;
+    // Formats the input strings into comma separated, single quoted values.
+    const formattedInputs = formatToQuotedList(inputs);
+    // Formats the output strings into comma separated, single quoted values.
+    const formattedOutputs = formatToQuotedList(outputs);
+    // Formats the method strings into comma separated, single quoted values.
+    const formattedMethods = formatToQuotedList(methods);
+    const proxyCmpOptions = [];
+    if (includeImportCustomElements) {
+        const defineCustomElementFn = `define${tagNameAsPascal}`;
+        proxyCmpOptions.push(`\n  defineCustomElementFn: ${defineCustomElementFn}`);
     }
-    const tagNameAsPascal = dashToPascalCase(cmpMeta.tagName);
-    const outputsInterface = new Set();
-    const outputReferenceRemap = {};
-    outputs.forEach((output) => {
-        Object.entries(output.complexType.references).forEach(([reference, refObject]) => {
-            // Add import line for each local/import reference, and add new mapping name.
-            // `outputReferenceRemap` should be updated only if the import interface is set in outputsInterface,
-            // this will prevent global types to be remapped.
-            const remappedReference = `I${cmpMeta.componentClassName}${reference}`;
-            if (refObject.location === 'local' || refObject.location === 'import') {
-                outputReferenceRemap[reference] = remappedReference;
-                let importLocation = componentCorePackage;
-                if (componentCorePackage !== undefined) {
-                    const dirPath = includeImportCustomElements ? `/${customElementsDir || 'components'}` : '';
-                    importLocation = `${normalizePath(componentCorePackage)}${dirPath}`;
-                }
-                outputsInterface.add(`import type { ${reference} as ${remappedReference} } from '${importLocation}';`);
-            }
-        });
-    });
-    const componentEvents = [
-        '' // Empty first line
-    ];
-    // Generate outputs
-    outputs.forEach((output, index) => {
-        componentEvents.push(`  /**
-   * ${output.docs.text} ${output.docs.tags.map((tag) => `@${tag.name} ${tag.text}`)}
-   */`);
-        /**
-         * The original attribute contains the original type defined by the devs.
-         * This regexp normalizes the reference, by removing linebreaks,
-         * replacing consecutive spaces with a single space, and adding a single space after commas.
-         **/
-        const outputTypeRemapped = Object.entries(outputReferenceRemap).reduce((type, [src, dst]) => {
-            return type
-                .replace(new RegExp(`^${src}$`, 'g'), `${dst}`)
-                .replace(new RegExp(`([^\\w])${src}([^\\w])`, 'g'), (v, p1, p2) => [p1, dst, p2].join(''));
-        }, output.complexType.original
-            .replace(/\n/g, ' ')
-            .replace(/\s{2,}/g, ' ')
-            .replace(/,\s*/g, ', '));
-        componentEvents.push(`  ${output.name}: EventEmitter<CustomEvent<${outputTypeRemapped.trim()}>>;`);
-        if (index === outputs.length - 1) {
-            // Empty line to push end `}` to new line
-            componentEvents.push('\n');
-        }
-    });
-    const lines = [
-        '',
-        `${[...outputsInterface].join('\n')}
-export declare interface ${tagNameAsPascal} extends Components.${tagNameAsPascal} {${componentEvents.length > 1 ? componentEvents.join('\n') : ''}}
-
-${getProxyCmp(cmpMeta.tagName, includeImportCustomElements, inputs, methods)}
+    if (hasInputs) {
+        proxyCmpOptions.push(`\n  inputs: [${formattedInputs}]`);
+    }
+    if (hasMethods) {
+        proxyCmpOptions.push(`\n  methods: [${formattedMethods}]`);
+    }
+    /**
+     * Notes on the generated output:
+     * - We disable @angular-eslint/no-inputs-metadata-property, so that
+     * Angular does not complain about the inputs property. The output target
+     * uses the inputs property to define the inputs of the component instead of
+     * having to use the @Input decorator (and manually define the type and default value).
+     */
+    const output = `@ProxyCmp({${proxyCmpOptions.join(',')}\n})
 @Component({
-  ${directiveOpts.join(',\n  ')}
+  selector: '${tagName}',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content></ng-content>',
+  // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
+  inputs: [${formattedInputs}],
 })
-export class ${tagNameAsPascal} {`,
-    ];
-    lines.push('  protected el: HTMLElement;');
-    lines.push(`  constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
+export class ${tagNameAsPascal} {
+  protected el: HTMLElement;
+  constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
-    this.el = r.nativeElement;`);
-    if (hasOutputs) {
-        lines.push(`    proxyOutputs(this, this.el, ['${outputs.map((output) => output.name).join(`', '`)}']);`);
+    this.el = r.nativeElement;${hasOutputs
+        ? `
+    proxyOutputs(this, this.el, [${formattedOutputs}]);`
+        : ''}
+  }
+}`;
+    return output;
+};
+/**
+ * Sanitizes and formats the component event type.
+ * @param componentClassName The class name of the component (e.g. 'MyComponent')
+ * @param event The Stencil component event.
+ * @returns The sanitized event type as a string.
+ */
+const formatOutputType = (componentClassName, event) => {
+    /**
+     * The original attribute contains the original type defined by the devs.
+     * This regexp normalizes the reference, by removing linebreaks,
+     * replacing consecutive spaces with a single space, and adding a single space after commas.
+     */
+    return Object.entries(event.complexType.references)
+        .filter(([_, refObject]) => refObject.location === 'local' || refObject.location === 'import')
+        .reduce((type, [src, dst]) => {
+        const renamedType = `I${componentClassName}${type}`;
+        return (renamedType
+            .replace(new RegExp(`^${src}$`, 'g'), `${dst}`)
+            // Capture all instances of the `src` field surrounded by non-word characters on each side and join them.
+            .replace(new RegExp(`([^\\w])${src}([^\\w])`, 'g'), (v, p1, p2) => [p1, dst, p2].join('')));
+    }, event.complexType.original
+        .replace(/\n/g, ' ')
+        .replace(/\s{2,}/g, ' ')
+        .replace(/,\s*/g, ', '));
+};
+/**
+ * Creates a formatted comment block based on the JS doc comment.
+ * @param doc The compiler jsdoc.
+ * @returns The formatted comment block as a string.
+ */
+const createDocComment = (doc) => {
+    if (doc.text.trim().length === 0 && doc.tags.length === 0) {
+        return '';
     }
-    lines.push(`  }`);
-    lines.push(`}`);
-    return lines.join('\n');
+    return `/**
+   * ${doc.text}${doc.tags.length > 0 ? ' ' : ''}${doc.tags.map((tag) => `@${tag.name} ${tag.text}`)}
+   */`;
+};
+/**
+ * Creates the component interface type definition.
+ * @param tagNameAsPascal The tag name as PascalCase.
+ * @param events The events to generate the interface properties for.
+ * @param componentCorePackage The component core package.
+ * @param includeImportCustomElements Whether to include the import for the custom element definition.
+ * @param customElementsDir The custom elements directory.
+ * @returns The component interface type definition as a string.
+ */
+export const createComponentTypeDefinition = (tagNameAsPascal, events, componentCorePackage, includeImportCustomElements = false, customElementsDir) => {
+    const publicEvents = events.filter((ev) => !ev.internal);
+    const eventTypeImports = createComponentEventTypeImports(tagNameAsPascal, publicEvents, {
+        componentCorePackage,
+        includeImportCustomElements,
+        customElementsDir,
+    });
+    const eventTypes = publicEvents.map((event) => {
+        const comment = createDocComment(event.docs);
+        let eventName = event.name;
+        if (event.name.includes('-')) {
+            // If an event name includes a dash, we need to wrap it in quotes.
+            // https://github.com/ionic-team/stencil-ds-output-targets/issues/212
+            eventName = `'${event.name}'`;
+        }
+        return `${comment.length > 0 ? `  ${comment}` : ''}
+  ${eventName}: EventEmitter<CustomEvent<${formatOutputType(tagNameAsPascal, event)}>>;`;
+    });
+    const interfaceDeclaration = `export declare interface ${tagNameAsPascal} extends Components.${tagNameAsPascal} {`;
+    const typeDefinition = (eventTypeImports.length > 0 ? `${eventTypeImports + '\n\n'}` : '') +
+        `${interfaceDeclaration}${eventTypes.length === 0
+            ? '}'
+            : `
+${eventTypes.join('\n')}
+}`}`;
+    return typeDefinition;
 };
-function getProxyCmp(tagName, includeCustomElement, inputs, methods) {
-    const hasInputs = inputs.length > 0;
-    const hasMethods = methods.length > 0;
-    const proxMeta = [
-        `defineCustomElementFn: ${includeCustomElement ? 'define' + dashToPascalCase(tagName) : 'undefined'}`
-    ];
-    if (hasInputs)
-        proxMeta.push(`inputs: ['${inputs.join(`', '`)}']`);
-    if (hasMethods)
-        proxMeta.push(`methods: ['${methods.join(`', '`)}']`);
-    return `@ProxyCmp({\n  ${proxMeta.join(',\n  ')}\n})`;
-}

package/dist/generate-value-accessors.js

@@ -1,15 +1,12 @@
 import { EOL } from 'os';
 import path from 'path';
 export default async function generateValueAccessors(compilerCtx, components, outputTarget, config) {
-    if (!Array.isArray(outputTarget.valueAccessorConfigs) ||
-        outputTarget.valueAccessorConfigs.length === 0) {
+    if (!Array.isArray(outputTarget.valueAccessorConfigs) || outputTarget.valueAccessorConfigs.length === 0) {
         return;
     }
     const targetDir = path.dirname(outputTarget.directivesProxyFile);
     const normalizedValueAccessors = outputTarget.valueAccessorConfigs.reduce((allAccessors, va) => {
-        const elementSelectors = Array.isArray(va.elementSelectors)
-            ? va.elementSelectors
-            : [va.elementSelectors];
+        const elementSelectors = Array.isArray(va.elementSelectors) ? va.elementSelectors : [va.elementSelectors];
         const type = va.type;
         let allElementSelectors = [];
         let allEventTargets = [];