DWVv0.37.0
src/tools/layerGroupPointer.jsjavascript
import {
  getMousePoint,
  getTouchPoints
} from '../gui/generic.js';
import {getLayerDetailsFromEvent} from '../gui/layerGroup.js';
import {WheelTick} from './behaviors/wheelTick.js';

// Avoid mouse events. To use with browser mobile simulation.
const TOUCH_EVENTS_DEBUG = false;

// Max display-pixel distance from the down point still considered a tap
// (mouse/finger jitter tolerance), not a move.
const MOVE_TOLERANCE = 5;

/**
 * `MouseEvent#button` values (left through fifth / forward).
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
 *
 * @type {Readonly<{
 *   left: 0,
 *   middle: 1,
 *   right: 2,
 *   back: 3,
 *   forward: 4
 * }>}
 */
export const MouseEventButtons = {
  left: 0,
  middle: 1,
  right: 2,
  back: 3,
  forward: 4
};

/**
 * @import {App} from '../app/application.js';
 * @import {DragBehavior} from './behaviors/dragBehavior.js';
 * @import {HoverBehavior} from './behaviors/hoverBehavior.js';
 * @import {Point2D} from '../math/point.js';
 * @import {LayerGroup} from '../gui/layerGroup.js';
 * @import {WheelBehavior} from './behaviors/wheelBehavior.js';
 * @import {DoubleClickBehavior} from './behaviors/doubleClickBehavior.js';
 * @import {TapBehavior} from './behaviors/tapBehavior.js';
 * @import {TwoTouchBehavior} from './behaviors/twoTouchBehavior.js';
 * @import {StageController} from '../app/stageController.js';
 */

/**
 * @typedef {object} LayerGroupPointerOptions
 * @property {StageController} stageController The stage controller.
 * @property {DragBehavior} [dragBehavior] Drag behaviour:
 *   mouse down / touch start + move + end (mouse or touch).
 * @property {HoverBehavior} [hoverBehavior] Hover behaviour:
 *   mouse move without click (only mouse).
 * @property {WheelBehavior} [wheelBehavior] Mouse wheel handling
 *   (only mouse).
 * @property {DoubleClickBehavior} [doubleClickBehavior] Double-click
 *   behaviour, also triggered by long touch.
 * @property {TwoTouchBehavior} [twoTouchBehavior] Two-finger behaviour
 *   (only touch).
 * @property {TapBehavior} [tapBehavior] Tap behaviour: can be one tap
 *   or sticky tap for multiple taps (finite or finished with double click).
 *   For mouse or touch.
 * @property {number|null} [longTouchToDblClickMs] After a touchstart on the
 *   single-touch path, schedule {@link LayerGroupPointer#dblclick} after this
 *   many milliseconds (defaults to 500).
 */

/**
 * Normalises layer mouse/touch input into a single-pointer drag lifecycle.
 * Per-move deltas are computed inside {@link DragBehavior#onUpdate}.
 * Hover ({@link HoverBehavior}) is driven from mouse events only, not touch.
 *
 * Extends {@link EventTarget} so subclasses (tools) can use
 * `addEventListener` / `dispatchEvent` like other UI tools.
 *
 * Event entry points use the same names as tools (`mousedown`, `mousemove`,
 * `wheel`, `dblclick`, …). Those handlers are arrow functions so they stay
 * bound when the toolbox invokes them as bare callbacks (`func(event)`).
 *
 * `preventDefault` is only called on the `NonPassiveInteractionEventNames`
 * (from `gui/generic.js`), the events the layers listen to as not passive.
 */
export class LayerGroupPointer extends EventTarget {

  /**
   * @type {StageController}
   */
  #stageController;

  /**
   * @type {DragBehavior|undefined}
   */
  #dragBehavior;

  /**
   * @type {HoverBehavior|undefined}
   */
  #hoverBehavior;

  /**
   * @type {WheelBehavior|undefined}
   */
  #wheelBehavior;

  /**
   * @type {WheelTick}
   */
  #wheelTick = new WheelTick();

  /**
   * @type {DoubleClickBehavior|undefined}
   */
  #doubleClickBehavior;

  /**
   * @type {TwoTouchBehavior|undefined}
   */
  #twoTouchBehavior;

  /**
   * @type {TapBehavior|undefined}
   */
  #tapBehavior;

  /**
   * @type {number|null}
   */
  #longTouchToDblClickMs;

  /**
   * @type {number|undefined}
   */
  #longTouchTimerId;

  /**
   * True after a mouse down, reset at mouseup or mouseout.
   *
   * @type {boolean}
   */
  #downed = false;

  /**
   * Pointer position at mousedown or touchstart, used to measure
   * {@link MOVE_TOLERANCE}.
   *
   * @type {Point2D|undefined}
   */
  #downPoint;

  /**
   * @param {LayerGroupPointerOptions} options Constructor options.
   */
  constructor({
    stageController,
    dragBehavior,
    hoverBehavior,
    wheelBehavior,
    doubleClickBehavior,
    twoTouchBehavior,
    tapBehavior,
    longTouchToDblClickMs = 500
  }) {
    super();
    this.#stageController = stageController;
    this.#dragBehavior = dragBehavior;
    this.#hoverBehavior = hoverBehavior;
    this.#wheelBehavior = wheelBehavior;
    this.#doubleClickBehavior = doubleClickBehavior;
    this.#twoTouchBehavior = twoTouchBehavior;
    this.#tapBehavior = tapBehavior;
    this.#longTouchToDblClickMs = longTouchToDblClickMs;
  }

  /**
   * Get the layer group associated with a div id.
   *
   * @param {string} divId The div id.
   * @returns {LayerGroup|undefined} The layer group,
   *   or undefined if not found.
   */
  #getLayerGroupByDivId(divId) {
    return this.#stageController.getLayerGroupByDivId(divId);
  }

  /**
   * Mouse position and layer group from a DOM event targeting a view layer.
   *
   * @param {MouseEvent} event The mouse or touch event.
   * @returns {{point: Point2D, layerGroup: LayerGroup}}
   *   Pointer position and layer group.
   */
  #getMouseLayerContext(event) {
    const layerDetails = getLayerDetailsFromEvent(event);
    const layerGroup = this.#getLayerGroupByDivId(layerDetails.groupDivId);
    return {
      point: getMousePoint(event),
      layerGroup
    };
  }

  /**
   * Live check of a pointer position against {@link #downPoint}: false
   * (tap jitter, not a move) while within {@link MOVE_TOLERANCE}.
   *
   * @param {Point2D} point Pointer position to check, typically at
   *   mouseup/touchend.
   * @returns {boolean} True when the point is more than
   *   {@link MOVE_TOLERANCE} display pixels away from the down point.
   */
  #isMoved(point) {
    return typeof this.#downPoint === 'undefined' ||
      this.#downPoint.getDistance(point) > MOVE_TOLERANCE;
  }

  /**
   * First touch position and layer group from a touch event.
   *
   * @param {TouchEvent} event The touch event.
   * @returns {{point: Point2D, layerGroup: LayerGroup}}
   *   Primary touch point and layer group.
   */
  #getPrimaryTouchLayerContext(event) {
    const layerDetails = getLayerDetailsFromEvent(event);
    const layerGroup = this.#getLayerGroupByDivId(layerDetails.groupDivId);
    return {
      point: getTouchPoints(event)[0],
      layerGroup
    };
  }

  /**
   * Get the list of event names that this tool can fire.
   * Default implementation returns an empty array.
   *
   * @returns {string[]} The list of event names.
   */
  getEventNames() {
    return [];
  }

  /**
   * Handle mouse wheel. Prevents the default (page scroll) only
   * when the tool has a wheel behaviour.
   *
   * @param {WheelEvent} event The mouse wheel event.
   */
  wheel = (event) => {
    if (typeof this.#wheelBehavior === 'undefined') {
      return;
    }
    event.preventDefault();
    const layerDetails = getLayerDetailsFromEvent(event);
    const layerGroup = this.#getLayerGroupByDivId(layerDetails.groupDivId);
    this.#wheelBehavior.onWheel(event, layerGroup);

    this.#wheelTick.add(event);
    const up = this.#wheelTick.getSum() >= 0;
    if (!this.#wheelTick.isTick()) {
      return;
    }
    this.#wheelTick.clear();

    this.#wheelBehavior.onWheelTick(up, layerGroup);
  };

  /**
   * @param {MouseEvent} event The double click event.
   */
  dblclick = (event) => {
    if (TOUCH_EVENTS_DEBUG) {
      return;
    }

    const {point, layerGroup} = this.#getMouseLayerContext(event);
    if (typeof this.#doubleClickBehavior !== 'undefined') {
      this.#doubleClickBehavior.onDoubleClick(point, layerGroup);
    } else if (this.#tapBehavior?.isActive()) {
      this.#tapBehavior.onEnd();
    }
  };

  /**
   * @param {Point2D} point Display point.
   * @param {LayerGroup} layerGroup Layer group.
   */
  #longTouch(point, layerGroup) {
    // similar to this.dblclick
    if (typeof this.#doubleClickBehavior !== 'undefined') {
      this.#doubleClickBehavior.onDoubleClick(point, layerGroup);
    } else if (this.#tapBehavior?.isActive()) {
      // add last point
      this.#tapBehavior.onTap(point, layerGroup);
      this.#tapBehavior.onEnd();
    }
    // avoid tap on touchend
    this.#downed = false;
    // reset timer
    this.#longTouchTimerId = undefined;
  };

  /**
   * End behaviors that have end method.
   */
  cancel() {
    this.#downed = false;
    this.#downPoint = undefined;
    this.#clearLongTouchTimer();

    // reset drag
    if (this.#dragBehavior?.isActive()) {
      this.#dragBehavior.reset();
    }
    // reset sticky tap
    if (this.#tapBehavior?.isActive()) {
      this.#tapBehavior.reset();
    }
    // reset two touch
    if (this.#twoTouchBehavior?.isActive()) {
      this.#twoTouchBehavior?.reset();
    }
    // reset hover
    this.#hoverBehavior?.reset();
  }

  /**
   * Handle mouse down.
   *
   * @param {MouseEvent} event The mouse down event.
   */
  mousedown = (event) => {
    if (TOUCH_EVENTS_DEBUG) {
      return;
    }
    // reset
    if (this.#dragBehavior?.isActive()) {
      this.#dragBehavior.reset();
    }
    // context
    const {point, layerGroup} = this.#getMouseLayerContext(event);
    // set flags
    this.#downed = true;
    this.#downPoint = point;

    if (!this.#tapBehavior?.isActive() &&
      this.#dragBehavior?.canStart(point, layerGroup)) {
      this.#dragBehavior.onStart(point, layerGroup, {
        mouseDownButton: event.button
      });
    }
  };

  /**
   * Handle mouse move.
   *
   * @param {MouseEvent} event The mouse move event.
   */
  mousemove = (event) => {
    if (TOUCH_EVENTS_DEBUG) {
      return;
    }
    // context
    const {point, layerGroup} = this.#getMouseLayerContext(event);

    if (this.#downed) {
      // remove hover for down+move
      this.#hoverBehavior?.onEnd();
      // update drag
      if (this.#dragBehavior?.isActive()) {
        this.#dragBehavior.onUpdate(point, layerGroup);
      }
    } else {
      // update sticky tap
      if (this.#tapBehavior?.isActive()) {
        this.#tapBehavior.onUpdate(point, layerGroup);
      }
      // update hover
      this.#hoverBehavior?.onUpdate(point, layerGroup);
    }
  };

  /**
   * Handle mouse up.
   *
   * @param {MouseEvent} event The mouse up event.
   */
  mouseup = (event) => {
    if (TOUCH_EVENTS_DEBUG) {
      return;
    }
    // context
    const {point, layerGroup} = this.#getMouseLayerContext(event);
    const moved = this.#isMoved(point);

    if (this.#dragBehavior?.isActive()) {
      if (moved) {
        // up+move -> end drag
        this.#dragBehavior.onEnd();
      } else {
        // up and no move -> reset drag
        this.#dragBehavior.reset();
      }
    }

    if (this.#tapBehavior &&
      (this.#tapBehavior.isActive() || (this.#downed && !moved))) {
      // active tap -> sticky tap
      // down + no move -> discrete tap
      this.#tapBehavior.onTap(point, layerGroup);
    }

    // reset flag
    this.#downed = false;
  };

  /**
   * @param {MouseEvent} _event The mouse out event.
   */
  mouseout = (_event) => {
    if (TOUCH_EVENTS_DEBUG) {
      return;
    }

    // end drag
    if (this.#dragBehavior?.isActive()) {
      this.#dragBehavior.onEnd();
    }
    // end sticky tap
    if (this.#tapBehavior?.isActive()) {
      this.#tapBehavior.onEnd();
    }
    // end hover
    this.#hoverBehavior?.onEnd();
    // reset flags
    this.#downed = false;
    this.#downPoint = undefined;
  };

  /**
   * Handle touch start. Always prevents the default to stop the browser
   * from scrolling or zooming the page and from emulating mouse events
   * (which would be handled a second time by the mouse handlers).
   *
   * @param {TouchEvent} event The touch start event.
   */
  touchstart = (event) => {
    event.preventDefault();
    // reset
    if (this.#dragBehavior?.isActive()) {
      this.#dragBehavior.reset();
    }
    this.#clearLongTouchTimer();
    // get touch points
    const touchPoints = getTouchPoints(event);
    // set flags
    this.#downed = true;
    this.#downPoint = touchPoints[0];

    if (touchPoints.length === 1) {
      // one touch drag
      const {point, layerGroup} = this.#getPrimaryTouchLayerContext(event);
      if (this.#dragBehavior?.canStart(point, layerGroup)) {
        this.#dragBehavior.onStart(point, layerGroup, {});
      }
      // long single touch to dblclick
      const delay = this.#longTouchToDblClickMs;
      if (delay !== null && delay !== undefined && delay > 0) {
        // @ts-expect-error -- recommended type is ReturnType<typeof
        //   setTimeout> but lint does not like it
        this.#longTouchTimerId = setTimeout(() => {
          this.#longTouch(point, layerGroup);
        }, delay);
      }
    } else if (touchPoints.length === 2) {
      this.#twoTouchBehavior?.onStart(touchPoints);
    }
  };

  /**
   * @param {TouchEvent} event The touch move event.
   */
  touchmove = (event) => {
    // reset
    this.#clearLongTouchTimer();

    // context
    const {point, layerGroup} = this.#getPrimaryTouchLayerContext(event);

    const touchPoints = getTouchPoints(event);
    if (touchPoints.length === 1) {
      // one touch drag
      if (this.#dragBehavior?.isActive()) {
        this.#dragBehavior.onUpdate(point, layerGroup);
      }
    } else if (touchPoints.length === 2) {
      // Transition frames may have two touches before two-touch is active.
      if (this.#dragBehavior?.isActive()) {
        this.#dragBehavior.reset();
      }
      if (this.#twoTouchBehavior?.isActive()) {
        this.#twoTouchBehavior.onUpdate(touchPoints, layerGroup);
      }
    }
  };

  /**
   * @param {TouchEvent} event The touch end event.
   */
  touchend = (event) => {
    // reset
    this.#clearLongTouchTimer();

    if (this.#twoTouchBehavior?.isActive()) {
      this.#twoTouchBehavior.onEnd();
      return;
    }

    // context
    const {point, layerGroup} = this.#getPrimaryTouchLayerContext(event);
    const moved = this.#isMoved(point);

    if (this.#dragBehavior?.isActive()) {
      if (moved) {
        // up+move -> end drag
        this.#dragBehavior.onEnd();
      } else {
        // up and no move -> reset drag
        this.#dragBehavior.reset();
      }
    }

    if (this.#tapBehavior &&
      (this.#tapBehavior.isActive() || (this.#downed && !moved))) {
      // active tap -> sticky tap
      // down + no move -> discrete tap
      this.#tapBehavior.onTap(point, layerGroup);
    }

    // reset flag
    this.#downed = false;
  };

  /**
   * Handle touch cancel: the browser or the system interrupted the touch
   * (for example an incoming call or an OS gesture), end it with
   * {@link LayerGroupPointer#cancel}.
   *
   * @param {TouchEvent} _event The touch cancel event.
   */
  touchcancel = (_event) => {
    this.cancel();
  };

  #clearLongTouchTimer() {
    if (typeof this.#longTouchTimerId !== 'undefined') {
      clearTimeout(this.#longTouchTimerId);
      this.#longTouchTimerId = undefined;
    }
  }

}