feat(all): add CustomEvents types to components that emit events (#23956

)

resolves #22925

BREAKING CHANGE: The `RadioChangeEventDetail` interface has been removed in favor of `RadioGroupChangeEventDetail`.

BREAKING.md

@@ -18,6 +18,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
   * [Input](#input)
   * [Modal](#modal)
   * [Popover](#popover)
+  * [Radio](#radio)
   * [Searchbar](#searchbar)
   * [Select](#select)
   * [Tab Bar](#tab-bar)
@@ -106,6 +107,10 @@ Converted `ion-popover` to use [Shadow DOM](https://developer.mozilla.org/en-US/
 
 If you were targeting the internals of `ion-popover` in your CSS, you will need to target the `backdrop`, `arrow`, or `content` [Shadow Parts](https://ionicframework.com/docs/theming/css-shadow-parts) instead, or use the provided CSS Variables.
 
+#### Radio
+
+The `RadioChangeEventDetail` interface has been removed. Instead, listen for the `ionChange` event on `ion-radio-group` and use the `RadioGroupChangeEventDetail` interface.
+
 #### Searchbar
 
 The `showClearButton` property now defaults to `'always'` for improved usability with screen readers.

angular/src/index.ts

@@ -44,11 +44,19 @@ export * from './types/ionic-lifecycle-hooks';
 // PACKAGE MODULE
 export { IonicModule } from './ionic-module';
 
-// UTILS
-export { PlatformConfig, IonicSafeString, getPlatforms, isPlatform, createAnimation, IonicSwiper } from '@ionic/core';
-
-// CORE TYPES
 export {
+  // UTILS
+  createAnimation,
+  createGesture,
+  iosTransitionAnimation,
+  mdTransitionAnimation,
+  setupConfig,
+  IonicSwiper,
+  getPlatforms,
+  isPlatform,
+  getTimeGivenProgression,
+
+  // TYPES
   Animation,
   AnimationBuilder,
   AnimationCallbackOptions,
@@ -59,12 +67,16 @@ export {
   Gesture,
   GestureConfig,
   GestureDetail,
-  mdTransitionAnimation,
-  iosTransitionAnimation,
   NavComponentWithProps,
 
   SpinnerTypes,
 
+  AccordionGroupCustomEvent,
+  AccordionGroupChangeEventDetail,
+
+  BreadcrumbCustomEvent,
+  BreadcrumbCollapsedClickEventDetail,
+
   ActionSheetOptions,
   ActionSheetButton,
 
@@ -74,18 +86,74 @@ export {
   AlertInputAttributes,
   AlertButton,
 
+  BackButtonEvent,
+
+  CheckboxCustomEvent,
+  CheckboxChangeEventDetail,
+
+  DatetimeCustomEvent,
+  DatetimeChangeEventDetail,
+
+  InfiniteScrollCustomEvent,
+
+  InputCustomEvent,
+  InputChangeEventDetail,
+
+  ItemReorderEventDetail,
+  ItemReorderCustomEvent,
+
+  ItemSlidingCustomEvent,
+
+  IonicSafeString,
+
   LoadingOptions,
 
+  MenuCustomEvent,
+
   ModalOptions,
 
+  NavCustomEvent,
+
   PickerOptions,
   PickerButton,
   PickerColumn,
   PickerColumnOption,
 
+  PlatformConfig,
+
   PopoverOptions,
 
+  RadioGroupCustomEvent,
+  RadioGroupChangeEventDetail,
+
+  RefresherCustomEvent,
+  RefresherEventDetail,
+
+  RouterEventDetail,
+  RouterCustomEvent,
+
+  ScrollBaseCustomEvent,
+  ScrollBaseDetail,
+  ScrollDetail,
+  ScrollCustomEvent,
+
+  SearchbarCustomEvent,
+  SearchbarChangeEventDetail,
+
+  SegmentChangeEventDetail,
+  SegmentCustomEvent,
+
+  SelectChangeEventDetail,
+  SelectCustomEvent,
+
+  TabsCustomEvent,
+
+  TextareaChangeEventDetail,
+  TextareaCustomEvent,
+
   ToastOptions,
-  ToastButton
+  ToastButton,
 
+  ToggleChangeEventDetail,
+  ToggleCustomEvent,
 } from '@ionic/core';

core/api.txt

@@ -1407,7 +1407,7 @@ ion-toggle,prop,mode,"ios" | "md",undefined,false,false
 ion-toggle,prop,name,string,this.inputId,false,false
 ion-toggle,prop,value,null | string | undefined,'on',false,false
 ion-toggle,event,ionBlur,void,true
-ion-toggle,event,ionChange,ToggleChangeEventDetail,true
+ion-toggle,event,ionChange,ToggleChangeEventDetail<any>,true
 ion-toggle,event,ionFocus,void,true
 ion-toggle,css-prop,--background
 ion-toggle,css-prop,--background-checked

core/src/components/accordion-group/accordion-group-interface.ts

@@ -2,7 +2,7 @@ export interface AccordionGroupChangeEventDetail<T = any> {
   value: T;
 }
 
-export interface AccordionGroupChangeEvent extends CustomEvent {
-  detail: AccordionGroupChangeEventDetail;
+export interface AccordionGroupCustomEvent<T = any> extends CustomEvent {
+  detail: AccordionGroupChangeEventDetail<T>;
   target: HTMLIonAccordionGroupElement;
 }

core/src/components/accordion-group/readme.md

@@ -4,6 +4,27 @@ Accordion group is a container for accordion instances. It manages the state of
 
 For more information as well as usage, see the [Accordion Documentation](./accordion)
 
+## Interfaces
+
+### AccordionGroupChangeEventDetail
+
+```typescript
+interface AccordionGroupChangeEventDetail<T = any> {
+  value: T;
+}
+```
+
+### AccordionGroupCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface AccordionGroupCustomEvent<T = any> extends CustomEvent {
+  detail: AccordionGroupChangeEventDetail<T>;
+  target: HTMLIonAccordionGroupElement;
+}
+```
+
 <!-- Auto Generated Below -->
 
 

core/src/components/breadcrumb/breadcrumb-interface.ts

@@ -2,3 +2,8 @@ export interface BreadcrumbCollapsedClickEventDetail {
   ionShadowTarget?: HTMLElement;
   collapsedBreadcrumbs?: HTMLIonBreadcrumbElement[];
 }
+
+export interface BreadcrumbCustomEvent extends CustomEvent {
+  detail: BreadcrumbCollapsedClickEventDetail;
+  target: HTMLIonBreadcrumbElement;
+}

core/src/components/breadcrumb/readme.md

@@ -2,6 +2,27 @@
 
 A Breadcrumb is a single navigation item that is a child of the Breadcrumbs component. A breadcrumb can link elsewhere in an app or it can be plain text. Each breadcrumb has a separator between it and the next breadcrumb and can optionally contain an icon.
 
+## Interfaces
+
+### BreadcrumbCollapsedClickEventDetail
+
+```typescript
+interface BreadcrumbCollapsedClickEventDetail {
+  collapsedBreadcrumbs?: HTMLIonBreadcrumbElement[];
+}
+```
+
+### BreadcrumbCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing .
+
+```typescript
+interface BreadcrumbCustomEvent extends CustomEvent {
+  detail: BreadcrumbCollapsedClickEventDetail;
+  target: HTMLIonBreadcrumbElement;
+}
+```
+
 
 <!-- Auto Generated Below -->
 

core/src/components/checkbox/checkbox-interface.ts

@@ -3,3 +3,8 @@ export interface CheckboxChangeEventDetail<T = any> {
   value: T;
   checked: boolean;
 }
+
+export interface CheckboxCustomEvent<T = any> extends CustomEvent {
+  detail: CheckboxChangeEventDetail<T>;
+  target: HTMLIonCheckboxElement;
+}

core/src/components/checkbox/readme.md

@@ -2,7 +2,27 @@
 
 Checkboxes allow the selection of multiple options from a set of options. They appear as checked (ticked) when activated. Clicking on a checkbox will toggle the `checked` property. They can also be checked programmatically by setting the `checked` property.
 
+## Interfaces
 
+### CheckboxChangeEventDetail
+
+```typescript
+interface CheckboxChangeEventDetail<T = any> {
+  value: T;
+  checked: boolean;
+}
+```
+
+### CheckboxCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface CheckboxCustomEvent<T = any> extends CustomEvent {
+  detail: CheckboxChangeEventDetail<T>;
+  target: HTMLIonCheckboxElement;
+}
+```
 
 
 <!-- Auto Generated Below -->

core/src/components/content/content-interface.ts

@@ -10,3 +10,12 @@ export interface ScrollDetail extends GestureDetail, ScrollBaseDetail {
 }
 
 export type ScrollCallback = (detail?: ScrollDetail) => boolean | void;
+
+export interface ScrollBaseCustomEvent extends CustomEvent {
+  detail: ScrollBaseDetail;
+  target: HTMLIonContentElement;
+}
+
+export interface ScrollCustomEvent extends ScrollBaseCustomEvent {
+  detail: ScrollDetail;
+}

core/src/components/content/readme.md

@@ -11,6 +11,46 @@ Content, along with many other Ionic components, can be customized to modify its
 
 In order to place elements outside of the scrollable area, `slot="fixed"` can be added to the element. This will absolutely position the element placing it in the top left. In order to place the element in a different position, style it using [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position).
 
+## Interfaces
+
+### ScrollBaseDetail
+
+```typescript
+interface ScrollBaseDetail {
+  isScrolling: boolean;
+}
+```
+
+### ScrollDetail
+
+```typescript
+interface ScrollDetail extends GestureDetail, ScrollBaseDetail {
+  scrollTop: number;
+  scrollLeft: number;
+}
+```
+
+### ScrollBaseCustomEvent 
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScrollStart` and `ionScrollEnd` events.
+
+```typescript
+interface ScrollBaseCustomEvent extends CustomEvent {
+  detail: ScrollBaseDetail;
+  target: HTMLIonContentElement;
+}
+```
+
+### ScrollCustomEvent 
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScroll` event.
+
+```typescript
+interface ScrollCustomEvent extends ScrollBaseCustomEvent {
+  detail: ScrollDetail;
+}
+```
+
 
 <!-- Auto Generated Below -->
 

core/src/components/datetime/datetime-interface.ts

@@ -6,6 +6,11 @@ export interface DatetimeChangeEventDetail {
   value?: string | null;
 }
 
+export interface DatetimeCustomEvent extends CustomEvent {
+  detail: DatetimeChangeEventDetail;
+  target: HTMLIonDatetimeElement;
+}
+
 export interface DatetimeParts {
   month: number;
   day: number | null;

core/src/components/datetime/readme.md

@@ -183,6 +183,27 @@ dates in JavaScript.
 | `Shift` + `PageUp` | Changes the grid of dates to the previous year. |
 | `Shift` + `PageDown` | Changes the grid of dates to the next year. |
 
+## Interfaces
+
+### DatetimeChangeEventDetail
+
+```typescript
+interface DatetimeChangeEventDetail {
+  value?: string | null;
+}
+```
+
+### DatetimeCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface DatetimeCustomEvent extends CustomEvent {
+  detail: DatetimeChangeEventDetail;
+  target: HTMLIonDatetimeElement;
+}
+```
+
 <!-- Auto Generated Below -->
 
 

core/src/components/infinite-scroll/infinite-scroll-interface.ts

@@ -0,0 +1,3 @@
+export interface InfiniteScrollCustomEvent extends CustomEvent {
+  target: HTMLIonInfiniteScrollElement;
+}

core/src/components/infinite-scroll/readme.md

@@ -12,6 +12,18 @@ The `ion-infinite-scroll` component has the infinite scroll logic. It requires a
 
 Separating the `ion-infinite-scroll` and `ion-infinite-scroll-content` components allows developers to create their own content components, if desired. This content can contain anything, from an SVG element to elements with unique CSS animations.
 
+## Interfaces
+
+### InfiniteScrollCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface InfiniteScrollCustomEvent extends CustomEvent {
+  target: HTMLIonInfiniteScrollElement;
+}
+```
+
 <!-- Auto Generated Below -->
 
 

core/src/components/input/input-interface.ts

@@ -2,3 +2,8 @@
 export interface InputChangeEventDetail {
   value: string | undefined | null;
 }
+
+export interface InputCustomEvent extends CustomEvent {
+  detail: InputChangeEventDetail;
+  target: HTMLIonInputElement;
+}