fix(datepicker): allow DateAdapter authors to have more control over what can/can't be coerced to a date

BREAKING CHANGES:
- `fromIso8601` method on `DateAdapter` removed in favor of `coerceToDate`

Author: mmalerba

src/lib/core/datetime/date-adapter.ts

@@ -170,13 +170,6 @@ export abstract class DateAdapter<D> {
    */
   abstract toIso8601(date: D): string;
 
-  /**
-   * Creates a date from an RFC 3339 compatible string (https://tools.ietf.org/html/rfc3339).
-   * @param iso8601String The ISO date string to create a date from
-   * @returns The date created from the ISO date string.
-   */
-  abstract fromIso8601(iso8601String: string): D | null;
-
   /**
    * Checks whether the given object is considered a date instance by this DateAdapter.
    * @param obj The object to check
@@ -191,6 +184,23 @@ export abstract class DateAdapter<D> {
    */
   abstract isValid(date: D): boolean;
 
+  /**
+   * Attempts to coerce a value to a valid date object. This is different from parsing in that it
+   * should only coerce non-ambiguous, locale-independent values (e.g. a ISO 8601 string).
+   * The default implementation does not allow any coercion, it simply checks that the given value
+   * is already a valid date object or null.
+   * @param value The value to be coerced to a date object.
+   * @returns The coerced date object, either a valid date, null if the value can be coerced to a
+   *     null date (e.g. the empty string).
+   * @throws If the given value cannot be coerced to a valid date or null.
+   */
+  coerceToDate(value: any): D | null {
+    if (value == null || this.isDateInstance(value) && this.isValid(value)) {
+      return value;
+    }
+    throw Error(`Could not coerce "${value}" to a valid date object.`);
+  }
+
   /**
    * Sets the locale used for all dates.
    * @param locale The new locale.

src/lib/core/datetime/native-date-adapter.spec.ts

@@ -6,6 +6,7 @@ import {DateAdapter, MAT_DATE_LOCALE, NativeDateAdapter, NativeDateModule} from
 
 const SUPPORTS_INTL = typeof Intl != 'undefined';
 
+
 describe('NativeDateAdapter', () => {
   const platform = new Platform();
   let adapter: NativeDateAdapter;
@@ -333,14 +334,18 @@ describe('NativeDateAdapter', () => {
   });
 
   it('should create dates from valid ISO strings', () => {
-    expect(adapter.fromIso8601('1985-04-12T23:20:50.52Z')).not.toBeNull();
-    expect(adapter.fromIso8601('1996-12-19T16:39:57-08:00')).not.toBeNull();
-    expect(adapter.fromIso8601('1937-01-01T12:00:27.87+00:20')).not.toBeNull();
-    expect(adapter.fromIso8601('2017-01-01')).not.toBeNull();
-    expect(adapter.fromIso8601('2017-01-01T00:00:00')).not.toBeNull();
-    expect(adapter.fromIso8601('1990-13-31T23:59:00Z')).toBeNull();
-    expect(adapter.fromIso8601('1/1/2017')).toBeNull();
-    expect(adapter.fromIso8601('2017-01-01T')).toBeNull();
+    expect(adapter.coerceToDate('1985-04-12T23:20:50.52Z')).not.toBeNull();
+    expect(adapter.coerceToDate('1996-12-19T16:39:57-08:00')).not.toBeNull();
+    expect(adapter.coerceToDate('1937-01-01T12:00:27.87+00:20')).not.toBeNull();
+    expect(adapter.coerceToDate('2017-01-01')).not.toBeNull();
+    expect(adapter.coerceToDate('2017-01-01T00:00:00')).not.toBeNull();
+    expect(() => adapter.coerceToDate('1990-13-31T23:59:00Z')).toThrow();
+    expect(() => adapter.coerceToDate('1/1/2017')).toThrow();
+    expect(() => adapter.coerceToDate('2017-01-01T')).toThrow();
+    expect(adapter.coerceToDate('')).toBeNull();
+    expect(adapter.coerceToDate(null)).toBeNull();
+    expect(adapter.coerceToDate(new Date())).not.toBeNull();
+    expect(() => adapter.coerceToDate(new Date(NaN))).toThrow();
   });
 });
 
@@ -390,5 +395,4 @@ describe('NativeDateAdapter with LOCALE_ID override', () => {
 
     expect(adapter.getDayOfWeekNames('long')).toEqual(expectedValue);
   });
-
 });

src/lib/core/datetime/native-date-adapter.ts

@@ -7,8 +7,9 @@
  */
 
 import {Inject, Injectable, Optional} from '@angular/core';
-import {DateAdapter, MAT_DATE_LOCALE} from './date-adapter';
 import {extendObject} from '../util/object-extend';
+import {DateAdapter, MAT_DATE_LOCALE} from './date-adapter';
+
 
 // TODO(mmalerba): Remove when we no longer support safari 9.
 /** Whether the browser supports the Intl API. */
@@ -219,16 +220,26 @@ export class NativeDateAdapter extends DateAdapter<Date> {
     ].join('-');
   }
 
-  fromIso8601(iso8601String: string): Date | null {
-    // The `Date` constructor accepts formats other than ISO 8601, so we need to make sure the
-    // string is the right format first.
-    if (ISO_8601_REGEX.test(iso8601String)) {
-      let d = new Date(iso8601String);
-      if (this.isValid(d)) {
-        return d;
+  /**
+   * Returns the given value if given a valid Date or null. Coerces valid ISO 8601 strings
+   * (https://www.ietf.org/rfc/rfc3339.txt) to valid Dates and empty string to null. Throws on all
+   * other values.
+   */
+  coerceToDate(value: any): Date | null {
+    if (typeof value === 'string') {
+      if (!value) {
+        return null;
+      }
+      // The `Date` constructor accepts formats other than ISO 8601, so we need to make sure the
+      // string is the right format first.
+      if (ISO_8601_REGEX.test(value)) {
+        let date = new Date(value);
+        if (this.isValid(date)) {
+          return date;
+        }
       }
     }
-    return null;
+    return super.coerceToDate(value);
   }
 
   isDateInstance(obj: any) {

src/lib/datepicker/calendar.ts

@@ -38,7 +38,6 @@ import {
 import {DateAdapter, MAT_DATE_FORMATS, MatDateFormats} from '@angular/material/core';
 import {first} from 'rxjs/operator/first';
 import {Subscription} from 'rxjs/Subscription';
-import {coerceDateProperty} from './coerce-date-property';
 import {createMissingDateImplError} from './datepicker-errors';
 import {MatDatepickerIntl} from './datepicker-intl';
 import {MatMonthView} from './month-view';
@@ -67,7 +66,7 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
   /** A date representing the period (month or year) to start the calendar in. */
   @Input()
   get startAt(): D | null { return this._startAt; }
-  set startAt(value: D | null) { this._startAt = coerceDateProperty(this._dateAdapter, value); }
+  set startAt(value: D | null) { this._startAt = this._dateAdapter.coerceToDate(value); }
   private _startAt: D | null;
 
   /** Whether the calendar should be started in month or year view. */
@@ -76,19 +75,19 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
   /** The currently selected date. */
   @Input()
   get selected(): D | null { return this._selected; }
-  set selected(value: D | null) { this._selected = coerceDateProperty(this._dateAdapter, value); }
+  set selected(value: D | null) { this._selected = this._dateAdapter.coerceToDate(value); }
   private _selected: D | null;
 
   /** The minimum selectable date. */
   @Input()
   get minDate(): D | null { return this._minDate; }
-  set minDate(value: D | null) { this._minDate = coerceDateProperty(this._dateAdapter, value); }
+  set minDate(value: D | null) { this._minDate = this._dateAdapter.coerceToDate(value); }
   private _minDate: D | null;
 
   /** The maximum selectable date. */
   @Input()
   get maxDate(): D | null { return this._maxDate; }
-  set maxDate(value: D | null) { this._maxDate = coerceDateProperty(this._dateAdapter, value); }
+  set maxDate(value: D | null) { this._maxDate = this._dateAdapter.coerceToDate(value); }
   private _maxDate: D | null;
 
   /** A function used to filter which dates are selectable. */

src/lib/datepicker/coerce-date-property.spec.ts

@@ -1,54 +0,0 @@
-import {async, inject, TestBed} from '@angular/core/testing';
-import {DateAdapter, JAN, MatNativeDateModule} from '@angular/material/core';
-import {coerceDateProperty} from './index';
-
-
-describe('coerceDateProperty', () => {
-  let adapter: DateAdapter<Date>;
-
-  beforeEach(async(() => {
-    TestBed.configureTestingModule({
-      imports: [MatNativeDateModule],
-    });
-
-    TestBed.compileComponents();
-  }));
-
-  beforeEach(inject([DateAdapter], (dateAdapter: DateAdapter<Date>) => {
-    adapter = dateAdapter;
-  }));
-
-  it('should pass through existing date', () => {
-    const d = new Date(2017, JAN, 1);
-    expect(coerceDateProperty(adapter, d)).toBe(d);
-  });
-
-  it('should pass through invalid date', () => {
-    const d = new Date(NaN);
-    expect(coerceDateProperty(adapter, d)).toBe(d);
-  });
-
-  it('should pass through null and undefined', () => {
-    expect(coerceDateProperty(adapter, null)).toBeNull();
-    expect(coerceDateProperty(adapter, undefined)).toBeUndefined();
-  });
-
-  it('should coerce empty string to null', () => {
-    expect(coerceDateProperty(adapter, '')).toBe(null);
-  });
-
-  it('should coerce ISO 8601 string to date', () => {
-    let isoString = '2017-01-01T00:00:00Z';
-    expect(coerceDateProperty(adapter, isoString)).toEqual(new Date(isoString));
-  });
-
-  it('should throw when given a number', () => {
-    expect(() => coerceDateProperty(adapter, 5)).toThrow();
-    expect(() => coerceDateProperty(adapter, 0)).toThrow();
-  });
-
-  it('should throw when given a string with incorrect format', () => {
-    expect(() => coerceDateProperty(adapter, '1/1/2017')).toThrow();
-    expect(() => coerceDateProperty(adapter, 'hello')).toThrow();
-  });
-});

src/lib/datepicker/coerce-date-property.ts

@@ -1,35 +0,0 @@
-/**
- * @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 {DateAdapter} from '@angular/material/core';
-
-
-/**
- * Function that attempts to coerce a value to a date using a DateAdapter. Date instances, null,
- * and undefined will be passed through. Empty strings will be coerced to null. Valid ISO 8601
- * strings (https://www.ietf.org/rfc/rfc3339.txt) will be coerced to dates. All other values will
- * result in an error being thrown.
- * @param adapter The date adapter to use for coercion
- * @param value The value to coerce.
- * @return A date object coerced from the value.
- * @throws Throws when the value cannot be coerced.
- */
-export function coerceDateProperty<D>(adapter: DateAdapter<D>, value: any): D | null {
-  if (typeof value === 'string') {
-    if (value == '') {
-      value = null;
-    } else {
-      value = adapter.fromIso8601(value) || value;
-    }
-  }
-  if (value == null || adapter.isDateInstance(value)) {
-    return value;
-  }
-  throw Error(`Datepicker: Value must be either a date object recognized by the DateAdapter or ` +
-              `an ISO 8601 string. Instead got: ${value}`);
-}

src/lib/datepicker/datepicker-input.ts

@@ -34,7 +34,6 @@ import {
 import {DateAdapter, MAT_DATE_FORMATS, MatDateFormats} from '@angular/material/core';
 import {MatFormField} from '@angular/material/form-field';
 import {Subscription} from 'rxjs/Subscription';
-import {coerceDateProperty} from './coerce-date-property';
 import {MatDatepicker} from './datepicker';
 import {createMissingDateImplError} from './datepicker-errors';
 
@@ -113,7 +112,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
     return this._value;
   }
   set value(value: D | null) {
-    value = coerceDateProperty(this._dateAdapter, value);
+    value = this._dateAdapter.coerceToDate(value);
     this._lastValueValid = !value || this._dateAdapter.isValid(value);
     value = this._getValidDateOrNull(value);
 
@@ -131,7 +130,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
   @Input()
   get min(): D | null { return this._min; }
   set min(value: D | null) {
-    this._min = coerceDateProperty(this._dateAdapter, value);
+    this._min = this._dateAdapter.coerceToDate(value);
     this._validatorOnChange();
   }
   private _min: D | null;
@@ -140,7 +139,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
   @Input()
   get max(): D | null { return this._max; }
   set max(value: D | null) {
-    this._max = coerceDateProperty(this._dateAdapter, value);
+    this._max = this._dateAdapter.coerceToDate(value);
     this._validatorOnChange();
   }
   private _max: D | null;
@@ -188,23 +187,23 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
 
   /** The form control validator for the min date. */
   private _minValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = coerceDateProperty(this._dateAdapter, control.value);
+    const controlValue = this._dateAdapter.coerceToDate(control.value);
     return (!this.min || !controlValue ||
         this._dateAdapter.compareDate(this.min, controlValue) <= 0) ?
         null : {'matDatepickerMin': {'min': this.min, 'actual': controlValue}};
   }
 
   /** The form control validator for the max date. */
   private _maxValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = coerceDateProperty(this._dateAdapter, control.value);
+    const controlValue = this._dateAdapter.coerceToDate(control.value);
     return (!this.max || !controlValue ||
         this._dateAdapter.compareDate(this.max, controlValue) >= 0) ?
         null : {'matDatepickerMax': {'max': this.max, 'actual': controlValue}};
   }
 
   /** The form control validator for the date filter. */
   private _filterValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = coerceDateProperty(this._dateAdapter, control.value);
+    const controlValue = this._dateAdapter.coerceToDate(control.value);
     return !this._dateFilter || !controlValue || this._dateFilter(controlValue) ?
         null : {'matDatepickerFilter': true};
   }

src/lib/datepicker/datepicker.spec.ts

@@ -275,9 +275,8 @@ describe('MatDatepicker', () => {
       it('should throw when given wrong data type', () => {
         testComponent.date = '1/1/2017' as any;
 
-        expect(() => fixture.detectChanges()).toThrowError(
-            'Datepicker: Value must be either a date object recognized by the DateAdapter or an ' +
-            'ISO 8601 string. Instead got: 1/1/2017');
+        expect(() => fixture.detectChanges())
+            .toThrowError('Could not coerce "1/1/2017" to a valid date object.');
 
         testComponent.date = null;
       });

src/lib/datepicker/datepicker.ts

@@ -42,7 +42,6 @@ import {DOCUMENT} from '@angular/platform-browser';
 import {Subject} from 'rxjs/Subject';
 import {Subscription} from 'rxjs/Subscription';
 import {MatCalendar} from './calendar';
-import {coerceDateProperty} from './coerce-date-property';
 import {createMissingDateImplError} from './datepicker-errors';
 import {MatDatepickerInput} from './datepicker-input';
 
@@ -133,7 +132,7 @@ export class MatDatepicker<D> implements OnDestroy {
     // selected value is.
     return this._startAt || (this._datepickerInput ? this._datepickerInput.value : null);
   }
-  set startAt(date: D | null) { this._startAt = coerceDateProperty(this._dateAdapter, date); }
+  set startAt(date: D | null) { this._startAt = this._dateAdapter.coerceToDate(date); }
   private _startAt: D | null;
 
   /** The view that the calendar should start in. */

src/lib/datepicker/month-view.ts

@@ -20,7 +20,6 @@ import {
 } from '@angular/core';
 import {DateAdapter, MAT_DATE_FORMATS, MatDateFormats} from '@angular/material/core';
 import {MatCalendarCell} from './calendar-body';
-import {coerceDateProperty} from './coerce-date-property';
 import {createMissingDateImplError} from './datepicker-errors';
 
 
@@ -47,7 +46,7 @@ export class MatMonthView<D> implements AfterContentInit {
   get activeDate(): D { return this._activeDate; }
   set activeDate(value: D) {
     let oldActiveDate = this._activeDate;
-    this._activeDate = coerceDateProperty(this._dateAdapter, value) || this._dateAdapter.today();
+    this._activeDate = this._dateAdapter.coerceToDate(value) || this._dateAdapter.today();
     if (!this._hasSameMonthAndYear(oldActiveDate, this._activeDate)) {
       this._init();
     }
@@ -58,7 +57,7 @@ export class MatMonthView<D> implements AfterContentInit {
   @Input()
   get selected(): D | null { return this._selected; }
   set selected(value: D | null) {
-    this._selected = coerceDateProperty(this._dateAdapter, value);
+    this._selected = this._dateAdapter.coerceToDate(value);
     this._selectedDate = this._getDateInCurrentMonth(this._selected);
   }
   private _selected: D | null;