react-native-tvos 0.86.0-2 → 0.87.0-0

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.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,
   /**

package/Libraries/Components/Touchable/TouchableHighlight.js

@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ColorValue} from '../../StyleSheet/StyleSheet';
 import type {TVViewProps} from '../TV/TVViewPropTypes';
 import type {AccessibilityState} from '../View/ViewAccessibility';
@@ -20,36 +21,44 @@ import Pressability, {
 import {PressabilityDebugView} from '../../Pressability/PressabilityDebug';
 import StyleSheet, {type ViewStyleProp} from '../../StyleSheet/StyleSheet';
 import Platform from '../../Utilities/Platform';
+import warnOnce from '../../Utilities/warnOnce';
 import tagForComponentOrHandle from '../TV/tagForComponentOrHandle';
 import * as React from 'react';
 import {cloneElement} from 'react';
 
+export type TouchableHighlightInstance = HostInstance;
+
 type TouchableHighlightBaseProps = Readonly<{
   /**
-   * Determines what the opacity of the wrapped view should be when touch is active.
+   * Opacity of the wrapped view when touch is active. Requires `underlayColor` to be set.
+   *
+   * @default `0.85`
    */
   activeOpacity?: ?number,
+
   /**
-   * The color of the underlay that will show through when the touch is active.
+   * Color of the underlay shown when touch is active.
    */
   underlayColor?: ?ColorValue,
-  /**
-   * @see https://reactnative.dev/docs/view#style
-   */
+
   style?: ?ViewStyleProp,
+
   /**
-   * Called immediately after the underlay is shown
+   * Called immediately after the underlay is shown.
    */
   onShowUnderlay?: ?() => void,
+
   /**
-   * Called immediately after the underlay is hidden
+   * Called immediately after the underlay is hidden.
    */
   onHideUnderlay?: ?() => void,
+
   testOnly_pressed?: ?boolean,
 
-  hostRef?: React.RefSetter<React.ElementRef<typeof View>>,
+  hostRef?: React.RefSetter<TouchableHighlightInstance>,
 }>;
 
+/** @build-types emit-as-interface Uniwind compatibility */
 export type TouchableHighlightProps = Readonly<{
   ...TouchableWithoutFeedbackProps,
   ...TVViewProps,
@@ -66,102 +75,6 @@ type TouchableHighlightState = Readonly<{
   extraStyles: ?ExtraStyles,
 }>;
 
-/**
- * A wrapper for making views respond properly to touches.
- * On press down, the opacity of the wrapped view is decreased, which allows
- * the underlay color to show through, darkening or tinting the view.
- *
- * The underlay comes from wrapping the child in a new View, which can affect
- * layout, and sometimes cause unwanted visual artifacts if not used correctly,
- * for example if the backgroundColor of the wrapped view isn't explicitly set
- * to an opaque color.
- *
- * TouchableHighlight must have one child (not zero or more than one).
- * If you wish to have several child components, wrap them in a View.
- *
- * Example:
- *
- * ```
- * renderButton: function() {
- *   return (
- *     <TouchableHighlight onPress={this._onPressButton}>
- *       <Image
- *         style={styles.button}
- *         source={require('./myButton.png')}
- *       />
- *     </TouchableHighlight>
- *   );
- * },
- * ```
- *
- *
- * ### Example
- *
- * ```ReactNativeWebPlayer
- * import React, { Component } from 'react'
- * import {
- *   AppRegistry,
- *   StyleSheet,
- *   TouchableHighlight,
- *   Text,
- *   View,
- * } from 'react-native'
- *
- * class App extends Component {
- *   constructor(props) {
- *     super(props)
- *     this.state = { count: 0 }
- *   }
- *
- *   onPress = () => {
- *     this.setState({
- *       count: this.state.count+1
- *     })
- *   }
- *
- *  render() {
- *     return (
- *       <View style={styles.container}>
- *         <TouchableHighlight
- *          style={styles.button}
- *          onPress={this.onPress}
- *         >
- *          <Text> Touch Here </Text>
- *         </TouchableHighlight>
- *         <View style={[styles.countContainer]}>
- *           <Text style={[styles.countText]}>
- *             { this.state.count !== 0 ? this.state.count: null}
- *           </Text>
- *         </View>
- *       </View>
- *     )
- *   }
- * }
- *
- * const styles = StyleSheet.create({
- *   container: {
- *     flex: 1,
- *     justifyContent: 'center',
- *     paddingHorizontal: 10
- *   },
- *   button: {
- *     alignItems: 'center',
- *     backgroundColor: '#DDDDDD',
- *     padding: 10
- *   },
- *   countContainer: {
- *     alignItems: 'center',
- *     padding: 10
- *   },
- *   countText: {
- *     color: '#FF00FF'
- *   }
- * })
- *
- * AppRegistry.registerComponent('App', () => App)
- * ```
- *
- */
 class TouchableHighlightImpl extends React.Component<
   TouchableHighlightProps,
   TouchableHighlightState,
@@ -294,6 +207,13 @@ class TouchableHighlightImpl extends React.Component<
 
   render(): React.Node {
     const child = React.Children.only<$FlowFixMe>(this.props.children);
+    if (__DEV__ && child.type === React.Fragment) {
+      warnOnce(
+        'TouchableHighlight-fragment',
+        'TouchableHighlight does not support React.Fragment as a child. ' +
+          'Wrap the children in a single host element such as <View>.',
+      );
+    }
 
     // BACKWARD-COMPATIBILITY: Focus and blur events were never supported before
     // adopting `Pressability`, so preserve that behavior.
@@ -352,8 +272,7 @@ class TouchableHighlightImpl extends React.Component<
         hitSlop={this.props.hitSlop}
         hasTVPreferredFocus={this.props.hasTVPreferredFocus === true}
         focusable={
-          this.props.focusable !== false &&
-          this.props.isTVSelectable !== false
+          this.props.focusable !== false && this.props.isTVSelectable !== false
         }
         tvParallaxProperties={this.props.tvParallaxProperties}
         nextFocusDown={tagForComponentOrHandle(this.props.nextFocusDown)}
@@ -365,12 +284,14 @@ class TouchableHighlightImpl extends React.Component<
         testID={this.props.testID}
         ref={this.props.hostRef}
         {...eventHandlers}>
-        {cloneElement(child, {
-          style: StyleSheet.compose(
-            child.props.style,
-            this.state.extraStyles?.child,
-          ),
-        })}
+        {child.type === React.Fragment
+          ? child
+          : cloneElement(child, {
+              style: StyleSheet.compose(
+                child.props.style,
+                this.state.extraStyles?.child,
+              ),
+            })}
         {__DEV__ ? (
           <PressabilityDebugView color="green" hitSlop={this.props.hitSlop} />
         ) : null}
@@ -399,14 +320,25 @@ class TouchableHighlightImpl extends React.Component<
   }
 }
 
+/**
+ * A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, which allows the underlay color to show through, darkening or tinting the view.
+ *
+ * The underlay comes from wrapping the child in a new View, which can affect layout.
+ *
+ * Must have exactly one child (not zero or more than one). If you wish to have several child components, wrap them in a View.
+ *
+ * If you need more extensive and future-proof touch handling, use `Pressable`.
+ *
+ * @see https://reactnative.dev/docs/touchablehighlight
+ */
 const TouchableHighlight: component(
-  ref?: React.RefSetter<React.ElementRef<typeof View>>,
+  ref?: React.RefSetter<TouchableHighlightInstance>,
   ...props: Readonly<Omit<TouchableHighlightProps, 'hostRef'>>
 ) = ({
   ref: hostRef,
   ...props
 }: {
-  ref?: React.RefSetter<React.ElementRef<typeof View>>,
+  ref?: React.RefSetter<TouchableHighlightInstance>,
   ...Readonly<Omit<TouchableHighlightProps, 'hostRef'>>,
 }) => <TouchableHighlightImpl {...props} hostRef={hostRef} />;
 

package/Libraries/Components/Touchable/TouchableNativeFeedback.js

@@ -31,18 +31,11 @@ export type TouchableNativeFeedbackProps = Readonly<{
   ...TouchableWithoutFeedbackProps,
   ...TVViewProps,
   /**
-   * Determines the type of background drawable that's going to be used to display feedback.
-   * It takes an object with type property and extra data depending on the type.
-   * It's recommended to use one of the following static methods to generate that dictionary:
-   *      1) TouchableNativeFeedback.SelectableBackground() - will create object that represents android theme's
-   *         default background for selectable elements (?android:attr/selectableItemBackground)
-   *      2) TouchableNativeFeedback.SelectableBackgroundBorderless() - will create object that represent android
-   *         theme's default background for borderless selectable elements
-   *         (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+
-   *      3) TouchableNativeFeedback.Ripple(color, borderless) - will create object that represents ripple drawable
-   *         with specified color (as a string). If property borderless evaluates to true the ripple will render
-   *         outside of the view bounds (see native actionbar buttons as an example of that behavior). This background
-   *         type is available on Android API level 21+
+   * Determines the type of background drawable used to display touch feedback. Use one of the static methods to generate this value:
+   *
+   * - `TouchableNativeFeedback.SelectableBackground()` - Default background for selectable elements.
+   * - `TouchableNativeFeedback.SelectableBackgroundBorderless()` - Default background for borderless selectable elements. API 21+.
+   * - `TouchableNativeFeedback.Ripple(color, borderless)` - Ripple drawable with the specified color.
    */
   background?: ?(
     | Readonly<{
@@ -60,14 +53,9 @@ export type TouchableNativeFeedbackProps = Readonly<{
       }>
   ),
   /**
-   * Set to true to add the ripple effect to the foreground of the view, instead
-   * of the background. This is useful if one of your child views has a
-   * background of its own, or you're e.g. displaying images, and you don't want
-   * the ripple to be covered by them.
+   * If `true`, adds the ripple effect to the foreground of the view instead of the background. Useful if a child view has its own background, or you are displaying images.
    *
-   * Check TouchableNativeFeedback.canUseNativeForeground() first, as this is
-   * only available on Android 6.0 and above. If you try to use this on older
-   * versions, this will fallback to background.
+   * Check `TouchableNativeFeedback.canUseNativeForeground()` first, as this is only available on Android 6.0 and above. On older versions, this falls back to background.
    */
   useForeground?: ?boolean,
 }>;
@@ -77,14 +65,12 @@ type TouchableNativeFeedbackState = Readonly<{
 }>;
 
 /**
- * A wrapper for making views respond properly to touches (Android only).
- * On Android this component uses native state drawable to display touch feedback.
- * At the moment it only supports having a single View instance as a child node,
- * as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.
+ * A wrapper for making views respond properly to touches (Android only). Uses native state drawable to display touch feedback.
  *
- * Background drawable of native feedback touchable can be customized with background property.
+ * Supports only a single View instance as a child. If you need more extensive and future-proof touch handling, use `Pressable`.
  *
- * @see https://reactnative.dev/docs/touchablenativefeedback#content
+ * @see https://reactnative.dev/docs/touchablenativefeedback
+ * @platform android
  */
 class TouchableNativeFeedback extends React.Component<
   TouchableNativeFeedbackProps,
@@ -365,4 +351,6 @@ const getBackgroundProp =
 
 TouchableNativeFeedback.displayName = 'TouchableNativeFeedback';
 
+export type TouchableNativeFeedbackInstance = TouchableNativeFeedback;
+
 export default TouchableNativeFeedback;