Merge pull request #206 from bvaughn/version-7

Version 7

Author: bvaughn

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
-node_modules
-npm-debug.log
 build
 coverage
+dist
+node_modules
+npm-debug.log

.npmignore

@@ -1,4 +1,5 @@
 build
+codemods
 coverage
 docs
 source

CHANGELOG.md

@@ -1,6 +1,10 @@
 Changelog
 ------------
 
+# 7.0.0
+Version 7 changes are described in detail on the [Version 7 Roadmap wiki page](https://github.com/bvaughn/react-virtualized/wiki/Version-7-Roadmap).
+Upgrade instructions and [jscodeshift](https://github.com/facebook/jscodeshift) mods can also be found there.
+
 ##### 6.3.2
 Fixed edge-case bug in `Collection` where initial `scrollLeft` and `scrollTop` would not correctly adjust inner offsets.
 Thanks @edulan for the contribution!

README.md

@@ -61,6 +61,7 @@ There are also a couple of how-to guides:
 * [Displaying items in reverse order](docs/reverseList.md)
 * [Using AutoSizer](docs/usingAutoSizer.md)
 * [Creating an infinite-loading list](docs/creatingAnInfiniteLoadingList.md)
+* [Displaying a reverse list](docs/reverseList.md)
 
 Examples
 ---------------
@@ -71,6 +72,7 @@ Here are some online demos of each component:
 
 * [ArrowKeyStepper](https://bvaughn.github.io/react-virtualized/?component=ArrowKeyStepper)
 * [AutoSizer](https://bvaughn.github.io/react-virtualized/?component=AutoSizer)
+* [CellMeasurer](https://bvaughn.github.io/react-virtualized/?component=CellMeasurer)
 * [Collection](https://bvaughn.github.io/react-virtualized/?component=Collection)
 * [ColumnSizer](https://bvaughn.github.io/react-virtualized/?component=ColumnSizer)
 * [FlexTable](https://bvaughn.github.io/react-virtualized/?component=FlexTable)
@@ -82,6 +84,8 @@ Here are some online demos of each component:
 And here are some "recipe" type demos:
 * [Collapsable tree view](https://rawgit.com/bvaughn/react-virtualized/master/playground/tree.html)
 * [Full-page grid (spreadsheet)](https://rawgit.com/bvaughn/react-virtualized/master/playground/grid.html)
+* [Dyanmic cell measuring](https://rawgit.com/bvaughn/react-virtualized/master/playground/chat.html)
+* [Cell hover effects](https://rawgit.com/bvaughn/react-virtualized/master/playground/hover.html)
 
 Contributions
 ------------

codemods/6-to-7/rename-properties.js

@@ -0,0 +1,63 @@
+'use strict'
+
+// Renames react-virtualized version 6.x properties to be version-7 compatible
+module.exports = function transformer (file, api) {
+  const jscodeshift = api.jscodeshift
+
+  let source = file.source
+
+  // Rename variable references
+  for (var property in propertyRenameMap) {
+    source = jscodeshift(source)
+      .findVariableDeclarators(property)
+      .renameTo(propertyRenameMap[property])
+      .toSource()
+  }
+
+  // Rename JSX attributes
+  source = jscodeshift(source)
+    .find(jscodeshift.JSXAttribute)
+    .filter(shouldAttributeBeRenamed)
+    .replaceWith(renameReactVirtualizedAttribute)
+    .toSource()
+
+  return source
+}
+
+const reactVirtualizedElementNames = [
+  'ArrowKeyStepper',
+  'AutoSizer',
+  'Collection',
+  'ColumnSizer',
+  'FlexTable',
+  'Grid',
+  'ScrollSync',
+  'VirtualScroll'
+]
+
+// @param path jscodeshift.JSXAttribute
+const attributeBelongsToReactVirtualizedElement = path => reactVirtualizedElementNames.includes(path.parent.value.name.name)
+
+// See https://github.com/bvaughn/react-virtualized/wiki/Version-7-Roadmap#clean-up-property-names
+const propertyRenameMap = {
+  cellClassName: 'className',
+  columnsCount: 'columnCount',
+  overscanColumnsCount: 'overscanColumnCount',
+  overscanRowsCount: 'overscanRowCount',
+  renderCell: 'cellRenderer',
+  renderCellRanges: 'cellRangeRenderer',
+  rowsCount: 'rowCount'
+}
+
+// @param path jscodeshift.JSXAttribute
+const shouldAttributeBeRenamed = path => attributeBelongsToReactVirtualizedElement(path) && isAttributeInPropertyRenameMap(path)
+
+// @param path jscodeshift.JSXAttribute
+const isAttributeInPropertyRenameMap = path => propertyRenameMap.hasOwnProperty(path.value.name.name)
+
+// @param path jscodeshift.JSXAttribute
+const renameReactVirtualizedAttribute = path => {
+  path.value.name.name = propertyRenameMap[path.value.name.name] || path.value.name.name
+
+  return path.node
+}

docs/ArrowKeyStepper.md

@@ -10,18 +10,17 @@ The appearance of this wrapper element can be customized using the `className` p
 ### Prop Types
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
-| children | Function | ✓ | Function respondible for rendering children. This function should implement the following signature: `({ onKeyDown, onSectionRendered, scrollToColumn, scrollToRow }) => PropTypes.element` |
+| children | Function | ✓ | Function respondible for rendering children. This function should implement the following signature: `({ onSectionRendered: Function, scrollToColumn: number, scrollToRow: number }) => PropTypes.element` |
 | className | String |  | CSS class name to attach to the wrapper `<div>`. |
-| columnsCount | Number | ✓ | Number of columns in grid; for `FlexTable` and `VirtualScroll` this property should always be `1`. |
-| rowsCount | Number | ✓ | Number of rows in grid. |
+| columnCount | Number | ✓ | Number of columns in grid; for `FlexTable` and `VirtualScroll` this property should always be `1`. |
+| rowCount | Number | ✓ | Number of rows in grid. |
 
 ### Children function
 
 The child function is passed the following named parameters:
 
 | Parameter | Type | Description |
-|:---|:---|:---:|
-| onKeyDown | Function | Key-down event handler to be attached to the DOM hierarchy. |
+|:---|:---|:---|
 | onSectionRendered | Function | Pass-through callback to be attached to child component; informs the key-stepper which range of cells are currently visible. |
 | scrollToColumn | Number | Specifies which column in the child component should be visible |
 | scrollToRow | Number | Specifies which row in the child component should be visible |
@@ -38,20 +37,18 @@ import 'react-virtualized/styles.css'; // only needs to be imported once
 
 ReactDOM.render(
   <ArrowKeyStepper
-    columnsCount={columnsCount}
-    rowsCount={rowsCount}
+    columnCount={columnCount}
+    rowCount={rowCount}
   >
-    {({ onKeyDown, onSectionRendered, scrollToColumn, scrollToRow }) => (
-      <div onKeyDown={onKeyDown}>
-        <Grid
-          columnsCount={columnsCount}
-          onSectionRendered={onSectionRendered}
-          rowsCount={rowsCount}
-          scrollToColumn={scrollToColumn}
-          scrollToRow={scrollToRow}
-          {...otherGridProps}
-        />
-      </div>
+    {({ onSectionRendered, scrollToColumn, scrollToRow }) => (
+      <Grid
+        columnCount={columnCount}
+        onSectionRendered={onSectionRendered}
+        rowCount={rowCount}
+        scrollToColumn={scrollToColumn}
+        scrollToRow={scrollToRow}
+        {...otherGridProps}
+      />
     )}
   </ArrowKeyStepper>,
   document.getElementById('example')

docs/AutoSizer.md

@@ -6,10 +6,10 @@ High-order component that automatically adjusts the width and height of a single
 ### Prop Types
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
-| children | Function | ✓ | Function respondible for rendering children. This function should implement the following signature: `({ height, width }) => PropTypes.element` |
-| disableHeight | Boolean |  | If true the child's `height` property will not be managed |
-| disableWidth | Boolean |  | If true the child's `width` property will not be managed |
-| onResize | Function | Callback to be invoked on-resize; it is passed the following named parameters: `({ height, width })` | 
+| children | Function | ✓ | Function respondible for rendering children. This function should implement the following signature: `({ height: number, width: number }) => PropTypes.element` |
+| disableHeight | Boolean |  | Fixed `height`; if specified, the child's `height` property will not be managed |
+| disableWidth | Boolean |  | Fixed `width`; if specified, the child's `width` property will not be managed |
+| onResize | Function |  | Callback to be invoked on-resize; it is passed the following named parameters: `({ height: number, width: number })`. | 
 
 ### Examples
 
@@ -36,7 +36,7 @@ ReactDOM.render(
       <VirtualScroll
         width={width}
         height={height}
-        rowsCount={list.length}
+        rowCount={list.length}
         rowHeight={20}
         rowRenderer={
           index => list[index] // Could also be a DOM element

docs/CellMeasurer.md

@@ -0,0 +1,65 @@
+CellMeasurer
+---------------
+
+High-order component for automatically measuring a cell's contents by rendering it in a way that is not visible to the user.
+Specify a fixed width or height constraint if you only want to measure one dimension.
+
+**Warning**: This HOC is fairly experimental and may change in future releases.
+At this time it is only intended for use with a `Grid` (not `VirtualScroll` or `FlexTable` as their item rendering and cell measuring signatures are different).
+Also note that in order to measure a column's width for a `Grid`, that column's content must be rendered for all rows in order to determine the maximum width.
+For this reason it may not be a good idea to use this HOC for `Grid`s containing a large number of both columns _and_ cells.
+
+### Prop Types
+| Property | Type | Required? | Description |
+|:---|:---|:---:|:---|
+| cellRenderer | Function | ✓ | Renders a cell given its indices. `({ columnIndex: number, rowIndex: number }): PropTypes.node` |
+| children | Function | ✓ | Function respondible for rendering a virtualized component; `({ getColumnWidth: Function, getRowHeight: Function, resetMeasurements: Function }) => PropTypes.element` |
+| columnCount | number | ✓ | Number of columns in the `Grid`; in order to measure a row's height, all of that row's columns must be rendered. |
+| container |  |  | A Node, Component instance, or function that returns either. If this property is not specified the document body will be used. |
+| height | number |  | Fixed height; specify this property to measure cell-width only. |
+| rowCount | number | ✓ | Number of rows in the `Grid`; in order to measure a column's width, all of that column's rows must be rendered. |
+| width | number |  | Fixed width; specify this property to measure cell-height only. |
+
+### Children function
+
+The child function is passed the following named parameters:
+
+| Parameter | Type | Description |
+|:---|:---|:---|
+| getColumnWidth | Function | Callback to set as the `columnWidth` property of a `Grid` |
+| getRowHeight | Function | Callback to set as the `rowHeight` property of a `Grid` |
+| resetMeasurements | Function | Use this function to clear cached measurements in `CellRenderer`; its size will be remeasured the next time it is requested. |
+
+### Examples
+
+This example shows a `Grid` with fixed column widths and dynamic row heights.
+For more examples check out the component [demo page](https://bvaughn.github.io/react-virtualized/?component=CellMeasurer).
+
+```javascript
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { CellMeasurer, Grid } from 'react-virtualized';
+import 'react-virtualized/styles.css'; // only needs to be imported once
+
+ReactDOM.render(
+  <CellMeasurer
+    cellRenderer={cellRenderer}
+    columnCount={columnCount}
+    height={height}
+    rowCount={rowCount}
+  >
+    {({ getColumnWidth }) => (
+      <Grid
+        columnCount={columnCount}
+        columnWidth={getColumnWidth}
+        height={height}
+        cellRenderer={cellRenderer}
+        rowCount={rowCount}
+        rowHeight={fixedRowHeight}
+        width={width}
+      />
+    )}
+  </CellMeasurer>,
+  document.getElementById('example')
+);
+```

docs/Collection.md

@@ -4,22 +4,25 @@ Collection
 Renders scattered or non-linear data.
 Unlike `Grid`, which renders checkerboard data, `Collection` can render arbitrarily positioned- even overlapping- data.
 
+**Note** that this component's measuring and layout phase is more expensive than `Grid` since it can not assume a correlation between a cell's index and position. For this reason it will take signifnicantly longer to initialize than the more linear/checkerboard components.
+
 ### Prop Types
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
 | className | String |  | Optional custom CSS class name to attach to root Collection element. |
 | cellCount | Number | ✓ | Number of cells in collection. |
+| cellGroupRenderer | Function | ✓ | Responsible for rendering a group of cells given their indices.: `({ cellSizeAndPositionGetter:Function, indices: Array<number>, cellRenderer: Function }): Array<PropTypes.node>` |
+| cellRenderer | Function | ✓ | Responsible for rendering a cell given an row and column index: `({ index: number, isScrolling: boolean }): PropTypes.element` |
+| cellSizeAndPositionGetter | Function | ✓ | Callback responsible for returning size and offset/position information for a given cell (index): `({ index: number }): { height: number, width: number, x: number, y: number }` |
 | height | Number | ✓ | Height of Collection; this property determines the number of visible (vs virtualized) rows. |
 | noContentRenderer | Function |  | Optional renderer to be rendered inside the grid when `cellCount` is 0: `(): PropTypes.node` |
-| onSectionRendered | Function |  | Callback invoked with information about the section of the Collection that was just rendered: `(indices: Array<number>): void` |
-| onScroll | Function |  | Callback invoked whenever the scroll offset changes within the inner scrollable region: `({ clientHeight, clientWidth, scrollHeight, scrollLeft, scrollTop, scrollWidth }): void` |
-| cellRenderer | Function | ✓ | Responsible for rendering a cell given an row and column index: `(index: number): PropTypes.node` |
-| cellGroupRenderer | Function | ✓ | Responsible for rendering a group of cells given their indices.: `({ cellSizeAndPositionGetter:Function, indices: Array<number>, cellRenderer: Function }): Array<PropTypes.node>` |
-| cellSizeAndPositionGetter | Function | ✓ | Callback responsible for returning size and offset/position information for a given cell (index): `(index): { height: number, width: number, x: number, y: number }` |
+| onSectionRendered | Function |  | Callback invoked with information about the section of the Collection that was just rendered: `({ indices: Array<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` |
 | scrollLeft | Number |  | Horizontal offset |
 | scrollToCell | Number |  | Cell index to ensure visible (by scrolling if necessary) |
 | scrollTop | Number |  | Vertical offset |
-| sectionSize | Number |  | Optionally override the size of the sections a Collection's cells are split into. |
+| sectionSize | Number |  | Optionally override the size of the sections a Collection's cells are split into. This is an advanced option and should only be used for performance tuning purposes. |
+| style | Object |  | Optional custom inline style to attach to root Collection element. |
 | width | Number | ✓ | Width of Collection; this property determines the number of visible (vs virtualized) columns. |
 
 ### Public Methods
@@ -29,7 +32,7 @@ Unlike `Grid`, which renders checkerboard data, `Collection` can render arbitrar
 Recomputes cell sizes and positions.
 
 This function should be called if cell sizes or positions have changed but nothing else has.
-Since Collection only receives `cellCount` it has no way of detecting when the underlying data changes.
+Since Collection only receives `cellCount` (and not the underlying List or Array) it has no way of detecting when the underlying data changes.
 
 ### Class names
 
@@ -62,9 +65,16 @@ const list = [
 ReactDOM.render(
   <Collection
     cellCount={list.length}
-    cellRenderer={(index) => list[index].name}
-    cellSizeAndPositionGetter={(index) => list[index]}
-    columnsCount={list.length}
+    cellRenderer={({ index }) => list[index].name}
+    cellSizeAndPositionGetter={({ index }) => {
+      const datum = list[index]
+      return {
+        height: datum.height,
+        width: datum.width,
+        x: datum.x,
+        y: datum.y
+      }
+    }}
     height={300}
     width={300}
   />,

docs/ColumnSizer.md

@@ -6,7 +6,7 @@ High-order component that auto-calculates column-widths for `Grid` cells.
 ### Prop Types
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
-| children | Function | ✓ | Function respondible for rendering a virtualized Grid. This function should implement the following signature: `({ adjustedWidth, getColumnWidth, registerChild }) => PropTypes.element` |
+| children | Function | ✓ | Function respondible for rendering a virtualized Grid. This function should implement the following signature: `({ adjustedWidth: number, getColumnWidth: Function, registerChild: Function }) => PropTypes.element` |
 | columnMaxWidth | Number |  | Optional maximum allowed column width |
 | columnMinWidth | Number |  | Optional minimum allowed column width |
 | width | Number | ✓ | Width of Grid or `FlexTable` child |
@@ -16,14 +16,14 @@ High-order component that auto-calculates column-widths for `Grid` cells.
 The child function is passed the following named parameters:
 
 | Parameter | Type | Description |
-|:---|:---|:---:|
+|:---|:---|:---|
+| adjustedWidth | Number | This number reflects the lesser of the overall `Grid` width or the width of all columns. Use this to make your `Grid` shrink to fit sparse content. |
 | getColumnWidth | Function | This function should be passed to the `Grid`'s `columnWidth` property. |
 | registerChild | Function | This function should be set as the child's `ref` property. It enables a set of rows to be refreshed once their data has finished loading. |
-| adjustedWidth | Number | This number reflects the lesser of the overall `Grid` width or the width of all columns. Use this to make your `Grid` shrink to fit sparse content. |
 
 ### Examples
 
-This example displays a `Grid` that shrinks to fit sparse content (using the `adjustedWidth` parameter).
+This example displays a `Grid` that shrinks to fit sparse content (using the `adjustedWidth` parameter). An interactive demo of this component can be seen [here](https://bvaughn.github.io/react-virtualized/?component=ColumnSizer).
 
 ```javascript
 import React from 'react';
@@ -38,18 +38,18 @@ ReactDOM.render(
   <ColumnSizer
     columnMaxWidth={100}
     columnMinWidth={50}
-    columnsCount={numColumns}
+    columnCount={numColumns}
     width={someCalculatedWidth}
   >
     {({ adjustedWidth, getColumnWidth, registerChild }) => (
       <Grid
         ref={registerChild}
         columnWidth={getColumnWidth}
-        columnsCount={numColumns}
+        columnCount={numColumns}
         height={someCalculatedHeight}
-        renderCell={someCellRenderer}
+        cellRenderer={someCellRenderer}
         rowHeight={50}
-        rowsCount={numRows}
+        rowCount={numRows}
         width={adjustedWidth}
       />
     )}