feat(datepicker): @output for year and month selected in multiyear/year (#9678)

* feat(datepicker): @output of year and month selected in multiyear/year
views

* address @mmalerba's comments

* address comments

* add types to some outputs

* fix wrong parameter type

* restore accidentally removed object

* example and docs text

* change emitted values to objects instead of just numbers

* change datepicker.md and switch back tslint configs

* fix nit

* Remove changes in demo app

Author: julianobrasil

package-lock.json

@@ -93,7 +93,7 @@ <h2>Input disabled datepicker</h2>
     <input matInput [matDatepicker]="datePicker1" [(ngModel)]="date" [min]="minDate" [max]="maxDate"
            [matDatepickerFilter]="filterOdd ? dateFilter : null" disabled>
     <mat-datepicker #datePicker1 [touchUi]="touch" [startAt]="startAt"
-                   [startView]="yearView ? 'year' : 'month'"></mat-datepicker>
+                    [startView]="yearView ? 'year' : 'month'"></mat-datepicker>
   </mat-form-field>
 </p>
 
@@ -121,7 +121,7 @@ <h2>Input disabled, datepicker popup enabled</h2>
     <input matInput disabled [matDatepicker]="datePicker3" [(ngModel)]="date" [min]="minDate"
            [max]="maxDate" [matDatepickerFilter]="filterOdd ? dateFilter : null">
     <mat-datepicker #datePicker3 [touchUi]="touch" [disabled]="false" [startAt]="startAt"
-                   [startView]="yearView ? 'year' : 'month'"></mat-datepicker>
+                    [startView]="yearView ? 'year' : 'month'"></mat-datepicker>
   </mat-form-field>
 </p>
 

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

@@ -1,3 +1,4 @@
 mat-calendar {
   width: 300px;
 }
+

src/demo-app/datepicker/datepicker-demo.scss

@@ -8,8 +8,7 @@
 
 import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {FormControl} from '@angular/forms';
-import {MatDatepickerInputEvent} from '@angular/material/datepicker';
-
+import {MatDatepickerInputEvent} from '@angular/material';
 
 @Component({
   moduleId: module.id,
@@ -31,11 +30,11 @@ export class DatepickerDemo {
   lastDateInput: Date | null;
   lastDateChange: Date | null;
 
+  dateCtrl = new FormControl();
+
   dateFilter =
       (date: Date) => !(date.getFullYear() % 2) && (date.getMonth() % 2) && !(date.getDate() % 2)
 
   onDateInput = (e: MatDatepickerInputEvent<Date>) => this.lastDateInput = e.value;
   onDateChange = (e: MatDatepickerInputEvent<Date>) => this.lastDateChange = e.value;
-
-  dateCtrl = new FormControl();
 }

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

@@ -31,7 +31,7 @@ import {AccessibilityDemoModule} from './a11y/a11y-module';
   ],
   entryComponents: [
     EntryApp,
-  ],
+  ]
 })
 export class DemoAppModule {
   constructor(private _appRef: ApplicationRef) { }

src/demo-app/demo-app-module.ts

@@ -36,6 +36,7 @@
       [activeDate]="_activeDate"
       [selected]="selected"
       [dateFilter]="_dateFilterForViews"
+      (monthSelected)="_monthSelectedInYearView($event)"
       (selectedChange)="_goToDateInView($event, 'month')">
   </mat-year-view>
 
@@ -44,6 +45,7 @@
       [activeDate]="_activeDate"
       [selected]="selected"
       [dateFilter]="_dateFilterForViews"
+      (yearSelected)="_yearSelectedInMultiYearView($event)"
       (selectedChange)="_goToDateInView($event, 'year')">
   </mat-multi-year-view>
 </div>

src/lib/datepicker/calendar.html

@@ -196,6 +196,40 @@ describe('MatCalendar', () => {
       expect(testComponent.selected).toEqual(new Date(2017, JAN, 31));
     });
 
+    it('should emit the selected month on cell clicked in year view', () => {
+      periodButton.click();
+      fixture.detectChanges();
+
+      expect(calendarInstance._currentView).toBe('multi-year');
+      expect(calendarInstance._activeDate).toEqual(new Date(2017, JAN, 31));
+
+      (calendarElement.querySelector('.mat-calendar-body-active') as HTMLElement).click();
+
+      fixture.detectChanges();
+
+      expect(calendarInstance._currentView).toBe('year');
+
+      (calendarElement.querySelector('.mat-calendar-body-active') as HTMLElement).click();
+
+      const normalizedMonth: Date = fixture.componentInstance.selectedMonth;
+      expect(normalizedMonth.getMonth()).toEqual(0);
+    });
+
+    it('should emit the selected year on cell clicked in multiyear view', () => {
+      periodButton.click();
+      fixture.detectChanges();
+
+      expect(calendarInstance._currentView).toBe('multi-year');
+      expect(calendarInstance._activeDate).toEqual(new Date(2017, JAN, 31));
+
+      (calendarElement.querySelector('.mat-calendar-body-active') as HTMLElement).click();
+
+      fixture.detectChanges();
+
+      const normalizedYear: Date = fixture.componentInstance.selectedYear;
+      expect(normalizedYear.getFullYear()).toEqual(2017);
+    });
+
     it('should re-render when the i18n labels have changed',
       inject([MatDatepickerIntl], (intl: MatDatepickerIntl) => {
         const button = fixture.debugElement.nativeElement
@@ -916,10 +950,18 @@ describe('MatCalendar', () => {
 
 
 @Component({
-  template: `<mat-calendar [startAt]="startDate" [(selected)]="selected"></mat-calendar>`
+  template: `
+    <mat-calendar
+        [startAt]="startDate"
+        [(selected)]="selected"
+        (yearSelected)="selectedYear=$event"
+        (monthSelected)="selectedMonth=$event">
+    </mat-calendar>`
 })
 class StandardCalendar {
   selected: Date;
+  selectedYear: Date;
+  selectedMonth: Date;
   startDate = new Date(2017, JAN, 31);
 }
 

src/lib/datepicker/calendar.spec.ts

@@ -107,6 +107,18 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
   /** Emits when the currently selected date changes. */
   @Output() readonly selectedChange: EventEmitter<D> = new EventEmitter<D>();
 
+  /**
+   * Emits the year chosen in multiyear view.
+   * This doesn't imply a change on the selected date.
+   */
+  @Output() readonly yearSelected: EventEmitter<D> = new EventEmitter<D>();
+
+  /**
+   * Emits the month chosen in year view.
+   * This doesn't imply a change on the selected date.
+   */
+  @Output() readonly monthSelected: EventEmitter<D> = new EventEmitter<D>();
+
   /** Emits when any date is selected. */
   @Output() readonly _userSelection: EventEmitter<void> = new EventEmitter<void>();
 
@@ -228,6 +240,16 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
     }
   }
 
+  /** Handles year selection in the multiyear view. */
+  _yearSelectedInMultiYearView(normalizedYear: D) {
+    this.yearSelected.emit(normalizedYear);
+  }
+
+  /** Handles month selection in the year view. */
+  _monthSelectedInYearView(normalizedMonth: D) {
+    this.monthSelected.emit(normalizedMonth);
+  }
+
   _userSelected(): void {
     this._userSelection.emit();
   }

src/lib/datepicker/calendar.ts

@@ -8,5 +8,7 @@
     [dateFilter]="datepicker._dateFilter"
     [selected]="datepicker._selected"
     (selectedChange)="datepicker._select($event)"
+    (yearSelected)="datepicker._selectYear($event)"
+    (monthSelected)="datepicker._selectMonth($event)"
     (_userSelection)="datepicker.close()">
 </mat-calendar>

src/lib/datepicker/datepicker-content.html

@@ -51,6 +51,31 @@ year containing the `startAt` date.
 
 <!-- example(datepicker-start-view) -->
 
+#### Watching the views for changes on selected years and months
+
+When a year or a month is selected in `multi-year` and `year` views respecively, the `yearSelected`
+and `monthSelected` outputs emit a normalized date representing the chosen year or month. By
+"normalized" we mean that the dates representing a year will have their month set to January and
+their day set to the 1st. Dates representing months will have their day set to the 1st of the
+month. For example, if `<mat-datepicker>` is configured to work with javascript native Date
+objects, the `yearSelected` will emit `new Date(2017, 0, 1)` if the user selects 2017 in
+`multi-year` view. Similarly, `monthSelected` will emit `new Date(2017, 1, 0)` if the user
+selects **February** in `year` view and the current date value of the connected `<input>` was
+something like `new Date(2017, MM, dd)` (the month and day are irrelevant in this case).
+
+Notice that the emitted value does not affect the current value in the connected `<input>`, which
+is only bound to the selection made in the `month` view. So if the end user closes the calendar 
+after choosing a year in `multi-view` mode (by pressing the `ESC` key, for example), the selected
+year, emitted by `yearSelected` output, will not cause any change in the value of the date in the
+associated `<input>`.
+
+The following example uses `yearSelected` and `monthSelected` outputs to emulate a month and year
+picker (if you're not familiar with the usage of `MomentDateAdapter` and `MAT_DATE_FORMATS`
+you can [read more about them](#choosing-a-date-implementation-and-date-format-settings) below in
+this document to fully understand the example).
+
+<!-- example(datepicker-views-selection) -->
+
 ### Setting the selected date
 
 The type of values that the datepicker expects depends on the type of `DateAdapter` provided in your