- Doc updates

- Removed root-level require() capabilities

Author: wcjohnson

.npmignore

@@ -9,4 +9,3 @@ build/
 book.json
 coffeelint.json
 .eslintrc
-.babelrc

CHANGELOG.md

@@ -0,0 +1,58 @@
+## 0.2
+
+### **BREAKING CHANGE:** require() targeting package root no longer supported.
+
+In 0.1.x, under CommonJS, you could `require()` specific submodules with e.g. `require('redux-components/createClass')`. This cherry-picking is no longer supported.
+
+Redux-components is moving to the ES Modules + Babel model, so individual submodules are exported from the `index` module.
+
+The correct way to pick out modules going forward is `{ createClass } = require('redux-components')`.
+
+### ES2015 Module build
+
+0.2.x now exports appropriate `jsnext:main` and `module` entries from `package.json` allowing use as an ES2015 module. CommonJS is still supported subject to the caveats above.
+
+### Git Submodule support
+
+Some people on my team were upset about how I broke Git submodule support in 0.1, so I fixed it for 0.2. You can now check out redux-components directly from Git as a submodule beneath some `node_modules` folder in your project. After an initial `npm install` to set up the git hooks, everything should work automatically, including a `post-merge` hook to rebuild the `lib` and `es` artifacts whenever you merge from upstream.
+
+### Action Dispatchers
+
+A new component specification entry, `spec.actionDispatchers`, has been added:
+```coffeescript
+spec.actionDispatchers = { key: (args...) => action, ... }
+```
+
+Action dispatchers are like action creators, except that they are automatically wrapped with `dispatch()` for the appropriate Redux Store when the component is mounted. Calling an action dispatcher will save you the extra step of calling `dispatch` yourself.
+
+>**NB:** Your action dispatchers must return actions, just as action creators do.
+
+### Reducer Indirection and Dynamic Reducers
+
+- The `reducer` property of each `ReduxComponent` instance is now a lightweight thunk reducer that indirectly calls the last return value from `getReducer`.
+
+- `spec.getReducer` has a new signature:
+```coffeescript
+spec.getReducer = (state?) => (state, action) => nextState
+```
+
+- If you register a class with a `getReducer` function taking zero arguments, the internal behavior of the `ReduxComponent` is the same as it was in 0.1.x.
+
+- If you create a class with a `getReducer` function taking one or more arguments, the internal behavior of the `ReduxComponent` changes:
+	- `getReducer` will be passed the current state of the component as its first argument.
+	- The thunk reducer will call whatever you return from `getReducer`, allowing you to update your reducer dynamically.
+	- Your `ReduxComponent` instance will have an `updateReducer()` method that will cause `getReducer` to be invoked. `updateReducer` is impure. **DO NOT** call `updateReducer` from inside of a reducer.
+
+> **NB:** Dynamic reducers are an advanced and dangerous feature. You should only use them if you are completely certain that you need them. Don't forget the Redux contract!
+- Reducers should be pure functions of state and action. Dynamic reducer behavior should only be used when you are sure you can honor this contract.
+- In particular, you should think of "the state of your dynamic reducer" as being a part of your app's overall state.
+- That means the behavior of a dynamic reducer should be a pure function of some branch of your state tree.
+- If you make dynamic reducer behavior depend on stateful information that isn't stored in Redux, you are virtually guaranteed to break core Redux features like time travel and rehydration.
+
+### Observable Selectors
+
+A new mixin, `ObservableSelectorMixin`, has been provided. When mixed into a component, all `selectors` declared on the component will be instantiated as [ES7 Observables](https://github.com/tc39/proposal-observable) when the component is mounted.
+
+If `componentInstance` is an instance of a component that uses `ObservableSelectorMixin`, and `selector` is one of its selectors, then `componentInstance.selector.subscribe(observer)` will invoke `observer.next(value)` whenever the value returned by the selector changes.
+
+> The observable implementation assumes your store's state obeys the Redux contract, so `===` equality is used to compare selector values.

ReduxComponent.js

@@ -0,0 +1,98 @@
+# Component Specification
+
+A component specification is a plain JavaScript object that declaratively specifies the behavior of a component class. This object is passed to `createClass`, which in turn builds a `ReduxComponent` matching the spec.
+
+Generally speaking, any function assigned to a key on the specification object will be copied into the prototype of the class and thus become available as instance methods. The exception to this rule is for certain specially-named keys which are used by redux-components to implement core component behavior. The special keys are as follows:
+
+## Meta properties
+
+### spec.displayName
+```coffeescript
+spec.displayName = string
+```
+If specified, gives a name to this component that can be used by debugging and development tools.
+
+> Just as with React, relying on displayName to do type checking in production is an antipattern. Use the instanceof operator.
+
+### spec.statics
+```coffeescript
+spec.statics = { ... }
+```
+All keys and values from ```spec.statics``` are merged onto the constructor for the component class via ```Object.assign```. This makes them available as "static methods" on the class constructor.
+
+### spec.mixins
+```coffeescript
+spec.mixins = [ {spec}, {spec}, ... ]
+```
+An array of additional specs that will be mixed into this spec before creating the class. Mixins are processed in the order they appear in the array. In general, the keys on the mixin specs will be assigned to the base spec as with ```Object.assign```, with auto-binding for functions. There is special behavior for certain keys. See [Mixins](Mixins.md) for more.
+
+## Lifecycle methods
+
+### spec.componentWillMount
+```coffeescript
+spec.componentWillMount = =>
+```
+### spec.componentDidMount
+```coffeescript
+spec.componentDidMount = =>
+```
+### spec.componentWillUnmount
+```coffeescript
+spec.componentWillUnmount = =>
+```
+Specifies the lifecycle methods for instances of the class. See [Components](Components.md) for details on when the methods are called.
+
+## Redux-related properties
+
+### spec.getReducer
+```coffeescript
+spec.getReducer = => (state, action) => nextState
+```
+getReducer returns a reducer function that will be used for the state subtree managed by this component.
+
+Reducers made by getReducer are automatically bound to their component instances so that they can have access to scoped properties, particularly scoped action verbs.
+
+> **NB:**
+> - After all mixins are evaluated, a final spec must have exactly one ```.getReducer```. We prefer to be unopinionated, so by default, there is no specified behavior for composing multiple reducers. (But see ```SubtreeMixin```.)
+
+> - Do not use magic binding as an excuse to introduce impure behavior into your reducer! If you want the all the benefits of Redux, keep your reducers as pure functions of props and state. Don't make your reducer rely on non-constant properties of the redux-component, and don't be tempted to  store any state on the redux-component itself. (You can sometimes use ```getReducer``` to mimic "impure" behaviors without making your reducer itself impure.)
+
+> - By default, redux-components will call `getReducer()` only once when your component is mounted to a state tree. If you expect your reducer to change during the Redux store's lifecycle, you must arrange for `getReducer()` to be called at appropriate times, and for `Store.replaceReducer()` to be called on your root store. If you use redux-components and `SubtreeMixin` throughout your state tree, we provide facilities for automating this.
+
+> - You may optionally declare a `getReducer` method that accepts a `stateNow` argument:
+```coffeescript
+spec.getReducer = (stateNow) => (state, action) => nextState
+```
+> If you do, your reducer is considered to be a [dynamic reducer](/docs/Advanced/DynamicReducer.md). The JavaScript `Function.length` property is used to make this determination. Dynamic reducers are an advanced feature and should not generally be used. Please read [the dynamic reducer documentation](/docs/Advanced/DynamicReducer.md) carefully before use.
+
+### spec.verbs
+```coffeescript
+spec.verbs = [ string, string, ... ]
+```
+Specifies a list of action names that will be scoped to each instance of the component using the instance's path in the state tree. Verbs are scoped according to the following pattern: ```#{path}:#{verb}``` and are available on the instance object at a key corresponding to the verb root. For example, a component instance mounted at ```foo.bar``` in the state tree having a verb ```"BAZ"``` would have the scoped verb ```"foo.bar:BAZ"``` available as ```this.BAZ```.
+
+> If you don't want a verb to be scoped, don't put it in the verbs array. Instead set it as a plain string property on the specification. It will then bypass the auto-scoping behavior.
+
+### spec.actionCreators
+```coffeescript
+spec.actionCreators = { key: (args...) -> action, ... }
+```
+Specify the action creators associated with this component class. Each property on the ```actionCreators``` object will be bound to each component instance and made available on the instance as a method.
+> **NB:** The redux-components core makes no assumptions about which middleware is present on a store. If you have e.g. `redux-thunk` middleware installed, you may of course return thunks from your actions and actionCreators.
+
+### spec.actionDispatchers
+```coffeescript
+spec.actionDispatchers = { key: (args...) -> action, ... }
+```
+Specify action dispatchers associated with this component class. Action dispatchers are like action creators, except the value returned is automatically `dispatch()`ed to the Store where this component is mounted. The wrapped action function will return the same thing as `dispatch()`, allowing it to be used with thunks and other related middleware.
+
+### spec.selectors
+```coffeescript
+spec.selectors = { key: (state, ...) -> any, ... }
+```
+Specify the selectors associated with this component class. Each property on the `selectors` object will be bound to each component instance and wrapped in a function that scopes the selector to the instance's state. The net effect will be that the state argument received by the selector will point to the state subtree managed by the particular component instance, rather than the global Redux state.
+> If you don't want a selector to be auto-scoped, don't put it in the selectors object. Instead set it as a property on the specification. This will bypass the auto-scoping behavior.
+
+## Other properties
+
+The specification's other properties will be `Object.assign()`ed onto the prototype for the class. Properties that are functions will be automatically bound to class instances by the constructor. Other properties will be available on the prototype.

SubtreeMixin.js

@@ -2,7 +2,7 @@
 
 ## Component Classes
 
-As in React, components are built up from the JavaScript object model. One creates a component class by passing a specification object to  [createClass](createClass.md). To instantiate an instance of the class, which can then be mounted to a Redux state tree, use [createComponent](createComponent.md), which is the analogue of React's `createElement`:
+As in React, components are built up from the JavaScript object model. One creates a component class by passing a [specification object](ComponentSpecification.md) to  [createClass](createClass.md). To instantiate an instance of the class, which can then be mounted to a Redux state tree, use [createComponent](createComponent.md), which is the analogue of React's `createElement`:
 ```coffeescript
 componentInstance = createComponent(ComponentClass)
 ```

createClass.js

@@ -1,6 +1,6 @@
 # SubtreeMixin
 ```coffeescript
-SubtreeMixin = require 'redux-components/SubtreeMixin'
+{ SubtreeMixin } = require 'redux-components'
 ```
 
 The `SubtreeMixin` is for creating components that manage a subtree of state. The state of the node is an object whose keys represent distinct subtrees. Each of these nodes has a redux-component instance mounted to it, and their reducers are combined via the standard Redux `combineReducers()` API to obtain the reducer for the parent node.

createComponent.js

@@ -1,93 +1,6 @@
 # createClass
 ```coffeescript
-createClass = require 'redux-components/createClass'
+{ createClass } = require 'redux-components'
 createClass = ({spec}) -> ReduxComponentClass
 ```
-Creates a component class given a specification object. Generally speaking, any function assigned to a key on the specification object will be copied into the prototype of the class and thus become available as instance methods. The exception to this rule is for certain specially-named keys which are used by redux-components to implement core component behavior. The special keys are as follows:
-
-## Meta properties
-
-### spec.displayName
-```coffeescript
-spec.displayName = string
-```
-If specified, gives a name to this component that can be used by debugging and development tools.
-
-> Just as with React, relying on displayName to do type checking in production is an antipattern. Use the instanceof operator.
-
-### spec.statics
-```coffeescript
-spec.statics = { ... }
-```
-All keys and values from ```spec.statics``` are merged onto the constructor for the component class via ```Object.assign```. This makes them available as "static methods" on the class constructor.
-
-### spec.mixins
-```coffeescript
-spec.mixins = [ {spec}, {spec}, ... ]
-```
-An array of additional specs that will be mixed into this spec before creating the class. Mixins are processed in the order they appear in the array. In general, the keys on the mixin specs will be assigned to the base spec as with ```Object.assign```, with auto-binding for functions. There is special behavior for certain keys. See [Mixins](Mixins.md) for more.
-
-## Lifecycle methods
-
-### spec.componentWillMount
-```coffeescript
-spec.componentWillMount = =>
-```
-### spec.componentDidMount
-```coffeescript
-spec.componentDidMount = =>
-```
-### spec.componentWillUnmount
-```coffeescript
-spec.componentWillUnmount = =>
-```
-Specifies the lifecycle methods for instances of the class. See [Components](Components.md) for details on when the methods are called.
-
-## Redux-related properties
-
-### spec.getReducer
-```coffeescript
-spec.getReducer = => (state, action) => nextState
-```
-getReducer returns a reducer function that will be used for the state subtree managed by this component.
-
-Reducers made by getReducer are automatically bound to their component instances so that they can have access to scoped properties, particularly scoped action verbs.
-
-> **NB:**
-> - After all mixins are evaluated, a final spec must have exactly one ```.getReducer```. We prefer to be unopinionated, so by default, there is no specified behavior for composing multiple reducers. (But see ```SubtreeMixin```.)
-
-> - Do not use magic binding as an excuse to introduce impure behavior into your reducer! If you want the all the benefits of Redux, keep your reducers as pure functions of props and state. Don't make your reducer rely on non-constant properties of the redux-component, and don't be tempted to  store any state on the redux-component itself. (You can sometimes use ```getReducer``` to mimic "impure" behaviors without making your reducer itself impure.)
-
-> - By default, redux-components will call `getReducer()` only once when your component is mounted to a state tree. If you expect your reducer to change during the Redux store's lifecycle, you must arrange for `getReducer()` to be called at appropriate times, and for `Store.replaceReducer()` to be called on your root store. If you use redux-components and `SubtreeMixin` throughout your state tree, we provide facilities for automating this.
-
-### spec.verbs
-```coffeescript
-spec.verbs = [ string, string, ... ]
-```
-Specifies a list of action names that will be scoped to each instance of the component using the instance's path in the state tree. Verbs are scoped according to the following pattern: ```#{path}:#{verb}``` and are available on the instance object at a key corresponding to the verb root. For example, a component instance mounted at ```foo.bar``` in the state tree having a verb ```"BAZ"``` would have the scoped verb ```"foo.bar:BAZ"``` available as ```this.BAZ```.
-
-> If you don't want a verb to be scoped, don't put it in the verbs array. Instead set it as a plain string property on the specification. It will then bypass the auto-scoping behavior.
-
-### spec.actionCreators
-```coffeescript
-spec.actionCreators = { key: (args...) -> action, ... }
-```
-Specify the action creators associated with this component class. Each property on the ```actionCreators``` object will be bound to each component instance and made available on the instance as a method.
-> **NB:** The redux-components core makes no assumptions about which middleware is present on a store. If you have e.g. `redux-thunk` middleware installed, you may of course return thunks from your actions and actionCreators.
-
-### spec.actionDispatchers
-```coffeescript
-spec.actionDispatchers = { key: (args...) -> action, ... }
-```
-Specify actions associated with this component class. Action dispatchers are like action creators, except the value returned is automatically `dispatch()`ed to the Store where this component is mounted. The wrapped action function will return the same thing as `dispatch()`, allowing it to be used with thunks and other related middleware.
-
-### spec.selectors
-```coffeescript
-spec.selectors = { key: (state, ...) -> any, ... }
-```
-Specify the selectors associated with this component class. Each property on the `selectors` object will be bound to each component instance and wrapped in a function that scopes the selector to the instance's state. The net effect will be that the state argument received by the selector will point to the state subtree managed by the particular component instance, rather than the global Redux state.
-> If you don't want a selector to be auto-scoped, don't put it in the selectors object. Instead set it as a property on the specification. This will bypass the auto-scoping behavior.
-
-## Other properties
-
-The specification's other properties will be `Object.assign()`ed onto the prototype for the class. Properties that are functions will be automatically bound to class instances by the constructor. Other properties will be available on the prototype.
+Creates a component class given a [component specification object](ComponentSpecification.md). Please see those docs for reference on how to create a specification object.