docs(input, textarea): clarify ionInput and ionChange (#27710)

Issue number: N/A

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

See https://github.com/ionic-team/ionic-framework/issues/27709

The `ionInput` description is vague and does not clarify that it only
fires as the user types.

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Clarified the ionInput description for input and textarea

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!-- If this introduces a breaking change, please describe the impact
and migration path for existing applications below. -->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

angular/src/directives/proxies.ts

@@ -1002,8 +1002,9 @@ import type { InputChangeEventDetail as IIonInputInputChangeEventDetail } from '
 
 export declare interface IonInput extends Components.IonInput {
   /**
-   * The `ionInput` event fires when the `value` of an `<ion-input>` element
+   * The `ionInput` event is fired each time the user modifies the input's value.
-has been changed.
+Unlike the `ionChange` event, the `ionInput` event is fired for each alteration
+to the input's value. This typically happens for each keystroke as the user types.
 
 For elements that accept text input (`type=text`, `type=tel`, etc.), the interface
 is [`InputEvent`](https://developer.mozilla.org/en-US/docs/Web/API/InputEvent); for others,
@@ -1012,9 +1013,9 @@ the input is cleared on edit, the type is `null`.
    */
   ionInput: EventEmitter<CustomEvent<IIonInputInputInputEventDetail>>;
   /**
-   * The `ionChange` event is fired for `<ion-input>` elements when the user
+   * The `ionChange` event is fired when the user modifies the input's value.
-modifies the element's value. Unlike the `ionInput` event, the `ionChange`
+Unlike the `ionInput` event, the `ionChange` event is only fired when changes
-event is not necessarily fired for each alteration to an element's value.
+are committed, not as the user types.
 
 Depending on the way the users interacts with the element, the `ionChange`
 event fires at a different moment:
@@ -2186,17 +2187,15 @@ import type { TextareaInputEventDetail as IIonTextareaTextareaInputEventDetail }
 
 export declare interface IonTextarea extends Components.IonTextarea {
   /**
-   * The `ionChange` event is fired for `<ion-textarea>` elements when the user
+   * The `ionChange` event is fired when the user modifies the textarea's value.
-modifies the element's value. Unlike the `ionInput` event, the `ionChange`
+Unlike the `ionInput` event, the `ionChange` event is fired when
-event is not necessarily fired for each alteration to an element's value.
+the element loses focus after its value has been modified.
-
-The `ionChange` event is fired when the element loses focus after its value
-has been modified.
    */
   ionChange: EventEmitter<CustomEvent<IIonTextareaTextareaChangeEventDetail>>;
   /**
-   * The `ionInput` event fires when the `value` of an `<ion-textarea>` element
+   * The `ionInput` event is fired each time the user modifies the textarea's value.
-has been changed.
+Unlike the `ionChange` event, the `ionInput` event is fired for each alteration
+to the textarea's value. This typically happens for each keystroke as the user types.
 
 When `clearOnEdit` is enabled, the `ionInput` event will be fired when
 the user clears the textarea by performing a keydown event.

core/src/components.d.ts

@@ -5300,7 +5300,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonInputCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-input>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.
+          * The `ionChange` event is fired when the user modifies the input's value. Unlike the `ionInput` event, the `ionChange` event is only fired when changes are committed, not as the user types.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.
          */
         "onIonChange"?: (event: IonInputCustomEvent<InputChangeEventDetail>) => void;
         /**
@@ -5308,7 +5308,7 @@ declare namespace LocalJSX {
          */
         "onIonFocus"?: (event: IonInputCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionInput` event fires when the `value` of an `<ion-input>` element has been changed.  For elements that accept text input (`type=text`, `type=tel`, etc.), the interface is [`InputEvent`](https://developer.mozilla.org/en-US/docs/Web/API/InputEvent); for others, the interface is [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event). If the input is cleared on edit, the type is `null`.
+          * The `ionInput` event is fired each time the user modifies the input's value. Unlike the `ionChange` event, the `ionInput` event is fired for each alteration to the input's value. This typically happens for each keystroke as the user types.  For elements that accept text input (`type=text`, `type=tel`, etc.), the interface is [`InputEvent`](https://developer.mozilla.org/en-US/docs/Web/API/InputEvent); for others, the interface is [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event). If the input is cleared on edit, the type is `null`.
          */
         "onIonInput"?: (event: IonInputCustomEvent<InputInputEventDetail>) => void;
         /**
@@ -7122,7 +7122,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-textarea>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  The `ionChange` event is fired when the element loses focus after its value has been modified.
+          * The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified.
          */
         "onIonChange"?: (event: IonTextareaCustomEvent<TextareaChangeEventDetail>) => void;
         /**
@@ -7130,7 +7130,7 @@ declare namespace LocalJSX {
          */
         "onIonFocus"?: (event: IonTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionInput` event fires when the `value` of an `<ion-textarea>` element has been changed.  When `clearOnEdit` is enabled, the `ionInput` event will be fired when the user clears the textarea by performing a keydown event.
+          * The `ionInput` event is fired each time the user modifies the textarea's value. Unlike the `ionChange` event, the `ionInput` event is fired for each alteration to the textarea's value. This typically happens for each keystroke as the user types.  When `clearOnEdit` is enabled, the `ionInput` event will be fired when the user clears the textarea by performing a keydown event.
          */
         "onIonInput"?: (event: IonTextareaCustomEvent<TextareaInputEventDetail>) => void;
         /**

core/src/components/input/input.tsx

@@ -284,8 +284,9 @@ export class Input implements ComponentInterface {
   @Prop({ mutable: true }) value?: string | number | null = '';
 
   /**
-   * The `ionInput` event fires when the `value` of an `<ion-input>` element
+   * The `ionInput` event is fired each time the user modifies the input's value.
-   * has been changed.
+   * Unlike the `ionChange` event, the `ionInput` event is fired for each alteration
+   * to the input's value. This typically happens for each keystroke as the user types.
    *
    * For elements that accept text input (`type=text`, `type=tel`, etc.), the interface
    * is [`InputEvent`](https://developer.mozilla.org/en-US/docs/Web/API/InputEvent); for others,
@@ -295,9 +296,9 @@ export class Input implements ComponentInterface {
   @Event() ionInput!: EventEmitter<InputInputEventDetail>;
 
   /**
-   * The `ionChange` event is fired for `<ion-input>` elements when the user
+   * The `ionChange` event is fired when the user modifies the input's value.
-   * modifies the element's value. Unlike the `ionInput` event, the `ionChange`
+   * Unlike the `ionInput` event, the `ionChange` event is only fired when changes
-   * event is not necessarily fired for each alteration to an element's value.
+   * are committed, not as the user types.
    *
    * Depending on the way the users interacts with the element, the `ionChange`
    * event fires at a different moment:

core/src/components/textarea/textarea.tsx

@@ -275,18 +275,16 @@ export class Textarea implements ComponentInterface {
   }
 
   /**
-   * The `ionChange` event is fired for `<ion-textarea>` elements when the user
+   * The `ionChange` event is fired when the user modifies the textarea's value.
-   * modifies the element's value. Unlike the `ionInput` event, the `ionChange`
+   * Unlike the `ionInput` event, the `ionChange` event is fired when
-   * event is not necessarily fired for each alteration to an element's value.
+   * the element loses focus after its value has been modified.
-   *
-   * The `ionChange` event is fired when the element loses focus after its value
-   * has been modified.
    */
   @Event() ionChange!: EventEmitter<TextareaChangeEventDetail>;
 
   /**
-   * The `ionInput` event fires when the `value` of an `<ion-textarea>` element
+   * The `ionInput` event is fired each time the user modifies the textarea's value.
-   * has been changed.
+   * Unlike the `ionChange` event, the `ionInput` event is fired for each alteration
+   * to the textarea's value. This typically happens for each keystroke as the user types.
    *
    * When `clearOnEdit` is enabled, the `ionInput` event will be fired when
    * the user clears the textarea by performing a keydown event.