coral-spectrum/coral-component-tooltip/src/scripts/Tooltip.js

/**
 * Copyright 2019 Adobe. All rights reserved.
 * This file is licensed to you under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy
 * of the License at http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
 * OF ANY KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */
 
import {ExtensibleOverlay, Overlay} from '../../../coral-component-overlay';
import Vent from '@adobe/vent';
import base from '../templates/base';
import {commons, transform, validate} from '../../../coral-utils';
import {Decorator} from '../../../coral-decorator';
 
const arrowMap = {
  left: 'left',
  right: 'right',
  top: 'top',
  bottom: 'bottom'
};
 
const CLASSNAME = '_coral-Tooltip';
 
const OFFSET = 5;
 
/**
 Enumeration for {@link Tooltip} variants.
 
 @typedef {Object} TooltipVariantEnum
 
 @property {String} DEFAULT
 A default tooltip that provides additional information.
 @property {String} INFO
 A tooltip that informs the user of non-critical information.
 @property {String} SUCCESS
 A tooltip that indicates an operation was successful.
 @property {String} ERROR
 A tooltip that indicates an error has occurred.
 @property {String} WARNING
 Not supported. Falls back to DEFAULT.
 @property {String} INSPECT
 Not supported. Falls back to DEFAULT.
 */
const variant = {
  DEFAULT: 'default',
  INFO: 'info',
  SUCCESS: 'success',
  ERROR: 'error',
  WARNING: 'warning',
  INSPECT: 'inspect'
};
 
// A string of all possible variant classnames
const ALL_VARIANT_CLASSES = [];
for (const variantName in variant) {
  ALL_VARIANT_CLASSES.push(`${CLASSNAME}--${variant[variantName]}`);
}
 
// A string of all position placement classnames
const ALL_PLACEMENT_CLASSES = [];
 
// A map of lowercase directions to their corresponding classname
const placementClassMap = {};
for (const key in Overlay.placement) {
  const direction = Overlay.placement[key];
  const placementClass = `${CLASSNAME}--${arrowMap[direction]}`;
 
  // Store in map
  placementClassMap[direction] = placementClass;
 
  // Store in list
  ALL_PLACEMENT_CLASSES.push(placementClass);
}
 
/**
 @class Coral.Tooltip
 @classdesc A Tooltip component that can be attached to any element and may be displayed immediately or on hovering the
 target element.
 @htmltag coral-tooltip
 @extends {Overlay}
 */
const Tooltip = Decorator(class extends ExtensibleOverlay {
  /** @ignore */
  constructor() {
    super();
 
    // Override defaults
    this._lengthOffset = OFFSET;
    this._overlayAnimationTime = Overlay.FADETIME;
    this._focusOnShow = Overlay.focusOnShow.OFF;
 
    // Fetch or create the content zone element
    this._elements = commons.extend(this._elements, {
      content: this.querySelector('coral-tooltip-content') || document.createElement('coral-tooltip-content')
    });
 
    // Generate template
    base.call(this._elements);
 
    // Used for events
    this._id = commons.getUID();
    this._delegateEvents({
      'coral-overlay:positioned': '_onPositioned',
      'coral-overlay:_animate': '_onAnimate',
      'mouseenter': '_onMouseEnter',
      'mouseleave': '_onMouseLeave'
    });
  }
 
  /**
   The variant of tooltip. See {@link TooltipVariantEnum}.
 
   @type {String}
   @default TooltipVariantEnum.DEFAULT
   @htmlattribute variant
   @htmlattributereflected
   */
  get variant() {
    return this._variant || variant.DEFAULT;
  }
 
  set variant(value) {
    value = transform.string(value).toLowerCase();
    this._variant = validate.enumeration(variant)(value) && value || variant.DEFAULT;
    this._reflectAttribute('variant', this._variant);
 
    this.classList.remove(...ALL_VARIANT_CLASSES);
    this.classList.add(`${CLASSNAME}--${this._variant}`);
  }
 
  /**
   The amount of time in miliseconds to wait before showing the tooltip when the target is interacted with.
 
   @type {Number}
   @default 500
   @htmlattribute delay
   */
  get delay() {
    return typeof this._delay === 'number' ? this._delay : 500;
  }
 
  set delay(value) {
    this._delay = transform.number(value);
  }
 
  /**
   The Tooltip content element.
 
   @type {TooltipContent}
   @contentzone
   */
  get content() {
    return this._getContentZone(this._elements.content);
  }
 
  set content(value) {
    this._setContentZone('content', value, {
      handle: 'content',
      tagName: 'coral-tooltip-content',
      insert: function (content) {
        content.classList.add(`${CLASSNAME}-label`);
        this.appendChild(content);
      }
    });
  }
 
  /**
   Inherited from {@link Overlay#open}.
   */
  get open() {
    return super.open;
  }
 
  set open(value) {
    super.open = value;
 
    if (!this.open) {
      // Stop previous show operations from happening
      this._cancelShow();
    }
  }
 
  /**
   Inherited from {@link Overlay#target}.
   */
  get target() {
    return super.target;
  }
 
  set target(value) {
    super.target = value;
 
    const target = this._getTarget(value);
 
    if (target) {
      this._elements.tip.hidden = false;
 
      if (this.interaction === this.constructor.interaction.ON) {
        // Add listeners to the target
        this._addTargetListeners(target);
      }
    } else {
      this._elements.tip.hidden = true;
    }
  }
 
  /**
   Inherited from {@link Overlay#interaction}.
   */
  get interaction() {
    return super.interaction;
  }
 
  set interaction(value) {
    super.interaction = value;
 
    const target = this._getTarget();
 
    if (target) {
      if (value === this.constructor.interaction.ON) {
        this._addTargetListeners(target);
      } else {
        this._removeTargetListeners(target);
      }
    }
  }
 
  /** @ignore */
  _onPositioned(event) {
    // Set arrow placement
    this.classList.remove(...ALL_PLACEMENT_CLASSES);
    this.classList.add(placementClassMap[event.detail.placement]);
  }
 
  _onAnimate() {
    // popper attribute
    const popperPlacement = this.getAttribute('x-placement');
 
    // popper takes care of setting left, top to 0 on positioning
    if (popperPlacement === 'left') {
      this.style.left = '8px';
    } else if (popperPlacement === 'top') {
      this.style.top = '8px';
    } else if (popperPlacement === 'right') {
      this.style.left = '-8px';
    } else if (popperPlacement === 'bottom') {
      this.style.top = '-8px';
    }
  }
 
  _onMouseEnter() {
    if (this.interaction === this.constructor.interaction.ON && this.open) {
      // on automatic interaction and tooltip still open and mouse enters the tooltip, cancel hide.
      this._cancelHide();
    }
  }
 
  _onMouseLeave() {
    if (this.interaction === this.constructor.interaction.ON) {
      // on automatic interaction and mouse leave tooltip and execute same flow when mouse leaves target.
      this._startHide();
    }
  }
 
  /** @ignore */
  _handleFocusOut() {
    // The item that should have focus will get it on the next frame
    window.requestAnimationFrame(() => {
      const targetIsFocused = document.activeElement === this._getTarget();
 
      if (!targetIsFocused) {
        this._cancelShow();
        this.open = false;
      }
    });
  }
 
  /** @ignore */
  _cancelShow() {
    window.clearTimeout(this._showTimeout);
  }
 
  /** @ignore */
  _cancelHide() {
    window.clearTimeout(this._hideTimeout);
  }
 
  /** @ignore */
  _startHide() {
    if (this.delay === 0) {
      // Hide immediately
      this._handleFocusOut();
    } else {
      this._hideTimeout = window.setTimeout(() => {
        this._handleFocusOut();
      }, this.delay);
    }
  }
 
  /** @ignore */
  _addTargetListeners(target) {
    // Make sure we don't add listeners twice to the same element for this particular tooltip
    if (target[`_hasTooltipListeners${this._id}`]) {
      return;
    }
    target[`_hasTooltipListeners${this._id}`] = true;
 
    // Remove listeners from the old target
    if (this._oldTarget) {
      const oldTarget = this._getTarget(this._oldTarget);
      if (oldTarget) {
        this._removeTargetListeners(oldTarget);
      }
    }
 
    // Store the current target value
    this._oldTarget = target;
 
    // Use Vent to bind events on the target
    this._targetEvents = new Vent(target);
 
    this._targetEvents.on(`mouseenter.Tooltip${this._id}`, this._handleOpenTooltip.bind(this));
    this._targetEvents.on(`focusin.Tooltip${this._id}`, this._handleOpenTooltip.bind(this));
 
    this._targetEvents.on(`mouseleave.Tooltip${this._id}`, () => {
      if (this.interaction === this.constructor.interaction.ON) {
        this._startHide();
      }
    });
 
    this._targetEvents.on(`focusout.Tooltip${this._id}`, () => {
      if (this.interaction === this.constructor.interaction.ON) {
        this._handleFocusOut();
      }
    });
  }
 
  _handleOpenTooltip() {
    // Don't let the tooltip hide
    this._cancelHide();
 
    if (!this.open) {
      this._cancelShow();
 
      if (this.delay === 0) {
        // Show immediately
        this.show();
      } else {
        this._showTimeout = window.setTimeout(() => {
          this.show();
        }, this.delay);
      }
    }
  }
 
  /** @ignore */
  _removeTargetListeners(target) {
    // Remove listeners for this tooltip and mark that the element doesn't have them
    // Use the ID so we can support multiple tooltips on the same element
    if (this._targetEvents) {
      this._targetEvents.off(`.Tooltip${this._id}`);
    }
    target[`_hasTooltipListeners${this._id}`] = false;
  }
 
  get _contentZones() {
    return {'coral-tooltip-content': 'content'};
  }
 
  /**
   Returns {@link Tooltip} variants.
 
   @return {TooltipVariantEnum}
   */
  static get variant() {
    return variant;
  }
 
  /** @ignore */
  static get observedAttributes() {
    return super.observedAttributes.concat(['variant', 'delay']);
  }
 
  /** @ignore */
  render() {
    super.render();
 
    this.classList.add(CLASSNAME);
 
    // ARIA
    this.setAttribute('role', 'tooltip');
    // Let the tooltip be focusable
    // We'll marshall focus around when its focused
    this.setAttribute('tabindex', '-1');
 
    // Default reflected attributes
    if (!this._variant) {
      this.variant = variant.DEFAULT;
    }
 
    // Support cloneNode
    const tip = this.querySelector('._coral-Tooltip-tip');
    if (tip) {
      tip.remove();
    }
 
    const content = this._elements.content;
 
    // Move the content into the content zone if none specified
    if (!content.parentNode) {
      while (this.firstChild) {
        content.appendChild(this.firstChild);
      }
    }
 
    // Append template
    this.appendChild(this._elements.tip);
 
    // Assign the content zone so the insert function will be called
    this.content = content;
  }
});
 
export default Tooltip;