bm-core-ui 2.7.0 → 2.8.3

package/build/BMCollectionView/BMCollectionViewFlowLayout.js

@@ -18,7 +18,7 @@ const BM_AUTOMATIC_CELL_SIZE_MESSAGES = NO;
 /**
  * Constants representing the types of supplementary views that table layouts support.
  */
-export var BMCollectionViewTableLayoutSupplementaryView = Object.freeze({
+export var BMCollectionViewTableLayoutSupplementaryView = Object.freeze({ // <enum>
 	/**
 	 * Indicates that this supplementary view is a footer.
 	 */
@@ -1279,38 +1279,38 @@ BMExtend(BMCollectionViewTreeLayout.prototype, BMCollectionViewLayout.prototype,
 /**
  * Controls how cells are distributed within their row.
  */
-export var BMCollectionViewFlowLayoutGravity = Object.freeze({
+export var BMCollectionViewFlowLayoutGravity = Object.freeze({ // <enum>
 	
 	/**
 	 * The cells will flow to the center of the row with no spacing between them.
 	 */
-	Center: {},
+	Center: {}, // <enum>
 	
 	/**
 	 * The cells will be aligned to the start of the row.
 	 */
-	Start: {},
+	Start: {}, // <enum>
 	
 	/**
 	 * The cells will be aligned to the end of the row.
 	 */
-	End: {},
+	End: {}, // <enum>
 	
 	/**
 	 * The cells will flow to the edges of the row with equal spacing between them.
 	 */
-	Edge: {},
+	Edge: {}, // <enum>
 	
 	/**
 	 * The cells will flow such that they have equal spacing between them and the row edges.
 	 */
-	Spaced: {},
+	Spaced: {}, // <enum>
 	
 	/**
 	 * The cells will flow such that they will have no spacing between them.
 	 * If the cells in a row do not occupy the entire horizontal alrea of that row, they will be expanded proportionally until they do.
 	 */
-	Expand: {}
+	Expand: {} // <enum>
 	
 });
 
@@ -1325,39 +1325,39 @@ export var BMCollectionViewFlowLayoutAlignment = (function () {
 	/**
 	 * Controls how cells will be aligned within their row.
 	 */
-	var BMCollectionViewFlowLayoutAlignment = Object.freeze({
+	var BMCollectionViewFlowLayoutAlignment = Object.freeze({ // <enum>
 		
 		/**
 		 * @deprecated Use `Start`
 		 * The cells will be aligned to the starting edge of the row.
 		 */
-		Top: start,
+		Top: start, // <enum>
 		
 		/**
 		 * The cells will be aligned to the start of the row.
 		 */
-		Start: start,
+		Start: start, // <enum>
 		
 		/**
 		 * The cells will be aligned to the center of the row.
 		 */
-		Center: {},
+		Center: {}, // <enum>
 		
 		/**
 		 * @deprecated Use `End`
 		 * The cells will be aligned to the end of the row.
 		 */
-		Bottom: end,
+		Bottom: end, // <enum>
 		
 		/**
 		 * The cells will be aligned to the end of the row.
 		 */
-		End: end,
+		End: end, // <enum>
 		
 		/**
 		 * The cells will expand to fit the entire height of the row.
 		 */
-		Expand: {}
+		Expand: {} // <enum>
 		
 	});
 
@@ -1371,18 +1371,18 @@ export var BMCollectionViewFlowLayoutAlignment = (function () {
 /**
  * An enum containing the possible orientations that the flow layout can use.
  */
-export var BMCollectionViewFlowLayoutOrientation = Object.freeze({
+export var BMCollectionViewFlowLayoutOrientation = Object.freeze({ // <enum>
 	/**
 	 * Indicates that the flow layout will arrange cells primarily along the horizontal axis.
 	 * When the orientation is set to this value the flow layout will scroll horizontally.
 	 */
-	Horizontal: {},
+	Horizontal: {}, // <enum>
 
 	/**
 	 * Indicates that the flow layout will arrange cells primarily along the vertical axis.
 	 * When the orientation is set to this value the tile flow will scroll vertically.
 	 */
-	Vertical: {}
+	Vertical: {} // <enum>
 });
 
 // @endtype
@@ -1699,9 +1699,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 	 * When using automatic cell sizes, the generator will yield execution and only calculate portions of the layout on demand.
 	 * With the exeption of the first invocation, it is required to pass an index path to the iterator's `next` method. The layout process
 	 * will continue until it fully lays out the cell for that index path, at which point it will yield again.
-	 * @param useOffset <Boolean>			When set to `YES` the layout will take the scrollbar size into account.
+	 * @param useOffset <Boolean>							When set to `YES` the layout will take the scrollbar size into account.
+	 * {
+	 * 	@param targetRect <BMRect, nullable>				When computing a layout using automatic cell sizes, this is an optional rect up to which
+	 * 														to measure cells. This is reserved for when this is invoked as a delegate.
+	 * 	@param targetIndexPath <BMIndexPath, nullable>		When computing a layout using automatic cell sizes, this is an optional index path up to which
+	 * 														to measure cells. This is reserved for when this is invoked as a delegate.
+	 * }
 	 */
-	*_prepareLayoutWithScrollbarOffsetGenerator(useOffset) {
+	*_prepareLayoutWithScrollbarOffsetGenerator(useOffset, target) {
 		
 		// To standardize naming in order to support the orientation setting, the following terms are used:
 		// Length - refers to the dimension across the axis on which collection view scrolls: height for vertical and width for horizontal
@@ -1803,7 +1809,6 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 				targetRect?: BMRect;
 			}
 			*/
-			let target;
 
 			// The sections that contain the preliminary layout
 			const preliminarySections = [];
@@ -1981,8 +1986,11 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 					else {
 						// If there is no minimum spacing required, then the number of columns is simply the available space divided
 						// by the cell width
-						numberOfColumns = ((maximumLength / expectedSize) | 0) || 1;
+						numberOfColumns = (maximumLength / expectedSize) | 0;
 					}
+
+					// Ensure that there is at least one column
+					numberOfColumns = Math.max(numberOfColumns, 1);
 				}
 
 				// Create the preliminary sections
@@ -2066,7 +2074,12 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 
 					cachedLayout.size = BMSizeMake(this.collectionView.frame.size.width, height);
 	
-					target = yield;
+					// Yield after building the preliminary layout and wait for a target rect or index path up to which to measure
+					if (!target) {
+						// If a target is already supplied (as a parameter) this is a delegate generator and processing should continue
+						// until this target
+						target = yield;
+					}
 
 					// When requesting a rect initially, pre-measure the cells up to that rect
 					if (target.rect) {
@@ -2082,7 +2095,13 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 
 					cachedLayout.size = BMSizeMake(width, this.collectionView.frame.size.height);
 	
-					target = yield;
+					// Yield after building the preliminary layout and wait for a target rect or index path up to which to measure
+					if (!target) {
+						// If a target is already supplied (as a parameter) this is a delegate generator and processing should continue
+						// until this target
+						target = yield;
+					}
+
 					// When requesting a rect initially, pre-measure the cells up to that rect
 					if (target.rect) {
 						measureCellsInRect(target.rect);
@@ -2217,7 +2236,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 
 						// If the row height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 						if (row[rowStartAttribute] + rowBreadth > frameSize) {
-							if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+							if (this.collectionView.scrollBarSize && !useOffset) {
+								if (target) {
+									// With automatic cell size delegate iteration to the new invocation
+									return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+								}
+								else {
+									return this._prepareLayoutWithScrollbarOffset(YES);
+								}
+							}
 						}
 						
 						// if there is one
@@ -2380,7 +2407,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 						
 						// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 						if (height > frameHeight) {
-							if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+							if (this.collectionView.scrollBarSize && !useOffset) {
+								if (target) {
+									// With automatic cell size delegate iteration to the new invocation
+									return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+								}
+								else {
+									return this._prepareLayoutWithScrollbarOffset(YES);
+								}
+							}
 						}
 					}
 					else {
@@ -2401,7 +2436,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 						
 						// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 						if (width > frameWidth) {
-							if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+							if (this.collectionView.scrollBarSize && !useOffset) {
+								if (target) {
+									// With automatic cell size delegate iteration to the new invocation
+									return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+								}
+								else {
+									return this._prepareLayoutWithScrollbarOffset(YES);
+								}
+							}
 						}
 					}
 				}
@@ -2415,7 +2458,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 					
 					// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 					if (height > frameHeight) {
-						if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+						if (this.collectionView.scrollBarSize && !useOffset) {
+							if (target) {
+								// With automatic cell size delegate iteration to the new invocation
+								return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+							}
+							else {
+								return this._prepareLayoutWithScrollbarOffset(YES);
+							}
+						}
 					}
 				}
 				else {
@@ -2426,7 +2477,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 					
 					// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 					if (width > frameWidth) {
-						if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+						if (this.collectionView.scrollBarSize && !useOffset) {
+							if (target) {
+								// With automatic cell size delegate iteration to the new invocation
+								return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+							}
+							else {
+								return this._prepareLayoutWithScrollbarOffset(YES);
+							}
+						}
 					}
 				}
 				
@@ -2437,7 +2496,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 				
 				// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 				if (height > frameHeight) {
-					if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+					if (this.collectionView.scrollBarSize && !useOffset) {
+						if (target) {
+							// With automatic cell size delegate iteration to the new invocation
+							return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+						}
+						else {
+							return this._prepareLayoutWithScrollbarOffset(YES);
+						}
+					}
 				}
 			
 				// If the height is lower than the collection view's height, the content gravity must be applied to all cached attributes
@@ -2531,7 +2598,15 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 			else {
 				// If the total height exceeds the collection view frame height, perform a second layout pass to account for the scrollbars
 				if (width > frameWidth) {
-					if (this.collectionView.scrollBarSize && !useOffset) return this._prepareLayoutWithScrollbarOffset(YES);
+					if (this.collectionView.scrollBarSize && !useOffset) {
+						if (target) {
+							// With automatic cell size delegate iteration to the new invocation
+							return yield *this._prepareLayoutWithScrollbarOffsetGenerator(YES, target);
+						}
+						else {
+							return this._prepareLayoutWithScrollbarOffset(YES);
+						}
+					}
 				}
 			
 				// If the height is lower than the collection view's height, the content gravity must be applied to all cached attributes
@@ -2604,7 +2679,7 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 								const scaledRowHeight = rowWidth * scaleFactor | 0;
 								for (const attribute of row.attributes) {
 									attribute.frame.origin.x += displacement;
-									attribute.frame.size.height = attribute.frame.size.height * scaleFactor | 0;
+									attribute.frame.size.width = attribute.frame.size.width * scaleFactor | 0;
 								}
 
 								// Advance the displacement based on the row's new width then displace the row end
@@ -2711,8 +2786,10 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
 				else {
 					// If there is no minimum spacing required, then the number of columns is simply the available space divided
 					// by the cell width
-					numberOfColumns = ((length / cellSize) | 0) || 1;
+					numberOfColumns = (length / cellSize) | 0;
 				}
+
+				numberOfColumns = Math.max(numberOfColumns, 1);
 			}
 			cachedLayout.numberOfColumns = numberOfColumns;
 			
@@ -4420,6 +4497,319 @@ BMCollectionViewFlowLayout.prototype = BMExtend(Object.create(BMCollectionViewLa
         
         return attributes;
     },
+
+	// @override - BMCollectionViewLayout
+	indexPathToTheLeftOfIndexPath(indexPath) {
+		// In a horizontal layout this function the same as above for vertical,
+		// shifting to the previous row to a column with similar positioning
+		if (this._orientation == BMCollectionViewFlowLayoutOrientation.Horizontal) {
+			if (!this._cellSize || this._expectedCellSize) return this._cachedIndexPathAboveIndexPath(indexPath);
+	
+			return this._computedIndexPathAboveIndexPath(indexPath);
+		}
+
+		// Otherwise the base implementation is sufficient
+		return BMCollectionViewLayout.prototype.indexPathToTheLeftOfIndexPath.apply(this, arguments);
+	},
+
+	// @override - BMCollectionViewLayout
+	indexPathAboveIndexPath(indexPath) {
+		// In a horizontal layout the base implementation is sufficient
+		if (this._orientation == BMCollectionViewFlowLayoutOrientation.Horizontal) {
+			return BMCollectionViewLayout.prototype.indexPathToTheLeftOfIndexPath.apply(this, arguments);
+		}
+
+		if (!this._cellSize || this._expectedCellSize) return this._cachedIndexPathAboveIndexPath(indexPath);
+
+		return this._computedIndexPathAboveIndexPath(indexPath);
+	},
+
+	// @override - BMCollectionViewLayout
+	indexPathToTheRightOfIndexPath(indexPath) {
+		// In a horizontal layout this function the same as below for vertical,
+		// shifting to the next row to a column with similar positioning
+		if (this._orientation == BMCollectionViewFlowLayoutOrientation.Horizontal) {
+			if (!this._cellSize || this._expectedCellSize) return this._cachedIndexPathBelowIndexPath(indexPath);
+	
+			return this._computedIndexPathBelowIndexPath(indexPath);
+		}
+
+		// Otherwise the base implementation is sufficient
+		return BMCollectionViewLayout.prototype.indexPathToTheRightOfIndexPath.apply(this, arguments);
+	},
+
+	// @override - BMCollectionViewLayout
+	indexPathBelowIndexPath(indexPath) {
+		// In a horizontal layout the base implementation is sufficient
+		if (this._orientation == BMCollectionViewFlowLayoutOrientation.Horizontal) {
+			return BMCollectionViewLayout.prototype.indexPathToTheRightOfIndexPath.apply(this, arguments);
+		}
+
+		if (!this._cellSize || this._expectedCellSize) return this._cachedIndexPathBelowIndexPath(indexPath);
+
+		return this._computedIndexPathBelowIndexPath(indexPath);
+	},
+
+	/**
+	 * Returns the index path that is above the given index path in a cached layout.
+	 * In a horizontal layout this returns the index path that is to the left of the given index path.
+	 * @param indexPath <BMIndexPath>		The index path to start from.
+	 * @returns <BMIndexPath>				The index path above the given one.
+	 */
+	_cachedIndexPathAboveIndexPath(indexPath) {
+		const section = indexPath.section;
+		const row = indexPath.row;
+
+		// Find the row where the current index path is
+		const cachedSection = this.cachedLayout.sections[section];
+
+		if (!cachedSection) return indexPath;
+
+		const sectionRows = cachedSection.rows;
+		
+		let rowIndex = 0;
+		const rowCount = sectionRows.length;
+		for (rowIndex; rowIndex < rowCount; rowIndex++) {
+			const sectionRow = sectionRows[rowIndex];
+			if (sectionRow.startIndex <= row && sectionRow.endIndex >= row) {
+				break;
+			}
+		}
+
+		const attributes = sectionRows[rowIndex].attributes.find(a => a.indexPath.row == row);
+		const positionProperty = this._orientation == BMCollectionViewFlowLayoutOrientation.Vertical ? 'x' : 'y';
+		const position = attributes.frame.center[positionProperty];
+
+		let previousRow;
+
+		// Find the next row, if any
+		if (rowIndex >= 0) {
+			const previousRowIndex = rowIndex - 1;
+			previousRow = sectionRows[previousRowIndex];
+		}
+		else {
+			// If the current row is the first one in its section, find the next section that has at least one row
+			let sectionIndex = section - 1;
+			while (sectionIndex >= 0) {
+				if (this.collectionView.numberOfObjectsInSectionAtIndex(sectionIndex)) {
+					previousRow = this.cachedLayout.sections[sectionIndex].sectionRows[this.cachedLayout.sections[sectionIndex].sectionRows.length - 1];
+					break;
+				}
+				sectionIndex--;
+			}
+		}
+
+
+		// If no viable row is found, the current row is the first one
+		if (previousRow) {
+			// In this row, return the index path for the attributes with
+			// the closest horizontal distance from the source index path
+			let minDistance = Number.MAX_SAFE_INTEGER;
+			let minDistanceIndex = -1;
+			for (let i = 0; i < previousRow.attributes.length; i++) {
+				const attributes = previousRow.attributes[i];
+				const distance = Math.abs(attributes.frame.center[positionProperty] - position);
+
+				if (distance < minDistance) {
+					minDistance = distance;
+					minDistanceIndex = i;
+				}
+			}
+
+			return previousRow.attributes[minDistanceIndex].indexPath;
+		}
+
+		return indexPath;
+	},
+
+	/**
+	 * Returns the index path that is above the given index path in a computed layout.
+	 * In a horizontal layout this returns the index path that is to the left of the given index path.
+	 * @param indexPath <BMIndexPath>		The index path to start from.
+	 * @returns <BMIndexPath>				The index path above the given one.
+	 */
+	_computedIndexPathAboveIndexPath(indexPath) {
+		const cache = this.cachedLayout;
+		
+		var sectionIndex = indexPath.section;
+		
+		const numberOfColumns = cache.numberOfColumns;
+		
+		var objectIndex = indexPath.row;
+		
+		// Find the row and column index within the section
+		const cellRow = (objectIndex / numberOfColumns) | 0;
+		const cellColumn = objectIndex % numberOfColumns;
+
+		let previousRow;
+
+		if (cellRow > 0) {
+			previousRow = cellRow - 1;
+		}
+		else {
+			// If the current row is the last one in its section, find the next section that has at least one row
+			let previousSectionIndex = sectionIndex - 1;
+			while (previousSectionIndex >= 0) {
+				if (this.collectionView.numberOfObjectsInSectionAtIndex(previousSectionIndex)) {
+					previousRow = cache.sections[previousSectionIndex].numberOfRows - 1;
+					sectionIndex = previousSectionIndex;
+					break;
+				}
+				previousSectionIndex--;
+			}
+		}
+
+		if (typeof previousRow != 'number') return indexPath;
+
+		const nextRowIndexStart = numberOfColumns * previousRow;
+		const nextSectionNumberOfObjects = this.collectionView.numberOfObjectsInSectionAtIndex(sectionIndex);
+		
+		
+		// Find this cell's row prototype. In most cases this will be the prototype for the numberOfColumns columns,
+		// unless this cell is in the last row - in those cases it is possible that there may be fewer columns
+		if (previousRow == ((nextSectionNumberOfObjects / numberOfColumns) | 0)) {
+			var numberOfColumnsInLastRow = (nextSectionNumberOfObjects % numberOfColumns) || numberOfColumns;
+			
+			return this.collectionView.indexPathForObjectAtRow(nextRowIndexStart + Math.min(numberOfColumnsInLastRow, cellColumn), {inSectionAtIndex: sectionIndex})
+		}
+		else {
+			return this.collectionView.indexPathForObjectAtRow(nextRowIndexStart + cellColumn, {inSectionAtIndex: sectionIndex});
+		}
+		
+	},
+
+	/**
+	 * Returns the index path that is below the given index path in a cached layout.
+	 * In a horizontal layout this returns the index path that is to the right of the given index path.
+	 * @param indexPath <BMIndexPath>		The index path to start from.
+	 * @returns <BMIndexPath>				The index path below the given one.
+	 */
+	_cachedIndexPathBelowIndexPath(indexPath) {
+		const sectionCount = this.collectionView.numberOfSections();
+
+		const section = indexPath.section;
+		const row = indexPath.row;
+
+		// Find the row where the current index path is
+		const cachedSection = this.cachedLayout.sections[section];
+
+		if (!cachedSection) return indexPath;
+
+		const sectionRows = cachedSection.rows;
+		
+		let rowIndex = 0;
+		const rowCount = sectionRows.length;
+		for (rowIndex; rowIndex < rowCount; rowIndex++) {
+			const sectionRow = sectionRows[rowIndex];
+			if (sectionRow.startIndex <= row && sectionRow.endIndex >= row) {
+				break;
+			}
+		}
+
+		const attributes = sectionRows[rowIndex].attributes.find(a => a.indexPath.row == row);
+		const positionProperty = this._orientation == BMCollectionViewFlowLayoutOrientation.Vertical ? 'x' : 'y';
+		const position = attributes.frame.center[positionProperty];
+
+		let nextRow;
+
+		// Find the next row, if any
+		if (rowIndex < rowCount - 1) {
+			const nextRowIndex = rowIndex + 1;
+			nextRow = sectionRows[nextRowIndex];
+		}
+		else {
+			// If the current row is the last one in its section, find the next section that has at least one row
+			let sectionIndex = section + 1;
+			while (sectionIndex < sectionCount) {
+				if (this.collectionView.numberOfObjectsInSectionAtIndex(sectionIndex)) {
+					nextRow = this.cachedLayout.sections[sectionIndex].sectionRows[0];
+					break;
+				}
+				sectionIndex++;
+			}
+		}
+
+
+		// If no viable row is found, the current row is the last one
+		if (nextRow) {
+			// In this row, return the index path for the attributes with
+			// the closest horizontal distance from the source index path
+			let minDistance = Number.MAX_SAFE_INTEGER;
+			let minDistanceIndex = -1;
+			for (let i = 0; i < nextRow.attributes.length; i++) {
+				const attributes = nextRow.attributes[i];
+				const distance = Math.abs(attributes.frame.center[positionProperty] - position);
+
+				if (distance < minDistance) {
+					minDistance = distance;
+					minDistanceIndex = i;
+				}
+			}
+
+			return nextRow.attributes[minDistanceIndex].indexPath;
+		}
+
+		return indexPath;
+	},
+
+	/**
+	 * Returns the index path that is below the given index path in a computed layout.
+	 * In a horizontal layout this returns the index path that is to the left of the given index path.
+	 * @param indexPath <BMIndexPath>		The index path to start from.
+	 * @returns <BMIndexPath>				The index path below the given one.
+	 */
+	_computedIndexPathBelowIndexPath(indexPath) {
+		const sectionCount = this.collectionView.numberOfSections();
+
+		const cache = this.cachedLayout;
+		
+		var sectionIndex = indexPath.section;
+		var section = cache.sections[sectionIndex];
+		
+		const numberOfColumns = cache.numberOfColumns;
+		
+		var objectIndex = indexPath.row;
+		
+		// Find the row and column index within the section
+		const cellRow = (objectIndex / numberOfColumns) | 0;
+		const cellColumn = objectIndex % numberOfColumns;
+
+		let nextRow;
+
+		if (cellRow < section.numberOfRows - 1) {
+			nextRow = cellRow + 1;
+		}
+		else {
+			// If the current row is the last one in its section, find the next section that has at least one row
+			let nextSectionIndex = sectionIndex + 1;
+			while (nextSectionIndex < sectionCount) {
+				if (this.collectionView.numberOfObjectsInSectionAtIndex(nextSectionIndex)) {
+					nextRow = 0;
+					sectionIndex = nextSectionIndex;
+					break;
+				}
+				nextSectionIndex++;
+			}
+		}
+
+		if (typeof nextRow != 'number') return indexPath;
+
+		const nextRowIndexStart = numberOfColumns * nextRow;
+		const nextSectionNumberOfObjects = this.collectionView.numberOfObjectsInSectionAtIndex(sectionIndex);
+		
+		
+		// Find this cell's row prototype. In most cases this will be the prototype for the numberOfColumns columns,
+		// unless this cell is in the last row - in those cases it is possible that there may be fewer columns
+		if (nextRow == ((nextSectionNumberOfObjects / numberOfColumns) | 0)) {
+			var numberOfColumnsInLastRow = (nextSectionNumberOfObjects % numberOfColumns) || numberOfColumns;
+			
+			return this.collectionView.indexPathForObjectAtRow(nextRowIndexStart + Math.min(numberOfColumnsInLastRow, cellColumn), {inSectionAtIndex: sectionIndex})
+		}
+		else {
+			return this.collectionView.indexPathForObjectAtRow(nextRowIndexStart + cellColumn, {inSectionAtIndex: sectionIndex});
+		}
+		
+	},
 	
 	// @override - BMCollectionViewLayout
 	copy: function () {