feat(datepicker): add the ability to restrict users to a calendar view (#9736)

* Adds the ability to restrict users to a calendar view. For example, it's now possible to let users only select a month, instead of having to pick out a date within the month. This can be useful for cases like a credit card form, where the day of the month doesn't necessarily make sense.
* Fixes an issue where the year view wouldn't highlight the proper cell, if the model was changed externally and the date was different from the first day of the month.

Fixes #9260.

Author: crisbeto

src/components/datepicker/calendar.scss

@@ -127,7 +127,7 @@ md-calendar {
   font-weight: 500; // Roboto Medium
   @include rtl(padding, 0 0 0 $md-calendar-side-padding + $md-calendar-month-label-padding, rtl-value( 0 0 0 $md-calendar-side-padding + $md-calendar-month-label-padding));
 
-  md-calendar-month &:not(.md-calendar-month-label-disabled) {
+  &.md-calendar-label-clickable {
     cursor: pointer;
   }
 

src/components/datepicker/demoBasicUsage/index.html

@@ -29,5 +29,10 @@ <h4>Custom calendar trigger</h4>
       <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date" md-is-open="ctrl.isOpen"></md-datepicker>
       <md-button class="md-primary md-raised" ng-click="ctrl.isOpen = true">Open</md-button>
     </div>
+
+    <div flex-gt-xs>
+      <h4>Date-picker that only allows for the month to be selected</h4>
+      <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date" md-mode="month"></md-datepicker>
+    </div>
   </div>
 </md-content>

src/components/datepicker/js/calendar.js

@@ -10,6 +10,10 @@
    * @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 {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.
    *
    * @description
    * `<md-calendar>` is a component that renders a calendar that can be used to select a date.
@@ -58,6 +62,10 @@
         minDate: '=mdMinDate',
         maxDate: '=mdMaxDate',
         dateFilter: '=mdDateFilter',
+
+        // These need to be prefixed, because Angular resets
+        // any changes to the value due to bindToController.
+        _mode: '@mdMode',
         _currentView: '@mdCurrentView'
       },
       require: ['ngModel', 'mdCalendar'],
@@ -84,6 +92,12 @@
   /** Next identifier for calendar instance. */
   var nextUniqueId = 0;
 
+  /** Maps the `md-mode` values to their corresponding calendar views. */
+  var MODE_MAP = {
+    day: 'month',
+    month: 'year'
+  };
+
   /**
    * Controller for the mdCalendar component.
    * @ngInject @constructor
@@ -192,8 +206,6 @@
 
     var boundKeyHandler = angular.bind(this, this.handleKeyEvent);
 
-
-
     // If use the md-calendar directly in the body without datepicker,
     // handleKeyEvent will disable other inputs on the page.
     // So only apply the handleKeyEvent on the body when the md-calendar inside datepicker,
@@ -227,14 +239,19 @@
    * Bindings are not guaranteed to have been assigned in the controller, but they are in the $onInit hook.
    */
   CalendarCtrl.prototype.$onInit = function() {
-
     /**
      * The currently visible calendar view. Note the prefix on the scope value,
      * which is necessary, because the datepicker seems to reset the real one value if the
-     * calendar is open, but the value on the datepicker's scope is empty.
+     * calendar is open, but the `currentView` on the datepicker's scope is empty.
      * @type {String}
      */
-    this.currentView = this._currentView || 'month';
+    if (this._mode && MODE_MAP.hasOwnProperty(this._mode)) {
+      this.currentView = MODE_MAP[this._mode];
+      this.mode = this._mode;
+    } else {
+      this.currentView = this._currentView || 'month';
+      this.mode = null;
+    }
 
     var dateLocale = this.$mdDateLocale;
 
@@ -318,7 +335,7 @@
    */
   CalendarCtrl.prototype.focus = function(date) {
     if (this.dateUtil.isValidDate(date)) {
-      var previousFocus = this.$element[0].querySelector('.md-focus');
+      var previousFocus = this.$element[0].querySelector('.' + this.FOCUSED_DATE_CLASS);
       if (previousFocus) {
         previousFocus.classList.remove(this.FOCUSED_DATE_CLASS);
       }
@@ -339,6 +356,32 @@
     }
   };
 
+  /**
+   * Highlights a date cell on the calendar and changes the selected date.
+   * @param {Date=} date Date to be marked as selected.
+   */
+  CalendarCtrl.prototype.changeSelectedDate = function(date) {
+    var selectedDateClass = this.SELECTED_DATE_CLASS;
+    var prevDateCell = this.$element[0].querySelector('.' + selectedDateClass);
+
+    // Remove the selected class from the previously selected date, if any.
+    if (prevDateCell) {
+      prevDateCell.classList.remove(selectedDateClass);
+      prevDateCell.setAttribute('aria-selected', 'false');
+    }
+
+    // Apply the select class to the new selected date if it is set.
+    if (date) {
+      var dateCell = document.getElementById(this.getDateId(date, this.currentView));
+      if (dateCell) {
+        dateCell.classList.add(selectedDateClass);
+        dateCell.setAttribute('aria-selected', 'true');
+      }
+    }
+
+    this.selectedDate = date;
+  };
+
   /**
    * Normalizes the key event into an action name. The action will be broadcast
    * to the child controllers.
@@ -355,8 +398,6 @@
       case keyCode.RIGHT_ARROW: return 'move-right';
       case keyCode.LEFT_ARROW: return 'move-left';
 
-      // TODO(crisbeto): Might want to reconsider using metaKey, because it maps
-      // to the "Windows" key on PC, which opens the start menu or resizes the browser.
       case keyCode.DOWN_ARROW: return event.metaKey ? 'move-page-down' : 'move-row-down';
       case keyCode.UP_ARROW: return event.metaKey ? 'move-page-up' : 'move-row-up';
 

src/components/datepicker/js/calendar.spec.js

@@ -17,7 +17,6 @@ describe('md-calendar', function() {
    */
   function applyDateChange() {
     $timeout.flush();
-    pageScope.$apply();
     $material.flushOutstandingAnimations();
 
     // Internally, the calendar sets scrollTop to scroll to the month for a change.
@@ -57,7 +56,7 @@ describe('md-calendar', function() {
   /**
    * Finds a month `tbody` in the calendar element given a date.
    */
-  function findMonthElement(date) {
+  function findMonthElement(element, date) {
     var months = element.querySelectorAll('[md-calendar-month-body]');
     var monthHeader = dateLocale.monthHeaderFormatter(date);
     var month;
@@ -72,8 +71,8 @@ describe('md-calendar', function() {
   }
 
   /** Find the `tbody` for a year in the calendar. */
-  function findYearElement(year) {
-    var node = element[0] || element;
+  function findYearElement(parent, year) {
+    var node = parent[0] || parent;
     var years = node.querySelectorAll('[md-calendar-year-body]');
     var yearHeader = year.toString();
     var target;
@@ -415,9 +414,9 @@ describe('md-calendar', function() {
         newScope.$apply();
         element = createElement(newScope)[0];
 
-        expect(findMonthElement(new Date(2014, JUL, 1))).not.toBeNull();
-        expect(findMonthElement(new Date(2014, JUN, 1))).not.toBeNull();
-        expect(findMonthElement(new Date(2014, MAY, 1))).toBeNull();
+        expect(findMonthElement(element, new Date(2014, JUL, 1))).not.toBeNull();
+        expect(findMonthElement(element, new Date(2014, JUN, 1))).not.toBeNull();
+        expect(findMonthElement(element, new Date(2014, MAY, 1))).toBeNull();
       });
     });
 
@@ -514,8 +513,27 @@ describe('md-calendar', function() {
         element.controller('mdCalendar').setCurrentView('year');
         applyDateChange();
 
-        expect(findYearElement(2014)).not.toBeNull();
-        expect(findYearElement(2013)).toBeNull();
+        expect(findYearElement(element, 2014)).not.toBeNull();
+        expect(findYearElement(element, 2013)).toBeNull();
+      });
+
+      it('should highlight the proper cell, even when the date is not the ' +
+        'first day of the month', function() {
+        var newScope = $rootScope.$new();
+
+        newScope.myDate = new Date(2015, MAY, 1);
+        element = createElement(newScope)[0];
+        angular.element(element).controller('mdCalendar').setCurrentView('year');
+        applyDateChange();
+
+        var yearElement = findYearElement(element, 2015);
+
+        expect(findCellByLabel(yearElement, 'May')).toHaveClass('md-calendar-selected-date');
+
+        newScope.myDate = new Date(2015, JUL, 15);
+        applyDateChange();
+
+        expect(findCellByLabel(yearElement, 'Jul')).toHaveClass('md-calendar-selected-date');
       });
 
       it('should ensure that all year elements have a height when the ' +
@@ -737,6 +755,106 @@ describe('md-calendar', function() {
     });
   });
 
+  describe('md-mode support', function() {
+    var element, controller;
+
+    function compileElement(attrs) {
+      ngElement.remove();
+      element = createElement(pageScope, '<md-calendar ng-model="myDate" ' + (attrs || '') + '></md-calendar>');
+      controller = element.controller('mdCalendar');
+    }
+
+    it('should go to the corresponding view', function() {
+      compileElement('md-mode="month"');
+
+      expect(element.find('md-calendar-month').length).toBe(0);
+      expect(element.find('md-calendar-year').length).toBe(1);
+      expect(controller.currentView).toBe('year');
+    });
+
+    it('should override md-current-view', function() {
+      compileElement('md-mode="day" md-current-view="year"');
+
+      expect(element.find('md-calendar-year').length).toBe(0);
+      expect(element.find('md-calendar-month').length).toBe(1);
+      expect(controller.currentView).toBe('month');
+    });
+
+    it('should not allow users to go to a different view', function() {
+      compileElement('md-mode="day"');
+
+      expect(controller.currentView).toBe('month');
+
+      element[0].querySelector('.md-calendar-month-label').click();
+      applyDateChange();
+
+      expect(controller.currentView).toBe('month');
+    });
+
+    it('should allow users to navigate to a different view if the md-mode is not supported', function() {
+      compileElement('md-mode="invalid-mode"');
+
+      expect(controller.currentView).toBe('month');
+      expect(controller.mode).toBeFalsy();
+
+      element[0].querySelector('.md-calendar-month-label').click();
+      applyDateChange();
+
+      expect(controller.currentView).toBe('year');
+    });
+
+    it('should update the model when clicking on a cell in the year view', function() {
+      pageScope.myDate = new Date(2015, MAY, 15);
+
+      compileElement('md-mode="month"');
+
+      expect(controller.currentView).toBe('year');
+
+      var yearElement = findYearElement(element[0], 2015);
+      var monthCell = findCellByLabel(yearElement, 'Sep');
+      var expectedDate = new Date(2015, SEP, 1);
+
+      monthCell.click();
+      applyDateChange();
+
+      expect(pageScope.myDate).toBeSameDayAs(expectedDate);
+      expect(controller.currentView).toBe('year');
+    });
+
+    it('should update the model when clicking on a cell in the day view', function() {
+      pageScope.myDate = new Date(2015, MAY, 15);
+
+      compileElement('md-mode="day"');
+
+      var monthElement = findMonthElement(element[0], pageScope.myDate);
+      var monthCell = findCellByLabel(monthElement, '28');
+      var expectedDate = new Date(2015, MAY, 28);
+
+      monthCell.click();
+      applyDateChange();
+
+      expect(pageScope.myDate).toBeSameDayAs(expectedDate);
+    });
+  });
+
+  describe('md-current-view support', function() {
+    beforeEach(function() {
+      ngElement && ngElement.remove();
+    });
+
+    it('should have a configurable default view', function() {
+      var calendar = createElement(null, '<md-calendar ng-model="myDate" md-current-view="year"></md-calendar>')[0];
+
+      expect(calendar.querySelector('md-calendar-month')).toBeFalsy();
+      expect(calendar.querySelector('md-calendar-year')).toBeTruthy();
+    });
+
+    it('should default to the month view if no view is supploied', function() {
+      var calendar = createElement(null, '<md-calendar ng-model="myDate"></md-calendar>');
+      expect(calendar.controller('mdCalendar').currentView).toBe('month');
+    });
+  });
+
   it('should render one single-row month of disabled cells after the max date', function() {
     ngElement.remove();
     var newScope = $rootScope.$new();
@@ -745,11 +863,11 @@ describe('md-calendar', function() {
     newScope.$apply();
     element = createElement(newScope)[0];
 
-    expect(findMonthElement(new Date(2014, MAR, 1))).not.toBeNull();
-    expect(findMonthElement(new Date(2014, APR, 1))).not.toBeNull();
+    expect(findMonthElement(element, new Date(2014, MAR, 1))).not.toBeNull();
+    expect(findMonthElement(element, new Date(2014, APR, 1))).not.toBeNull();
 
     // First date of May 2014 on Thursday (i.e. has 3 dates on the first row).
-    var nextMonth = findMonthElement(new Date(2014, MAY, 1));
+    var nextMonth = findMonthElement(element, new Date(2014, MAY, 1));
     expect(nextMonth).not.toBeNull();
     expect(nextMonth.querySelector('.md-calendar-month-label')).toHaveClass(
         'md-calendar-month-label-disabled');
@@ -764,12 +882,4 @@ describe('md-calendar', function() {
       }
     }
   });
-
-  it('should have a configurable default view', function() {
-    ngElement.remove();
-    var calendar = createElement(null, '<md-calendar ng-model="myDate" md-current-view="year"></md-calendar>')[0];
-
-    expect(calendar.querySelector('md-calendar-month')).toBeFalsy();
-    expect(calendar.querySelector('md-calendar-year')).toBeTruthy();
-  });
 });

src/components/datepicker/js/calendarMonth.js

@@ -156,40 +156,6 @@
     );
   };
 
-  /**
-   * Change the selected date in the calendar (ngModel value has already been changed).
-   * @param {Date} date
-   */
-  CalendarMonthCtrl.prototype.changeSelectedDate = function(date) {
-    var self = this;
-    var calendarCtrl = self.calendarCtrl;
-    var previousSelectedDate = calendarCtrl.selectedDate;
-    calendarCtrl.selectedDate = date;
-
-    this.changeDisplayDate(date).then(function() {
-      var selectedDateClass = calendarCtrl.SELECTED_DATE_CLASS;
-      var namespace = 'month';
-
-      // Remove the selected class from the previously selected date, if any.
-      if (previousSelectedDate) {
-        var prevDateCell = document.getElementById(calendarCtrl.getDateId(previousSelectedDate, namespace));
-        if (prevDateCell) {
-          prevDateCell.classList.remove(selectedDateClass);
-          prevDateCell.setAttribute('aria-selected', 'false');
-        }
-      }
-
-      // Apply the select class to the new selected date if it is set.
-      if (date) {
-        var dateCell = document.getElementById(calendarCtrl.getDateId(date, namespace));
-        if (dateCell) {
-          dateCell.classList.add(selectedDateClass);
-          dateCell.setAttribute('aria-selected', 'true');
-        }
-      }
-    });
-  };
-
   /**
    * Change the date that is being shown in the calendar. If the given date is in a different
    * month, the displayed month will be transitioned.
@@ -262,7 +228,8 @@
     var self = this;
 
     self.$scope.$on('md-calendar-parent-changed', function(event, value) {
-      self.changeSelectedDate(value);
+      self.calendarCtrl.changeSelectedDate(value);
+      self.changeDisplayDate(value);
     });
 
     self.$scope.$on('md-calendar-parent-action', angular.bind(this, this.handleKeyEvent));