Improve Gitbook.connect to accept a mapActionsToProps

6 files changed, 135 insertions, 8 deletions

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index cf98051..fdddbb9 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -41,10 +41,15 @@
     * [Test your plugin](plugins/testing.md)
 * [Theming](themes/README.md)
 
+### Plugin Development
+
+* [Introduction](./api/README.md)
+* [Node](./api/node.md)
+* [Connect to the context](./api/connect.md)
+* [Components](./api/components.md)
+
 --
 
 * [FAQ](faq.md)
 * [Examples](examples.md)
 * [Release notes](https://github.com/GitbookIO/gitbook/blob/master/CHANGES.md)
-
-
diff --git a/docs/api/README.md b/docs/api/README.md
index 4349fd4..c3beb6e 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -1,3 +1,24 @@
 # Plugin Architecture
 
 A GitBook plugin is a NPM package that follow a defined convention.
+
+`gitbook-plugin` is a command line utility to help you create, test and release plugins.
+
+### Bootstrap your first plugin
+
+Install `gitbook-plugin` from NPM:
+
+```
+$ npm install gitbook-plugin -g
+```
+
+Then create your plugin using:
+
+```
+$ gitbook-plugin create
+```
+
+It will prompt you to enter a name and a description.
+
+
+### Publish your plugin 
diff --git a/docs/api/connect.md b/docs/api/connect.md
new file mode 100644
index 0000000..740deca
--- /dev/null
+++ b/docs/api/connect.md
@@ -0,0 +1,33 @@
+# Connect to the context
+
+`GitBook.connect(Component, [mapStateToProps], [mapActionsToProps])` connects a react component to the GitBook context.
+
+It does not modify the component class passed to it.
+Instead, it returns a new, connected component class, for you to use.
+
+### `mapStateToProps(state, [ownProps]): stateProps`
+
+If specified, the component will subscribe to GitBook store updates. Any time it updates, `mapStateToProps` will be called. Its result must be a plain object, and it will be merged into the component’s props.
+
+If you omit it, the component will not be subscribed to the GitBook store. If `ownProps` is specified as a second argument, its value will be the props passed to your component, and `mapStateToProps` will be additionally re-invoked whenever the component receives new props (e.g. if props received from a parent component have shallowly changed, and you use the `ownProps` argument, `mapStateToProps` is re-evaluated).
+
+For example to render the title of the current page:
+
+```js
+const GitBook = require('gitbook-core');
+
+let PageTitle = React.createClass({
+    render() {
+        const { page } = this.props;
+        return <h1>{page.title}</h1>;
+    }
+});
+
+function mapStateToProps(state) {
+    return { page: state.page };
+}
+
+PageTitle = GitBook.connect(PageTitle, mapStateToProps);
+```
+
+### `mapActionsToProps(actions, [dispatch])`
diff --git a/packages/gitbook-core/src/components/ContextProvider.js b/packages/gitbook-core/src/components/ContextProvider.js
new file mode 100644
index 0000000..47ed35e
--- /dev/null
+++ b/packages/gitbook-core/src/components/ContextProvider.js
@@ -0,0 +1,32 @@
+const React = require('react');
+const { Provider } = require('react-redux');
+
+/**
+ * React component to provide a GitBook context to children components.
+ */
+
+const ContextProvider = React.createClass({
+    propTypes: {
+        context: React.PropTypes.object.isRequired,
+        children: React.PropTypes.node
+    },
+
+    childContextTypes: {
+        gitbookContext: React.PropTypes.object.isRequired
+    },
+
+    getChildContext() {
+        const { context } = this.props;
+
+        return {
+            gitbookContext: context
+        };
+    },
+
+    render() {
+        const { context, children } = this.props;
+        return <Provider store={context}>{children}</Provider>;
+    }
+});
+
+module.exports = ContextProvider;
diff --git a/packages/gitbook-core/src/lib/connect.js b/packages/gitbook-core/src/lib/connect.js
index e18158e..a2f1f46 100644
--- a/packages/gitbook-core/src/lib/connect.js
+++ b/packages/gitbook-core/src/lib/connect.js
@@ -1,13 +1,49 @@
+const React = require('react');
 const ReactRedux = require('react-redux');
 
 /**
- * Connect a component to the GitBook store
+ * Use the GitBook context provided by ContextProvider to map actions to props
+ * @param  {ReactComponent} Component
+ * @param  {Function} mapActionsToProps
+ * @return {ReactComponent}
+ */
+function connectToActions(Component, mapActionsToProps) {
+    if (!mapActionsToProps) {
+        return Component;
+    }
+
+    return React.createClass({
+        displayName: `ConnectActions(${Component.displayName})`,
+        propTypes: {
+            children: React.PropTypes.node
+        },
+
+        contextTypes: {
+            gitbookContext: React.PropTypes.object.isRequired
+        },
+
+        render() {
+            const { gitbookContext } = this.context;
+            const { children, ...props } = this.props;
+            const { actions, store } = gitbookContext;
+
+            const actionsProps = mapActionsToProps(actions, store.dispatch);
+
+            return <Component {...props} {...actionsProps}>{children}</Component>;
+        }
+    });
+}
+
+/**
+ * Connect a component to the GitBook context (store and actions).
+ *
  * @param {ReactComponent} Component
  * @param {Function} mapStateToProps
  * @return {ReactComponent}
  */
-function connect(Component, mapStateToProps, mapDispatchToProps) {
-    return ReactRedux.connect(mapStateToProps, mapDispatchToProps)(Component);
+function connect(Component, mapStateToProps, mapActionsToProps) {
+    const connectToStore = ReactRedux.connect(mapStateToProps);
+    return connectToActions(connectToStore(Component), mapActionsToProps);
 }
 
 module.exports = connect;
diff --git a/packages/gitbook-core/src/lib/renderWithContext.js b/packages/gitbook-core/src/lib/renderWithContext.js
index b9e2cfd..20ec25f 100644
--- a/packages/gitbook-core/src/lib/renderWithContext.js
+++ b/packages/gitbook-core/src/lib/renderWithContext.js
@@ -1,9 +1,9 @@
 const React = require('react');
-const { Provider } = require('react-redux');
 
 const { InjectedComponent } = require('../components/InjectedComponent');
 const PJAXWrapper = require('../components/PJAXWrapper');
 const IntlProvider = require('../components/IntlProvider');
+const ContextProvider = require('../components/IntlProvider');
 
 /**
  * Render the application for a store
@@ -12,13 +12,13 @@ const IntlProvider = require('../components/IntlProvider');
  */
 function renderWithContext(context) {
     return (
-        <Provider store={context.store}>
+        <ContextProvider context={context}>
             <PJAXWrapper>
                 <IntlProvider>
                     <InjectedComponent matching={{ role: 'Body' }} />
                 </IntlProvider>
             </PJAXWrapper>
-        </Provider>
+        </ContextProvider>
     );
 }