Add Navigation Overview

Summary:
Initial stab at writing a high level guide on navigation. Its main focus is on Navigator due to it being cross-platform and fairly simple to use.

This guide should be expanded to cover tabbed applications in a future pull request.

The Navigation (Experimental) section will be similarly expanded upon as the API stabilizes.

![navigation](https://cloud.githubusercontent.com/assets/165856/16324560/52b508dc-396a-11e6-94b7-b2d1175f69e0.png)
Closes #8390

Differential Revision: D3480304

Pulled By: caabernathy

fbshipit-source-id: 280da9185fca295bc107a2df20106c783b461be7

Libraries/Components/Navigation/NavigatorIOS.ios.js

@@ -98,9 +98,6 @@ type Event = Object;
  * [`Navigator`](/docs/navigator.html) for a similar solution for your
  * cross-platform needs.
  *
- * > **NOTE**: This component is not maintained by Facebook and is the
- * > community's responsibility.
- *
  * To set up the navigator, provide the `initialRoute` prop with a route
  * object. A route object is used to describe each scene that your app
  * navigates to. `initialRoute` represents the first route in your navigator.

docs/JavaScriptEnvironment.md

@@ -4,7 +4,7 @@ title: JavaScript Environment
 layout: docs
 category: Guides
 permalink: docs/javascript-environment.html
-next: navigator-comparison
+next: navigation
 ---
 
 ## JavaScript Runtime

docs/Navigation.md

@@ -0,0 +1,165 @@
+---
+id: navigation
+title: Navigation
+layout: docs
+category: Guides
+permalink: docs/navigation.html
+next: navigator-comparison
+---
+
+Mobile apps rarely consist of just one screen or scene. As soon as you add a second scene to your app, you will have to take into consideration how the user will navigate from one scene to the other.
+
+Navigators in React Native allow you to push and pop scenes in a master/detail stack, or to pop up modal scenes. Navigators handle the transitions between scenes, and also maintain the navigational state of your application.
+
+If you are just getting started with React Native, you will probably want to start with the `Navigator` component.
+
+## Navigator
+
+`Navigator` is a cross-platform implementation of a navigation stack, so it works on both iOS and Android. It is easy to customize and includes simple navigation bars.
+
+```js
+<Navigator
+  initialRoute={{ title: 'My Initial Scene', index: 0}}
+  renderScene={(route, navigator) => {
+      // We'll get to this function soon.
+  }}
+/>
+```
+
+Something you will encounter a lot when dealing with navigation is the concept of routes. A route is an object that contains information about a scene. It is used to provide all the context the `renderScene` function needs to render a scene.
+
+The `push` and `pop` functions provided by Navigator can be used to push and pop routes into the navigation stack. A more complete example that demonstrates the pushing and popping of routes could therefore look something like this:
+
+```js
+class MyScene extends Component {
+  static propTypes = {
+    title: PropTypes.string.isRequired,
+    onForward: PropTypes.func.isRequired,
+    onBack: PropTypes.func.isRequired,
+  }
+  render() {
+    return (
+      <View>
+        <Text>Current Scene: { this.props.title }</Text>
+        <TouchableHighlight onPress={this.props.onForward}>
+          <Text>Tap me to load the next scene</Text>
+        </TouchableHighlight>
+        <TouchableHighlight onPress={this.props.onBack}>
+          <Text>Tap me to go back</Text>
+        </TouchableHighlight>
+      </View>
+    )
+  }
+}
+
+class SimpleNavigationApp extends Component {
+  render() {
+    return (
+      <Navigator
+        initialRoute={{ title: 'My Initial Scene', index: 0 }}
+        renderScene={(route, navigator) =>
+          <MyScene
+            title={route.title}
+            onForward={ () => {
+              const nextIndex = route.index + 1;
+              navigator.push({
+                title: 'Scene ' + nextIndex,
+                index: nextIndex,
+              });
+            }}
+            onBack={() => {
+              if (route.index > 0) {
+                navigator.pop();
+              }
+            }}
+          />
+        }
+      />
+    )
+  }
+}
+```
+
+In this example, the `MyScene` component is passed the title of the current route via the `title` prop. It displays two tappable components that call the `onForward` and `onBack` functions passed through its props, which in turn will call `navigator.push()` and `navigator.pop()` as needed.
+
+While this is a very basic example, it can easily be adapted to render an entirely different component based on the route that is passed to the `renderScene` function. Navigator will push new scenes from the right by default, and you can control this behavior by using the `configureScene` function. Check out the [Navigator API reference](docs/navigator.html) to learn more.
+
+## NavigatorIOS
+
+If you are targeting iOS only, you may also want to consider using `NavigatorIOS`. It looks and feels just like `UINavigationController`, because it is actually built on top of it.
+
+```js
+<NavigatorIOS
+  initialRoute={{
+    component: MyScene,
+    title: 'My Initial Scene',
+    passProps: { myProp: 'foo' },
+  }}
+/>
+```
+
+Just like Navigator, it it uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the `component` key in the route, and any props that should be passed to this component can be specified in `passProps`. A navigator object is automatically passed as a prop to the component, allowing you to call `push` and `pop` as needed.
+
+Check out the [NavigatorIOS reference docs](docs/navigatorios.html) to learn more about this component.
+
+```js
+class MyScene extends Component {
+  static propTypes = {
+    title: PropTypes.string.isRequired,
+    navigator: PropTypes.object.isRequired,
+  }
+
+  constructor(props, context) {
+    super(props, context);
+    this._onForward = this._onForward.bind(this);
+    this._onBack = this._onBack.bind(this);
+  }
+
+  _onForward() {
+    this.props.navigator.push({
+      title: 'Scene ' + nextIndex,
+    });
+  }
+
+  _onBack() {
+    this.props.navigator.pop();
+  }
+
+  render() {
+    return (
+      <View>
+        <Text>Current Scene: { this.props.title }</Text>
+        <TouchableHighlight onPress={this._onForward}>
+          <Text>Tap me to load the next scene</Text>
+        </TouchableHighlight>
+        <TouchableHighlight onPress={this._onBack}>
+          <Text>Tap me to go back</Text>
+        </TouchableHighlight>
+      </View>
+    )
+  }
+}
+
+class NavigatorIOSApp extends Component {
+  render() {
+    return (
+      <NavigatorIOS
+        initialRoute={{
+          component: MyScene,
+          title: 'My Initial Scene',
+          index: 0
+        }}
+        renderScene={ (route, navigator) =>
+          <MyScene title={route.title} />
+        }
+      />
+    )
+  }
+}
+```
+
+> You may also want to check out [react-native-navigation](https://github.com/wix/react-native-navigation), a component that aims to provide native navigation on both iOS and Android.
+
+## Navigation (Experimental)
+
+If you are looking for a more powerful navigation API, check out [NavigationExperimental](https://github.com/facebook/react-native/tree/master/Examples/UIExplorer/NavigationExperimental). It provides greater customization over your transitions, uses single-directional data flow using reducers to manipulate state at a top-level object, and offloads transition animations to the GPU.