More docs

README.md

@@ -4,34 +4,38 @@
 
 [Follow author @PAksonov](https://twitter.com/PAksonov)
 
-Please 🌟 my proposal talk for ReactiveConf 2017 [What is RNRNF?](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410) 
+Please 🌟 my talk proposal for [ReactiveConf 2017](https://reactiveconf.com/) - [What is RNRF?](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410)
 
-#### Go [here](https://github.com/aksonov/react-native-router-flux/tree/v3) for v3. Docs could be found [here](https://github.com/aksonov/react-native-router-flux/blob/master/README3.md)
+#### NOTE: v4 (based on [React Navigation](https://reactnavigation.org/)) is in beta. See [this branch](https://github.com/aksonov/react-native-router-flux/tree/v3) and [docs](https://github.com/aksonov/react-native-router-flux/blob/master/README3.md) for v3.
 
 ___
 
-Define all your routes in one place...
+* [Example](#try-the-example-app)
+* [Motivation](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410)
+* [v4 Features](#v4-features)
+* [API](/docs/API.md)
+* [Migrating from v3](/docs/MIGRATION.md)
+* [Sponsors/Backers/Contributors](#contributors)
+
+
+Define all your routes in one React component...
 
 ```js
-class App extends React.Component {
-  render() {
-    return (
-      <Router>
-        <Scene key="root">
-          <Scene key="login" component={Login} title="Login"/>
-          <Scene key="register" component={Register} title="Register"/>
-          <Scene key="home" component={Home}/>
-        </Scene>
-      </Router>
-    );
-  }
-}
+const App = () => (
+  <Router>
+    <Scene key="root">
+      <Scene key="login" component={Login} title="Login"/>
+      <Scene key="register" component={Register} title="Register"/>
+      <Scene key="home" component={Home}/>
+    </Scene>
+  </Router>
+);
 ```
 
 ...and navigate from scene to scene with a simple, powerful API
 
 ```js
-// login.js
+// Login.js
 
 // navigate to 'home' as defined in your top-level router
 Actions.home(PARAMS)
@@ -63,36 +67,20 @@ react-native run-ios
 ## v4 Features
 * Based on latest [React Navigation](https://reactnavigation.org) API
 * Separate navigation logic from presentation. You may change now navigation state directly from your business logic code - stores/reducers/etc. navigationStore
-* Built-in state machine (v3 `Switch` replacement) - each ‘scene’ could have onEnter/onExit handlers. onEnter handler could be async. For successful termination of onEnter, `success` handler (if defined) will be executed (if `success` is string then router will navigation to that Scene), in case of handler's failure `failure` (if defined) will be run. It will allow to build authentication, data validation and conditional transitions in very easy way.
-* MobX-powered, all used scenes are wrapped as 'observer' automatically. You may subscribe to navigationStore (former Actions), observe current navigation state, etc. If you are using Redux, skip this.
-* Flexible nav bar customization, that is not allowed by react navigation right now:
+* Built-in state machine (v3 `Switch` replacement)
+  * Each `Scene` can have `onEnter`/`onExit`/`on` handlers.
+  * `onEnter`/`on` handler can be async.
+  * For 'truthy' return of `onEnter`/`on`, `success` handler (if defined) will be executed
+    * if `success` is a string then router will navigate to the `Scene` with that key
+  * in case of handler's failure, `failure` prop (if defined) will be run.
+  * Combining `onEnter`, `onExit`, `success`, and `failure` makes patterns like authentication, data validation, and conditional transitions simple and intuitive.
+* [MobX](https://mobx.js.org/)-friendly: all scenes are wrapped with `observer`. You may subscribe to `navigationStore` (`Actions` in v3) and observe current navigation state. Not applicable to Redux.
+* Flexible nav bar customization not currently allowed by React Navigation:
 https://github.com/react-community/react-navigation/issues/779
-* Drawer support (provided by reactnavigation)
-* Inheritance of scene attributes allow you to avoid any code/attribute duplications. If you send rightTitle it will be shown in all children.
-* Access to your app navigations state as simple as `Actions.state`, use `Actions.currentScene` to get name of current scene.
-
-## Breaking changes (compared to v3):
-* `Actions.create` (alternative syntax to define scenes) is not available (for simplicity) - just use `<Router>` as top component for your App. You may wrap it with Redux as well.
-* No `duration`/`panHandlers` support - you have to implement custom navigator now instead and pass it as ‘navigator’ prop
-https://reactnavigation.org/docs/navigators/custom. You could still pass `panHandlers={null}` to disable gestures or `gesturedEnabled={false}`
-* No `component` support for scene containers (that contains children `Scene`) - you have to use custom navigator
-* No support for partial hiding of tab bar for some tabs because of react navigation bug (react navigation issue):
-https://github.com/react-community/react-navigation/issues/1584
-* No possibility to skip animation during reset/replace (react navigation issue):
-https://github.com/react-community/react-navigation/issues/1493
-* `Switch` is removed - you may use onEnter/onExit handlers for more flexible logic.
-* `getSceneStyle` is removed (no needed in v4, you may pass any values to Router now and they will be inherited by all scenes).
-* Custom reducer is supported (`createReducer` prop for Router) but Redux actions now are passed directly from React Navigation (‘Navigation/BACK’, ‘Navigation/NAVIGATE’, etc.)
-* Drawer is 'drawer' attribute Scene
-* Modal is 'lightbox' attribute for Scene (used for popups, like Error)
-* Container scenes (that has children) cannot have `component` (or it will be considered as child!). If you want to customize containers, use react navigation custom navigators and pass it as `navigator` prop.
-* No `position` attribute is supported for custom transitions. For vertical transition add `modal` to parent `Scene`.
-* No flux 'focus' actions - use onEnter/onExit handlers instead.
-* tabBarSelectedItemStyle is not supported. Instead please use React Navigation TabBar params for tabs Scene: `activeTintColor`, `inactiveTintColor`, etc (https://reactnavigation.org/docs/navigators/tab)
-* Possible other stuff.
-
-## Migrating from v3
-Coming soon
+* Drawer support (provided by React Navigation)
+* Inheritance of scene attributes allow you to avoid any code/attribute duplications. Adding `rightTitle` to a scene will apply to all child scenes. See example app.
+* Access to your app navigations state as simple as `Actions.state`.
+* Use `Actions.currentScene` to get name of current scene.
 
 ## Contributors
 
@@ -121,5 +109,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l
 <a href="https://opencollective.com/react-native-router-flux/sponsor/7/website" target="_blank"><img src="https://opencollective.com/react-native-router-flux/sponsor/7/avatar.svg"></a>
 <a href="https://opencollective.com/react-native-router-flux/sponsor/8/website" target="_blank"><img src="https://opencollective.com/react-native-router-flux/sponsor/8/avatar.svg"></a>
 <a href="https://opencollective.com/react-native-router-flux/sponsor/9/website" target="_blank"><img src="https://opencollective.com/react-native-router-flux/sponsor/9/avatar.svg"></a>
-
-

docs/API.md

@@ -0,0 +1,50 @@
+# API and Configuration
+
+## Available imports
+- `Router`
+- `Scene`
+- `Actions`
+- `ActionConst`
+
+## Router:
+
+| Property | Type | Default | Description |
+|-------------|----------|--------------|----------------------------------------------------------------|
+| children |  | required | Scene root element |
+| `wrapBy`   | `Function` |  | allows integration of state management schemes like Redux (`connect`) and Mobx (`observer`) |
+
+## Scene:
+
+| Property | Type | Default | Description |
+|-----------|----------|----------|--------------------------------------------|
+| `key`       | `string` | required | Will be used to call screen transition, for example, `Actions.name(params)`. Must be unique. |
+| `component` | `React.Component` | semi-required | The `Component` to be displayed. Not required when defining a nested `Scene`, see example. |
+| `initial`   | `boolean` | false | Set to `true` if this is the first scene to display among its sibling `Scene`s |
+| `clone`     | `boolean` | false | Scenes marked with `clone` will be treated as templates and cloned into the current scene's parent when pushed. See example. |
+| `on`     | `Function` | | aka `onEnter`. Called when the `Scene` is navigated to. `props` are provided as a function param |
+| `onExit`     | `Function` | | Called when the `Scene` is navigated away from. |
+| `success`     | `Function` | | If `on` returns a "truthy" value then `success` is called. |
+| `failure`     | `Function` | | If `on` returns a "falsey" value then `failure` is called. |
+| `tabs`     | `boolean` | false | load child scenes as [TabNavigator](https://reactnavigation.org/docs/navigators/tab). Other [Tab Navigator  props](https://reactnavigation.org/docs/navigators/tab#TabNavigatorConfig) also apply here. |
+| `hideTabBar`     | `boolean` | false | hide the tab bar (only applies to scenes with `tabs` specified) |
+| `drawer`     | `boolean` | false | load child scenes inside [DrawerNavigator](https://reactnavigation.org/docs/navigators/drawer) |
+| `contentComponent`     | `React.Component` |  | Component used to render the content of the drawer (e.g. navigation items). |
+| `onLeft`     | `boolean` | false | load child scenes as [DrawerNavigator](https://reactnavigation.org/docs/navigators/drawer) |
+| `navTransparent`     | `boolean` | false | nav bar background transparency |
+| `hideNavBar`     | `boolean` | false | hide the nav bar |
+| `title`     | `string` |  | Text to be displayed in the center of the nav bar. |
+| `onLeft`     | `Function` |  | Called when the left nav bar button is pressed. |
+| `onRight`     | `Function` |  | Called when the right nav bar button is pressed. |
+| `leftButtonImage`     | `Image` |  | Image to substitute for the left nav bar button |
+| `rightButtonImage`     | `Image` |  | Image to substitute for the right nav bar button |
+| `modal`     | `boolean` | false |  |
+| `back`     | `boolean` | false | Show a back button on the left side of the nav bar that calls `Actions.pop` on press. |
+| all other props     |  |  | Any other props not listed here will be pass on to the specified `Scene`'s `component` |
+
+## Actions
+
+| Property | Type | Default | Description |
+|-----------------|----------|----------|--------------------------------------------|
+| `[key]`       | `Function` |  | Scenes are "automagically" added as functions on the `Actions` object by `key`. To navigate to a scene, call `Actions.{key}`. The function takes an `Object` which gets passed to the Scene as React props. |
+| `pop`       | `Function` |  | Go back to the previous scene by "popping" the current scene off the nav stack |
+| `refresh`       | `Function` |  | "Refresh" the current scene. The function takes an `Object` which gets passed to the Scene as React props. |

docs/MIGRATION.md

@@ -1,13 +1,21 @@
-# Migrating from 2.x
+# Migrating from 3.x
 
-## Breaking changes comparing with 2.x version:
-- React Native 0.26 is required
-- `Router` is root container now and should not be nested. For nested scenes you should use `Scene` element
-- `Route` became `Scene`, now unique `key` attribute is required for each scene (it was `name` attribute before)
-- Define all your scenes on top-level, not within `Router` as before (see Example)
-- No `Schema` element is supported for now (for simplicity), maybe later it could be added
-- No ActionSheet support
-- Custom scene renderers are used instead of 'custom' types (like 'modal'), so 'modal' scenes are pushed as usual, but custom renderer will render them as popup. No `dismiss`, just usual `pop` to close such popups.
-- No old navigator.sceneConfig support (instead the component uses React Native NavigationAnimatedView for better transitions)
-- No onPush/onPop/etc handlers because they are not needed now. If navigation state is changed, container will be re-rendered with changed navigationState property, see `Modal` as Example.
-- No header/footer properties are supported for Scene currently - you may include them into Scene component.
+## Breaking changes (compared to v3):
+* `Actions.create` (alternative syntax to define scenes) is not available (for simplicity) - just use `<Router>` as top component for your App. You may wrap it with Redux as well.
+* No `duration`/`panHandlers` support - you have to implement custom navigator now instead and pass it as ‘navigator’ prop
+https://reactnavigation.org/docs/navigators/custom. You could still pass `panHandlers={null}` to disable gestures or `gesturedEnabled={false}`
+* No `component` support for scene containers (that contains children `Scene`) - you have to use custom navigator
+* No support for partial hiding of tab bar for some tabs because of react navigation bug (react navigation issue):
+https://github.com/react-community/react-navigation/issues/1584
+* No possibility to skip animation during reset/replace (react navigation issue):
+https://github.com/react-community/react-navigation/issues/1493
+* `Switch` is removed - you may use onEnter/onExit handlers for more flexible logic.
+* `getSceneStyle` is removed (no needed in v4, you may pass any values to Router now and they will be inherited by all scenes).
+* Custom reducer is supported (`createReducer` prop for Router) but Redux actions now are passed directly from React Navigation (‘Navigation/BACK’, ‘Navigation/NAVIGATE’, etc.)
+* Drawer is 'drawer' attribute Scene
+* Modal is 'lightbox' attribute for Scene (used for popups, like Error)
+* Container scenes (that has children) cannot have `component` (or it will be considered as child!). If you want to customize containers, use react navigation custom navigators and pass it as `navigator` prop.
+* No `position` attribute is supported for custom transitions. For vertical transition add `modal` to parent `Scene`.
+* No flux 'focus' actions - use onEnter/onExit handlers instead.
+* tabBarSelectedItemStyle is not supported. Instead please use React Navigation TabBar params for tabs Scene: `activeTintColor`, `inactiveTintColor`, etc (https://reactnavigation.org/docs/navigators/tab)
+* Possible other stuff.

docs/v3/MIGRATION.md

@@ -0,0 +1,13 @@
+# Migrating from 2.x
+
+## Breaking changes comparing with 2.x version:
+- React Native 0.26 is required
+- `Router` is root container now and should not be nested. For nested scenes you should use `Scene` element
+- `Route` became `Scene`, now unique `key` attribute is required for each scene (it was `name` attribute before)
+- Define all your scenes on top-level, not within `Router` as before (see Example)
+- No `Schema` element is supported for now (for simplicity), maybe later it could be added
+- No ActionSheet support
+- Custom scene renderers are used instead of 'custom' types (like 'modal'), so 'modal' scenes are pushed as usual, but custom renderer will render them as popup. No `dismiss`, just usual `pop` to close such popups.
+- No old navigator.sceneConfig support (instead the component uses React Native NavigationAnimatedView for better transitions)
+- No onPush/onPop/etc handlers because they are not needed now. If navigation state is changed, container will be re-rendered with changed navigationState property, see `Modal` as Example.
+- No header/footer properties are supported for Scene currently - you may include them into Scene component.