Add docs for tabBarOnLongPress and animated switch navigator (react-navigation#404)

jarvisluong · brentvatne · commit 9ccb0851ffdd · 2019-04-15T10:02:56.000-07:00
* chore: add doc for tabBarOnLongPress

* update docs on v3 branch

* docs about animated switch navigator

* Update wording for docs/animated-switch-navigator.md

Co-Authored-By: jarvisluong &lt;jarvisluong@users.noreply.github.com&gt;

* document the transition option for animated switch navigator
diff --git a/docs/animated-switch-navigator.md b/docs/animated-switch-navigator.md
@@ -0,0 +1,19 @@
+---
+id: animated-switch-navigator
+title: createAnimatedSwitchNavigator
+sidebar_label: createAnimatedSwitchNavigator
+---
+
+A switch navigator with the ability to animate transitions between screens. 
+
+To use this navigator, you need to install `react-native-reanimated >= 1.0.0`. If you have a managed Expo project, you need to use >= SDK 33 to have the correct version of Reanimated.
+
+## API Definition
+
+```js
+import createAnimatedSwitchNavigator from 'react-navigation-animated-switch';
+
+createAnimatedSwitchNavigator(RouteConfigs, SwitchNavigatorConfig);
+```
+
+The route configs and navigator configs are identical to [createSwitchNavigator](switch-navigator.html)
diff --git a/docs/bottom-tab-navigator.md b/docs/bottom-tab-navigator.md
@@ -111,4 +111,12 @@ Callback to handle press events; the argument is an object containing:
 * `navigation`: navigation prop for the screen
 * `defaultHandler`: the default handler for tab press
 
-Useful for adding a custom logic before the transition to the next scene (the tapped one) starts.
+Useful for adding a custom logic before the transition to the next scene (the
+tapped one) starts.
+
+#### `tabBarOnLongPress`
+
+Callback to handle long press events; the argument is an object containing:
+
+- `navigation`: navigation prop for the screen
+- `defaultHandler`: the default handler for tab press
diff --git a/docs/material-bottom-tab-navigator.md b/docs/material-bottom-tab-navigator.md
@@ -16,8 +16,15 @@ npm install react-navigation-material-bottom-tabs react-native-paper
 
 This API also requires that you install `react-native-vector-icons`! If you are using Expo, it will just work out of the box. Otherwise, [follow these installation instructions](https://github.com/oblador/react-native-vector-icons#installation).
 
+To use this tab navigator, import it from `react-navigation-material-bottom-tabs`
+
 ```js
-createMaterialBottomTabNavigator(RouteConfigs, MaterialBottomTabNavigatorConfig);
+import { createMaterialBottomTabNavigator } from "react-navigation-material-bottom-tabs";
+
+createMaterialBottomTabNavigator(
+  RouteConfigs,
+  MaterialBottomTabNavigatorConfig
+);
 ```
 
 This library uses the [`BottomNavigation` component from `react-native-paper`](https://callstack.github.io/react-native-paper/bottom-navigation.html). It doesn't include the whole `react-native-paper` library in your bundle, so you don't need to worry about it.
diff --git a/docs/material-top-tab-navigator.md b/docs/material-top-tab-navigator.md
@@ -94,4 +94,12 @@ Callback to handle press events; the argument is an object containing:
 * `navigation`: navigation prop for the screen
 * `defaultHandler`: the default handler for tab press
 
-Useful for adding a custom logic before the transition to the next scene (the tapped one) starts.
+Useful for adding a custom logic before the transition to the next scene (the
+tapped one) starts.
+
+#### `tabBarOnLongPress`
+
+Callback to handle long press events; the argument is an object containing:
+
+- `navigation`: navigation prop for the screen
+- `defaultHandler`: the default handler for tab press
diff --git a/docs/tab-navigator.md b/docs/tab-navigator.md
@@ -4,7 +4,7 @@ title: createTabNavigator
 sidebar_label: createTabNavigator
 ---
 
-> Note: `createTabNavigator` is deprecated. Please use `createBottomTabNavigator` and/or `createMaterialTopTabNavigator` instead.
+> Note: `createTabNavigator` is deprecated and removed in `react-navigation@3.x`. Please use `createBottomTabNavigator` and/or `createMaterialTopTabNavigator` instead.
 
 ```js
 createTabNavigator(RouteConfigs, TabNavigatorConfig);
diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -9,6 +9,10 @@
         "title": "Alternative libraries",
         "sidebar_label": "Alternative libraries"
       },
+      "animated-switch-navigator": {
+        "title": "createAnimatedSwitchNavigator",
+        "sidebar_label": "createAnimatedSwitchNavigator"
+      },
       "anti-pitch": {
         "title": "anti-pitch"
       },
@@ -24,9 +28,6 @@
         "title": "Authentication flows",
         "sidebar_label": "Authentication flows"
       },
-      "bottom-sheet": {
-        "title": "bottom-sheet"
-      },
       "bottom-tab-navigator": {
         "title": "createBottomTabNavigator",
         "sidebar_label": "createBottomTabNavigator"
@@ -89,9 +90,6 @@
         "title": "createDrawerNavigator",
         "sidebar_label": "createDrawerNavigator"
       },
-      "dynamic-routes": {
-        "title": "dynamic-routes"
-      },
       "function-after-focusing-screen": {
         "title": "Call a function when focused screen changes",
         "sidebar_label": "Call a function when focused screen changes"
@@ -134,9 +132,6 @@
         "title": "Know when a screen is focused and blurred",
         "sidebar_label": "Know when a screen is focused and blurred"
       },
-      "localization": {
-        "title": "localization"
-      },
       "material-bottom-tab-navigator": {
         "title": "createMaterialBottomTabNavigator",
         "sidebar_label": "createMaterialBottomTabNavigator"
@@ -666,6 +661,10 @@
         "title": "withNavigation",
         "sidebar_label": "withNavigation"
       },
+      "version-3.x-animated-switch-navigator": {
+        "title": "createAnimatedSwitchNavigator",
+        "sidebar_label": "createAnimatedSwitchNavigator"
+      },
       "version-3.x-auth-flow": {
         "title": "Authentication flows",
         "sidebar_label": "Authentication flows"
@@ -734,6 +733,10 @@
         "title": "Limitations",
         "sidebar_label": "Limitations"
       },
+      "version-3.x-material-bottom-tab-navigator": {
+        "title": "createMaterialBottomTabNavigator",
+        "sidebar_label": "createMaterialBottomTabNavigator"
+      },
       "version-3.x-material-top-tab-navigator": {
         "title": "createMaterialTopTabNavigator",
         "sidebar_label": "createMaterialTopTabNavigator"
@@ -762,6 +765,10 @@
         "title": "Navigation options resolution",
         "sidebar_label": "Navigation options resolution"
       },
+      "version-3.x-navigation-views": {
+        "title": "Navigation views",
+        "sidebar_label": "Navigation views"
+      },
       "version-3.x-params": {
         "title": "Passing parameters to routes",
         "sidebar_label": "Passing parameters to routes"
@@ -806,10 +813,18 @@
         "title": "Tab navigation",
         "sidebar_label": "Tab navigation"
       },
+      "version-3.x-tab-navigator": {
+        "title": "createTabNavigator",
+        "sidebar_label": "createTabNavigator"
+      },
       "version-3.x-themes": {
         "title": "Themes",
         "sidebar_label": "Themes"
       },
+      "version-3.x-transitioner": {
+        "title": "Transitioner",
+        "sidebar_label": "Transitioner"
+      },
       "version-3.x-web-support": {
         "title": "React Navigation on the Web",
         "sidebar_label": "Web support"
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -59,6 +59,7 @@
       "drawer-actions",
       "stack-navigator",
       "switch-navigator",
+      "animated-switch-navigator",
       "drawer-navigator",
       "tab-navigator",
       "bottom-tab-navigator",
diff --git a/website/versioned_docs/version-3.x/animated-switch-navigator.md b/website/versioned_docs/version-3.x/animated-switch-navigator.md
@@ -0,0 +1,55 @@
+---
+id: version-3.x-animated-switch-navigator
+title: createAnimatedSwitchNavigator
+sidebar_label: createAnimatedSwitchNavigator
+original_id: animated-switch-navigator
+---
+
+An SwitchNavigator with animation support. 
+
+To use this navigator, you need to install `react-native-reanimated >= 1.0.0`. If you have a managed Expo project, you need to use >= SDK 33 to have the correct version of Reanimated.
+
+## API Definition
+
+```js
+import createAnimatedSwitchNavigator from 'react-navigation-animated-switch';
+
+createAnimatedSwitchNavigator(RouteConfigs, SwitchNavigatorConfig);
+```
+
+## RouteConfigs
+
+The route configs are identical to [createSwitchNavigator](switch-navigator.html)
+
+## SwitchNavigatorConfig
+
+The switch navigator configs are identical to [createSwitchNavigator](switch-navigator.html).
+
+By default, the transition between screens is a cross-fade. You can customize the transition with an additional option `transition`:
+
+```jsx
+import createAnimatedSwitchNavigator from 'react-navigation-animated-switch';
+import { Transition } from 'react-native-reanimated';
+
+const MySwitch = createAnimatedSwitchNavigator(
+  {
+    Home: HomeScreen,
+    Other: OtherScreen,
+  },
+  {
+    // The previous screen will slide to the bottom while the next screen will fade in
+    transition: (
+      <Transition.Together>
+        <Transition.Out
+          type="slide-bottom"
+          durationMs={400}
+          interpolation="easeIn"
+        />
+        <Transition.In type="fade" durationMs={500} />
+      </Transition.Together>
+    ),
+  }
+);
+```
+
+Since the transition are possible thanks to the `Transition` API from `react-native-reanimated`, you can learn more about it [here](https://github.com/kmagiera/react-native-reanimated).
diff --git a/website/versioned_docs/version-3.x/auth-flow.md b/website/versioned_docs/version-3.x/auth-flow.md
@@ -134,4 +134,5 @@ class HomeScreen extends React.Component {
 ```
 <a href="https://snack.expo.io/@react-navigation/auth-flow-v3" target="blank" class="run-code-button">&rarr; Run this code</a>
 
-That's about all there is to it. At the moment, `createSwitchNavigator` doesn't support animating between screens. Let us know if this is important to you [on Canny](https://react-navigation.canny.io/feature-requests).
+That's about all there is to it. To enable animation, you need to use
+[createAnimatedSwitchNavigator](animated-switch-navigator.html) instead.
diff --git a/website/versioned_docs/version-3.x/bottom-tab-navigator.md b/website/versioned_docs/version-3.x/bottom-tab-navigator.md
@@ -112,4 +112,12 @@ Callback to handle press events; the argument is an object containing:
 * `navigation`: navigation prop for the screen
 * `defaultHandler`: the default handler for tab press
 
-Useful for adding a custom logic before the transition to the next scene (the tapped one) starts.
+Useful for adding a custom logic before the transition to the next scene (the
+tapped one) starts.
+
+#### `tabBarOnLongPress`
+
+Callback to handle long press events; the argument is an object containing:
+
+- `navigation`: navigation prop for the screen
+- `defaultHandler`: the default handler for tab press
diff --git a/website/versioned_docs/version-3.x/material-bottom-tab-navigator.md b/website/versioned_docs/version-3.x/material-bottom-tab-navigator.md
@@ -0,0 +1,102 @@
+---
+id: version-3.x-material-bottom-tab-navigator
+title: createMaterialBottomTabNavigator
+sidebar_label: createMaterialBottomTabNavigator
+original_id: material-bottom-tab-navigator
+---
+
+A material-design themed tab bar on the bottom of the screen that lets you switch between different routes. Routes are lazily initialized -- their screen components are not mounted until they are first focused.
+
+<img src="/docs/assets/navigators/bottom-navigation.gif" style="width: 420px; max-width: 100%">
+
+To use this navigator, you need to install `react-navigation-material-bottom-tabs`
+
+```
+npm install react-navigation-material-bottom-tabs react-native-paper
+```
+
+This API also requires that you install `react-native-vector-icons`! If you are using Expo, it will just work out of the box. Otherwise, [follow these installation instructions](https://github.com/oblador/react-native-vector-icons#installation).
+
+To use this tab navigator, import it from `react-navigation-material-bottom-tabs`
+
+```js
+import { createMaterialBottomTabNavigator } from "react-navigation-material-bottom-tabs";
+
+createMaterialBottomTabNavigator(
+  RouteConfigs,
+  MaterialBottomTabNavigatorConfig
+);
+```
+
+This library uses the [`BottomNavigation` component from `react-native-paper`](https://callstack.github.io/react-native-paper/bottom-navigation.html). It doesn't include the whole `react-native-paper` library in your bundle, so you don't need to worry about it.
+
+## RouteConfigs
+
+The route configs object is a mapping from route name to a route config.
+
+## MaterialBottomTabNavigatorConfig
+
+* `shifting` - Whether the shifting style is used, the active tab appears wider and the inactive tabs won't have a label. By default, this is `true` when you have more than 3 tabs.
+* `labeled` - Whether to show labels in tabs. When `false`, only icons will be displayed.
+* `activeColor` - Custom color for icon and label in the active tab.
+* `inactiveColor` - Custom color for icon and label in the inactive tab.
+* `barStyle` - Style for the bottom navigation bar. You can set a bottom padding here if you have a translucent navigation bar on Android: `barStyle={{ paddingBottom: 48 }}`.
+* `initialRouteName` - The routeName for the initial tab route when first loading.
+* `order` - Array of routeNames which defines the order of the tabs.
+* `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
+* `backBehavior` - `initialRoute` to return to initial tab, `order` to return to previous tab, `history` to return to last visited tab, or `none`.
+
+Example:
+
+```js
+export default createMaterialBottomTabNavigator({
+  Album: { screen: Album },
+  Library: { screen: Library },
+  History: { screen: History },
+  Cart: { screen: Cart },
+}, {
+  initialRouteName: 'Album',
+  activeColor: '#f0edf6',
+  inactiveColor: '#3e2465',
+  barStyle: { backgroundColor: '#694fad' },
+});
+```
+
+## `navigationOptions` for screens inside of the navigator
+
+#### `title`
+
+Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.
+
+#### `tabBarIcon`
+
+React Element or a function that given `{ focused: boolean, horizontal: boolean, tintColor: string }` returns a React.Node, to display in the tab bar. `horizontal` is `true` when the device is in landscape and `false` when portrait. The icon is re-rendered whenever the device orientation changes.
+
+#### `tabBarColor`
+
+Color for the tab bar when the tab corresponding to the screen is active. Used for the ripple effect. This is only supported when `shifting` is `true`.
+
+#### `tabBarLabel`
+
+Title string of a tab displayed in the tab bar. When undefined, scene `title` is used. To hide, see `labeled` option in the previous section.
+
+#### `tabBarAccessibilityLabel`
+
+Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.
+
+#### `tabBarTestID`
+
+ID to locate this tab button in tests.
+
+#### `tabBarOnPress`
+
+Callback to handle press events; the argument is an object containing:
+
+* `navigation`: navigation prop for the screen
+* `defaultHandler`: the default handler for tab press
+
+Useful for adding a custom logic before the transition to the next scene (the tapped one) starts.
+
+## Using with `react-native-paper` (optional)
+
+You can use the theming support in `react-native-paper` to customize the material bottom navigation by wrapping your app in [`Provider` from `react-native-paper`](https://callstack.github.io/react-native-paper/getting-started.html). A common use case for this can be to customize the background color for the screens when your app has a dark theme. Follow the [instructions on `react-native-paper`'s documentation](https://callstack.github.io/react-native-paper/theming.html) to learn how to customize the theme.
diff --git a/website/versioned_docs/version-3.x/material-top-tab-navigator.md b/website/versioned_docs/version-3.x/material-top-tab-navigator.md
@@ -95,4 +95,12 @@ Callback to handle press events; the argument is an object containing:
 * `navigation`: navigation prop for the screen
 * `defaultHandler`: the default handler for tab press
 
-Useful for adding a custom logic before the transition to the next scene (the tapped one) starts.
+Useful for adding a custom logic before the transition to the next scene (the
+tapped one) starts.
+
+#### `tabBarOnLongPress`
+
+Callback to handle long press events; the argument is an object containing:
+
+- `navigation`: navigation prop for the screen
+- `defaultHandler`: the default handler for tab press
diff --git a/website/versioned_docs/version-3.x/tab-navigator.md b/website/versioned_docs/version-3.x/tab-navigator.md
@@ -0,0 +1,9 @@
+---
+id: version-3.x-tab-navigator
+title: createTabNavigator
+sidebar_label: createTabNavigator
+original_id: tab-navigator
+---
+
+> Note: `createTabNavigator` is removed in `react-navigation@3.x`. Please use `createBottomTabNavigator` and/or `createMaterialTopTabNavigator` instead.
+
diff --git a/website/versioned_docs/version-3.x/transitioner.md b/website/versioned_docs/version-3.x/transitioner.md
@@ -1,8 +1,8 @@
 ---
 id: version-3.x-transitioner
-original_id: transitioner
 title: Transitioner
 sidebar_label: Transitioner
+original_id: transitioner
 ---
 
 `Transitioner` is a React component that helps manage transitions for complex animated components. It manages the timing of animations and keeps track of various screens as they enter and leave, but it doesn't know what anything looks like, because rendering is entirely deferred to the developer.
diff --git a/website/versioned_sidebars/version-3.x-sidebars.json b/website/versioned_sidebars/version-3.x-sidebars.json
@@ -63,6 +63,7 @@
       "version-3.x-drawer-actions",
       "version-3.x-stack-navigator",
       "version-3.x-switch-navigator",
+      "version-3.x-animated-switch-navigator",
       "version-3.x-drawer-navigator",
       "version-3.x-tab-navigator",
       "version-3.x-bottom-tab-navigator",
