From 74e5952ad4d5e168a880bc373e896166b87c2c54 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 15:10:09 -0700
Subject: [PATCH 1/7] fix(tooltip): add accessibility standards (focus show,
 blur hide, aria roles)

---
 src/lib/tooltip/tooltip.html    |  2 ++
 src/lib/tooltip/tooltip.spec.ts | 28 +++++++++++++++++++++++++++-
 src/lib/tooltip/tooltip.ts      | 15 +++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/src/lib/tooltip/tooltip.html b/src/lib/tooltip/tooltip.html
index f4fdd8ff1160..4e57e84441e2 100644
--- a/src/lib/tooltip/tooltip.html
+++ b/src/lib/tooltip/tooltip.html
@@ -1,4 +1,6 @@
 <div class="mat-tooltip"
+     role="tooltip"
+     [id]="id"
      [style.transform-origin]="_transformOrigin"
      [@state]="_visibility"
      (@state.done)="_afterVisibilityAnimation($event)">
diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index 8e5dc8a3a333..f203a7026139 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -10,7 +10,7 @@ import {
   Component,
   DebugElement,
   ViewChild,
-  ChangeDetectionStrategy
+  ChangeDetectionStrategy, ContentChild, ElementRef
 } from '@angular/core';
 import {AnimationEvent} from '@angular/animations';
 import {By} from '@angular/platform-browser';
@@ -366,6 +366,30 @@ describe('MdTooltip', () => {
       expect(tooltipWrapper).toBeTruthy('Expected tooltip to be shown.');
       expect(tooltipWrapper.getAttribute('dir')).toBe('rtl', 'Expected tooltip to be in RTL mode.');
     }));
+
+    it('should associate trigger and tooltip through aria-describedby', fakeAsync(() => {
+      // Expect that the trigger does not have an associated tooltip since there is no tooltip shown
+      const trigger = fixture.componentInstance.trigger.nativeElement;
+      expect(trigger.getAttribute('aria-describedBy')).toBe('');
+
+      tooltipDirective.show(0);
+      tick(0); // Tick for the show delay
+
+      // Tooltip is shown, check that the tooltip's id matches the aria-describedby
+      fixture.detectChanges();
+      expect(tooltipDirective._getTooltipId()).toBe('md-tooltip-0');
+      expect(tooltipDirective._tooltipInstance.id).toBe('md-tooltip-0');
+      expect(trigger.getAttribute('aria-describedBy')).toBe('md-tooltip-0');
+
+      tooltipDirective.hide(0);
+      tick(0); // Tick for the hide delay
+      fixture.detectChanges();
+      flushMicrotasks();
+
+      // Tooltip is hidden again, check that the trigger does not have an aria-describedby
+      expect(tooltipDirective._getTooltipId()).toBe('');
+      expect(trigger.getAttribute('aria-describedBy')).toBe('');
+    }));
   });
 
   describe('scrollable usage', () => {
@@ -467,6 +491,7 @@ describe('MdTooltip', () => {
   selector: 'app',
   template: `
     <button *ngIf="showButton"
+            #trigger
             [mdTooltip]="message"
             [mdTooltipPosition]="position">
       Button
@@ -476,6 +501,7 @@ class BasicTooltipDemo {
   position: string = 'below';
   message: string = initialTooltipMessage;
   showButton: boolean = true;
+  @ViewChild('trigger') trigger: ElementRef;
   @ViewChild(MdTooltip) tooltip: MdTooltip;
 }
 
diff --git a/src/lib/tooltip/tooltip.ts b/src/lib/tooltip/tooltip.ts
index e32e1cb8d589..04fc601a2910 100644
--- a/src/lib/tooltip/tooltip.ts
+++ b/src/lib/tooltip/tooltip.ts
@@ -58,7 +58,11 @@ export function throwMdTooltipInvalidPositionError(position: string) {
   selector: '[md-tooltip], [mdTooltip], [mat-tooltip], [matTooltip]',
   host: {
     '(longpress)': 'show()',
+    '(focus)': 'show()',
+    '(blur)': 'hide(0)',
+    '(keydown.esc)': 'hide(0)',
     '(touchend)': 'hide(' + TOUCHEND_HIDE_DELAY + ')',
+    '[attr.aria-describedby]': '_getTooltipId()'
   },
   exportAs: 'mdTooltip',
 })
@@ -199,6 +203,10 @@ export class MdTooltip implements OnDestroy {
     this._isTooltipVisible() ? this.hide() : this.show();
   }
 
+  _getTooltipId(): string {
+    return this._tooltipInstance ? this._tooltipInstance.id : '';
+  }
+
   /** Returns true if the tooltip is currently visible to the user */
   _isTooltipVisible(): boolean {
     return !!this._tooltipInstance && this._tooltipInstance.isVisible();
@@ -214,6 +222,7 @@ export class MdTooltip implements OnDestroy {
     this._tooltipInstance.afterHidden().subscribe(() => {
       // Check first if the tooltip has already been removed through this components destroy.
       if (this._tooltipInstance) {
+        debugger;
         this._disposeTooltip();
       }
     });
@@ -317,6 +326,9 @@ export class MdTooltip implements OnDestroy {
 
 export type TooltipVisibility = 'initial' | 'visible' | 'hidden';
 
+/** Tooltip IDs need to be unique, so this counter exists outside of the component definition. */
+let _uniqueTooltipIdCounter = 0;
+
 /**
  * Internal component that wraps the tooltip's content.
  * @docs-private
@@ -359,6 +371,9 @@ export class TooltipComponent {
   /** The transform origin used in the animation for showing and hiding the tooltip */
   _transformOrigin: string = 'bottom';
 
+  /** Unique ID to be used by the tooltip trigger's "aria-describedby" property. */
+  id: string = `md-tooltip-${_uniqueTooltipIdCounter++}`;
+
   /** Subject for notifying that the tooltip has been hidden from the view */
   private _onHide: Subject<any> = new Subject();
 

From ca8b92a5adfa432454c570e217cbdaf8f420ee77 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 15:12:06 -0700
Subject: [PATCH 2/7] remove debugger statement

---
 src/lib/tooltip/tooltip.spec.ts | 13 +++++++------
 src/lib/tooltip/tooltip.ts      |  1 -
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index f203a7026139..c0a2255e0f72 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -1,21 +1,22 @@
 import {
   async,
   ComponentFixture,
-  TestBed,
-  tick,
   fakeAsync,
-  flushMicrotasks
+  flushMicrotasks,
+  TestBed,
+  tick
 } from '@angular/core/testing';
 import {
+  ChangeDetectionStrategy,
   Component,
   DebugElement,
-  ViewChild,
-  ChangeDetectionStrategy, ContentChild, ElementRef
+  ElementRef,
+  ViewChild
 } from '@angular/core';
 import {AnimationEvent} from '@angular/animations';
 import {By} from '@angular/platform-browser';
 import {NoopAnimationsModule} from '@angular/platform-browser/animations';
-import {TooltipPosition, MdTooltip, MdTooltipModule, SCROLL_THROTTLE_MS} from './index';
+import {MdTooltip, MdTooltipModule, SCROLL_THROTTLE_MS, TooltipPosition} from './index';
 import {OverlayContainer} from '../core';
 import {Dir, LayoutDirection} from '../core/rtl/dir';
 import {OverlayModule} from '../core/overlay/overlay-directives';
diff --git a/src/lib/tooltip/tooltip.ts b/src/lib/tooltip/tooltip.ts
index 04fc601a2910..489b508d8962 100644
--- a/src/lib/tooltip/tooltip.ts
+++ b/src/lib/tooltip/tooltip.ts
@@ -222,7 +222,6 @@ export class MdTooltip implements OnDestroy {
     this._tooltipInstance.afterHidden().subscribe(() => {
       // Check first if the tooltip has already been removed through this components destroy.
       if (this._tooltipInstance) {
-        debugger;
         this._disposeTooltip();
       }
     });

From 2ca72a786fbab891f988d9975a0ab80df9c20194 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 15:39:15 -0700
Subject: [PATCH 3/7] tests

---
 src/lib/tooltip/tooltip.spec.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index c0a2255e0f72..79cd048de629 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -378,9 +378,9 @@ describe('MdTooltip', () => {
 
       // Tooltip is shown, check that the tooltip's id matches the aria-describedby
       fixture.detectChanges();
-      expect(tooltipDirective._getTooltipId()).toBe('md-tooltip-0');
-      expect(tooltipDirective._tooltipInstance.id).toBe('md-tooltip-0');
-      expect(trigger.getAttribute('aria-describedBy')).toBe('md-tooltip-0');
+      expect(tooltipDirective._getTooltipId()).toContain('md-tooltip-');
+      expect(tooltipDirective._tooltipInstance.id).toContain('md-tooltip-');
+      expect(trigger.getAttribute('aria-describedBy')).toContain('md-tooltip-');
 
       tooltipDirective.hide(0);
       tick(0); // Tick for the hide delay

From a30eab11621abfc0af76555c816e3f246e6d4f08 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 16:10:59 -0700
Subject: [PATCH 4/7] flushing tooltip after each test

---
 src/lib/tooltip/tooltip.spec.ts | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index 79cd048de629..14bfd516e1ea 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -69,6 +69,11 @@ describe('MdTooltip', () => {
       tooltipDirective = buttonDebugElement.injector.get<MdTooltip>(MdTooltip);
     });
 
+    afterEach(() => {
+      fixture.detectChanges();
+      flushMicrotasks();
+    });
+
     it('should show and hide the tooltip', fakeAsync(() => {
       expect(tooltipDirective._tooltipInstance).toBeUndefined();
 
@@ -378,9 +383,9 @@ describe('MdTooltip', () => {
 
       // Tooltip is shown, check that the tooltip's id matches the aria-describedby
       fixture.detectChanges();
-      expect(tooltipDirective._getTooltipId()).toContain('md-tooltip-');
-      expect(tooltipDirective._tooltipInstance.id).toContain('md-tooltip-');
-      expect(trigger.getAttribute('aria-describedBy')).toContain('md-tooltip-');
+      expect(tooltipDirective._getTooltipId()).toBe('md-tooltip-0');
+      expect(tooltipDirective._tooltipInstance.id).toBe('md-tooltip-0');
+      expect(trigger.getAttribute('aria-describedBy')).toBe('md-tooltip-0');
 
       tooltipDirective.hide(0);
       tick(0); // Tick for the hide delay

From d30a360d6dc5e4fadf4b0dab59bc29cd2b0c9e52 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 16:19:40 -0700
Subject: [PATCH 5/7] fix tests

---
 src/lib/tooltip/tooltip.spec.ts | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index 14bfd516e1ea..95d65a1daeec 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -27,7 +27,7 @@ import {dispatchFakeEvent} from '../core/testing/dispatch-events';
 
 const initialTooltipMessage = 'initial tooltip message';
 
-describe('MdTooltip', () => {
+fdescribe('MdTooltip', () => {
   let overlayContainerElement: HTMLElement;
   let dir: {value: LayoutDirection};
 
@@ -69,11 +69,6 @@ describe('MdTooltip', () => {
       tooltipDirective = buttonDebugElement.injector.get<MdTooltip>(MdTooltip);
     });
 
-    afterEach(() => {
-      fixture.detectChanges();
-      flushMicrotasks();
-    });
-
     it('should show and hide the tooltip', fakeAsync(() => {
       expect(tooltipDirective._tooltipInstance).toBeUndefined();
 
@@ -383,14 +378,17 @@ describe('MdTooltip', () => {
 
       // Tooltip is shown, check that the tooltip's id matches the aria-describedby
       fixture.detectChanges();
-      expect(tooltipDirective._getTooltipId()).toBe('md-tooltip-0');
-      expect(tooltipDirective._tooltipInstance.id).toBe('md-tooltip-0');
-      expect(trigger.getAttribute('aria-describedBy')).toBe('md-tooltip-0');
+      expect(tooltipDirective._getTooltipId()).toContain('md-tooltip-');
+      expect(tooltipDirective._tooltipInstance.id).toContain('md-tooltip-');
+      expect(trigger.getAttribute('aria-describedBy')).toContain('md-tooltip-');
 
       tooltipDirective.hide(0);
       tick(0); // Tick for the hide delay
       fixture.detectChanges();
+
+      // Let animation play out and resolve to remove the tooltip
       flushMicrotasks();
+      fixture.detectChanges();
 
       // Tooltip is hidden again, check that the trigger does not have an aria-describedby
       expect(tooltipDirective._getTooltipId()).toBe('');

From a33eb3a964c9559fb01e21360acca66dafcaf632 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 16:26:50 -0700
Subject: [PATCH 6/7] remove fdescribe

---
 src/lib/tooltip/tooltip.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index 95d65a1daeec..aa7bfeeda31e 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -27,7 +27,7 @@ import {dispatchFakeEvent} from '../core/testing/dispatch-events';
 
 const initialTooltipMessage = 'initial tooltip message';
 
-fdescribe('MdTooltip', () => {
+describe('MdTooltip', () => {
   let overlayContainerElement: HTMLElement;
   let dir: {value: LayoutDirection};
 

From b1fee0118612a533b3128b5ec66e1da80ca74218 Mon Sep 17 00:00:00 2001
From: Andrew Seguin <andrewjs@google.com>
Date: Fri, 19 May 2017 17:18:27 -0700
Subject: [PATCH 7/7] changes to aria-describedby

---
 src/lib/tooltip/tooltip.spec.ts |  2 +-
 src/lib/tooltip/tooltip.ts      | 83 +++++++++++++++++++++------------
 2 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/src/lib/tooltip/tooltip.spec.ts b/src/lib/tooltip/tooltip.spec.ts
index aa7bfeeda31e..eb5153ccaa23 100644
--- a/src/lib/tooltip/tooltip.spec.ts
+++ b/src/lib/tooltip/tooltip.spec.ts
@@ -371,7 +371,7 @@ describe('MdTooltip', () => {
     it('should associate trigger and tooltip through aria-describedby', fakeAsync(() => {
       // Expect that the trigger does not have an associated tooltip since there is no tooltip shown
       const trigger = fixture.componentInstance.trigger.nativeElement;
-      expect(trigger.getAttribute('aria-describedBy')).toBe('');
+      expect(trigger.getAttribute('aria-describedBy')).toBe(null);
 
       tooltipDirective.show(0);
       tick(0); // Tick for the show delay
diff --git a/src/lib/tooltip/tooltip.ts b/src/lib/tooltip/tooltip.ts
index 489b508d8962..3959d92b2309 100644
--- a/src/lib/tooltip/tooltip.ts
+++ b/src/lib/tooltip/tooltip.ts
@@ -1,31 +1,24 @@
 import {
+  ChangeDetectorRef,
   Component,
   Directive,
-  Input,
   ElementRef,
-  ViewContainerRef,
+  Input,
   NgZone,
-  Optional,
   OnDestroy,
+  Optional,
   Renderer2,
-  ChangeDetectorRef,
+  ViewContainerRef
 } from '@angular/core';
+import {animate, AnimationEvent, state, style, transition, trigger} from '@angular/animations';
 import {
-  style,
-  trigger,
-  state,
-  transition,
-  animate,
-  AnimationEvent,
-} from '@angular/animations';
-import {
-  Overlay,
-  OverlayState,
-  OverlayRef,
   ComponentPortal,
-  OverlayConnectionPosition,
   OriginConnectionPosition,
-  RepositionScrollStrategy,
+  Overlay,
+  OverlayConnectionPosition,
+  OverlayRef,
+  OverlayState,
+  RepositionScrollStrategy
 } from '../core';
 import {Observable} from 'rxjs/Observable';
 import {Subject} from 'rxjs/Subject';
@@ -34,6 +27,7 @@ import {Platform} from '../core/platform/index';
 import 'rxjs/add/operator/first';
 import {ScrollDispatcher} from '../core/overlay/scroll/scroll-dispatcher';
 import {coerceBooleanProperty} from '../core/coercion/boolean-property';
+import {ESCAPE} from '../core/keyboard/keycodes';
 
 export type TooltipPosition = 'left' | 'right' | 'above' | 'below' | 'before' | 'after';
 
@@ -60,9 +54,8 @@ export function throwMdTooltipInvalidPositionError(position: string) {
     '(longpress)': 'show()',
     '(focus)': 'show()',
     '(blur)': 'hide(0)',
-    '(keydown.esc)': 'hide(0)',
+    '(keydown)': '_handleKeydown($event)',
     '(touchend)': 'hide(' + TOUCHEND_HIDE_DELAY + ')',
-    '[attr.aria-describedby]': '_getTooltipId()'
   },
   exportAs: 'mdTooltip',
 })
@@ -153,15 +146,14 @@ export class MdTooltip implements OnDestroy {
   set _matShowDelay(v) { this.showDelay = v; }
 
   constructor(
-    private _overlay: Overlay,
-    private _elementRef: ElementRef,
-    private _scrollDispatcher: ScrollDispatcher,
-    private _viewContainerRef: ViewContainerRef,
-    private _ngZone: NgZone,
-    private _renderer: Renderer2,
-    private _platform: Platform,
-    @Optional() private _dir: Dir) {
-
+      private _overlay: Overlay,
+      private _elementRef: ElementRef,
+      private _scrollDispatcher: ScrollDispatcher,
+      private _viewContainerRef: ViewContainerRef,
+      private _ngZone: NgZone,
+      private _renderer: Renderer2,
+      private _platform: Platform,
+      @Optional() private _dir: Dir) {
     // The mouse events shouldn't be bound on iOS devices, because
     // they can prevent the first tap from firing its click event.
     if (!_platform.IOS) {
@@ -170,9 +162,7 @@ export class MdTooltip implements OnDestroy {
     }
   }
 
-  /**
-   * Dispose the tooltip when destroyed.
-   */
+  /** Dispose the tooltip when destroyed. */
   ngOnDestroy() {
     if (this._tooltipInstance) {
       this._disposeTooltip();
@@ -187,6 +177,11 @@ export class MdTooltip implements OnDestroy {
       this._createTooltip();
     }
 
+    // If the user has not already set an aria-describedby, then use the tooltip's id.
+    if (!this._getAriaDescribedby()) {
+      this._setAriaDescribedBy(this._tooltipInstance.id);
+    }
+
     this._setTooltipMessage(this._message);
     this._tooltipInstance.show(this._position, delay);
   }
@@ -194,6 +189,11 @@ export class MdTooltip implements OnDestroy {
   /** Hides the tooltip after the delay in ms, defaults to tooltip-delay-hide or 0ms if no input */
   hide(delay: number = this.hideDelay): void {
     if (this._tooltipInstance) {
+      // Remove the aria-describedby attribute if it matches the now-hidden tooltip's id
+      if (this._getAriaDescribedby() === this._tooltipInstance.id) {
+        this._setAriaDescribedBy('');
+      }
+
       this._tooltipInstance.hide(delay);
     }
   }
@@ -212,6 +212,27 @@ export class MdTooltip implements OnDestroy {
     return !!this._tooltipInstance && this._tooltipInstance.isVisible();
   }
 
+  /** Handles the keydown events on the host element. */
+  _handleKeydown(e: KeyboardEvent) {
+    // If the tooltip is visible and the user pressed escape,
+    // intercept the event and hide the tooltip.
+    if (this._tooltipInstance && this._tooltipInstance.isVisible() && e.keyCode === ESCAPE) {
+      e.stopPropagation();
+      this.hide(0);
+    }
+  }
+
+  /** Returns the trigger's aria-describedby attribute. */
+  private _getAriaDescribedby(): string {
+    return this._elementRef.nativeElement.getAttribute('aria-describedby');
+  }
+
+  /** Sets the trigger's aria-describedby attribute. */
+  private _setAriaDescribedBy(ariaDescribedby: string) {
+    this._renderer.setAttribute(
+        this._elementRef.nativeElement, 'aria-describedby', ariaDescribedby);
+  }
+
   /** Create the tooltip to display */
   private _createTooltip(): void {
     this._createOverlay();