feat(tooltip): Added persistent variant for rich tooltips that shows/hides based on mouse clicks on the anchor element. Clicks on elements other than the anchor will also hide the persistent variant.

Shi Shu · copybara-github · commit 9775856508a7 · 2020-12-02T06:35:09.000-08:00
BREAKING CHANGE:
  Added adapter method:
  - anchorContainsElement(element: HTMLElement): boolean;
Rich tooltips are currently in development and is not yet ready for use.

PiperOrigin-RevId: 345221617
diff --git a/packages/mdc-tooltip/adapter.ts b/packages/mdc-tooltip/adapter.ts
@@ -98,6 +98,11 @@ export interface MDCTooltipAdapter {
    */
   isRTL(): boolean;
 
+  /**
+   * Checks if element is contained within the anchor element.
+   */
+  anchorContainsElement(element: HTMLElement): boolean;
+
   /**
    * Registers an event listener to the root element.
    */
diff --git a/packages/mdc-tooltip/component.ts b/packages/mdc-tooltip/component.ts
@@ -34,12 +34,15 @@ export class MDCTooltip extends MDCComponent<MDCTooltipFoundation> {
   }
 
   private anchorElem!: HTMLElement|null;  // assigned in initialSyncWithDOM
+  private isTooltipRich!: boolean;        // assigned in initialSyncWithDOM
+  private isTooltipPersistent!: boolean;  // assigned in initialSyncWithDOM
 
   private handleMouseEnter!: SpecificEventListener<'mouseenter'>;
   private handleFocus!: SpecificEventListener<'focus'>;
   private handleMouseLeave!: SpecificEventListener<'mouseleave'>;
   private handleBlur!: SpecificEventListener<'blur'>;
   private handleTransitionEnd!: SpecificEventListener<'transitionend'>;
+  private handleClick!: SpecificEventListener<'click'>;
 
   initialSyncWithDOM() {
     const tooltipId = this.root.getAttribute('id');
@@ -55,6 +58,9 @@ export class MDCTooltip extends MDCComponent<MDCTooltipFoundation> {
           'MDCTooltip: Tooltip component requires an anchor element annotated with [aria-describedby] or [data-tooltip-id] anchor element.');
     }
 
+    this.isTooltipRich = this.foundation.getIsRich();
+    this.isTooltipPersistent = this.foundation.getIsPersistent();
+
     this.handleMouseEnter = () => {
       this.foundation.handleAnchorMouseEnter();
     };
@@ -75,21 +81,35 @@ export class MDCTooltip extends MDCComponent<MDCTooltipFoundation> {
       this.foundation.handleTransitionEnd();
     };
 
-    this.anchorElem.addEventListener('mouseenter', this.handleMouseEnter);
-    // TODO(b/157075286): Listening for a 'focus' event is too broad.
-    this.anchorElem.addEventListener('focus', this.handleFocus);
-    this.anchorElem.addEventListener('mouseleave', this.handleMouseLeave);
-    this.anchorElem.addEventListener('blur', this.handleBlur);
+    this.handleClick = () => {
+      this.foundation.handleAnchorClick();
+    };
+
+    if (this.isTooltipRich && this.isTooltipPersistent) {
+      this.anchorElem.addEventListener('click', this.handleClick);
+    } else {
+      this.anchorElem.addEventListener('mouseenter', this.handleMouseEnter);
+      // TODO(b/157075286): Listening for a 'focus' event is too broad.
+      this.anchorElem.addEventListener('focus', this.handleFocus);
+      this.anchorElem.addEventListener('mouseleave', this.handleMouseLeave);
+      this.anchorElem.addEventListener('blur', this.handleBlur);
+    }
 
     this.listen('transitionend', this.handleTransitionEnd);
   }
 
   destroy() {
     if (this.anchorElem) {
-      this.anchorElem.removeEventListener('mouseenter', this.handleMouseEnter);
-      this.anchorElem.removeEventListener('focus', this.handleFocus);
-      this.anchorElem.removeEventListener('mouseleave', this.handleMouseLeave);
-      this.anchorElem.removeEventListener('blur', this.handleBlur);
+      if (this.isTooltipRich && this.isTooltipPersistent) {
+        this.anchorElem.removeEventListener('click', this.handleClick);
+      } else {
+        this.anchorElem.removeEventListener(
+            'mouseenter', this.handleMouseEnter);
+        this.anchorElem.removeEventListener('focus', this.handleFocus);
+        this.anchorElem.removeEventListener(
+            'mouseleave', this.handleMouseLeave);
+        this.anchorElem.removeEventListener('blur', this.handleBlur);
+      }
     }
 
     this.unlisten('transitionend', this.handleTransitionEnd);
@@ -138,6 +158,10 @@ export class MDCTooltip extends MDCComponent<MDCTooltipFoundation> {
         this.anchorElem?.setAttribute(attr, value);
       },
       isRTL: () => getComputedStyle(this.root).direction === 'rtl',
+      anchorContainsElement: (element) => {
+        const hasAnchorElem = Boolean(this.anchorElem);
+        return hasAnchorElem && this.anchorElem!.contains(element);
+      },
       registerEventHandler: (evt, handler) => {
         if (this.root instanceof HTMLElement) {
           this.root.addEventListener(evt, handler);
diff --git a/packages/mdc-tooltip/constants.ts b/packages/mdc-tooltip/constants.ts
@@ -43,6 +43,10 @@ const numbers = {
   // LINT.ThenChange(_tooltip.scss:tooltip-dimensions)
 };
 
+const attributes = {
+  PERSISTENT: 'data-mdc-tooltip-persistent',
+};
+
 const events = {
   HIDDEN: 'MDCTooltip:hidden',
 };
@@ -72,4 +76,12 @@ enum AnchorBoundaryType {
   UNBOUNDED = 1,
 }
 
-export {CssClasses, numbers, events, XPosition, AnchorBoundaryType, YPosition};
+export {
+  CssClasses,
+  numbers,
+  attributes,
+  events,
+  XPosition,
+  AnchorBoundaryType,
+  YPosition
+};
diff --git a/packages/mdc-tooltip/foundation.ts b/packages/mdc-tooltip/foundation.ts
@@ -25,8 +25,9 @@ import {AnimationFrame} from '@material/animation/animationframe';
 import {MDCFoundation} from '@material/base/foundation';
 import {SpecificEventListener} from '@material/base/types';
 import {KEY, normalizeKey} from '@material/dom/keyboard';
+
 import {MDCTooltipAdapter} from './adapter';
-import {AnchorBoundaryType, CssClasses, numbers, XPosition, YPosition} from './constants';
+import {AnchorBoundaryType, attributes, CssClasses, numbers, XPosition, YPosition} from './constants';
 import {ShowTooltipOptions} from './types';
 
 const {
@@ -60,6 +61,7 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
       getAnchorAttribute: () => null,
       setAnchorAttribute: () => null,
       isRTL: () => false,
+      anchorContainsElement: () => false,
       registerEventHandler: () => undefined,
       deregisterEventHandler: () => undefined,
       registerDocumentEventHandler: () => undefined,
@@ -71,6 +73,7 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
   }
 
   private isRich!: boolean;  // assigned in init()
+  private isPersistent!: boolean;  // assigned in init()
   private isShown = false;
   private anchorGap = numbers.BOUNDED_ANCHOR_GAP;
   private xTooltipPos = XPosition.DETECTED;
@@ -99,8 +102,8 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
     super({...MDCTooltipFoundation.defaultAdapter, ...adapter});
     this.animFrame = new AnimationFrame();
 
-    this.documentClickHandler = () => {
-      this.handleClick();
+    this.documentClickHandler = (evt) => {
+      this.handleDocumentClick(evt);
     };
 
     this.documentKeydownHandler = (evt) => {
@@ -126,6 +129,16 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
 
   init() {
     this.isRich = this.adapter.hasClass(RICH);
+    this.isPersistent =
+        this.adapter.getAttribute(attributes.PERSISTENT) === 'true';
+  }
+
+  getIsRich() {
+    return this.isRich;
+  }
+
+  getIsPersistent() {
+    return this.isPersistent;
   }
 
   handleAnchorMouseEnter() {
@@ -163,7 +176,25 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
     this.hide();
   }
 
-  handleClick() {
+  handleAnchorClick() {
+    if (this.isShown) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  handleDocumentClick(evt: MouseEvent) {
+    const anchorContainsTargetElement = evt.target instanceof HTMLElement &&
+        this.adapter.anchorContainsElement(evt.target);
+    // For persistent rich tooltips, we will only hide if the click target is
+    // not within the anchor element, otherwise both the anchor element's click
+    // handler and this handler will handle the click (due to event
+    // propagation), resulting in a shown tooltip being immediately hidden if
+    // the tooltip was initially hidden.
+    if (this.isRich && this.isPersistent && anchorContainsTargetElement) {
+      return;
+    }
     // Hide the tooltip immediately on click.
     this.hide();
   }
@@ -215,10 +246,12 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
     }
     if (this.isRich) {
       this.adapter.setAnchorAttribute('aria-expanded', 'true');
-      this.adapter.registerEventHandler(
-          'mouseenter', this.richTooltipMouseEnterHandler);
-      this.adapter.registerEventHandler(
-          'mouseleave', this.richTooltipMouseLeaveHandler);
+      if (!this.isPersistent) {
+        this.adapter.registerEventHandler(
+            'mouseenter', this.richTooltipMouseEnterHandler);
+        this.adapter.registerEventHandler(
+            'mouseleave', this.richTooltipMouseLeaveHandler);
+      }
     }
     this.adapter.removeClass(HIDE);
     this.adapter.addClass(SHOWING);
@@ -259,10 +292,12 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
     this.adapter.setAttribute('aria-hidden', 'true');
     if (this.isRich) {
       this.adapter.setAnchorAttribute('aria-expanded', 'false');
-      this.adapter.deregisterEventHandler(
-          'mouseenter', this.richTooltipMouseEnterHandler);
-      this.adapter.deregisterEventHandler(
-          'mouseleave', this.richTooltipMouseLeaveHandler);
+      if (!this.isPersistent) {
+        this.adapter.deregisterEventHandler(
+            'mouseenter', this.richTooltipMouseEnterHandler);
+        this.adapter.deregisterEventHandler(
+            'mouseleave', this.richTooltipMouseLeaveHandler);
+      }
     }
     this.clearAllAnimationClasses();
     this.adapter.addClass(HIDE);
@@ -589,7 +624,7 @@ export class MDCTooltipFoundation extends MDCFoundation<MDCTooltipAdapter> {
     this.adapter.removeClass(HIDE);
     this.adapter.removeClass(HIDE_TRANSITION);
 
-    if (this.isRich) {
+    if (this.isRich && !this.isPersistent) {
       this.adapter.deregisterEventHandler(
           'mouseenter', this.richTooltipMouseEnterHandler);
       this.adapter.deregisterEventHandler(
diff --git a/packages/mdc-tooltip/test/component.test.ts b/packages/mdc-tooltip/test/component.test.ts
@@ -256,7 +256,7 @@ describe('MDCTooltip', () => {
     });
   });
 
-  describe('rich tooltip tests', () => {
+  describe('default rich tooltip tests', () => {
     beforeEach(() => {
       fixture = getFixture(`<div>
         <button aria-describedby="tt0" aria-haspopup="true" aria-expanded="false">
@@ -283,7 +283,19 @@ describe('MDCTooltip', () => {
           .toEqual(jasmine.any(MDCTooltip));
     });
 
-    it('sets aria-expanded on anchor to true when showing rich tooltip`',
+    it('sets aria-expanded on anchor to true when showing rich tooltip', () => {
+      const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
+      const anchorElem =
+          fixture.querySelector<HTMLElement>('[aria-describedby]')!;
+      MDCTooltip.attachTo(tooltipElem);
+
+      emitEvent(anchorElem, 'mouseenter');
+      jasmine.clock().tick(numbers.SHOW_DELAY_MS);
+
+      expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
+    });
+
+    it('aria-expanded remains true on anchor when mouseleave anchor and mouseenter rich tooltip',
        () => {
          const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
          const anchorElem =
@@ -292,11 +304,13 @@ describe('MDCTooltip', () => {
 
          emitEvent(anchorElem, 'mouseenter');
          jasmine.clock().tick(numbers.SHOW_DELAY_MS);
+         emitEvent(anchorElem, 'mouseleave');
+         emitEvent(tooltipElem, 'mouseenter');
 
          expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
        });
 
-    it('aria-expanded remains true on anchor when mouseleave anchor and mouseenter rich tooltip`',
+    it('aria-expanded remains true on anchor when mouseleave rich tooltip and mouseenter anchor`',
        () => {
          const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
          const anchorElem =
@@ -305,25 +319,91 @@ describe('MDCTooltip', () => {
 
          emitEvent(anchorElem, 'mouseenter');
          jasmine.clock().tick(numbers.SHOW_DELAY_MS);
-         emitEvent(anchorElem, 'mouseleave');
-         emitEvent(tooltipElem, 'mouseenter');
+         emitEvent(tooltipElem, 'mouseleave');
+         emitEvent(anchorElem, 'mouseenter');
 
          expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
        });
+  });
 
-    it('aria-expanded remains true on anchor when mouseleave rich tooltip and mouseenter anchor`',
+  describe('persistent rich tooltip tests', () => {
+    beforeEach(() => {
+      fixture = getFixture(`<div>
+        <button aria-describedby="tt0" aria-haspopup="true" aria-expanded="false">
+          anchor
+        </button>
+        <div id="tt0" class="mdc-tooltip mdc-tooltip--rich" aria-role="dialog" aria-hidden="true" data-mdc-tooltip-persistent="true">
+          <div class="mdc-tooltip__surface">
+            <p class="mdc-tooltip__content">
+              demo tooltip
+            </p>
+          </div>
+        </div>
+      </div>`);
+      document.body.appendChild(fixture);
+    });
+
+    afterEach(() => {
+      document.body.removeChild(fixture);
+    });
+
+    it('aria-expanded remains false on anchor when mouseenter anchor', () => {
+      const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
+      const anchorElem =
+          fixture.querySelector<HTMLElement>('[aria-describedby]')!;
+      MDCTooltip.attachTo(tooltipElem);
+
+      emitEvent(anchorElem, 'mouseenter');
+      jasmine.clock().tick(numbers.SHOW_DELAY_MS);
+
+      expect(anchorElem.getAttribute('aria-expanded')).toEqual('false');
+    });
+
+    it('set aria-expanded to true on anchor when anchor clicked while tooltip is hidden',
        () => {
          const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
          const anchorElem =
              fixture.querySelector<HTMLElement>('[aria-describedby]')!;
          MDCTooltip.attachTo(tooltipElem);
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('true');
+         expect(anchorElem.getAttribute('aria-expanded')).toEqual('false');
 
-         emitEvent(anchorElem, 'mouseenter');
-         jasmine.clock().tick(numbers.SHOW_DELAY_MS);
-         emitEvent(tooltipElem, 'mouseleave');
-         emitEvent(anchorElem, 'mouseenter');
+         emitEvent(anchorElem, 'click');
+
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('false');
+         expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
+       });
+
+    it('set aria-expanded to false on anchor when anchor clicked while tooltip is shown',
+       () => {
+         const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
+         const anchorElem =
+             fixture.querySelector<HTMLElement>('[aria-describedby]')!;
+         MDCTooltip.attachTo(tooltipElem);
 
+         emitEvent(anchorElem, 'click');
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('false');
          expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
+         emitEvent(anchorElem, 'click');
+
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('true');
+         expect(anchorElem.getAttribute('aria-expanded')).toEqual('false');
+       });
+
+    it('set aria-expanded to false on anchor when element other than anchor is clicked while tooltip is shown',
+       () => {
+         const tooltipElem = fixture.querySelector<HTMLElement>('#tt0')!;
+         const anchorElem =
+             fixture.querySelector<HTMLElement>('[aria-describedby]')!;
+         MDCTooltip.attachTo(tooltipElem);
+
+         emitEvent(anchorElem, 'click');
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('false');
+         expect(anchorElem.getAttribute('aria-expanded')).toEqual('true');
+         emitEvent(document.body, 'click');
+
+         expect(tooltipElem.getAttribute('aria-hidden')).toEqual('true');
+         expect(anchorElem.getAttribute('aria-expanded')).toEqual('false');
        });
   });
 });
diff --git a/packages/mdc-tooltip/test/foundation.test.ts b/packages/mdc-tooltip/test/foundation.test.ts
