firefox/browser/components/customizableui/DragPositionManager.sys.mjs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * A cache of AreaPositionManagers weakly mapped to customization area nodes.
 *
 * @type {WeakMap<DOMNode, AreaPositionManager>}
 */
var gManagers = new WeakMap();

const kPaletteId = "customization-palette";

/**
 * An AreaPositionManager is used to power the animated drag-and-drop grid
 * behaviour of each customizable area (toolbars, the palette, the overflow
 * panel) while in customize mode. Each customizable area has its own
 * AreaPositionManager, per browser window.
 */
class AreaPositionManager {
  /**
   * True if the container is oriented from right-to-left.
   *
   * @type {boolean}
   */
  #rtl = false;

  /**
   * A DOMRectReadOnly for the bounding client rect for the container,
   * collected once during construction.
   *
   * @type {DOMRectReadOnly|null}
   */
  #containerInfo = null;

  /**
   * The calculated horizontal distance between the first two visible child
   * nodes of the container.
   *
   * @type {number}
   */
  #horizontalDistance = 0;

  /**
   * The ratio of the width of the container and the height of the first
   * visible child node. This is used in the weighted cartesian distance
   * calculation used in the AreaPositionManager.find method.
   *
   * @see AreaPositionManager.find
   * @type {number}
   */
  #heightToWidthFactor = 0;

  /**
   * Constructs an instance of AreaPositionManager for a customizable area.
   *
   * @param {DOMNode} aContainer
   *   The customizable area container node for which drag-and-drop animations
   *   are to be calculated for.
   */
  constructor(aContainer) {
    // Caching the direction and bounds of the container for quick access later:
    this.#rtl = aContainer.ownerGlobal.RTL_UI;
    this.#containerInfo = DOMRectReadOnly.fromRect(
      aContainer.getBoundingClientRect()
    );
    this.update(aContainer);
  }

  /**
   * A cache of container child node size and position data.
   *
   * @type {WeakMap<DOMNode, DOMRectReadOnly>}
   */
  #nodePositionStore = new WeakMap();

  /**
   * The child node immediately after the most recently placed placeholder. May
   * be null if no placeholder has been inserted yet, or if the placeholder is
   * at the end of the container.
   *
   * @type {DOMNode|null}
   */
  #lastPlaceholderInsertion = null;

  /**
   * Iterates the visible children of the container, sampling their bounding
   * client rects and storing them in a local cache. Also collects and stores
   * metrics like the horizontal distance between the first two children,
   * the height of the first item, and a ratio between the width of the
   * container and the height of the first child item.
   *
   * @param {DOMNode} aContainer
   *   The container node to collect the measurements for.
   */
  update(aContainer) {
    let last = null;
    let singleItemHeight;
    for (let child of aContainer.children) {
      if (child.hidden) {
        continue;
      }
      let coordinates = this.#lazyStoreGet(child);
      // We keep a baseline horizontal distance between nodes around
      // for use when we can't compare with previous/next nodes
      if (!this.#horizontalDistance && last) {
        this.#horizontalDistance = coordinates.left - last.left;
      }
      // We also keep the basic height of items for use below:
      if (!singleItemHeight) {
        singleItemHeight = coordinates.height;
      }
      last = coordinates;
    }
    this.#heightToWidthFactor = this.#containerInfo.width / singleItemHeight;
  }

  /**
   * Find the closest node in the container given the coordinates.
   * "Closest" is defined in a somewhat strange manner: we prefer nodes
   * which are in the same row over nodes that are in a different row.
   * In order to implement this, we use a weighted cartesian distance
   * where dy is more heavily weighted by a factor corresponding to the
   * ratio between the container's width and the height of its elements.
   *
   * @param {DOMNode} aContainer
   *   The container element that contains one or more rows of child elements
   *   in some kind of grid formation.
   * @param {number} aX
   *   The X horizontal coordinate that we're finding the closest child node
   *   for.
   * @param {number} aY
   *   The Y vertical coordinate that we're finding the closest child node
   *   for.
   * @returns {DOMNode|null}
   *   The closest node to the aX and aY coordinates, preferring child nodes
   *   in the same row of the grid. This may also return the container itself,
   *   if the coordinates are on the outside edge of the last node in the
   *   container.
   */
  find(aContainer, aX, aY) {
    let closest = null;
    let minCartesian = Number.MAX_VALUE;
    let containerX = this.#containerInfo.left;
    let containerY = this.#containerInfo.top;

    // First, iterate through all children and find the closest child to the
    // aX and aY coordinates (preferring children in the same row as the aX
    // and aY coordinates).
    for (let node of aContainer.children) {
      let coordinates = this.#lazyStoreGet(node);
      let offsetX = coordinates.x - containerX;
      let offsetY = coordinates.y - containerY;
      let hDiff = offsetX - aX;
      let vDiff = offsetY - aY;
      // Then compensate for the height/width ratio so that we prefer items
      // which are in the same row:
      hDiff /= this.#heightToWidthFactor;

      let cartesianDiff = hDiff * hDiff + vDiff * vDiff;
      if (cartesianDiff < minCartesian) {
        minCartesian = cartesianDiff;
        closest = node;
      }
    }

    // Now refine our result based on whether or not we're closer to the outside
    // edge of the closest node. If we are, we actually want to return the
    // closest node's sibling, because this is the one we'll style to indicate
    // the drop position.
    if (closest) {
      let targetBounds = this.#lazyStoreGet(closest);
      let farSide = this.#rtl ? "left" : "right";
      let outsideX = targetBounds[farSide];
      // Check if we're closer to the next target than to this one:
      // Only move if we're not targeting a node in a different row:
      if (aY > targetBounds.top && aY < targetBounds.bottom) {
        if ((!this.#rtl && aX > outsideX) || (this.#rtl && aX < outsideX)) {
          return closest.nextElementSibling || aContainer;
        }
      }
    }
    return closest;
  }

  /**
   * "Insert" a "placeholder" by shifting the subsequent children out of the
   * way. We go through all the children, and shift them based on the position
   * they would have if we had inserted something before aBefore. We use CSS
   * transforms for this, which are CSS transitioned.
   *
   * @param {DOMNode} aContainer
   *   The container of the nodes for which we are inserting the placeholder
   *   and shifting the child nodes.
   * @param {DOMNode} aBefore
   *   The child node before which we are inserting the placeholder.
   * @param {DOMRectReadOnly} aSize
   *   The size of the placeholder to create.
   * @param {boolean} aIsFromThisArea
   *   True if the node being dragged happens to be from this container, as
   *   opposed to some other container (like a toolbar, for instance).
   */
  insertPlaceholder(aContainer, aBefore, aSize, aIsFromThisArea) {
    let isShifted = false;
    for (let child of aContainer.children) {
      // Don't need to shift hidden nodes:
      if (child.hidden) {
        continue;
      }
      // If this is the node before which we're inserting, start shifting
      // everything that comes after. One exception is inserting at the end
      // of the menupanel, in which case we do not shift the placeholders:
      if (child == aBefore) {
        isShifted = true;
      }
      if (isShifted) {
        if (aIsFromThisArea && !this.#lastPlaceholderInsertion) {
          child.setAttribute("notransition", "true");
        }
        // Determine the CSS transform based on the next node and apply it.
        child.style.transform = this.#diffWithNext(child, aSize);
      } else {
        // If we're not shifting this node, reset the transform
        child.style.transform = "";
      }
    }

    // Bug 959848: without this routine, when we start the drag of an item in
    // the customization palette, we'd take the dragged item out of the flow of
    // the document, and _then_ insert the placeholder, creating a lot of motion
    // on the initial drag. We mask this case by removing the item and inserting
    // the placeholder for the dragged item in a single shot without animation.
    if (
      aContainer.lastElementChild &&
      aIsFromThisArea &&
      !this.#lastPlaceholderInsertion
    ) {
      // Flush layout to force the snap transition.
      aContainer.lastElementChild.getBoundingClientRect();
      // then remove all the [notransition]
      for (let child of aContainer.children) {
        child.removeAttribute("notransition");
      }
    }
    this.#lastPlaceholderInsertion = aBefore;
  }

  /**
   * Reset all the transforms in this container, optionally without
   * transitioning them.
   *
   * @param {DOMNode} aContainer
   *   The container in which to reset the transforms.
   * @param {boolean} aNoTransition
   *   If truthy, adds a notransition attribute to the node while resetting the
   *   transform. It is assumed that a CSS rule will interpret the notransition
   *   attribute as a directive to skip transition animations.
   */
  clearPlaceholders(aContainer, aNoTransition) {
    for (let child of aContainer.children) {
      if (aNoTransition) {
        child.setAttribute("notransition", true);
      }
      child.style.transform = "";
      if (aNoTransition) {
        // Need to force a reflow otherwise this won't work. :(
        child.getBoundingClientRect();
        child.removeAttribute("notransition");
      }
    }
    // We snapped back, so we can assume there's no more
    // "last" placeholder insertion point to keep track of.
    if (aNoTransition) {
      this.#lastPlaceholderInsertion = null;
    }
  }

  /**
   * Determines the transform rule to apply to aNode to reposition it to
   * accommodate a placeholder drop target for a dragged node of aSize.
   *
   * @param {DOMNode} aNode
   *   The node to calculate the transform rule for.
   * @param {DOMRectReadOnly} aSize
   *   The size of the placeholder drop target that was inserted which then
   *   requires us to reposition this node.
   * @returns {string}
   *   The CSS transform rule to apply to aNode.
   */
  #diffWithNext(aNode, aSize) {
    let xDiff;
    let yDiff = null;
    let nodeBounds = this.#lazyStoreGet(aNode);
    let side = this.#rtl ? "right" : "left";
    let next = this.#getVisibleSiblingForDirection(aNode, "next");
    // First we determine the transform along the x axis.
    // Usually, there will be a next node to base this on:
    if (next) {
      let otherBounds = this.#lazyStoreGet(next);
      xDiff = otherBounds[side] - nodeBounds[side];
      // We set this explicitly because otherwise some strange difference
      // between the height and the actual difference between line creeps in
      // and messes with alignments
      yDiff = otherBounds.top - nodeBounds.top;
    } else {
      // We don't have a sibling whose position we can use. First, let's see
      // if we're also the first item (which complicates things):
      let firstNode = this.#firstInRow(aNode);
      if (aNode == firstNode) {
        // Maybe we stored the horizontal distance between nodes,
        // if not, we'll use the width of the incoming node as a proxy:
        xDiff = this.#horizontalDistance || (this.#rtl ? -1 : 1) * aSize.width;
      } else {
        // If not, we should be able to get the distance to the previous node
        // and use the inverse, unless there's no room for another node (ie we
        // are the last node and there's no room for another one)
        xDiff = this.#moveNextBasedOnPrevious(aNode, nodeBounds, firstNode);
      }
    }

    // If we've not determined the vertical difference yet, check it here
    if (yDiff === null) {
      // If the next node is behind rather than in front, we must have moved
      // vertically:
      if ((xDiff > 0 && this.#rtl) || (xDiff < 0 && !this.#rtl)) {
        yDiff = aSize.height;
      } else {
        // Otherwise, we haven't
        yDiff = 0;
      }
    }
    return "translate(" + xDiff + "px, " + yDiff + "px)";
  }

  /**
   * Helper function to find the horizontal transform value for a node if there
   * isn't a next node to base that on.
   *
   * @param {DOMNode} aNode
   *   The node to have the transform applied to.
   * @param {DOMRectReadOnly} aNodeBounds
   *   The bounding rect info of aNode.
   * @param {DOMNode} aFirstNodeInRow
   *   The first node in aNode's row in the container grid.
   * @returns {number}
   *   The horizontal distance to transform aNode.
   */
  #moveNextBasedOnPrevious(aNode, aNodeBounds, aFirstNodeInRow) {
    let next = this.#getVisibleSiblingForDirection(aNode, "previous");
    let otherBounds = this.#lazyStoreGet(next);
    let side = this.#rtl ? "right" : "left";
    let xDiff = aNodeBounds[side] - otherBounds[side];
    // If, however, this means we move outside the container's box
    // (i.e. the row in which this item is placed is full)
    // we should move it to align with the first item in the next row instead
    let bound = this.#containerInfo[this.#rtl ? "left" : "right"];
    if (
      (!this.#rtl && xDiff + aNodeBounds.right > bound) ||
      (this.#rtl && xDiff + aNodeBounds.left < bound)
    ) {
      xDiff = this.#lazyStoreGet(aFirstNodeInRow)[side] - aNodeBounds[side];
    }
    return xDiff;
  }

  /**
   * Get the DOMRectReadOnly for a node from our cache. If the rect is not yet
   * cached, calculate that rect and cache it now.
   *
   * @param {DOMNode} aNode
   *   The node whose DOMRectReadOnly that we want.
   * @returns {DOMRectReadOnly}
   *   The size and position of aNode that was either just calculated, or
   *   previously calculated during the lifetime of this AreaPositionManager and
   *   cached.
   */
  #lazyStoreGet(aNode) {
    let rect = this.#nodePositionStore.get(aNode);
    if (!rect) {
      // getBoundingClientRect() returns a DOMRect that is live, meaning that
      // as the element moves around, the rects values change. We don't want
      // that - we want a snapshot of what the rect values are right at this
      // moment, and nothing else. So we have to clone the values as a
      // DOMRectReadOnly.
      rect = DOMRectReadOnly.fromRect(aNode.getBoundingClientRect());
      this.#nodePositionStore.set(aNode, rect);
    }
    return rect;
  }

  /**
   * Returns the first node in aNode's row in the container grid.
   *
   * @param {DOMNode} aNode
   *   The node in the row for which we want to find the first node.
   * @returns {DOMNode}
   */
  #firstInRow(aNode) {
    // XXXmconley: I'm not entirely sure why we need to take the floor of these
    // values - it looks like, periodically, we're getting fractional pixels back
    // from lazyStoreGet. I've filed bug 994247 to investigate.
    let bound = Math.floor(this.#lazyStoreGet(aNode).top);
    let rv = aNode;
    let prev;
    while (rv && (prev = this.#getVisibleSiblingForDirection(rv, "previous"))) {
      if (Math.floor(this.#lazyStoreGet(prev).bottom) <= bound) {
        return rv;
      }
      rv = prev;
    }
    return rv;
  }

  /**
   * Returns the next visible sibling DOMNode to aNode in the direction
   * aDirection.
   *
   * @param {DOMNode} aNode
   *   The node to get the next visible sibling for.
   * @param {string} aDirection
   *   One of either "previous" or "next". Any other value will probably throw.
   * @returns {DOMNode}
   */
  #getVisibleSiblingForDirection(aNode, aDirection) {
    let rv = aNode;
    do {
      rv = rv[aDirection + "ElementSibling"];
    } while (rv && rv.hidden);
    return rv;
  }
}

/**
 * DragPositionManager manages the AreaPositionManagers for all of the
 * grid-like customizable areas. These days, that's just the customization
 * palette.
 */
export var DragPositionManager = {
  /**
   * Starts CustomizeMode drag position management for a window aWindow.
   *
   * @param {DOMWindow} aWindow
   *   The browser window to start drag position management in.
   */
  start(aWindow) {
    let paletteArea = aWindow.document.getElementById(kPaletteId);
    let positionManager = gManagers.get(paletteArea);
    if (positionManager) {
      positionManager.update(paletteArea);
    } else {
      // This gManagers WeakMap may have made more sense when we had the
      // menu panel also acting as a grid. It's maybe superfluous at this point.
      gManagers.set(paletteArea, new AreaPositionManager(paletteArea));
    }
  },

  /**
   * Stops CustomizeMode drag position management for all windows.
   */
  stop() {
    gManagers = new WeakMap();
  },

  /**
   * Returns the AreaPositionManager instance for a particular aArea DOMNode,
   * if one has been created.
   *
   * @param {DOMNode} aArea
   * @returns {AreaPositionManager|null}
   */
  getManagerForArea(aArea) {
    return gManagers.get(aArea);
  },
};

Object.freeze(DragPositionManager);