fix(autocomplete): announce when an item is selected from the dropdown (#11403)

make sure that this message can be overridden in non-English locales
fix some lint warnings and style issues
add and fix JSDoc

Fixes #10837

Author: Splaktar

src/components/autocomplete/autocomplete.spec.js

@@ -1733,15 +1733,41 @@ describe('<md-autocomplete>', function() {
 
       ctrl.keydown(keydownEvent($mdConstant.KEY_CODE.DOWN_ARROW));
 
-      // Flush twice, because the display value will be resolved asynchronously and then the live-announcer will
-      // be triggered.
+      // Flush twice, because the display value will be resolved asynchronously and then the
+      // live-announcer will be triggered.
       $timeout.flush();
       $timeout.flush();
 
       expect(ctrl.index).toBe(1);
       expect(liveEl.textContent).toBe(scope.items[1].display);
     });
 
+    it('should announce when an option is selected', function() {
+      ctrl.focus();
+      waitForVirtualRepeat();
+
+      expect(ctrl.hidden).toBe(false);
+
+      ctrl.keydown(keydownEvent($mdConstant.KEY_CODE.DOWN_ARROW));
+
+      // Flush twice, because the display value will be resolved asynchronously and then the
+      // live-announcer will be triggered.
+      $timeout.flush();
+      $timeout.flush();
+
+      expect(ctrl.index).toBe(0);
+      expect(liveEl.textContent).toBe(scope.items[0].display);
+
+      ctrl.keydown(keydownEvent($mdConstant.KEY_CODE.ENTER));
+
+      // Flush twice, because the display value will be resolved asynchronously and then the
+      // live-announcer will be triggered.
+      $timeout.flush();
+      $timeout.flush();
+
+      expect(liveEl.textContent).toBe(scope.items[0].display + ' ' + ctrl.selectedMessage);
+    });
+
     it('should announce the count when matches change', function() {
 
       ctrl.focus();

src/components/autocomplete/demoBasicUsage/index.html

@@ -25,8 +25,11 @@
       <md-checkbox ng-model="ctrl.simulateQuery">Simulate query for results?</md-checkbox>
       <md-checkbox ng-model="ctrl.noCache">Disable caching of queries?</md-checkbox>
       <md-checkbox ng-model="ctrl.isDisabled">Disable the input?</md-checkbox>
-
-      <p>By default, <code>md-autocomplete</code> will cache results when performing a query.  After the initial call is performed, it will use the cached results to eliminate unnecessary server requests or lookup logic. This can be disabled above.</p>
+      <p>
+        By default, <code>md-autocomplete</code> will cache results when performing a query.
+        After the initial call is performed, it will use the cached results to eliminate unnecessary
+        server requests or lookup logic. This can be disabled above.
+      </p>
     </form>
   </md-content>
 </div>

src/components/autocomplete/js/autocompleteController.js

@@ -40,6 +40,7 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
   ctrl.isRequired = null;
   ctrl.isReadonly = null;
   ctrl.hasNotFound = false;
+  ctrl.selectedMessage = $scope.selectedMessage || 'selected';
 
   // Public Exported Methods
   ctrl.keydown                       = keydown;
@@ -321,8 +322,8 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
     if (!hidden && oldHidden) {
       positionDropdown();
 
-      // Report in polite mode, because the screenreader should finish the default description of
-      // the input. element.
+      // Report in polite mode, because the screen reader should finish the default description of
+      // the input element.
       reportMessages(true, ReportType.Count | ReportType.Selected);
 
       if (elements) {
@@ -406,14 +407,17 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
       });
     }
 
-    if (selectedItem !== previousSelectedItem) announceItemChange();
+    if (selectedItem !== previousSelectedItem) {
+      announceItemChange();
+    }
   }
 
   /**
    * Use the user-defined expression to announce changes each time a new item is selected
    */
   function announceItemChange () {
-    angular.isFunction($scope.itemChange) && $scope.itemChange(getItemAsNameVal($scope.selectedItem));
+    angular.isFunction($scope.itemChange) &&
+      $scope.itemChange(getItemAsNameVal($scope.selectedItem));
   }
 
   /**
@@ -430,15 +434,17 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
    * @param previousSelectedItem
    */
   function handleSelectedItemChange (selectedItem, previousSelectedItem) {
-    selectedItemWatchers.forEach(function (watcher) { watcher(selectedItem, previousSelectedItem); });
+    selectedItemWatchers.forEach(function (watcher) {
+      watcher(selectedItem, previousSelectedItem);
+    });
   }
 
   /**
    * Register a function to be called when the selected item changes.
    * @param cb
    */
   function registerSelectedItemWatcher (cb) {
-    if (selectedItemWatchers.indexOf(cb) == -1) {
+    if (selectedItemWatchers.indexOf(cb) === -1) {
       selectedItemWatchers.push(cb);
     }
   }
@@ -449,7 +455,7 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
    */
   function unregisterSelectedItemWatcher (cb) {
     var i = selectedItemWatchers.indexOf(cb);
-    if (i != -1) {
+    if (i !== -1) {
       selectedItemWatchers.splice(i, 1);
     }
   }
@@ -472,9 +478,10 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
       if (searchText !== val) {
         $scope.selectedItem = null;
 
-
         // trigger change event if available
-        if (searchText !== previousSearchText) announceTextChange();
+        if (searchText !== previousSearchText) {
+          announceTextChange();
+        }
 
         // cancel results if search text is not long enough
         if (!isMinLengthMet()) {
@@ -617,6 +624,8 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
     /**
      * Getter function to invoke user-defined expression (in the directive)
      * to convert your object to a single string.
+     * @param item
+     * @returns {string|null}
      */
     function getItemText (item) {
       return (item && $scope.itemText) ? $scope.itemText(getItemAsNameVal(item)) : null;
@@ -626,20 +635,24 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
   /**
    * Returns the locals object for compiling item templates.
    * @param item
-   * @returns {{}}
+   * @returns {Object|undefined}
    */
   function getItemAsNameVal (item) {
-    if (!item) return undefined;
+    if (!item) {
+      return undefined;
+    }
 
     var locals = {};
-    if (ctrl.itemName) locals[ ctrl.itemName ] = item;
+    if (ctrl.itemName) {
+      locals[ ctrl.itemName ] = item;
+    }
 
     return locals;
   }
 
   /**
    * Returns the default index based on whether or not autoselect is enabled.
-   * @returns {number}
+   * @returns {number} 0 if autoselect is enabled, -1 if not.
    */
   function getDefaultIndex () {
     return $scope.autoselect ? 0 : -1;
@@ -650,7 +663,7 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
    * @param value {boolean} Whether or not the component is currently loading.
    */
   function setLoading(value) {
-    if (ctrl.loading != value) {
+    if (ctrl.loading !== value) {
       ctrl.loading = value;
     }
 
@@ -718,40 +731,36 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
   }
 
   /**
-   * Returns true if the search text has matches.
-   * @returns {boolean}
+   * @returns {boolean} true if the search text has matches.
    */
   function hasMatches() {
     return ctrl.matches.length ? true : false;
   }
 
   /**
-   * Returns true if the autocomplete has a valid selection.
-   * @returns {boolean}
+   * @returns {boolean} true if the autocomplete has a valid selection.
    */
   function hasSelection() {
     return ctrl.scope.selectedItem ? true : false;
   }
 
   /**
-   * Returns true if the loading indicator is, or should be, visible.
-   * @returns {boolean}
+   * @returns {boolean} true if the loading indicator is, or should be, visible.
    */
   function loadingIsVisible() {
     return ctrl.loading && !hasSelection();
   }
 
   /**
-   * Returns the display value of the current item.
-   * @returns {*}
+   * @returns {*} the display value of the current item.
    */
   function getCurrentDisplayValue () {
     return getDisplayValue(ctrl.matches[ ctrl.index ]);
   }
 
   /**
    * Determines if the minimum length is met by the search text.
-   * @returns {*}
+   * @returns {*} true if the minimum length is met by the search text
    */
   function isMinLengthMet () {
     return ($scope.searchText || '').length >= getMinLength();
@@ -761,9 +770,9 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
 
   /**
    * Defines a public property with a handler and a default value.
-   * @param key
-   * @param handler
-   * @param value
+   * @param {string} key
+   * @param {Function} handler function
+   * @param {*} value default value
    */
   function defineProperty (key, handler, value) {
     Object.defineProperty(ctrl, key, {
@@ -778,13 +787,14 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
 
   /**
    * Selects the item at the given index.
-   * @param index
+   * @param {number} index to select
    */
   function select (index) {
     //-- force form to update state for validation
     $mdUtil.nextTick(function () {
       getDisplayValue(ctrl.matches[ index ]).then(function (val) {
         var ngModel = elements.$.input.controller('ngModel');
+        $mdLiveAnnouncer.announce(val + ' ' + ctrl.selectedMessage, 'assertive');
         ngModel.$setViewValue(val);
         ngModel.$render();
       }).finally(function () {
@@ -884,12 +894,11 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
 
 
   /**
-   * Reports given message types to supported screenreaders.
+   * Reports given message types to supported screen readers.
    * @param {boolean} isPolite Whether the announcement should be polite.
-   * @param {!number} types Message flags to be reported to the screenreader.
+   * @param {!number} types Message flags to be reported to the screen reader.
    */
   function reportMessages(isPolite, types) {
-
     var politeness = isPolite ? 'polite' : 'assertive';
     var messages = [];
 
@@ -904,12 +913,10 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
     $q.all(messages).then(function(data) {
       $mdLiveAnnouncer.announce(data.join(' '), politeness);
     });
-
   }
 
   /**
-   * Returns the ARIA message for how many results match the current query.
-   * @returns {*}
+   * @returns {string} the ARIA message for how many results match the current query.
    */
   function getCountMessage () {
     switch (ctrl.matches.length) {
@@ -1000,12 +1007,14 @@ function MdAutocompleteCtrl ($scope, $element, $mdUtil, $mdConstant, $mdTheming,
         matches    = ctrl.matches,
         item       = matches[ 0 ];
     if (matches.length === 1) getDisplayValue(item).then(function (displayValue) {
-      var isMatching = searchText == displayValue;
+      var isMatching = searchText === displayValue;
       if ($scope.matchInsensitive && !isMatching) {
-        isMatching = searchText.toLowerCase() == displayValue.toLowerCase();
+        isMatching = searchText.toLowerCase() === displayValue.toLowerCase();
       }
 
-      if (isMatching) select(0);
+      if (isMatching) {
+        select(0);
+      }
     });
   }
 

src/components/autocomplete/js/autocompleteDirective.js

@@ -128,7 +128,12 @@ angular
  *     the dropdown.<br/><br/>
  *     When the dropdown doesn't fit into the viewport, the dropdown will shrink
  *     as much as possible.
- * @param {string=} md-dropdown-position Overrides the default dropdown position. Options: `top`, `bottom`.
+ * @param {string=} md-dropdown-position Overrides the default dropdown position. Options: `top`,
+ *    `bottom`.
+ * @param {string=} md-selected-message Attribute to specify the text that the screen reader will
+ *    announce after a value is selected. Default is: "selected". If `Alaska` is selected in the
+ *    options panel, it will read "Alaska selected". You will want to override this when your app
+ *    is running in a non-English locale.
  * @param {boolean=} ng-trim If set to false, the search text will be not trimmed automatically.
  *     Defaults to true.
  * @param {string=} ng-pattern Adds the pattern validator to the ngModel of the search text.
@@ -272,7 +277,8 @@ function MdAutocomplete ($$mdSvgRegistry) {
       escapeOptions:      '@?mdEscapeOptions',
       dropdownItems:      '=?mdDropdownItems',
       dropdownPosition:   '@?mdDropdownPosition',
-      clearButton:        '=?mdClearButton'
+      clearButton:        '=?mdClearButton',
+      selectedMessage:    '@?mdSelectedMessage'
     },
     compile: function(tElement, tAttrs) {
       var attributes = ['md-select-on-focus', 'md-no-asterisk', 'ng-trim', 'ng-pattern'];