feat: Custom HTMLElement type for event targets

[sean-perkins]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already include this feature request, without success.

Describe the Feature Request

Export additional type data on the generated component interfaces, that allows developers to have typings for the event target with custom events.

i.e.:

"onIonInfinite"?: (event: CustomEvent<void> & { target: HTMLIonInfiniteScrollElement }) => void;

Usage:

<ion-infinite onIonInfinite={ev => ev.target.complete()} />

The ev.target would allow accessing all the public methods available on the host element.

Additionally it would be valuable to export the custom event type as an interface for each event, so that development eco-systems like Angular can access the reusable type:

handleInfiniteScroll(ev: InfiniteScrollEvent<void>) {
  ev.target.complete();
}

Describe the Use Case

When the event is emitted, it already contains information around the target, but does not include any type information in the generated types. This is problematic because developers have to re-cast or use any for event handlers.

Ideally, developers would like to directly access the correct typings the event target, without having to recast:

<ion-infinite onIonInfinite={ev => ev.target.complete()} />

Describe Preferred Solution

There are two changes that are necessary to support this (from the generated output).

1. Each custom event will need a type that includes a reference to the HTMLElement, such as:

"onIonInfinite"?: (event: CustomEvent<void> & { target: HTMLIonInfiniteScrollElement }) => void;

2. Ideally this event type is not inlined and rather a generated public type that is consumed for this type, but available to implementers:

"onIonInfinite"?: InfiniteScrollEvent<void>;

export type InfiniteScrollEvent = <T=any>(event: CustomEvent<T> & { target: HTMLIonInfiniteScrollElement }) => void;

Describe Alternatives

No response

Related Code

I have the first case outlined above handled with this:

export const generateEventTypes = (cmpEvents: d.ComponentCompilerEvent[], cmpHtmlElementInterface: string): d.TypeInfo => {
  return cmpEvents.map((cmpEvent) => {
    const name = `on${toTitleCase(cmpEvent.name)}`;
    const targetType = `{ target: ${cmpHtmlElementInterface} }`;
    const type = cmpEvent.complexType.original
      ? `(event: CustomEvent<${cmpEvent.complexType.original}> & ${targetType}) => void`
      : `CustomEvent & ${targetType}`;
    return {
      name,
      type,
      optional: false,
      required: false,
      internal: cmpEvent.internal,
      jsdoc: getTextDocs(cmpEvent.docs),
    };
  });
};

I will investigate the work effort of the second item.

Additional Information

Related issues:

Framework:

• Angular issue: bug: Angular - Argument of type 'Event' is not assignable to parameter of type 'CustomEvent<XXX>'.  ionic-framework#24245
• React issue: bug: Stencil components have incorrect event types ionic-framework#24952

Stencil output targets:

• Angular binding error : Argument of type 'Event' is not assignable to parameter of type CustomEvent stencil-ds-output-targets#219

[rwaskiewicz]

I'm going to close this issue, as the related-PR (#3296) is a part of today's Stencil v2.16.0 release. Thanks again!