feat(datetime): add clear button (#23920)

resolves #17482 

Co-authored-by: Liam DeBeasi <liamdebeasi@users.noreply.github.com>

angular/src/directives/proxies.ts

@@ -244,8 +244,8 @@ export class IonContent {
 }
 export declare interface IonDatetime extends Components.IonDatetime {
 }
-@ProxyCmp({ inputs: ["cancelText", "color", "dayValues", "disabled", "doneText", "firstDayOfWeek", "hourCycle", "hourValues", "locale", "max", "min", "minuteValues", "mode", "monthValues", "name", "presentation", "readonly", "showDefaultButtons", "showDefaultTimeLabel", "showDefaultTitle", "size", "value", "yearValues"], "methods": ["confirm", "reset", "cancel"] })
+@ProxyCmp({ inputs: ["cancelText", "clearText", "color", "dayValues", "disabled", "doneText", "firstDayOfWeek", "hourCycle", "hourValues", "locale", "max", "min", "minuteValues", "mode", "monthValues", "name", "presentation", "readonly", "showClearButton", "showDefaultButtons", "showDefaultTimeLabel", "showDefaultTitle", "size", "value", "yearValues"], "methods": ["confirm", "reset", "cancel"] })
-@Component({ selector: "ion-datetime", changeDetection: ChangeDetectionStrategy.OnPush, template: "<ng-content></ng-content>", inputs: ["cancelText", "color", "dayValues", "disabled", "doneText", "firstDayOfWeek", "hourCycle", "hourValues", "locale", "max", "min", "minuteValues", "mode", "monthValues", "name", "presentation", "readonly", "showDefaultButtons", "showDefaultTimeLabel", "showDefaultTitle", "size", "value", "yearValues"] })
+@Component({ selector: "ion-datetime", changeDetection: ChangeDetectionStrategy.OnPush, template: "<ng-content></ng-content>", inputs: ["cancelText", "clearText", "color", "dayValues", "disabled", "doneText", "firstDayOfWeek", "hourCycle", "hourValues", "locale", "max", "min", "minuteValues", "mode", "monthValues", "name", "presentation", "readonly", "showClearButton", "showDefaultButtons", "showDefaultTimeLabel", "showDefaultTitle", "size", "value", "yearValues"] })
 export class IonDatetime {
   ionCancel!: EventEmitter<CustomEvent>;
   ionChange!: EventEmitter<CustomEvent>;

core/api.txt

@@ -370,6 +370,7 @@ ion-content,part,scroll
 
 ion-datetime,shadow
 ion-datetime,prop,cancelText,string,'Cancel',false,false
+ion-datetime,prop,clearText,string,'Clear',false,false
 ion-datetime,prop,color,string | undefined,'primary',false,false
 ion-datetime,prop,dayValues,number | number[] | string | undefined,undefined,false,false
 ion-datetime,prop,disabled,boolean,false,false,false
@@ -386,6 +387,7 @@ ion-datetime,prop,monthValues,number | number[] | string | undefined,undefined,f
 ion-datetime,prop,name,string,this.inputId,false,false
 ion-datetime,prop,presentation,"date" | "date-time" | "month" | "month-year" | "time" | "time-date" | "year",'date-time',false,false
 ion-datetime,prop,readonly,boolean,false,false,false
+ion-datetime,prop,showClearButton,boolean,false,false,false
 ion-datetime,prop,showDefaultButtons,boolean,false,false,false
 ion-datetime,prop,showDefaultTimeLabel,boolean,true,false,false
 ion-datetime,prop,showDefaultTitle,boolean,false,false,false
@@ -394,7 +396,7 @@ ion-datetime,prop,value,null | string | undefined,undefined,false,false
 ion-datetime,prop,yearValues,number | number[] | string | undefined,undefined,false,false
 ion-datetime,method,cancel,cancel(closeOverlay?: boolean) => Promise<void>
 ion-datetime,method,confirm,confirm(closeOverlay?: boolean) => Promise<void>
-ion-datetime,method,reset,reset(value?: string | undefined) => Promise<void>
+ion-datetime,method,reset,reset(startDate?: string | undefined) => Promise<void>
 ion-datetime,event,ionBlur,void,true
 ion-datetime,event,ionCancel,void,true
 ion-datetime,event,ionChange,DatetimeChangeEventDetail,true

core/src/components.d.ts

@@ -708,6 +708,10 @@ export namespace Components {
           * The text to display on the picker's cancel button.
          */
         "cancelText": string;
+        /**
+          * The text to display on the picker's "Clear" button.
+         */
+        "clearText": string;
         /**
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
@@ -777,9 +781,13 @@ export namespace Components {
          */
         "readonly": boolean;
         /**
-          * Resets the internal state of the datetime but does not update the value. Passing a value ISO-8601 string will reset the state of te component to the provided date.
+          * Resets the internal state of the datetime but does not update the value. Passing a valid ISO-8601 string will reset the state of the component to the provided date. If no value is provided, the internal state will be reset to today.
          */
-        "reset": (value?: string | undefined) => Promise<void>;
+        "reset": (startDate?: string | undefined) => Promise<void>;
+        /**
+          * If `true`, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
+         */
+        "showClearButton": boolean;
         /**
           * If `true`, the default "Cancel" and "OK" buttons will be rendered at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
          */
@@ -4300,6 +4308,10 @@ declare namespace LocalJSX {
           * The text to display on the picker's cancel button.
          */
         "cancelText"?: string;
+        /**
+          * The text to display on the picker's "Clear" button.
+         */
+        "clearText"?: string;
         /**
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
@@ -4384,6 +4396,10 @@ declare namespace LocalJSX {
           * If `true`, the datetime appears normal but is not interactive.
          */
         "readonly"?: boolean;
+        /**
+          * If `true`, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
+         */
+        "showClearButton"?: boolean;
         /**
           * If `true`, the default "Cancel" and "OK" buttons will be rendered at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
          */

core/src/components/datetime/datetime.scss

@@ -112,6 +112,16 @@
 // Calendar / Header / Action Buttons
 // -----------------------------------
 
+:host .datetime-action-buttons.has-clear-button {
+  width: 100%;
+}
+
+:host .datetime-action-buttons ion-buttons {
+  display: flex;
+
+  justify-content: space-between;
+}
+
 /**
  * Date/Year button should be on
  * the opposite side of the component

core/src/components/datetime/datetime.tsx

@@ -199,6 +199,11 @@ export class Datetime implements ComponentInterface {
    */
   @Prop() doneText = 'Done';
 
+  /**
+   * The text to display on the picker's "Clear" button.
+   */
+  @Prop() clearText = 'Clear';
+
   /**
    * Values used to create the list of selectable years. By default
    * the year values range between the `min` and `max` datetime inputs. However, to
@@ -313,6 +318,16 @@ export class Datetime implements ComponentInterface {
    */
   @Prop() showDefaultButtons = false;
 
+  /**
+   * If `true`, a "Clear" button will be rendered alongside
+   * the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime`
+   * component. Developers can also use the `button` slot
+   * if they want to customize these buttons. If custom
+   * buttons are set in the `button` slot then the
+   * default buttons will not be rendered.
+   */
+  @Prop() showClearButton = false;
+
   /**
    * If `true`, the default "Time" label will be rendered
    * for the time selector of the `ion-datetime` component.
@@ -388,14 +403,13 @@ export class Datetime implements ComponentInterface {
   }
 
   /**
-   * Resets the internal state of the datetime
+   * Resets the internal state of the datetime but does not update the value.
-   * but does not update the value. Passing a value
+   * Passing a valid ISO-8601 string will reset the state of the component to the provided date.
-   * ISO-8601 string will reset the state of
+   * If no value is provided, the internal state will be reset to today.
-   * te component to the provided date.
    */
   @Method()
-  async reset(value?: string) {
+  async reset(startDate?: string) {
-    this.processValue(value);
+    this.processValue(startDate);
   }
 
   /**
@@ -1197,6 +1211,11 @@ export class Datetime implements ComponentInterface {
     const hasSlottedButtons = this.el.querySelector('[slot="buttons"]') !== null;
     if (!hasSlottedButtons && !this.showDefaultButtons) { return; }
 
+    const clearButtonClick = () => {
+      this.reset();
+      this.value = undefined;
+    }
+
     /**
      * By default we render two buttons:
      * Cancel - Dismisses the datetime and
@@ -1207,11 +1226,17 @@ export class Datetime implements ComponentInterface {
     return (
       <div class="datetime-footer">
         <div class="datetime-buttons">
-          <div class="datetime-action-buttons">
+          <div class={{
+            ['datetime-action-buttons']: true,
+            ['has-clear-button']: this.showClearButton
+          }}>
             <slot name="buttons">
               <ion-buttons>
                 <ion-button color={this.color} onClick={() => this.cancel(true)}>{this.cancelText}</ion-button>
+                <div>
+                  {this.showClearButton && <ion-button color={this.color} onClick={() => clearButtonClick()}>{this.clearText}</ion-button>}
                   <ion-button color={this.color} onClick={() => this.confirm(true)}>{this.doneText}</ion-button>
+                </div>
               </ion-buttons>
             </slot>
           </div>

core/src/components/datetime/readme.md

@@ -232,6 +232,9 @@ dates in JavaScript.
   <div slot="title">My Custom Title</div>
 </ion-datetime>
 
+<!-- Clear button -->
+<ion-datetime [showClearButton]="true"></ion-datetime>
+
 <!-- Datetime in overlay -->
 <ion-button id="open-modal">Open Datetime Modal</ion-button>
 <ion-modal trigger="open-modal">
@@ -320,6 +323,9 @@ export class MyComponent {
   <div slot="title">My Custom Title</div>
 </ion-datetime>
 
+<!-- Clear button -->
+<ion-datetime show-clear-button="true"></ion-datetime>
+
 <!-- Custom buttons -->
 <ion-datetime id="custom-datetime">
   <ion-buttons slot="buttons">
@@ -420,6 +426,9 @@ export const DateTimeExamples: React.FC = () => {
         <div slot="title">My Custom Title</div>
       </IonDatetime>
 
+      {/* Clear button */}
+      <IonDatetime showClearButton={true}></IonDatetime>
+      
       {/* Custom buttons */}
       <IonDatetime ref={customDatetime}>
         <IonButtons slot="buttons">
@@ -510,6 +519,9 @@ export class DatetimeExample {
         <div slot="title">My Custom Title</div>
       </ion-datetime>,
 
+      {/* Clear button */}
+      <ion-datetime showClearButton={true}></ion-datetime>  
+      
       {/* Custom buttons */}
       <ion-datetime ref={el => this.customDatetime = el}>
         <ion-buttons slot="buttons">
@@ -576,6 +588,9 @@ export class DatetimeExample {
     <div slot="title">My Custom Title</div>
   </ion-datetime>
 
+  <!-- Clear button -->
+  <ion-datetime :show-clear-button="true"></ion-datetime>
+  
   <!-- Custom buttons -->
   <ion-datetime ref="customDatetime">
     <ion-buttons slot="buttons">
@@ -640,6 +655,7 @@ export class DatetimeExample {
 | Property               | Attribute                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Type                                                                                  | Default        |
 | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- |
 | `cancelText`           | `cancel-text`             | The text to display on the picker's cancel button.                                                                                                                                                                                                                                                                                                                                                                                                                                                | `string`                                                                              | `'Cancel'`     |
+| `clearText`            | `clear-text`              | The text to display on the picker's "Clear" button.                                                                                                                                                                                                                                                                                                                                                                                                                                               | `string`                                                                              | `'Clear'`      |
 | `color`                | `color`                   | The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).                                                                                                                                                                                                                            | `string \| undefined`                                                                 | `'primary'`    |
 | `dayValues`            | `day-values`              | Values used to create the list of selectable days. By default every day is shown for the given month. However, to control exactly which days of the month to display, the `dayValues` input can take a number, an array of numbers, or a string of comma separated numbers. Note that even if the array days have an invalid number for the selected month, like `31` in February, it will correctly not show days which are not valid for the selected month.                                    | `number \| number[] \| string \| undefined`                                           | `undefined`    |
 | `disabled`             | `disabled`                | If `true`, the user cannot interact with the datetime.                                                                                                                                                                                                                                                                                                                                                                                                                                            | `boolean`                                                                             | `false`        |
@@ -656,6 +672,7 @@ export class DatetimeExample {
 | `name`                 | `name`                    | The name of the control, which is submitted with the form data.                                                                                                                                                                                                                                                                                                                                                                                                                                   | `string`                                                                              | `this.inputId` |
 | `presentation`         | `presentation`            | Which values you want to select. `'date'` will show a calendar picker to select the month, day, and year. `'time'` will show a time picker to select the hour, minute, and (optionally) AM/PM. `'date-time'` will show the date picker first and time picker second. `'time-date'` will show the time picker first and date picker second.                                                                                                                                                        | `"date" \| "date-time" \| "month" \| "month-year" \| "time" \| "time-date" \| "year"` | `'date-time'`  |
 | `readonly`             | `readonly`                | If `true`, the datetime appears normal but is not interactive.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                             | `false`        |
+| `showClearButton`      | `show-clear-button`       | If `true`, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.                                                                                                                                                                      | `boolean`                                                                             | `false`        |
 | `showDefaultButtons`   | `show-default-buttons`    | If `true`, the default "Cancel" and "OK" buttons will be rendered at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.                                                                                                                                                                                                 | `boolean`                                                                             | `false`        |
 | `showDefaultTimeLabel` | `show-default-time-label` | If `true`, the default "Time" label will be rendered for the time selector of the `ion-datetime` component. Developers can also use the `time-label` slot if they want to customize this label. If a custom label is set in the `time-label` slot then the default label will not be rendered.                                                                                                                                                                                                    | `boolean`                                                                             | `true`         |
 | `showDefaultTitle`     | `show-default-title`      | If `true`, a header will be shown above the calendar picker. On `ios` mode this will include the slotted title, and on `md` mode this will include the slotted title and the selected date.                                                                                                                                                                                                                                                                                                       | `boolean`                                                                             | `false`        |
@@ -701,12 +718,11 @@ Type: `Promise<void>`
 
 
 
-### `reset(value?: string | undefined) => Promise<void>`
+### `reset(startDate?: string | undefined) => Promise<void>`
 
-Resets the internal state of the datetime
+Resets the internal state of the datetime but does not update the value.
-but does not update the value. Passing a value
+Passing a valid ISO-8601 string will reset the state of the component to the provided date.
-ISO-8601 string will reset the state of
+If no value is provided, the internal state will be reset to today.
-te component to the provided date.
 
 #### Returns
 

core/src/components/datetime/test/basic/index.html

@@ -279,7 +279,7 @@
 
           <div class="grid-item">
             <h2>Inline - Custom</h2>
-            <ion-datetime show-default-buttons="true" color="danger" id="custom-datetime">
+            <ion-datetime show-default-buttons="true" color="danger" id="custom-datetime" show-clear-button="true">
               <span slot="title">Select Date</span>
             </ion-datetime>
           </div>

core/src/components/datetime/usage/angular.md

@@ -40,6 +40,9 @@
   <div slot="title">My Custom Title</div>
 </ion-datetime>
 
+<!-- Clear button -->
+<ion-datetime [showClearButton]="true"></ion-datetime>
+
 <!-- Datetime in overlay -->
 <ion-button id="open-modal">Open Datetime Modal</ion-button>
 <ion-modal trigger="open-modal">

core/src/components/datetime/usage/javascript.md

@@ -40,6 +40,9 @@
   <div slot="title">My Custom Title</div>
 </ion-datetime>
 
+<!-- Clear button -->
+<ion-datetime show-clear-button="true"></ion-datetime>
+
 <!-- Custom buttons -->
 <ion-datetime id="custom-datetime">
   <ion-buttons slot="buttons">

core/src/components/datetime/usage/react.md

@@ -67,6 +67,9 @@ export const DateTimeExamples: React.FC = () => {
         <div slot="title">My Custom Title</div>
       </IonDatetime>
 
+      {/* Clear button */}
+      <IonDatetime showClearButton={true}></IonDatetime>
+      
       {/* Custom buttons */}
       <IonDatetime ref={customDatetime}>
         <IonButtons slot="buttons">

core/src/components/datetime/usage/stencil.md

@@ -65,6 +65,9 @@ export class DatetimeExample {
         <div slot="title">My Custom Title</div>
       </ion-datetime>,
 
+      {/* Clear button */}
+      <ion-datetime showClearButton={true}></ion-datetime>  
+      
       {/* Custom buttons */}
       <ion-datetime ref={el => this.customDatetime = el}>
         <ion-buttons slot="buttons">

core/src/components/datetime/usage/vue.md

@@ -41,6 +41,9 @@
     <div slot="title">My Custom Title</div>
   </ion-datetime>
 
+  <!-- Clear button -->
+  <ion-datetime :show-clear-button="true"></ion-datetime>
+  
   <!-- Custom buttons -->
   <ion-datetime ref="customDatetime">
     <ion-buttons slot="buttons">

packages/vue/src/proxies.ts

@@ -275,6 +275,7 @@ export const IonDatetime = /*@__PURE__*/ defineContainer<JSX.IonDatetime>('ion-d
   'presentation',
   'cancelText',
   'doneText',
+  'clearText',
   'yearValues',
   'monthValues',
   'dayValues',
@@ -285,6 +286,7 @@ export const IonDatetime = /*@__PURE__*/ defineContainer<JSX.IonDatetime>('ion-d
   'value',
   'showDefaultTitle',
   'showDefaultButtons',
+  'showClearButton',
   'showDefaultTimeLabel',
   'hourCycle',
   'size',