From 9f73a4beb05b49b41325987c7642a34d18685051 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kacper=20Kapu=C5=9Bciak?= <39658211+kacperkapusciak@users.noreply.github.com> Date: Wed, 29 Nov 2023 14:50:03 +0100 Subject: [PATCH] Add TSDoc to public API (#5377) This PR aims to cover the entirety of Reanimated public API with short, descriptive TSDoc comments. This will allow developers to stay longer in their editors and save some time searching and googling. Under each function there's a link to the documentation. --- .eslintrc.js | 10 +- docs/docs/advanced/setNativeProps.mdx | 4 +- docs/docs/animations/withDecay.mdx | 4 +- docs/docs/animations/withDelay.mdx | 2 +- docs/docs/animations/withRepeat.mdx | 4 +- docs/docs/animations/withSequence.mdx | 2 +- docs/docs/animations/withSpring.mdx | 4 +- docs/docs/animations/withTiming.mdx | 12 +- docs/docs/core/useAnimatedRef.mdx | 2 +- docs/docs/fundamentals/glossary.mdx | 20 +++- .../layout-animation-config.mdx | 2 +- .../layout-animations/layout-transitions.mdx | 2 +- package.json | 1 + .../createAnimatedComponent.tsx | 7 ++ .../setAndForwardRef.ts | 2 + src/reanimated2/Easing.ts | 6 +- src/reanimated2/animation/decay/decay.ts | 8 ++ src/reanimated2/animation/decay/utils.ts | 12 ++ src/reanimated2/animation/delay.ts | 9 ++ src/reanimated2/animation/repeat.ts | 11 ++ src/reanimated2/animation/sequence.ts | 8 ++ src/reanimated2/animation/spring.ts | 9 ++ src/reanimated2/animation/springUtils.ts | 15 +++ src/reanimated2/animation/timing.ts | 17 +++ src/reanimated2/animation/util.ts | 6 + src/reanimated2/commonTypes.ts | 32 +++-- src/reanimated2/component/FlatList.tsx | 6 + .../component/LayoutAnimationConfig.tsx | 7 ++ src/reanimated2/helperTypes.ts | 48 +++++++- src/reanimated2/hook/useAnimatedKeyboard.ts | 7 ++ src/reanimated2/hook/useAnimatedProps.ts | 9 ++ src/reanimated2/hook/useAnimatedReaction.ts | 10 +- src/reanimated2/hook/useAnimatedRef.ts | 6 + .../hook/useAnimatedScrollHandler.ts | 10 ++ src/reanimated2/hook/useAnimatedSensor.ts | 8 ++ src/reanimated2/hook/useAnimatedStyle.ts | 8 ++ src/reanimated2/hook/useDerivedValue.ts | 22 ++-- src/reanimated2/hook/useEvent.ts | 15 ++- src/reanimated2/hook/useFrameCallback.ts | 14 +++ src/reanimated2/hook/useHandler.ts | 8 ++ src/reanimated2/hook/useReducedMotion.ts | 8 ++ src/reanimated2/hook/useScrollViewOffset.ts | 7 ++ src/reanimated2/hook/useSharedValue.ts | 15 ++- src/reanimated2/hook/useWorkletCallback.ts | 3 + src/reanimated2/index.ts | 2 +- src/reanimated2/interpolateColor.ts | 17 +++ src/reanimated2/interpolation.ts | 70 +++++++---- .../animationBuilder/BaseAnimationBuilder.ts | 29 ++++- .../ComplexAnimationBuilder.ts | 59 ++++++++- .../animationBuilder/commonTypes.ts | 4 + .../defaultAnimations/Bounce.ts | 71 +++++++++++ .../defaultAnimations/Fade.ts | 71 ++++++++++- .../defaultAnimations/Flip.ts | 84 +++++++++++++ .../defaultAnimations/Lightspeed.ts | 28 +++++ .../defaultAnimations/Pinwheel.ts | 14 +++ .../defaultAnimations/Roll.ts | 28 +++++ .../defaultAnimations/Rotate.ts | 56 +++++++++ .../defaultAnimations/Slide.ts | 56 +++++++++ .../defaultAnimations/Stretch.ts | 28 +++++ .../defaultAnimations/Zoom.ts | 112 ++++++++++++++++++ .../defaultTransitions/CurvedTransition.ts | 7 ++ .../defaultTransitions/EntryExitTransition.ts | 8 ++ .../defaultTransitions/FadingTransition.ts | 7 ++ .../defaultTransitions/JumpingTransition.ts | 8 ++ .../defaultTransitions/LinearTransition.ts | 13 +- .../defaultTransitions/SequencedTransition.ts | 7 ++ .../sharedTransitions/SharedTransition.ts | 48 +++++++- .../layoutReanimation/web/createAnimation.ts | 8 +- .../platformFunctions/dispatchCommand.ts | 8 ++ .../platformFunctions/getRelativeCoords.ts | 16 ++- src/reanimated2/platformFunctions/measure.ts | 7 ++ src/reanimated2/platformFunctions/scrollTo.ts | 9 ++ .../platformFunctions/setNativeProps.ts | 7 ++ src/reanimated2/runtimes.ts | 8 ++ src/reanimated2/threads.ts | 25 ++-- yarn.lock | 59 ++++++++- 76 files changed, 1290 insertions(+), 106 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 0e3517f9bf2..0184b9598ac 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -12,7 +12,14 @@ module.exports = { 'plugin:import/typescript', 'plugin:react-hooks/recommended', ], - plugins: ['react', 'react-native', 'import', 'jest', '@typescript-eslint'], + plugins: [ + 'react', + 'react-native', + 'import', + 'jest', + '@typescript-eslint', + 'eslint-plugin-tsdoc', + ], env: { 'react-native/react-native': true, 'jest/globals': true, @@ -52,5 +59,6 @@ module.exports = { 'error', { fixMixedExportsWithInlineTypeSpecifier: false }, ], + 'tsdoc/syntax': 'error', }, }; diff --git a/docs/docs/advanced/setNativeProps.mdx b/docs/docs/advanced/setNativeProps.mdx index b19233c6b84..f54b8cf1510 100644 --- a/docs/docs/advanced/setNativeProps.mdx +++ b/docs/docs/advanced/setNativeProps.mdx @@ -10,7 +10,7 @@ sidebar_position: 7 `setNativeProps` is an escape hatch for specific edge-cases. -You should always reach for [`useAnimatedStyle`](docs/core/useAnimatedStyle) and [`useAnimatedProps`](docs/core/useAnimatedProps) first when animating styles or properties. +You should always reach for [`useAnimatedStyle`](/docs/core/useAnimatedStyle) and [`useAnimatedProps`](/docs/core/useAnimatedProps) first when animating styles or properties. ::: @@ -48,7 +48,7 @@ function setNativeProps( #### `animatedRef` -An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the measurements from. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component. +An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to update. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component. #### `updates` diff --git a/docs/docs/animations/withDecay.mdx b/docs/docs/animations/withDecay.mdx index 091df72678b..489a66ee0ea 100644 --- a/docs/docs/animations/withDecay.mdx +++ b/docs/docs/animations/withDecay.mdx @@ -4,7 +4,7 @@ sidebar_position: 3 # withDecay -`withDecay` lets you create animations that mimic objects in motion. The animation will start with the provided velocity and slow down over time according to the given deceleration rate until it stops. +`withDecay` lets you create animations that mimic objects in motion with friction. The animation will start with the provided velocity and slow down over time according to the given deceleration rate until it stops. import DecayBasic from '@site/src/examples/DecayBasic'; import DecayBasicSrc from '!!raw-loader!@site/src/examples/DecayBasic'; @@ -80,7 +80,7 @@ A function called on animation complete. In case the animation is cancelled, the ### Returns -`withDecay` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](/docs/core/useAnimatedStyle). +`withDecay` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](/docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/animations/withDelay.mdx b/docs/docs/animations/withDelay.mdx index 47985b7a682..830b332c727 100644 --- a/docs/docs/animations/withDelay.mdx +++ b/docs/docs/animations/withDelay.mdx @@ -54,7 +54,7 @@ A parameter that determines how the animation responds to the device's reduced m ### Returns -`withDelay` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). +`withDelay` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/animations/withRepeat.mdx b/docs/docs/animations/withRepeat.mdx index 5edf4aa4648..9801770bee9 100644 --- a/docs/docs/animations/withRepeat.mdx +++ b/docs/docs/animations/withRepeat.mdx @@ -49,7 +49,7 @@ enum ReduceMotion { #### `animation` -The animation you want to repeat. +An [animation object](/docs/fundamentals/glossary#animation-object) you want to repeat. #### `numberOfReps` @@ -73,7 +73,7 @@ A parameter that determines how the animation responds to the device's reduced m ### Returns -`withRepeat` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). +`withRepeat` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/animations/withSequence.mdx b/docs/docs/animations/withSequence.mdx index 93d55ff2d4e..70dfa6ac6db 100644 --- a/docs/docs/animations/withSequence.mdx +++ b/docs/docs/animations/withSequence.mdx @@ -54,7 +54,7 @@ Any number of [animation objects](docs/fundamentals/glossary#animation-object) t ### Returns -`withSequence` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). +`withSequence` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/animations/withSpring.mdx b/docs/docs/animations/withSpring.mdx index 8ae6a6f2330..5f52fff0851 100644 --- a/docs/docs/animations/withSpring.mdx +++ b/docs/docs/animations/withSpring.mdx @@ -81,7 +81,7 @@ Available properties: | overshootClamping | `boolean` | false | Whether a spring can bounce over the `toValue`. | | restDisplacementThreshold | `number` | 0.01 | The displacement below which the spring will snap to `toValue` without further oscillations. | | restSpeedThreshold | `number` | 2 | The speed in pixels per second from which the spring will snap to `toValue` without further oscillations. | -| reduceMotion | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. | +| reduceMotion | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. | :::info The `mass` and `damping` (physics-based) properties can't be used at the same time as `duration` and `dampingRatio` (duration-based). @@ -95,7 +95,7 @@ A function called upon animation completion. If the animation is cancelled, the ### Returns -`withSpring` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). +`withSpring` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/animations/withTiming.mdx b/docs/docs/animations/withTiming.mdx index 57f799318cf..1d67e1fbdf3 100644 --- a/docs/docs/animations/withTiming.mdx +++ b/docs/docs/animations/withTiming.mdx @@ -65,11 +65,11 @@ import { useTimingPlayground } from '@site/src/components/InteractivePlayground' Available properties: -| Name | Type | Default | Description | -| ------------------------- | -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | -| duration | `number` | 300 | Length of the animation (in milliseconds). | -| easing | `Easing` | `Easing.inOut(Easing.quad)` | An easing function which defines the animation curve. | -| reduceMotion | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. | +| Name | Type | Default | Description | +| ------------ | -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | +| duration | `number` | 300 | Length of the animation (in milliseconds). | +| easing | `Easing` | `Easing.inOut(Easing.quad)` | An easing function which defines the animation curve. | +| reduceMotion | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. | ##### `Easing` @@ -124,7 +124,7 @@ A function called upon animation completion. If the animation is cancelled, the ### Returns -`withTiming` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). +`withTiming` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle). ## Example diff --git a/docs/docs/core/useAnimatedRef.mdx b/docs/docs/core/useAnimatedRef.mdx index 006bdfeb594..83704894ec4 100644 --- a/docs/docs/core/useAnimatedRef.mdx +++ b/docs/docs/core/useAnimatedRef.mdx @@ -6,7 +6,7 @@ sidebar_position: 4 `useAnimatedRef` lets you get a reference of a view. Used alongside [`measure`](/docs/advanced/measure), [`scrollTo`](/docs/scroll/scrollTo), and [`useScrollViewOffset`](/docs/scroll/useScrollViewOffset) functions. -An object defined using `useAnimatedRef` has to be passed to the `ref` property of a component. +You need to pass the object defined using `useAnimatedRef` to the `ref` property of a component. ## Reference diff --git a/docs/docs/fundamentals/glossary.mdx b/docs/docs/fundamentals/glossary.mdx index 635ea704627..c7f3b494295 100644 --- a/docs/docs/fundamentals/glossary.mdx +++ b/docs/docs/fundamentals/glossary.mdx @@ -33,7 +33,7 @@ const AnimatedCircle = Animated.createAnimatedComponent(Circle); Shared values are a driving factor of all your animations in Reanimated. -They are defined using `useSharedValue` hook: +They are defined using [`useSharedValue`](/docs/core/useSharedValue) hook: ```javascript import { useSharedValue } from 'react-native-reanimated'; @@ -111,6 +111,24 @@ function App() { } ``` +## Layout animation modifier + +Layout animation modifiers are methods used to customize layout animations. + +```jsx + +``` + +Reanimated comes with plenty of built-in layout animation modifiers. Some of them are: + +- `.duration(durationMs: number)` - the length of the animation (in milliseconds). +- `.easing(easingFunction: EasingFunction)` - an easing function which defines the animation curve. +- `.springify()` - enables the spring-based animation configuration. +- `.damping(value: number)` - decides how quickly a spring stops moving. +- `.withCallback(callback: (finished: boolean) => void)` - the callback that will fire after the animation ends. + +For a list of all available modifiers for each animation refer to the documentation of individual layout animation. + ## Worklet Worklets are short-running JavaScript functions that can be run on the [UI thread](/docs/fundamentals/glossary#ui-thread). They can also be run on a JavaScript thread just as you would run a function in your code. diff --git a/docs/docs/layout-animations/layout-animation-config.mdx b/docs/docs/layout-animations/layout-animation-config.mdx index 0b5bb72613c..008b5bf591a 100644 --- a/docs/docs/layout-animations/layout-animation-config.mdx +++ b/docs/docs/layout-animations/layout-animation-config.mdx @@ -78,7 +78,7 @@ import LayoutAnimationConfigSrc from '!!raw-loader!@site/src/examples/LayoutAnim ## Platform compatibility -
+
| Android | iOS | Web | | ------- | --- | --- | diff --git a/docs/docs/layout-animations/layout-transitions.mdx b/docs/docs/layout-animations/layout-transitions.mdx index 4542a8c61f2..e88b2257ca9 100644 --- a/docs/docs/layout-animations/layout-transitions.mdx +++ b/docs/docs/layout-animations/layout-transitions.mdx @@ -43,7 +43,7 @@ Below we listed all of the currently available predefined layout transitions. Ea If you cannot find an transition that suits you then you can create a custom one. If you think that the animation should be here, please open an issue or create a pull request. -### Layout +### Linear transition Linear transition, animates both position and dimension in the same way. diff --git a/package.json b/package.json index e8dd6e11bfc..f3a5e3d822f 100644 --- a/package.json +++ b/package.json @@ -149,6 +149,7 @@ "eslint-plugin-promise": "^6.0.0", "eslint-plugin-react-hooks": "^4.6.0", "eslint-plugin-standard": "^5.0.0", + "eslint-plugin-tsdoc": "^0.2.17", "husky": "^7.0.4", "jest": "^29.0.0", "lint-staged": "^11.2.0", diff --git a/src/createAnimatedComponent/createAnimatedComponent.tsx b/src/createAnimatedComponent/createAnimatedComponent.tsx index 02fc610a780..068792d2514 100644 --- a/src/createAnimatedComponent/createAnimatedComponent.tsx +++ b/src/createAnimatedComponent/createAnimatedComponent.tsx @@ -77,6 +77,13 @@ type Options

= { setNativeProps: (ref: AnimatedComponentRef, props: P) => void; }; +/** + * Lets you create an Animated version of any React Native component. + * + * @param component - The component you want to make animatable. + * @returns A component that Reanimated is capable of animating. + * @see https://docs.swmansion.com/react-native-reanimated/docs/core/createAnimatedComponent + */ export function createAnimatedComponent

( component: FunctionComponent

, options?: Options

diff --git a/src/createAnimatedComponent/setAndForwardRef.ts b/src/createAnimatedComponent/setAndForwardRef.ts index 3ce108a5ffa..17d1bb3ab96 100644 --- a/src/createAnimatedComponent/setAndForwardRef.ts +++ b/src/createAnimatedComponent/setAndForwardRef.ts @@ -5,6 +5,7 @@ import type { MutableRefObject } from 'react'; +/* eslint-disable */ /** * This is a helper function for when a component needs to be able to forward a ref * to a child component, but still needs to have access to that component as part of @@ -35,6 +36,7 @@ import type { MutableRefObject } from 'react'; * * module.exports = MyViewWithRef; */ +/* eslint-enable */ type ForwardedRef = () => MutableRefObject | ((ref: T) => void); diff --git a/src/reanimated2/Easing.ts b/src/reanimated2/Easing.ts index e84b55c2d98..224cbd382f3 100644 --- a/src/reanimated2/Easing.ts +++ b/src/reanimated2/Easing.ts @@ -50,14 +50,14 @@ import { Bezier } from './Bezier'; export type EasingFunction = (t: number) => number; /** - * @deprecated Please use `EasingFunction` type instead. + * @deprecated Please use {@link EasingFunction} type instead. */ export type EasingFn = EasingFunction; export type EasingFunctionFactory = { factory: () => EasingFunction }; /** - * @deprecated Please use `EasingFunctionFactory` type instead. + * @deprecated Please use {@link EasingFunctionFactory} type instead. */ export type EasingFactoryFn = EasingFunctionFactory; /** @@ -153,7 +153,7 @@ function exp(t: number): number { * forth. * * Default bounciness is 1, which overshoots a little bit once. 0 bounciness - * doesn't overshoot at all, and bounciness of N > 1 will overshoot about N + * doesn't overshoot at all, and bounciness of N \> 1 will overshoot about N * times. * * http://easings.net/#easeInElastic diff --git a/src/reanimated2/animation/decay/decay.ts b/src/reanimated2/animation/decay/decay.ts index 342f4662ec0..fbdb221f630 100644 --- a/src/reanimated2/animation/decay/decay.ts +++ b/src/reanimated2/animation/decay/decay.ts @@ -49,6 +49,14 @@ function validateConfig(config: DefaultDecayConfig): void { } } +/** + * Lets you create animations that mimic objects in motion with friction. + * + * @param config - The decay animation configuration - {@link DecayConfig}. + * @param callback - A function called upon animation completion - {@link AnimationCallback}. + * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withDecay + */ export const withDecay = function ( userConfig: DecayConfig, callback?: AnimationCallback diff --git a/src/reanimated2/animation/decay/utils.ts b/src/reanimated2/animation/decay/utils.ts index ff37064b3b6..31aa656508e 100644 --- a/src/reanimated2/animation/decay/utils.ts +++ b/src/reanimated2/animation/decay/utils.ts @@ -28,6 +28,18 @@ export interface InnerDecayAnimation springActive?: boolean; } +/** + * The decay animation configuration. + * + * @param velocity - Initial velocity of the animation. Defaults to 0. + * @param deceleration - The rate at which the velocity decreases over time. Defaults to 0.998. + * @param clamp - Array of two numbers which restricts animation's range. Defaults to []. + * @param velocityFactor - Velocity multiplier. Defaults to 1. + * @param rubberBandEffect - Makes the animation bounce over the limit specified in `clamp`. Defaults to `false`. + * @param rubberBandFactor - Strength of the rubber band effect. Defaults to 0.6. + * @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/animations/withDecay#config + */ export type DecayConfig = { deceleration?: number; velocityFactor?: number; diff --git a/src/reanimated2/animation/delay.ts b/src/reanimated2/animation/delay.ts index 10d2317b9e2..764063cda54 100644 --- a/src/reanimated2/animation/delay.ts +++ b/src/reanimated2/animation/delay.ts @@ -16,6 +16,15 @@ type withDelayType = ( reduceMotion?: ReduceMotion ) => T; +/** + * An animation modifier that lets you start an animation with a delay. + * + * @param delayMs - Duration (in milliseconds) before the animation starts. + * @param nextAnimation - The animation to delay. + * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}. + * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withDelay + */ export const withDelay = function ( delayMs: number, _nextAnimation: T | (() => T), diff --git a/src/reanimated2/animation/repeat.ts b/src/reanimated2/animation/repeat.ts index 72114e471d9..36721a45d4c 100644 --- a/src/reanimated2/animation/repeat.ts +++ b/src/reanimated2/animation/repeat.ts @@ -19,6 +19,17 @@ type withRepeatType = ( reduceMotion?: ReduceMotion ) => T; +/** + * Lets you repeat an animation given number of times or run it indefinitely. + * + * @param animation - An animation object you want to repeat. + * @param numberOfReps - The number of times the animation is going to be repeated. Defaults to 2. + * @param reverse - Whether the animation should run in reverse every other repetition. Defaults to false. + * @param callback - A function called on animation complete. + * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}. + * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withRepeat + */ export const withRepeat = function ( _nextAnimation: T | (() => T), numberOfReps = 2, diff --git a/src/reanimated2/animation/sequence.ts b/src/reanimated2/animation/sequence.ts index ed7d86b3a0d..95617168621 100644 --- a/src/reanimated2/animation/sequence.ts +++ b/src/reanimated2/animation/sequence.ts @@ -9,6 +9,14 @@ import type { Timestamp, } from '../commonTypes'; +/** + * Lets you run animations in a sequence. + * + * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}. + * @param animations - Any number of animation objects to be run in a sequence. + * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation/ + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withSequence + */ export function withSequence( _reduceMotion: ReduceMotion, ...animations: T[] diff --git a/src/reanimated2/animation/spring.ts b/src/reanimated2/animation/spring.ts index 40b3699ccf8..ea340bac49b 100644 --- a/src/reanimated2/animation/spring.ts +++ b/src/reanimated2/animation/spring.ts @@ -29,6 +29,15 @@ type withSpringType = ( callback?: AnimationCallback ) => T; +/** + * Lets you create spring-based animations. + * + * @param toValue - the value at which the animation will come to rest - {@link AnimatableValue} + * @param config - the spring animation configuration - {@link SpringConfig} + * @param callback - a function called on animation complete - {@link AnimationCallback} + * @returns an [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withSpring + */ export const withSpring = (( toValue: AnimatableValue, userConfig?: SpringConfig, diff --git a/src/reanimated2/animation/springUtils.ts b/src/reanimated2/animation/springUtils.ts index 11aff046650..2c0e979dc87 100644 --- a/src/reanimated2/animation/springUtils.ts +++ b/src/reanimated2/animation/springUtils.ts @@ -6,6 +6,21 @@ import type { ReduceMotion, } from '../commonTypes'; +/** + * Spring animation configuration. + * + * @param mass - The weight of the spring. Reducing this value makes the animation faster. Defaults to 1. + * @param damping - How quickly a spring slows down. Higher damping means the spring will come to rest faster. Defaults to 10. + * @param duration - Length of the animation (in milliseconds). Defaults to 2000. + * @param dampingRatio - How damped the spring is. Value 1 means the spring is critically damped, and value \>1 means the spring is overdamped. Defaults to 0.5. + * @param stiffness - How bouncy the spring is. Defaults to 100. + * @param velocity - Initial velocity applied to the spring equation. Defaults to 0. + * @param overshootClamping - Whether a spring can bounce over the `toValue`. Defaults to false. + * @param restDisplacementThreshold - The displacement below which the spring will snap to toValue without further oscillations. Defaults to 0.01. + * @param restSpeedThreshold - The speed in pixels per second from which the spring will snap to toValue without further oscillations. Defaults to 2. + * @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/animations/withSpring/#config- + */ export type SpringConfig = { stiffness?: number; overshootClamping?: boolean; diff --git a/src/reanimated2/animation/timing.ts b/src/reanimated2/animation/timing.ts index 34b56866267..5897981f2ae 100644 --- a/src/reanimated2/animation/timing.ts +++ b/src/reanimated2/animation/timing.ts @@ -10,6 +10,14 @@ import type { ReduceMotion, } from '../commonTypes'; +/** + * The timing animation configuration. + * + * @param duration - Length of the animation (in milliseconds). Defaults to 300. + * @param easing - An easing function which defines the animation curve. Defaults to `Easing.inOut(Easing.quad)`. + * @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/animations/withTiming#config- + */ interface TimingConfig { duration?: number; reduceMotion?: ReduceMotion; @@ -41,6 +49,15 @@ type withTimingType = ( callback?: AnimationCallback ) => T; +/** + * Lets you create an animation based on duration and easing. + * + * @param toValue - The value on which the animation will come at rest - {@link AnimatableValue}. + * @param config - The timing animation configuration - {@link TimingConfig}. + * @param callback - A function called on animation complete - {@link AnimationCallback}. + * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. + * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withTiming + */ export const withTiming = function ( toValue: AnimatableValue, userConfig?: TimingConfig, diff --git a/src/reanimated2/animation/util.ts b/src/reanimated2/animation/util.ts index 6c90fc60ee8..f634ac774f0 100644 --- a/src/reanimated2/animation/util.ts +++ b/src/reanimated2/animation/util.ts @@ -493,6 +493,12 @@ export function defineAnimation< return create; } +/** + * Lets you cancel a running animation paired to a shared value. + * + * @param sharedValue - The shared value of a running animation that you want to cancel. + * @see https://docs.swmansion.com/react-native-reanimated/docs/core/cancelAnimation + */ export function cancelAnimation(sharedValue: SharedValue): void { 'worklet'; // setting the current value cancels the animation if one is currently running diff --git a/src/reanimated2/commonTypes.ts b/src/reanimated2/commonTypes.ts index c8ff78c8e10..d7986541edf 100644 --- a/src/reanimated2/commonTypes.ts +++ b/src/reanimated2/commonTypes.ts @@ -8,6 +8,11 @@ export interface StyleProps extends ViewStyle, TextStyle { [key: string]: any; } +/** + * A value that can be used both on the [JavaScript thread](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#javascript-thread) and the [UI thread](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#ui-thread). + * + * Shared values are defined using [useSharedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue) hook. You access and modify shared values by their `.value` property. + */ export interface SharedValue { value: Value; addListener: (listenerID: number, listener: (value: any) => void) => void; @@ -154,6 +159,9 @@ export type AnimatedSensor = { config: SensorConfig; }; +/** + * A function called upon animation completion. If the animation is cancelled, the callback will receive `false` as the argument; otherwise, it will receive `true`. + */ export type AnimationCallback = ( finished?: boolean, current?: AnimatableValue @@ -203,6 +211,15 @@ export type AnimatedKeyboardInfo = { state: SharedValue; }; +/** + * @param x - A number representing X coordinate relative to the parent component. + * @param y - A number representing Y coordinate relative to the parent component. + * @param width - A number representing the width of the component. + * @param height - A number representing the height of the component. + * @param pageX - A number representing X coordinate relative to the screen. + * @param pageY - A number representing Y coordinate relative to the screen. + * @see https://docs.swmansion.com/react-native-reanimated/docs/advanced/measure#returns + */ export interface MeasuredDimensions { x: number; y: number; @@ -217,9 +234,10 @@ export interface AnimatedKeyboardOptions { } /** - * - `System` - If the `Reduce motion` accessibility setting is enabled on the device, disable the animation. Otherwise, enable the animation. - * - `Always` - Disable the animation. - * - `Never` - Enable the animation. + * @param System - If the `Reduce motion` accessibility setting is enabled on the device, disable the animation. Otherwise, enable the animation. + * @param Always - Disable the animation. + * @param Never - Enable the animation. + * @see https://docs.swmansion.com/react-native-reanimated/docs/guides/accessibility */ export enum ReduceMotion { System = 'system', @@ -230,7 +248,7 @@ export enum ReduceMotion { // THE LAND OF THE DEPRECATED /** - * @deprecated + * @deprecated don't use */ export interface __WorkletFunction { __closure?: Record; @@ -238,14 +256,14 @@ export interface __WorkletFunction { } /** - * @deprecated + * @deprecated don't use */ export interface __BasicWorkletFunction extends __WorkletFunction { (): T; } /** - * @deprecated + * @deprecated don't use */ export interface __ComplexWorkletFunction extends __WorkletFunction { @@ -254,7 +272,7 @@ export interface __ComplexWorkletFunction } /** - * @deprecated + * @deprecated don't use */ export interface __AdapterWorkletFunction extends __WorkletFunction { (value: NestedObject): void; diff --git a/src/reanimated2/component/FlatList.tsx b/src/reanimated2/component/FlatList.tsx index e629d06f25a..2a33aedbc6c 100644 --- a/src/reanimated2/component/FlatList.tsx +++ b/src/reanimated2/component/FlatList.tsx @@ -42,7 +42,13 @@ const createCellRendererComponent = ( interface ReanimatedFlatListPropsWithLayout extends AnimatedProps> { + /** + * Lets you pass layout animation directly to the FlatList item. + */ itemLayoutAnimation?: ILayoutAnimationBuilder; + /** + * Lets you skip entering and exiting animations of FlatList items when on FlatList mount or unmount. + */ skipEnteringExitingAnimations?: boolean; } diff --git a/src/reanimated2/component/LayoutAnimationConfig.tsx b/src/reanimated2/component/LayoutAnimationConfig.tsx index 582047be6a2..eedf4bad5cb 100644 --- a/src/reanimated2/component/LayoutAnimationConfig.tsx +++ b/src/reanimated2/component/LayoutAnimationConfig.tsx @@ -42,6 +42,13 @@ function SkipEntering(props: { shouldSkip: boolean; children: ReactNode }) { // when the wrapper is unmounted to prevent the animation. // Since `ReactNode` can be a list of nodes, we wrap every child with our wrapper // so we are able to access its tag with `findNodeHandle`. +/** + * A component that lets you skip entering and exiting animations. + * + * @param skipEntering - A boolean indicating whether children's entering animations should be skipped when `LayoutAnimationConfig` is mounted. + * @param skipExiting - A boolean indicating whether children's exiting animations should be skipped when LayoutAnimationConfig is unmounted. + * @see https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/layout-animation-config/ + */ export class LayoutAnimationConfig extends Component { getMaybeWrappedChildren() { return Children.count(this.props.children) > 1 && this.props.skipExiting diff --git a/src/reanimated2/helperTypes.ts b/src/reanimated2/helperTypes.ts index 055b2c676b6..d8f5d76c500 100644 --- a/src/reanimated2/helperTypes.ts +++ b/src/reanimated2/helperTypes.ts @@ -93,16 +93,53 @@ type RestProps = { }; type LayoutProps = { + /** + * Lets you animate the layout changes when components are added to or removed from the view hierarchy. + * + * You can use the predefined layout transitions (eg. `LinearTransition`, `FadingTransition`) or create your own ones. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/layout-transitions + */ layout?: | BaseAnimationBuilder | LayoutAnimationFunction | typeof BaseAnimationBuilder; + /** + * Lets you animate an element when it's added to or removed from the view hierarchy. + * + * You can use the predefined entering animations (eg. `FadeIn`, `SlideInLeft`) or create your own ones. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/entering-exiting-animations + */ entering?: EntryOrExitLayoutType; + /** + * Lets you animate an element when it's added to or removed from the view hierarchy. + * + * You can use the predefined entering animations (eg. `FadeOut`, `SlideOutRight`) or create your own ones. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/entering-exiting-animations + */ exiting?: EntryOrExitLayoutType; }; type SharedTransitionProps = { + /** + * Lets you animate components between two navigation screens. + * + * Assign the same `sharedTransitionTag` to [animated components](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animated-component) on two different navigation screens to create a shared transition. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview + * @experimental + */ sharedTransitionTag?: string; + /** + * Lets you create a custom shared transition animation. + * + * Used alongside `SharedTransition.custom()` method. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/shared-element-transitions/overview + * @experimental + */ sharedTransitionStyle?: SharedTransition; }; @@ -115,6 +152,11 @@ export type AnimatedProps = RestProps & AnimatedStyleProps & LayoutProps & SharedTransitionProps & { + /** + * Lets you animate component props. + * + * @see https://docs.swmansion.com/react-native-reanimated/docs/core/useAnimatedProps + */ animatedProps?: Partial>; }; @@ -150,12 +192,12 @@ export type AdaptTransforms = { }; /** - * @deprecated Please use `TransformArrayItem` type instead. + * @deprecated Please use {@link TransformArrayItem} type instead. */ export type TransformStyleTypes = TransformArrayItem; /** - * @deprecated Please use `AnimatedStyle` type instead. + * @deprecated Please use {@link AnimatedStyle} type instead. */ export type AnimateStyle