bm-core-ui 2.11.8 → 2.11.9-beta.1

package/build/BMWindow/BMPopover/BMPopover.js

@@ -1,21 +1,172 @@
 // @ts-check
 
-import { BMExtend, NO, YES, BMCopyProperties, BMNumberByConstrainingNumberToBounds, BMUUIDMake } from "../../Core/BMCoreUI";
+import { BMExtend, NO, YES, BMCopyProperties, BMNumberByConstrainingNumberToBounds, BMUUIDMake, BMNumberByInterpolatingNumbersWithFraction } from "../../Core/BMCoreUI";
 import { BMWindow } from "../BMWindow";
 import { BMRectMakeWithOrigin, BMRectMakeWithNodeFrame, BMRectMake } from "../../Core/BMRect";
 import { BMPointMake } from "../../Core/BMPoint";
-import { BMHook, __BMVelocityAnimate } from "../../Core/BMAnimationContext";
+import { BMAnimateWithBlock, BMAnimationApplyBlocking, BMAnimationBeginWithDuration, BMAnimationContext, BMAnimationContextAddCompletionHandler, BMAnimationContextBeginStatic, BMAnimationContextGetCurrent, BMHook, __BMVelocityAnimate } from "../../Core/BMAnimationContext";
 import { BMView, BMViewColorScheme } from "../../BMView/BMView_v2.5";
 import { BMInsetMakeWithEqualInsets } from "../../Core/BMInset";
 
-// @type BMPopoverIndicatorDirection
+
+/**
+ * The number of pixels a touch or clicked pointer can wander off before causing a popover to detach.
+ */
+const BMPopoverDragThreshold = 128; // <Number>
+
+// @type _BMPopoverDisplayConfiguration implements BMAnimating
+
+/**
+ * A class that describes the display attributes of a popover and supports interpolation.
+ */
+function _BMPopoverDisplayConfiguration() {} // <constructor>
+
+_BMPopoverDisplayConfiguration.prototype = {
+    /**
+     * The popover's frame, excluding the indicator's size.
+     */
+    _frame: undefined, // <BMRect>
+
+    /**
+     * The indicator's direction relative to the popover's anchor.
+     */
+    _direction: undefined, // <BMPopoverIndicatorDirection>
+
+    /**
+     * The indicator's position along the popover's edge.
+     */
+    _indicatorPosition: undefined, // <Number>
+
+    /**
+     * The size of the indicator.
+     */
+    _indicatorSize: undefined, // <Number>
+
+    /**
+     * The round radius of the popover's corners.
+     */
+    _borderRadius: undefined, // <Number>
+
+    /**
+     * The height of the visible portion of the indicator.
+     */
+    get _indicatorHeight() { // <Number>
+        // The indicator height represents the edge size of the indicator square;
+        // Therefore its total width/height represents the diagonal of that square
+        // and its visible height is half of the square's diagonal
+        const indicatorWidth = this._indicatorSize * Math.SQRT2;
+        return indicatorWidth / 2 | 0;
+    },
+
+    /**
+     * Initializes this popover popover display configuration object with the specified values.
+     * @param frame <BMRect>                            The popover's frame.
+     * {
+     *  @param direction <BMPopoverIndicatorDirection>  The indicator's direction relative to the popover's anchor.
+     *  @param indicatorPosition <Number>               The indicator's position relative to the popover's edge.
+     *  @param indicatorSize <Number>                   The size of the indicator.
+     *  @param borderRadius <Number>                    The size of the popover's corners.
+     * }
+     * @returns <_BMPopoverDisplayConfiguration>        This popover display configuration.
+     */
+    initWithFrame(frame, {direction, indicatorPosition, indicatorSize, borderRadius}) {
+        this._frame = frame.copy();
+        this._direction = direction;
+        this._indicatorPosition = indicatorPosition;
+        this._indicatorSize = indicatorSize;
+        this._borderRadius = borderRadius;
+
+        return this;
+    },
+
+    /**
+     * Initializes this popover popover display configuration object by copying the values of
+     * the specified popover display configuration.
+     * @param config <_BMPopoverDisplayConfiguration>   The configuration whose values to copy.
+     * @returns <_BMPopoverDisplayConfiguration>        This popover display configuration.
+     */
+    initWithPopoverDisplayConfiguration(config) {
+        this._frame = config._frame.copy();
+        this._direction = config._direction;
+        this._indicatorPosition = config._indicatorPosition;
+        this._indicatorSize = config._indicatorSize;
+        this._borderRadius = config._borderRadius;
+
+        return this;
+    },
+
+    /**
+     * Creates and returns a copy of this popover display configuration.
+     * @returns <_BMPopoverDisplayConfiguration>        A copy of this object.
+     */
+    copy() {
+        return (new _BMPopoverDisplayConfiguration).initWithPopoverDisplayConfiguration(this);
+    },
+
+    /**
+     * Invoked by the CoreUI animation engine to obtain an interpolated
+     * value between this object and the target object.
+     * @param fraction <Number>                         The animation fraction.
+     * {
+     *  @param toValue <_BMPopoverDisplayConfiguration> The object to which to interpolate.
+     * }
+	 * @return <_BMPopoverDisplayConfiguration>		    A popover display configuration.
+     */
+    interpolatedValueWithFraction(fraction, {toValue: target}) {
+        const copy = this.copy();
+
+        copy._frame = this._frame.interpolatedValueWithFraction(fraction, {toValue: target._frame});
+
+        if (this._direction == target._direction) {
+            // When the direction remains the same animate all other indicator properties smoothly
+            copy._indicatorPosition = BMNumberByInterpolatingNumbersWithFraction(this._indicatorPosition, target._indicatorPosition, fraction);
+            copy._indicatorSize = BMNumberByInterpolatingNumbersWithFraction(this._indicatorSize, target._indicatorSize, fraction);
+        }
+        else {
+            // Otherwise hide then indicator from its source direction then reveal it at the target direction over the course of the animation
+            if (fraction < 0.5) {
+                // In the first half, hide the indicator, keeping it in the source direction
+                copy._direction = this._direction;
+                copy._indicatorPosition = this._indicatorPosition;
+                copy._indicatorSize = BMNumberByInterpolatingNumbersWithFraction(this._indicatorSize, 0, fraction * 2);
+            }
+            else {
+                // In the second half, show the indicator, keeping it in the target direction
+                copy._direction = target._direction;
+                copy._indicatorPosition = target._indicatorPosition;
+                copy._indicatorSize = BMNumberByInterpolatingNumbersWithFraction(0, target._indicatorSize, (fraction - 0.5) * 2);
+            }
+        }
+
+        copy._borderRadius = BMNumberByInterpolatingNumbersWithFraction(this._borderRadius, target._borderRadius, fraction);
+
+        return copy;
+    },
+};
+
+/**
+ * Creates and returns a popover display configuration object initialized with the specified values.
+ * @param frame <BMRect>                            The popover's frame.
+ * {
+ *  @param direction <BMPopoverIndicatorDirection>  The indicator's direction relative to the popover's anchor.
+ *  @param indicatorPosition <Number>               The indicator's position relative to the popover's edge.
+ *  @param indicatorSize <Number>                   The size of the indicator.
+ *  @param borderRadius <Number>                    The size of the popover's corners.
+ * }
+ * @returns <_BMPopoverDisplayConfiguration>        A popover display configuration.
+ */
+_BMPopoverDisplayConfiguration.configurationWithFrame = function (frame, args) {
+    return (new this).initWithFrame(frame, args);
+};
 
 // @endtype
 
+// @type BMPopoverIndicatorDirection
+
 /**
  * Constants describing the position where the indicator appears on its popover.
  */
- export var BMPopoverIndicatorDirection = Object.freeze({ // <enum>
+export var BMPopoverIndicatorDirection = Object.freeze({ // <enum>
 	/**
 	 * Causes the popover indicator to appear on the top edge of the popover.
 	 */
@@ -37,6 +188,8 @@ import { BMInsetMakeWithEqualInsets } from "../../Core/BMInset";
 	Right: "Right" // <enum>
 });
 
+// @endtype
+
 // @type BMPopover extends BMWindow
 
 /**
@@ -49,9 +202,14 @@ import { BMInsetMakeWithEqualInsets } from "../../Core/BMInset";
 export function BMPopover() {} // <constructor>
 
 BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
+	
+	/**
+	 * An optional delegate which this popover may notify of key events.
+	 */
+	delegate: undefined, // <BMPopoverDelegate, nullable>
 
     /**
-     * The point from which this popover should originate, relative to the document. Either this property
+     * Animatable. The point from which this popover should originate, relative to the document. Either this property
      * or `anchorNode` or `anchorRect` must be set before this popover is displayed.
      */
     _anchorPoint: undefined, // <BMPoint, nullable>
@@ -60,12 +218,16 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
         return this._anchorPoint;
     },
     set anchorPoint(point) {
+        this._anchorRect = undefined;
+        this._anchorNode = undefined;
         this._anchorPoint = point;
+
+        this._updatePosition();
     },
 
 
     /**
-     * The rect from which this popover should originate, relative to the document. Either this property
+     * Animatable. The rect from which this popover should originate, relative to the document. Either this property
      * or `anchorPoint` or `anchorNode` must be set before this popover is displayed.
      */
     _anchorRect: undefined, // <BMRect, nullable>
@@ -74,12 +236,16 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
         return this._anchorRect;
     },
     set anchorRect(rect) {
+        this._anchorPoint = undefined;
+        this._anchorNode = undefined;
         this._anchorRect = rect;
+
+        this._updatePosition();
     },
 
 
     /**
-     * The element from which this popover should originate. Either this property
+     * Animatable. The element from which this popover should originate. Either this property
      * or `anchorPoint` or `anchorRect` must be set before this popover is displayed.
      */
     _anchorNode: undefined, // <DOMNode, nullable>
@@ -88,7 +254,11 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
         return this._anchorNode;
     },
     set anchorNode(node) {
+        this._anchorRect = undefined;
+        this._anchorPoint = undefined;
         this._anchorNode = node;
+
+        this._updatePosition();
     },
 
     /**
@@ -101,6 +271,8 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     },
     set size(size) {
         this._size = size.copy();
+
+        this._updatePosition();
     },
 
     /**
@@ -113,6 +285,8 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     },
     set indicatorSize(size) {
         this._indicatorSize = size;
+
+        this._updatePosition();
     },
 
     /**
@@ -125,6 +299,8 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     },
     set borderRadius(radius) {
         this._borderRadius = radius;
+
+        this._updatePosition();
     },
 
     /**
@@ -139,11 +315,7 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     set edgeInsets(margin) {
         this._edgeInsets = margin || BMInsetMakeWithEqualInsets(8);
 
-        if (this.isVisible) {
-            // If this is updated while the popover is visible, update its position accordingly
-            // TODO: Only update when this would actually change the position
-            this._updatePosition();
-        }
+        this._updatePosition();
     },
 
     /**
@@ -244,6 +416,8 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     },
     set permittedDirections(directions) {
         this._permittedDirections = directions.slice();
+
+        this._updatePosition();
     },
 
     /**
@@ -340,119 +514,237 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
 	},
 
     /**
-     * Invoked by CoreUI to update this popover's position and recalculate the various paths used by it.
+     * Set to `YES` while this popover is detached. When set to `YES` the popover is detached from
+     * its anchor and can be freely moved. When set to `NO`, the popover remains attached to its
+     * anchor in a fixed position.
      */
-    _updatePosition() {
+    _isDetached: NO, // <Boolean>
+
+    get isDetached() {
+        return this._isDetached;
+    },
+
+    /**
+     * The current detached position of this popover.
+     */
+    _position: undefined, // <BMPoint>
+
+    /**
+     * The popover's current direction. Set to `undefined` until this popover is first displayed.
+     */
+    _direction: undefined, // <BMPopoverIndicatorDirection, nullable>
+
+    /**
+     * Controls whether this popover retains the direction that was set to it when it was first
+     * displayed. When set to `NO`, whenever the popover's size or attributes change it will try
+     * to find a new direction around the anchor. When set to `YES`, the current direction or the
+     * initial display direction will be kept regardless of how the popover changes.
+     * 
+     * When set to `undefined`, this popover will use the behaviour set on the `BMPopover` class.
+     */
+    _retainsDirection: undefined, // <Boolean, nullable>
+
+    get retainsDirection() {
+        return this._retainsDirection ?? BMPopover._retainsDirection;
+    },
+
+    set retainsDirection(retains) {
+        this._retainsDirection = retains;
+    },
+
+    /**
+     * The current display configuration. Set to `undefined` until this popover is first displayed.
+     */
+    _config: undefined, // <_BMPopoverDisplayConfiguration, nullable>
+
+    /**
+     * The current display configuration. Set to `undefined` until this popover is first displayed.
+     */
+    get _displayConfiguration() { // <_BMPopoverDisplayConfiguration, nullable>
+        return this._config;
+    },
+
+    set _displayConfiguration(config) {
+        this._config = config;
+        this._applyDisplayConfiguration(config);
+    },
+
+    /**
+     * Invoked by CoreUI to create a new display configuration for this popover based on the
+     * current values of its properties.
+     * @return <_BMPopoverDisplayConfiguration>         The configuration.
+     */
+    _createDisplayConfiguration() {
         const frame = BMRectMake();
-        frame.size.height = this._size.height + this._indicatorHeight;
+        frame.size.height = this._size.height;
         frame.size.width = this._size.width;
+        frame.origin.x = (this._position?.x ?? this._frame.origin.x) | 0;
+        frame.origin.y = (this._position?.y ?? this._frame.origin.y) | 0;
 
         const nodeFrame = this.anchorRect || (this.anchorNode && BMRectMakeWithNodeFrame(this.anchorNode));
         const location = this.anchorPoint ? this.anchorPoint.copy() : nodeFrame.center;
 
         // Determine the appropriate direction to display this popover
         let direction;
-        if (this.anchorPoint) {
+        if (this._direction && this.retainsDirection) {
+            direction = this._direction;
+        }
+        else if (this.anchorPoint) {
             direction = this._directionAroundPoint(location);
         }
         else {
             direction = this._directionAroundRect(nodeFrame);
         }
 
-        // Adjust the constraints based on the direction
+        if (!this._isDetached) {
+            // If this popover is attached, update the frame's position based on the anchor
+            // Move the frame to the appropriate position based on the selected direction
+            switch (direction) {
+                case BMPopoverIndicatorDirection.Top:
+                    frame.size.height += this._indicatorHeight;
+                    frame.origin.y = this.anchorPoint ? location.y : nodeFrame.bottom - 2;
+    
+                    frame.origin.x = location.x - frame.size.width / 2 | 0;
+    
+                    if (frame.origin.x < this._edgeInsets.left) {
+                        frame.origin.x = this._edgeInsets.left;
+                    }
+                    if (frame.right > window.innerWidth - this._edgeInsets.right) {
+                        frame.origin.x = window.innerWidth - frame.size.width - this._edgeInsets.right;
+                    }
+                    break;
+                case BMPopoverIndicatorDirection.Bottom:
+                    frame.size.height += this._indicatorHeight;
+                    frame.origin.y = this.anchorPoint ? location.y - frame.size.height : nodeFrame.origin.y + 2 - frame.size.height;
+    
+                    frame.origin.x = location.x - frame.size.width / 2 | 0;
+    
+                    if (frame.origin.x < this._edgeInsets.left) {
+                        frame.origin.x = this._edgeInsets.left;
+                    }
+                    if (frame.right > window.innerWidth - this._edgeInsets.right) {
+                        frame.origin.x = window.innerWidth - frame.size.width - this._edgeInsets.right;
+                    }
+                    break;
+                case BMPopoverIndicatorDirection.Right:
+                    frame.size.width += this._indicatorHeight;
+                    frame.origin.x = this.anchorPoint ? location.x - frame.size.width : nodeFrame.origin.x + 2 - frame.size.width;
+    
+                    frame.origin.y = location.y - frame.size.height / 2 | 0;
+    
+                    if (frame.origin.y < this._edgeInsets.top) {
+                        frame.origin.y = this._edgeInsets.top;
+                    }
+                    if (frame.bottom > window.innerHeight - this._edgeInsets.bottom) {
+                        frame.origin.y = window.innerHeight - frame.size.height - this._edgeInsets.bottom;
+                    }
+                    break;
+                case BMPopoverIndicatorDirection.Left:
+                    frame.size.width += this._indicatorHeight;
+                    frame.origin.x = this.anchorPoint ? location.x : nodeFrame.right - 2;
+    
+                    frame.origin.y = location.y - frame.size.height / 2 | 0;
+    
+                    if (frame.origin.y < this._edgeInsets.top) {
+                        frame.origin.y = this._edgeInsets.top;
+                    }
+                    if (frame.bottom > window.innerHeight - this._edgeInsets.bottom) {
+                        frame.origin.y = window.innerHeight - frame.size.height - this._edgeInsets.bottom;
+                    }
+                    break;
+            }
+        }
+        else {
+            // If the popover is detached, prevent it from exceeding the screen's size
+            frame.size.width = BMNumberByConstrainingNumberToBounds(frame.size.width, 0, window.innerWidth);
+            frame.size.height = BMNumberByConstrainingNumberToBounds(frame.size.height, 0, window.innerHeight);
+            frame.origin.x = BMNumberByConstrainingNumberToBounds(frame.origin.x, 0, window.innerWidth - frame.size.width);
+            frame.origin.y = BMNumberByConstrainingNumberToBounds(frame.origin.y, 0, window.innerHeight - frame.size.height);
+        }
+
+        // Determine the indicator's position along its edge
+        let indicatorPosition;
         switch (direction) {
+            case BMPopoverIndicatorDirection.Bottom:
             case BMPopoverIndicatorDirection.Top:
-                frame.origin.y = this.anchorPoint ? location.y : nodeFrame.bottom - 2;
-
-                frame.origin.x = location.x - frame.size.width / 2 | 0;
-
-                if (frame.origin.x < this._edgeInsets.left) {
-                    frame.origin.x = this._edgeInsets.left;
+                if (!this._isDetached) {
+                    frame.size.height -= this._indicatorHeight;
                 }
-                if (frame.right > window.innerWidth - this._edgeInsets.right) {
-                    frame.origin.x = window.innerWidth - frame.size.width - this._edgeInsets.right;
+                indicatorPosition = BMNumberByConstrainingNumberToBounds(location.x - frame.origin.x, this._borderRadius * 1.5 + this._indicatorSize * Math.SQRT2 / 2, frame.size.width - this._borderRadius * 1.5 - this._indicatorSize * Math.SQRT2 / 2);
+                break;
+            case BMPopoverIndicatorDirection.Left:
+            case BMPopoverIndicatorDirection.Right:
+                if (!this._isDetached) {
+                    frame.size.width -= this._indicatorHeight;
                 }
-                
-                this._contentViewTopConstraint.constant = this._indicatorHeight;
+                indicatorPosition = BMNumberByConstrainingNumberToBounds(location.y - frame.origin.y, this._borderRadius * 1.5 + this._indicatorSize * Math.SQRT2 / 2, frame.size.height - this._borderRadius * 1.5 - this._indicatorSize * Math.SQRT2 / 2);
+                break;
+        }
+
+        const indicatorSize = this._isDetached ? 0 : this._indicatorSize;
+
+        const configuration = _BMPopoverDisplayConfiguration.configurationWithFrame(frame, {direction, indicatorSize, indicatorPosition, borderRadius: this._borderRadius});
+        return configuration;
+    },
+
+    /**
+     * Invoked by CoreUI to apply the specified display configuration to this popover and its various SVG elements.
+     * @param config <_BMPopoverDisplayConfiguration>   The configuration to apply.
+     */
+    _applyDisplayConfiguration(config) {
+		if (this.__released) {
+            // Prevent configuration applications from throwing an error if a popover was released while an
+            // animation was playing
+            return;
+        }
+
+        const frame = config._frame.copy();
+        const indicatorHeight = config._indicatorHeight;
+        const direction = config._direction;
+
+        // Adjust the constraints based on the direction
+        switch (direction) {
+            case BMPopoverIndicatorDirection.Top:
+                frame.size.height += indicatorHeight;
+                this._contentViewTopConstraint.constant = indicatorHeight;
                 this._contentViewBottomConstraint.constant = 0;
                 this._contentViewLeftConstraint.constant = 0;
                 this._contentViewRightConstraint.constant = 0;
                 break;
             case BMPopoverIndicatorDirection.Bottom:
-                frame.origin.y = this.anchorPoint ? location.y - frame.size.height : nodeFrame.origin.y + 2 - frame.size.height;
-
-                frame.origin.x = location.x - frame.size.width / 2 | 0;
-
-                if (frame.origin.x < this._edgeInsets.left) {
-                    frame.origin.x = this._edgeInsets.left;
-                }
-                if (frame.right > window.innerWidth - this._edgeInsets.right) {
-                    frame.origin.x = window.innerWidth - frame.size.width - this._edgeInsets.right;
-                }
-                
+                frame.size.height += indicatorHeight;
                 this._contentViewTopConstraint.constant = 0;
-                this._contentViewBottomConstraint.constant = -this._indicatorHeight;
+                this._contentViewBottomConstraint.constant = -indicatorHeight;
                 this._contentViewLeftConstraint.constant = 0;
                 this._contentViewRightConstraint.constant = 0;
                 break;
             case BMPopoverIndicatorDirection.Right:
-                frame.origin.x = this.anchorPoint ? location.x - frame.size.width : nodeFrame.origin.x + 2 - frame.size.width;
-
-                frame.origin.y = location.y - frame.size.height / 2 | 0;
-
-                if (frame.origin.y < this._edgeInsets.top) {
-                    frame.origin.y = this._edgeInsets.top;
-                }
-                if (frame.bottom > window.innerHeight - this._edgeInsets.bottom) {
-                    frame.origin.y = window.innerHeight - frame.size.height - this._edgeInsets.bottom;
-                }
-                
+                frame.size.width += indicatorHeight;
                 this._contentViewTopConstraint.constant = 0;
                 this._contentViewBottomConstraint.constant = 0;
                 this._contentViewLeftConstraint.constant = 0;
-                this._contentViewRightConstraint.constant = -this._indicatorHeight;
+                this._contentViewRightConstraint.constant = -indicatorHeight;
                 break;
             case BMPopoverIndicatorDirection.Left:
-                frame.origin.x = this.anchorPoint ? location.x : nodeFrame.right - 2;
-
-                frame.origin.y = location.y - frame.size.height / 2 | 0;
-
-                if (frame.origin.y < this._edgeInsets.top) {
-                    frame.origin.y = this._edgeInsets.top;
-                }
-                if (frame.bottom > window.innerHeight - this._edgeInsets.bottom) {
-                    frame.origin.y = window.innerHeight - frame.size.height - this._edgeInsets.bottom;
-                }
-                
+                frame.size.width += indicatorHeight;
                 this._contentViewTopConstraint.constant = 0;
                 this._contentViewBottomConstraint.constant = 0;
-                this._contentViewLeftConstraint.constant = this._indicatorHeight;
+                this._contentViewLeftConstraint.constant = indicatorHeight;
                 this._contentViewRightConstraint.constant = 0;
                 break;
         }
 
-        this.frame = frame;
-
-        // Determine the indicator's position along its edge
-        let indicatorPosition;
-        switch (direction) {
-            case BMPopoverIndicatorDirection.Bottom:
-            case BMPopoverIndicatorDirection.Top:
-                indicatorPosition = BMNumberByConstrainingNumberToBounds(location.x - frame.origin.x, 12, frame.size.width - 12);
-                break;
-            case BMPopoverIndicatorDirection.Left:
-            case BMPopoverIndicatorDirection.Right:
-                indicatorPosition = BMNumberByConstrainingNumberToBounds(location.y - frame.origin.y, 12, frame.size.height - 12);
-                break;
-        }
+        const indicatorPosition = config._indicatorPosition;
+        const borderRadius = config._borderRadius;
+        const indicatorSize = config._indicatorSize;
 
         // Create an inner frame to be used by the various paths
         const innerFrame = frame.copy();
         innerFrame.origin = BMPointMake();
 
-        const pathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize: this._indicatorSize, position: indicatorPosition, direction, radius: this._borderRadius})}`;
-        const outlinePathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize: this._indicatorSize, inset: 1, position: indicatorPosition, direction, radius: this._borderRadius - 1.5})}`;
-        const boxShadowPathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize: this._indicatorSize, position: indicatorPosition, direction, radius: this._borderRadius + 1.5})}`;
+        const pathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize, position: indicatorPosition, direction, radius: borderRadius})}`;
+        const outlinePathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize, inset: 1, position: indicatorPosition, direction, radius: borderRadius - 1.5})}`;
+        const boxShadowPathContent = `${this._pathForPopoverWithFrame(innerFrame, {indicatorSize, position: indicatorPosition, direction, radius: borderRadius + 1.5})}`;
 
         if (!this._clipPathUUID && !CSS.supports('clip-path', `path('${pathContent}')`)) {
             // If inline path definitions are not supported by the browsers, create an UUID for a SVG clip path and create it
@@ -531,26 +823,85 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
         let transformOriginX, transformOriginY;
         switch (direction) {
             case BMPopoverIndicatorDirection.Bottom:
-                transformOriginX = ((indicatorPosition / this.frame.size.width) * 100) + '%';
+                transformOriginX = ((indicatorPosition / frame.size.width) * 100) + '%';
                 transformOriginY = '100%';
                 break;
             case BMPopoverIndicatorDirection.Top:
-                transformOriginX = ((indicatorPosition / this.frame.size.width) * 100) + '%';
+                transformOriginX = ((indicatorPosition / frame.size.width) * 100) + '%';
                 transformOriginY = '0%';
                 break;
             case BMPopoverIndicatorDirection.Left:
                 transformOriginX = '0%';
-                transformOriginY = ((indicatorPosition / this.frame.size.height) * 100) + '%';
+                transformOriginY = ((indicatorPosition / frame.size.height) * 100) + '%';
                 break;
             case BMPopoverIndicatorDirection.Right:
                 transformOriginX = '100%';
-                transformOriginY = ((indicatorPosition / this.frame.size.height) * 100) + '%';
+                transformOriginY = ((indicatorPosition / frame.size.height) * 100) + '%';
                 break;
         }
 
         for (const layer of popoverLayers) {
             layer.style.transformOrigin = `${transformOriginX} ${transformOriginY}`;
         }
+
+        this.frame = frame;
+        this.layoutIfNeeded();
+    },
+
+    /**
+     * The number of display configuration animations running currently against this popover's display configuration.
+     */
+    _displayConfigurationAnimations: 0, // <Number>
+
+    /**
+     * A display configuration that will be applied to this popover at the end of any current
+     * animations affecting the display configuration.
+     */
+    _pendingDisplayConfiguration: undefined, // <_BMPopoverDisplayConfiguration>
+
+    /**
+     * Animatable. Invoked by CoreUI to update this popover's position and recalculate the various paths used by it.
+     */
+    _updatePosition() {
+        // If the popover is not currently visible, there is not action to take
+        if (!this.isVisible) {
+            return;
+        }
+
+        const config = this._createDisplayConfiguration();
+
+        const context = BMAnimationContextGetCurrent();
+        if (context) {
+            const controller = context.controllerForObject(this, {node: this.node});
+            controller.registerAnimatableProperty('_displayConfiguration', {targetValue: config});
+
+            this._displayConfigurationAnimations++;
+            // When all animations finish on this popover, if there was any pending display configuration, apply it then
+            BMAnimationContextAddCompletionHandler(() => {
+                this._displayConfigurationAnimations--;
+
+                if (!this.isVisible) {
+                    return;
+                }
+
+                if (!this._displayConfigurationAnimations && this._pendingDisplayConfiguration) {
+                    BMAnimationContextBeginStatic(); {
+                        this._displayConfiguration = this._pendingDisplayConfiguration;
+                        this._pendingDisplayConfiguration = undefined;
+                    } BMAnimationApplyBlocking();
+                }
+            });
+        }
+        else {
+            if (this._displayConfigurationAnimations) {
+                // If an animation is in progress, wait for it to finish before applying the new configuration
+                this._pendingDisplayConfiguration = config;
+            }
+            else {
+                // Else apply the configuration directly
+                this._displayConfiguration = config;
+            }
+        }
     },
 
     /**
@@ -723,6 +1074,138 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
         return path;
     },
 
+    /**
+     * Controls whether an in-progress drag can detach this popover.
+     */
+    _canDetach: NO, // <Boolean>
+
+    /**
+     * @protected
+     * Controls whether this popover is detachable. Defaults to the result provided
+     * by the delegate.
+     * @return <Boolean>    `YES` if the popover is detachable, `NO` otherwise.
+     */
+    isDetachable() {
+        return this.delegate?.popoverCanDetach?.(this) ?? NO;
+    },
+
+    /**
+     * During a drag operation set to the point where the drag began.
+     */
+    _initialDragPosition: undefined, // <BMPoint, nullable>
+
+    // @override - BMWindow
+    dragBeganAtPosition(position, {withEvent: event}) {
+        this._canDetach = this.isDetachable();
+
+        // If the popover is neither detached nor can it detach, drags cannot be performed
+        if (!this._canDetach && !this._isDetached) {
+            return;
+        }
+
+        this._initialDragPosition = position.copy();
+        BMWindow.prototype.dragBeganAtPosition.apply(this, arguments);
+    },
+
+    // @override - BMWindow
+    dragPositionDidChangeFromPosition(fromPosition, {toPosition, event}) {
+        if (!this._canDetach && !this._isDetached) {
+            return;
+        }
+
+        if (!this._isDetached) {
+            // If not detached, apply a displacement to this popover that is half of the regular
+            // drag distance, until this popover is fully detached
+            BMHook(this.node, {
+                translateX: `${(toPosition.x - this._initialDragPosition.x) / 3 | 0}px`,
+                translateY: `${(toPosition.y - this._initialDragPosition.y) / 3 | 0}px`,
+            });
+
+            const distance = toPosition.distanceToPoint(this._initialDragPosition);
+            if (distance > BMPopoverDragThreshold) {
+                // If the movement exceeds the detachment threshold, detach this popover
+                this.detachAnimated(YES);
+            }
+        }
+        else {
+            // If this is detached, update the popover's position
+            this._position = BMPointMake(
+                BMNumberByConstrainingNumberToBounds(this._position.x + toPosition.x - fromPosition.x, 0, window.innerWidth - this.frame.size.width),
+                BMNumberByConstrainingNumberToBounds(this._position.y + toPosition.y - fromPosition.y, 0, window.innerHeight - this.frame.size.height),
+            );
+            this._displayConfiguration = this._createDisplayConfiguration();
+        }
+    },
+
+    // @override - BMWindow
+	dragEndedAtPosition(position, {withEvent: event}) {
+        BMWindow.prototype.dragEndedAtPosition.apply(this, arguments);
+
+        if (!this._isDetached && this._canDetach) {
+            // If the drag operation didn't cause this popover to detach, animate it back to its
+            // regular position
+            BMAnimateWithBlock(() => {
+                const controller = BMAnimationContextGetCurrent().controllerForObject(this, {node: this.node});
+                controller.registerBuiltInPropertiesWithDictionary({
+                    translateX: '0px',
+                    translateY: '0px',
+                });
+            }, {duration: 500, easing: 'easeInOutQuart'});
+        }
+
+        this._canDetach = NO;
+	},
+
+    /**
+     * Detaches this popover from its anchor and allows it to be freely movable.
+     * @param animated <Boolean, nullable>  Defaults to `YES`. When set to `YES`, this change will be animated,
+     *                                      otherwise it will be instant.
+     * @returns <Promise<void>>             A promise that resolves when the operation completes.
+     */
+    detachAnimated(animated) {
+        // If this popover is already detached, this method has no effect
+        if (this._isDetached) {
+            return;
+        }
+
+        // If this change is animated and there isn't already an active animation context, start one
+        let animationContextStarted = NO;
+        if (animated && !BMAnimationContextGetCurrent()) {
+            animationContextStarted = YES;
+            BMAnimationBeginWithDuration(300, {easing: 'easeInOutQuart'});
+        }
+
+        this._isDetached = YES;
+        this._displayConfiguration = this._createDisplayConfiguration();
+        this._position = this.frame.origin.copy();
+
+        let promise;
+
+        // If a temporary transform was applied to this node, clear it
+        if (BMAnimationContextGetCurrent()) {
+            const controller = BMAnimationContextGetCurrent().controllerForObject(this, {node: this.node});
+            controller.registerBuiltInPropertiesWithDictionary({
+                translateX: '0px',
+                translateY: '0px',
+            });
+
+            promise = new Promise(r => BMAnimationContextAddCompletionHandler(r));
+        }
+        else {
+            BMHook(this.node, {translateX: '0px', translateY: '0px'});
+        }
+
+        if (animationContextStarted) {
+            BMAnimationApplyBlocking(YES);
+        }
+
+        if (!promise) {
+            promise = Promise.resolve();
+        }
+
+        return promise;
+    },
+
     // @override - BMWindow
     animateInWithCompletionHandler(completionHandler) {
         const popoverLayers = [this.contentNode, this._background, this._dropShadowContainer];
@@ -763,7 +1246,7 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
     bringToFrontAnimated(animated, args) {
         if (!this.anchorNode && !this.anchorPoint && !this.anchorRect) throw new Error('The anchorPoint, anchorRect or anchorNode must be set prior to showing this popover.');
 
-        this._updatePosition();
+        this._displayConfiguration = this._createDisplayConfiguration();
 
         BMWindow.prototype.bringToFrontAnimated.apply(this, arguments);
     },
@@ -780,7 +1263,7 @@ BMPopover.prototype = BMExtend(Object.create(BMWindow.prototype), {
 });
 
 /**
- * Constructs and returns a popover with the given size.
+ * Constructs and returns a popover with the specified size.
  * @param size <BMSize>         The popover's size.
  * @return <BMPopover>          A popover.
  */
@@ -788,4 +1271,25 @@ BMPopover.popoverWithSize = function (size) {
     return (new BMPopover).initWithSize(size);
 }
 
+/**
+ * Controls whether popovers retain the direction that was set to them when they were first
+ * displayed, by default. When set to `NO`, whenever a popover's size or attributes change it will try
+ * to find a new direction around the anchor. When set to `YES`, the current direction or the
+ * initial display direction will be kept regardless of how the popover changes.
+ */
+BMPopover._retainsDirection = NO; // <Boolean>
+
+/**
+ * Controls whether popovers retain the direction that was set to them when they were first
+ * displayed, by default. When set to `NO`, whenever a popover's size or attributes change it will try
+ * to find a new direction around the anchor. When set to `YES`, the current direction or the
+ * initial display direction will be kept regardless of how the popover changes.
+ * @param retains <Boolean, nullable>       Defaults to `NO`. When set to `YES`, popovers will retain their
+ *                                          initial direction, otherwise they will recalculate their direction
+ *                                          whenever any update occurs.
+ */
+BMPopover.setRetainsDirection = function (retains) {
+    BMPopover._retainsDirection = retains || NO;
+}
+
 // @endtype