feat(datepicker): add docs with usage for $mdDateLocale

src/components/datepicker/calendar.js

@@ -76,7 +76,7 @@
  * @ngInject @constructor
  */
  function CalendarCtrl($element, $attrs, $scope, $animate, $q, $mdConstant,
- $mdTheming, $$mdDateUtil, $$mdDateLocale, $mdInkRipple, $mdUtil) {
+ $mdTheming, $$mdDateUtil, $mdDateLocale, $mdInkRipple, $mdUtil) {
  $mdTheming($element);
  /**
  * Dummy array-like object for virtual-repeat to iterate over. The length is the total
@@ -104,7 +104,7 @@
  this.dateUtil = $$mdDateUtil;
 
  /** @final */
- this.dateLocale = $$mdDateLocale;
+ this.dateLocale = $mdDateLocale;
 
  /** @final {!angular.JQLite} */
  this.$element = $element;

src/components/datepicker/calendar.spec.js

@@ -98,7 +98,7 @@ describe('md-calendar', function() {
  $compile = $injector.get('$compile');
  $rootScope = $injector.get('$rootScope');
  $$rAF = $injector.get('$$rAF');
- dateLocale = $injector.get('$$mdDateLocale');
+ dateLocale = $injector.get('$mdDateLocale');
  dateUtil = $injector.get('$$mdDateUtil');
  $mdUtil = $injector.get('$mdUtil');
  keyCodes = $injector.get('$mdConstant').KEY_CODE;
@@ -136,7 +136,7 @@ describe('md-calendar', function() {
  expect(extractRowText(header)).toEqual(['S', 'M', 'T', 'W', 'T', 'F' ,'S']);
  });
 
- it('should use $$mdDateLocale.shortDays as weeks header values', function() {
+ it('should use $mdDateLocale.shortDays as weeks header values', function() {
  var oldShortDays = dateLocale.shortDays;
  dateLocale.shortDays = ['SZ', 'MZ', 'TZ', 'WZ', 'TZ', 'FZ', 'SZ'];
 

src/components/datepicker/calendarMonth.js

@@ -48,9 +48,9 @@
  * Controller for a single calendar month.
  * @ngInject @constructor
  */
- function CalendarMonthCtrl($element, $$mdDateUtil, $$mdDateLocale) {
+ function CalendarMonthCtrl($element, $$mdDateUtil, $mdDateLocale) {
  this.dateUtil = $$mdDateUtil;
- this.dateLocale = $$mdDateLocale;
+ this.dateLocale = $mdDateLocale;
  this.$element = $element;
  this.calendarCtrl = null;
 
@@ -108,7 +108,7 @@
  selectionIndicator.textContent = this.dateLocale.dates[opt_date.getDate()];
 
  cell.setAttribute('tabindex', '-1');
- cell.setAttribute('aria-label', this.dateLocale.longAnnounceFormatter(opt_date));
+ cell.setAttribute('aria-label', this.dateLocale.longDateFormatter(opt_date));
  cell.id = calendarCtrl.getDateId(opt_date);
  cell.addEventListener('click', calendarCtrl.cellClickHandler);
 

src/components/datepicker/dateLocale.spec.js

@@ -1,5 +1,5 @@
 
-describe('$$mdDateLocale', function() {
+describe('$mdDateLocale', function() {
  var dateLocale, dateUtil;
 
  // Fake $locale with made-up days and months.
@@ -19,8 +19,8 @@ describe('$$mdDateLocale', function() {
  $provide.value('$locale', $localeFake);
  }));
 
- beforeEach(inject(function($$mdDateLocale, $$mdDateUtil) {
- dateLocale = $$mdDateLocale;
+ beforeEach(inject(function($mdDateLocale, $$mdDateUtil) {
+ dateLocale = $mdDateLocale;
  dateUtil = $$mdDateUtil;
  }));
 
@@ -55,23 +55,23 @@ describe('$$mdDateLocale', function() {
  'X12', 'X13', 'X14', 'X15', 'X16', 'X17', 'X18', 'X19', 'X20', 'X21', 'X22', 'X23', 'X24',
  'X25', 'X26', 'X27', 'X28', 'X29', 'X30', 'X31'];
 
- beforeEach(module(function($$mdDateLocaleProvider) {
- $$mdDateLocaleProvider.months = fakeMonths;
- $$mdDateLocaleProvider.shortMonths = fakeshortMonths;
- $$mdDateLocaleProvider.days = fakeDays;
- $$mdDateLocaleProvider.shortDays = fakeShortDays;
- $$mdDateLocaleProvider.dates = fakeDates;
- $$mdDateLocaleProvider.formatDate = function() {
+ beforeEach(module(function($mdDateLocaleProvider) {
+ $mdDateLocaleProvider.months = fakeMonths;
+ $mdDateLocaleProvider.shortMonths = fakeshortMonths;
+ $mdDateLocaleProvider.days = fakeDays;
+ $mdDateLocaleProvider.shortDays = fakeShortDays;
+ $mdDateLocaleProvider.dates = fakeDates;
+ $mdDateLocaleProvider.formatDate = function() {
  return 'Your birthday!'
  };
- $$mdDateLocaleProvider.parseDate = function() {
+ $mdDateLocaleProvider.parseDate = function() {
  return new Date(1969, 6, 16);
  };
  }));
 
 
- beforeEach(inject(function($$mdDateLocale, $$mdDateUtil) {
- dateLocale = $$mdDateLocale;
+ beforeEach(inject(function($mdDateLocale, $$mdDateUtil) {
+ dateLocale = $mdDateLocale;
  dateUtil = $$mdDateUtil;
  }));
 

src/components/datepicker/dateLocaleProvider.js

@@ -5,6 +5,53 @@
  * Provider that allows the user to specify messages, formatters, and parsers for date
  * internationalization.
  */
+
+
+ /**
+ * @ngdoc service
+ * @name $mdDateLocaleProvider
+ * @module material.components.datepicker
+ *
+ * @description
+ * The `$mdDateLocaleProvider` is the provider that creates the `$mdDateLocale` service.
+ * This provider that allows the user to specify messages, formatters, and parsers for date
+ * internationalization. The `$mdDateLocale` service itself is consumed by Angular Material
+ * components that that deal with dates.
+ *
+ * @usage
+ * <hljs lang="js">
+ * myAppModule.config(function($mdDateLocaleProvider) {
+ *
+ * // Example of a French localization.
+ * $mdDateLocaleProvider.months = ['Janvier', 'Février', 'Mars', ...];
+ * $mdDateLocaleProvider.shortMonths = ['Janv', 'Févr', 'Mars', ...];
+ * $mdDateLocaleProvider.days = ['Lundi', 'Mardi', 'Mercredi', ...];
+ * $mdDateLocaleProvider.shortDays = ['L', 'M', 'M', ...];
+ * $mdDateLocaleProvider.dates = [1, 2, 3, 4, 5, 6, ...];
+ *
+ * // Example uses moment.js to parse and format dates.
+ * $mdDateLocaleProvider.formatDate = function(date) {
+ * return moment(date).format
+ * };
+ * $mdDateLocaleProvider.parseDate = function(dateString) {
+ * return moment(dateString).toDate('L');
+ * };
+ *
+ * $mdDateLocaleProvider.monthHeaderFormatter = function(date) {
+ * $mdDateLocale.shortMonths[date.getMonth()] + ' ' + date.getFullYear();
+ * };
+ *
+ * $mdDateLocaleProvider.weekNumberFormatter = function(weekNumber) {
+ * return 'Semaine ' + weekNumber;
+ * };
+ *
+ * $mdDateLocaleProvider.msgCalendar = 'Calendrier';
+ * $mdDateLocaleProvider.msgOpenCalendar = 'Ouvrir le calendrier';
+ *
+ * });
+ * </hljs>
+ *
+ */
  angular.module('material.components.datepicker').config(function($provide) {
  // TODO(jelbourn): Assert provided values are correctly formatted. Need assertions.
 
@@ -50,18 +97,11 @@
  this.weekNumberFormatter = null;
 
  /**
- * Function that formats a date into a short aria-live announcement that is read when
- * the focused date changes within the same month.
- * @type {function(Date): string}
- */
- this.shortAnnounceFormatter = null;
-
- /**
- * Function that formats a date into a long aria-live announcement that is read when
- * the focused date changes to a date in a different month.
+ * Function that formats a date into a long aria-label that is read
+ * when the focused date changes.
  * @type {function(Date): string}
  */
- this.longAnnounceFormatter = null;
+ this.longDateFormatter = null;
 
  /**
  * ARIA label for the calendar "dialog" used in the datepicker.
@@ -120,21 +160,11 @@
  }
 
  /**
- * Default formatter for short aria-live announcements.
- * @param {!Date} date
- * @returns {string}
- */
- function defaultShortAnnounceFormatter(date) {
- // Example: 'Tuesday 12'
- return service.days[date.getDay()] + ' ' + service.dates[date.getDate()];
- }
-
- /**
- * Default formatter for long aria-live announcements.
+ * Default formatter for date cell aria-labels.
  * @param {!Date} date
  * @returns {string}
  */
- function defaultLongAnnounceFormatter(date) {
+ function defaultLongDateFormatter(date) {
  // Example: 'Thursday June 18 2015'
  return [
  service.days[date.getDay()],
@@ -170,15 +200,14 @@
  parseDate: this.parseDate || defaultParseDate,
  monthHeaderFormatter: this.monthHeaderFormatter || defaultMonthHeaderFormatter,
  weekNumberFormatter: this.weekNumberFormatter || defaultWeekNumberFormatter,
- shortAnnounceFormatter: this.shortAnnounceFormatter || defaultShortAnnounceFormatter,
- longAnnounceFormatter: this.longAnnounceFormatter || defaultLongAnnounceFormatter,
+ longDateFormatter: this.longDateFormatter || defaultLongDateFormatter,
  msgCalendar: this.msgCalendar || defaultMsgCalendar,
  msgOpenCalendar: this.msgOpenCalendar || defaultMsgOpenCalendar
  });
 
  return service;
  };
 
- $provide.provider('$$mdDateLocale', new DateLocaleProvider());
+ $provide.provider('$mdDateLocale', new DateLocaleProvider());
  });
 })();

src/components/datepicker/datePicker.js

@@ -29,6 +29,8 @@
  *
  * @description
  * `<md-datepicker>` is a component used to select a single date.
+ * For information on how to configure internationalization for the date piicker,
+ * see `$mdDateLocaleProvider`.
  *
  * @usage
  * <hljs lang="html">
@@ -45,7 +47,7 @@
  '<md-button class="md-datepicker-button md-icon-button" type="button" ' +
  'tabindex="-1" aria-hidden="true" ' +
  'ng-click="ctrl.openCalendarPane($event)">' +
-  '<md-icon class="md-datepicker-calendar-icon" md-svg-icon="md-calendar"></md-icon>' +
+ '<md-icon class="md-datepicker-calendar-icon" md-svg-icon="md-calendar"></md-icon>' +
  '</md-button>' +
  '<div class="md-datepicker-input-container">' +
  '<input class="md-datepicker-input" aria-haspopup="true">' +
@@ -90,15 +92,15 @@
  * @ngInject @constructor
  */
  function DatePickerCtrl($scope, $element, $attrs, $compile, $timeout, $mdConstant, $mdTheming,
- $mdUtil, $$mdDateLocale, $$mdDateUtil, $$rAF) {
+ $mdUtil, $mdDateLocale, $$mdDateUtil, $$rAF) {
  /** @final */
  this.$compile = $compile;
 
  /** @final */
  this.$timeout = $timeout;
 
  /** @final */
- this.dateLocale = $$mdDateLocale;
+ this.dateLocale = $mdDateLocale;
 
  /** @final */
  this.dateUtil = $$mdDateUtil;

src/components/datepicker/datePicker.spec.js

@@ -16,7 +16,7 @@ describe('md-date-picker', function() {
  $$rAF = $injector.get('$$rAF');
  $animate = $injector.get('$animate');
  dateUtil = $injector.get('$$mdDateUtil');
- dateLocale = $injector.get('$$mdDateLocale');
+ dateLocale = $injector.get('$mdDateLocale');
  $timeout = $injector.get('$timeout');
  keyCodes = $injector.get('$mdConstant').KEY_CODE;