@depup/react-native 0.86.0-depup.49 → 0.87.0-depup.0

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,39 +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.
- *
- * 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;
@@ -79,9 +65,8 @@ const BackHandler: TBackHandler = {
   },
 
   /**
-   * Adds an event handler. Supported events:
-   *
-   * - `hardwareBackPress`: Fires when the Android hardware back 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;

package/Libraries/Utilities/PlatformTypes.js

@@ -29,9 +29,24 @@ export type PlatformSelectSpec<T> =
 
 type IOSPlatform = {
   __constants: null,
+
+  /** The platform identifier. Always `'ios'` on iOS. */
   OS: 'ios',
+
+  /**
+   * The OS version string (e.g. `'26.0'`).
+   *
+   * @platform ios
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get Version(): string,
+
+  /**
+   * An object of platform-specific constants, including `reactNativeVersion`,
+   * `osVersion`, `interfaceIdiom`, and more.
+   *
+   * @platform ios
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get constants(): {
     forceTouchAvailable: boolean,
@@ -48,26 +63,69 @@ type IOSPlatform = {
     systemName: string,
     isMacCatalyst?: boolean,
   },
+
+  /**
+   * Whether the app is running on an iPad.
+   *
+   * @platform ios
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isPad(): boolean,
+
+  /**
+   * Whether the app is running on a TV device.
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isTV(): boolean,
+
+  /**
+   * Whether the app is running on Apple Vision Pro.
+   *
+   * @platform ios
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isVision(): boolean,
+
+  /**
+   * Whether the app is running in a test environment.
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isTesting(): boolean,
+
   // $FlowFixMe[unsafe-getters-setters]
   get isDisableAnimations(): boolean,
+
   // $FlowFixMe[unsafe-getters-setters]
   get isMacCatalyst(): boolean,
+
+  /**
+   * Returns the most fitting value for the current platform from the given
+   * spec object. The spec can include keys for specific platform names
+   * (`'ios'`, `'android'`, etc.) and a `default` fallback.
+   */
   select: <T>(spec: PlatformSelectSpec<T>) => T,
 };
 
 type AndroidPlatform = {
   __constants: null,
+
+  /** The platform identifier. Always `'android'` on Android. */
   OS: 'android',
+
+  /**
+   * The Android API level (e.g. `34`).
+   *
+   * @platform android
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get Version(): number,
+
+  /**
+   * An object of platform-specific constants, including `reactNativeVersion`,
+   * `Version`, `Release`, `Model`, and more.
+   *
+   * @platform android
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get constants(): {
     isTesting: boolean,
@@ -88,14 +146,33 @@ type AndroidPlatform = {
     Brand: string,
     Manufacturer: string,
   },
+
+  /**
+   * Whether the app is running on a TV device.
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isTV(): boolean,
+
+  /**
+   * Whether the app is running on Apple Vision Pro. Always `false` on Android.
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isVision(): boolean,
+
+  /**
+   * Whether the app is running in a test environment.
+   */
   // $FlowFixMe[unsafe-getters-setters]
   get isTesting(): boolean,
+
   // $FlowFixMe[unsafe-getters-setters]
   get isDisableAnimations(): boolean,
+
+  /**
+   * Returns the most fitting value for the current platform from the given
+   * spec object. The spec can include keys for specific platform names
+   * (`'ios'`, `'android'`, etc.) and a `default` fallback.
+   */
   select: <T>(spec: PlatformSelectSpec<T>) => T,
 };
 

package/Libraries/Utilities/differ/deepDiffer.js

@@ -13,10 +13,13 @@
 let logListeners;
 
 type LogListeners = {
-  +onDifferentFunctionsIgnored: (nameOne: ?string, nameTwo: ?string) => void,
+  readonly onDifferentFunctionsIgnored: (
+    nameOne: ?string,
+    nameTwo: ?string,
+  ) => void,
 };
 
-type Options = {+unsafelyIgnoreFunctions?: boolean};
+type Options = {readonly unsafelyIgnoreFunctions?: boolean};
 
 function unstable_setLogListeners(listeners: ?LogListeners) {
   logListeners = listeners;

package/Libraries/Utilities/useColorScheme.js

@@ -20,6 +20,16 @@ const subscribe = (onStoreChange: () => void) => {
   return () => appearanceSubscription.remove();
 };
 
-export default function useColorScheme(): ?ColorSchemeName {
+/**
+ * React hook that provides and subscribes to color scheme updates from the
+ * `Appearance` module. Returns `'light'`, `'dark'`, or `null`.
+ *
+ * Notes:
+ * - `null` will only be returned if the native Appearance module is unavailable
+ *   (out of tree platforms).
+ *
+ * @see https://reactnative.dev/docs/usecolorscheme
+ */
+export default function useColorScheme(): ColorSchemeName | null {
   return useSyncExternalStore(subscribe, getColorScheme);
 }

package/Libraries/Utilities/useWindowDimensions.js

@@ -15,6 +15,12 @@ import {
 } from './NativeDeviceInfo';
 import {useEffect, useState} from 'react';
 
+/**
+ * React hook that provides the application window's width, height, scale, and
+ * font scale. Automatically updates when screen size or font scale changes.
+ *
+ * @see https://reactnative.dev/docs/usewindowdimensions
+ */
 export default function useWindowDimensions():
   | DisplayMetrics
   | DisplayMetricsAndroid {

package/Libraries/Vibration/Vibration.js

@@ -12,12 +12,6 @@ import NativeVibration from './NativeVibration';
 
 const Platform = require('../Utilities/Platform').default;
 
-/**
- * Vibration API
- *
- * See https://reactnative.dev/docs/vibration
- */
-
 let _vibrating: boolean = false;
 let _id: number = 0; // _id is necessary to prevent race condition.
 const _default_vibration_length = 400;
@@ -64,11 +58,21 @@ function vibrateScheduler(
   );
 }
 
+/**
+ * Vibrates the device. On Android, requires the `android.permission.VIBRATE`
+ * permission. On iOS, vibration duration is fixed at approximately 400ms
+ * (implemented via `AudioServicesPlaySystemSound(kSystemSoundID_Vibrate)`).
+ *
+ * @see https://reactnative.dev/docs/vibration
+ */
 const Vibration = {
   /**
-   * Trigger a vibration with specified `pattern`.
+   * Trigger a vibration with the specified `pattern`.
    *
-   * See https://reactnative.dev/docs/vibration#vibrate
+   * The pattern can be a number (duration in ms) or an array of numbers. When
+   * an array is provided on Android, odd indices represent vibration duration
+   * and even indices represent separation time. On iOS, the duration value is
+   * ignored and each vibration lasts approximately 400ms.
    */
   vibrate: function (
     pattern?: number | Array<number> = _default_vibration_length,
@@ -95,10 +99,9 @@ const Vibration = {
       }
     }
   },
+
   /**
-   * Stop vibration
-   *
-   * See https://reactnative.dev/docs/vibration#cancel
+   * Stop vibrating after `vibrate()` was called with repetition enabled.
    */
   cancel: function () {
     if (Platform.OS === 'ios') {

package/Libraries/vendor/emitter/EventEmitter.js

@@ -41,9 +41,9 @@ export interface IEventEmitter<
 }
 
 interface Registration<TArgs> {
-  +context: unknown;
-  +listener: (...args: TArgs) => unknown;
-  +remove: () => void;
+  readonly context: unknown;
+  readonly listener: (...args: TArgs) => unknown;
+  readonly remove: () => void;
 }
 
 type Registry<