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.html

@@ -2,6 +2,7 @@
   class="mdc-tooltip mdc-tooltip--shown mat-mdc-tooltip"
   [ngClass]="tooltipClass"
   [class.mdc-tooltip--multiline]="_isMultiline"
+  [style.margin.px]="_gap"
   [@state]="_visibility"
   (@state.start)="_animationStart()"
   (@state.done)="_animationDone($event)">

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

@@ -6,9 +6,4 @@
 .mat-mdc-tooltip {
   // We don't use MDC's positioning so this has to be static.
   position: static;
-
-  // 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;
 }

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,71 @@ 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(() => {
+      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(() => {
+      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(() => {
+      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(() => {
+      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

@@ -22,7 +22,7 @@ import {DOCUMENT} from '@angular/common';
 import {Platform} from '@angular/cdk/platform';
 import {AriaDescriber, FocusMonitor} from '@angular/cdk/a11y';
 import {Directionality} from '@angular/cdk/bidi';
-import {ConnectedPosition, Overlay, ScrollDispatcher} from '@angular/cdk/overlay';
+import {Overlay, ScrollDispatcher} from '@angular/cdk/overlay';
 import {
   MatTooltipDefaultOptions,
   MAT_TOOLTIP_DEFAULT_OPTIONS,
@@ -87,23 +87,6 @@ export class MatTooltip extends _MatTooltipBase<TooltipComponent> {
     );
     this._viewportMargin = numbers.MIN_VIEWPORT_TOOLTIP_THRESHOLD;
   }
-
-  protected override _addOffset(position: ConnectedPosition): ConnectedPosition {
-    const offset = numbers.UNBOUNDED_ANCHOR_GAP;
-    const isLtr = !this._dir || this._dir.value == 'ltr';
-
-    if (position.originY === 'top') {
-      position.offsetY = -offset;
-    } else if (position.originY === 'bottom') {
-      position.offsetY = offset;
-    } else if (position.originX === 'start') {
-      position.offsetX = isLtr ? -offset : offset;
-    } else if (position.originX === 'end') {
-      position.offsetX = isLtr ? offset : -offset;
-    }
-
-    return position;
-  }
 }
 
 /**
@@ -121,12 +104,16 @@ 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;
+
+  /** Gap between the tooltip and the trigger. */
+  _gap = numbers.UNBOUNDED_ANCHOR_GAP;
 
   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,65 @@ 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(() => {
+      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(() => {
+      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(() => {
+      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(() => {
+      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,
@@ -207,6 +206,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 +379,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 */
@@ -483,16 +488,11 @@ export abstract class _MatTooltipBase<T extends _TooltipComponentBase>
     const overlay = this._getOverlayPosition();
 
     position.withPositions([
-      this._addOffset({...origin.main, ...overlay.main}),
-      this._addOffset({...origin.fallback, ...overlay.fallback}),
+      {...origin.main, ...overlay.main},
+      {...origin.fallback, ...overlay.fallback},
     ]);
   }
 
-  /** Adds the configured offset to a position. Used as a hook for child classes. */
-  protected _addOffset(position: ConnectedPosition): ConnectedPosition {
-    return position;
-  }
-
   /**
    * Returns the origin position and a fallback position based on the user's position preference.
    * The fallback position is the inverse of the origin (e.g. `'below' -> 'above'`).
@@ -687,7 +687,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 +832,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 +899,7 @@ export abstract class _TooltipComponentBase implements OnDestroy {
     clearTimeout(this._showTimeoutId);
     clearTimeout(this._hideTimeoutId);
     this._onHide.complete();
+    this._triggerElement = null!;
   }
 
   _animationStart() {
@@ -923,6 +938,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 +967,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

@@ -13,7 +13,6 @@ import { BreakpointObserver } from '@angular/cdk/layout';
 import { BreakpointState } from '@angular/cdk/layout';
 import { ChangeDetectorRef } from '@angular/core';
 import { ComponentType } from '@angular/cdk/portal';
-import { ConnectedPosition } from '@angular/cdk/overlay';
 import { Directionality } from '@angular/cdk/bidi';
 import { ElementRef } from '@angular/core';
 import { FocusMonitor } from '@angular/cdk/a11y';
@@ -78,7 +77,6 @@ export const matTooltipAnimations: {
 // @public (undocumented)
 export abstract class _MatTooltipBase<T extends _TooltipComponentBase> implements OnDestroy, AfterViewInit {
     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);
-    protected _addOffset(position: ConnectedPosition): ConnectedPosition;
     // (undocumented)
     protected readonly _cssClassPrefix: string;
     // (undocumented)
@@ -178,11 +176,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 +192,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>;