Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

10.7 KB
Raw Blame
/*
 * -- copyright
 * OpenProject is an open source project management software.
 * Copyright (C) the OpenProject GmbH
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version 3.
 *
 * OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
 * Copyright (C) 2006-2013 Jean-Philippe Lang
 * Copyright (C) 2010-2013 the ChiliProject Team
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 *
 * See COPYRIGHT and LICENSE files for more details.
 * ++
 */

import { ApplicationController } from 'stimulus-use';
import { sanitizeUrl } from '@braintree/sanitize-url';
import { computePosition, flip, limitShift, shift } from '@floating-ui/dom';

/**
 * This controller is responsible for showing a hover card when hovering over a trigger element.
 *
 * You can define a trigger element by adding the `data-hover-card-trigger-target="trigger"` to it.
 * To have hover cards available everywhere, add this controller to the body tag.
 */
export default class HoverCardTriggerController extends ApplicationController {
  static targets = ['trigger', 'card'];

  private readonly triggerTargets:HTMLElement[];

  private mouseInModal = false;
  private mouseIsHoveringOverTrigger = false;
  private hoverTimeout:number|null = null;
  private closeTimeout:number|null = null;
  private previousTarget:HTMLElement|null = null;

  // Track whether we currently show a hover card or not. It is important not to open multiple hover cards at
  // the same time, and refrain from closing the wrong kind of modal overlay.
  private isShowingHoverCard:boolean = false;

  // The time you need to keep hovering over a trigger before the hover card is shown
  OPEN_DELAY_IN_MS = 1000;
  // The time you need to keep away from trigger/hover card before an opened card is closed
  CLOSE_DELAY_IN_MS = 250;

  private triggerMouseOverBound= this.onMouseOver.bind(this);
  private triggerMouseLeaveBound= this.onMouseLeave.bind(this);
  private cardMouseLeaveBound= this.onMouseLeave.bind(this);
  private cardMouseEnterBound= this.onMouseEnter.bind(this);

  /**
   * Attempting to show hover cards on touch-based devices often leads to quirky and unwanted
   * behavior. As all information in our hover cards is optional, we'd rather only show them
   * on devices that primarily support a mouse cursor. That means that hovering is a reliable
   * option for interaction.
   */
  shouldRegisterHoverEventListeners() {
    const browserSupportsHovering = window.matchMedia('(hover: hover)').matches;
    // The browser on the CI claims not to support hovering, so we must detect whether we are in a test environment:
    const isTestEnv = window.OpenProject.environment === 'test';

    return isTestEnv || browserSupportsHovering;
  }

  private triggerTargetConnected(trigger:Element) {
    if (this.shouldRegisterHoverEventListeners()) {
      trigger.addEventListener('mouseover', this.triggerMouseOverBound);
      trigger.addEventListener('mouseleave', this.triggerMouseLeaveBound);
    }
  }

  private triggerTargetDisconnected(trigger:Element) {
    trigger.removeEventListener('mouseover', this.triggerMouseOverBound);
    trigger.removeEventListener('mouseleave', this.triggerMouseLeaveBound);
  }

  private cardTargetConnected(card:Element) {
    if (this.shouldRegisterHoverEventListeners()) {
      card.addEventListener('mouseleave', this.cardMouseLeaveBound);
      card.addEventListener('mouseenter', this.cardMouseEnterBound);
    }
  }

  private cardTargetDisconnected(card:Element) {
    card.removeEventListener('mouseleave', this.cardMouseLeaveBound);
    card.removeEventListener('mouseenter', this.cardMouseEnterBound);
  }

  private onMouseLeave() {
    this.clearHoverTimer();
    this.mouseInModal = false;
    this.mouseIsHoveringOverTrigger = false;
    this.closeAfterTimeout();
  }

  private onMouseEnter() {
    this.mouseInModal = true;
  }

  private onMouseOver(e:MouseEvent) {
    e.preventDefault();
    e.stopPropagation();

    let el = e.target as HTMLElement;
    if (!el) { return; }

    // If the trigger contains other elements, one of them might have triggered the event. We want to only refer to
    // the original trigger as this makes event and state handling easier. Find the correct target element:
    if (!this.triggerTargets.some((trigger) => trigger === el)) {
      // If the element is not a trigger itself, one of its parents must be. Find the correct one.
      const trigger = el.closest('[data-hover-card-trigger-target="trigger"]') as HTMLElement;
      if (!trigger) { return; }

      el = trigger;
    }

    this.mouseIsHoveringOverTrigger = true;

    if (this.previousTarget && this.previousTarget === el) {
      // Re-entering the trigger counts as hovering over the card:
      this.mouseInModal = true;
      // But we will not re-render the same card, abort here
      return;
    }

    // Hovering over a new target. Close the old one (if any).
    this.close(true);

    const turboFrameUrl = this.parseHoverCardUrl(el);
    if (!turboFrameUrl) { return; }

    // Reset close timer for when hovering over multiple triggers in quick succession.
    // A timer from a previous hover card might still be running. We do not want it to
    // close the new (i.e. this) hover card.
    this.clearCloseTimer();

    // Set a delay before showing the hover card
    this.hoverTimeout = window.setTimeout(() => {
      this.showHoverCard(el, turboFrameUrl);
    }, this.OPEN_DELAY_IN_MS);
  }

  private showHoverCard(el:HTMLElement, turboFrameUrl:string) {
    // Abort if the element is no longer present in the DOM. This can happen when this method is called after a delay.
    if (!this.element.contains(el)) { return; }
    // Do not try to show two hover cards at the same time.
    if (this.isShowingHoverCard) { return; }
    // The mouse might have left the trigger while we were waiting for the hover delay.
    if (!this.mouseIsHoveringOverTrigger) { return; }

    this.loadAndShowHoverCard(el, turboFrameUrl);
  }

  private loadAndShowHoverCard(targetEl:HTMLElement, turboFrameUrl:string) {
    const overlay = this.getAndResetOverlay();
    if (!overlay) { return; }

    this.moveOverlayToAppropriateParent(overlay, targetEl);

    const { turboFrame, popover } = this.constructPopover(overlay, turboFrameUrl);

    this.isShowingHoverCard = true;
    this.previousTarget = targetEl;

    turboFrame.addEventListener('turbo:frame-load', () => {
      void this.reposition(popover, targetEl);

      // Content has been loaded, card has been positioned. Show it!
      popover.showPopover();
    });
  }

  // Should be called when the mouse leaves the hover-zone so that we no longer attempt to display the hover card.
  private clearHoverTimer() {
    if (this.hoverTimeout) {
      clearTimeout(this.hoverTimeout);
      this.hoverTimeout = null;
    }
  }

  private clearCloseTimer() {
    if (this.closeTimeout) {
      clearTimeout(this.closeTimeout);
      this.closeTimeout = null;
    }
  }

  private closeAfterTimeout() {
    this.closeTimeout = window.setTimeout(() => {
      this.close();
    }, this.CLOSE_DELAY_IN_MS);
  }

  private close(forceClose=false) {
    if (forceClose) {
      this.mouseInModal = false;
    }

    if (this.isShowingHoverCard && !this.mouseInModal) {
      this.getAndResetOverlay();

      this.isShowingHoverCard = false;
      // Allow opening this target once more, since it has been orderly closed
      this.previousTarget = null;
    }
  }

  private getAndResetOverlay() {
    const overlay = document.getElementById('hover-card-overlay');
    if (overlay) {
      overlay.innerHTML = '';
      overlay.remove();
    }

    const newOverlay = document.createElement('div');
    newOverlay.id = 'hover-card-overlay';

    return newOverlay;
  }

  /*
   * Will fetch the URL from the element's data attribute and sanitize it.
   * When there is no URL or if the URL is invalid, will return an empty string.
   */
  private parseHoverCardUrl(el:HTMLElement) {
    let url = el.getAttribute('data-hover-card-url');
    if (!url) { return ''; }

    url = sanitizeUrl(url);

    // `sanitizeUrl` will return 'about:blank' for invalid URLs. We will return an empty-string instead since
    // there's no reason to show an empty hover card.
    return url === 'about:blank' ? '' : url;
  }

  private async reposition(element:HTMLElement, target:HTMLElement) {
    const floatingEl = element;

    const { x, y } = await computePosition(
      target,
      floatingEl,
      {
        placement: 'top',
        middleware: [
          flip({
            mainAxis: true,
            crossAxis: true,
            fallbackAxisSideDirection: 'start',
          }),
          shift({ limiter: limitShift() }),
        ],
      },
    );
    Object.assign(floatingEl.style, {
      left: `${x}px`,
      top: `${y}px`,
    });
  }

  private constructPopover(overlay:HTMLElement, turboFrameUrl:string) {
    const popover = document.createElement('div');
    popover.className = 'op-hover-card';
    popover.setAttribute('popover', 'auto');
    popover.setAttribute('data-hover-card-trigger-target', 'card');

    const turboFrame = document.createElement('turbo-frame');
    turboFrame.id = 'op-hover-card-body';
    popover.appendChild(turboFrame);
    turboFrame.setAttribute('src', turboFrameUrl);

    overlay.appendChild(popover);

    return { turboFrame, popover };
  }

  /*
   * For dialogs, we must ensure that the overlay is a child of the dialog, not the body. Otherwise, the overlay
   * is visible, but cannot be interacted with. This is a bug, see https://github.com/whatwg/html/issues/9936
   *
   * Until this is fixed, we must ensure the popover is interactable. We can do this by checking
   * if the target element is a child of a dialog, and if so, append the hover card overlay to the dialog.
   * Otherwise, we append it to the body.
   */
  private moveOverlayToAppropriateParent(overlay:HTMLElement, targetEl:HTMLElement) {
    const targetParentDialog = targetEl.closest('dialog-helper > dialog');

    if (targetParentDialog) {
      targetParentDialog.appendChild(overlay);
    } else {
      this.element.appendChild(overlay);
    }
  }
}