Source code
Revision control
Copy as Markdown
Other Tools
/* 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
/**
* 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 = "";
}
}
// 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
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);