@stencil/angular-output-target 0.9.1 → 0.10.0

package/README.md

@@ -49,3 +49,4 @@ export const config: Config = {
 | `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"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `inlineProperties` | Experimental. When true, tries to inline the properties of components. This is required to enable Angular Language Service to type-check and show jsdocs when using the components in html-templates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

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

@@ -1,4 +1,4 @@
-import type { ComponentCompilerEvent } from '@stencil/core/internal';
+import type { ComponentCompilerEvent, ComponentCompilerProperty } from '@stencil/core/internal';
 import type { OutputType } from './types';
 /**
  * Creates an Angular component declaration from formatted Stencil compiler metadata.
@@ -9,9 +9,10 @@ import type { OutputType } from './types';
  * @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.
+ * @param inlineComponentProps List of properties that should be inlined into the component definition.
  * @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;
+export declare const createAngularComponentDefinition: (tagName: string, inputs: readonly string[], outputs: readonly string[], methods: readonly string[], includeImportCustomElements?: boolean, standalone?: boolean, inlineComponentProps?: readonly ComponentCompilerProperty[]) => string;
 /**
  * Creates the component interface type definition.
  * @param outputType The output type.

package/dist/generate-angular-component.js

@@ -1,4 +1,22 @@
 import { createComponentEventTypeImports, dashToPascalCase, formatToQuotedList } from './utils';
+/**
+ * Creates a property declaration.
+ *
+ * @param prop A ComponentCompilerEvent or ComponentCompilerProperty to turn into a property declaration.
+ * @param type The name of the type (e.g. 'string')
+ * @returns The property declaration as a string.
+ */
+function createPropertyDeclaration(prop, type) {
+    const comment = createDocComment(prop.docs);
+    let eventName = prop.name;
+    if (/[-/]/.test(prop.name)) {
+        // If a member name includes a dash or a forward slash, we need to wrap it in quotes.
+        // https://github.com/ionic-team/stencil-ds-output-targets/issues/212
+        eventName = `'${prop.name}'`;
+    }
+    return `${comment.length > 0 ? `  ${comment}` : ''}
+  ${eventName}: ${type};`;
+}
 /**
  * Creates an Angular component declaration from formatted Stencil compiler metadata.
  *
@@ -8,9 +26,10 @@ import { createComponentEventTypeImports, dashToPascalCase, formatToQuotedList }
  * @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.
+ * @param inlineComponentProps List of properties that should be inlined into the component definition.
  * @returns The component declaration as a string.
  */
-export const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false) => {
+export const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false, inlineComponentProps = []) => {
     const tagNameAsPascal = dashToPascalCase(tagName);
     const hasInputs = inputs.length > 0;
     const hasOutputs = outputs.length > 0;
@@ -36,6 +55,8 @@ export const createAngularComponentDefinition = (tagName, inputs, outputs, metho
     if (standalone && includeImportCustomElements) {
         standaloneOption = `\n  standalone: true`;
     }
+    const propertyDeclarations = inlineComponentProps.map((m) => createPropertyDeclaration(m, `Components.${tagNameAsPascal}['${m.name}']`));
+    const propertiesDeclarationText = ['protected el: HTMLElement;', ...propertyDeclarations].join('\n  ');
     /**
      * Notes on the generated output:
      * - We disable @angular-eslint/no-inputs-metadata-property, so that
@@ -52,7 +73,7 @@ export const createAngularComponentDefinition = (tagName, inputs, outputs, metho
   inputs: [${formattedInputs}],${standaloneOption}
 })
 export class ${tagNameAsPascal} {
-  protected el: HTMLElement;
+  ${propertiesDeclarationText}
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
     this.el = r.nativeElement;${hasOutputs
@@ -146,17 +167,7 @@ export const createComponentTypeDefinition = (outputType, tagNameAsPascal, event
         customElementsDir,
         outputType,
     });
-    const eventTypes = publicEvents.map((event) => {
-        const comment = createDocComment(event.docs);
-        let eventName = event.name;
-        if (/[-/]/.test(event.name)) {
-            // If an event name includes a dash or a forward slash, 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 eventTypes = publicEvents.map((event) => createPropertyDeclaration(event, `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

package/dist/index.cjs.js

@@ -144,6 +144,24 @@ const EXTENDED_PATH_REGEX = /^\\\\\?\\/;
 const NON_ASCII_REGEX = /[^\x00-\x80]+/;
 const SLASH_REGEX = /\\/g;
 
+/**
+ * Creates a property declaration.
+ *
+ * @param prop A ComponentCompilerEvent or ComponentCompilerProperty to turn into a property declaration.
+ * @param type The name of the type (e.g. 'string')
+ * @returns The property declaration as a string.
+ */
+function createPropertyDeclaration(prop, type) {
+    const comment = createDocComment(prop.docs);
+    let eventName = prop.name;
+    if (/[-/]/.test(prop.name)) {
+        // If a member name includes a dash or a forward slash, we need to wrap it in quotes.
+        // https://github.com/ionic-team/stencil-ds-output-targets/issues/212
+        eventName = `'${prop.name}'`;
+    }
+    return `${comment.length > 0 ? `  ${comment}` : ''}
+  ${eventName}: ${type};`;
+}
 /**
  * Creates an Angular component declaration from formatted Stencil compiler metadata.
  *
@@ -153,9 +171,10 @@ const SLASH_REGEX = /\\/g;
  * @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.
+ * @param inlineComponentProps List of properties that should be inlined into the component definition.
  * @returns The component declaration as a string.
  */
-const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false) => {
+const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false, inlineComponentProps = []) => {
     const tagNameAsPascal = dashToPascalCase(tagName);
     const hasInputs = inputs.length > 0;
     const hasOutputs = outputs.length > 0;
@@ -181,6 +200,8 @@ const createAngularComponentDefinition = (tagName, inputs, outputs, methods, inc
     if (standalone && includeImportCustomElements) {
         standaloneOption = `\n  standalone: true`;
     }
+    const propertyDeclarations = inlineComponentProps.map((m) => createPropertyDeclaration(m, `Components.${tagNameAsPascal}['${m.name}']`));
+    const propertiesDeclarationText = ['protected el: HTMLElement;', ...propertyDeclarations].join('\n  ');
     /**
      * Notes on the generated output:
      * - We disable @angular-eslint/no-inputs-metadata-property, so that
@@ -197,7 +218,7 @@ const createAngularComponentDefinition = (tagName, inputs, outputs, methods, inc
   inputs: [${formattedInputs}],${standaloneOption}
 })
 export class ${tagNameAsPascal} {
-  protected el: HTMLElement;
+  ${propertiesDeclarationText}
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
     this.el = r.nativeElement;${hasOutputs
@@ -291,17 +312,7 @@ const createComponentTypeDefinition = (outputType, tagNameAsPascal, events, comp
         customElementsDir,
         outputType,
     });
-    const eventTypes = publicEvents.map((event) => {
-        const comment = createDocComment(event.docs);
-        let eventName = event.name;
-        if (/[-/]/.test(event.name)) {
-            // If an event name includes a dash or a forward slash, 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 eventTypes = publicEvents.map((event) => createPropertyDeclaration(event, `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
@@ -504,10 +515,11 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
     const { componentCorePackage, customElementsDir } = outputTarget;
     for (let cmpMeta of components) {
         const tagNameAsPascal = dashToPascalCase(cmpMeta.tagName);
-        const inputs = [];
+        const internalProps = [];
         if (cmpMeta.properties) {
-            inputs.push(...cmpMeta.properties.filter(filterInternalProps).map(mapPropName));
+            internalProps.push(...cmpMeta.properties.filter(filterInternalProps));
         }
+        const inputs = internalProps.map(mapPropName);
         if (cmpMeta.virtualProperties) {
             inputs.push(...cmpMeta.virtualProperties.map(mapPropName));
         }
@@ -520,13 +532,14 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
         if (cmpMeta.methods) {
             methods.push(...cmpMeta.methods.filter(filterInternalProps).map(mapPropName));
         }
+        const inlineComponentProps = outputTarget.inlineProperties ? internalProps : [];
         /**
          * For each component, we need to generate:
          * 1. The @Component decorated class
          * 2. Optionally the @NgModule decorated class (if includeSingleComponentAngularModules is true)
          * 3. The component interface (using declaration merging for types).
          */
-        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild);
+        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild, inlineComponentProps);
         const moduleDefinition = generateAngularModuleForComponent(cmpMeta.tagName);
         const componentTypeDefinition = createComponentTypeDefinition(outputType, tagNameAsPascal, cmpMeta.events, componentCorePackage, customElementsDir);
         proxyFileOutput.push(componentDefinition, '\n');

package/dist/index.js

@@ -136,6 +136,24 @@ const EXTENDED_PATH_REGEX = /^\\\\\?\\/;
 const NON_ASCII_REGEX = /[^\x00-\x80]+/;
 const SLASH_REGEX = /\\/g;
 
+/**
+ * Creates a property declaration.
+ *
+ * @param prop A ComponentCompilerEvent or ComponentCompilerProperty to turn into a property declaration.
+ * @param type The name of the type (e.g. 'string')
+ * @returns The property declaration as a string.
+ */
+function createPropertyDeclaration(prop, type) {
+    const comment = createDocComment(prop.docs);
+    let eventName = prop.name;
+    if (/[-/]/.test(prop.name)) {
+        // If a member name includes a dash or a forward slash, we need to wrap it in quotes.
+        // https://github.com/ionic-team/stencil-ds-output-targets/issues/212
+        eventName = `'${prop.name}'`;
+    }
+    return `${comment.length > 0 ? `  ${comment}` : ''}
+  ${eventName}: ${type};`;
+}
 /**
  * Creates an Angular component declaration from formatted Stencil compiler metadata.
  *
@@ -145,9 +163,10 @@ const SLASH_REGEX = /\\/g;
  * @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.
+ * @param inlineComponentProps List of properties that should be inlined into the component definition.
  * @returns The component declaration as a string.
  */
-const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false) => {
+const createAngularComponentDefinition = (tagName, inputs, outputs, methods, includeImportCustomElements = false, standalone = false, inlineComponentProps = []) => {
     const tagNameAsPascal = dashToPascalCase(tagName);
     const hasInputs = inputs.length > 0;
     const hasOutputs = outputs.length > 0;
@@ -173,6 +192,8 @@ const createAngularComponentDefinition = (tagName, inputs, outputs, methods, inc
     if (standalone && includeImportCustomElements) {
         standaloneOption = `\n  standalone: true`;
     }
+    const propertyDeclarations = inlineComponentProps.map((m) => createPropertyDeclaration(m, `Components.${tagNameAsPascal}['${m.name}']`));
+    const propertiesDeclarationText = ['protected el: HTMLElement;', ...propertyDeclarations].join('\n  ');
     /**
      * Notes on the generated output:
      * - We disable @angular-eslint/no-inputs-metadata-property, so that
@@ -189,7 +210,7 @@ const createAngularComponentDefinition = (tagName, inputs, outputs, methods, inc
   inputs: [${formattedInputs}],${standaloneOption}
 })
 export class ${tagNameAsPascal} {
-  protected el: HTMLElement;
+  ${propertiesDeclarationText}
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
     this.el = r.nativeElement;${hasOutputs
@@ -283,17 +304,7 @@ const createComponentTypeDefinition = (outputType, tagNameAsPascal, events, comp
         customElementsDir,
         outputType,
     });
-    const eventTypes = publicEvents.map((event) => {
-        const comment = createDocComment(event.docs);
-        let eventName = event.name;
-        if (/[-/]/.test(event.name)) {
-            // If an event name includes a dash or a forward slash, 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 eventTypes = publicEvents.map((event) => createPropertyDeclaration(event, `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
@@ -496,10 +507,11 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
     const { componentCorePackage, customElementsDir } = outputTarget;
     for (let cmpMeta of components) {
         const tagNameAsPascal = dashToPascalCase(cmpMeta.tagName);
-        const inputs = [];
+        const internalProps = [];
         if (cmpMeta.properties) {
-            inputs.push(...cmpMeta.properties.filter(filterInternalProps).map(mapPropName));
+            internalProps.push(...cmpMeta.properties.filter(filterInternalProps));
         }
+        const inputs = internalProps.map(mapPropName);
         if (cmpMeta.virtualProperties) {
             inputs.push(...cmpMeta.virtualProperties.map(mapPropName));
         }
@@ -512,13 +524,14 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
         if (cmpMeta.methods) {
             methods.push(...cmpMeta.methods.filter(filterInternalProps).map(mapPropName));
         }
+        const inlineComponentProps = outputTarget.inlineProperties ? internalProps : [];
         /**
          * For each component, we need to generate:
          * 1. The @Component decorated class
          * 2. Optionally the @NgModule decorated class (if includeSingleComponentAngularModules is true)
          * 3. The component interface (using declaration merging for types).
          */
-        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild);
+        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild, inlineComponentProps);
         const moduleDefinition = generateAngularModuleForComponent(cmpMeta.tagName);
         const componentTypeDefinition = createComponentTypeDefinition(outputType, tagNameAsPascal, cmpMeta.events, componentCorePackage, customElementsDir);
         proxyFileOutput.push(componentDefinition, '\n');

package/dist/output-angular.js

@@ -101,10 +101,11 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
     const { componentCorePackage, customElementsDir } = outputTarget;
     for (let cmpMeta of components) {
         const tagNameAsPascal = dashToPascalCase(cmpMeta.tagName);
-        const inputs = [];
+        const internalProps = [];
         if (cmpMeta.properties) {
-            inputs.push(...cmpMeta.properties.filter(filterInternalProps).map(mapPropName));
+            internalProps.push(...cmpMeta.properties.filter(filterInternalProps));
         }
+        const inputs = internalProps.map(mapPropName);
         if (cmpMeta.virtualProperties) {
             inputs.push(...cmpMeta.virtualProperties.map(mapPropName));
         }
@@ -117,13 +118,14 @@ ${createImportStatement(componentLibImports, './angular-component-lib/utils')}\n
         if (cmpMeta.methods) {
             methods.push(...cmpMeta.methods.filter(filterInternalProps).map(mapPropName));
         }
+        const inlineComponentProps = outputTarget.inlineProperties ? internalProps : [];
         /**
          * For each component, we need to generate:
          * 1. The @Component decorated class
          * 2. Optionally the @NgModule decorated class (if includeSingleComponentAngularModules is true)
          * 3. The component interface (using declaration merging for types).
          */
-        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild);
+        const componentDefinition = createAngularComponentDefinition(cmpMeta.tagName, inputs, outputs, methods, isCustomElementsBuild, isStandaloneBuild, inlineComponentProps);
         const moduleDefinition = generateAngularModuleForComponent(cmpMeta.tagName);
         const componentTypeDefinition = createComponentTypeDefinition(outputType, tagNameAsPascal, cmpMeta.events, componentCorePackage, customElementsDir);
         proxyFileOutput.push(componentDefinition, '\n');

package/dist/types.d.ts

@@ -27,6 +27,12 @@ export interface OutputTargetAngular {
      * - `standalone` - Generate a component with the `standalone` flag set to `true`.
      */
     outputType?: OutputType;
+    /**
+     * Experimental (!)
+     * When true, tries to inline the properties of components. This is required to enable Angular Language Service
+     * to type-check and show jsdocs when using the components in html-templates.
+     */
+    inlineProperties?: boolean;
 }
 export type ValueAccessorTypes = 'text' | 'radio' | 'select' | 'number' | 'boolean';
 export interface ValueAccessorConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/angular-output-target",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Angular output target for @stencil/core components.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",

package/resources/control-value-accessors/boolean-value-accessor.ts

@@ -21,7 +21,7 @@ export class BooleanValueAccessor extends ValueAccessor {
   constructor(el: ElementRef) {
     super(el);
   }
-  writeValue(value: any) {
+  override writeValue(value: any) {
     this.el.nativeElement.checked = this.lastValue = value == null ? false : value;
   }
 }

package/resources/control-value-accessors/number-value-accessor.ts

@@ -21,7 +21,7 @@ export class NumericValueAccessor extends ValueAccessor {
   constructor(el: ElementRef) {
     super(el);
   }
-  registerOnChange(fn: (_: number | null) => void) {
+  override registerOnChange(fn: (_: number | null) => void) {
     super.registerOnChange(value => {
       fn(value === '' ? null : parseFloat(value));
     });