fix(material/tooltip): not closing when scrolling away using mouse wheel (#19735)

We depend on the `mouseleave` event to close the tooltip, but it won't fire
if the user scrolls away without moving their mouse. These changes add
some logic so the tooltip is closed if a `wheel` event resulted in the cursor
leaving the trigger.

Fixes #18611.

Author: crisbeto

src/material/tooltip/tooltip.spec.ts

@@ -29,6 +29,7 @@ import {
   dispatchMouseEvent,
   createKeyboardEvent,
   dispatchEvent,
+  createFakeEvent,
 } from '@angular/cdk/testing/private';
 import {ESCAPE} from '@angular/cdk/keycodes';
 import {FocusMonitor} from '@angular/cdk/a11y';
@@ -48,13 +49,10 @@ describe('MatTooltip', () => {
   let overlayContainer: OverlayContainer;
   let overlayContainerElement: HTMLElement;
   let dir: {value: Direction};
-  let platform: {IOS: boolean, isBrowser: boolean, ANDROID: boolean};
+  let platform: Platform;
   let focusMonitor: FocusMonitor;
 
   beforeEach(waitForAsync(() => {
-    // Set the default Platform override that can be updated before component creation.
-    platform = {IOS: false, isBrowser: true, ANDROID: false};
-
     TestBed.configureTestingModule({
       imports: [MatTooltipModule, OverlayModule, NoopAnimationsModule],
       declarations: [
@@ -67,7 +65,6 @@ describe('MatTooltip', () => {
         DataBoundAriaLabelTooltip,
       ],
       providers: [
-        {provide: Platform, useFactory: () => platform},
         {provide: Directionality, useFactory: () => {
           return dir = {value: 'ltr'};
         }}
@@ -76,11 +73,13 @@ describe('MatTooltip', () => {
 
     TestBed.compileComponents();
 
-    inject([OverlayContainer, FocusMonitor], (oc: OverlayContainer, fm: FocusMonitor) => {
-      overlayContainer = oc;
-      overlayContainerElement = oc.getContainerElement();
-      focusMonitor = fm;
-    })();
+    inject([OverlayContainer, FocusMonitor, Platform],
+      (oc: OverlayContainer, fm: FocusMonitor, pl: Platform) => {
+        overlayContainer = oc;
+        overlayContainerElement = oc.getContainerElement();
+        focusMonitor = fm;
+        platform = pl;
+      })();
   }));
 
   afterEach(inject([OverlayContainer], (currentOverlayContainer: OverlayContainer) => {
@@ -886,6 +885,11 @@ describe('MatTooltip', () => {
     }));
 
     it('should have rendered the tooltip text on init', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
       dispatchFakeEvent(buttonElement, 'mouseenter');
       fixture.detectChanges();
       tick(0);
@@ -1089,6 +1093,75 @@ describe('MatTooltip', () => {
     });
   });
 
+  describe('mouse wheel handling', () => {
+    it('should close when a wheel event causes the cursor to leave the trigger', fakeAsync(() => {
+      // We don't bind wheel events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      const fixture = TestBed.createComponent(BasicTooltipDemo);
+      fixture.detectChanges();
+      const button: HTMLButtonElement = fixture.nativeElement.querySelector('button');
+
+      dispatchFakeEvent(button, 'mouseenter');
+      fixture.detectChanges();
+      tick(500); // Finish the open delay.
+      fixture.detectChanges();
+      tick(500); // Finish the animation.
+      assertTooltipInstance(fixture.componentInstance.tooltip, true);
+
+      // Simulate the pointer at the bottom/right of the page.
+      const wheelEvent = createFakeEvent('wheel');
+      Object.defineProperties(wheelEvent, {
+        clientX: {get: () => window.innerWidth},
+        clientY: {get: () => window.innerHeight}
+      });
+
+      dispatchEvent(button, wheelEvent);
+      fixture.detectChanges();
+      tick(1500); // Finish the delay.
+      fixture.detectChanges();
+      tick(500); // Finish the exit animation.
+
+      assertTooltipInstance(fixture.componentInstance.tooltip, false);
+    }));
+
+    it('should not close if the cursor is over the trigger after a wheel event', fakeAsync(() => {
+      // We don't bind wheel events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      const fixture = TestBed.createComponent(BasicTooltipDemo);
+      fixture.detectChanges();
+      const button: HTMLButtonElement = fixture.nativeElement.querySelector('button');
+
+      dispatchFakeEvent(button, 'mouseenter');
+      fixture.detectChanges();
+      tick(500); // Finish the open delay.
+      fixture.detectChanges();
+      tick(500); // Finish the animation.
+      assertTooltipInstance(fixture.componentInstance.tooltip, true);
+
+      // Simulate the pointer over the trigger.
+      const triggerRect = button.getBoundingClientRect();
+      const wheelEvent = createFakeEvent('wheel');
+      Object.defineProperties(wheelEvent, {
+        clientX: {get: () => triggerRect.left + 1},
+        clientY: {get: () => triggerRect.top + 1}
+      });
+
+      dispatchEvent(button, wheelEvent);
+      fixture.detectChanges();
+      tick(1500); // Finish the delay.
+      fixture.detectChanges();
+      tick(500); // Finish the exit animation.
+
+      assertTooltipInstance(fixture.componentInstance.tooltip, true);
+    }));
+  });
+
 });
 
 @Component({

src/material/tooltip/tooltip.ts

@@ -40,6 +40,7 @@ import {
   ViewEncapsulation,
   AfterViewInit,
 } from '@angular/core';
+import {DOCUMENT} from '@angular/common';
 import {Observable, Subject} from 'rxjs';
 import {take, takeUntil} from 'rxjs/operators';
 
@@ -245,6 +246,12 @@ export class MatTooltip implements OnDestroy, AfterViewInit {
   private readonly _passiveListeners:
       (readonly [string, EventListenerOrEventListenerObject])[] = [];
 
+  /**
+   * Reference to the current document.
+   * @breaking-change 11.0.0 Remove `| null` typing for `document`.
+   */
+  private _document: Document | null;
+
   /** Timer started at the last `touchstart` event. */
   private _touchstartTimeout: number;
 
@@ -263,7 +270,10 @@ export class MatTooltip implements OnDestroy, AfterViewInit {
     @Inject(MAT_TOOLTIP_SCROLL_STRATEGY) scrollStrategy: any,
     @Optional() private _dir: Directionality,
     @Optional() @Inject(MAT_TOOLTIP_DEFAULT_OPTIONS)
-      private _defaultOptions: MatTooltipDefaultOptions) {
+      private _defaultOptions: MatTooltipDefaultOptions,
+
+    /** @breaking-change 11.0.0 _document argument to become required. */
+    @Inject(DOCUMENT) _document: any) {
 
     this._scrollStrategy = scrollStrategy;
 
@@ -590,7 +600,10 @@ export class MatTooltip implements OnDestroy, AfterViewInit {
 
     const exitListeners: (readonly [string, EventListenerOrEventListenerObject])[] = [];
     if (this._platformSupportsMouseEvents()) {
-      exitListeners.push(['mouseleave', () => this.hide()]);
+      exitListeners.push(
+        ['mouseleave', () => this.hide()],
+        ['wheel', event => this._wheelListener(event as WheelEvent)]
+      );
     } else if (this.touchGestures !== 'off') {
       this._disableNativeGesturesIfNecessary();
       const touchendListener = () => {
@@ -619,6 +632,24 @@ export class MatTooltip implements OnDestroy, AfterViewInit {
     return !this._platform.IOS && !this._platform.ANDROID;
   }
 
+  /** Listener for the `wheel` event on the element. */
+  private _wheelListener(event: WheelEvent) {
+    if (this._isTooltipVisible()) {
+      // @breaking-change 11.0.0 Remove `|| document` once the document is a required param.
+      const doc = this._document || document;
+      const elementUnderPointer = doc.elementFromPoint(event.clientX, event.clientY);
+      const element = this._elementRef.nativeElement;
+
+      // On non-touch devices we depend on the `mouseleave` event to close the tooltip, but it
+      // won't fire if the user scrolls away using the wheel without moving their cursor. We
+      // work around it by finding the element under the user's cursor and closing the tooltip
+      // if it's not the trigger.
+      if (elementUnderPointer !== element && !element.contains(elementUnderPointer)) {
+        this.hide();
+      }
+    }
+  }
+
   /** Disables the native browser gestures, based on how the tooltip has been configured. */
   private _disableNativeGesturesIfNecessary() {
     const gestures = this.touchGestures;

tools/public_api_guard/material/tooltip.d.ts

@@ -32,7 +32,8 @@ export declare class MatTooltip implements OnDestroy, AfterViewInit {
         [key: string]: any;
     });
     touchGestures: TooltipTouchGestures;
-    constructor(_overlay: Overlay, _elementRef: ElementRef<HTMLElement>, _scrollDispatcher: ScrollDispatcher, _viewContainerRef: ViewContainerRef, _ngZone: NgZone, _platform: Platform, _ariaDescriber: AriaDescriber, _focusMonitor: FocusMonitor, scrollStrategy: any, _dir: Directionality, _defaultOptions: MatTooltipDefaultOptions);
+    constructor(_overlay: Overlay, _elementRef: ElementRef<HTMLElement>, _scrollDispatcher: ScrollDispatcher, _viewContainerRef: ViewContainerRef, _ngZone: NgZone, _platform: Platform, _ariaDescriber: AriaDescriber, _focusMonitor: FocusMonitor, scrollStrategy: any, _dir: Directionality, _defaultOptions: MatTooltipDefaultOptions,
+    _document: any);
     _getOrigin(): {
         main: OriginConnectionPosition;
         fallback: OriginConnectionPosition;
@@ -51,7 +52,7 @@ export declare class MatTooltip implements OnDestroy, AfterViewInit {
     static ngAcceptInputType_hideDelay: NumberInput;
     static ngAcceptInputType_showDelay: NumberInput;
     static ɵdir: i0.ɵɵDirectiveDefWithMeta<MatTooltip, "[matTooltip]", ["matTooltip"], { "position": "matTooltipPosition"; "disabled": "matTooltipDisabled"; "showDelay": "matTooltipShowDelay"; "hideDelay": "matTooltipHideDelay"; "touchGestures": "matTooltipTouchGestures"; "message": "matTooltip"; "tooltipClass": "matTooltipClass"; }, {}, never>;
-    static ɵfac: i0.ɵɵFactoryDef<MatTooltip, [null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDef<MatTooltip, [null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }, null]>;
 }
 
 export declare const matTooltipAnimations: {