Merge remote-tracking branch 'origin' into images-5

docs/animations.md

@@ -20,11 +20,11 @@ import React, { useState, useEffect } from 'react';
 import { Animated, Text, View } from 'react-native';
 
 const FadeInView = (props) => {
-  const [fadeAdmin] = useState(new Animated.Value(0))  // Initial value for opacity: 0
+  const [fadeAnim] = useState(new Animated.Value(0))  // Initial value for opacity: 0
 
   React.useEffect(() => {
     Animated.timing(
-      fadeAdmin,
+      fadeAnim,
       {
         toValue: 1,
         duration: 10000,
@@ -36,7 +36,7 @@ const FadeInView = (props) => {
     <Animated.View                 // Special animatable View
       style={{
         ...props.style,
-        opacity: fadeAdnim,         // Bind opacity to animated value
+        opacity: fadeAnim,         // Bind opacity to animated value
       }}
     >
       {props.children}

docs/components-and-apis.md

@@ -288,10 +288,4 @@ These components may come in handy for certain applications. For an exhaustive l
       <p>Component to control the app status bar.</p>
     </a>
   </div>
-  <div class="component">
-    <a href="./webview">
-      <h3>WebView</h3>
-      <p>A component that renders web content in a native view.</p>
-    </a>
-  </div>
 </div>

docs/debugging.md

@@ -3,10 +3,6 @@ id: debugging
 title: Debugging
 ---
 
-## Enabling Keyboard Shortcuts
-
-React Native supports a few keyboard shortcuts in the iOS Simulator. They are described below. To enable them, open the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.
-
 ## Accessing the In-App Developer Menu
 
 You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the `⌘D` keyboard shortcut when your app is running in the iOS Simulator, or `⌘M` when running in an Android emulator on Mac OS and `Ctrl+M` on Windows and Linux. Alternatively for Android, you can run the command `adb shell input keyevent 82` to open the dev menu (82 being the Menu key code).
@@ -15,22 +11,13 @@ You can access the developer menu by shaking your device or by selecting "Shake
 
 > The Developer Menu is disabled in release (production) builds.
 
-## Reloading JavaScript
-
-Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press `⌘R` in the iOS Simulator, or tap `R` twice on Android emulators.
+## Enabling Fast Refresh
 
-### Automatic reloading
+Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have [Fast Refresh](fast-refresh.md) enabled.  Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. When enabled, most of your edits should be visible within a second or two.
 
-You can speed up your development times by having your app reload automatically any time your code changes. Automatic reloading can be enabled by selecting "Enable Live Reload" from the Developer Menu.
-
-You may even go a step further and keep your app running as new versions of your files are injected into the JavaScript bundle automatically by enabling [Hot Reloading](https://facebook.github.io/react-native/blog/2016/03/24/introducing-hot-reloading) from the Developer Menu. This will allow you to persist the app's state through reloads.
-
-> There are some instances where hot reloading cannot be implemented perfectly. If you run into any issues, use a full reload to reset your app.
-
-You will need to rebuild your app for changes to take effect in certain situations:
+## Enabling Keyboard Shortcuts
 
-- You have added new resources to your native app's bundle, such as an image in `Images.xcassets` on iOS or the `res/drawable` folder on Android.
-- You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android).
+React Native supports a few keyboard shortcuts in the iOS Simulator. They are described below. To enable them, open the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.
 
 ## In-app Errors and Warnings
 

docs/fast-refresh.md

@@ -0,0 +1,38 @@
+---
+id: fast-refresh
+title: Fast Refresh
+---
+
+Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.
+
+## How It Works
+
+- If you edit a module that **only exports React component(s)**, Fast Refresh will update the code just for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
+- If you edit a module with exports that _aren't_ React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both `Button.js` and `Modal.js` import `Theme.js`, editing `Theme.js` will update both components.
+- Finally, if you **edit a file** that's **imported by modules outside of the React tree**, Fast Refresh **will fall back to doing a full reload**. You might have a file which renders a React component but also exports a value that is imported by a **non-React component**. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.
+
+## Error Resilience
+
+If you make a **syntax error** during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.
+
+If you make a **runtime error during the module initialization** (for example, typing `Style.create` instead of `StyleSheet.create`), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.
+
+If you make a mistake that leads to a **runtime error inside your component**, the Fast Refresh session will _also_ continue after you fix the error. In that case, React will remount your application using the updated code.
+
+If you have [error boundaries](https://reactjs.org/docs/error-boundaries.html) in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be _too_ granular. They are used by React in production, and should always be designed intentionally.
+
+## Limitations
+
+Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:
+
+- Local state is not preserved for class components (only function components and Hooks preserve state).
+- The module you're editing might have _other_ exports in addition to a React component.
+- Sometimes, a module would export the result of calling higher-order component like `createNavigationContainer(MyScreen)`. If the returned component is a class, state will be reset.
+
+In longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.
+
+## Tips
+
+- Fast Refresh preserves React local state in function components (and Hooks) by default.
+- Sometimes you might want to _force_ the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add `// @refresh reset` anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.
+- You can put `console.log` or `debugger;` into the components you edit during a Fast Refresh session.

docs/flatlist.md

@@ -18,76 +18,159 @@ A performant interface for rendering simple, flat lists, supporting the most han
 
 If you need section support, use [`<SectionList>`](sectionlist.md).
 
-Minimal Example:
+### Basic Example:
+
+```SnackPlayer name=flatlist-simple
+import React from 'react';
+import { SafeAreaView, View, FlatList, StyleSheet, Text } from 'react-native';
+import Constants from 'expo-constants';
+
+const DATA = [
+  {
+    id: 'bd7acbea-c1b1-46c2-aed5-3ad53abb28ba',
+    title: 'First Item',
+  },
+  {
+    id: '3ac68afc-c605-48d3-a4f8-fbd91aa97f63',
+    title: 'Second Item',
+  },
+  {
+    id: '58694a0f-3da1-471f-bd96-145571e29d72',
+    title: 'Third Item',
+  },
+];
+
+function Item({ title }) {
+  return (
+    <View style={styles.item}>
+      <Text style={styles.title}>{title}</Text>
+    </View>
+  );
+}
 
-```jsx
-<FlatList
-  data={[{key: 'a'}, {key: 'b'}]}
-  renderItem={({item}) => <Text>{item.key}</Text>}
-/>
+export default function App() {
+  return (
+    <SafeAreaView style={styles.container}>
+      <FlatList
+        data={DATA}
+        renderItem={({ item }) => <Item title={item.title} />}
+        keyExtractor={item => item.id}
+      />
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    marginTop: Constants.statusBarHeight,
+  },
+  item: {
+    backgroundColor: '#f9c2ff',
+    padding: 20,
+    marginVertical: 8,
+    marginHorizontal: 16,
+  },
+  title: {
+    fontSize: 32,
+  },
+});
 ```
 
 To render multiple columns, use the [`numColumns`](flatlist.md#numcolumns) prop. Using this approach instead of a `flexWrap` layout can prevent conflicts with the item height logic.
 
-More complex, multi-select example demonstrating `PureComponent` usage for perf optimization and avoiding bugs.
+More complex, multi-select example demonstrating `` usage for perf optimization and avoiding bugs.
 
-- By binding the `onPressItem` handler, the props will remain `===` and `PureComponent` will prevent wasteful re-renders unless the actual `id`, `selected`, or `title` props change, even if the components rendered in `MyListItem` did not have such optimizations.
-- By passing `extraData={this.state}` to `FlatList` we make sure `FlatList` itself will re-render when the `state.selected` changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is also a `PureComponent` and the prop comparison will not show any changes.
+- By passing `extraData={selected}` to `FlatList` we make sure `FlatList` itself will re-render when the state changes. Without setting this prop, `FlatList` would not know it needs to re-render any items because it is a `PureComponent` and the prop comparison will not show any changes.
 - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property.
 
-```jsx
-class MyListItem extends React.PureComponent {
-  _onPress = () => {
-    this.props.onPressItem(this.props.id);
-  };
-
-  render() {
-    const textColor = this.props.selected ? 'red' : 'black';
-    return (
-      <TouchableOpacity onPress={this._onPress}>
-        <View>
-          <Text style={{color: textColor}}>{this.props.title}</Text>
-        </View>
-      </TouchableOpacity>
-    );
-  }
+```SnackPlayer name=flatlist-selectable
+import React from 'react';
+import {
+  SafeAreaView,
+  TouchableOpacity,
+  FlatList,
+  StyleSheet,
+  Text,
+} from 'react-native';
+import Constants from 'expo-constants';
+
+const DATA = [
+  {
+    id: 'bd7acbea-c1b1-46c2-aed5-3ad53abb28ba',
+    title: 'First Item',
+  },
+  {
+    id: '3ac68afc-c605-48d3-a4f8-fbd91aa97f63',
+    title: 'Second Item',
+  },
+  {
+    id: '58694a0f-3da1-471f-bd96-145571e29d72',
+    title: 'Third Item',
+  },
+];
+
+function Item({ id, title, selected, onSelect }) {
+  return (
+    <TouchableOpacity
+      onPress={() => onSelect(id)}
+      style={[
+        styles.item,
+        { backgroundColor: selected ? '#6e3b6e' : '#f9c2ff' },
+      ]}
+    >
+      <Text style={styles.title}>{title}</Text>
+    </TouchableOpacity>
+  );
 }
 
-class MultiSelectList extends React.PureComponent {
-  state = {selected: (new Map(): Map<string, boolean>)};
-
-  _keyExtractor = (item, index) => item.id;
-
-  _onPressItem = (id: string) => {
-    // updater functions are preferred for transactional updates
-    this.setState((state) => {
-      // copy the map rather than modifying state.
-      const selected = new Map(state.selected);
-      selected.set(id, !selected.get(id)); // toggle
-      return {selected};
-    });
-  };
-
-  _renderItem = ({item}) => (
-    <MyListItem
-      id={item.id}
-      onPressItem={this._onPressItem}
-      selected={!!this.state.selected.get(item.id)}
-      title={item.title}
-    />
+export default function App() {
+  const [selected, setSelected] = React.useState(new Map());
+
+  const onSelect = React.useCallback(
+    id => {
+      const newSelected = new Map(selected);
+      newSelected.set(id, !selected.get(id));
+
+      setSelected(newSelected);
+    },
+    [selected],
   );
 
-  render() {
-    return (
+  return (
+    <SafeAreaView style={styles.container}>
       <FlatList
-        data={this.props.data}
-        extraData={this.state}
-        keyExtractor={this._keyExtractor}
-        renderItem={this._renderItem}
+        data={DATA}
+        renderItem={({ item }) => (
+          <Item
+            id={item.id}
+            title={item.title}
+            selected={!!selected.get(item.id)}
+            onSelect={onSelect}
+          />
+        )}
+        keyExtractor={item => item.id}
+        extraData={selected}
       />
-    );
-  }
+    </SafeAreaView>
+  );
 }
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    marginTop: Constants.statusBarHeight,
+  },
+  item: {
+    backgroundColor: '#f9c2ff',
+    padding: 20,
+    marginVertical: 8,
+    marginHorizontal: 16,
+  },
+  title: {
+    fontSize: 32,
+  },
+});
 ```
 
 This is a convenience wrapper around [`<VirtualizedList>`](virtualizedlist.md), and thus inherits its props (as well as those of [`<ScrollView>`](scrollview.md)) that aren't explicitly listed here, along with the following caveats:

docs/getting-started.md

@@ -91,17 +91,17 @@ The instructions are a bit different depending on your development operating sys
 <div class="toggler">
   <span>Development OS:</span>
   <span role="tablist" id="toggle-os">
-    <button role="tab" class="button-mac" onclick="displayTab('os', 'mac')">macOS</a>
-    <button role="tab" class="button-windows" onclick="displayTab('os', 'windows')">Windows</a>
-    <button role="tab" class="button-linux" onclick="displayTab('os', 'linux')">Linux</a>
+    <button role="tab" class="button-mac" onclick="displayTab('os', 'mac')">macOS</button>
+    <button role="tab" class="button-windows" onclick="displayTab('os', 'windows')">Windows</button>
+    <button role="tab" class="button-linux" onclick="displayTab('os', 'linux')">Linux</button>
   </span>
 </div>
 
 <div class="toggler">
   <span>Target OS:</span>
   <span role="tablist" id="toggle-platform">
-    <button role="tab" class="button-ios" onclick="displayTab('platform', 'ios')">iOS</a>
-    <button role="tab" class="button-android" onclick="displayTab('platform', 'android')">Android</a>
+    <button role="tab" class="button-ios" onclick="displayTab('platform', 'ios')">iOS</button>
+    <button role="tab" class="button-android" onclick="displayTab('platform', 'android')">Android</button>
   </span>
 </div>
 

docs/height-and-width.md

@@ -34,7 +34,7 @@ Use `flex` in a component's style to have the component expand and shrink dynami
 
 > A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed `width` and `height` or `flex`, the parent will have dimensions of 0 and the `flex` children will not be visible.
 
-````SnackPlayer name=Flex%20Dimensions
+```SnackPlayer name=Flex%20Dimensions
 import React, { Component } from 'react';
 import { View } from 'react-native';
 
@@ -55,4 +55,3 @@ export default class FlexDimensionsBasics extends Component {
 ```
 
 After you can control a component's size, the next step is to [learn how to lay it out on the screen](flexbox.md).
-````

docs/hermes.md

@@ -9,7 +9,9 @@ title: Using Hermes
 
 [Hermes](https://hermesengine.dev) is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, simply enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an **opt-in** React Native feature, and this guide explains how to enable it.
 
-First, ensure you're using at least version 0.60.4 of React Native. If you're upgrading an existing app ensure everything works before trying to switch to Hermes.
+First, ensure you're using at least version 0.60.4 of React Native.
+
+If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See [Upgrading to new React Native Versions](/react-native/docs/upgrading) for how to do this. Make especially sure that all changes to `android/app/build.gradle` have been applied, as detailed by the [React Native upgrade helper](https://react-native-community.github.io/upgrade-helper/?from=0.59.0). After upgrading the app, make sure everything works before trying to switch to Hermes.
 
 > ## Note for Windows users.
 >

docs/inputaccessoryview.md

@@ -44,7 +44,7 @@ export default class UselessTextInput extends Component {
 }
 ```
 
-This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a `TextInput` with the `InputAccessoryView` component, and don't set a `nativeID`. For an example, look at [InputAccessoryViewExample.js](https://github.com/facebook/react-native/blob/master/RNTester/js/InputAccessoryViewExample.js).
+This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a `TextInput` with the `InputAccessoryView` component, and don't set a `nativeID`. For an example, look at [InputAccessoryViewExample.js](https://github.com/facebook/react-native/blob/master/RNTester/js/examples/InputAccessoryView/InputAccessoryViewExample.js).
 
 ---