Rename childRef to registerChild and add some docs (bvaughn#947)

Rename childRef to registerChild and add some docs

Author: TrySound

docs/WindowScroller.md

@@ -1,16 +1,16 @@
 WindowScroller
 ---------------
 
-High-order component that enables a `Table` or `List` component to be scrolled based on the window's scroll positions.
+A component that enables a `Table` or `List` component to be scrolled based on the window's scroll positions.
 This can be used to create layouts similar to Facebook or Twitter news feeds.
 
-**Note** that this HOC does not currently work with a horizontally-scrolling `Grid` as horizontal scrolls reset the internal `scrollTop`.
-This may change with a future release but for the time being this HOC is should be used with `Table` or `List` only.
+**Note** that this component does not currently work with a horizontally-scrolling `Grid` as horizontal scrolls reset the internal `scrollTop`.
+This may change with a future release but for the time being this component is should be used with `Table` or `List` only.
 
 ### Prop Types
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
-| children | Function | ✓ | Function responsible for rendering children. This function should implement the following signature: `({ height: number, width: number, isScrolling: boolean, scrollTop: number, onChildScroll: function }) => PropTypes.element` |
+| children | Function | ✓ | Function responsible for rendering children. This function should implement the following signature: `({ height: number, width: number, isScrolling: boolean, scrollTop: number, registerChild: function, onChildScroll: function }) => PropTypes.element` |
 | onResize | Function |  | Callback to be invoked on-resize; it is passed the following named parameters: `({ height: number, width: number })`. |
 | onScroll | Function |  | Callback to be invoked on-scroll; it is passed the following named parameters: `({ scrollTop: number, scrollLeft: number })`. |
 | scrollElement | any |  | Element to attach scroll event listeners. Defaults to `window`. |
@@ -53,3 +53,37 @@ ReactDOM.render(
   document.getElementById('example')
 );
 ```
+
+or using `registerChild` you can specify grid container deeper in layout (by default `WindowScroller` uses `ReactDOM.findDOMNode` function)
+
+```javascript
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { List, WindowScroller } from 'react-virtualized';
+import 'react-virtualized/styles.css'; // only needs to be imported once
+
+ReactDOM.render(
+  <WindowScroller>
+    {({ height, isScrolling, registerChild, scrollTop }) => (
+      <div>
+        <header>
+          Table header
+        </header>
+        <div ref={registerChild}>
+          <List
+            autoHeight
+            height={height}
+            isScrolling={isScrolling}
+            rowCount={...}
+            rowHeight={...}
+            rowRenderer={...}
+            scrollTop={scrollTop}
+            width={...}
+          />
+        </div>
+      </div>
+    )}
+  </WindowScroller>,
+  document.getElementById('example')
+);
+```

source/WindowScroller/WindowScroller.example.js

@@ -86,11 +86,11 @@ export default class WindowScrollerExample extends PureComponent<{}, State> {
         <WindowScroller
           ref={this._setRef}
           scrollElement={isScrollingCustomElement ? customElement : window}>
-          {({height, isScrolling, childRef, onChildScroll, scrollTop}) => (
+          {({height, isScrolling, registerChild, onChildScroll, scrollTop}) => (
             <div className={styles.WindowScrollerWrapper}>
               <AutoSizer disableHeight>
                 {({width}) => (
-                  <div ref={childRef}>
+                  <div ref={registerChild}>
                     <List
                       ref={el => {
                         window.listEl = el;

source/WindowScroller/WindowScroller.jest.js

@@ -82,7 +82,7 @@ describe('WindowScroller', () => {
     expect(component._positionFromLeft).toEqual(left);
   });
 
-  it('should allow passing child element with childRef of children function param', () => {
+  it('should allow passing child element with registerChild of children function param', () => {
     const scrollElement = document.createElement('div');
     scrollElement.scrollTop = 100;
     scrollElement.scrollLeft = 150;
@@ -97,7 +97,7 @@ describe('WindowScroller', () => {
     });
     const renderFn = jest.fn();
     const component = render(getMarkup({scrollElement, renderFn}));
-    renderFn.mock.calls[0][0].childRef(child);
+    renderFn.mock.calls[0][0].registerChild(child);
     expect(component._positionFromTop).toEqual(300 + 100 - 200);
     expect(component._positionFromLeft).toEqual(350 + 150 - 250);
   });

source/WindowScroller/WindowScroller.js

@@ -20,9 +20,9 @@ type Props = {
    * This function should implement the following signature:
    * ({ height, isScrolling, scrollLeft, scrollTop, width }) => PropTypes.element
    */
-  children: (params: {
+  children: ({
     onChildScroll: ({scrollTop: number}) => void,
-    childRef: (?Element) => void,
+    registerChild: (?Element) => void,
     height: number,
     isScrolling: boolean,
     scrollLeft: number,
@@ -31,10 +31,10 @@ type Props = {
   }) => React.Node,
 
   /** Callback to be invoked on-resize: ({ height, width }) */
-  onResize: (params: {height: number, width: number}) => void,
+  onResize: ({height: number, width: number}) => void,
 
   /** Callback to be invoked on-scroll: ({ scrollLeft, scrollTop }) */
-  onScroll: (params: {scrollLeft: number, scrollTop: number}) => void,
+  onScroll: ({scrollLeft: number, scrollTop: number}) => void,
 
   /** Element to attach scroll event listeners. Defaults to window. */
   scrollElement: ?Element,
@@ -173,7 +173,7 @@ export default class WindowScroller extends React.PureComponent<Props, State> {
 
     return children({
       onChildScroll: this._onChildScroll,
-      childRef: this._childRef,
+      registerChild: this._registerChild,
       height,
       isScrolling,
       scrollLeft,
@@ -182,7 +182,7 @@ export default class WindowScroller extends React.PureComponent<Props, State> {
     });
   }
 
-  _childRef = element => {
+  _registerChild = element => {
     this._child = element;
     this.updatePosition();
   };