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

package/Libraries/ActionSheetIOS/ActionSheetIOS.js

@@ -38,6 +38,10 @@ export type ShareActionSheetIOSOptions = Readonly<{
   tintColor?: ?number,
   cancelButtonTintColor?: ?number,
   disabledButtonTintColor?: ?number,
+  /**
+   * The activities to exclude from the ActionSheet.
+   * For example: ['com.apple.UIKit.activity.PostToTwitter']
+   */
   excludedActivityTypes?: ?Array<string>,
   userInterfaceStyle?: ?string,
 }>;
@@ -50,9 +54,10 @@ export type ShareActionSheetError = Readonly<{
 }>;
 
 /**
- * Display action sheets and share sheets on iOS.
+ * Displays native iOS action sheets and share sheets.
  *
- * See https://reactnative.dev/docs/actionsheetios
+ * @see https://reactnative.dev/docs/actionsheetios
+ * @platform ios
  */
 const ActionSheetIOS = {
   /**
@@ -62,15 +67,13 @@ const ActionSheetIOS = {
    *
    * - `options` (array of strings) - a list of button titles (required)
    * - `cancelButtonIndex` (int) - index of cancel button in `options`
-   * - `destructiveButtonIndex` (int or array of ints) - index or indices of destructive buttons in `options`
+   * - `destructiveButtonIndex` (int or array of ints) - indices of destructive buttons in `options`
    * - `title` (string) - a title to show above the action sheet
    * - `message` (string) - a message to show below the title
    * - `disabledButtonIndices` (array of numbers) - a list of button indices which should be disabled
    *
-   * The 'callback' function takes one parameter, the zero-based index
-   * of the selected item.
-   *
-   * See https://reactnative.dev/docs/actionsheetios#showactionsheetwithoptions
+   * The `callback` function receives the zero-based index of the selected
+   * item.
    */
   showActionSheetWithOptions(
     options: ActionSheetIOSOptions,
@@ -136,27 +139,19 @@ const ActionSheetIOS = {
   },
 
   /**
-   * Display the iOS share sheet. The `options` object should contain
-   * one or both of `message` and `url` and can additionally have
-   * a `subject` or `excludedActivityTypes`:
+   * Display the iOS share sheet. The `options` object should contain one or
+   * both of `message` and `url` and can additionally have a `subject` or
+   * `excludedActivityTypes`:
    *
    * - `url` (string) - a URL to share
    * - `message` (string) - a message to share
    * - `subject` (string) - a subject for the message
-   * - `excludedActivityTypes` (array) - the activities to exclude from
-   *   the ActionSheet
+   * - `excludedActivityTypes` (array) - the activities to exclude from the ActionSheet
    * - `tintColor` (color) - tint color of the buttons
    *
-   * The 'failureCallback' function takes one parameter, an error object.
-   * The only property defined on this object is an optional `stack` property
-   * of type `string`.
-   *
-   * The 'successCallback' function takes two parameters:
-   *
-   * - a boolean value signifying success or failure
-   * - a string that, in the case of success, indicates the method of sharing
-   *
-   * See https://reactnative.dev/docs/actionsheetios#showshareactionsheetwithoptions
+   * The `failureCallback` function receives an error object. The
+   * `successCallback` function receives a boolean indicating success and a
+   * string describing the sharing method used.
    */
   showShareActionSheetWithOptions(
     options: ShareActionSheetIOSOptions,
@@ -186,8 +181,8 @@ const ActionSheetIOS = {
   },
 
   /**
-   * Dismisses the most upper iOS action sheet presented, if no action sheet is
-   * present a warning is displayed.
+   * Dismiss the most upper action sheet currently presented. Displays a
+   * warning if no action sheet is present.
    */
   dismissActionSheet: () => {
     invariant(RCTActionSheetManager, "ActionSheetManager doesn't exist");

package/Libraries/Alert/Alert.js

@@ -57,9 +57,43 @@ export type AlertOptions = {
  * alerts. On iOS, you can show an alert that prompts the user to enter
  * some information.
  *
- * See https://reactnative.dev/docs/alert
+ * ## iOS
+ *
+ * On iOS you can specify any number of buttons. Each button can optionally
+ * specify a style, which is one of 'default', 'cancel' or 'destructive'.
+ *
+ * ## Android
+ *
+ * On Android at most three buttons can be specified. Android has a concept
+ * of a neutral, negative and a positive button:
+ *
+ *   - If you specify one button, it will be the 'positive' one (such as 'OK')
+ *   - Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
+ *   - Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
+ *
+ * Example:
+ *
+ * ```tsx
+ * // Works on both iOS and Android
+ * Alert.alert(
+ *   'Alert Title',
+ *   'My Alert Msg',
+ *   [
+ *     {text: 'Ask me later', onPress: () => console.log('Ask me later pressed')},
+ *     {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
+ *     {text: 'OK', onPress: () => console.log('OK Pressed')},
+ *   ]
+ * )
+ * ```
+ *
+ * @see https://reactnative.dev/docs/alert
  */
 class Alert {
+  /**
+   * Display an alert dialog with the specified title, message, and buttons.
+   * On Android, at most three buttons can be specified. On iOS, any number of
+   * buttons can be used.
+   */
   static alert(
     title: ?string,
     message?: ?string,
@@ -140,6 +174,9 @@ class Alert {
   }
 
   /**
+   * Create and display a prompt to enter text. Accepts a title, message,
+   * callback or buttons, input type, default value, keyboard type, and options.
+   *
    * @platform ios
    */
   static prompt(

package/Libraries/Animated/AnimatedExports.js

@@ -24,21 +24,43 @@ const Animated: typeof AnimatedImplementation = Platform.isDisableAnimations
   : AnimatedImplementation;
 
 export default {
+  /**
+   * FlatList and SectionList infer generic Type defined under their `data` and `section` props.
+   */
   get FlatList(): AnimatedFlatList<any> {
     return require('./components/AnimatedFlatList').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get Image(): AnimatedImage {
     return require('./components/AnimatedImage').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get ScrollView(): AnimatedScrollView {
     return require('./components/AnimatedScrollView').default;
   },
+  /**
+   * FlatList and SectionList infer generic Type defined under their `data` and `section` props.
+   */
   get SectionList(): AnimatedSectionList<any, any> {
     return require('./components/AnimatedSectionList').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get Text(): AnimatedText {
     return require('./components/AnimatedText').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get View(): AnimatedView {
     return require('./components/AnimatedView').default;
   },

package/Libraries/Animated/AnimatedExports.js.flow

@@ -10,7 +10,7 @@
 
 import AnimatedImplementation from './AnimatedImplementation';
 
-export type {CompositeAnimation} from './AnimatedImplementation';
+export type {CompositeAnimation, Numeric} from './AnimatedImplementation';
 export type {DecayAnimationConfig} from './animations/DecayAnimation';
 export type {SpringAnimationConfig} from './animations/SpringAnimation';
 export type {TimingAnimationConfig} from './animations/TimingAnimation';

package/Libraries/Animated/AnimatedImplementation.js

@@ -20,6 +20,7 @@ import type {DecayAnimationConfig} from './animations/DecayAnimation';
 import type {SpringAnimationConfig} from './animations/SpringAnimation';
 import type {TimingAnimationConfig} from './animations/TimingAnimation';
 
+import NativeAnimatedHelper from '../../src/private/animated/NativeAnimatedHelper';
 import {AnimatedEvent, attachNativeEventImpl} from './AnimatedEvent';
 import DecayAnimation from './animations/DecayAnimation';
 import SpringAnimation from './animations/SpringAnimation';
@@ -39,8 +40,29 @@ import AnimatedValue from './nodes/AnimatedValue';
 import AnimatedValueXY from './nodes/AnimatedValueXY';
 
 export type CompositeAnimation = {
+  /**
+   * Animations are started by calling start() on your animation.
+   * start() takes a completion callback that will be called when the
+   * animation is done or when the animation is done because stop() was
+   * called on it before it could finish.
+   *
+   * @param callback - Optional function that will be called
+   *      after the animation finished running normally or when the animation
+   *      is done because stop() was called on it before it could finish
+   *
+   * @example
+   *   Animated.timing({}).start(({ finished }) => {
+   *    // completion callback
+   *   });
+   */
   start: (callback?: ?EndCallback, isLooping?: boolean) => void,
+  /**
+   * Stops any running animation.
+   */
   stop: () => void,
+  /**
+   * Stops any running animation and resets the value to its original.
+   */
   reset: () => void,
   _startNativeLoop: (iterations?: number) => void,
   _isUsingNativeDriver: () => boolean,
@@ -200,7 +222,11 @@ const springImpl = function (
       },
 
       _isUsingNativeDriver: function (): boolean {
-        return config.useNativeDriver || false;
+        return (
+          NativeAnimatedHelper.isNativeDriverForced() ||
+          config.useNativeDriver ||
+          false
+        );
       },
     }
   );
@@ -254,7 +280,11 @@ const timingImpl = function (
       },
 
       _isUsingNativeDriver: function (): boolean {
-        return config.useNativeDriver || false;
+        return (
+          NativeAnimatedHelper.isNativeDriverForced() ||
+          config.useNativeDriver ||
+          false
+        );
       },
     }
   );
@@ -296,7 +326,11 @@ const decayImpl = function (
       },
 
       _isUsingNativeDriver: function (): boolean {
-        return config.useNativeDriver || false;
+        return (
+          NativeAnimatedHelper.isNativeDriverForced() ||
+          config.useNativeDriver ||
+          false
+        );
       },
     }
   );
@@ -608,21 +642,104 @@ export default {
    * See https://reactnative.dev/docs/animated#node
    */
   Node: AnimatedNode,
+  /**
+   * Animates a value from an initial velocity to zero based on a decay
+   * coefficient.
+   */
   decay: decayImpl,
+  /**
+   * Animates a value along a timed easing curve.  The `Easing` module has tons
+   * of pre-defined curves, or you can use your own function.
+   */
   timing: timingImpl,
+  /**
+   * Spring animation based on Rebound and Origami.  Tracks velocity state to
+   * create fluid motions as the `toValue` updates, and can be chained together.
+   */
   spring: springImpl,
+  /**
+   * Creates a new Animated value composed from two Animated values added
+   * together.
+   */
   add: addImpl,
+  /**
+   * Creates a new Animated value composed by subtracting the second Animated
+   * value from the first Animated value.
+   */
   subtract: subtractImpl,
+  /**
+   * Creates a new Animated value composed by dividing the first Animated
+   * value by the second Animated value.
+   */
   divide: divideImpl,
+  /**
+   * Creates a new Animated value composed from two Animated values multiplied
+   * together.
+   */
   multiply: multiplyImpl,
+  /**
+   * Creates a new Animated value that is the (non-negative) modulo of the
+   * provided Animated value
+   */
   modulo: moduloImpl,
+  /**
+   * Create a new Animated value that is limited between 2 values. It uses the
+   * difference between the last value so even if the value is far from the bounds
+   * it will start changing when the value starts getting closer again.
+   * (`value = clamp(value + diff, min, max)`).
+   *
+   * This is useful with scroll events, for example, to show the navbar when
+   * scrolling up and to hide it when scrolling down.
+   */
   diffClamp: diffClampImpl,
+  /**
+   * Starts an animation after the given delay.
+   */
   delay: delayImpl,
+  /**
+   * Starts an array of animations in order, waiting for each to complete
+   * before starting the next.  If the current running animation is stopped, no
+   * following animations will be started.
+   */
   sequence: sequenceImpl,
+  /**
+   * Starts an array of animations all at the same time.  By default, if one
+   * of the animations is stopped, they will all be stopped.  You can override
+   * this with the `stopTogether` flag.
+   */
   parallel: parallelImpl,
+  /**
+   * Array of animations may run in parallel (overlap), but are started in
+   * sequence with successive delays.  Nice for doing trailing effects.
+   */
   stagger: staggerImpl,
+  /**
+   * Loops a given animation continuously, so that each time it reaches the end,
+   * it resets and begins again from the start. Can specify number of times to
+   * loop using the key 'iterations' in the config. Will loop without blocking
+   * the UI thread if the child animation is set to 'useNativeDriver'.
+   */
   loop: loopImpl,
+  /**
+   *  Takes an array of mappings and extracts values from each arg accordingly,
+   *  then calls `setValue` on the mapped outputs.  e.g.
+   *
+   *```javascript
+   *  onScroll={Animated.event(
+   *    [{nativeEvent: {contentOffset: {x: this._scrollX}}}]
+   *    {listener},          // Optional async listener
+   *  )
+   *  ...
+   *  onPanResponderMove: Animated.event([
+   *    null,                // raw event arg ignored
+   *    {dx: this._panX},    // gestureState arg
+   *  ]),
+   *```
+   */
   event: eventImpl,
+  /**
+   * Make any React component Animatable.  Used to create `Animated.View`, etc.
+   */
   createAnimatedComponent,
   attachNativeEvent: attachNativeEventImpl,
   forkEvent: forkEventImpl,

package/Libraries/Animated/Easing.js

@@ -15,9 +15,8 @@ let ease;
 export type EasingFunction = (t: number) => number;
 
 /**
- * The `Easing` module implements common easing functions. This module is used
- * by [Animate.timing()](docs/animate.html#timing) to convey physically
- * believable motion in animations.
+ * Implements common easing functions for use with `Animated.timing()` to convey
+ * physically believable motion in animations.
  *
  * You can find a visualization of some common easing functions at
  * http://easings.net/
@@ -58,6 +57,8 @@ export type EasingFunction = (t: number) => number;
  * - [`in`](docs/easing.html#in) runs an easing function forwards
  * - [`inOut`](docs/easing.html#inout) makes any easing function symmetrical
  * - [`out`](docs/easing.html#out) runs an easing function backwards
+ *
+ * @see https://reactnative.dev/docs/easing
  */
 const EasingStatic = {
   /**

package/Libraries/Animated/NativeAnimatedAllowlist.js

@@ -78,6 +78,42 @@ const SUPPORTED_STYLES: {[string]: true} = {
         top: true,
         /* flex */
         flex: true,
+        flexGrow: true,
+        flexShrink: true,
+        flexBasis: true,
+        aspectRatio: true,
+        /* margin */
+        margin: true,
+        marginLeft: true,
+        marginRight: true,
+        marginTop: true,
+        marginBottom: true,
+        marginStart: true,
+        marginEnd: true,
+        marginHorizontal: true,
+        marginVertical: true,
+        /* padding */
+        padding: true,
+        paddingLeft: true,
+        paddingRight: true,
+        paddingTop: true,
+        paddingBottom: true,
+        paddingStart: true,
+        paddingEnd: true,
+        paddingHorizontal: true,
+        paddingVertical: true,
+        /* border width */
+        borderWidth: true,
+        borderLeftWidth: true,
+        borderRightWidth: true,
+        borderTopWidth: true,
+        borderBottomWidth: true,
+        borderStartWidth: true,
+        borderEndWidth: true,
+        /* gap */
+        gap: true,
+        rowGap: true,
+        columnGap: true,
       }
     : {}),
 };
@@ -106,6 +142,7 @@ const SUPPORTED_INTERPOLATION_PARAMS: {[string]: true} = {
   extrapolate: true,
   extrapolateRight: true,
   extrapolateLeft: true,
+  easing: true,
 };
 
 /**

package/Libraries/Animated/animations/Animation.js

@@ -70,6 +70,7 @@ export default class Animation {
     previousAnimation: ?Animation,
     animatedValue: AnimatedValue,
   ): void {
+    // TODO: T274006331 - Remove js-only animation once shared backend is fully rolled out
     if (!this._useNativeDriver && animatedValue.__isNative === true) {
       throw new Error(
         'Attempting to run JS driven animation on animated node ' +
@@ -141,14 +142,22 @@ export default class Animation {
         animatedValue.__getNativeTag(),
         config,
         result => {
-          this.__notifyAnimationEnd(result);
-
           // When using natively driven animations, once the animation completes,
           // we need to ensure that the JS side nodes are synced with the updated
           // values.
           const {value, offset} = result;
-          if (value != null) {
+          const syncBeforeCallback =
+            ReactNativeFeatureFlags.animatedShouldSyncValueBeforeStartCallback();
+          if (syncBeforeCallback && value != null) {
             animatedValue.__onAnimatedValueUpdateReceived(value, offset);
+          }
+
+          this.__notifyAnimationEnd(result);
+
+          if (value != null) {
+            if (!syncBeforeCallback) {
+              animatedValue.__onAnimatedValueUpdateReceived(value, offset);
+            }
 
             const isJsSyncRemoved =
               ReactNativeFeatureFlags.cxxNativeAnimatedEnabled();
@@ -158,8 +167,8 @@ export default class Animation {
               }
             }
 
-            // Once the JS side node is synced with the updated values, trigger an
-            // update on the AnimatedProps nodes to call any registered callbacks.
+            // Trigger an update on the AnimatedProps nodes to call any
+            // registered callbacks now that the JS-side node is in sync.
             this.__findAnimatedPropsNodes(animatedValue).forEach(node =>
               node.update(),
             );

package/Libraries/Animated/animations/DecayAnimation.js

@@ -85,6 +85,7 @@ export default class DecayAnimation extends Animation {
     this._startTime = Date.now();
 
     const useNativeDriver = this.__startAnimationIfNative(animatedValue);
+    // TODO: T274006331 - Remove js-only animation once shared backend is fully rolled out
     if (!useNativeDriver) {
       this._animationFrame = requestAnimationFrame(() => this.onUpdate());
     }

package/Libraries/Animated/animations/SpringAnimation.js

@@ -225,6 +225,7 @@ export default class SpringAnimation extends Animation {
 
     const start = () => {
       const useNativeDriver = this.__startAnimationIfNative(animatedValue);
+      // TODO: T274006331 - Remove js-only animation once shared backend is fully rolled out
       if (!useNativeDriver) {
         this.onUpdate();
       }

package/Libraries/Animated/animations/TimingAnimation.js

@@ -15,6 +15,7 @@ import type AnimatedValue from '../nodes/AnimatedValue';
 import type AnimatedValueXY from '../nodes/AnimatedValueXY';
 import type {AnimationConfig, EndCallback} from './Animation';
 
+import * as ReactNativeFeatureFlags from '../../../src/private/featureflags/ReactNativeFeatureFlags';
 import AnimatedColor from '../nodes/AnimatedColor';
 import Animation from './Animation';
 
@@ -69,6 +70,7 @@ export default class TimingAnimation extends Animation {
   _animationFrame: ?AnimationFrameID;
   _timeout: ?TimeoutID;
   _platformConfig: ?PlatformConfig;
+  _deferredStart: boolean;
 
   constructor(config: TimingAnimationConfigSingle) {
     super(config);
@@ -78,6 +80,7 @@ export default class TimingAnimation extends Animation {
     this._duration = config.duration ?? 500;
     this._delay = config.delay ?? 0;
     this._platformConfig = config.platformConfig;
+    this._deferredStart = false;
   }
 
   __getNativeAnimationConfig(): Readonly<{
@@ -102,6 +105,7 @@ export default class TimingAnimation extends Animation {
       iterations: this.__iterations,
       platformConfig: this._platformConfig,
       debugID: this.__getDebugID(),
+      deferredStart: this._deferredStart,
     };
   }
 
@@ -116,11 +120,16 @@ export default class TimingAnimation extends Animation {
 
     this._fromValue = fromValue;
     this._onUpdate = onUpdate;
+    if (ReactNativeFeatureFlags.animatedDeferStartOfTimingAnimations()) {
+      this._deferredStart = animatedValue.__deferAnimationStart;
+      animatedValue.__deferAnimationStart = false;
+    }
 
     const start = () => {
       this._startTime = Date.now();
 
       const useNativeDriver = this.__startAnimationIfNative(animatedValue);
+      // TODO: T274006331 - Remove js-only animation once shared backend is fully rolled out
       if (!useNativeDriver) {
         // Animations that sometimes have 0 duration and sometimes do not
         // still need to use the native driver when duration is 0 so as to

package/Libraries/Animated/createAnimatedComponent.js

@@ -31,7 +31,7 @@ type Nullable = void | null;
 type Primitive = string | number | boolean | symbol | void;
 type Builtin = (...ReadonlyArray<empty>) => unknown | Date | Error | RegExp;
 
-export type WithAnimatedValue<+T> = T extends Builtin | Nullable
+export type WithAnimatedValue<out T> = T extends Builtin | Nullable
   ? T
   : T extends Primitive
     ?
@@ -51,7 +51,7 @@ export type WithAnimatedValue<+T> = T extends Builtin | Nullable
     : T extends ReadonlyArray<infer P>
       ? ReadonlyArray<WithAnimatedValue<P>>
       : T extends {...}
-        ? {+[K in keyof T]: WithAnimatedValue<T[K]>}
+        ? {readonly [K in keyof T]: WithAnimatedValue<T[K]>}
         : T;
 
 type NonAnimatedProps =
@@ -91,7 +91,7 @@ export type AnimatedBaseProps<Props extends {...}> = LooseOmit<
 
 export type AnimatedComponentType<
   Props extends {...},
-  +Instance = unknown,
+  out Instance = unknown,
 > = component(ref?: React.RefSetter<Instance>, ...AnimatedProps<Props>);
 
 export default function createAnimatedComponent<

package/Libraries/Animated/nodes/AnimatedColor.js

@@ -30,18 +30,18 @@ export type AnimatedColorConfig = Readonly<{
 type ColorListenerCallback = (value: ColorValue) => unknown;
 
 export type RgbaValue = {
-  +r: number,
-  +g: number,
-  +b: number,
-  +a: number,
+  readonly r: number,
+  readonly g: number,
+  readonly b: number,
+  readonly a: number,
   ...
 };
 
 type RgbaAnimatedValue = {
-  +r: AnimatedValue,
-  +g: AnimatedValue,
-  +b: AnimatedValue,
-  +a: AnimatedValue,
+  readonly r: AnimatedValue,
+  readonly g: AnimatedValue,
+  readonly b: AnimatedValue,
+  readonly a: AnimatedValue,
   ...
 };