feat(material/datepicker): add support for cancel/apply buttons (#21487)

Adds support for projecting in "Cancel" and "Apply" buttons in `mat-datepicker` and
`mat-date-range-picker`. Doing so will change the behavior of the datepicker so that the user
has to explicitly accept a value after they've clicked on it. The consumption is as follows:

```
<mat-datepicker>
  <mat-datepicker-actions>
    <button mat-button matDatepickerCancel>Cancel</button>
    <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
  </mat-datepicker-actions>
</mat-datepicker>
```

Author: crisbeto

src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.css

@@ -0,0 +1,3 @@
+.example-form-field {
+  margin-right: 20px;
+}

src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html

@@ -0,0 +1,30 @@
+<mat-form-field appearance="fill" class="example-form-field">
+  <mat-label>Choose a date</mat-label>
+  <input matInput [matDatepicker]="datepicker">
+  <mat-datepicker-toggle matSuffix [for]="datepicker"></mat-datepicker-toggle>
+<!-- #docregion datepicker-actions -->
+  <mat-datepicker #datepicker>
+    <mat-datepicker-actions>
+      <button mat-button matDatepickerCancel>Cancel</button>
+      <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+    </mat-datepicker-actions>
+  </mat-datepicker>
+<!-- #enddocregion datepicker-actions -->
+</mat-form-field>
+
+<mat-form-field appearance="fill" class="example-form-field">
+  <mat-label>Enter a date range</mat-label>
+  <mat-date-range-input [rangePicker]="rangePicker">
+    <input matStartDate placeholder="Start date">
+    <input matEndDate placeholder="End date">
+  </mat-date-range-input>
+  <mat-datepicker-toggle matSuffix [for]="rangePicker"></mat-datepicker-toggle>
+<!-- #docregion date-range-picker-actions -->
+  <mat-date-range-picker #rangePicker>
+    <mat-date-range-picker-actions>
+      <button mat-button matDateRangePickerCancel>Cancel</button>
+      <button mat-raised-button color="primary" matDateRangePickerApply>Apply</button>
+    </mat-date-range-picker-actions>
+  </mat-date-range-picker>
+<!-- #enddocregion date-range-picker-actions -->
+</mat-form-field>

src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.ts

@@ -0,0 +1,9 @@
+import {Component} from '@angular/core';
+
+/** @title Datepicker action buttons */
+@Component({
+  selector: 'datepicker-actions-example',
+  templateUrl: 'datepicker-actions-example.html',
+  styleUrls: ['datepicker-actions-example.css']
+})
+export class DatepickerActionsExample {}

src/components-examples/material/datepicker/index.ts

@@ -42,6 +42,7 @@ import {
   DateRangePickerSelectionStrategyExample
 } from './date-range-picker-selection-strategy/date-range-picker-selection-strategy-example';
 import {DatepickerHarnessExample} from './datepicker-harness/datepicker-harness-example';
+import {DatepickerActionsExample} from './datepicker-actions/datepicker-actions-example';
 
 export {
   DatepickerApiExample,
@@ -66,6 +67,7 @@ export {
   DateRangePickerFormsExample,
   DateRangePickerComparisonExample,
   DateRangePickerSelectionStrategyExample,
+  DatepickerActionsExample,
   ExampleHeader,
 };
 
@@ -92,6 +94,7 @@ const EXAMPLES = [
   DateRangePickerFormsExample,
   DateRangePickerComparisonExample,
   DateRangePickerSelectionStrategyExample,
+  DatepickerActionsExample,
   ExampleHeader,
 ];
 

src/dev-app/datepicker/datepicker-demo.html

@@ -5,6 +5,7 @@ <h2>Options</h2>
   <mat-checkbox [(ngModel)]="yearView">Start in year view</mat-checkbox>
   <mat-checkbox [(ngModel)]="datepickerDisabled">Disable datepicker</mat-checkbox>
   <mat-checkbox [(ngModel)]="inputDisabled">Disable input</mat-checkbox>
+  <mat-checkbox [(ngModel)]="showActions">Show action buttons</mat-checkbox>
   <mat-form-field>
     <mat-select [(ngModel)]="color" placeholder="Color">
       <mat-option value="primary">Primary</mat-option>
@@ -19,14 +20,24 @@ <h2>Options</h2>
     <input matInput [matDatepicker]="minDatePicker" [(ngModel)]="minDate"
         [disabled]="inputDisabled" [max]="maxDate">
     <mat-datepicker-toggle matSuffix [for]="minDatePicker"></mat-datepicker-toggle>
-    <mat-datepicker #minDatePicker [touchUi]="touch" [disabled]="datepickerDisabled"></mat-datepicker>
+    <mat-datepicker #minDatePicker [touchUi]="touch" [disabled]="datepickerDisabled">
+      <mat-datepicker-actions *ngIf="showActions">
+        <button mat-button matDatepickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+      </mat-datepicker-actions>
+    </mat-datepicker>
   </mat-form-field>
   <mat-form-field color="accent">
     <mat-label>Max date</mat-label>
     <input matInput [matDatepicker]="maxDatePicker" [(ngModel)]="maxDate"
         [disabled]="inputDisabled" [min]="minDate">
     <mat-datepicker-toggle matSuffix [for]="maxDatePicker"></mat-datepicker-toggle>
-    <mat-datepicker #maxDatePicker [touchUi]="touch" [disabled]="datepickerDisabled"></mat-datepicker>
+    <mat-datepicker #maxDatePicker [touchUi]="touch" [disabled]="datepickerDisabled">
+      <mat-datepicker-actions *ngIf="showActions">
+        <button mat-button matDatepickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+      </mat-datepicker-actions>
+    </mat-datepicker>
   </mat-form-field>
 </p>
 <p>
@@ -35,7 +46,12 @@ <h2>Options</h2>
     <input matInput [matDatepicker]="startAtPicker" [(ngModel)]="startAt"
         [disabled]="inputDisabled">
     <mat-datepicker-toggle matSuffix [for]="startAtPicker"></mat-datepicker-toggle>
-    <mat-datepicker #startAtPicker [touchUi]="touch" [disabled]="datepickerDisabled"></mat-datepicker>
+    <mat-datepicker #startAtPicker [touchUi]="touch" [disabled]="datepickerDisabled">
+      <mat-datepicker-actions *ngIf="showActions">
+        <button mat-button matDatepickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+      </mat-datepicker-actions>
+    </mat-datepicker>
   </mat-form-field>
 </p>
 
@@ -62,6 +78,10 @@ <h2>Result</h2>
         [startAt]="startAt"
         [startView]="yearView ? 'year' : 'month'"
         [color]="color">
+      <mat-datepicker-actions *ngIf="showActions">
+        <button mat-button matDatepickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+      </mat-datepicker-actions>
     </mat-datepicker>
     <mat-error *ngIf="resultPickerModel.hasError('matDatepickerParse')">
       "{{resultPickerModel.getError('matDatepickerParse').text}}" is not a valid date!
@@ -90,6 +110,10 @@ <h2>Result</h2>
       [disabled]="datepickerDisabled"
       [startAt]="startAt"
       [startView]="yearView ? 'year' : 'month'">
+    <mat-datepicker-actions *ngIf="showActions">
+      <button mat-button matDatepickerCancel>Cancel</button>
+      <button mat-raised-button color="primary" matDatepickerApply>Apply</button>
+    </mat-datepicker-actions>
   </mat-datepicker>
 </p>
 
@@ -191,7 +215,12 @@ <h2>Range picker</h2>
     <mat-date-range-picker
       [touchUi]="touch"
       [disabled]="datepickerDisabled"
-      #range1Picker></mat-date-range-picker>
+      #range1Picker>
+      <mat-date-range-picker-actions *ngIf="showActions">
+        <button mat-button matDateRangePickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDateRangePickerApply>Apply</button>
+      </mat-date-range-picker-actions>
+    </mat-date-range-picker>
   </mat-form-field>
   <div>{{range1.value | json}}</div>
 </div>
@@ -216,7 +245,12 @@ <h2>Range picker</h2>
       [touchUi]="touch"
       [disabled]="datepickerDisabled"
       panelClass="demo-custom-range"
-      #range2Picker></mat-date-range-picker>
+      #range2Picker>
+      <mat-date-range-picker-actions *ngIf="showActions">
+        <button mat-button matDateRangePickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDateRangePickerApply>Apply</button>
+      </mat-date-range-picker-actions>
+    </mat-date-range-picker>
   </mat-form-field>
   <div>{{range2.value | json}}</div>
 </div>
@@ -240,7 +274,12 @@ <h2>Range picker</h2>
     <mat-date-range-picker
       [touchUi]="touch"
       [disabled]="datepickerDisabled"
-      #range3Picker></mat-date-range-picker>
+      #range3Picker>
+      <mat-date-range-picker-actions *ngIf="showActions">
+        <button mat-button matDateRangePickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDateRangePickerApply>Apply</button>
+      </mat-date-range-picker-actions>
+    </mat-date-range-picker>
   </mat-form-field>
   <div>{{range3.value | json}}</div>
 </div>
@@ -255,6 +294,11 @@ <h2>Range picker with custom selection strategy</h2>
       <input matEndDate placeholder="End date"/>
     </mat-date-range-input>
     <mat-datepicker-toggle [for]="range4Picker" matSuffix></mat-datepicker-toggle>
-    <mat-date-range-picker customRangeStrategy #range4Picker></mat-date-range-picker>
+    <mat-date-range-picker customRangeStrategy #range4Picker>
+      <mat-date-range-picker-actions *ngIf="showActions">
+        <button mat-button matDateRangePickerCancel>Cancel</button>
+        <button mat-raised-button color="primary" matDateRangePickerApply>Apply</button>
+      </mat-date-range-picker-actions>
+    </mat-date-range-picker>
   </mat-form-field>
 </div>

src/dev-app/datepicker/datepicker-demo.ts

@@ -52,6 +52,7 @@ export class DatepickerDemo {
   lastDateInput: Date | null;
   lastDateChange: Date | null;
   color: ThemePalette;
+  showActions = false;
 
   dateCtrl = new FormControl();
   range1 = new FormGroup({start: new FormControl(), end: new FormControl()});

src/material/datepicker/BUILD.bazel

@@ -18,6 +18,7 @@ ng_module(
     ),
     assets = [
         ":datepicker-content.css",
+        ":datepicker-actions.css",
         ":datepicker-toggle.css",
         ":date-range-input.css",
         ":calendar-body.css",
@@ -79,6 +80,11 @@ sass_binary(
     deps = ["//src/material/core:core_scss_lib"],
 )
 
+sass_binary(
+    name = "datepicker_actions_scss",
+    src = "datepicker-actions.scss",
+)
+
 ng_test_library(
     name = "unit_test_sources",
     srcs = glob(
@@ -98,6 +104,7 @@ ng_test_library(
         "//src/material/form-field",
         "//src/material/input",
         "//src/material/testing",
+        "@npm//@angular/common",
         "@npm//@angular/forms",
         "@npm//@angular/platform-browser",
         "@npm//@angular/platform-browser-dynamic",

src/material/datepicker/date-range-picker.ts

@@ -33,6 +33,7 @@ export interface MatDateRangePickerInput<D> extends MatDatepickerControl<D> {
   providers: [
     MAT_RANGE_DATE_SELECTION_MODEL_PROVIDER,
     MAT_CALENDAR_RANGE_STRATEGY_PROVIDER,
+    {provide: MatDatepickerBase, useExisting: MatDateRangePicker},
   ]
 })
 export class MatDateRangePicker<D> extends MatDatepickerBase<MatDateRangePickerInput<D>,

src/material/datepicker/date-selection-model.ts

@@ -83,6 +83,19 @@ export abstract class MatDateSelectionModel<S, D = ExtractDateTypeFromSelection<
 
   /** Checks whether the current selection is complete. */
   abstract isComplete(): boolean;
+
+  /**
+   * Clones the selection model.
+   * @deprecated To be turned into an abstract method.
+   * @breaking-change 12.0.0
+   */
+  clone(): MatDateSelectionModel<S, D> {
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      throw Error('Not implemented');
+    }
+
+    return null!;
+  }
 }
 
 /**  A selection model that contains a single date. */
@@ -112,6 +125,13 @@ export class MatSingleDateSelectionModel<D> extends MatDateSelectionModel<D | nu
   isComplete() {
     return this.selection != null;
   }
+
+  /** Clones the selection model. */
+  clone() {
+    const clone = new MatSingleDateSelectionModel<D>(this._adapter);
+    clone.updateSelection(this.selection, this);
+    return clone;
+  }
 }
 
 /**  A selection model that contains a date range. */
@@ -168,6 +188,13 @@ export class MatRangeDateSelectionModel<D> extends MatDateSelectionModel<DateRan
   isComplete(): boolean {
     return this.selection.start != null && this.selection.end != null;
   }
+
+  /** Clones the selection model. */
+  clone() {
+    const clone = new MatRangeDateSelectionModel<D>(this._adapter);
+    clone.updateSelection(this.selection, this);
+    return clone;
+  }
 }
 
 /** @docs-private */

src/material/datepicker/datepicker-actions.scss

@@ -0,0 +1,16 @@
+.mat-datepicker-actions {
+  $spacing: 8px;
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  padding: 0 $spacing $spacing $spacing;
+
+  .mat-button-base + .mat-button-base {
+    margin-left: $spacing;
+
+    [dir='rtl'] & {
+      margin-left: 0;
+      margin-right: $spacing;
+    }
+  }
+}