react-native-tvos 0.86.2-0 → 0.87.0-0

package/Libraries/Components/TextInput/TextInput.js

@@ -118,6 +118,7 @@ export type {
   TextInputKeyPressEvent,
   TextInputProps,
   TextInputSelectionChangeEvent,
+  TextInputInstance,
   TextInputSubmitEditingEvent,
 };
 
@@ -244,117 +245,6 @@ function useTextInputStateSynchronization({
   return {setLastNativeSelection, setLastNativeText};
 }
 
-/**
- * A foundational component for inputting text into the app via a
- * keyboard. Props provide configurability for several features, such as
- * auto-correction, auto-capitalization, placeholder text, and different keyboard
- * types, such as a numeric keypad.
- *
- * The simplest use case is to plop down a `TextInput` and subscribe to the
- * `onChangeText` events to read the user input. There are also other events,
- * such as `onSubmitEditing` and `onFocus` that can be subscribed to. A simple
- * example:
- *
- * ```ReactNativeWebPlayer
- * import React, { Component } from 'react';
- * import { AppRegistry, TextInput } from 'react-native';
- *
- * export default class UselessTextInput extends Component {
- *   constructor(props) {
- *     super(props);
- *     this.state = { text: 'Useless Placeholder' };
- *   }
- *
- *   render() {
- *     return (
- *       <TextInput
- *         style={{height: 40, borderColor: 'gray', borderWidth: 1}}
- *         onChangeText={(text) => this.setState({text})}
- *         value={this.state.text}
- *       />
- *     );
- *   }
- * }
- *
- * // skip this line if using Create React Native App
- * AppRegistry.registerComponent('AwesomeProject', () => UselessTextInput);
- * ```
- *
- * Two methods exposed via the native element are .focus() and .blur() that
- * will focus or blur the TextInput programmatically.
- *
- * Note that some props are only available with `multiline={true/false}`.
- * Additionally, border styles that apply to only one side of the element
- * (e.g., `borderBottomColor`, `borderLeftWidth`, etc.) will not be applied if
- * `multiline=false`. To achieve the same effect, you can wrap your `TextInput`
- * in a `View`:
- *
- * ```ReactNativeWebPlayer
- * import React, { Component } from 'react';
- * import { AppRegistry, View, TextInput } from 'react-native';
- *
- * class UselessTextInput extends Component {
- *   render() {
- *     return (
- *       <TextInput
- *         {...this.props} // Inherit any props passed to it; e.g., multiline, numberOfLines below
- *         editable={true}
- *         maxLength={40}
- *       />
- *     );
- *   }
- * }
- *
- * export default class UselessTextInputMultiline extends Component {
- *   constructor(props) {
- *     super(props);
- *     this.state = {
- *       text: 'Useless Multiline Placeholder',
- *     };
- *   }
- *
- *   // If you type something in the text box that is a color, the background will change to that
- *   // color.
- *   render() {
- *     return (
- *      <View style={{
- *        backgroundColor: this.state.text,
- *        borderBottomColor: '#000000',
- *        borderBottomWidth: 1 }}
- *      >
- *        <UselessTextInput
- *          multiline={true}
- *          numberOfLines={4}
- *          onChangeText={(text) => this.setState({text})}
- *          value={this.state.text}
- *        />
- *      </View>
- *     );
- *   }
- * }
- *
- * // skip these lines if using Create React Native App
- * AppRegistry.registerComponent(
- *  'AwesomeProject',
- *  () => UselessTextInputMultiline
- * );
- * ```
- *
- * `TextInput` has by default a border at the bottom of its view. This border
- * has its padding set by the background image provided by the system, and it
- * cannot be changed. Solutions to avoid this is to either not set height
- * explicitly, case in which the system will take care of displaying the border
- * in the correct position, or to not display the border by setting
- * `underlineColorAndroid` to transparent.
- *
- * Note that on Android performing text selection in input can change
- * app's activity `windowSoftInputMode` param to `adjustResize`.
- * This may cause issues with components that have position: 'absolute'
- * while keyboard is active. To avoid this behavior either specify `windowSoftInputMode`
- * in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html )
- * or control this param programmatically with native code.
- *
- */
 function InternalTextInput(props: TextInputProps): React.Node {
   const {
     'aria-busy': ariaBusy,
@@ -906,6 +796,121 @@ const autoCompleteWebToTextContentTypeMap = {
   username: 'username',
 } as const;
 
+/**
+ * A foundational component for inputting text into the app via a
+ * keyboard. Props provide configurability for several features, such as
+ * auto-correction, auto-capitalization, placeholder text, and different keyboard
+ * types, such as a numeric keypad.
+ *
+ * The simplest use case is to plop down a `TextInput` and subscribe to the
+ * `onChangeText` events to read the user input. There are also other events,
+ * such as `onSubmitEditing` and `onFocus` that can be subscribed to.
+ *
+ * Example:
+ *
+ * ```tsx
+ * import React, { Component } from 'react';
+ * import { AppRegistry, TextInput } from 'react-native';
+ *
+ * export default class UselessTextInput extends Component {
+ *   constructor(props) {
+ *     super(props);
+ *     this.state = { text: 'Useless Placeholder' };
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <TextInput
+ *         style={{height: 40, borderColor: 'gray', borderWidth: 1}}
+ *         onChangeText={(text) => this.setState({text})}
+ *         value={this.state.text}
+ *       />
+ *     );
+ *   }
+ * }
+ *
+ * // skip this line if using Create React Native App
+ * AppRegistry.registerComponent('AwesomeProject', () => UselessTextInput);
+ * ```
+ *
+ * Two methods exposed via the native element are .focus() and .blur() that
+ * will focus or blur the TextInput programmatically.
+ *
+ * Note that some props are only available with `multiline={true/false}`.
+ * Additionally, border styles that apply to only one side of the element
+ * (e.g., `borderBottomColor`, `borderLeftWidth`, etc.) will not be applied if
+ * `multiline=false`. To achieve the same effect, you can wrap your `TextInput`
+ * in a `View`:
+ *
+ * Example:
+ *
+ * ```tsx
+ * import React, { Component } from 'react';
+ * import { AppRegistry, View, TextInput } from 'react-native';
+ *
+ * class UselessTextInput extends Component {
+ *   render() {
+ *     return (
+ *       <TextInput
+ *         {...this.props} // Inherit any props passed to it; e.g., multiline, numberOfLines below
+ *         editable={true}
+ *         maxLength={40}
+ *       />
+ *     );
+ *   }
+ * }
+ *
+ * export default class UselessTextInputMultiline extends Component {
+ *   constructor(props) {
+ *     super(props);
+ *     this.state = {
+ *       text: 'Useless Multiline Placeholder',
+ *     };
+ *   }
+ *
+ *   // If you type something in the text box that is a color, the background will change to that
+ *   // color.
+ *   render() {
+ *     return (
+ *      <View style={{
+ *        backgroundColor: this.state.text,
+ *        borderBottomColor: '#000000',
+ *        borderBottomWidth: 1 }}
+ *      >
+ *        <UselessTextInput
+ *          multiline={true}
+ *          numberOfLines={4}
+ *          onChangeText={(text) => this.setState({text})}
+ *          value={this.state.text}
+ *        />
+ *      </View>
+ *     );
+ *   }
+ * }
+ *
+ * // skip these lines if using Create React Native App
+ * AppRegistry.registerComponent(
+ *  'AwesomeProject',
+ *  () => UselessTextInputMultiline
+ * );
+ * ```
+ *
+ * `TextInput` has by default a border at the bottom of its view. This border
+ * has its padding set by the background image provided by the system, and it
+ * cannot be changed. Solutions to avoid this is to either not set height
+ * explicitly, case in which the system will take care of displaying the border
+ * in the correct position, or to not display the border by setting
+ * `underlineColorAndroid` to transparent.
+ *
+ * Note that on Android performing text selection in input can change
+ * app's activity `windowSoftInputMode` param to `adjustResize`.
+ * This may cause issues with components that have position: 'absolute'
+ * while keyboard is active. To avoid this behavior either specify `windowSoftInputMode`
+ * in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html )
+ * or control this param programmatically with native code.
+ *
+ * @see https://reactnative.dev/docs/textinput
+ */
 const TextInput: component(
   ref?: React.RefSetter<TextInputInstance>,
   ...props: React.ElementConfig<typeof InternalTextInput>

package/Libraries/Components/TextInput/TextInputNativeCommands.js

@@ -13,9 +13,9 @@ import type {Int32} from '../../Types/CodegenTypes';
 import * as React from 'react';
 
 export interface TextInputNativeCommands<T> {
-  +focus: (viewRef: React.ElementRef<T>) => void;
-  +blur: (viewRef: React.ElementRef<T>) => void;
-  +setTextAndSelection: (
+  readonly focus: (viewRef: React.ElementRef<T>) => void;
+  readonly blur: (viewRef: React.ElementRef<T>) => void;
+  readonly setTextAndSelection: (
     viewRef: React.ElementRef<T>,
     mostRecentEventCount: Int32,
     value: ?string, // in theory this is nullable

package/Libraries/Components/ToastAndroid/ToastAndroid.android.js

@@ -11,41 +11,43 @@
 import NativeToastAndroid from './NativeToastAndroid';
 
 /**
- * This exposes the native ToastAndroid module as a JS module. This has a function 'show'
- * which takes the following parameters:
+ * Displays Android toast messages.
  *
- * 1. String message: A string with the text to toast
- * 2. int duration: The duration of the toast. May be ToastAndroid.SHORT or ToastAndroid.LONG
- *
- * There is also a function `showWithGravity` to specify the layout gravity. May be
- * ToastAndroid.TOP, ToastAndroid.BOTTOM, ToastAndroid.CENTER.
- *
- * The 'showWithGravityAndOffset' function adds on the ability to specify offset
- * These offset values will translate to pixels.
- *
- * Basic usage:
- * ```javascript
- * ToastAndroid.show('A pikachu appeared nearby !', ToastAndroid.SHORT);
- * ToastAndroid.showWithGravity('All Your Base Are Belong To Us', ToastAndroid.SHORT, ToastAndroid.CENTER);
- * ToastAndroid.showWithGravityAndOffset('A wild toast appeared!', ToastAndroid.LONG, ToastAndroid.BOTTOM, 25, 50);
- * ```
+ * @see https://reactnative.dev/docs/toastandroid
+ * @platform android
  */
 
 const ToastAndroidConstants = NativeToastAndroid.getConstants();
 
 const ToastAndroid = {
-  // Toast duration constants
+  /** Toast duration constant for a short display time. */
   SHORT: ToastAndroidConstants.SHORT as number,
+
+  /** Toast duration constant for a long display time. */
   LONG: ToastAndroidConstants.LONG as number,
-  // Toast gravity constants
+
+  /** Toast gravity constant for top positioning. */
   TOP: ToastAndroidConstants.TOP as number,
+
+  /** Toast gravity constant for bottom positioning. */
   BOTTOM: ToastAndroidConstants.BOTTOM as number,
+
+  /** Toast gravity constant for center positioning. */
   CENTER: ToastAndroidConstants.CENTER as number,
 
+  /**
+   * Show a toast with the given message and duration (`ToastAndroid.SHORT` or
+   * `ToastAndroid.LONG`).
+   */
   show: function (message: string, duration: number): void {
     NativeToastAndroid.show(message, duration);
   },
 
+  /**
+   * Show a toast at a specified gravity position (`ToastAndroid.TOP`,
+   * `ToastAndroid.BOTTOM`, or `ToastAndroid.CENTER`). Only works on API 29
+   * and below.
+   */
   showWithGravity: function (
     message: string,
     duration: number,
@@ -54,6 +56,10 @@ const ToastAndroid = {
     NativeToastAndroid.showWithGravity(message, duration, gravity);
   },
 
+  /**
+   * Show a toast at a specified gravity position with additional pixel
+   * offsets. Only works on API 29 and below.
+   */
   showWithGravityAndOffset: function (
     message: string,
     duration: number,

package/Libraries/Components/Touchable/Touchable.d.ts

@@ -32,7 +32,7 @@ export const Touchable: {
 };
 
 /**
- * @see https://github.com/react/react-native/blob/0.34-stable\Libraries\Components\Touchable\Touchable.js
+ * @see https://github.com/facebook/react-native/blob/0.34-stable\Libraries\Components\Touchable\Touchable.js
  */
 interface TouchableMixin {
   /**

package/Libraries/Components/Touchable/Touchable.js

@@ -25,16 +25,16 @@ import Position from './Position';
 import * as React from 'react';
 
 const extractSingleTouch = (nativeEvent: {
-  +changedTouches: ReadonlyArray<GestureResponderEvent['nativeEvent']>,
-  +force?: number,
-  +identifier: number,
-  +locationX: number,
-  +locationY: number,
-  +pageX: number,
-  +pageY: number,
-  +target: ?number,
-  +timestamp: number,
-  +touches: ReadonlyArray<GestureResponderEvent['nativeEvent']>,
+  readonly changedTouches: ReadonlyArray<GestureResponderEvent['nativeEvent']>,
+  readonly force?: number,
+  readonly identifier: number,
+  readonly locationX: number,
+  readonly locationY: number,
+  readonly pageX: number,
+  readonly pageY: number,
+  readonly target: ?number,
+  readonly timestamp: number,
+  readonly touches: ReadonlyArray<GestureResponderEvent['nativeEvent']>,
 }) => {
   const touches = nativeEvent.touches;
   const changedTouches = nativeEvent.changedTouches;
@@ -48,91 +48,6 @@ const extractSingleTouch = (nativeEvent: {
       : nativeEvent;
 };
 
-/**
- * `Touchable`: Taps done right.
- *
- * You hook your `ResponderEventPlugin` events into `Touchable`. `Touchable`
- * will measure time/geometry and tells you when to give feedback to the user.
- *
- * ====================== Touchable Tutorial ===============================
- * The `Touchable` mixin helps you handle the "press" interaction. It analyzes
- * the geometry of elements, and observes when another responder (scroll view
- * etc) has stolen the touch lock. It notifies your component when it should
- * give feedback to the user. (bouncing/highlighting/unhighlighting).
- *
- * - When a touch was activated (typically you highlight)
- * - When a touch was deactivated (typically you unhighlight)
- * - When a touch was "pressed" - a touch ended while still within the geometry
- *   of the element, and no other element (like scroller) has "stolen" touch
- *   lock ("responder") (Typically you bounce the element).
- *
- * A good tap interaction isn't as simple as you might think. There should be a
- * slight delay before showing a highlight when starting a touch. If a
- * subsequent touch move exceeds the boundary of the element, it should
- * unhighlight, but if that same touch is brought back within the boundary, it
- * should rehighlight again. A touch can move in and out of that boundary
- * several times, each time toggling highlighting, but a "press" is only
- * triggered if that touch ends while within the element's boundary and no
- * scroller (or anything else) has stolen the lock on touches.
- *
- * To create a new type of component that handles interaction using the
- * `Touchable` mixin, do the following:
- *
- * - Initialize the `Touchable` state.
- *
- *   getInitialState: function() {
- *     return merge(this.touchableGetInitialState(), yourComponentState);
- *   }
- *
- * - Choose the rendered component who's touches should start the interactive
- *   sequence. On that rendered node, forward all `Touchable` responder
- *   handlers. You can choose any rendered node you like. Choose a node whose
- *   hit target you'd like to instigate the interaction sequence:
- *
- *   // In render function:
- *   return (
- *     <View
- *       onStartShouldSetResponder={this.touchableHandleStartShouldSetResponder}
- *       onResponderTerminationRequest={this.touchableHandleResponderTerminationRequest}
- *       onResponderGrant={this.touchableHandleResponderGrant}
- *       onResponderMove={this.touchableHandleResponderMove}
- *       onResponderRelease={this.touchableHandleResponderRelease}
- *       onResponderTerminate={this.touchableHandleResponderTerminate}>
- *       <View>
- *         Even though the hit detection/interactions are triggered by the
- *         wrapping (typically larger) node, we usually end up implementing
- *         custom logic that highlights this inner one.
- *       </View>
- *     </View>
- *   );
- *
- * - You may set up your own handlers for each of these events, so long as you
- *   also invoke the `touchable*` handlers inside of your custom handler.
- *
- * - Implement the handlers on your component class in order to provide
- *   feedback to the user. See documentation for each of these class methods
- *   that you should implement.
- *
- *   touchableHandlePress: function() {
- *      this.performBounceAnimation();  // or whatever you want to do.
- *   },
- *   touchableHandleActivePressIn: function() {
- *     this.beginHighlighting(...);  // Whatever you like to convey activation
- *   },
- *   touchableHandleActivePressOut: function() {
- *     this.endHighlighting(...);  // Whatever you like to convey deactivation
- *   },
- *
- * - There are more advanced methods you can implement (see documentation below):
- *   touchableGetHighlightDelayMS: function() {
- *     return 20;
- *   }
- *   // In practice, *always* use a predeclared constant (conserve memory).
- *   touchableGetPressRectOffset: function() {
- *     return {top: 20, left: 20, right: 20, bottom: 100};
- *   }
- */
-
 /**
  * Touchable states.
  */
@@ -947,6 +862,90 @@ const {
 TouchableMixinImpl.withoutDefaultFocusAndBlur =
   TouchableMixinWithoutDefaultFocusAndBlur;
 
+/**
+ * `Touchable`: Taps done right.
+ *
+ * You hook your `ResponderEventPlugin` events into `Touchable`. `Touchable`
+ * will measure time/geometry and tells you when to give feedback to the user.
+ *
+ * ====================== Touchable Tutorial ===============================
+ * The `Touchable` mixin helps you handle the "press" interaction. It analyzes
+ * the geometry of elements, and observes when another responder (scroll view
+ * etc) has stolen the touch lock. It notifies your component when it should
+ * give feedback to the user. (bouncing/highlighting/unhighlighting).
+ *
+ * - When a touch was activated (typically you highlight)
+ * - When a touch was deactivated (typically you unhighlight)
+ * - When a touch was "pressed" - a touch ended while still within the geometry
+ *   of the element, and no other element (like scroller) has "stolen" touch
+ *   lock ("responder") (Typically you bounce the element).
+ *
+ * A good tap interaction isn't as simple as you might think. There should be a
+ * slight delay before showing a highlight when starting a touch. If a
+ * subsequent touch move exceeds the boundary of the element, it should
+ * unhighlight, but if that same touch is brought back within the boundary, it
+ * should rehighlight again. A touch can move in and out of that boundary
+ * several times, each time toggling highlighting, but a "press" is only
+ * triggered if that touch ends while within the element's boundary and no
+ * scroller (or anything else) has stolen the lock on touches.
+ *
+ * To create a new type of component that handles interaction using the
+ * `Touchable` mixin, do the following:
+ *
+ * - Initialize the `Touchable` state.
+ *
+ *   getInitialState: function() {
+ *     return merge(this.touchableGetInitialState(), yourComponentState);
+ *   }
+ *
+ * - Choose the rendered component who's touches should start the interactive
+ *   sequence. On that rendered node, forward all `Touchable` responder
+ *   handlers. You can choose any rendered node you like. Choose a node whose
+ *   hit target you'd like to instigate the interaction sequence:
+ *
+ *   // In render function:
+ *   return (
+ *     <View
+ *       onStartShouldSetResponder={this.touchableHandleStartShouldSetResponder}
+ *       onResponderTerminationRequest={this.touchableHandleResponderTerminationRequest}
+ *       onResponderGrant={this.touchableHandleResponderGrant}
+ *       onResponderMove={this.touchableHandleResponderMove}
+ *       onResponderRelease={this.touchableHandleResponderRelease}
+ *       onResponderTerminate={this.touchableHandleResponderTerminate}>
+ *       <View>
+ *         Even though the hit detection/interactions are triggered by the
+ *         wrapping (typically larger) node, we usually end up implementing
+ *         custom logic that highlights this inner one.
+ *       </View>
+ *     </View>
+ *   );
+ *
+ * - You may set up your own handlers for each of these events, so long as you
+ *   also invoke the `touchable*` handlers inside of your custom handler.
+ *
+ * - Implement the handlers on your component class in order to provide
+ *   feedback to the user. See documentation for each of these class methods
+ *   that you should implement.
+ *
+ *   touchableHandlePress: function() {
+ *      this.performBounceAnimation();  // or whatever you want to do.
+ *   },
+ *   touchableHandleActivePressIn: function() {
+ *     this.beginHighlighting(...);  // Whatever you like to convey activation
+ *   },
+ *   touchableHandleActivePressOut: function() {
+ *     this.endHighlighting(...);  // Whatever you like to convey deactivation
+ *   },
+ *
+ * - There are more advanced methods you can implement (see documentation below):
+ *   touchableGetHighlightDelayMS: function() {
+ *     return 20;
+ *   }
+ *   // In practice, *always* use a predeclared constant (conserve memory).
+ *   touchableGetPressRectOffset: function() {
+ *     return {top: 20, left: 20, right: 20, bottom: 100};
+ *   }
+ */
 const TouchableImpl = {
   Mixin: TouchableMixinImpl,
   /**