@stencil/angular-output-target 0.0.0-dev.11698339436.1d39048b

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2019-present Drifty Co.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @stencil/angular-output-target
+
+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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `outputType`           | Specifies the type of output to be generated. It can take one of the following values: <br />1. `component`: Generates all the component wrappers to be declared on an Angular module. This option is required for Stencil projects using the `dist` hydrated output.<br /> 2. `scam`: Generates a separate Angular module for each component.<br /> 3. `standalone`: Generates standalone component wrappers.<br /> Both `scam` and `standalone` options are compatible with the `dist-custom-elements` output. <br />Note: Please choose the appropriate `outputType` based on your project's requirements and the desired output structure. Defaults to `component`. |
+| `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 for `outputType: "scam"` or `outputType: "standalone"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

package/angular-component-lib/utils.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+/* tslint:disable */
+import { fromEvent } from 'rxjs';
+
+export const proxyInputs = (Cmp: any, inputs: string[]) => {
+  const Prototype = Cmp.prototype;
+  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) => {
+    Prototype[methodName] = function () {
+      const args = arguments;
+      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)));
+};
+
+export const defineCustomElement = (tagName: string, customElement: any) => {
+  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 }) {
+  const decorator = function (cls: any) {
+    const { defineCustomElementFn, inputs, methods } = opts;
+
+    if (defineCustomElementFn !== undefined) {
+      defineCustomElementFn();
+    }
+
+    if (inputs) {
+      proxyInputs(cls, inputs);
+    }
+    if (methods) {
+      proxyMethods(cls, methods);
+    }
+    return cls;
+  };
+  return decorator;
+}

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

@@ -0,0 +1,24 @@
+import type { ComponentCompilerEvent } from '@stencil/core/internal';
+import type { OutputType } from './types';
+/**
+ * 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.
+ * @param standalone Whether to define the component as a standalone component.
+ * @returns The component declaration as a string.
+ */
+export declare const createAngularComponentDefinition: (tagName: string, inputs: readonly string[], outputs: readonly string[], methods: readonly string[], includeImportCustomElements?: boolean, standalone?: boolean) => string;
+/**
+ * Creates the component interface type definition.
+ * @param outputType The output type.
+ * @param tagNameAsPascal The tag name as PascalCase.
+ * @param events The events to generate the interface properties for.
+ * @param componentCorePackage The component core package.
+ * @param customElementsDir The custom elements directory.
+ * @returns The component interface type definition as a string.
+ */
+export declare const createComponentTypeDefinition: (outputType: OutputType, tagNameAsPascal: string, events: readonly ComponentCompilerEvent[], componentCorePackage: string, customElementsDir?: string | undefined) => string;

package/dist/generate-angular-component.js

@@ -0,0 +1,153 @@
+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.
+ * @param standalone Whether to define the component as a standalone component.
+ * @returns The component declaration as a string.
+ */
+export const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false) => {
+    const tagNameAsPascal = dashToPascalCase(tagName);
+    const hasInputs = inputs.length > 0;
+    const hasOutputs = outputs.length > 0;
+    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}`);
+    }
+    if (hasInputs) {
+        proxyCmpOptions.push(`\n  inputs: [${formattedInputs}]`);
+    }
+    if (hasMethods) {
+        proxyCmpOptions.push(`\n  methods: [${formattedMethods}]`);
+    }
+    let standaloneOption = '';
+    if (standalone && includeImportCustomElements) {
+        standaloneOption = `\n  standalone: true`;
+    }
+    /**
+     * 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({
+  selector: '${tagName}',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content></ng-content>',
+  // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
+  inputs: [${formattedInputs}],${standaloneOption}
+})
+export class ${tagNameAsPascal} {
+  protected el: HTMLElement;
+  constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
+    c.detach();
+    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) => {
+    const prefix = `I${componentClassName}`;
+    /**
+     * 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]) => {
+        let renamedType = type;
+        if (!type.startsWith(prefix)) {
+            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) => {
+            if ((dst === null || dst === void 0 ? void 0 : dst.location) === 'import') {
+                /**
+                 * Replaces a complex type reference within a generic type.
+                 * For example, remapping a type like `EventEmitter<CustomEvent<MyEvent<T>>>` to
+                 * `EventEmitter<CustomEvent<IMyComponentMyEvent<IMyComponentT>>>`.
+                 */
+                return [p1, `I${componentClassName}${v.substring(1, v.length - 1)}`, p2].join('');
+            }
+            return [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 '';
+    }
+    return `/**
+   * ${doc.text}${doc.tags.length > 0 ? ' ' : ''}${doc.tags.map((tag) => `@${tag.name} ${tag.text}`)}
+   */`;
+};
+/**
+ * Creates the component interface type definition.
+ * @param outputType The output type.
+ * @param tagNameAsPascal The tag name as PascalCase.
+ * @param events The events to generate the interface properties for.
+ * @param componentCorePackage The component core package.
+ * @param customElementsDir The custom elements directory.
+ * @returns The component interface type definition as a string.
+ */
+export const createComponentTypeDefinition = (outputType, tagNameAsPascal, events, componentCorePackage, customElementsDir) => {
+    const publicEvents = events.filter((ev) => !ev.internal);
+    const eventTypeImports = createComponentEventTypeImports(tagNameAsPascal, publicEvents, {
+        componentCorePackage,
+        customElementsDir,
+        outputType,
+    });
+    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;
+};

package/dist/generate-angular-directives-file.d.ts

@@ -0,0 +1,3 @@
+import type { OutputTargetAngular } from './types';
+import type { CompilerCtx, ComponentCompilerMeta } from '@stencil/core/internal';
+export declare function generateAngularDirectivesFile(compilerCtx: CompilerCtx, components: ComponentCompilerMeta[], outputTarget: OutputTargetAngular): Promise<any>;

package/dist/generate-angular-directives-file.js

@@ -0,0 +1,20 @@
+import { dashToPascalCase, relativeImport } from './utils';
+export function generateAngularDirectivesFile(compilerCtx, components, outputTarget) {
+    // Only create the file if it is defined in the stencil configuration
+    if (!outputTarget.directivesArrayFile) {
+        return Promise.resolve();
+    }
+    const proxyPath = relativeImport(outputTarget.directivesArrayFile, outputTarget.directivesProxyFile, '.ts');
+    const directives = components
+        .map((cmpMeta) => dashToPascalCase(cmpMeta.tagName))
+        .map((className) => `d.${className}`)
+        .join(',\n  ');
+    const c = `
+import * as d from '${proxyPath}';
+
+export const DIRECTIVES = [
+  ${directives}
+];
+`;
+    return compilerCtx.fs.writeFile(outputTarget.directivesArrayFile, c);
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Creates an Angular module declaration for a component wrapper.
+ * @param componentTagName The tag name of the Stencil component.
+ * @returns The Angular module declaration as a string.
+ */
+export declare const generateAngularModuleForComponent: (componentTagName: string) => string;

package/dist/generate-angular-modules.js

@@ -0,0 +1,17 @@
+import { dashToPascalCase } from './utils';
+/**
+ * Creates an Angular module declaration for a component wrapper.
+ * @param componentTagName The tag name of the Stencil component.
+ * @returns The Angular module declaration as a string.
+ */
+export const generateAngularModuleForComponent = (componentTagName) => {
+    const tagNameAsPascal = dashToPascalCase(componentTagName);
+    const componentClassName = `${tagNameAsPascal}`;
+    const moduleClassName = `${tagNameAsPascal}Module`;
+    const moduleDefinition = `@NgModule({
+  declarations: [${componentClassName}],
+  exports: [${componentClassName}]
+})
+export class ${moduleClassName} { }`;
+    return moduleDefinition;
+};

package/dist/generate-value-accessors.d.ts

@@ -0,0 +1,8 @@
+import type { OutputTargetAngular } from './types';
+import type { CompilerCtx, ComponentCompilerMeta, Config } from '@stencil/core/internal';
+export interface ValueAccessor {
+    elementSelectors: string[];
+    eventTargets: [string, string][];
+}
+export default function generateValueAccessors(compilerCtx: CompilerCtx, components: ComponentCompilerMeta[], outputTarget: OutputTargetAngular, config: Config): Promise<void>;
+export declare function createValueAccessor(srcFileContents: string, valueAccessor: ValueAccessor): string;

package/dist/generate-value-accessors.js

@@ -0,0 +1,56 @@
+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) {
+        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 type = va.type;
+        let allElementSelectors = [];
+        let allEventTargets = [];
+        if (allAccessors.hasOwnProperty(type)) {
+            allElementSelectors = allAccessors[type].elementSelectors;
+            allEventTargets = allAccessors[type].eventTargets;
+        }
+        return Object.assign(Object.assign({}, allAccessors), { [type]: {
+                elementSelectors: allElementSelectors.concat(elementSelectors),
+                eventTargets: allEventTargets.concat([[va.event, va.targetAttr]]),
+            } });
+    }, {});
+    await Promise.all(Object.keys(normalizedValueAccessors).map(async (type) => {
+        const valueAccessorType = type; // Object.keys converts to string
+        const targetFileName = `${type}-value-accessor.ts`;
+        const targetFilePath = path.join(targetDir, targetFileName);
+        const srcFilePath = path.join(__dirname, '../resources/control-value-accessors/', targetFileName);
+        const srcFileContents = await compilerCtx.fs.readFile(srcFilePath);
+        const finalText = createValueAccessor(srcFileContents, normalizedValueAccessors[valueAccessorType]);
+        await compilerCtx.fs.writeFile(targetFilePath, finalText);
+    }));
+    await copyResources(config, ['value-accessor.ts'], targetDir);
+}
+export function createValueAccessor(srcFileContents, valueAccessor) {
+    const hostContents = valueAccessor.eventTargets.map((listItem) => VALUE_ACCESSOR_EVENTTARGETS.replace(VALUE_ACCESSOR_EVENT, listItem[0]).replace(VALUE_ACCESSOR_TARGETATTR, listItem[1]));
+    return srcFileContents
+        .replace(VALUE_ACCESSOR_SELECTORS, valueAccessor.elementSelectors.join(', '))
+        .replace(VALUE_ACCESSOR_EVENTTARGETS, hostContents.join(`,${EOL}`));
+}
+function copyResources(config, resourcesFilesToCopy, directory) {
+    if (!config.sys || !config.sys.copy) {
+        throw new Error('stencil is not properly intialized at this step. Notify the developer');
+    }
+    const copyTasks = resourcesFilesToCopy.map((rf) => {
+        return {
+            src: path.join(__dirname, '../resources/control-value-accessors/', rf),
+            dest: path.join(directory, rf),
+            keepDirStructure: false,
+            warn: false,
+        };
+    });
+    return config.sys.copy(copyTasks, path.join(directory));
+}
+const VALUE_ACCESSOR_SELECTORS = `<VALUE_ACCESSOR_SELECTORS>`;
+const VALUE_ACCESSOR_EVENT = `<VALUE_ACCESSOR_EVENT>`;
+const VALUE_ACCESSOR_TARGETATTR = '<VALUE_ACCESSOR_TARGETATTR>';
+const VALUE_ACCESSOR_EVENTTARGETS = `    '(<VALUE_ACCESSOR_EVENT>)': 'handleChangeEvent($event.target.<VALUE_ACCESSOR_TARGETATTR>)'`;