Add connect() API doc (#1140)

* Add `connect()` doc * Move remaining api.md to `createProvider()` and `connectAdvanced()` docs, repectively * Hide duplicated title for Provider.md * Update doc site configurations for connect doc * Fix `siteConfig.js` * Fix some links. * More betterer link fix... * Clean up connect docs * Remove createProvider page * Clean up connectAdvanced * Include docs in formatting * Specify format spacing * Format docs content * Remove stray semi
salvoravida · Dec 23, 2018 · 5088345 · 5088345
1 parent 4b03b70
commit 5088345
Show file tree

Hide file tree

Showing 17 changed files with 974 additions and 755 deletions.
diff --git a/.prettierrc b/.prettierrc
@@ -1,4 +1,5 @@
 {
   "semi": false,
-  "singleQuote": true
+  "singleQuote": true,
+  "tabWidth": 2
 }
diff --git a/docs/README.md b/docs/README.md
@@ -5,8 +5,8 @@
   - [Basic Tutorial](./introduction/basic-tutorial.md)
 - Using React Redux
   - [Connect: Extracting Data with `mapStateToProps`](./using-react-redux/connect-extracting-data-with-mapStateToProps.md)
-- [API](api.md#api)
-  - [`<Provider store>`](api.md#provider-store)
-  - [`connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])`](api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options)
-  - [`connectAdvanced(selectorFactory, [connectOptions])`](api.md#connectadvancedselectorfactory-connectoptions)
+- API
+  - [`<Provider store>`](./api/Provider.md)
+  - [`connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])`](./api/connect.md)
+  - [`connectAdvanced(selectorFactory, [connectOptions])`](./api/connect-advanced.md)
 - [Troubleshooting](troubleshooting.md#troubleshooting)
diff --git a/docs/api.md b/docs/api.md
diff --git a/docs/api/Provider.md b/docs/api/Provider.md
@@ -2,6 +2,7 @@
 id: provider
 title: Provider
 sidebar_label: Provider
+hide_title: true
 ---
 
 # `<Provider />`
@@ -18,62 +19,60 @@ Note: If you really need to, you can manually pass `store` as a prop to a connec
 
 ### Props
 
-`store` (Redux Store)
+`store` ([Redux Store](https://redux.js.org/api/store))
 The single Redux `store` in your application.
 
 `children` (ReactElement)
 The root of your component hierarchy.
 
-
 ### Example Usage
 
 In the example below, the `<App />` component is our root-level component. This means it’s at the very top of our component hierarchy.
 
 **Vanilla React Example**
 
 ```jsx
-    import React from 'react';
-    import ReactDOM from 'react-dom';
-    import { Provider } from 'react-redux';
-
-    import { App } from './App';
-    import createStore from './createReduxStore';
+import React from 'react'
+import ReactDOM from 'react-dom'
+import { Provider } from 'react-redux'
 
-    const store = createStore();
+import { App } from './App'
+import createStore from './createReduxStore'
 
-    ReactDOM.render(
-      <Provider store={store}>
-        <App />
-      </Provider>,
-      document.getElementById('root')
-    )
-```    
+const store = createStore()
 
+ReactDOM.render(
+  <Provider store={store}>
+    <App />
+  </Provider>,
+  document.getElementById('root')
+)
+```
 
 **Usage with React Router**
 
 ```jsx
-    import React from 'react';
-    import ReactDOM from 'react-dom';
-    import { Provider } from 'react-redux';
-    import { Router, Route } from 'react-router-dom';
-
-    import { App } from './App';
-    import { Foo } from './Foo';
-    import { Bar } from './Bar';
-    import createStore from './createReduxStore';
-
-    const store = createStore();
-
-    ReactDOM.render(
-      <Provider store={store}>
-        <Router history={history}>
-          <Route path="/" component={App}>
-            <Route path="foo" component={Foo}/>
-            <Route path="bar" component={Bar}/>
-          </Route>
-        </Router>
-      </Provider>,
-      document.getElementById('root')
-    )
-```    
+import React from 'react'
+import ReactDOM from 'react-dom'
+import { Provider } from 'react-redux'
+import { Router, Route } from 'react-router-dom'
+
+import { App } from './App'
+import { Foo } from './Foo'
+import { Bar } from './Bar'
+import createStore from './createReduxStore'
+
+const store = createStore()
+
+ReactDOM.render(
+  <Provider store={store}>
+    <Router history={history}>
+      <Route path="/" component={App}>
+        <Route path="foo" component={Foo} />
+        <Route path="bar" component={Bar} />
+      </Route>
+    </Router>
+  </Provider>,
+  document.getElementById('root')
+)
+```
diff --git a/docs/api/connect-advanced.md b/docs/api/connect-advanced.md
@@ -0,0 +1,86 @@
+---
+id: connect-advanced
+title: connectAdvanced
+sidebar_label: connectAdvanced()
+hide_title: true
+---
+
+# `connectAdvanced()`
+
+```js
+connectAdvanced(selectorFactory, connectOptions?)
+```
+
+Connects a React component to a Redux store. It is the base for `connect()` but is less opinionated about how to combine `state`, `props`, and `dispatch` into your final props. It makes no assumptions about defaults or memoization of results, leaving those responsibilities to the caller.
+
+It does not modify the component class passed to it; instead, it _returns_ a new, connected component class for you to use.
+
+Most applications will not need to use this, as the default behavior in `connect` is intended to work for most use cases.
+
+> Note: `connectAdvanced` was added in version 5.0, and `connect` was reimplemented as a specific set of parameters to `connectAdvanced`.
+
+## Arguments
+
+- `selectorFactory(dispatch, factoryOptions): selector(state, ownProps): props` \(_Function_): Initializes a selector function (during each instance's constructor). That selector function is called any time the connector component needs to compute new props, as a result of a store state change or receiving new props. The result of `selector` is expected to be a plain object, which is passed as the props to the wrapped component. If a consecutive call to `selector` returns the same object (`===`) as its previous call, the component will not be re-rendered. It's the responsibility of `selector` to return that previous object when appropriate.
+
+- [`connectOptions`] _(Object)_ If specified, further customizes the behavior of the connector.
+
+  - [`getDisplayName`] _(Function)_: computes the connector component's displayName property relative to that of the wrapped component. Usually overridden by wrapper functions. Default value: `name => 'ConnectAdvanced('+name+')'`
+
+  - [`methodName`] _(String)_: shown in error messages. Usually overridden by wrapper functions. Default value: `'connectAdvanced'`
+
+  - [`renderCountProp`] _(String)_: if defined, a property named this value will be added to the props passed to the wrapped component. Its value will be the number of times the component has been rendered, which can be useful for tracking down unnecessary re-renders. Default value: `undefined`
+
+  - [`shouldHandleStateChanges`] _(Boolean)_: controls whether the connector component subscribes to redux store state changes. If set to false, it will only re-render when parent component re-renders. Default value: `true`
+
+  - [`forwardRef`] _(Boolean)_: If true, adding a ref to the connected wrapper component will actually return the instance of the wrapped component.
+
+  - Additionally, any extra options passed via `connectOptions` will be passed through to your `selectorFactory` in the `factoryOptions` argument.
+
+<a id="connectAdvanced-returns"></a>
+
+## Returns
+
+A higher-order React component class that builds props from the store state and passes them to the wrapped component. A higher-order component is a function which accepts a component argument and returns a new component.
+
+### Static Properties
+
+- `WrappedComponent` _(Component)_: The original component class passed to `connectAdvanced(...)(Component)`.
+
+### Static Methods
+
+All the original static methods of the component are hoisted.
+
+## Remarks
+
+- Since `connectAdvanced` returns a higher-order component, it needs to be invoked two times. The first time with its arguments as described above, and a second time, with the component: `connectAdvanced(selectorFactory)(MyComponent)`.
+
+- `connectAdvanced` does not modify the passed React component. It returns a new, connected component, that you should use instead.
+
+<a id="connectAdvanced-examples"></a>
+
+### Examples
+
+### Inject `todos` of a specific user depending on props, and inject `props.userId` into the action
+
+```js
+import * as actionCreators from './actionCreators'
+import { bindActionCreators } from 'redux'
+
+function selectorFactory(dispatch) {
+  let ownProps = {}
+  let result = {}
+
+  const actions = bindActionCreators(actionCreators, dispatch)
+  const addTodo = text => actions.addTodo(ownProps.userId, text)
+
+  return (nextState, nextOwnProps) => {
+    const todos = nextState.todos[nextOwnProps.userId]
+    const nextResult = { ...nextOwnProps, todos, addTodo }
+    ownProps = nextOwnProps
+    if (!shallowEqual(result, nextResult)) result = nextResult
+    return result
+  }
+}
+export default connectAdvanced(selectorFactory)(TodoApp)
+```