fix(select): md-focused not removed from options on panel close

- add tests for select menu options' focus decoration
- improve some JSDoc for interimElement

Fixes #11927

Author: Splaktar

src/components/select/select.js

@@ -1884,6 +1884,7 @@ function SelectProvider($$interimElementProvider) {
 
               $mdUtil.nextTick(function () {
                 $mdSelect.hide(selectMenuController.ngModel.$viewValue);
+                opts.focusedNode.classList.remove('md-focused');
               }, true);
             }
           }

src/components/select/select.spec.js

@@ -267,17 +267,77 @@ describe('<md-select>', function() {
       var select = setupSelect('ng-model="val"').find('md-select');
       openSelect(select);
 
-      $document[0].body.appendChild(select[0]);
+      body.appendChild(select[0]);
 
       var selectMenu = $document.find('md-select-menu');
+      // Dismiss the menu with the Escape key.
       pressKeyByCode(selectMenu, 27);
       $material.flushInterimElement();
 
       // FIXME- does not work with minified, jquery
       // expect($document[0].activeElement).toBe(select[0]);
 
       // Clean up the DOM after the test.
-      $document[0].body.removeChild(select[0]);
+      body.removeChild(select[0]);
+    });
+
+    it('auto focuses option in the list when opened', function() {
+      var select = setupSelect('ng-model="val"', ['One']).find('md-select');
+      openSelect(select);
+
+      body.appendChild(select[0]);
+
+      var selectMenu = $document.find('md-select-menu');
+      var mdOption = selectMenu.find('md-option');
+      expect(mdOption[0].classList.contains('md-focused')).toBeTruthy();
+
+      // Clean up the DOM after the test.
+      body.removeChild(select[0]);
+    });
+
+    it('changes focus decoration on selection change by keyboard', function() {
+      var select = setupSelect('ng-model="val"', ['One', 'Two']).find('md-select');
+      openSelect(select);
+
+      body.appendChild(select[0]);
+
+      var selectMenu = $document.find('md-select-menu');
+      var mdOption = selectMenu.find('md-option');
+      expect(mdOption[0].classList.contains('md-focused')).toBeTruthy();
+
+      // Select the second option using the down arrow key.
+      pressKeyByCode(selectMenu, 40);
+      expect(mdOption[0].classList.contains('md-focused')).toBeFalsy();
+      expect(mdOption[1].classList.contains('md-focused')).toBeTruthy();
+      $material.flushInterimElement();
+
+      // Clean up the DOM after the test.
+      body.removeChild(select[0]);
+    });
+
+    it('removes md-focused from first option when second option is clicked', function() {
+      var select = setupSelect('ng-model="val"', ['One', 'Two']).find('md-select');
+      openSelect(select);
+
+      body.appendChild(select[0]);
+
+      var selectMenu = $document.find('md-select-menu');
+      var mdOption = selectMenu.find('md-option');
+      expect(mdOption[0].classList.contains('md-focused')).toBeTruthy();
+
+      clickOption(select, 1);
+      $material.flushInterimElement();
+      expect(mdOption[0].classList.contains('md-focused')).toBeFalsy();
+      expect(mdOption[1].classList.contains('md-focused')).toBeFalsy();
+
+      openSelect(select);
+      selectMenu = $document.find('md-select-menu');
+      mdOption = selectMenu.find('md-option');
+      expect(mdOption[0].classList.contains('md-focused')).toBeFalsy();
+      expect(mdOption[1].classList.contains('md-focused')).toBeTruthy();
+
+      // Clean up the DOM after the test.
+      body.removeChild(select[0]);
     });
 
     it('should remove the input-container focus state', function() {

src/core/services/interimElement/interimElement.js

@@ -339,17 +339,17 @@ function InterimElementProvider() {
         return interimElement.deferred.promise;
       }
 
-      /*
+      /**
        * @ngdoc method
        * @name $$interimElement.$service#hide
        * @kind function
        *
        * @description
-       * Removes the `$interimElement` from the DOM and resolves the promise returned from `show`
-       *
-       * @param {*} resolveParam Data to resolve the promise with
-       * @returns a Promise that will be resolved after the element has been removed.
+       * Removes the `$interimElement` from the DOM and resolves the promise returned from `show`.
        *
+       * @param {*} reason Data to resolve the promise with
+       * @param {object} options
+       * @returns {Promise} a Promise that will be resolved after the element has been removed.
        */
       function hide(reason, options) {
         options = options || {};
@@ -364,8 +364,11 @@ function InterimElementProvider() {
         // Hide the latest showing interim element.
         return closeElement(showingInterims[showingInterims.length - 1]);
 
+        /**
+         * @param {InterimElement} interim element to close
+         * @returns {Promise<InterimElement>}
+         */
         function closeElement(interim) {
-
           if (!interim) {
             return $q.when(reason);
           }
@@ -384,7 +387,7 @@ function InterimElementProvider() {
         }
       }
 
-      /*
+      /**
        * @ngdoc method
        * @name $$interimElement.$service#cancel
        * @kind function
@@ -393,8 +396,8 @@ function InterimElementProvider() {
        * Removes the `$interimElement` from the DOM and rejects the promise returned from `show`
        *
        * @param {*} reason Data to reject the promise with
-       * @returns Promise that will be resolved after the element has been removed.
-       *
+       * @param {object} options
+       * @returns {Promise} Promise that will be resolved after the element has been removed.
        */
       function cancel(reason, options) {
         var interim = showingInterims.pop();