feat(datepicker,calendar): md-date-filter disables months in month mode (#11526)

only the first day of the month is checked to disable the month
fix typos in docs
fix JSDoc

Closes #11525

Author: Splaktar

src/components/datepicker/demoValidations/index.html

@@ -37,4 +37,11 @@ <h4>Inside a md-input-container</h4>
       </md-input-container>
     </form>
   </div>
+  <div layout-gt-xs="row">
+    <div flex-gt-xs>
+      <h4>Date-picker that only allows for certain months to be selected</h4>
+      <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date" md-mode="month"
+                     md-date-filter="ctrl.filter"></md-datepicker>
+    </div>
+  </div>
 </md-content>

src/components/datepicker/demoValidations/script.js

@@ -1,4 +1,5 @@
-angular.module('datepickerValidations', ['ngMaterial', 'ngMessages']).controller('AppCtrl', function() {
+angular.module('datepickerValidations', ['ngMaterial', 'ngMessages'])
+.controller('AppCtrl', function() {
   this.myDate = new Date();
 
   this.minDate = new Date(
@@ -13,8 +14,20 @@ angular.module('datepickerValidations', ['ngMaterial', 'ngMessages']).controller
     this.myDate.getDate()
   );
 
+  /**
+   * @param {Date} date
+   * @returns {boolean}
+   */
   this.onlyWeekendsPredicate = function(date) {
     var day = date.getDay();
     return day === 0 || day === 6;
   };
+
+  /**
+   * @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;
+  }
 });

src/components/datepicker/js/calendar.js

@@ -9,11 +9,13 @@
    * @param {Date} ng-model The component's model. Should be a Date object.
    * @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.
+   * @param {(function(Date): boolean)=} md-date-filter Function expecting a date and returning a
+   *  boolean whether it can be selected 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 (e.g. only selecting the month).
-   * Can be either "month" or "day". **Note** that this will ovewrite the `md-current-view` value.
+   * @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
+   *  (e.g. only selecting the month). Can be either "month" or "day". **Note** that this will
+   *  overwrite the `md-current-view` value.
    *
    * @description
    * `<md-calendar>` is a component that renders a calendar that can be used to select a date.

src/components/datepicker/js/calendarYearBody.js

@@ -83,8 +83,8 @@
 
   /**
    * Creates a single cell to contain a year in the calendar.
-   * @param {number} opt_year Four-digit year.
-   * @param {number} opt_month Zero-indexed month.
+   * @param {number} year Four-digit year.
+   * @param {number} month Zero-indexed month.
    * @returns {HTMLElement}
    */
   CalendarYearBodyCtrl.prototype.buildMonthCell = function(year, month) {
@@ -98,7 +98,7 @@
     cell.id = calendarCtrl.getDateId(firstOfMonth, 'year');
 
     // Use `data-timestamp` attribute because IE10 does not support the `dataset` property.
-    cell.setAttribute('data-timestamp', firstOfMonth.getTime());
+    cell.setAttribute('data-timestamp', String(firstOfMonth.getTime()));
 
     if (this.dateUtil.isSameMonthAndYear(firstOfMonth, calendarCtrl.today)) {
       cell.classList.add(calendarCtrl.TODAY_CLASS);
@@ -112,15 +112,18 @@
 
     var cellText = this.dateLocale.shortMonths[month];
 
-    if (this.dateUtil.isMonthWithinRange(firstOfMonth,
-        calendarCtrl.minDate, calendarCtrl.maxDate)) {
+    if (this.dateUtil.isMonthWithinRange(
+          firstOfMonth, calendarCtrl.minDate, calendarCtrl.maxDate) &&
+      (!angular.isFunction(this.calendarCtrl.dateFilter) ||
+        this.calendarCtrl.dateFilter(firstOfMonth))) {
       var selectionIndicator = document.createElement('span');
       selectionIndicator.classList.add('md-calendar-date-selection-indicator');
       selectionIndicator.textContent = cellText;
       cell.appendChild(selectionIndicator);
       cell.addEventListener('click', yearCtrl.cellClickHandler);
 
-      if (calendarCtrl.displayDate && this.dateUtil.isSameMonthAndYear(firstOfMonth, calendarCtrl.displayDate)) {
+      if (calendarCtrl.displayDate &&
+          this.dateUtil.isSameMonthAndYear(firstOfMonth, calendarCtrl.displayDate)) {
         this.focusAfterAppend = cell;
       }
     } else {
@@ -133,7 +136,7 @@
 
   /**
    * Builds a blank cell.
-   * @return {HTMLTableCellElement}
+   * @return {HTMLElement}
    */
   CalendarYearBodyCtrl.prototype.buildBlankCell = function() {
     var cell = document.createElement('td');