Add doc for web, createAppContainer docs for v3

Author: ericvicenti

docs/app-containers.md

@@ -0,0 +1,72 @@
+---
+id: app-containers
+title: App Containers
+sidebar_label: App Containers
+---
+
+Containers are responsible for managing your app state and linking your top-level navigator to the app environment. On Android, the app container uses the Linking API to handle the back button. The container can also be configured to persist your navigation state. On web, you'd use different containers than React Native.
+
+> Note: In v2 and earlier, the containers in React Navigation were automatically provided by the `create*Navigator` functions. Now you are required to use the container directly. In v3 we also renamed `createNavigationContainer` to `createAppContainer`.
+
+A quick example of `createAppContainer`:
+
+```
+import { createAppContainer } from 'react-navigation';
+// you can also import from @react-navigation/native
+
+const AppNavigator = createStackNavigator(...);
+
+const AppContainer = createAppContainer(AppNavigator);
+
+// Now AppContainer is the main component for React to render
+
+export default AppContainer;
+```
+
+## Props of `createAppContainer` on React Native
+
+```js
+<AppContainer
+  onNavigationStateChange={handleNavigationChange}
+  uriPrefix="/app"
+/>
+```
+
+### `onNavigationStateChange(prevState, newState, action)`
+
+Function that gets called every time navigation state managed by the navigator changes. It receives the previous state, the new state of the navigation and the action that issued state change. By default it prints state changes to the console.
+
+### `uriPrefix`
+
+The prefix of the URIs that the app might handle. This will be used when handling a [deep link](deep-linking.html) to extract the path passed to the router.
+
+## Calling Dispatch or Navigate on App Container
+
+In case you want to dispatch actions on an app container, you can use a React [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html#the-ref-callback-attribute) to call the `dispatch` method on it:
+
+```js
+const AppContainer = createAppContainer(AppNavigator);
+
+class App extends React.Component {
+  someEvent() {
+    // call navigate for AppNavigator here:
+    this.navigator &&
+      this.navigator.dispatch(
+        NavigationActions.navigate({ routeName: someRouteName })
+      );
+  }
+  render() {
+    return (
+      <AppContainer
+        ref={nav => {
+          this.navigator = nav;
+        }}
+      />
+    );
+  }
+}
+```
+
+## App Containers on the web
+
+On the web, you can use `createBrowserApp` and `handleServerRequest` to maintain the state for your top-level navigator.

docs/custom-navigator-overview.md

@@ -22,47 +22,6 @@ Under the hood, navigators are plain React components.
 The navigators render application screens which are just React components.
 
 To learn how to create screens, read about:
+
 - [Screen `navigation` prop](navigation-prop.html) to allow the screen to dispatch navigation actions, such as opening another screen
 - Screen `navigationOptions` to customize how the screen gets presented by the navigator (e.g. [header title](stack-navigator.html#navigationoptions-used-by-stacknavigator), tab label)
-
-### Calling Navigate on Top Level Component
-
-In case you want to use Navigator from the same level you declare it you can use react's [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html#the-ref-callback-attribute) option:  
-```js
-import { NavigationActions } from 'react-navigation';
-
-const AppNavigator = createStackNavigator(SomeAppRouteConfigs);
-
-class App extends React.Component {
-  someEvent() {
-    // call navigate for AppNavigator here:
-    this.navigator && this.navigator.dispatch(
-      NavigationActions.navigate({ routeName: someRouteName })
-    );
-  }
-  render() {
-    return (
-      <AppNavigator ref={nav => { this.navigator = nav; }} />
-    );
-  }
-}
-```
-Please notice that this solution should only be used on the top level navigator.  
-
-## Navigation Containers
-
-The built in navigators can automatically behave like top-level navigators when the navigation prop is missing. This functionality provides a transparent navigation container, which is where the top-level navigation prop comes from.
-
-When rendering one of the included navigators, the navigation prop is optional. When it is missing, the container steps in and manages its own navigation state. It also handles URLs, external linking, and Android back button integration.
-
-For the purpose of convenience, the built-in navigators have this ability because behind the scenes they use `createNavigationContainer`. Usually, navigators require a navigation prop in order to function.
-
-Top-level navigators accept the following props:  
-
-### `onNavigationStateChange(prevState, newState, action)`
-
-Function that gets called every time navigation state managed by the navigator changes. It receives the previous state, the new state of the navigation and the action that issued state change. By default it prints state changes to the console.
-
-### `uriPrefix`
-
-The prefix of the URIs that the app might handle. This will be used when handling a [deep link](deep-linking.html) to extract the path passed to the router.

docs/custom-navigators.md

@@ -52,7 +52,6 @@ class CustomNavigator extends React.Component {
 }
 ```
 
-
 ## Navigator Navigation Prop
 
 The navigation prop passed down to a navigator only includes `state`, `dispatch`, and `addListener`. This is the current state of the navigator, and an event channel to send action requests.
@@ -102,7 +101,7 @@ To help developers implement custom navigators, the following utilities are prov
 This utility combines a [router](routers.html) and a [navigation view](navigation-views.html) together in a standard way:
 
 ```js
-import {createNavigator} from 'react-navigation';
+import { createNavigator } from "react-navigation";
 
 const AppNavigator = createNavigator(NavigationView, router, navigationConfig);
 ```
@@ -127,7 +126,7 @@ Then the view will be rendered in the following way:
 />
 ```
 
-The `navigation` prop is the same navigation prop that was passed into the navigator.  
+The `navigation` prop is the same navigation prop that was passed into the navigator.
 
 Both `navigationConfig` and `screenProps` are simply passed through, as defined above.
 
@@ -142,8 +141,3 @@ A scene descriptor has the following properties:
 - `navigation`, the child navigation prop, including actions and the route `state`
 - `state`, the navigation state for the child screen (a shortcut for `navigation.state`)
 - `key`, the key of the route (a shortcut for `navigation.state.key`)
-
-
-### `createNavigationContainer`
-
-If you want your navigator to be usable as a top-level component, (without a navigation prop being passed in), you can use `createNavigationContainer`. This utility will make your navigator act like a top-level navigator when the navigation prop is missing. It will manage the app state, and integrate with app-level nav features, like handling incoming and outgoing links, and Android back button behavior.

docs/hello-react-navigation.md

@@ -8,7 +8,7 @@ In a web browser, you can link to different pages using an anchor (`<a>`) tag. W
 
 React Navigation's stack navigator provides a way for your app to transition between screens and manage navigation history. If your app uses only one stack navigator then it is conceptually similar to how a web browser handles navigation state - your app pushes and pops items from the navigation stack as users interact with it, and this results in the user seeing different screens. A key difference between how this works in a web browser and in React Navigation is that React Navigation's stack navigator provides the gestures and animations that you would expect on Android and iOS when navigating between routes in the stack.
 
-All we need to get started using React Navigation is a function called `createStackNavigator`.
+Lets start by demonstrating the most common navigator, `createStackNavigator`.
 
 ## Creating a stack navigator
 
@@ -17,47 +17,45 @@ All we need to get started using React Navigation is a function called `createSt
 ```javascript
 // In App.js in a new project
 
-import React from 'react';
-import { View, Text } from 'react-native';
-import { createStackNavigator } from 'react-navigation';
+import React from "react";
+import { View, Text } from "react-native";
+import { createStackNavigator, createAppContainer } from "react-navigation";
 
 class HomeScreen extends React.Component {
   render() {
     return (
-      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+      <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
         <Text>Home Screen</Text>
       </View>
     );
   }
 }
 
-export default createStackNavigator({
+const AppNavigator = createStackNavigator({
   Home: {
     screen: HomeScreen
-  },
+  }
 });
+
+export default createAppContainer(AppNavigator);
 ```
 
-<a href="https://snack.expo.io/@react-navigation/hello-world-v2" target="blank" class="run-code-button">&rarr; Run this code</a> 
+<a href="https://snack.expo.io/@react-navigation/hello-world-v2" target="blank" class="run-code-button">&rarr; Run this code</a>
 
 If you run this code, you will see a screen with an empty navigation bar and a grey content area containing your `HomeScreen` component. The styles you see for the navigation bar and the content area are the default configuration for a stack navigator, we'll learn how to configure those later.
 
 > The casing of the route name doesn't matter -- you can use lowercase `home` or capitalized `Home`, it's up to you. We prefer capitalizing our route names.
 
 > The only required configuration for a route is the `screen` component. You can read more about the other options available in the [StackNavigator reference](stack-navigator.html).
 
-In React Native, the component exported from `App.js` is the entry point (or root component) for your app -- it is the component from which every other component descends. It's often useful to have more control over the component at the root of your app than you would get from exporting the result of `createStackNavigator`, so let's export a component that just renders our `RootStack` stack navigator.
+In React Native, the component exported from `App.js` is the entry point (or root component) for your app -- it is the component from which every other component descends. It's often useful to have more control over the component at the root of your app than you would get from exporting the result of `createAppContainer`, so let's export a component that just renders our `AppNavigator` stack navigator.
 
 ```js
-const RootStack = createStackNavigator({
-  Home: {
-    screen: HomeScreen
-  },
-});
+const AppContainer = createAppContainer(AppNavigator);
 
 export default class App extends React.Component {
   render() {
-    return <RootStack />;
+    return <AppContainer />;
   }
 }
 ```
@@ -82,7 +80,7 @@ The `<RootStack />` component doesn't accept any props -- all configuration is s
 class DetailsScreen extends React.Component {
   render() {
     return (
-      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+      <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
         <Text>Details Screen</Text>
       </View>
     );
@@ -92,10 +90,10 @@ class DetailsScreen extends React.Component {
 const RootStack = createStackNavigator(
   {
     Home: HomeScreen,
-    Details: DetailsScreen,
+    Details: DetailsScreen
   },
   {
-    initialRouteName: 'Home',
+    initialRouteName: "Home"
   }
 );
 
@@ -106,8 +104,8 @@ Now our stack has two _routes_, a `Home` route and a `Details` route. The `Home`
 
 ## Summary
 
-* React Native doesn't have a built-in API for navigation like a web browser does. React Navigation provides this for you, along with the iOS and Android gestures and animations to transition between screens.
-* `createStackNavigator` is a function that takes a route configuration object and an options object and returns a React component.
-* The keys in the route configuration object are the route names and the values are the configuration for that route. The only required property on the configuration is the `screen` (the component to use for the route).
-* To specify what the initial route in a stack is, provide an `initialRouteName` on the stack options object.
-* [Full source of what we have built so far](https://snack.expo.io/@react-navigation/hello-react-navigation-v2).
+- React Native doesn't have a built-in API for navigation like a web browser does. React Navigation provides this for you, along with the iOS and Android gestures and animations to transition between screens.
+- `createStackNavigator` is a function that takes a route configuration object and an options object and returns a React component.
+- The keys in the route configuration object are the route names and the values are the configuration for that route. The only required property on the configuration is the `screen` (the component to use for the route).
+- To specify what the initial route in a stack is, provide an `initialRouteName` on the stack options object.
+- [Full source of what we have built so far](https://snack.expo.io/@react-navigation/hello-react-navigation-v2).

docs/web-support.md

@@ -0,0 +1,81 @@
+---
+id: web-support
+title: React Navigation on the Web
+sidebar_label: Web Support
+---
+
+Starting in v3, React Navigation has built-in support for web sites, including server rendering.
+
+To set up a navigator in a React app, [(such as one created with create-react-app)](https://github.com/react-navigation/example-web):
+
+```js
+import { createSwitchNavigator } from "@react-navigation/core";
+import { createBrowserApp } from "@react-navigation/web";
+
+const MyNavigator = createSwitchNavigator(routes);
+
+const App = createBrowserApp(MyNavigator);
+
+// now you can render "App" normally
+```
+
+## Web Links
+
+We ship a utility out of the box which automatically sets up an `<a>` tag for you with the correct `href`.
+
+This is necessary to properly support server rendering, critical for accessibility, and nice to provide a good user experience when the browser displays what URL the link will go to.
+
+When the app is running, the default browser behavior will be blocked and a navigation action will be dispatched instead.
+
+To render a link to the "Profile" route:
+
+```js
+<Link toRoute="Profile" params={{ name: "jamie" }}>
+  Jamie's Profile
+</Link>
+```
+
+Depending on the `path` that is set up for the `Profile` route, the above link may render to html as `<a href="/people/jamie">Jamie's Profile</a>`
+
+You can alternatively provide an `action` prop to the `Link`, to specify the exact navigation action that will be used to handle this link.
+
+## Server rendering
+
+You can use the `handleServerRequest` function to get the top-level navigation prop for your app, as well as the current title for this route.
+
+```js
+expressApp.get("/*", (req, res) => {
+  const { navigation, title, options } = handleServerRequest(
+    AppNavigator.router,
+    path,
+    query
+  );
+
+  const markup = renderToString(<AppNavigator navigation={navigation} />);
+
+  res.send(
+    `<!doctype html>
+  <html lang="">
+  <head>
+    <title>${title}</title>
+    <script src="main.js"></script>
+  </head>
+  <body>
+    <div id="root">${markup}</div>
+  </body>
+</html>`
+  );
+});
+```
+
+For a full example, [see a full server+client React web app here](https://github.com/react-navigation/web-server-example)
+
+## Custom navigators for the web
+
+The built-in navigator components such as Stack are often not well suited for web sites, so you may want to create custom navigators yourself.
+
+Your view can use `props.descriptors` to see the current set of screens, get their navigation object, and see the current navigation options. You should use `SceneView` to present your child screen components.
+
+See ["Custom Navigators"](custom-navigators.html) for more details.
+
+For an example of this, see how the custom `SidebarView` and `AppView` are used from [`App.js` in the web server example](https://github.com/react-navigation/web-server-example/blob/master/src/App.js).

website/i18n/en.json

@@ -9,6 +9,8 @@
     "anti-pitch": "anti-pitch",
     "api-reference": "API Reference",
     "Overview": "Overview",
+    "app-containers": "App Containers",
+    "App Containers": "App Containers",
     "auth-flow": "Authentication flows",
     "Authentication flows": "Authentication flows",
     "bottom-tab-navigator": "createBottomTabNavigator",
@@ -119,6 +121,8 @@
     "createTabNavigator": "createTabNavigator",
     "transitioner": "Transitioner",
     "Transitioner": "Transitioner",
+    "web-support": "React Navigation on the Web",
+    "Web Support": "Web Support",
     "with-navigation-focus": "withNavigationFocus",
     "withNavigationFocus": "withNavigationFocus",
     "with-navigation": "withNavigation",

website/sidebars.json

@@ -8,6 +8,7 @@
       "params",
       "headers",
       "header-buttons",
+      "app-containers",
       "modal",
       "next-steps",
       "glossary-of-terms",
@@ -28,7 +29,8 @@
       "deep-linking",
       "screen-tracking",
       "state-persistence",
-      "redux-integration"
+      "redux-integration",
+      "web-support"
     ],
     "Build your own Navigator": [
       "custom-navigator-overview",