Merge pull request #35 from jrowny/2.0-pure

2.0 pure components

Author: jrowny

README.md

@@ -7,24 +7,38 @@ Usage:
 
 Install with `npm install react-absolute-grid`
 
-    import React from 'react';
-    import AbsoluteGrid from './lib/AbsoluteGrid.jsx';
+```javascript
+import React from 'react';
+import createAbosluteGrid from './lib/AbsoluteGrid.jsx';
 
-     var sampleItems = [
-      {key: 1, name: 'Test', sort: 0, filtered: 0},
-      {key: 2, name: 'Test 1', sort: 1, filtered: 0},
-    ];
+// This is the component that will display your data
+import YourDisplayComponent from 'your-display-component';
 
-    React.render(<AbsoluteGrid items={sampleItems} />, document.getElementById('Container'));
+ var sampleItems = [
+  {key: 1, name: 'Test', sort: 0, filtered: 0},
+  {key: 2, name: 'Test 1', sort: 1, filtered: 0},
+];
 
+// Pass your display component to create a new grid
+const AbsoluteGrid = createAbsoluteGrid(YourDisplayComponent, {someProp: 'my component needs this'});
+React.render(<AbsoluteGrid items={sampleItems} />, document.getElementById('Container'));
+```
 
-Options (Properties)
+CreateAbsoluteGrid
 ------
+```javascript
+createAbsoluteGrid(DisplayComponent, displayProps = {}, forceImpure = false)
+```
+ 
+ * `DisplayComponent`: is a react component to display in your grid
+ * `displayProps`: *optional* : are properties you want passed down to the DisplayComponent such as event handlers. 
+ * `forceImpure`: *optional* : **not recommended** Will make this function as an impure component, meaning it always renders. 
 
+Options (Properties)
+------
 | Property | Default | Description |
 |---|:---:|---|
 | **items** | [] | The array of items in the grid |
-| **displayObject** | (required) | The React component to render items |
 | **keyProp** | 'key' | The property to be used as a key  |
 | **filterProp** | 'filtered' | The property to be used for filtering, if the filtered value is true, the item won't be displayed. It's important to not remove items from the array because that will cause React to remove the DOM, for performance we would rather hide it then remove it. |
 | **sortProp** | 'sort' | The property to sort on |
@@ -36,47 +50,51 @@ Options (Properties)
 | **animation** | 'transform 300ms ease' | The CSS animation to use on elements. Pass a blank string or `false` for no animation. |
 | **zoom** | 1 | Zooms the contents of the grid, 1 = 100% |
 | **onMove** | `fn(from, to)` | This function is called when an item is dragged over another item. It is your responsibility to update the sort of all items when this happens. |
+| **onDragStart** | `fn(e)` | This function is called when an item starts dragging, this is NOT required. |
+| **onDragMove** | `fn(e)` | This function is called when as an item is being moved, this is NOT required. |
+| **onDragEnd** | `fn(e)` | This function is called when an item has finished its drag, this is NOT required. |
 
-Creating a DisplayObject component
+Your Component
 ------
-displayObject component will receive `item`, `index` and `itemsLength` as props. Here's the simplest possible example:
-
-    import React from 'react';
-    
-    export default class SampleDisplay extends React.Component {
-
-      render() {
-        // Supposing your item shape is something like {name: 'foo'}
-        const { item, index, itemsLength } = this.props;
-        return <div>Item {index} of {itemsLength}: {item.name}</div>;
-      }
-    }
+Your component will receive `item`, `index` and `itemsLength` as props, as well as anything you pass into the createAbsoluteGrid function. Here's the simplest possible example:
 
-Once you've created a display object, use it like this:
+```javascript
+import React from 'react';
 
-     var grid = (<AbsoluteGrid ... displayObject={(<SampleDisplay {...pass props normally} />)}/>);
+export default function SampleDisplay(props) {
+    // Supposing your item shape is something like {name: 'foo'}
+    const { item, index, itemsLength } = props;
+    return <div>Item {index} of {itemsLength}: {item.name}</div>;
+}
+```
 
 What Makes AbsoluteGrid Unique?
 ----
-The idea behind AbsoluteGrid is high performance. This is achieved by using Translate3d to position each item in the layout. Items are never removed from the DOM, instead they are hidden. For best performance you should avoid re-arranging or removing items which you pass into AbsoluteGrid, instead you can use the `filtered` and `sort` properties to hide or sort an item. Those properties are customizable using the `keyProp` and `filterProp` properties.
+The idea behind AbsoluteGrid is high performance. This is achieved by using Translate3d to position each item in the layout. Items are never removed from the DOM, instead they are hidden. For best performance you should avoid re-arranging or removing items which you pass into AbsoluteGrid, instead you can use the `filtered` and `sort` properties to hide or sort an item. Those properties are customizable using the `keyProp` and `filterProp` properties. In addition, all data passed must be immutable so that we don't waste any renders.
 
-DisplayObject props
+Your Display Component props
 ----
-Each DisplayObject component is passed the following props.
+Each Component is passed the following props, as well as anything passed into the second parameter of `createAbsoluteGrid`
 
 | Property | Description |
 |---|:---|
 | **item** | The data associated with the GridItem |
 | **index** | The index of the item data in the `items` array |
 | **itemsLength** | The total length of the `items` array |
-
+| **...displayProps** | props passed into `createAbsoluteGrid` |
 
 ToDo:
 -----
+ * Tests
  * Improve Drag & Drop browser support and reliability
 
 Browser Compatibility
 -----
 This component should work in all browsers that [support CSS3 3D Transforms](http://caniuse.com/#feat=transforms3d). If you need IE9 support you can modify it to use transform rather than transform3d. Pull requests welcome!
 
 Drag and Drop only works on IE11+ due to lack of pointer events, although there is a workaround coming soon.
+
+Migrating from 2.x
+-----
+
+Instead of passing `displayObject` to the AbsoluteGrid component, pass the component directly into the composer function, `createAbsoluteGrid` which returns an AbsoluteGrid component. That's it!

demo.js

@@ -2,7 +2,8 @@
 
 import React from 'react';
 import ReactDOM from 'react-dom';
-import AbsoluteGrid from './index.js';
+import Perf from 'react-addons-perf';
+import createAbsoluteGrid from './index.js';
 import SampleDisplay from './demo/SampleDisplay.jsx';
 import * as data from './demo/sampleData.js';
 import * as _ from 'lodash';
@@ -20,16 +21,22 @@ demo();
 
 function demo() {
 
-  var sampleItems = data.screens;
-  var displayObject = (<SampleDisplay/>);
-  var render;
-  var zoom = 0.7;
+  let sampleItems = data.screens;
+  let render;
+  let zoom = 0.7;
 
   //We set a property on each item to let the grid know not to show it
   var onFilter = function(event){
     var search = new RegExp(event.target.value, 'i');
-    sampleItems.forEach(function(item){
-      item.filtered = !item.name.match(search);
+    sampleItems = sampleItems.map(function(item){
+      const isMatched = !item.name.match(search);
+      if(!item.filtered || isMatched !== item.filtered) {
+        return {
+          ...item,
+          filtered: isMatched
+        }
+      }
+      return item;
     });
     render();
   };
@@ -39,24 +46,37 @@ function demo() {
     source = _.find(sampleItems, {key: parseInt(source, 10)});
     target = _.find(sampleItems, {key: parseInt(target, 10)});
 
-    var targetSort = target.sort;
+    const targetSort = target.sort;
 
     //CAREFUL, For maximum performance we must maintain the array's order, but change sort
-    sampleItems.forEach(function(item){
+    sampleItems = sampleItems.map(function(item){
       //Decrement sorts between positions when target is greater
-      if(target.sort > source.sort && (item.sort <= target.sort && item.sort > source.sort)){
-        item.sort --;
-      //Incremenet sorts between positions when source is greator
-      }else if(item.sort >= target.sort && item.sort < source.sort){
-        item.sort ++;
+      if(item.key === source.key) {
+        return {
+          ...item,
+          sort: targetSort
+        }
+      } else if(target.sort > source.sort && (item.sort <= target.sort && item.sort > source.sort)){
+        return {
+          ...item,
+          sort: item.sort - 1
+        };
+      //Increment sorts between positions when source is greater
+      } else if (item.sort >= target.sort && item.sort < source.sort){
+        return {
+          ...item,
+          sort: item.sort + 1
+        };
       }
+      return item;
     });
-
-    source.sort = targetSort;
+    Perf.start();
     render();
+    Perf.stop();
+    Perf.printWasted();
   };
 
-  var onMoveDebounced = _.debounce(onMove, 80);
+  var onMoveDebounced = _.debounce(onMove, 40);
 
   var unMountTest = function(){
     if(ReactDOM.unmountComponentAtNode(document.getElementById('Demo'))){
@@ -67,9 +87,9 @@ function demo() {
     }
   };
 
+  const AbsoluteGrid = createAbsoluteGrid(SampleDisplay);
   render = function(){
     ReactDOM.render(<AbsoluteGrid items={sampleItems}
-                               displayObject={displayObject}
                                onMove={onMoveDebounced}
                                dragEnabled={true}
                                zoom={zoom}