react-native-reanimated 3.6.0 → 3.6.2

package/src/reanimated2/layoutReanimation/sharedTransitions/SharedTransition.ts

@@ -29,6 +29,12 @@ type AnimationFactory = (
   values: SharedTransitionAnimationsValues
 ) => StyleProps;
 
+/**
+ * A SharedTransition builder class.
+ *
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+ * @experimental
+ */
 export class SharedTransition {
   private _customAnimationFactory: AnimationFactory | null = null;
   private _animation: SharedTransitionAnimationsFunction | null = null;
@@ -224,31 +230,67 @@ export class SharedTransition {
     };
   }
 
-  // static builder methods
+  // static builder methods i.e. shared transition modifiers
 
+  /**
+   * Lets you create a custom shared transition animation. Other shared transition modifiers can be chained alongside this modifier.
+   *
+   * @param customAnimationFactory - Callback function that have to return an object with styles for the custom shared transition.
+   * @returns A {@link SharedTransition} object. Styles returned from this function need to be to the `sharedTransitionStyle` prop.
+   * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+   * @experimental
+   */
   public static custom(
     customAnimationFactory: AnimationFactory
   ): SharedTransition {
     return new SharedTransition().custom(customAnimationFactory);
   }
 
+  /**
+   * Lets you change the duration of the shared transition. Other shared transition modifiers can be chained alongside this modifier.
+   *
+   * @param duration - The duration of the shared transition animation in milliseconds.
+   * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+   * @experimental
+   */
   public static duration(duration: number): SharedTransition {
     return new SharedTransition().duration(duration);
   }
 
+  /**
+   * Lets you create a shared transition animation bound to the progress between navigation screens. Other shared transition modifiers can be chained alongside this modifier.
+   *
+   * @param progressAnimationCallback - A callback called with the current progress value on every animation frame. It should return an object with styles for the shared transition.
+   * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+   * @experimental
+   */
   public static progressAnimation(
     progressAnimationCallback: CustomProgressAnimation
   ): SharedTransition {
     return new SharedTransition().progressAnimation(progressAnimationCallback);
   }
 
+  /**
+   * Whether the transition is progress-bound or not. Other shared transition modifiers can be chained alongside this modifier.
+   *
+   * @param transitionType - Type of the transition. Configured with {@link SharedTransitionType} enum.
+   * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+   * @experimental
+   */
   public static defaultTransitionType(
     transitionType: SharedTransitionType
   ): SharedTransition {
     return new SharedTransition().defaultTransitionType(transitionType);
   }
 
-  public static reduceMotion(_reduceMotion: ReduceMotion): SharedTransition {
-    return new SharedTransition().reduceMotion(_reduceMotion);
+  /**
+   * Lets you adjust the behavior when the device's reduced motion accessibility setting is turned on. Other shared transition modifiers can be chained alongside this modifier.
+   *
+   * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}.
+   * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview
+   * @experimental
+   */
+  public static reduceMotion(reduceMotion: ReduceMotion): SharedTransition {
+    return new SharedTransition().reduceMotion(reduceMotion);
   }
 }

package/src/reanimated2/layoutReanimation/web/createAnimation.ts

@@ -65,8 +65,8 @@ function addExistingTransform(
 /**
  *  Modifies default animation by preserving transformations that given element already contains.
  *
- * @param animationName Name of the animation to be modified (e.g. `FadeIn`).
- * @param existingTransform Transform values that element already contains.
+ * @param animationName - Name of the animation to be modified (e.g. `FadeIn`).
+ * @param existingTransform - Transform values that element already contains.
  * @returns Animation parsed to keyframe string.
  */
 export function createAnimationWithExistingTransform(
@@ -109,8 +109,8 @@ function generateNextCustomKeyframeName() {
 /**
  * Creates transition of given type, appends it to stylesheet and returns keyframe name.
  *
- * @param transitionType Type of transition (e.g. LINEAR).
- * @param transitionData Object containing data for transforms (translateX, scaleX,...).
+ * @param transitionType - Type of transition (e.g. LINEAR).
+ * @param transitionData - Object containing data for transforms (translateX, scaleX,...).
  * @returns Keyframe name that represents transition.
  */
 export function TransitionGenerator(

package/src/reanimated2/platform-specific/checkCppVersion.ts

@@ -4,10 +4,6 @@ import { jsVersion } from './jsVersion';
 export function checkCppVersion() {
   const cppVersion = global._REANIMATED_VERSION_CPP;
   if (cppVersion === undefined) {
-    console.warn(
-      `[Reanimated] Couldn't determine the version of the native part of Reanimated.
-    See \`https://docs.swmansion.com/react-native-reanimated/docs/guides/troubleshooting#couldnt-determine-the-version-of-the-native-part-of-reanimated\` for more details.`
-    );
     return;
   }
   const ok = matchVersion(jsVersion, cppVersion);

package/src/reanimated2/platform-specific/jsVersion.ts

@@ -4,4 +4,4 @@
  * with the version used to build the native part of the library in runtime.
  * Remember to keep this in sync with the version declared in `package.json`
  */
-export const jsVersion = '3.6.0';
+export const jsVersion = '3.6.2';

package/src/reanimated2/platformFunctions/dispatchCommand.ts

@@ -55,6 +55,14 @@ function dispatchCommandDefault() {
   );
 }
 
+/**
+ * Lets you synchronously call a command of a native component.
+ *
+ * @param animatedRef - An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef#returns) connected to the component you'd want to call the command on.
+ * @param commandName - The name of the command to dispatch (e.g. `"focus"` or `"scrollToEnd"`).
+ * @param args - An optional array of arguments for the command.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/advanced/dispatchCommand
+ */
 export let dispatchCommand: <T extends Component>(
   animatedRef: AnimatedRef<T>,
   commandName: string,

package/src/reanimated2/platformFunctions/getRelativeCoords.ts

@@ -3,22 +3,30 @@ import type { Component } from 'react';
 import { measure } from './measure';
 import type { AnimatedRef } from '../hook/commonTypes';
 
+/**
+ * An object which contains relative coordinates.
+ */
 export interface ComponentCoords {
   x: number;
   y: number;
 }
 
 /**
- * Given an absolute position and a component ref, returns the relative
- * position in the component's local coordinate space.
+ * Lets you determines the location on the screen, relative to the given view.
+ *
+ * @param animatedRef - An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the coordinates from.
+ * @param absoluteX - A number which is an absolute x coordinate.
+ * @param absoluteY - A number which is an absolute y coordinate.
+ * @returns An object which contains relative coordinates - {@link ComponentCoords}.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/utilities/getRelativeCoords
  */
 export function getRelativeCoords(
-  parentAnimatedRef: AnimatedRef<Component>,
+  animatedRef: AnimatedRef<Component>,
   absoluteX: number,
   absoluteY: number
 ): ComponentCoords | null {
   'worklet';
-  const parentCoords = measure(parentAnimatedRef);
+  const parentCoords = measure(animatedRef);
   if (parentCoords === null) {
     return null;
   }

package/src/reanimated2/platformFunctions/measure.ts

@@ -9,6 +9,13 @@ import {
 import type { AnimatedRef } from '../hook/commonTypes';
 import type { Component } from 'react';
 
+/**
+ * Lets you synchronously get the dimensions and position of a view on the screen.
+ *
+ * @param animatedRef - An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the measurements from.
+ * @returns An object containing component measurements or null when the measurement couldn't be performed- {@link MeasuredDimensions}.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/advanced/measure/
+ */
 export let measure: <T extends Component>(
   animatedRef: AnimatedRef<T>
 ) => MeasuredDimensions | null;

package/src/reanimated2/platformFunctions/scrollTo.ts

@@ -9,6 +9,15 @@ import { dispatchCommand } from './dispatchCommand';
 import type { AnimatedRef } from '../hook/commonTypes';
 import type { Component } from 'react';
 
+/**
+ * Lets you synchronously scroll to a given position of a `ScrollView`.
+ *
+ * @param animatedRef - An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef) attached to an `Animated.ScrollView` component.
+ * @param x - The x position you want to scroll to.
+ * @param y - The y position you want to scroll to.
+ * @param animated - Whether the scrolling should be smooth or instant.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/scroll/scrollTo
+ */
 export let scrollTo: <T extends Component>(
   animatedRef: AnimatedRef<T>,
   x: number,

package/src/reanimated2/platformFunctions/setNativeProps.ts

@@ -10,6 +10,13 @@ import type { AnimatedRef } from '../hook/commonTypes';
 import type { Component } from 'react';
 import { processColorsInProps } from '../Colors';
 
+/**
+ * Lets you imperatively update component properties. You should always reach for [useAnimatedStyle](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedStyle) and [useAnimatedProps](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedProps) first when animating styles or properties.
+ *
+ * @param animatedRef - An [animated ref](https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedRef#returns) connected to the component you'd want to update.
+ * @param updates - An object with properties you want to update.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/advanced/setNativeProps
+ */
 export let setNativeProps: <T extends Component>(
   animatedRef: AnimatedRef<T>,
   updates: StyleProps

package/src/reanimated2/runtimes.ts

@@ -15,6 +15,14 @@ export type WorkletRuntime = {
   readonly name: string;
 };
 
+/**
+ * Lets you create a new JS runtime which can be used to run worklets possibly on different threads than JS or UI thread.
+ *
+ * @param name - A name used to identify the runtime which will appear in devices list in Chrome DevTools.
+ * @param initializer - An optional worklet that will be run synchronously on the same thread immediately after the runtime is created.
+ * @returns WorkletRuntime which is a jsi::HostObject\<reanimated::WorkletRuntime\> - {@link WorkletRuntime}
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/threading/createWorkletRuntime
+ */
 export function createWorkletRuntime(
   name: string,
   initializer?: __ComplexWorkletFunction<[], void>

package/src/reanimated2/threads.ts

@@ -53,16 +53,23 @@ export const callMicrotasks = SHOULD_BE_USE_WEB
     }
   : callMicrotasksOnUIThread;
 
+/**
+ * Lets you asynchronously run [workletized](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#to-workletize) functions on the [UI thread](https://docs.swmansion.com/react-native-reanimated/docs/threading/runOnUI).
+ *
+ * This method does not schedule the work immediately but instead waits for other worklets
+ * to be scheduled within the same JS loop. It uses queueMicrotask to schedule all the worklets
+ * at once making sure they will run within the same frame boundaries on the UI thread.
+ *
+ * @param fun - A reference to a function you want to execute on the [UI thread](https://docs.swmansion.com/react-native-reanimated/docs/threading/runOnUI) from the [JavaScript thread](https://docs.swmansion.com/react-native-reanimated/docs/threading/runOnUI).
+ * @returns A function that accepts arguments for the function passed as the first argument.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/threading/runOnUI
+ */
 // @ts-expect-error This overload is correct since it's what user sees in his code
 // before it's transformed by Reanimated Babel plugin.
 export function runOnUI<Args extends unknown[], ReturnValue>(
   worklet: (...args: Args) => ReturnValue
 ): (...args: Args) => void;
-/**
- * Schedule a worklet to execute on the UI runtime. This method does not schedule the work immediately but instead
- * waits for other worklets to be scheduled within the same JS loop. It uses queueMicrotask to schedule all the worklets
- * at once making sure they will run within the same frame boundaries on the UI thread.
- */
+
 export function runOnUI<Args extends unknown[], ReturnValue>(
   worklet: WorkletFunction<Args, ReturnValue>
 ): (...args: Args) => void {
@@ -175,8 +182,12 @@ function runWorkletOnJS<Args extends unknown[], ReturnValue>(
 }
 
 /**
- * Returns a function that can be called to be executed asynchronously on both
- * UI and JS threads.
+ * Lets you asynchronously run non-[workletized](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#to-workletize) functions that couldn't otherwise run on the [UI thread](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#ui-thread).
+ * This applies to most external libraries as they don't have their functions marked with "worklet"; directive.
+ *
+ * @param fun - A reference to a function you want to execute on the JavaScript thread from the UI thread.
+ * @returns A function that accepts arguments for the function passed as the first argument.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/threading/runOnJS
  */
 export function runOnJS<Args extends unknown[], ReturnValue>(
   fun: