bm-core-ui 2.10.5 → 2.11.1

package/build/BMCollectionView/BMCollectionViewCell.js

@@ -114,6 +114,39 @@ BMJQueryShim.shimWithDOMNode = function (node) {
 // When set to YES, this will cause collection view cells to extend view
 const BM_USE_BMVIEW_SUBCLASS = YES;
 
+// @type BMCollectionViewCellReuseState
+
+/**
+ * Constants describing the various reuse states that a collection view cell may be in.
+ */
+export const BMCollectionViewCellReuseState = Object.freeze({ // <enum>
+
+	/**
+	 * Indicates that this cell is currently bound to a data source object and retained
+     * or managed by the collection view.
+	 */
+	InUse: "InUse", // <enum>
+	
+	/**
+	 * Indicates that this cell is not currently in use, but may be reused in the future.
+	 */
+	InQueue: "InQueue", // <enum>
+	
+	/**
+	 * Indicates that this cell is in the process of being deleted and is bound to a data
+     * source object that no longer has a valid index path.
+	 */
+	Deleting: "Deleting", // <enum>
+
+    /**
+     * Indicates that this cell is not currently in use and cannot be reused in the future.
+     * References to cells in this state should be cleared as they are no longer valid.
+     */
+    Discarded: "Discarded" // <enum>
+});
+
+// @endtype
+
 // @type BMCollectionViewCell extends BMView
 
 /**
@@ -156,16 +189,13 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
         return this.retainCount > 0;
     },
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     get _frame() {
         return this._attributes && this._attributes.frame;
     },
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     get frame() {
         return this._attributes && this._attributes.frame;
     },
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     set frame(frame) {
         // NOTE: A cell's frame is controlled by its layout attributes, therefore this operation is a no-op
     },
@@ -192,12 +222,6 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
 	 */
     _element: undefined, // <BMJQueryShim>
     get element() { return this._element || (this._element = BMJQueryShim.shimWithDOMNode(this.node)); },
-    
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
-    /**
-     * The DOM node managed by this cell.
-     */
-    //node: undefined, // <DOMNode>
 
     /**
      * The type of item this cell represents.
@@ -206,7 +230,8 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
     itemType: BMCollectionViewLayoutAttributesType.Cell, // <BMCollectionViewLayoutAttributesType>
 
     /**
-     * The cell's reuse identifier which corresponds to the template's reuse identifier.
+     * The cell's reuse identifier which controls when this cell is reused when data source objects
+     * request cell instances from the associated collection view.
      */
     _reuseIdentifier: undefined, // <String>
 
@@ -396,10 +421,8 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
     recycle: function () {
         this._unmanage();
 
-        this.invalidate();
-
-        //this.collectionView.cellWasUnmanaged(this);
         if (this.retainCount > 0) {
+            this.invalidate();
             this.collectionView.cellWasInvalidated(this);
             this.destroy();
             
@@ -422,9 +445,8 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
     releaseRecycledCell: function () {
         this.release();
 
-        this.invalidate();
-
         if (this.retainCount > 0) {
+            this.invalidate();
             this.collectionView.cellWasInvalidated(this);
             this.destroy();
             
@@ -438,6 +460,15 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
         }
     },
 
+    /**
+     * The cell's current reuse state.
+     */
+    _reuseState: BMCollectionViewCellReuseState.InQueue, // <BMCollectionViewCellReuseState>
+
+    get reuseState() {
+        return this._reuseState;
+    },
+
     /**
      * Should be set to YES to hide the cell, or NO to reveal it.
      */
@@ -475,7 +506,6 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
         this.node.classList.remove('BMCollectionViewCellHidden');
     },
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     _prepareForAutomaticIntrinsicSize() {
         for (let subview of this._subviews) {
             subview._prepareForAutomaticIntrinsicSize();
@@ -489,27 +519,25 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
             }
             else {
                 if (this._requiredWidth) {
-                    // Otherwise derive the measured size using the instrinsic CSS size
+                    // Otherwise derive the measured size using the intrinsic CSS size
                     BMCopyProperties(this._node.style, {width: this._requiredWidth + 'px', height: 'auto'});
                 }
                 else {
-                    // Otherwise derive the measured size using the instrinsic CSS size
+                    // Otherwise derive the measured size using the intrinsic CSS size
                     BMCopyProperties(this._node.style, {width: 'auto', height: 'auto'});
                 }
             }
         }
     },
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     _supportsAutomaticIntrinsicSize: NO,
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     /**
+     * @protected
      * Temporarily set to `YES` while this cell is being measured.
      */
     _isMeasuring: NO,
 
-    // #FLAG BM_USE_BMVIEW_SUBCLASS
     internalConstraints() {
         var constraints = [];
 
@@ -550,19 +578,19 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
     /**
      * Invoked prior to this cell being collected for reuse by the collection view.
      * Subclasses can override this method to perform any changes necessary for reusing this cell.
-     * Subclasses should invoke the superclass method at some point in their implementation.
+     * Subclasses must invoke the superclass method at some point in their implementation.
      */
     prepareForReuse() {
-
+        this._reuseState = BMCollectionViewCellReuseState.InQueue;
     },
 
     /**
      * Invoked prior to this cell being shown on the screen either after being initialized or after having been previously collected.
-     * Subclasses can override this method to perform any changes necesarry for displaying this cell.
-     * Subclasses should invoke the superclass method at some point in their implementaiton.
+     * Subclasses can override this method to perform any changes necessary for displaying this cell.
+     * Subclasses must invoke the superclass method at some point in their implementation.
      */
     prepareForDisplay() {
-
+        this._reuseState = BMCollectionViewCellReuseState.InUse;
     },
 
     /**
@@ -625,7 +653,6 @@ BMCollectionViewCell.prototype = BMExtend(BM_USE_BMVIEW_SUBCLASS ? Object.create
         
         this.collectionView = collectionView;
 
-        // #FLAG BM_USE_BMVIEW_SUBCLASS
         if (BM_USE_BMVIEW_SUBCLASS) {
             BMView.prototype.initWithDOMNode.call(this, args.node);
         }

package/build/BMCollectionView/BMCollectionViewFlowLayout.js

@@ -41,6 +41,7 @@ export var BMCollectionViewTableLayoutSupplementaryView = Object.freeze({ // <en
 
 /**
  * @deprecated Use `BMCollectionViewFlowLayout` with the `maximumCellsPerRow` property set to `1`.
+ * 
  * --------------------------------------
  * A basic layout implementation, the BMCollectionViewTableLayout will lay out its elements as a list where each row can have
  * either a fixed height or a variable height.
@@ -4964,7 +4965,7 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
  * @return <BMCollectionViewFlowLayout>		A flow layout.	 
  */
 BMCollectionViewFlowLayout.flowLayout = function () {
-	return new BMCollectionViewFlowLayout();
+	return new this();
 }
 
 // @endtype

package/build/BMCollectionView/BMCollectionViewMasonryLayout.js

@@ -625,7 +625,7 @@ BMCollectionViewMasonryLayout.prototype = BMExtend({}, BMCollectionViewLayout.pr
  * @returns <BMCollectionViewMasonryLayout>		A masonry layout.
  */
 BMCollectionViewMasonryLayout.masonryLayout = function () {
-	return new BMCollectionViewMasonryLayout();
+	return new this();
 };
 
 // @endtype

package/build/BMCollectionView/BMCollectionViewStackLayout.js

@@ -628,7 +628,7 @@ BMCollectionViewStackLayout.prototype = BMExtend({}, BMCollectionViewLayout.prot
  * @returns <BMCollectionViewStackLayout>	A stack layout.
  */
 BMCollectionViewStackLayout.stackLayout = function () {
-	return new BMCollectionViewStackLayout();
+	return new this();
 }
 
 // @endtype

package/build/BMCollectionView/BMCollectionViewTileLayout.js

@@ -1260,7 +1260,7 @@ BMCollectionViewTileLayout.prototype = BMExtend({}, BMCollectionViewLayout.proto
  * @return <BMCollectionViewTileLayout>		A tile layout.
  */
 BMCollectionViewTileLayout.tileLayout = function () {
-	return new BMCollectionViewTileLayout();
+	return new this();
 };
 
 // @endtype

package/build/BMWindow/BMWindow.js

@@ -1075,6 +1075,147 @@ BMWindow.prototype = BMExtend(Object.create(BMView.prototype), {
 		return this;
 	},
 
+	/**
+	 * Starts a drag event from the specified `mousedown` or `touchstart` event that moves this window.
+	 * When this method is invoked, further mouse and touch events will be blocked until the drag finishes.
+	 * 
+	 * If there is already a drag operation in progress or if this window is full screen or a modal window,
+	 * this method has no effect.
+	 * @param event <MouseEvent | TouchEvent>		The `mousedown` or `touchstart` event from which to begin
+	 * 												the window movement.
+	 */
+	performDragWithEvent(event) {
+		if (event.type == 'mousedown') {
+			this.performDragWithMouseEvent(event);
+		}
+		else if (event.type == 'touchstart') {
+			this.performDragWithTouchEvent(event);
+		}
+	},
+
+	/**
+	 * Starts a drag event from the specified `mousedown` event that will move this window.
+	 * When this method is invoked, further mouse events will be blocked until the drag finishes.
+	 * 
+	 * If there is already a drag operation in progress or if this window is full screen or a modal window,
+	 * this method has no effect.
+	 * @param event <MouseEvent | TouchEvent>		The `mousedown` event from which to begin the window movement.
+	 */
+	performDragWithMouseEvent(event) {
+		// Full screen and modal windows cannot be moved
+		if (this._fullScreen) return;
+
+		this._dragged = YES;
+
+		this._position = BMPointMake(this.node.offsetLeft, this.node.offsetTop);
+		let lastPosition = BMPointMake(event.clientX, event.clientY);
+
+		let mouseMoveEventListener = event => {
+			let position = BMPointMake(event.clientX, event.clientY);
+			const newPosition = BMPointMake(this._position.x + position.x - lastPosition.x, this._position.y + position.y - lastPosition.y);
+
+			// Check if the window can move
+			let canMove = YES;
+			if (this.delegate && this.delegate.windowShouldMove) {
+				canMove = this.delegate.windowShouldMove(this, newPosition);
+			}
+			if (!canMove) return;
+
+			this.leftConstraint.constant = this._position.x + position.x - lastPosition.x;
+			this.topConstraint.constant = this._position.y + position.y - lastPosition.y;
+			this._position = newPosition;
+			lastPosition = position;
+			this.layout();
+			event.preventDefault();
+		};
+
+		let mouseUpEventListener = event => {
+			window.removeEventListener('mousemove', mouseMoveEventListener, YES);
+			window.removeEventListener('mouseup', mouseUpEventListener, YES);
+		}
+
+		window.addEventListener('mousemove', mouseMoveEventListener, YES);
+		window.addEventListener('mouseup', mouseUpEventListener, YES);
+
+		event.preventDefault();
+	},
+
+	/**
+	 * The identifier of the touch point that is tracked during a drag operation. `undefined`
+	 * when not tracking a drag.
+	 */
+	_touchDragPoint: undefined, // <String>
+
+	/**
+	 * Starts a drag event from the specified `touchstart` event that will move this window.
+	 * When this method is invoked, further touch events will be blocked until the drag finishes.
+	 * 
+	 * 
+	 * If there is already a drag operation in progress or if this window is full screen or a modal window,
+	 * this method has no effect.
+	 * @param event <MouseEvent | TouchEvent>		The `touchstart` event from which to begin the window movement.
+	 */
+	performDragWithTouchEvent(event) {
+		// If there is already a drag in progress, don't process this new event
+		if (typeof this._touchDragPoint !== 'undefined') {
+			return;
+		}
+
+		// Full screen windows cannot be moved
+		if (this._fullScreen) return;
+
+		// Only use the first touch point
+		this._touchDragPoint = event.changedTouches[0].identifier;
+		this._dragged = YES;
+
+		this._position = BMPointMake(this.node.offsetLeft, this.node.offsetTop);
+		let lastPosition = BMPointMake(event.changedTouches[0].clientX, event.changedTouches[0].clientY);
+
+		let mouseMoveEventListener = event => {
+			// Look for the actively tracked touch point
+			let touch;
+			for (let changedTouch of event.changedTouches) {
+				if (changedTouch.identifier == this._touchDragPoint) {
+					touch = changedTouch;
+					break;
+				}
+			}
+
+			// If the actively tracked touch point did not move, do not process this event
+			if (!touch) return;
+
+			let position = BMPointMake(touch.clientX, touch.clientY);
+			const newPosition = BMPointMake(this._position.x + position.x - lastPosition.x, this._position.y + position.y - lastPosition.y);
+
+			// Check if the window can move
+			let canMove = YES;
+			if (this.delegate && this.delegate.windowShouldMove) {
+				canMove = this.delegate.windowShouldMove(this, newPosition);
+			}
+			if (!canMove) return;
+
+			this.leftConstraint.constant = this._position.x + position.x - lastPosition.x;
+			this.topConstraint.constant = this._position.y + position.y - lastPosition.y;
+			this._position = newPosition;
+			lastPosition = position;
+			this.layout();
+			event.preventDefault();
+		};
+
+		let mouseUpEventListener = event => {
+			this._touchDragPoint = undefined;
+			window.removeEventListener('touchmove', mouseMoveEventListener);
+			window.removeEventListener('touchend', mouseUpEventListener);
+			window.removeEventListener('touchcancel', mouseUpEventListener);
+		}
+
+		window.addEventListener('touchmove', mouseMoveEventListener);
+		window.addEventListener('touchend', mouseUpEventListener);
+		window.removeEventListener('touchcancel', mouseUpEventListener);
+
+		event.preventDefault();
+	},
+
 	// @override - BMView
 	colorSchemeDidChange(scheme) {
 		BMView.prototype.colorSchemeDidChange.apply(this, arguments);

package/build/Core/BMAnimationContext.js

@@ -625,6 +625,11 @@ BMAnimationContext.prototype = {
 	
 }
 
+/**
+ * A map having DOM nodes as keys which contains delayed animations that have yet to start.
+ */
+BMAnimationContext._pendingAnimations = new Map; // Map<DOMNode, unknown[]>
+
 /**
  * The animation stack holds all animations with their attributes.
  * Whenever an attribute property is changed while there is an active animation, that property
@@ -756,6 +761,37 @@ export function BMAnimationApply() {
 // Set to `YES` if the environment does not fully support web animations
 var BM_WEB_ANIMATIONS_DISABLED = NO;
 
+
+/**
+ * Stops all current animations for the specified node on the properties that
+ * are specified in an animation that is about to start.
+ * @param node <DOMNode>							The DOM node on which the animation is about to start.
+ * {
+ * 	@param withProperties <Dictionary<unknown>>		The properties that are about to be animated.
+ * 	@param options <Dictionary<unknown>>			The options of the animation that is about to start.
+ * }
+ */
+BMAnimationContext._prepareAnimationForNode = function (node, {withProperties: properties, options}) {
+	const velocity = window.Velocity || window.$?.Velocity;
+	if (!velocity) {
+		return;
+	}
+	
+	// Find all animations targeting the specified node
+	const nodeAnimations = velocity.State.calls.filter(c => c[1]?.[0] == node);
+
+	// For each animation clear out the properties that are about to be animated, except for the tween property
+	for (const call of nodeAnimations) {
+		for (const property in properties) {
+			if (property == 'element' || property == 'tween') {
+				continue;
+			}
+
+			delete call[0]?.[0]?.[property];
+		}
+	}
+}
+
 /**
  * Must be invoked after a <code>BMAnimationBeginWithDuration()</code> call to apply the pending animation.
  * Applying the animation in this way will stop all other running animations on the animation targets.
@@ -849,7 +885,13 @@ export function BMAnimationApplyBlocking(blocking) {
     for (var i = 0; i < animationTargetsLength; i++) {
         var element = animationTargets[i].element;
         
-        if (blocking) velocity(element, 'stop', true);
+        if (blocking && velocity) {
+			// velocity(element, 'stop', true);
+		}
+
+		// Web animations are used if enabled specifically for this animation context, enabled
+		// globally via the build flag and fully supported by the browser
+		const useWebAnimations = (context._useWebAnimations || BM_USE_WEB_ANIMATIONS) && document.body.animate && !BM_WEB_ANIMATIONS_DISABLED;
         
         // Allow each target to set its own options
         var options = animationTargets[i].options ? BMCopyProperties({}, animation.options, animationTargets[i].options) : BMCopyProperties({}, animation.options);
@@ -865,9 +907,15 @@ export function BMAnimationApplyBlocking(blocking) {
 	        delay += stride;
 		}
 
+		if (velocity && !useWebAnimations && !delay) {
+			// When velocity is used, if an element is already part of the velocity calls, clear out any properties
+			// that are part of this new animation
+			BMAnimationContext._prepareAnimationForNode(element, {withProperties: animationTargets[i].properties, options});
+		}
+
 		delete options.complete;
 		
-		if ((context._useWebAnimations || BM_USE_WEB_ANIMATIONS) && document.body.animate && !BM_WEB_ANIMATIONS_DISABLED) {
+		if (useWebAnimations) {
 			if (options.queue) {
 				console.warn('[BMCoreUI] Using the queue animation option with web animations which is not supported. This argument will be ignored.');
 			}
@@ -1031,10 +1079,50 @@ export function BMAnimationApplyBlocking(blocking) {
 			}
 		}
 		else {
-			promises.push(velocity.animate(element, animationTargets[i].properties, options));
-		
 			if (options.queue) {
-				velocity.Utilities.dequeue(element, options.queue);
+				console.warn(`Ignoring deprecated property "queue" for animation context.`);
+			}
+
+			options.queue = false;
+
+			// If a delay is specified, use setTimeout as velocity leaks delayed animations
+			if (options.delay) {
+				const node = element;
+				const properties = animationTargets[i].properties;
+				const animationOptions = options;
+
+				promises.push(new Promise(async resolve => {
+					const delay = options.delay;
+					options.delay = undefined;
+					const pendingAnimation = {node, properties, options: animationOptions, animationContext: context};
+
+					const timeout = setTimeout(async () => {
+						// When the timeout expires, start the animation and remove it from the pending list for the element
+						const pendingAnimations = BMAnimationContext._pendingAnimations.get(element) || [];
+						const index = pendingAnimations?.indexOf(pendingAnimation) ?? -1;
+						if (index != -1) {
+							pendingAnimations.splice(index, 1);
+						}
+
+						// If there are no further pending animations remove the element from the map
+						if (!pendingAnimation?.length) {
+							BMAnimationContext._pendingAnimations.delete(element);
+						}
+
+						// Before starting the animation, ensure that no other animations affect this node's properties
+						BMAnimationContext._prepareAnimationForNode(node, {withProperties: properties, options: animationOptions});
+						const animationResult = await velocity.animate(node, properties, animationOptions);
+						resolve(animationResult);
+					}, delay);
+
+					// Store this animation as pending
+					const pendingAnimations = BMAnimationContext._pendingAnimations.get(element) || [];
+					pendingAnimations.push(pendingAnimation);
+					BMAnimationContext._pendingAnimations.set(element, pendingAnimations);
+				}));
+			}
+			else {
+				promises.push(velocity.animate(element, animationTargets[i].properties, options));
 			}
 		}
 	}