feat(datepicker): allow for date range selection logic to be customized

As discussed, adds a provider that allows the consumer to customize how the range is changed after the user has selected a value. For now it only has one method (`selectionFinished`), but the interface should allow us to add more later on.

Author: crisbeto

src/material/datepicker/calendar-body.html

@@ -50,7 +50,7 @@
       [attr.aria-label]="item.ariaLabel"
       [attr.aria-disabled]="!item.enabled || null"
       [attr.aria-selected]="_isSelected(item)"
-      (click)="_cellClicked(item)"
+      (click)="_cellClicked(item, $event)"
       [style.width]="_cellWidth"
       [style.paddingTop]="_cellPadding"
       role="button"

src/material/datepicker/calendar-body.spec.ts

@@ -1,6 +1,6 @@
 import {async, ComponentFixture, TestBed} from '@angular/core/testing';
 import {Component} from '@angular/core';
-import {MatCalendarBody, MatCalendarCell} from './calendar-body';
+import {MatCalendarBody, MatCalendarCell, MatCalendarUserEvent} from './calendar-body';
 import {By} from '@angular/platform-browser';
 import {dispatchMouseEvent, dispatchFakeEvent} from '@angular/cdk/testing/private';
 
@@ -591,8 +591,8 @@ class StandardCalendarBody {
   labelMinRequiredCells = 3;
   numCols = 7;
 
-  onSelect(value: number) {
-    this.selectedValue = value;
+  onSelect(event: MatCalendarUserEvent<number>) {
+    this.selectedValue = event.value;
   }
 }
 
@@ -614,7 +614,8 @@ class RangeCalendarBody {
   comparisonStart: number | undefined;
   comparisonEnd: number | undefined;
 
-  onSelect(value: number) {
+  onSelect(event: MatCalendarUserEvent<number>) {
+    const value = event.value;
     if (!this.startValue) {
       this.startValue = value;
     } else if (!this.endValue) {

src/material/datepicker/calendar-body.ts

@@ -40,6 +40,11 @@ export class MatCalendarCell {
               public compareValue = value) {}
 }
 
+/** Event emitted when a date inside the calendar is triggered as a result of a user action. */
+export interface MatCalendarUserEvent<D> {
+  value: D;
+  event: Event;
+}
 
 /**
  * An internal component used to display calendar data in a table.
@@ -96,7 +101,8 @@ export class MatCalendarBody implements OnChanges, OnDestroy {
   @Input() comparisonEnd: number | null;
 
   /** Emits when a new value is selected. */
-  @Output() readonly selectedValueChange: EventEmitter<number> = new EventEmitter<number>();
+  @Output() readonly selectedValueChange: EventEmitter<MatCalendarUserEvent<number>> =
+      new EventEmitter<MatCalendarUserEvent<number>>();
 
   /** The number of blank cells to put at the beginning for the first row. */
   _firstRowOffset: number;
@@ -128,9 +134,9 @@ export class MatCalendarBody implements OnChanges, OnDestroy {
   }
 
   /** Called when a cell is clicked. */
-  _cellClicked(cell: MatCalendarCell): void {
+  _cellClicked(cell: MatCalendarCell, event: MouseEvent): void {
     if (cell.enabled) {
-      this.selectedValueChange.emit(cell.value);
+      this.selectedValueChange.emit({value: cell.value, event});
     }
   }
 

src/material/datepicker/calendar-range-selection-strategy.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Injectable, InjectionToken} from '@angular/core';
+import {DateAdapter} from '@angular/material/core';
+import {DateRange} from './date-selection-model';
+
+/** Injection token used to customize the date range selection behavior. */
+export const MAT_CALENDAR_RANGE_SELECTION_STRATEGY =
+    new InjectionToken<MatCalendarRangeSelectionStrategy<any>>(
+        'MAT_CALENDAR_RANGE_SELECTION_STRATEGY');
+
+/** Object that can be provided in order to customize the date range selection behavior. */
+export interface MatCalendarRangeSelectionStrategy<D> {
+  /** Called when the user has finished selecting a value. */
+  selectionFinished(date: D | null, currentRange: DateRange<D>, event: Event): DateRange<D>;
+}
+
+/** Provides the default date range selection behavior. */
+@Injectable()
+export class DefaultMatCalendarRangeStrategy<D> implements MatCalendarRangeSelectionStrategy<D> {
+  constructor(private _dateAdapter: DateAdapter<D>) {}
+
+  selectionFinished(date: D, currentRange: DateRange<D>) {
+    let {start, end} = currentRange;
+
+    if (start == null) {
+      start = date;
+    } else if (end == null && date && this._dateAdapter.compareDate(date, start) > 0) {
+      end = date;
+    } else {
+      start = date;
+      end = null;
+    }
+
+    return new DateRange<D>(start, end);
+  }
+}

src/material/datepicker/calendar.html

@@ -11,8 +11,7 @@
       [dateClass]="dateClass"
       [comparisonStart]="comparisonStart"
       [comparisonEnd]="comparisonEnd"
-      (selectedChange)="_dateSelected($event)"
-      (_userSelection)="_userSelected()">
+      (_userSelection)="_dateSelected($event)">
   </mat-month-view>
 
   <mat-year-view

src/material/datepicker/calendar.ts

@@ -31,7 +31,7 @@ import {
   MatDateFormats,
 } from '@angular/material/core';
 import {Subject, Subscription} from 'rxjs';
-import {MatCalendarCellCssClasses} from './calendar-body';
+import {MatCalendarCellCssClasses, MatCalendarUserEvent} from './calendar-body';
 import {createMissingDateImplError} from './datepicker-errors';
 import {MatDatepickerIntl} from './datepicker-intl';
 import {MatMonthView} from './month-view';
@@ -47,6 +47,10 @@ import {
   DateRange,
   MatDateSelectionModel,
 } from './date-selection-model';
+import {
+  MAT_CALENDAR_RANGE_SELECTION_STRATEGY,
+  MatCalendarRangeSelectionStrategy
+} from './calendar-range-selection-strategy';
 
 /**
  * Possible views for the calendar.
@@ -318,7 +322,9 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
               @Optional() private _dateAdapter: DateAdapter<D>,
               @Optional() @Inject(MAT_DATE_FORMATS) private _dateFormats: MatDateFormats,
               private _changeDetectorRef: ChangeDetectorRef,
-              private _model: MatDateSelectionModel<DateRange<D> | D | null>) {
+              private _model: MatDateSelectionModel<DateRange<D> | D | null>,
+              @Optional() @Inject(MAT_CALENDAR_RANGE_SELECTION_STRATEGY)
+                  private _rangeSelectionStrategy?: MatCalendarRangeSelectionStrategy<D>) {
 
     if (!this._dateAdapter) {
       throw createMissingDateImplError('DateAdapter');
@@ -403,8 +409,25 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
   }
 
   /** Handles date selection in the month view. */
-  _dateSelected(date: D | null): void {
-    this._model.add(date);
+  _dateSelected(event: MatCalendarUserEvent<D | null>): void {
+    const selection = this._model.selection;
+    const value = event.value;
+    const isRange = selection instanceof DateRange;
+
+    // If we're selecting a range and we have a selection strategy, always pass the value through
+    // there. Otherwise don't assign null values to the model, unless we're selecting a range.
+    // A null value when picking a range means that the user cancelled the selection (e.g. by
+    // pressing escape), whereas when selecting a single value it means that the value didn't
+    // change. This isn't very intuitive, but it's here for backwards-compatibility.
+    if (isRange && this._rangeSelectionStrategy) {
+      const newSelection = this._rangeSelectionStrategy.selectionFinished(value,
+          selection as DateRange<D>, event.event);
+      this._model.updateSelection(newSelection, this);
+    } else if (value || isRange) {
+      this._model.add(value);
+    }
+
+    this._userSelection.emit();
   }
 
   /** Handles year selection in the multiyear view. */
@@ -417,10 +440,6 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
     this.monthSelected.emit(normalizedMonth);
   }
 
-  _userSelected(): void {
-    this._userSelection.emit();
-  }
-
   /** Handles year/month selection in the multi-year/year views. */
   _goToDateInView(date: D, view: 'month' | 'year' | 'multi-year'): void {
     this.activeDate = date;

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

@@ -7,7 +7,6 @@
  */
 
 import {FactoryProvider, Injectable, Optional, SkipSelf, OnDestroy} from '@angular/core';
-import {DateAdapter} from '@angular/material/core';
 import {Observable, Subject} from 'rxjs';
 
 /** A class representing a range of dates. */
@@ -50,8 +49,6 @@ export abstract class MatDateSelectionModel<S, D = ExtractDateTypeFromSelection<
   selectionChanged: Observable<DateSelectionModelChange<S>> = this._selectionChanged.asObservable();
 
   protected constructor(
-    /** Date adapter used when interacting with dates in the model. */
-    protected readonly adapter: DateAdapter<D>,
     /** The current selection. */
     readonly selection: S) {
     this.selection = selection;
@@ -81,8 +78,8 @@ export abstract class MatDateSelectionModel<S, D = ExtractDateTypeFromSelection<
 /**  A selection model that contains a single date. */
 @Injectable()
 export class MatSingleDateSelectionModel<D> extends MatDateSelectionModel<D | null, D> {
-  constructor(adapter: DateAdapter<D>) {
-    super(adapter, null);
+  constructor() {
+    super(null);
   }
 
   /**
@@ -105,8 +102,8 @@ export class MatSingleDateSelectionModel<D> extends MatDateSelectionModel<D | nu
 /**  A selection model that contains a date range. */
 @Injectable()
 export class MatRangeDateSelectionModel<D> extends MatDateSelectionModel<DateRange<D>, D> {
-  constructor(adapter: DateAdapter<D>) {
-    super(adapter, new DateRange<D>(null, null));
+  constructor() {
+    super(new DateRange<D>(null, null));
   }
 
   /**
@@ -119,7 +116,7 @@ export class MatRangeDateSelectionModel<D> extends MatDateSelectionModel<DateRan
 
     if (start == null) {
       start = date;
-    } else if (end == null && date && this.adapter.compareDate(date, start) > 0) {
+    } else if (end == null) {
       end = date;
     } else {
       start = date;
@@ -140,27 +137,27 @@ export class MatRangeDateSelectionModel<D> extends MatDateSelectionModel<DateRan
 
 /** @docs-private */
 export function MAT_SINGLE_DATE_SELECTION_MODEL_FACTORY(
-    parent: MatSingleDateSelectionModel<unknown>, adapter: DateAdapter<unknown>) {
-  return parent || new MatSingleDateSelectionModel(adapter);
+    parent: MatSingleDateSelectionModel<unknown>) {
+  return parent || new MatSingleDateSelectionModel();
 }
 
 /** Used to provide a single selection model to a component. */
 export const MAT_SINGLE_DATE_SELECTION_MODEL_PROVIDER: FactoryProvider = {
   provide: MatDateSelectionModel,
-  deps: [[new Optional(), new SkipSelf(), MatDateSelectionModel], DateAdapter],
+  deps: [[new Optional(), new SkipSelf(), MatDateSelectionModel]],
   useFactory: MAT_SINGLE_DATE_SELECTION_MODEL_FACTORY,
 };
 
 
 /** @docs-private */
 export function MAT_RANGE_DATE_SELECTION_MODEL_FACTORY(
-    parent: MatSingleDateSelectionModel<unknown>, adapter: DateAdapter<unknown>) {
-  return parent || new MatRangeDateSelectionModel(adapter);
+    parent: MatSingleDateSelectionModel<unknown>) {
+  return parent || new MatRangeDateSelectionModel();
 }
 
 /** Used to provide a range selection model to a component. */
 export const MAT_RANGE_DATE_SELECTION_MODEL_PROVIDER: FactoryProvider = {
   provide: MatDateSelectionModel,
-  deps: [[new Optional(), new SkipSelf(), MatDateSelectionModel], DateAdapter],
+  deps: [[new Optional(), new SkipSelf(), MatDateSelectionModel]],
   useFactory: MAT_RANGE_DATE_SELECTION_MODEL_FACTORY,
 };

src/material/datepicker/datepicker-module.ts

@@ -29,6 +29,10 @@ import {MatYearView} from './year-view';
 import {MatDateRangeInput} from './date-range-input';
 import {MatStartDate, MatEndDate} from './date-range-input-parts';
 import {MatDateRangePicker} from './date-range-picker';
+import {
+  MAT_CALENDAR_RANGE_SELECTION_STRATEGY,
+  DefaultMatCalendarRangeStrategy
+} from './calendar-range-selection-strategy';
 
 
 @NgModule({
@@ -77,6 +81,10 @@ import {MatDateRangePicker} from './date-range-picker';
   providers: [
     MatDatepickerIntl,
     MAT_DATEPICKER_SCROLL_STRATEGY_FACTORY_PROVIDER,
+    {
+      provide: MAT_CALENDAR_RANGE_SELECTION_STRATEGY,
+      useClass: DefaultMatCalendarRangeStrategy
+    }
   ],
   entryComponents: [
     MatDatepickerContent,

src/material/datepicker/month-view.ts

@@ -35,7 +35,12 @@ import {
 } from '@angular/core';
 import {DateAdapter, MAT_DATE_FORMATS, MatDateFormats} from '@angular/material/core';
 import {Directionality} from '@angular/cdk/bidi';
-import {MatCalendarBody, MatCalendarCell, MatCalendarCellCssClasses} from './calendar-body';
+import {
+  MatCalendarBody,
+  MatCalendarCell,
+  MatCalendarCellCssClasses,
+  MatCalendarUserEvent,
+} from './calendar-body';
 import {createMissingDateImplError} from './datepicker-errors';
 import {Subscription} from 'rxjs';
 import {startWith} from 'rxjs/operators';
@@ -121,7 +126,8 @@ export class MatMonthView<D> implements AfterContentInit, OnDestroy {
   @Output() readonly selectedChange: EventEmitter<D | null> = new EventEmitter<D | null>();
 
   /** Emits when any date is selected. */
-  @Output() readonly _userSelection: EventEmitter<void> = new EventEmitter<void>();
+  @Output() readonly _userSelection: EventEmitter<MatCalendarUserEvent<D | null>> =
+      new EventEmitter<MatCalendarUserEvent<D | null>>();
 
   /** Emits when any date is activated. */
   @Output() readonly activeDateChange: EventEmitter<D> = new EventEmitter<D>();
@@ -181,7 +187,9 @@ export class MatMonthView<D> implements AfterContentInit, OnDestroy {
   }
 
   /** Handles when a new date is selected. */
-  _dateSelected(date: number) {
+  _dateSelected(event: MatCalendarUserEvent<number>) {
+    const date = event.value;
+    let selectedDate: D | null = null;
     let rangeStartDate: number | null;
     let rangeEndDate: number | null;
 
@@ -195,12 +203,11 @@ export class MatMonthView<D> implements AfterContentInit, OnDestroy {
     if (rangeStartDate !== date || rangeEndDate !== date) {
       const selectedYear = this._dateAdapter.getYear(this.activeDate);
       const selectedMonth = this._dateAdapter.getMonth(this.activeDate);
-      const selectedDate = this._dateAdapter.createDate(selectedYear, selectedMonth, date);
-
+      selectedDate = this._dateAdapter.createDate(selectedYear, selectedMonth, date);
       this.selectedChange.emit(selectedDate);
     }
 
-    this._userSelection.emit();
+    this._userSelection.emit({value: selectedDate, event: event.event});
   }
 
   /** Handles keydown events on the calendar body when calendar is in month view. */
@@ -247,8 +254,7 @@ export class MatMonthView<D> implements AfterContentInit, OnDestroy {
       case ENTER:
       case SPACE:
         if (!this.dateFilter || this.dateFilter(this._activeDate)) {
-          this._dateSelected(this._dateAdapter.getDate(this._activeDate));
-          this._userSelection.emit();
+          this._dateSelected({value: this._dateAdapter.getDate(this._activeDate), event});
           // Prevent unexpected default actions such as form submission.
           event.preventDefault();
         }
@@ -259,7 +265,7 @@ export class MatMonthView<D> implements AfterContentInit, OnDestroy {
         // rest of the range logic, because focus may have moved outside the calendar body.
         if (this._matCalendarBody._previewEnd > -1) {
           this.selectedChange.emit(null);
-          this._userSelection.emit();
+          this._userSelection.emit({value: null, event});
           event.preventDefault();
           event.stopPropagation(); // Prevents the overlay from closing.
         }

src/material/datepicker/multi-year-view.ts

@@ -33,7 +33,7 @@ import {
 } from '@angular/core';
 import {DateAdapter} from '@angular/material/core';
 import {Directionality} from '@angular/cdk/bidi';
-import {MatCalendarBody, MatCalendarCell} from './calendar-body';
+import {MatCalendarBody, MatCalendarCell, MatCalendarUserEvent} from './calendar-body';
 import {createMissingDateImplError} from './datepicker-errors';
 import {Subscription} from 'rxjs';
 import {startWith} from 'rxjs/operators';
@@ -174,7 +174,8 @@ export class MatMultiYearView<D> implements AfterContentInit, OnDestroy {
   }
 
   /** Handles when a new year is selected. */
-  _yearSelected(year: number) {
+  _yearSelected(event: MatCalendarUserEvent<number>) {
+    const year = event.value;
     this.yearSelected.emit(this._dateAdapter.createDate(year, 0, 1));
     let month = this._dateAdapter.getMonth(this.activeDate);
     let daysInMonth =
@@ -222,7 +223,7 @@ export class MatMultiYearView<D> implements AfterContentInit, OnDestroy {
         break;
       case ENTER:
       case SPACE:
-        this._yearSelected(this._dateAdapter.getYear(this._activeDate));
+        this._yearSelected({value: this._dateAdapter.getYear(this._activeDate), event});
         break;
       default:
         // Don't prevent default or focus active cell on keys that we don't explicitly handle.