Merge branch 'bc-1.0.0' of http://github.com/wbuchwalter/ng-redux into bc-1.0.0

Author: wbuchwalter

README.md

@@ -8,48 +8,26 @@ For Angular 2 see [ng2-redux](https://github.com/wbuchwalter/ng2-redux).
 [![build status](https://img.shields.io/travis/wbuchwalter/ng-redux/master.svg?style=flat-square)](https://travis-ci.org/wbuchwalter/ng-redux)
 [![npm version](https://img.shields.io/npm/v/ng-redux.svg?style=flat-square)](https://www.npmjs.com/package/ng-redux)
 
-## Installation
-```js
-npm install --save ng-redux
-```
-
-## Overview
 
-ngRedux lets you easily connect your angular components with Redux.
-the API is straightforward: 
-
-```JS
-$ngRedux.connect(selector, callback);
-```
-
-Where `selector` is a function that takes Redux's entire store state as argument and returns an object that contains the slices of store state that your component is interested in.
-e.g:
-```JS
-state => ({todos: state.todos})
-```
-Note: if you are not familiar with this syntax, go and check out the [MDN Guide on fat arrow  functions (ES2015)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions)
+*ngRedux lets you easily connect your angular components with Redux.*
 
-If you haven't, check out [reselect](https://github.com/faassen/reselect), an awesome tool to create and combine selectors.
 
+## Table of Contents
 
-This returned object will be passed as argument to the callback provided whenever the state changes.
-ngRedux checks for shallow equality of the state's selected slice whenever the Store is updated, and will call the callback only if there is a change.
-**Important: It is assumed that you never mutate your states, if you do mutate them, ng-redux will not execute the callback properly.**
-See [Redux's doc](http://gaearon.github.io/redux/docs/basics/Reducers.html) to understand why you should not mutate your states.
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API](#api)
+- [Using DevTools](#using-devtools)
 
+## Installation
+```js
+npm install --save ng-redux
+```
 
-## Getting Started
+## Quick Start
 
 #### Initialization
 
-```JS
-$ngReduxProvider.createStoreWith(reducer, [middlewares], storeEnhancer);
-```
-#### Parameters: 
-* reducer (Function): A single reducer composed of all other reducers (create with redux.combineReducer)
-* [middleware] (Array of Function or String): An array containing all the middleware that should be applied. Functions and strings are both valid members. String will be resolved via Angular, allowing you to use dependency injection in your middlewares.
-* storeEnhancer: Optional function that will be used to create the store, in most cases you don't need that, see [Store Enhancer official doc](http://rackt.github.io/redux/docs/Glossary.html#store-enhancer)
-
 ```JS
 import reducers from './reducers';
 import {combineReducers} from 'redux';
@@ -69,70 +47,96 @@ angular.module('app', ['ngRedux'])
   return {
     controllerAs: 'vm',
     controller: TodoLoaderController,
-    template: "<div ng-repeat='todo in vm.todos'>{{todo.text}}</div>",
-
-    [...]
+    template: "<div ng-repeat='todo in vm.todos'>{{todo.text}}</div>"
   };
 }
 
 class TodoLoaderController {
-
   constructor($ngRedux) {
-    this.todos = [];
-    $ngRedux.connect(state => ({todos: state.todos}), ({todos}) => this.todos = todos);
+    $ngRedux.connect(state => ({todos: state.todos}), this);
   }
-
-  [...]
 }
 ```
 
-**Note: The callback provided to `connect` will be called once directly after creation to allow initialization of your component states**
+## API
 
+### `createStoreWith([reducer], [middlewares], [storeEnhancers])`
 
+Creates the Redux store, and allow `connect()` to access it.
 
-You can also grab multiple slices of the state by passing an array of selectors:
+#### Arguments: 
+* [`reducer`] \(*Function*): A single reducer composed of all other reducers (create with redux.combineReducer)
+* [`middlewares`] \(*Function[]*): Optional, An array containing all the middleware that should be applied. Functions and strings are both valid members. String will be resolved via Angular, allowing you to use dependency injection in your middlewares.
+* [`storeEnhancers`] \(*Function[]*): Optional, this will be used to create the store, in most cases you don't need to pass anything, see [Store Enhancer official documentation.](http://rackt.github.io/redux/docs/Glossary.html#store-enhancer)
 
-```JS
-constructor($ngRedux) {
-    this.todos = [];
-    this.users = [];
-    $ngRedux.connect(state => ({
-        todos: state.todos,
-        users: state.users
-    }),
-    ({todos, users}) => { 
-        this.todos = todos
-        this.users = users;
-    });
-  }
-```
 
+### `connect([mapStateToTarget], [target])`
 
-#### Unsubscribing
+Connects an Angular component to Redux.
 
-You can close a connection like this:
+#### Arguments
+* [`mapStateToTarget`] \(*Function*): connect will subscribe to Redux store updates. Any time it updates, mapStateToTarget will be called. Its result must be a plain object, and it will be merged into `target`.
+* [`target`] \(*Object*): A plain object, this will be use as a target by `mapStateToTarget`. Read the Remarks below about the implication of passing `$scope` to `connect`.
 
-```JS
+#### Returns
+(*Function*): A function that unsubscribes the change listener.
 
-constructor($ngRedux) {
-    this.todos = [];
-    this.unsubscribe = $ngRedux.connect(state => ({todos: state.todos}), ({todos}) => this.todos = todos);
-  }
+#### Remarks
+If `$scope` is passed to `connect` as `target`, ngRedux will listen to the `$destroy` event and unsubscribe the change listener when it is triggered, you don't need to keep track of your subscribtions in this case.
+If anything else than `$scope` is passed as target, the responsability to unsubscribe correctly is deferred to the user.
 
-destroy() {
-    this.unsubscribe();
-}
+### Store API
+All of redux's store methods (i.e. `dispatch`, `subscribe` and `getState`) are exposed by $ngRedux and can be accessed directly. For example:
 
+```JS
+redux.bindActionCreators(actionCreator, $ngRedux.dispatch);
 ```
 
 
-#### Accessing Redux's store methods
-All of redux's store methods (i.e. `dispatch`, `subscribe` and `getState`) are exposed by $ngRedux and can be accessed directly. For example:
+## Using DevTools
+In order to use Redux DevTools with your angular app, you need to install [react](https://www.npmjs.com/package/react), [react-redux](https://www.npmjs.com/package/react-redux) and [redux-devtools](https://www.npmjs.com/package/redux-devtools) as development dependencies.
 
 ```JS
-redux.bindActionCreators(actionCreator, $ngRedux.dispatch);
+[...]
+import { devTools, persistState } from 'redux-devtools';
+import { DevTools, DebugPanel, LogMonitor } from 'redux-devtools/lib/react';
+import React, { Component } from 'react';
+
+angular.module('app', ['ngRedux'])
+  .config(($ngReduxProvider) => {
+      $ngReduxProvider.createStoreWith(rootReducer, [thunk], [devTools()]);
+    })
+  .run(($ngRedux, $rootScope) => {
+    React.render(
+      <App store={ $ngRedux }/>,
+      document.getElementById('devTools')
+    );
+    
+    //To reflect state changes when disabling/enabling actions via the monitor
+    //there is probably a smarter way to achieve that
+    $ngRedux.subscribe(_ => {
+        setTimeout($rootScope.$apply, 100);
+    });
+  });
+  
+  class App extends Component {
+  render() {
+    return (
+      <div>
+        <DebugPanel top right bottom>
+          <DevTools store={ this.props.store } monitor = { LogMonitor } />
+        </DebugPanel>
+      </div>
+    );
+  }
+}
 ```
-**Note:** If you choose to use `subscribe` directly, be sure to [unsubscribe](#unsubscribing) when your current scope is $destroyed.
 
-### Example:
-An example can be found here (in TypeScript): [tsRedux](https://github.com/wbuchwalter/tsRedux/blob/master/src/components/regionLister.ts).
+```HTML
+<body>
+    <div ng-app='app'>
+      [...]
+    </div>
+    <div id="devTools"></div>
+</body>
+```