From 218c653f511ae77c5076dbe04810f5c10ee816e5 Mon Sep 17 00:00:00 2001
From: Michael Prentice <splaktar@gmail.com>
Date: Mon, 14 Dec 2020 23:45:55 -0500
Subject: [PATCH] feat(datepicker): add input-aria-describedby and
 input-aria-labelledby

- add docs and demos for new APIs
- change String to string in datepicker param JSDoc
- make the `md-input-container` example more accessible
  as `md-input-container` does not apply `for="input_x"` to the label
  when `md-datepicker` is used

Fixes #11762
---
 .../datepicker/demoBasicUsage/index.html      | 10 +++++--
 .../datepicker/demoValidations/index.html     |  4 +--
 .../datepicker/js/datepickerDirective.js      | 26 ++++++++++++++-----
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/src/components/datepicker/demoBasicUsage/index.html b/src/components/datepicker/demoBasicUsage/index.html
index c27f6d1bd6f..103832e1eb9 100644
--- a/src/components/datepicker/demoBasicUsage/index.html
+++ b/src/components/datepicker/demoBasicUsage/index.html
@@ -1,8 +1,14 @@
 <md-content ng-controller="AppCtrl as ctrl" layout-padding ng-cloak>
   <div layout-gt-xs="row">
     <div flex-gt-xs>
-      <h4>Standard date-picker</h4>
-      <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date"></md-datepicker>
+      <h4 id="datepicker-header">Standard date-picker</h4>
+      <md-datepicker ng-model="ctrl.myDate" md-placeholder="Enter date"
+                     input-aria-describedby="datepicker-description"
+                     input-aria-labelledby="datepicker-header "></md-datepicker>
+      <p style="display: none" id="datepicker-description">
+        You can use input-aria-describedby to have screen readers provide a more detailed
+        description of a datepicker or its interactions.
+      </p>
     </div>
 
     <div flex-gt-xs>
diff --git a/src/components/datepicker/demoValidations/index.html b/src/components/datepicker/demoValidations/index.html
index 34bb281f741..14a1516cca1 100644
--- a/src/components/datepicker/demoValidations/index.html
+++ b/src/components/datepicker/demoValidations/index.html
@@ -25,9 +25,9 @@ <h4>Only weekends within given range are selectable</h4>
       <h4>Inside a md-input-container</h4>
 
       <md-input-container>
-        <label>Enter date</label>
+        <label id="enter-date-label">Enter date</label>
         <md-datepicker ng-model="ctrl.myDate" name="dateField" md-min-date="ctrl.minDate"
-          md-max-date="ctrl.maxDate"></md-datepicker>
+          md-max-date="ctrl.maxDate" input-aria-labelledby="enter-date-label"></md-datepicker>
 
         <div ng-messages="myForm.dateField.$error">
           <div ng-message="valid">Use a valid date format</div>
diff --git a/src/components/datepicker/js/datepickerDirective.js b/src/components/datepicker/js/datepickerDirective.js
index de48332a1ab..bdb5856df1e 100644
--- a/src/components/datepicker/js/datepickerDirective.js
+++ b/src/components/datepicker/js/datepickerDirective.js
@@ -34,19 +34,18 @@
    * @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
+   * @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.
    * @param {Boolean=} md-is-open Expression that can be used to open the datepicker's calendar
    *  on-demand.
-   * @param {String=} md-current-view Default open view of the calendar pane. Can be either
+   * @param {string=} md-current-view Default open view of the calendar pane. Can be either
    *  "month" or "year".
-   * @param {String=} md-mode Restricts the user to only selecting a value from a particular view.
+   * @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.
-   *
-   * @param {String=} md-hide-icons Determines which datepicker icons should be hidden. Note that
+   * @param {string=} md-hide-icons Determines which datepicker icons should be hidden. Note that
    *  this may cause the datepicker to not align properly with other components.
    *  **Use at your own risk.** Possible values are:
    * * `"all"` - Hides all icons.
@@ -55,6 +54,17 @@
    * @param {Object=} md-date-locale Allows for the values from the `$mdDateLocaleProvider` to be
    * overwritten on a per-element basis (e.g. `msgOpenCalendar` can be overwritten with
    * `md-date-locale="{ msgOpenCalendar: 'Open a special calendar' }"`).
+   * @param {string=} input-aria-describedby A space-separated list of element IDs. This should
+   *  contain the IDs of any elements that describe this datepicker. Screen readers will read the
+   *  content of these elements at the end of announcing that the datepicker has been selected
+   *  and describing its current state. The descriptive elements do not need to be visible on the
+   *  page.
+   * @param {string=} input-aria-labelledby A space-separated list of element IDs. The ideal use
+   *  case is that this would contain the ID of a `<label>` element should be associated with this
+   *  datepicker. This is necessary when using `md-datepicker` inside of an `md-input-container`
+   *  with a `<label>`.<br><br>
+   *  For `<label id="start-date">Start Date</label>`, you would set this to
+   *  `input-aria-labelledby="start-date"`.
    *
    * @description
    * `<md-datepicker>` is a component used to select a single date.
@@ -84,6 +94,8 @@
         // interaction on the text input, and multiple tab stops for one component (picker)
         // may be confusing.
         var hiddenIcons = tAttrs.mdHideIcons;
+        var inputAriaDescribedby = tAttrs.inputAriaDescribedby;
+        var inputAriaLabelledby = tAttrs.inputAriaLabelledby;
         var ariaLabelValue = tAttrs.ariaLabel || tAttrs.mdPlaceholder;
         var ngModelOptions = tAttrs.ngModelOptions;
 
@@ -113,6 +125,8 @@
         '<div class="md-datepicker-input-container" ng-class="{\'md-datepicker-focused\': ctrl.isFocused}">' +
           '<input ' +
             (ariaLabelValue ? 'aria-label="' + ariaLabelValue + '" ' : '') +
+            (inputAriaDescribedby ? 'aria-describedby="' + inputAriaDescribedby + '" ' : '') +
+            (inputAriaLabelledby ? 'aria-labelledby="' + inputAriaLabelledby + '" ' : '') +
             'class="md-datepicker-input" ' +
             'aria-haspopup="dialog" ' +
             'ng-focus="ctrl.setFocused(true)" ' +