bm-core-ui 2.7.0

package/build/Core/BMIndexPath.js

@@ -0,0 +1,165 @@
+// @ts-check
+
+import {YES, NO} from './BMCoreUI'
+
+// @type BMIndexPath<T = any>
+
+/*
+****************************************************************************************************************************************************************
+																		BMIndexPath
+****************************************************************************************************************************************************************
+*/
+
+/**
+ * A BMIndexPath object manages the mapping between an object and its position within a data set.
+ * It represents an ordered list of indexes that should be traversed within a data set to reach a given object.
+ * 
+ * Optionally, and index path may also contain a reference to the object to which its indexes point.
+ * 
+ * Index paths should be created using one of the `BMIndexPathMake` functions rather than using the constructor.
+ */
+export function BMIndexPath() {} // <constructor>
+
+BMIndexPath.prototype = {
+    /**
+     * The object.
+     */
+    object: undefined, // <T, nullable>
+
+    /**
+     * The ordered list of indexes.
+     */
+	indexes: undefined, // <[Int]>
+	
+	/**
+	 * Initializes this index path by copying the values of the given index path.
+	 * @param indexPath <BMIndexPath<T>>			The index path to copy.
+	 * @return <BMIndexPath<T>>						This index path.
+	 */
+	initWithIndexPath(indexPath) {
+		this.object = indexPath.object;
+		this.indexes = indexPath.indexes.slice();
+		return this;
+	},
+
+    /**
+     * The object's row. This corresponds to the second index.
+     */
+    get row() { // <Int>
+        return this.indexes[1];
+    },
+    set row(row) {
+        this.indexes[1] = row;
+    },
+
+    /**
+     * The object's section. This corresponds to the first index.
+     */
+    get section() { // <Int>
+        return this.indexes[0];
+    },
+    set section(section) {
+        this.indexes[0] = section;
+    },
+
+    /**
+     * Creates and returns a new <code>BMIndexPath</code> instance with the same property values
+     * as this index path.
+     * @return <BMIndexPath<T>>    An index path.
+     */
+    copy: function () {
+        var result = new BMIndexPath();
+        result.object = this.object;
+        result.indexes = this.indexes.slice();
+        return result;
+    },
+    
+    /**
+	 * Used to test if two index paths are strictly equal.
+	 * Two index paths are strictly equal if the contain the same indexes and point to the same object.
+	 * @param indexPath <BMIndexPath, nullable>					The index path. If undefined, this method returns NO.
+	 * {
+	 *	@param usingComparator <Boolean ^ (Object, Object)>		The comparator used to compare the pointed object.
+	 * }
+	 * @return <Boolean>										YES if the index paths are strictly equal, NO otherwise.
+	 */
+    isEqualToIndexPath: function (indexPath, options) {
+	    if (!indexPath || indexPath == BMIndexPathNone) return NO;
+	    
+	    if (indexPath.indexes.length != this.indexes.length) return NO;
+	    for (var i = 0; i < this.indexes.length; i++) {
+		    if (this.indexes[i] != indexPath.indexes[i]) return NO;
+	    }
+	    
+	    return options.usingComparator(this.object, indexPath.object);
+	    
+    },
+    
+    /**
+	 * Used to test if two index paths represent the same element, even if they have a different position in the data set.
+	 * Two index paths are loosely equal if they refer to the same object or if they both refer to no object but have equal indexes.
+	 * @param indexPath <BMIndexPath, nullable>					The index path. If undefined, this method returns NO.
+	 * {
+	 *	@param usingComparator <Boolean ^ (Object, Object)>		The comparator used to compare the pointed object.
+	 * }
+	 * @return <Boolean>										YES if the index paths are loosely equal, NO otherwise.
+	 */
+    isLooselyEqualToIndexPath: function (indexPath, options) {
+	    if (!indexPath || indexPath == BMIndexPathNone) return NO;
+	    
+	    if (indexPath.object === undefined && this.object === undefined) {
+		    if (indexPath.indexes.length != this.indexes.length) return NO;
+		    for (var i = 0; i < this.indexes.length; i++) {
+			    if (this.indexes[i] != indexPath.indexes[i]) return NO;
+		    }
+		    return YES;
+	    }
+	    else {
+	    	return options.usingComparator(this.object, indexPath.object);
+	    }
+    }
+
+};
+
+/**
+ * An index path that points to no object.
+ * This index path will return NO when tested for equality, even against itself.
+ */
+export var BMIndexPathNone = BMIndexPathMakeWithRow(NaN, {section: NaN, forObject: NaN}); // <BMIndexPath<any>>
+BMIndexPathNone.section = NaN;
+BMIndexPathNone.isEqualToIndexPath = function () { return NO; };
+BMIndexPathNone.isLooselyEqualToIndexPath = function () { return NO; };
+
+/**
+ * Constructs and returns a new BMIndexPath object initialized to the given row and section.
+ * @param row <Int>                     	The row number.
+ * {
+ *  @param section <Int, nullable>      	Defaults to 0. The section number.
+ *  @param forObject <Object, nullable>		The object.
+ * }
+ * @return <BMIndexPath>					An index path.
+ */
+export function BMIndexPathMakeWithRow(row, options) {
+    var indexPath = new BMIndexPath();
+    indexPath.indexes = [(options && options.section) || 0, row];
+    indexPath.object = (options && options.forObject);
+    return indexPath;
+}
+
+
+/**
+ * Constructs and returns a new BMIndexPath object initialized to the given indexes.
+ * @param indexes <[Int]>               		The indexes.
+ * {
+ *  @param forObject <Object, nullable>         Optional. The object.
+ * }
+ * @return <BMIndexPath>						An index path.
+ */
+export function BMIndexPathMakeWithIndexes(indexes, options) {
+	var indexPath = new BMIndexPath();
+	indexPath.indexes = indexes;
+	indexPath.object = options ? options.forObject : undefined;
+	return indexPath;
+}
+
+// @endtype

package/build/Core/BMInset.js

@@ -0,0 +1,138 @@
+// @ts-check
+
+// @type BMInset
+
+/*
+****************************************************************************************************************************************************************
+																		BMInset
+****************************************************************************************************************************************************************
+*/
+
+/**
+ * A struct which represents the insets which may be applied to a rect such a view's frame.
+ * An inset is represented by four numbers, each representing the amount by which each rect's edge should be inset.
+ * If an inset is positive, the rect edge will be inset (move towards the center) by that amount,
+ * if it is negative, the rect edge will be outset (move away from the center) by that amount.
+ */
+export function BMInset(left, top, right, bottom) { // <constructor>
+	this.left = left || 0;
+	this.top = top || 0;
+	this.right = right || 0;
+	this.bottom = bottom || 0;
+}
+
+BMInset.prototype = {
+	
+	/**
+	 * The left edge inset.
+	 */
+	left: 0, // <Number>
+	
+	/**
+	 * The top edge inset.
+	 */
+	top: 0, // <Number>
+	
+	/**
+	 * The right edge inset.
+	 */
+	right: 0, // <Number>
+	
+	/**
+	 * The bottom edge inset.
+	 */
+	bottom: 0, // <Number>
+
+	/**
+	 * Initializes this inset with the values of the given inset object.
+	 * @param inset <BMInset>	The inset to copy.
+	 * @return <BMInset>		This inset.
+	 */
+	initWithInset(inset) {
+		this.left = inset.left;
+		this.top = inset.top;
+		this.right = inset.right;
+		this.bottom = inset.bottom;
+
+		return this;
+	},
+
+	/**
+	 * Tests whether this inset is equal to the given inset.
+	 * The two insets are equal if their components are all equal.
+	 * @param inset <BMInset>		The inset to test against.
+	 * @return <Boolean>			`YES` if the two insets are equal, `NO` otherwise.
+	 */
+	isEqualToInset(inset) {
+		return (this.left === inset.left && this.top === inset.top && this.right === inset.right && this.bottom === inset.bottom);
+	},
+
+	/**
+	 * Creates and returns a copy of this BMInset object.
+	 * @return <BMInset>	An inset object.
+	 */
+	copy: function () {
+		return new BMInset(this.left, this.top, this.right, this.bottom);
+	}
+
+}
+
+/**
+ * Constructs and returns a new inset with all four edges having the same value.
+ * @param insets <Number, nullable>		Defaults to 0. The inset value to use for all four edges.
+ * @return <BMInset>					An inset.
+ */
+export function BMInsetMakeWithEqualInsets(insets) {
+	insets = insets || 0;
+	return BMInsetMake(insets, insets, insets, insets);
+};
+
+
+/**
+ * Constructs and returns a new inset with all four edges having the same value.
+ * @param insets <Number, nullable>		Defaults to 0. The inset value to use for all four edges.
+ * @return <BMInset>					An inset.
+ */
+BMInset.insetWithEqualInsets = BMInsetMakeWithEqualInsets;
+
+/**
+ * Creates and returns an inset object.
+ * @param left <Number, nullable>		Defaults to 0. The left inset.
+ * @param top <Number, nullable>		Defaults to 0. The top inset.
+ * @param right <Number, nullable>		Defaults to 0. The right inset.
+ * @param bottom <Number, nullable>		Defaults to 0. The bottom inset.
+ * @return <BMInset>					An insets object.
+ */
+export function BMInsetMake(left, top, right, bottom) {
+	return new BMInset(left, top, right, bottom);
+}
+
+/**
+ * Creates and returns an inset object.
+ * @param left <Number, nullable>		Defaults to 0. The left inset.
+ * {
+ *	@param top <Number, nullable>		Defaults to 0. The top inset.
+ *	@param right <Number, nullable>		Defaults to 0. The right inset.
+ *	@param bottom <Number, nullable>	Defaults to 0. The bottom inset.
+ * }
+ * @return <BMInset>					An insets object.
+ */
+export function BMInsetMakeWithLeft(left, args) {
+	args = args || {};
+	return new BMInset(left || 0, args.top || 0, args.right || 0, args.bottom || 0);
+}
+
+
+/**
+ * Creates and returns an inset object.
+ * @param left <Number, nullable>		Defaults to 0. The left inset.
+ * {
+ *	@param top <Number, nullable>		Defaults to 0. The top inset.
+ *	@param right <Number, nullable>		Defaults to 0. The right inset.
+ *	@param bottom <Number, nullable>	Defaults to 0. The bottom inset.
+ * }
+ * @return <BMInset>					An insets object.
+ */
+BMInset.insetWithLeft = BMInsetMakeWithLeft;
+
+// @endtype

package/build/Core/BMKeyPath.js

@@ -0,0 +1,100 @@
+// @ts-check
+
+// @type BMKeyPath
+
+/*
+****************************************************************************************************************************************************************
+																		BMKeyPath
+****************************************************************************************************************************************************************
+*/
+
+
+/**
+ * A BMKeyPath object represents an ordered list of key names that should be traversed within a data set to reach a given object.
+ * Key paths should be created using one of the `BMKeyPathMake` functions rather than using the constructor.
+ */
+export function BMKeyPath() {}; // <constructor>
+
+BMKeyPath.prototype = {
+	
+	/**
+	 * The list of keys which should be traversed by this key path.
+	 */
+	_components: undefined, // <[String]>
+	
+	get components() {
+		return this._components.slice();
+	},
+	
+	/**
+	 * Initializes this key path by parsing the given string.
+	 * The key path components should be separated by periods. If a key contains a period in its name
+	 * that period should be escaped using the '\' character.
+	 * @param string <String>		The string which represents the key path.
+	 */
+	initWithString: function (string) {
+		// TODO escaped periods
+		this._components = string.split('.');
+	},
+	
+	/**
+	 * Initializes this key path using the specified list of ordered key names.
+	 * @param components <[String]>		The array of keys.
+ 	 */
+	initWithComponents: function (components) {
+		this._components = components.slice();
+	},
+	
+	/**
+	 * Traverses this key path on the given object, returning the value for the last key.
+	 * If any of the intermediary objects are undefined, this method will return undefined.
+	 * @param object <AnyObject>				The object which should be traversed.
+	 * {
+	 *	@param withLimit <Number, nullable>		Defaults to this key path's length. The number of keys to use when traversing.
+	 * }
+	 * @return <AnyObject, nullable>			The value at the end of this key path, or undefined if the object could not be traversed
+	 *											for the entire key path.
+	 */
+	valueForObject: function (object, args) {
+		var value = object;
+		var length = Math.min(this._components.length, (args && args.withLimit) || this._components.length);
+		
+		for (var i = 0; i < length; i++) {
+			value = value[this._components[i]];
+			
+			if (typeof value === 'undefined') return undefined;
+		}
+		
+		return value;
+		
+	}
+	
+};
+
+
+/**
+ * Constructs and returns a new key path by parsing the given string.
+ * The key path components should be separated by periods. If a key contains a period in its name
+ * that period should be escaped using the '\' character.
+ * @param string <String>		The string which represents the key path.
+ * @return <BMKeyPath>			A key path.
+ */
+export function BMKeyPathMakeWithString(string) {
+	
+	return (new BMKeyPath).initWithString(string);
+	
+}
+
+
+/**
+ * Constructs and returns a new key path using the specified list of ordered key names.
+ * @param components <[String]>		The array of keys.
+ * @return <BMKeyPath>				A key path.
+ */
+export function BMKeyPathMakeWithComponents(components) {
+	
+	return (new BMKeyPath).initWithComponents(components);
+	
+}
+
+// @endtype

package/build/Core/BMPoint.js

@@ -0,0 +1,291 @@
+// @ts-check
+
+import {BMNumberByInterpolatingNumbersWithFraction, BMExtend} from './BMCoreUI'
+
+// @type BMPoint implements BMAnimating
+
+/*
+****************************************************************************************************************************************************************
+																		BMPoint
+****************************************************************************************************************************************************************
+*/
+
+/**
+ * A struct which represents a point in two dimensions.
+ * @param x <Number, nullable>     Defaults to 0. The x coordinate.
+ * @param y <Number, nullable>     Defaults to 0. The y coordinate.
+ */
+export function BMPoint(x, y) { // <constructor>
+	x = x || 0;
+	y = y || 0;
+
+	this.x = x;
+	this.y = y;
+};
+
+BMPoint.prototype = {
+	
+	/**
+	 * The point's X coordinate.
+	 */
+	x: 0, // <Number>
+	
+	/**
+	 * The point's Y coordinate.
+	 */
+	y: 0, // <Number>
+
+	/**
+	 * The point's polar radius coordinate.
+	 */
+	get r() { // <Number>
+		return BMDistanceBetweenPoints(this, BMOriginPoint);
+	},
+
+	set r(r) {
+		const t = this.t;
+
+		this.x = r * Math.cos(t);
+		this.y = r * Math.sin(t);
+	},
+
+	/**
+	 * The point's polar angle coordinate.
+	 */
+	get t() { // <Number>
+		return BMSlopeAngleBetweenPoints(BMOriginPoint, this);
+	},
+
+	set t(t) {
+		const r = this.r;
+
+		this.x = r * Math.cos(t);
+		this.y = r * Math.sin(t);
+	},
+
+	/**
+	 * Initializes this point by copying the values of the given point.
+	 * @param point <BMPoint> 	The point to copy.
+	 * @return <BMPoint>		This point.
+	 */
+	initWithPoint(point) {
+		this.x = point.x;
+		this.y = point.y;
+		return this;
+	},
+
+	/**
+	 * Returns a string representation of this point.
+	 */
+	get stringValue() {
+		return this.x + ',' + this.y;
+	},
+
+	/**
+	 * Returns a string representation of this point.
+	 * This property removes the fractional part of the components in the serialized representation.
+	 */
+	get integerStringValue() {
+		return (this.x | 0) + ',' + (this.y | 0);
+	},
+	
+	/**
+	 * Returns a point with the same coordinates as this point, but without their fractional parts.
+	 */
+	get integerPointValue() {
+		return BMPointMake(this.x | 0, this.y | 0);
+	},
+	
+	/**
+	 * Returns a point with the same coordinates as this point, but without their fractional parts.
+	 */
+	get integralPoint() {
+		return this.integerPointValue;
+	},
+	
+	/**
+	 * Tests whether this point is equal to the given point.
+	 * @param point <BMPoint>						The point.
+	 * @return <Boolean>							YES if the points are equal, NO otherwise.
+	 */
+	isEqualToPoint: function (point) {
+		return this.x == point.x && this.y == point.y;
+	},
+	
+	/**
+	 * Returns a copy of this point.
+	 * @return <BMPoint>	A point.
+	 */
+	copy: function () {
+		return BMPointMake(this.x, this.y);
+	},
+
+	/**
+	 * Multiplies all of this point's components by the given scalar.
+	 * @param scalar <Number> 		The scalar by which to multiply this point's components.
+	 */
+	multiplyWithScalar(scalar) {
+		this.x *= scalar;
+		this.y *= scalar;
+	},
+
+	/**
+	 * Returns a copy of this point whose components are multiplied by the given scalar.
+	 * @param scalar <Number>		The scalar by which to multiply the point's components.
+	 * @return <BMPoint>			A point.
+	 */
+	pointByMultiplyingWithScalar(scalar) {
+		const point = this.copy();
+		point.multiplyWithScalar(scalar);
+		return point;
+	},
+
+	/**
+	 * Constructs and returns a point that represents the sum of the components of this point and the given point.
+	 * @param point <BMPoint>		The point.
+	 * @return <BMPoint>			A point.
+	 */
+	pointByAddingPoint(point) {
+		return BMPointMake(this.x + point.x, this.y + point.y);
+	},
+
+	/**
+	 * Constructs and returns a point that represents the difference of the components of this point and the given point.
+	 * @param point <BMPoint>		The point.
+	 * @return <BMPoint>			A point.
+	 */
+	pointBySubtractingPoint(point) {
+		return BMPointMake(this.x - point.x, this.y - point.y);
+	},
+	
+	/**
+	 * Computes and returns the distance from this point to the given point.
+	 * @param point <BMPoint>				A point.
+	 * @return <Number>						The distance.
+	 */
+	distanceToPoint: function (point) {
+		return BMDistanceBetweenPoints(this, point);
+	},
+	
+	/**
+	 * Computes and returns the slope angle, in radians, of the line between this point and the given point.
+	 * @param point <BMPoint>				A point.
+	 * @return <Number>						The angle in radians.
+	 */
+	slopeAngleToPoint: function (point) {
+		return BMSlopeAngleBetweenPoints(this, point);
+	},
+
+    /**
+     * 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 <BMPoint>        The object to which to interpolate.
+     * }
+	 * @return <BMPoint>				A point.
+     */
+	interpolatedValueWithFraction(fraction, args) {
+		var target = args.toValue;
+		return BMPointMake(
+			BMNumberByInterpolatingNumbersWithFraction(this.x, target.x, fraction),
+			BMNumberByInterpolatingNumbersWithFraction(this.y, target.y, fraction)
+		);
+	},
+
+	/**
+	 * Returns a string representation of this point.
+	 * @return <String>		A string.
+	 */
+	toString() {
+		return `(${this.x}:${this.y})`;
+	}
+	
+};
+
+/**
+ * Constructs and returns a new point with the given coordinates.
+ * @param x <Number, nullable>     	Defaults to 0. The x coordinate.
+ * @param y <Number, nullable>     	Defaults to 0. The y coordinate.
+ * @return <BMPoint>				A Point.
+ */
+export function BMPointMake(x, y) {
+	return new BMPoint(x, y);
+};
+
+/**
+ * Constructs and returns a new point with the given cartesian coordinates.
+ * @param x <Number, nullable>     	Defaults to 0. The x coordinate.
+ * {
+ * 	@param y <Number, nullable>     Defaults to 0. The y coordinate.
+ * }
+ * @return <BMPoint>				A Point.
+ */
+export function BMPointMakeWithX(x, args) {
+	return new BMPoint(x || 0, (args && args.y) || 0);
+};
+
+
+/**
+ * Constructs and returns a new point with the given cartesian coordinates.
+ * @param x <Number, nullable>     	Defaults to 0. The x coordinate.
+ * {
+ * 	@param y <Number, nullable>     Defaults to 0. The y coordinate.
+ * }
+ * @return <BMPoint>				A Point.
+ */
+BMPoint.pointWithX = BMPointMakeWithX;
+
+
+/**
+ * Constructs and returns a new point with the given polar coordinates.
+ * @param radius <Number, nullable>     	Defaults to 0. The polar radius coordinate.
+ * {
+ * 	@param angle <Number, nullable>     	Defaults to 0. The polar angle coordinate in radians.
+ * }
+ * @return <BMPoint>				A Point.
+ */
+export function BMPointMakeWithRadius(radius = 0, {angle = 0} = {angle: 0}) {
+	return BMPointMake(
+		radius * Math.cos(angle),
+		radius * Math.sin(angle)
+	);
+};
+
+
+/**
+ * Constructs and returns a new point with the given polar coordinates.
+ * @param radius <Number, nullable>     	Defaults to 0. The polar radius coordinate.
+ * {
+ * 	@param angle <Number, nullable>     	Defaults to 0. The polar angle coordinate in radians.
+ * }
+ * @return <BMPoint>						A Point.
+ */
+BMPoint.pointWithRadius = BMPointMakeWithRadius;
+
+/**
+ * Computes and returns the absolute distance between the two given points.
+ * @param fromPoint <BMPoint>		The first point.
+ * @param toPoint <BMPoint>			The second point.
+ * @return <Number>					The distance between the two points.
+ */
+export function BMDistanceBetweenPoints(fromPoint, toPoint) {
+	return Math.sqrt(Math.pow(toPoint.x - fromPoint.x, 2) + Math.pow(toPoint.y - fromPoint.y, 2));
+}
+
+/**
+ * Computes and returns the slope angle, in radians, between the two given points.
+ * @param fromPoint <BMPoint>		The first point.
+ * @param toPoint <BMPoint>			The second point.
+ * @return <Number>					The angle in radians.
+ */
+export function BMSlopeAngleBetweenPoints(fromPoint, toPoint) {
+	return Math.atan2(toPoint.y - fromPoint.y, toPoint.x - fromPoint.x);
+}
+
+/**
+ * Represents the origin point.
+ */
+export const BMOriginPoint = BMPointMake(0, 0);
+
+// @endtype