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

package/Libraries/Types/CoreEventTypes.js

@@ -10,7 +10,7 @@
 
 import type {HostInstance} from '../../src/private/types/HostInstance';
 
-export type NativeSyntheticEvent<+T> = Readonly<{
+export type NativeSyntheticEvent<out T> = Readonly<{
   bubbles: ?boolean,
   cancelable: ?boolean,
   currentTarget: number | HostInstance,
@@ -76,6 +76,9 @@ export type LayoutChangeEvent = NativeSyntheticEvent<
   }>,
 >;
 
+/**
+ * @deprecated Use `TextLayoutEvent` instead.
+ */
 type TextLayoutEventData = Readonly<{
   lines: Array<TextLayoutLine>,
 }>;
@@ -102,7 +105,7 @@ export interface NativeUIEvent {
   /**
    * Returns a long with details about the event, depending on the event type.
    */
-  +detail: number;
+  readonly detail: number;
 }
 
 /**
@@ -112,72 +115,72 @@ export interface NativeMouseEvent extends NativeUIEvent {
   /**
    * The X coordinate of the mouse pointer in global (screen) coordinates.
    */
-  +screenX: number;
+  readonly screenX: number;
   /**
    * The Y coordinate of the mouse pointer in global (screen) coordinates.
    */
-  +screenY: number;
+  readonly screenY: number;
   /**
    * The X coordinate of the mouse pointer relative to the whole document.
    */
-  +pageX: number;
+  readonly pageX: number;
   /**
    * The Y coordinate of the mouse pointer relative to the whole document.
    */
-  +pageY: number;
+  readonly pageY: number;
   /**
    * The X coordinate of the mouse pointer in local (DOM content) coordinates.
    */
-  +clientX: number;
+  readonly clientX: number;
   /**
    * The Y coordinate of the mouse pointer in local (DOM content) coordinates.
    */
-  +clientY: number;
+  readonly clientY: number;
   /**
    * Alias for NativeMouseEvent.clientX
    */
-  +x: number;
+  readonly x: number;
   /**
    * Alias for NativeMouseEvent.clientY
    */
-  +y: number;
+  readonly y: number;
   /**
    * Returns true if the control key was down when the mouse event was fired.
    */
-  +ctrlKey: boolean;
+  readonly ctrlKey: boolean;
   /**
    * Returns true if the shift key was down when the mouse event was fired.
    */
-  +shiftKey: boolean;
+  readonly shiftKey: boolean;
   /**
    * Returns true if the alt key was down when the mouse event was fired.
    */
-  +altKey: boolean;
+  readonly altKey: boolean;
   /**
    * Returns true if the meta key was down when the mouse event was fired.
    */
-  +metaKey: boolean;
+  readonly metaKey: boolean;
   /**
    * The button number that was pressed (if applicable) when the mouse event was fired.
    */
-  +button: number;
+  readonly button: number;
   /**
    * The buttons being depressed (if any) when the mouse event was fired.
    */
-  +buttons: number;
+  readonly buttons: number;
   /**
    * The secondary target for the event, if there is one.
    */
-  +relatedTarget: null | number | HostInstance;
+  readonly relatedTarget: null | number | HostInstance;
   // offset is proposed: https://drafts.csswg.org/cssom-view/#extensions-to-the-mouseevent-interface
   /**
    * The X coordinate of the mouse pointer between that event and the padding edge of the target node
    */
-  +offsetX: number;
+  readonly offsetX: number;
   /**
    * The Y coordinate of the mouse pointer between that event and the padding edge of the target node
    */
-  +offsetY: number;
+  readonly offsetY: number;
 }
 
 /**
@@ -187,48 +190,48 @@ export interface NativePointerEvent extends NativeMouseEvent {
   /**
    * A unique identifier for the pointer causing the event.
    */
-  +pointerId: number;
+  readonly pointerId: number;
   /**
    * The width (magnitude on the X axis), in CSS pixels, of the contact geometry of the pointer
    */
-  +width: number;
+  readonly width: number;
   /**
    * The height (magnitude on the Y axis), in CSS pixels, of the contact geometry of the pointer.
    */
-  +height: number;
+  readonly height: number;
   /**
    * The normalized pressure of the pointer input in the range 0 to 1, where 0 and 1 represent
    * the minimum and maximum pressure the hardware is capable of detecting, respectively.
    */
-  +pressure: number;
+  readonly pressure: number;
   /**
    * The normalized tangential pressure of the pointer input (also known as barrel pressure or
    * cylinder stress) in the range -1 to 1, where 0 is the neutral position of the control.
    */
-  +tangentialPressure: number;
+  readonly tangentialPressure: number;
   /**
    * The plane angle (in degrees, in the range of -90 to 90) between the Y–Z plane and the plane
    * containing both the pointer (e.g. pen stylus) axis and the Y axis.
    */
-  +tiltX: number;
+  readonly tiltX: number;
   /**
    * The plane angle (in degrees, in the range of -90 to 90) between the X–Z plane and the plane
    * containing both the pointer (e.g. pen stylus) axis and the X axis.
    */
-  +tiltY: number;
+  readonly tiltY: number;
   /**
    * The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees,
    * with a value in the range 0 to 359.
    */
-  +twist: number;
+  readonly twist: number;
   /**
    * Indicates the device type that caused the event (mouse, pen, touch, etc.)
    */
-  +pointerType: string;
+  readonly pointerType: string;
   /**
    * Indicates if the pointer represents the primary pointer of this pointer type.
    */
-  +isPrimary: boolean;
+  readonly isPrimary: boolean;
 }
 
 export type PointerEvent = NativeSyntheticEvent<NativePointerEvent>;

package/Libraries/Types/UIManagerJSInterface.js

@@ -11,6 +11,6 @@
 import type {Spec} from '../ReactNative/NativeUIManager';
 
 export interface UIManagerJSInterface extends Spec {
-  +getViewManagerConfig: (viewManagerName: string) => Object;
-  +hasViewManagerConfig: (viewManagerName: string) => boolean;
+  readonly getViewManagerConfig: (viewManagerName: string) => Object;
+  readonly hasViewManagerConfig: (viewManagerName: string) => boolean;
 }

package/Libraries/Utilities/Appearance.d.ts

@@ -9,35 +9,46 @@
 
 import {NativeEventSubscription} from '../EventEmitter/RCTNativeAppEventEmitter';
 
-type ColorSchemeName = 'light' | 'dark' | 'unspecified';
+type ColorSchemeName = 'light' | 'dark';
+
+type ColorSchemeOverride =
+  | ColorSchemeName
+  | 'auto'
+  /** @deprecated Use 'auto' instead */
+  | 'unspecified';
 
 export namespace Appearance {
   type AppearancePreferences = {
-    colorScheme: ColorSchemeName;
+    colorScheme: ColorSchemeName | null;
   };
 
   type AppearanceListener = (preferences: AppearancePreferences) => void;
 
   /**
-   * Note: Although color scheme is available immediately, it may change at any
-   * time. Any rendering logic or styles that depend on this should try to call
-   * this function on every render, rather than caching the value (for example,
-   * using inline styles rather than setting a value in a `StyleSheet`).
+   * Returns the active color scheme (`'light'` or `'dark'`). This value may
+   * change at runtime, either at the system level (e.g. scheduled color scheme
+   * change at sunrise or sunset) or when overridden at the app level via
+   * `setColorScheme()`.
+   *
+   * Prefer `useColorScheme()` in React components.
    *
-   * Example: `const colorScheme = Appearance.getColorScheme();`
+   * Notes:
+   * - `null` will only be returned if the native Appearance module is
+   *   unavailable (out of tree platforms).
    */
-  export function getColorScheme(): ColorSchemeName | null | undefined;
+  export function getColorScheme(): ColorSchemeName | null;
 
   /**
-   * Set the color scheme preference. This is useful for overriding the default
-   * color scheme preference for the app. Note that this will not change the
-   * appearance of the system UI, only the appearance of the app.
-   * Only available on iOS 13+ and Android 10+.
+   * Force the application to always adopt a light or dark interface style. Pass
+   * `'auto'` to reset and follow the system default (removes any override).
+   * This does not affect the system UI, only the application.
    */
-  export function setColorScheme(scheme: ColorSchemeName): void;
+  export function setColorScheme(scheme: ColorSchemeOverride): void;
 
   /**
-   * Add an event handler that is fired when appearance preferences change.
+   * Subscribe to color scheme changes. The listener receives the new appearance
+   * preferences whenever the color scheme changes, whether from a system event
+   * or a call to `setColorScheme()`.
    */
   export function addChangeListener(
     listener: AppearanceListener,
@@ -45,7 +56,11 @@ export namespace Appearance {
 }
 
 /**
- * A new useColorScheme hook is provided as the preferred way of accessing
- * the user's preferred color scheme (e.g. Dark Mode).
+ * Returns the active color scheme (`'light'` or `'dark'`). Automatically
+ * re-renders the component when the color scheme changes.
+ *
+ * Notes:
+ * - `null` will only be returned if the native Appearance module is unavailable
+ *   (out of tree platforms).
  */
-export function useColorScheme(): ColorSchemeName;
+export function useColorScheme(): ColorSchemeName | null;

package/Libraries/Utilities/Appearance.js

@@ -9,27 +9,35 @@
  */
 
 import type {EventSubscription} from '../vendor/emitter/EventEmitter';
-import type {AppearancePreferences, ColorSchemeName} from './NativeAppearance';
+import type {
+  AppearancePreferences as NativeAppearancePreferences,
+  ColorSchemeName,
+  ColorSchemeOverride,
+} from './NativeAppearance';
 import typeof INativeAppearance from './NativeAppearance';
 
 import NativeEventEmitter from '../EventEmitter/NativeEventEmitter';
 import EventEmitter from '../vendor/emitter/EventEmitter';
 
-export type {AppearancePreferences};
+export type {ColorSchemeName, ColorSchemeOverride};
+
+export type AppearancePreferences = {
+  colorScheme: ColorSchemeName | null,
+};
 
 type Appearance = {
-  colorScheme: ?ColorSchemeName,
+  colorScheme: ColorSchemeName | null,
 };
 
 let lazyState: ?{
-  +NativeAppearance: INativeAppearance,
+  readonly NativeAppearance: INativeAppearance,
   // Cache the color scheme to reduce the cost of reading it between changes.
   // NOTE: If `NativeAppearance` is null, this will always be null.
   appearance: ?Appearance,
   // NOTE: This is non-nullable to make it easier for `onChangedListener` to
   // return a non-nullable `EventSubscription` value. This is not the common
   // path, so we do not have to over-optimize it.
-  +eventEmitter: EventEmitter<{change: [Appearance]}>,
+  readonly eventEmitter: EventEmitter<{change: [Appearance]}>,
 };
 
 /**
@@ -56,7 +64,7 @@ function getState(): NonNullable<typeof lazyState> {
       eventEmitter,
     };
     new NativeEventEmitter<{
-      appearanceChanged: [AppearancePreferences],
+      appearanceChanged: [NativeAppearancePreferences],
     }>(NativeAppearance).addListener('appearanceChanged', newAppearance => {
       state.appearance = {
         colorScheme: newAppearance.colorScheme,
@@ -69,11 +77,18 @@ function getState(): NonNullable<typeof lazyState> {
 }
 
 /**
- * Returns the current color scheme preference. This value may change, so the
- * value should not be cached without either listening to changes or using
- * the `useColorScheme` hook.
+ * Returns the active color scheme (`'light'` or `'dark'`). This value may
+ * change at runtime, either at the system level (e.g. scheduled color scheme
+ * change at sunrise or sunset) or when overridden at the app level via
+ * `setColorScheme()`.
+ *
+ * Prefer `useColorScheme()` in React components.
+ *
+ * Notes:
+ * - `null` will only be returned if the native Appearance module is unavailable
+ *   (out of tree platforms).
  */
-export function getColorScheme(): ?ColorSchemeName {
+export function getColorScheme(): ColorSchemeName | null {
   let colorScheme = null;
   const state = getState();
   const {NativeAppearance} = state;
@@ -91,29 +106,31 @@ export function getColorScheme(): ?ColorSchemeName {
 }
 
 /**
- * Updates the current color scheme to the supplied value.
+ * Force the application to always adopt a light or dark interface style. Pass
+ * `'auto'` to reset and follow the system default (removes any override).
+ * This does not affect the system UI, only the application.
  */
-export function setColorScheme(colorScheme: ColorSchemeName): void {
+export function setColorScheme(colorScheme: ColorSchemeOverride): void {
   const state = getState();
   const {NativeAppearance} = state;
   if (NativeAppearance != null) {
     NativeAppearance.setColorScheme(colorScheme);
     state.appearance = {
-      // When setting to 'unspecified', get the actual system color scheme.
-      // Fall back to the passed value if getColorScheme() returns null.
       colorScheme:
-        colorScheme === 'unspecified'
-          ? (NativeAppearance.getColorScheme() ?? colorScheme)
+        colorScheme === 'auto' || colorScheme === 'unspecified'
+          ? NativeAppearance.getColorScheme()
           : colorScheme,
     };
   }
 }
 
 /**
- * Add an event handler that is fired when appearance preferences change.
+ * Subscribe to color scheme changes. The listener receives the new appearance
+ * preferences whenever the color scheme changes, whether from a system event
+ * or a call to `setColorScheme()`.
  */
 export function addChangeListener(
-  listener: ({colorScheme: ?ColorSchemeName}) => void,
+  listener: (preferences: AppearancePreferences) => void,
 ): EventSubscription {
   const {eventEmitter} = getState();
   return eventEmitter.addListener('change', listener);

package/Libraries/Utilities/BackHandler.android.js

@@ -37,43 +37,25 @@ RCTDeviceEventEmitter.addListener(DEVICE_BACK_EVENT, function (nativeEvent) {
 });
 
 /**
- * Detect hardware button presses for back navigation.
+ * Detects hardware button presses for back navigation and lets you register
+ * event listeners for the system's back action. Event subscriptions are called
+ * in reverse order (i.e. last registered subscription first). If one
+ * subscription returns `true`, earlier subscriptions are not called.
  *
- * Android: Detect hardware back button presses, and programmatically invoke the default back button
- * functionality to exit the app if there are no listeners or if none of the listeners return true.
- *
- * tvOS: Detect presses of the menu button on the TV remote.  (Still to be implemented:
- * programmatically disable menu button handling
- * functionality to exit the app if there are no listeners or if none of the listeners return true.)
- *
- * iOS: Not applicable.
- *
- * The event subscriptions are called in reverse order (i.e. last registered subscription first),
- * and if one subscription returns true then subscriptions registered earlier will not be called.
- *
- * Example:
- *
- * ```javascript
- * BackHandler.addEventListener('hardwareBackPress', function() {
- *  // this.onMainScreen and this.goBack are just examples, you need to use your own implementation here
- *  // Typically you would use the navigator here to go to the last state.
- *
- *  if (!this.onMainScreen()) {
- *    this.goBack();
- *    return true;
- *  }
- *  return false;
- * });
- * ```
+ * @see https://reactnative.dev/docs/backhandler
+ * @platform android
  */
 type TBackHandler = {
-  +exitApp: () => void,
-  +addEventListener: (
+  readonly exitApp: () => void,
+  readonly addEventListener: (
     eventName: BackPressEventName,
     handler: BackPressHandler,
   ) => {remove: () => void, ...},
 };
 const BackHandler: TBackHandler = {
+  /**
+   * Programmatically exit the app.
+   */
   exitApp: function (): void {
     if (!NativeDeviceEventManager) {
       return;
@@ -83,10 +65,8 @@ const BackHandler: TBackHandler = {
   },
 
   /**
-   * Adds an event handler. Supported events:
-   *
-   * - `hardwareBackPress`: Fires when the Android hardware back button is pressed or when the
-   * tvOS menu button is pressed.
+   * Listen for the `hardwareBackPress` event. The handler should return `true`
+   * to prevent the event from bubbling to earlier registered listeners.
    */
   addEventListener: function (
     eventName: BackPressEventName,

package/Libraries/Utilities/BackHandler.js.flow

@@ -12,9 +12,14 @@
 
 export type BackPressEventName = 'backPress' | 'hardwareBackPress';
 
+/**
+ * Event dispatched when the hardware back button is pressed.
+ * The `timeStamp` property reflects the native timestamp captured
+ * when the back press was emitted.
+ */
 export interface HardwareBackPressEvent {
-  +type: string;
-  +timeStamp: number;
+  readonly type: string;
+  readonly timeStamp: number;
 }
 
 type TBackHandler = {
@@ -25,6 +30,17 @@ type TBackHandler = {
   ): {remove: () => void, ...},
 };
 
+/**
+ * Detect hardware back button presses, and programmatically invoke the
+ * default back button functionality to exit the app if there are no
+ * listeners or if none of the listeners return true.
+ * The event subscriptions are called in reverse order
+ * (i.e. last registered subscription first), and if one subscription
+ * returns true then subscriptions registered earlier
+ * will not be called.
+ *
+ * @see https://reactnative.dev/docs/backhandler
+ */
 declare const BackHandler: TBackHandler;
 
 declare export default typeof BackHandler;

package/Libraries/Utilities/DevSettings.js

@@ -15,7 +15,11 @@ import NativeDevSettings from '../NativeModules/specs/NativeDevSettings';
 import Platform from '../Utilities/Platform';
 
 /**
- * The DevSettings module exposes methods for customizing settings for developers in development.
+ * The `DevSettings` module exposes methods for customizing settings for
+ * developers in development mode. This module is a no-op in production
+ * builds.
+ *
+ * @see https://reactnative.dev/docs/devsettings
  */
 let DevSettings: {
   /**
@@ -31,6 +35,9 @@ let DevSettings: {
    * @param reason
    */
   reload(reason?: string): void,
+  /**
+   * Notify the native side that a Fast Refresh has occurred.
+   */
   onFastRefresh(): void,
 } = {
   addMenuItem(title: string, handler: () => unknown): void {},

package/Libraries/Utilities/Dimensions.js

@@ -30,18 +30,23 @@ const eventEmitter = new EventEmitter<{
 let dimensionsInitialized = false;
 let dimensions: DimensionsPayload;
 
+/**
+ * Provides the application window's width and height. Prefer
+ * `useWindowDimensions` in React components.
+ *
+ * @see https://reactnative.dev/docs/dimensions
+ */
 class Dimensions {
   /**
-   * NOTE: `useWindowDimensions` is the preferred API for React components.
+   * Returns the current dimensions for `'window'` or `'screen'`. On Android,
+   * `'window'` dimensions exclude the status bar and navigation bar.
    *
-   * Initial dimensions are set before `runApplication` is called so they should
-   * be available before any other require's are run, but may be updated later.
+   * NOTE: `useWindowDimensions` is the preferred API for React components.
    *
-   * Note: Although dimensions are available immediately, they may change (e.g
-   * due to device rotation) so any rendering logic or styles that depend on
-   * these constants should try to call this function on every render, rather
-   * than caching the value (for example, using inline styles rather than
-   * setting a value in a `StyleSheet`).
+   * Although dimensions are available immediately, they may change (e.g. due to
+   * device rotation) so any rendering logic or styles that depend on these
+   * constants should try to call this function on every render, rather than
+   * caching the value.
    *
    * Example: `const {height, width} = Dimensions.get('window');`
    *
@@ -98,10 +103,11 @@ class Dimensions {
   /**
    * Add an event handler. Supported events:
    *
-   * - `change`: Fires when a property within the `Dimensions` object changes. The argument
-   *   to the event handler is an object with `window` and `screen` properties whose values
-   *   are the same as the return values of `Dimensions.get('window')` and
-   *   `Dimensions.get('screen')`, respectively.
+   * - `change`: Fires when a property within the `Dimensions` object changes,
+   *   such as on device rotation or foldable device state changes. The argument
+   *   to the event handler is a `DimensionsPayload` object with `window` and
+   *   `screen` properties whose values are the same as the return values of
+   *   `Dimensions.get('window')` and `Dimensions.get('screen')`, respectively.
    */
   static addEventListener(
     type: 'change',

package/Libraries/Utilities/PixelRatio.js

@@ -13,7 +13,7 @@
 const Dimensions = require('./Dimensions').default;
 
 /**
- * PixelRatio class gives access to the device pixel density.
+ * Provides access to the device's pixel density and font scale.
  *
  * ## Fetching a correctly sized image
  *
@@ -21,7 +21,9 @@ const Dimensions = require('./Dimensions').default;
  * device. A good rule of thumb is to multiply the size of the image you display
  * by the pixel ratio.
  *
- * ```
+ * Example:
+ *
+ * ```tsx
  * var image = getImage({
  *   width: PixelRatio.getPixelSizeForLayoutSize(200),
  *   height: PixelRatio.getPixelSizeForLayoutSize(100),
@@ -55,6 +57,7 @@ const Dimensions = require('./Dimensions').default;
  * rounding is done relative to the root rather than the parent, again to avoid
  * accumulating rounding errors.
  *
+ * @see https://reactnative.dev/docs/pixelratio
  */
 class PixelRatio {
   /**

package/Libraries/Utilities/Platform.js.flow

@@ -10,4 +10,8 @@
 
 import type {PlatformType} from './PlatformTypes';
 
+/**
+ * Provides information about the platform the app is running on and utility
+ * methods for platform-specific logic.
+ */
 declare export default PlatformType;