feat(tooltip): add class to tooltip element based on the current position

Adds a class on the tooltip overlay element that indicates the current position of the tooltip. This allows for the tooltip to be customized to add position-based arrows or box shadows.

Fixes #15216.

Author: crisbeto

src/lib/tooltip/tooltip.md

@@ -14,27 +14,32 @@ the positions `before` and `after` should be used instead of `left` and `right`,
 | Position  | Description                                                                          |
 |-----------|--------------------------------------------------------------------------------------|
 | `above`   | Always display above the element                                                     |
-| `below `  | Always display beneath the element                                                   |
+| `below`   | Always display beneath the element                                                   |
 | `left`    | Always display to the left of the element                                            |
 | `right`   | Always display to the right of the element                                           |
 | `before`  | Display to the left in left-to-right layout and to the right in right-to-left layout |
-| `after`   | Display to the right in left-to-right layout and to the left in right-to-left layout|
+| `after`   | Display to the right in left-to-right layout and to the left in right-to-left layout |
+
+Based on the position in which the tooltip is shown, the `.mat-tooltip-panel` element will receive a
+CSS class that can be used for style (e.g. to add an arrow). The possible classes are
+`mat-tooltip-panel-above`, `mat-tooltip-panel-below`, `mat-tooltip-panel-left`,
+`mat-tooltip-panel-right`.
 
 <!-- example(tooltip-position) -->
 
 ### Showing and hiding
 
 By default, the tooltip will be immediately shown when the user's mouse hovers over the tooltip's
-trigger element and immediately hides when the user's mouse leaves. 
+trigger element and immediately hides when the user's mouse leaves.
 
 On mobile, the tooltip is displayed when the user longpresses the element and hides after a
 delay of 1500ms. The longpress behavior requires HammerJS to be loaded on the page. To learn more
-about adding HammerJS to your app, check out the Gesture Support section of the Getting Started 
+about adding HammerJS to your app, check out the Gesture Support section of the Getting Started
 guide.
 
 #### Show and hide delays
 
-To add a delay before showing or hiding the tooltip, you can use the inputs `matTooltipShowDelay` 
+To add a delay before showing or hiding the tooltip, you can use the inputs `matTooltipShowDelay`
 and `matTooltipHideDelay` to provide a delay time in milliseconds.
 
 The following example has a tooltip that waits one second to display after the user
@@ -58,7 +63,7 @@ which both accept a number in milliseconds to delay before applying the display
 
 #### Disabling the tooltip from showing
 
-To completely disable a tooltip, set `matTooltipDisabled`. While disabled, a tooltip will never be 
+To completely disable a tooltip, set `matTooltipDisabled`. While disabled, a tooltip will never be
 shown.
 
 ### Accessibility

src/lib/tooltip/tooltip.spec.ts

@@ -36,6 +36,7 @@ import {
   SCROLL_THROTTLE_MS,
   TOOLTIP_PANEL_CLASS,
   MAT_TOOLTIP_DEFAULT_OPTIONS,
+  TooltipPosition,
 } from './index';
 
 
@@ -691,6 +692,75 @@ describe('MatTooltip', () => {
       expect(overlayRef.detach).not.toHaveBeenCalled();
     }));
 
+    it('should set a class on the overlay panel that reflects the position', fakeAsync(() => {
+      // Move the element so that the primary position is always used.
+      buttonElement.style.position = 'fixed';
+      buttonElement.style.top = buttonElement.style.left = '100px';
+
+      setPositionAndShow('below');
+
+      const classList = tooltipDirective._overlayRef!.overlayElement.classList;
+      expect(classList).toContain('mat-tooltip-panel-below');
+
+      setPositionAndShow('above');
+      expect(classList).not.toContain('mat-tooltip-panel-below');
+      expect(classList).toContain('mat-tooltip-panel-above');
+
+      setPositionAndShow('left');
+      expect(classList).not.toContain('mat-tooltip-panel-above');
+      expect(classList).toContain('mat-tooltip-panel-left');
+
+      setPositionAndShow('right');
+      expect(classList).not.toContain('mat-tooltip-panel-left');
+      expect(classList).toContain('mat-tooltip-panel-right');
+
+      function setPositionAndShow(position: TooltipPosition) {
+        tooltipDirective.hide(0);
+        fixture.detectChanges();
+        tick(0);
+        tooltipDirective.position = position;
+        tooltipDirective.show(0);
+        fixture.detectChanges();
+        tick(0);
+        fixture.detectChanges();
+        tick(500);
+      }
+    }));
+
+    it('should account for RTL when setting the tooltip position class', fakeAsync(() => {
+      // Move the element so that the primary position is always used.
+      buttonElement.style.position = 'fixed';
+      buttonElement.style.top = buttonElement.style.left = '100px';
+      dir.value = 'ltr';
+      tooltipDirective.position = 'after';
+      tooltipDirective.show(0);
+      fixture.detectChanges();
+      tick(0);
+      fixture.detectChanges();
+      tick(500);
+
+      const classList = tooltipDirective._overlayRef!.overlayElement.classList;
+      expect(classList).not.toContain('mat-tooltip-panel-after');
+      expect(classList).not.toContain('mat-tooltip-panel-before');
+      expect(classList).not.toContain('mat-tooltip-panel-left');
+      expect(classList).toContain('mat-tooltip-panel-right');
+
+      tooltipDirective.hide(0);
+      fixture.detectChanges();
+      tick(0);
+      dir.value = 'rtl';
+      tooltipDirective.show(0);
+      fixture.detectChanges();
+      tick(0);
+      fixture.detectChanges();
+      tick(500);
+
+      expect(classList).not.toContain('mat-tooltip-panel-after');
+      expect(classList).not.toContain('mat-tooltip-panel-before');
+      expect(classList).not.toContain('mat-tooltip-panel-right');
+      expect(classList).toContain('mat-tooltip-panel-left');
+  }));
+
   });
 
   describe('fallback positions', () => {

src/lib/tooltip/tooltip.ts

@@ -21,6 +21,7 @@ import {
   OverlayRef,
   VerticalConnectionPos,
   ScrollStrategy,
+  ConnectionPositionPair,
 } from '@angular/cdk/overlay';
 import {ScrollDispatcher} from '@angular/cdk/scrolling';
 import {Platform} from '@angular/cdk/platform';
@@ -125,6 +126,7 @@ export class MatTooltip implements OnDestroy {
   private _disabled: boolean = false;
   private _tooltipClass: string|string[]|Set<string>|{[key: string]: any};
   private _scrollStrategy: () => ScrollStrategy;
+  private _currentPosition: TooltipPosition;
 
   /** Allows the user to define the position of the tooltip relative to the parent element */
   @Input('matTooltipPosition')
@@ -352,6 +354,8 @@ export class MatTooltip implements OnDestroy {
     strategy.withScrollableContainers(scrollableAncestors);
 
     strategy.positionChanges.pipe(takeUntil(this._destroyed)).subscribe(change => {
+      this._updateCurrentPositionClass(change.connectionPair);
+
       if (this._tooltipInstance) {
         if (change.scrollableViewProperties.isOverlayClipped && this._tooltipInstance.isVisible()) {
           // After position changes occur and the overlay is clipped by
@@ -509,6 +513,39 @@ export class MatTooltip implements OnDestroy {
 
     return {x, y};
   }
+
+  /** Updates the class on the overlay panel based on the current position of the tooltip. */
+  private _updateCurrentPositionClass(connectionPair: ConnectionPositionPair): void {
+    const {overlayY, originX, originY} = connectionPair;
+    let newPosition: TooltipPosition;
+
+    // If the overlay is in the middle along the Y axis,
+    // it means that it's either before or after.
+    if (overlayY === 'center') {
+      // Note that since this information is used for styling, we want to
+      // resolve `start` and `end` to their real values, otherwise consumers
+      // would have to remember to do it themselves on each consumption.
+      if (this._dir && this._dir.value === 'rtl') {
+        newPosition = originX === 'end' ? 'left' : 'right';
+      } else {
+        newPosition = originX === 'start' ? 'left' : 'right';
+      }
+    } else {
+      newPosition = overlayY === 'bottom' && originY === 'top' ? 'above' : 'below';
+    }
+
+    if (newPosition !== this._currentPosition) {
+      const overlayRef = this._overlayRef;
+
+      if (overlayRef) {
+        const classPrefix = 'mat-tooltip-panel-';
+        overlayRef.removePanelClass(classPrefix + this._currentPosition);
+        overlayRef.addPanelClass(classPrefix + newPosition);
+      }
+
+      this._currentPosition = newPosition;
+    }
+  }
 }
 
 export type TooltipVisibility = 'initial' | 'visible' | 'hidden';