Merge pull request #579 from clauderic/custom-indices-getter

Expose overscanIndices getter to make it user-extendable

docs/Grid.md

@@ -22,6 +22,7 @@ A windowed grid of elements. `Grid` only renders cells necessary to fill itself
 | onSectionRendered | Function |  | Callback invoked with information about the section of the Grid that was just rendered. This callback is only invoked when visible rows have changed: `({ columnOverscanStartIndex: number, columnOverscanStopIndex: number, columnStartIndex: number, columnStopIndex: number, rowOverscanStartIndex: number, rowOverscanStopIndex: number, rowStartIndex: number, rowStopIndex: number }): void` |
 | onScroll | Function |  | Callback invoked whenever the scroll offset changes within the inner scrollable region: `({ clientHeight: number, clientWidth: number, scrollHeight: number, scrollLeft: number, scrollTop: number, scrollWidth: number }): void` |
 | overscanColumnCount | Number |  | Number of columns to render before/after the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. |
+| overscanIndicesGetter | Function |  | Responsible for calculating the number of cells to overscan before and after a specified range [Learn more](#overscanIndicesGetter) |
 | overscanRowCount | Number |  | Number of rows to render above/below the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. |
 | rowCount | Number | ✓ | Number of rows in grid. |
 | rowHeight | Number or Function | ✓ | Either a fixed row height (number) or a function that returns the height of a row given its index: `({ index: number }): number` |
@@ -147,6 +148,10 @@ function cellRangeRenderer ({
 }
 ```
 
+### overscanIndicesGetter
+This is an advanced property.
+This function is responsible for calculating the number of cells to overscan before and after a specified range. By default, React Virtualized optimizes the number of cells to overscan based on scroll direction. If you'd like to customize this behavior, you may want to fork the [`defaultOverscanIndicesGetter`](https://github.com/bvaughn/react-virtualized/blob/master/source/Grid/utils/defaultOverscanIndicesGetter.js) function.
+
 ### cellRenderer
 
 Responsible for rendering a single cell, given its row and column index.
@@ -173,15 +178,15 @@ function cellRenderer ({
   // Style is required since it specifies how the cell is to be sized and positioned,
   // and React Virtualized depends on this sizing/positioning for proper scrolling behavior.
   // By default, the grid component specifies, calculates, and initializes the following style properties:
-  //    height 
-  //    width 
+  //    height
+  //    width
   //    left
   //    top
   //    position
   // You can add additional class names or style properties as you would like.
   // Key is also required by React to more efficiently manage the array of cells.
   return (
-    <div 
+    <div
       key={key}
       style={style}
     >

source/Grid/Grid.jest.js

@@ -5,7 +5,7 @@ import { Simulate } from 'react-addons-test-utils'
 import { render } from '../TestUtils'
 import shallowCompare from 'react-addons-shallow-compare'
 import Grid, { DEFAULT_SCROLLING_RESET_TIME_INTERVAL } from './Grid'
-import { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/getOverscanIndices'
+import { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/defaultOverscanIndicesGetter'
 import { DEFAULT_MAX_SCROLL_SIZE } from './utils/ScalingCellSizeAndPositionManager'
 
 const DEFAULT_COLUMN_WIDTH = 50

source/Grid/Grid.js

@@ -4,7 +4,7 @@ import cn from 'classnames'
 import calculateSizeAndPositionDataAndUpdateScrollOffset from './utils/calculateSizeAndPositionDataAndUpdateScrollOffset'
 import ScalingCellSizeAndPositionManager from './utils/ScalingCellSizeAndPositionManager'
 import createCallbackMemoizer from '../utils/createCallbackMemoizer'
-import getOverscanIndices, { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/getOverscanIndices'
+import defaultOverscanIndicesGetter, { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/defaultOverscanIndicesGetter'
 import getScrollbarSize from 'dom-helpers/util/scrollbarSize'
 import shallowCompare from 'react-addons-shallow-compare'
 import updateScrollIndexHelper from './utils/updateScrollIndexHelper'
@@ -134,6 +134,19 @@ export default class Grid extends Component {
      */
     overscanColumnCount: PropTypes.number.isRequired,
 
+    /**
+     * Calculates the number of cells to overscan before and after a specified range.
+     * This function ensures that overscanning doesn't exceed the available cells.
+     * Should implement the following interface: ({
+     *   cellCount: number,
+     *   overscanCellsCount: number,
+     *   scrollDirection: number,
+     *   startIndex: number,
+     *   stopIndex: number
+     * }): {overscanStartIndex: number, overscanStopIndex: number}
+     */
+    overscanIndicesGetter: PropTypes.func.isRequired,
+
     /**
      * Number of rows to render above/below the visible section of the grid.
      * These rows can help for smoother scrolling on touch devices or browsers that send scroll events infrequently.
@@ -198,6 +211,7 @@ export default class Grid extends Component {
     onScroll: () => null,
     onSectionRendered: () => null,
     overscanColumnCount: 0,
+    overscanIndicesGetter: defaultOverscanIndicesGetter,
     overscanRowCount: 10,
     scrollingResetTimeInterval: DEFAULT_SCROLLING_RESET_TIME_INTERVAL,
     scrollToAlignment: 'auto',
@@ -629,6 +643,7 @@ export default class Grid extends Component {
       columnCount,
       height,
       overscanColumnCount,
+      overscanIndicesGetter,
       overscanRowCount,
       rowCount,
       width
@@ -670,15 +685,15 @@ export default class Grid extends Component {
       this._renderedRowStartIndex = visibleRowIndices.start
       this._renderedRowStopIndex = visibleRowIndices.stop
 
-      const overscanColumnIndices = getOverscanIndices({
+      const overscanColumnIndices = overscanIndicesGetter({
         cellCount: columnCount,
         overscanCellsCount: overscanColumnCount,
         scrollDirection: scrollDirectionHorizontal,
         startIndex: this._renderedColumnStartIndex,
         stopIndex: this._renderedColumnStopIndex
       })
 
-      const overscanRowIndices = getOverscanIndices({
+      const overscanRowIndices = overscanIndicesGetter({
         cellCount: rowCount,
         overscanCellsCount: overscanRowCount,
         scrollDirection: scrollDirectionVertical,

source/Grid/utils/getOverscanIndices.jest.js → source/Grid/utils/defaultOverscanIndicesGetter.jest.js

@@ -1,17 +1,17 @@
-import getOverscanIndices, {
+import overscanIndicesGetter, {
   SCROLL_DIRECTION_BACKWARD,
   SCROLL_DIRECTION_FORWARD
-} from './getOverscanIndices'
+} from './defaultOverscanIndicesGetter'
 
-describe('getOverscanIndices', () => {
+describe('overscanIndicesGetter', () => {
   function testHelper ({
     cellCount,
     startIndex,
     stopIndex,
     overscanCellsCount,
     scrollDirection
   }) {
-    return getOverscanIndices({
+    return overscanIndicesGetter({
       cellCount,
       overscanCellsCount,
       scrollDirection,

source/Grid/utils/getOverscanIndices.js → source/Grid/utils/defaultOverscanIndicesGetter.js

@@ -6,12 +6,12 @@ export const SCROLL_DIRECTION_FORWARD = 1
  * This function ensures that overscanning doesn't exceed the available cells.
  *
  * @param cellCount Number of rows or columns in the current axis
- * @param scrollDirection One of SCROLL_DIRECTION_BACKWARD
+ * @param scrollDirection One of SCROLL_DIRECTION_BACKWARD or SCROLL_DIRECTION_FORWARD
  * @param overscanCellsCount Maximum number of cells to over-render in either direction
  * @param startIndex Begin of range of visible cells
  * @param stopIndex End of range of visible cells
  */
-export default function getOverscanIndices ({ cellCount, overscanCellsCount, scrollDirection, startIndex, stopIndex }) {
+export default function defaultOverscanIndicesGetter ({ cellCount, overscanCellsCount, scrollDirection, startIndex, stopIndex }) {
   let overscanStartIndex
   let overscanStopIndex