fix(calendar, datepicker): in year view, md-date-filter only evaluates first day of month

- add `md-month-filter` API
- no longer apply `md-date-filter` to year view
- fix JSDoc typos
- add JSDoc, tests, and demos

Fixes #11703

Author: Splaktar

src/components/datepicker/demoValidations/index.html

@@ -39,9 +39,15 @@ <h4>Inside a md-input-container</h4>
   </div>
   <div layout-gt-xs="row">
     <div flex-gt-xs>
-      <h4>Date-picker that only allows for certain months to be selected</h4>
+      <h4>Date-picker that only allows for even months</h4>
       <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date" md-mode="month"
-                     md-date-filter="ctrl.filter"></md-datepicker>
+                     md-month-filter="ctrl.evenMonthsPredicate"></md-datepicker>
+    </div>
+    <div flex-gt-xs>
+      <h4>Only allow even months and weekends</h4>
+      <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date"
+                     md-month-filter="ctrl.evenMonthsPredicate" md-current-view="year"
+                     md-date-filter="ctrl.onlyWeekendsPredicate"></md-datepicker>
     </div>
   </div>
 </md-content>

src/components/datepicker/demoValidations/script.js

@@ -27,7 +27,7 @@ angular.module('datepickerValidations', ['ngMaterial', 'ngMessages'])
    * @param {Date} date
    * @returns {boolean} return false to disable all odd numbered months, true for even months
    */
-  this.filter = function(date) {
-    return date.getMonth() % 2;
+  this.evenMonthsPredicate = function(date) {
+    return date.getMonth() % 2 !== 0;
   };
 });

src/components/datepicker/js/calendar.js

@@ -14,7 +14,9 @@
    * @param {Date=} md-min-date Expression representing the minimum date.
    * @param {Date=} md-max-date Expression representing the maximum date.
    * @param {(function(Date): boolean)=} md-date-filter Function expecting a date and returning a
-   *  boolean whether it can be selected or not.
+   *  boolean whether it can be selected in "day" mode or not.
+   * @param {(function(Date): boolean)=} md-month-filter Function expecting a date and returning a
+   *  boolean whether it can be selected in "month" mode or not.
    * @param {String=} md-current-view Current view of the calendar. Can be either "month" or "year".
    * @param {String=} md-mode Restricts the user to only selecting a value from a particular view.
    *  This option can be used if the user is only supposed to choose from a certain date type
@@ -60,6 +62,7 @@
         minDate: '=mdMinDate',
         maxDate: '=mdMaxDate',
         dateFilter: '=mdDateFilter',
+        monthFilter: '=mdMonthFilter',
 
         // These need to be prefixed, because Angular resets
         // any changes to the value due to bindToController.

src/components/datepicker/js/calendarYearBody.js

@@ -113,8 +113,8 @@
 
     if (this.dateUtil.isMonthWithinRange(
           firstOfMonth, calendarCtrl.minDate, calendarCtrl.maxDate) &&
-      (!angular.isFunction(this.calendarCtrl.dateFilter) ||
-        this.calendarCtrl.dateFilter(firstOfMonth))) {
+      (!angular.isFunction(calendarCtrl.monthFilter) ||
+        calendarCtrl.monthFilter(firstOfMonth))) {
       var selectionIndicator = document.createElement('span');
       selectionIndicator.classList.add('md-calendar-date-selection-indicator');
       selectionIndicator.textContent = cellText;

src/components/datepicker/js/datepickerDirective.js

@@ -29,7 +29,11 @@
    * @param {Date=} md-min-date Expression representing a min date (inclusive).
    * @param {Date=} md-max-date Expression representing a max date (inclusive).
    * @param {(function(Date): boolean)=} md-date-filter Function expecting a date and returning a
-   *  boolean whether it can be selected or not.
+   *  boolean whether it can be selected in "day" mode or not. Returning false will also trigger a
+   *  `filtered` model validation error.
+   * @param {(function(Date): boolean)=} md-month-filter Function expecting a date and returning a
+   *  boolean whether it can be selected in "month" mode or not. Returning false will also trigger a
+   *  `filtered` model validation error.
    * @param {String=} md-placeholder The date input placeholder value.
    * @param {String=} md-open-on-focus When present, the calendar will be opened when the input
    *  is focused.
@@ -49,7 +53,7 @@
    * * `"calendar"` - Only hides the calendar icon.
    * * `"triangle"` - Only hides the triangle icon.
    * @param {Object=} md-date-locale Allows for the values from the `$mdDateLocaleProvider` to be
-   * ovewritten on a per-element basis (e.g. `msgOpenCalendar` can be overwritten with
+   * overwritten on a per-element basis (e.g. `msgOpenCalendar` can be overwritten with
    * `md-date-locale="{ msgOpenCalendar: 'Open a special calendar' }"`).
    *
    * @description
@@ -127,6 +131,7 @@
                 'md-min-date="ctrl.minDate" ' +
                 'md-max-date="ctrl.maxDate" ' +
                 'md-date-filter="ctrl.dateFilter" ' +
+                'md-month-filter="ctrl.monthFilter" ' +
                 'ng-model="ctrl.date" ng-if="ctrl.isCalendarOpen">' +
             '</md-calendar>' +
           '</div>' +
@@ -140,6 +145,7 @@
         currentView: '@mdCurrentView',
         mode: '@mdMode',
         dateFilter: '=mdDateFilter',
+        monthFilter: '=mdMonthFilter',
         isOpen: '=?mdIsOpen',
         debounceInterval: '=mdDebounceInterval',
         dateLocale: '=mdDateLocale'
@@ -641,6 +647,10 @@
       if (angular.isFunction(this.dateFilter)) {
         this.ngModelCtrl.$setValidity('filtered', this.dateFilter(date));
       }
+
+      if (angular.isFunction(this.monthFilter)) {
+        this.ngModelCtrl.$setValidity('filtered', this.monthFilter(date));
+      }
     } else {
       // The date is seen as "not a valid date" if there is *something* set
       // (i.e.., not null or undefined), but that something isn't a valid date.
@@ -714,7 +724,8 @@
    */
   DatePickerCtrl.prototype.isDateEnabled = function(opt_date) {
     return this.dateUtil.isDateWithinRange(opt_date, this.minDate, this.maxDate) &&
-          (!angular.isFunction(this.dateFilter) || this.dateFilter(opt_date));
+          (!angular.isFunction(this.dateFilter) || this.dateFilter(opt_date)) &&
+          (!angular.isFunction(this.monthFilter) || this.monthFilter(opt_date));
   };
 
   /** Position and attach the floating calendar to the document. */
@@ -743,11 +754,11 @@
     // then it's possible that the already-scrolled body has a negative top/left. In this case,
     // we want to treat the "real" top as (0 - bodyRect.top). In a normal scrolling situation,
     // though, the top of the viewport should just be the body's scroll position.
-    var viewportTop = (bodyRect.top < 0 && document.body.scrollTop == 0) ?
+    var viewportTop = (bodyRect.top < 0 && document.body.scrollTop === 0) ?
         -bodyRect.top :
         document.body.scrollTop;
 
-    var viewportLeft = (bodyRect.left < 0 && document.body.scrollLeft == 0) ?
+    var viewportLeft = (bodyRect.left < 0 && document.body.scrollLeft === 0) ?
         -bodyRect.left :
         document.body.scrollLeft;
 

src/components/datepicker/js/datepickerDirective.spec.js

@@ -12,15 +12,16 @@ describe('md-datepicker', function() {
 
   var DATEPICKER_TEMPLATE =
     '<md-datepicker name="birthday" ' +
-         'md-max-date="maxDate" ' +
-         'md-min-date="minDate" ' +
-         'md-date-filter="dateFilter"' +
-         'ng-model="myDate" ' +
-         'ng-change="dateChangedHandler()" ' +
-         'ng-focus="focusHandler()" ' +
-         'ng-blur="blurHandler()" ' +
-         'ng-required="isRequired" ' +
-         'ng-disabled="isDisabled">' +
+      'md-max-date="maxDate" ' +
+      'md-min-date="minDate" ' +
+      'md-date-filter="dateFilter"' +
+      'md-month-filter="monthFilter"' +
+      'ng-model="myDate" ' +
+      'ng-change="dateChangedHandler()" ' +
+      'ng-focus="focusHandler()" ' +
+      'ng-blur="blurHandler()" ' +
+      'ng-required="isRequired" ' +
+      'ng-disabled="isDisabled">' +
     '</md-datepicker>';
 
   beforeEach(module('material.components.datepicker', 'material.components.input', 'ngAnimateMock'));
@@ -275,7 +276,7 @@ describe('md-datepicker', function() {
         expect(formCtrl.$error['maxdate']).toBeTruthy();
       });
 
-      it('should set `filtered` $error flag on the form', function() {
+      it('should set `filtered` $error flag on the form when date doesn\'t pass filter', function() {
         pageScope.dateFilter = function(date) {
           return date.getDay() === 1;
         };
@@ -285,6 +286,16 @@ describe('md-datepicker', function() {
         expect(formCtrl.$error['filtered']).toBeTruthy();
       });
 
+      it('should set `filtered` $error flag on the form when month doesn\'t pass filter', function() {
+        pageScope.monthFilter = function(date) {
+          return date.getMonth() === 10;
+        };
+        populateInputElement('2016-01-03');
+        controller.ngModelCtrl.$render();
+
+        expect(formCtrl.$error['filtered']).toBeTruthy();
+      });
+
       it('should add the invalid class when the form is submitted', function() {
         // This needs to be recompiled, in order to reproduce conditions where a form is
         // submitted, without the datepicker having being touched (usually it has it's value
@@ -383,7 +394,7 @@ describe('md-datepicker', function() {
       expect(controller.inputContainer).not.toHaveClass('md-datepicker-invalid');
     });
 
-    it('should not update the model when value is not enabled', function() {
+    it('should not update the model when value is not enabled due to date filter', function() {
       pageScope.dateFilter = function(date) {
         return date.getDay() === 1;
       };
@@ -393,6 +404,16 @@ describe('md-datepicker', function() {
       expect(controller.ngModelCtrl.$modelValue).toEqual(initialDate);
     });
 
+    it('should not update the model when value is not enabled due to month filter', function() {
+      pageScope.monthFilter = function(date) {
+        return date.getMonth() === 10;
+      };
+      pageScope.$apply();
+
+      populateInputElement('5/30/2014');
+      expect(controller.ngModelCtrl.$modelValue).toEqual(initialDate);
+    });
+
     it('should become touched from blurring closing the pane', function() {
       populateInputElement('17/1/2015');