fix(material/tooltip): don't hide when pointer moves to tooltip

Currently we hide the tooltip as soon as the pointer leaves the trigger element which may be problematic with larger cursors that partially obstruct the content.

These changes allow hover events on the tooltip and add extra logic so that moving to it doesn't start the hiding sequence.

Fixes #4942.

Author: crisbeto

src/material-experimental/mdc-tooltip/tooltip.scss

@@ -4,11 +4,18 @@
 @include tooltip.core-styles($query: structure);
 
 .mat-mdc-tooltip {
-  // We don't use MDC's positioning so this has to be static.
-  position: static;
+  // We don't use MDC's positioning so this has to be relative.
+  position: relative;
 
-  // The overlay reference updates the pointer-events style property directly on the HTMLElement
-  // depending on the state of the overlay. For tooltips the overlay panel should never enable
-  // pointer events. To overwrite the inline CSS from the overlay reference `!important` is needed.
-  pointer-events: none !important;
+  // Increases the area of the tooltip so the user's pointer can go from the trigger directly to it.
+  &::before {
+    $offset: -8px;
+    content: '';
+    top: $offset;
+    right: $offset;
+    bottom: $offset;
+    left: $offset;
+    z-index: -1;
+    position: absolute;
+  }
 }

src/material-experimental/mdc-tooltip/tooltip.spec.ts

@@ -7,6 +7,7 @@ import {Platform} from '@angular/cdk/platform';
 import {
   createFakeEvent,
   createKeyboardEvent,
+  createMouseEvent,
   dispatchEvent,
   dispatchFakeEvent,
   dispatchKeyboardEvent,
@@ -926,6 +927,91 @@ describe('MDC-based MatTooltip', () => {
       expect(tooltipElement.classList).toContain('mdc-tooltip--multiline');
       expect(tooltipDirective._tooltipInstance?._isMultiline).toBeTrue();
     }));
+
+    it('should hide on mouseleave on the trigger', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseleave');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(false);
+    }));
+
+    it('should not hide on mouseleave if the pointer goes from the trigger to the tooltip', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector(
+        '.mat-mdc-tooltip',
+      ) as HTMLElement;
+      const event = createMouseEvent('mouseleave');
+      Object.defineProperty(event, 'relatedTarget', {value: tooltipElement});
+
+      dispatchEvent(fixture.componentInstance.button.nativeElement, event);
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+    }));
+
+    it('should hide on mouseleave on the tooltip', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector(
+        '.mat-mdc-tooltip',
+      ) as HTMLElement;
+      dispatchMouseEvent(tooltipElement, 'mouseleave');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(false);
+    }));
+
+    it('should not hide on mouseleave if the pointer goes from the tooltip to the trigger', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector(
+        '.mat-mdc-tooltip',
+      ) as HTMLElement;
+      const event = createMouseEvent('mouseleave');
+      Object.defineProperty(event, 'relatedTarget', {
+        value: fixture.componentInstance.button.nativeElement,
+      });
+
+      dispatchEvent(tooltipElement, event);
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+    }));
   });
 
   describe('fallback positions', () => {

src/material-experimental/mdc-tooltip/tooltip.ts

@@ -121,12 +121,13 @@ export class MatTooltip extends _MatTooltipBase<TooltipComponent> {
     // Forces the element to have a layout in IE and Edge. This fixes issues where the element
     // won't be rendered if the animations are disabled or there is no web animations polyfill.
     '[style.zoom]': '_visibility === "visible" ? 1 : null',
+    '(mouseleave)': '_handleMouseLeave($event)',
     'aria-hidden': 'true',
   },
 })
 export class TooltipComponent extends _TooltipComponentBase {
   /* Whether the tooltip text overflows to multiple lines */
-  _isMultiline: boolean = false;
+  _isMultiline = false;
 
   constructor(changeDetectorRef: ChangeDetectorRef, private _elementRef: ElementRef) {
     super(changeDetectorRef);

src/material/tooltip/tooltip.scss

@@ -7,13 +7,6 @@ $margin: 14px;
 $handset-horizontal-padding: 16px;
 $handset-margin: 24px;
 
-.mat-tooltip-panel {
-  // The overlay reference updates the pointer-events style property directly on the HTMLElement
-  // depending on the state of the overlay. For tooltips the overlay panel should never enable
-  // pointer events. To overwrite the inline CSS from the overlay reference `!important` is needed.
-  pointer-events: none !important;
-}
-
 .mat-tooltip {
   color: white;
   border-radius: 4px;

src/material/tooltip/tooltip.spec.ts

@@ -7,6 +7,7 @@ import {Platform} from '@angular/cdk/platform';
 import {
   createFakeEvent,
   createKeyboardEvent,
+  createMouseEvent,
   dispatchEvent,
   dispatchFakeEvent,
   dispatchKeyboardEvent,
@@ -903,6 +904,85 @@ describe('MatTooltip', () => {
       // throw if we have any timers by the end of the test.
       fixture.destroy();
     }));
+
+    it('should hide on mouseleave on the trigger', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseleave');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(false);
+    }));
+
+    it('should not hide on mouseleave if the pointer goes from the trigger to the tooltip', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector('.mat-tooltip') as HTMLElement;
+      const event = createMouseEvent('mouseleave');
+      Object.defineProperty(event, 'relatedTarget', {value: tooltipElement});
+
+      dispatchEvent(fixture.componentInstance.button.nativeElement, event);
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+    }));
+
+    it('should hide on mouseleave on the tooltip', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector('.mat-tooltip') as HTMLElement;
+      dispatchMouseEvent(tooltipElement, 'mouseleave');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(false);
+    }));
+
+    it('should not hide on mouseleave if the pointer goes from the tooltip to the trigger', fakeAsync(() => {
+      // We don't bind mouse events on mobile devices.
+      if (platform.IOS || platform.ANDROID) {
+        return;
+      }
+
+      dispatchMouseEvent(fixture.componentInstance.button.nativeElement, 'mouseenter');
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+
+      const tooltipElement = overlayContainerElement.querySelector('.mat-tooltip') as HTMLElement;
+      const event = createMouseEvent('mouseleave');
+      Object.defineProperty(event, 'relatedTarget', {
+        value: fixture.componentInstance.button.nativeElement,
+      });
+
+      dispatchEvent(tooltipElement, event);
+      fixture.detectChanges();
+      tick(0);
+      expect(tooltipDirective._isTooltipVisible()).toBe(true);
+    }));
   });
 
   describe('fallback positions', () => {

src/material/tooltip/tooltip.ts

@@ -17,7 +17,6 @@ import {
 import {ESCAPE, hasModifierKey} from '@angular/cdk/keycodes';
 import {BreakpointObserver, Breakpoints, BreakpointState} from '@angular/cdk/layout';
 import {
-  ConnectedPosition,
   FlexibleConnectedPositionStrategy,
   HorizontalConnectionPos,
   OriginConnectionPosition,
@@ -27,6 +26,7 @@ import {
   ScrollStrategy,
   VerticalConnectionPos,
   ConnectionPositionPair,
+  ConnectedPosition,
 } from '@angular/cdk/overlay';
 import {Platform, normalizePassiveListenerOptions} from '@angular/cdk/platform';
 import {ComponentPortal, ComponentType} from '@angular/cdk/portal';
@@ -207,6 +207,10 @@ export abstract class _MatTooltipBase<T extends _TooltipComponentBase>
   }
   set hideDelay(value: NumberInput) {
     this._hideDelay = coerceNumberProperty(value);
+
+    if (this._tooltipInstance) {
+      this._tooltipInstance._mouseLeaveHideDelay = this._hideDelay;
+    }
   }
   private _hideDelay = this._defaultOptions.hideDelay;
 
@@ -376,14 +380,16 @@ export abstract class _MatTooltipBase<T extends _TooltipComponentBase>
     this._detach();
     this._portal =
       this._portal || new ComponentPortal(this._tooltipComponent, this._viewContainerRef);
-    this._tooltipInstance = overlayRef.attach(this._portal).instance;
-    this._tooltipInstance
+    const instance = (this._tooltipInstance = overlayRef.attach(this._portal).instance);
+    instance._triggerElement = this._elementRef.nativeElement;
+    instance._mouseLeaveHideDelay = this._hideDelay;
+    instance
       .afterHidden()
       .pipe(takeUntil(this._destroyed))
       .subscribe(() => this._detach());
     this._setTooltipClass(this._tooltipClass);
     this._updateTooltipMessage();
-    this._tooltipInstance!.show(delay);
+    instance.show(delay);
   }
 
   /** Hides the tooltip after the delay in ms, defaults to tooltip-delay-hide or 0ms if no input */
@@ -687,7 +693,15 @@ export abstract class _MatTooltipBase<T extends _TooltipComponentBase>
     const exitListeners: (readonly [string, EventListenerOrEventListenerObject])[] = [];
     if (this._platformSupportsMouseEvents()) {
       exitListeners.push(
-        ['mouseleave', () => this.hide()],
+        [
+          'mouseleave',
+          event => {
+            const newTarget = (event as MouseEvent).relatedTarget as Node | null;
+            if (!newTarget || !this._overlayRef?.overlayElement.contains(newTarget)) {
+              this.hide();
+            }
+          },
+        ],
         ['wheel', event => this._wheelListener(event as WheelEvent)],
       );
     } else if (this.touchGestures !== 'off') {
@@ -824,6 +838,12 @@ export abstract class _TooltipComponentBase implements OnDestroy {
   /** Property watched by the animation framework to show or hide the tooltip */
   _visibility: TooltipVisibility = 'initial';
 
+  /** Element that caused the tooltip to open. */
+  _triggerElement: HTMLElement;
+
+  /** Amount of milliseconds to delay the closing sequence. */
+  _mouseLeaveHideDelay: number;
+
   /** Whether interactions on the page should close the tooltip */
   private _closeOnInteraction: boolean = false;
 
@@ -885,6 +905,7 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     clearTimeout(this._showTimeoutId);
     clearTimeout(this._hideTimeoutId);
     this._onHide.complete();
+    this._triggerElement = null!;
   }
 
   _animationStart() {
@@ -923,6 +944,12 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     this._changeDetectorRef.markForCheck();
   }
 
+  _handleMouseLeave({relatedTarget}: MouseEvent) {
+    if (!relatedTarget || !this._triggerElement.contains(relatedTarget as Node)) {
+      this.hide(this._mouseLeaveHideDelay);
+    }
+  }
+
   /**
    * Callback for when the timeout in this.show() gets completed.
    * This method is only needed by the mdc-tooltip, and so it is only implemented
@@ -946,6 +973,7 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     // Forces the element to have a layout in IE and Edge. This fixes issues where the element
     // won't be rendered if the animations are disabled or there is no web animations polyfill.
     '[style.zoom]': '_visibility === "visible" ? 1 : null',
+    '(mouseleave)': '_handleMouseLeave($event)',
     'aria-hidden': 'true',
   },
 })

tools/public_api_guard/material/tooltip.md

@@ -178,11 +178,14 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     // (undocumented)
     _animationStart(): void;
     _handleBodyInteraction(): void;
+    // (undocumented)
+    _handleMouseLeave({ relatedTarget }: MouseEvent): void;
     hide(delay: number): void;
     _hideTimeoutId: number | undefined;
     isVisible(): boolean;
     _markForCheck(): void;
     message: string;
+    _mouseLeaveHideDelay: number;
     // (undocumented)
     ngOnDestroy(): void;
     protected _onShow(): void;
@@ -191,6 +194,7 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     tooltipClass: string | string[] | Set<string> | {
         [key: string]: any;
     };
+    _triggerElement: HTMLElement;
     _visibility: TooltipVisibility;
     // (undocumented)
     static ɵdir: i0.ɵɵDirectiveDeclaration<_TooltipComponentBase, never, never, {}, {}, never>;