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

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/dev-app/datepicker/datepicker-demo-module.ts

@@ -18,7 +18,12 @@ import {MatIconModule} from '@angular/material/icon';
 import {MatInputModule} from '@angular/material/input';
 import {MatSelectModule} from '@angular/material/select';
 import {RouterModule} from '@angular/router';
-import {CustomHeader, CustomHeaderNgContent, DatepickerDemo} from './datepicker-demo';
+import {
+  CustomHeader,
+  CustomHeaderNgContent,
+  DatepickerDemo,
+  CustomRangeStrategy,
+} from './datepicker-demo';
 
 @NgModule({
   imports: [
@@ -35,7 +40,7 @@ import {CustomHeader, CustomHeaderNgContent, DatepickerDemo} from './datepicker-
     ReactiveFormsModule,
     RouterModule.forChild([{path: '', component: DatepickerDemo}]),
   ],
-  declarations: [CustomHeader, CustomHeaderNgContent, DatepickerDemo],
+  declarations: [CustomHeader, CustomHeaderNgContent, DatepickerDemo, CustomRangeStrategy],
 })
 export class DatepickerDemoModule {
 }

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

@@ -244,3 +244,17 @@ <h2>Range picker</h2>
   </mat-form-field>
   <div>{{range3.value | json}}</div>
 </div>
+
+
+<h2>Range picker with custom selection strategy</h2>
+<div class="demo-range-group">
+  <mat-form-field>
+    <mat-label>Enter a date range</mat-label>
+    <mat-date-range-input [rangePicker]="range4Picker">
+      <input matStartDate placeholder="Start date"/>
+      <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-form-field>
+</div>

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

@@ -14,14 +14,19 @@ import {
   OnDestroy,
   Optional,
   ViewChild,
-  ViewEncapsulation
+  ViewEncapsulation,
+  Directive,
+  Injectable
 } from '@angular/core';
 import {FormControl, FormGroup} from '@angular/forms';
 import {DateAdapter, MAT_DATE_FORMATS, MatDateFormats, ThemePalette} from '@angular/material/core';
 import {
   MatCalendar,
   MatCalendarHeader,
-  MatDatepickerInputEvent
+  MatDatepickerInputEvent,
+  MAT_CALENDAR_RANGE_SELECTION_STRATEGY,
+  MatCalendarRangeSelectionStrategy,
+  DateRange
 } from '@angular/material/datepicker';
 import {Subject} from 'rxjs';
 import {takeUntil} from 'rxjs/operators';
@@ -79,6 +84,37 @@ export class DatepickerDemo {
   customHeaderNgContent = CustomHeaderNgContent;
 }
 
+/** Range selection strategy that preserves the current range. */
+@Injectable()
+export class PreserveRangeStrategy<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) {
+      end = date;
+    } else if (this._dateAdapter.compareDate(start, date) > 0) {
+      start = date;
+    } else {
+      end = date;
+    }
+
+    return new DateRange<D>(start, end);
+  }
+}
+
+@Directive({
+  selector: '[customRangeStrategy]',
+  providers: [{
+    provide: MAT_CALENDAR_RANGE_SELECTION_STRATEGY,
+    useClass: PreserveRangeStrategy
+  }]
+})
+export class CustomRangeStrategy {}
+
 // Custom header component for datepicker
 @Component({
   selector: 'custom-header',

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,45 @@
+/**
+ * @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';
+
+// TODO(crisbeto): this needs to be expanded to allow for the preview range to be customized.
+
+/** 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,
 };