react-ui-animate 3.0.0-rc.2 → 3.0.0-rc.3

package/README.md

@@ -2,114 +2,152 @@
 
 [![npm version](https://badge.fury.io/js/react-ui-animate.svg)](https://badge.fury.io/js/react-ui-animate)
 
-> React library for gestures and animation
+> Create smooth animations and interactive gestures in React applications effortlessly.
 
 ### Install
 
-Install with npm:
+You can install react-ui-animate via npm or yarn:
 
 ```sh
 npm i react-ui-animate
 ```
 
-or
-Install with yarn:
-
 ```sh
 yarn add react-ui-animate
 ```
 
 ### Getting Started
 
-`react-ui-animate` provides lots of easy to use APIs to create smooth animations and gestures.
+The `react-ui-animate` library provides a straightforward way to add animations and gestures to your React components. Here’s how you can get started quickly:
 
 ```javascript
-import { AnimatedBlock, useAnimatedValue } from "react-ui-animate";
+import { AnimatedBlock, useAnimatedValue } from 'react-ui-animate';
 
 export default function () {
-  const opacity = useAnimatedValue(0); // It initializes opacity object with value 0.
+  // Initialize an animated opacity value
+  const opacity = useAnimatedValue(0);
 
   return (
     <div>
-      {/* AnimatedBlock component can read useAnimatedValue() */}
+      {/* AnimatedBlock component uses the animated opacity value */}
       <AnimatedBlock
         style={{
           opacity: opacity.value, // using opacity with value property
           width: 100,
           padding: 20,
-          background: "#39F",
+          background: '#39F',
         }}
       >
         ANIMATED
       </AnimatedBlock>
 
-      {/* Assigning value to 1 auto animates from initialized value 0 to 1 smoothly */}
+      {/* Clicking the button changes the opacity smoothly to 1 */}
       <button onClick={() => (opacity.value = 1)}>Animate Me</button>
     </div>
   );
 }
 ```
 
-Animates opacity from 0 to 1.
+In this example, clicking the "Animate Me" button smoothly changes the opacity of the animated block from 0 to 1.
+
+### Key Features
 
 #### `useAnimatedValue()`
 
-`useAnimatedValue()` is very flexible and powerful hook that lets you define animated values. It accepts a value and returns a node with same value on `value` property. Whenever `value` property is assigned to another value, it auto animates from one value to another.
+The `useAnimatedValue()` hook is central to creating animations. It initializes an animated value and allows you to seamlessly update it to create dynamic effects.
 
 ```javascript
-const opacity = useAnimatedValue(0); // initialize with 0 opacity
+const opacity = useAnimatedValue(0); // Start with opacity set to 0
 
-...
+// Use in style
 style={{
-    opacity: opacity.value // access with `.value`
+  opacity: opacity.value, // Access the animated opacity value
 }}
-...
 
-...
-onClick={() => opacity.value = 1} // Assignment
-...
+// Update the value on user interaction
+onClick={() => (opacity.value = 1)} // Changes the opacity to 1
 ```
 
 #### `AnimatedBlock`
 
-`AnimatedBlock` is a `div` component which can accept the animation node from `useAnimatedValue()` hook.
+`AnimatedBlock` is a special component designed to work with `useAnimatedValue()`. It simplifies animating elements by directly using animated values.
 
 ```javascript
-const width = useAnimatedValue(100);
+const width = useAnimatedValue(100); // Start with a width of 100
 
 <AnimatedBlock
   style={{
     width: width.value,
     height: 100,
-    backgroundColor: "#39f",
+    backgroundColor: '#39f',
   }}
 />;
 ```
 
 #### `interpolate`
 
-The `interpolate()` function allows animated node value to map from input ranges to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.
+The `interpolate()` function is useful for mapping values from one range to another, enabling more complex animations.
 
 ```javascript
-import { useAnimatedValue, AnimatedBlock, interpolate } from "react-ui-animate";
+import { useAnimatedValue, AnimatedBlock, interpolate } from 'react-ui-animate';
 
-const width = useAnimatedValue(100);
+const width = useAnimatedValue(100); // Start with a width of 100
 
 <AnimatedBlock
   style={{
     width: width.value,
     height: 100,
-    backgroundColor: interpolate(width.value, [100, 200], ["red", "blue"]),
+    backgroundColor: interpolate(width.value, [100, 200], ['red', 'blue']),
   }}
 />;
 ```
 
-`backgroundColor` is interpolated from input range `[100, 200]` to output range `["red", "blue"]`. So, when the width changes from 100 to 200, `backgroundColor` will change from `red` to `blue`.
+In this example, as the width changes from 100 to 200, the background color smoothly transitions from red to blue.
+
+### Gestures
+
+The `react-ui-animate` library also provides several hooks for handling different types of gestures:
+
+1. `useDrag`: Handles drag gestures on elements.
+2. `useMouseMove`: Handles mouse movements.
+3. `useScroll`: Handles scrolling of the document.
+4. `useWheel`: Handles wheel rotation gestures.
+5. `useGesture`: Handles combinations of various gestures.
+
+**Example**: `useDrag`
+
+Here’s an example of using the useDrag hook to enable drag gestures:
+
+```jsx
+import { useAnimatedValue, AnimatedBlock, useDrag } from 'react-ui-animate';
+
+export const Draggable = () => {
+  const translateX = useAnimatedValue(0);
+
+  const bind = useDrag(function ({ down, movementX }) {
+    translateX.value = down ? movementX : 0;
+  });
+
+  return (
+    <AnimatedBlock
+      {...bind()}
+      style={{
+        width: 100,
+        height: 100,
+        backgroundColor: '#3399ff',
+        translateX: translateX.value, // Use translateX with animated value
+      }}
+    />
+  );
+};
+```
+
+In this example, the blue block can be dragged horizontally by clicking and dragging.
 
 ## Documentation
 
-The official documentation are now published at http://react-ui-animate.js.org/
+For detailed documentation and examples, visit the official [react-ui-animate documentation](http://react-ui-animate.js.org/).
 
 ## License
 
-MIT
+This library is licensed under the MIT License.

package/dist/animation/core/controllers/FluidValue.d.ts

@@ -28,5 +28,5 @@ export declare class FluidValue {
      * @param config - Optional configuration for the animation.
      * @param callback - Optional callback to be called after the animation ends.
      */
-    setValue(updatedValue: AssignValue, config?: FluidValueConfig, callback?: Fn<ResultType, void>): void;
+    setValue(updatedValue: AssignValue, callback?: Fn<ResultType, void>): void;
 }

package/dist/animation/core/index.d.ts

@@ -6,6 +6,6 @@ export { isFluidValue } from './helpers/isFluidValue';
 export { Easing } from './easing/Easing';
 export { interpolate } from './interpolation/Interpolation';
 export { FluidValue } from './controllers/FluidValue';
-export type { FluidValueConfig } from './types/animation';
+export type { FluidValueConfig, Length } from './types/animation';
 export type { UseMountConfig } from './react/useMount';
 export type { ExtrapolateConfig } from './interpolation/Interpolation';

package/dist/animation/core/react/useFluidValue.d.ts

@@ -1,9 +1,9 @@
 import { FluidValue } from '../controllers/FluidValue';
-import type { FluidValueConfig, Length, AssignValue, OnUpdateCallback } from '../types/animation';
+import type { FluidValueConfig, Length, OnUpdateFn } from '../types/animation';
 /**
  * useFluidValue
  *
  * @param value - initial value
  * @param config - the config object for `FluidValue`
  */
-export declare const useFluidValue: (value: Length, config?: FluidValueConfig) => [FluidValue, (updateValue: AssignValue, config?: FluidValueConfig, callback?: OnUpdateCallback) => void];
+export declare const useFluidValue: (value: Length, config?: FluidValueConfig) => [FluidValue, OnUpdateFn];

package/dist/animation/core/react/useMount.d.ts

@@ -1,9 +1,9 @@
 import { FluidValue } from '../controllers/FluidValue';
-import type { AssignValue, FluidValueConfig } from '../types/animation';
+import type { FluidValueConfig } from '../types/animation';
 export interface UseMountConfig {
     from: number;
-    enter: number | AssignValue;
-    exit: number | AssignValue;
+    enter: number;
+    exit: number;
     enterConfig?: FluidValueConfig;
     exitConfig?: FluidValueConfig;
     config?: FluidValueConfig;

package/dist/animation/lib/animationType.d.ts

@@ -1,15 +1,16 @@
+import { FluidValueConfig } from '../core';
 export declare const AnimationConfigUtils: {
-    ELASTIC: import("../core").FluidValueConfig;
-    BOUNCE: import("../core").FluidValueConfig;
-    EASE: import("../core").FluidValueConfig;
-    STIFF: import("../core").FluidValueConfig;
-    WOOBLE: import("../core").FluidValueConfig;
-    EASE_IN: import("../core").FluidValueConfig;
-    EASE_OUT: import("../core").FluidValueConfig;
-    EASE_IN_OUT: import("../core").FluidValueConfig;
-    POWER1: import("../core").FluidValueConfig;
-    POWER2: import("../core").FluidValueConfig;
-    POWER3: import("../core").FluidValueConfig;
-    POWER4: import("../core").FluidValueConfig;
-    LINEAR: import("../core").FluidValueConfig;
+    ELASTIC: FluidValueConfig;
+    BOUNCE: FluidValueConfig;
+    EASE: FluidValueConfig;
+    STIFF: FluidValueConfig;
+    WOOBLE: FluidValueConfig;
+    EASE_IN: FluidValueConfig;
+    EASE_OUT: FluidValueConfig;
+    EASE_IN_OUT: FluidValueConfig;
+    POWER1: FluidValueConfig;
+    POWER2: FluidValueConfig;
+    POWER3: FluidValueConfig;
+    POWER4: FluidValueConfig;
+    LINEAR: FluidValueConfig;
 };

package/dist/animation/lib/getInitialConfig.d.ts

@@ -1,3 +1,4 @@
 import { FluidValueConfig } from '../core';
-export type InitialConfigType = 'linear' | 'easein' | 'easeout' | 'easeinout' | 'ease' | 'power1' | 'power2' | 'power3' | 'power4' | 'elastic' | 'stiff' | 'wooble' | 'bounce';
+type InitialConfigType = 'linear' | 'easein' | 'easeout' | 'easeinout' | 'ease' | 'power1' | 'power2' | 'power3' | 'power4' | 'elastic' | 'stiff' | 'wooble' | 'bounce';
 export declare const getInitialConfig: (animationType?: InitialConfigType) => FluidValueConfig;
+export {};

package/dist/animation/lib/index.d.ts

@@ -3,3 +3,4 @@ export { AnimatedBlock, AnimatedImage, AnimatedInline, MountedBlock, ScrollableB
 export { useAnimatedValue, UseAnimatedValueConfig } from './useAnimatedValue';
 export { useMountedValue } from './useMountedValue';
 export { AnimationConfigUtils } from './animationType';
+export { withSpring, withTiming, withSequence, withDelay, } from './withFunctions';

package/dist/animation/lib/interpolation.d.ts

@@ -1,4 +1,5 @@
 import { ExtrapolateConfig, FluidValue } from '../core';
+import { ValueType } from './useAnimatedValue';
 /**
  * Maps the input range to the given output range using the specified extrapolation configuration.
  * The function ensures that the value is either a number or a FluidValue.
@@ -10,7 +11,7 @@ import { ExtrapolateConfig, FluidValue } from '../core';
  * @returns - The interpolated value, which will be a number or FluidValue.
  * @throws - Will throw an error if the value is not a number or FluidValue.
  */
-export declare function interpolate(value: FluidValue | number | string | undefined, inputRange: Array<number>, outputRange: Array<number | string>, extrapolateConfig?: ExtrapolateConfig): any;
+export declare function interpolate(value: FluidValue | ValueType | number, inputRange: Array<number>, outputRange: Array<number | string>, extrapolateConfig?: ExtrapolateConfig): any;
 /**
  * A shorthand function for interpolate that maps the input range [0, 1] to the given [minOutput, maxOutput].
  * The function ensures that the value is either a number or a FluidValue.
@@ -22,4 +23,4 @@ export declare function interpolate(value: FluidValue | number | string | undefi
  * @returns - The interpolated value, which will be a number or FluidValue.
  * @throws - Will throw an error if the value is not a number or FluidValue.
  */
-export declare function bInterpolate(value: FluidValue | number | string | undefined, minOutput: number | string, maxOutput: number | string, extrapolateConfig?: ExtrapolateConfig): any;
+export declare function bInterpolate(value: FluidValue | ValueType | number, minOutput: number | string, maxOutput: number | string, extrapolateConfig?: ExtrapolateConfig): any;

package/dist/animation/lib/modules/MountedBlock.d.ts

@@ -1,11 +1,12 @@
 import * as React from 'react';
-import { FluidValue, FluidValueConfig } from '../../core';
+import { FluidValueConfig } from '../../core';
+import { ValueType } from '../useAnimatedValue';
 interface MountedValueConfig extends FluidValueConfig {
 }
 interface MountedBlockProps {
     state: boolean;
     children: (animation: {
-        value: FluidValue;
+        value: ValueType;
     }) => React.ReactNode;
     from?: number;
     enter?: number;

package/dist/animation/lib/modules/ScrollableBlock.d.ts

@@ -1,9 +1,8 @@
 import * as React from 'react';
-import { UseAnimatedValueConfig } from '../useAnimatedValue';
-import { FluidValue } from '../../core';
+import { UseAnimatedValueConfig, ValueType } from '../useAnimatedValue';
 interface ScrollableBlockProps {
     children?: (animation: {
-        value?: FluidValue | string | number;
+        value: ValueType;
     }) => React.ReactNode;
     direction?: 'single' | 'both';
     threshold?: number;

package/dist/animation/lib/modules/TransitionBlock.d.ts

@@ -1,10 +1,9 @@
 import * as React from 'react';
-import { UseAnimatedValueConfig } from '../useAnimatedValue';
-import { FluidValue } from '../../core';
+import { UseAnimatedValueConfig, ValueType } from '../useAnimatedValue';
 interface TransitionBlockProps {
     state: boolean;
     children: (animation: {
-        value?: FluidValue | string | number;
+        value: ValueType;
     }) => React.ReactNode;
     config?: UseAnimatedValueConfig;
 }

package/dist/animation/lib/useAnimatedValue.d.ts

@@ -1,7 +1,12 @@
-import { FluidValueConfig, FluidValue } from '../core';
+import { FluidValueConfig } from '../core';
 type Length = number | string;
 export interface UseAnimatedValueConfig extends FluidValueConfig {
 }
+type AssignValue = {
+    toValue: Length;
+    config?: UseAnimatedValueConfig;
+};
+export type ValueType = Length | AssignValue | ((update: (next: AssignValue) => Promise<any>) => void);
 /**
  * `useAnimatedValue` returns an animation value with `.value` and `.currentValue` property which is
  * initialized when passed to argument (`initialValue`). The retured value persist until the lifetime of
@@ -11,7 +16,7 @@ export interface UseAnimatedValueConfig extends FluidValueConfig {
  * @param { UseAnimatedValueConfig } config - Animation configuration object.
  */
 export declare function useAnimatedValue(initialValue: Length, config?: UseAnimatedValueConfig): {
-    value: FluidValue | string | number | undefined;
+    value: ValueType;
     currentValue: number | string;
 };
 export {};

package/dist/animation/lib/withFunctions.d.ts

@@ -0,0 +1,63 @@
+import type { FluidValueConfig, Length } from '../core';
+interface WithSpringConfig extends Pick<FluidValueConfig, 'mass' | 'friction' | 'tension'> {
+}
+/**
+ * Creates a spring animation configuration.
+ * @param {Length} toValue - The target value of the animation.
+ * @param {WithSpringConfig} [config=AnimationConfigUtils.ELASTIC] - Optional spring configuration.
+ * @returns {{ toValue: Length; config: WithSpringConfig }}
+ */
+export declare const withSpring: (toValue: Length, config?: WithSpringConfig) => {
+    toValue: Length;
+    config: WithSpringConfig;
+};
+interface WithTimingConfig extends Pick<FluidValueConfig, 'duration' | 'easing'> {
+}
+/**
+ * Creates a timing animation configuration.
+ * @param {Length} toValue - The target value of the animation.
+ * @param {WithTimingConfig} [config={ duration: 250 }] - Optional timing configuration.
+ * @returns {{ toValue: Length; config: WithTimingConfig }}
+ */
+export declare const withTiming: (toValue: Length, config?: WithTimingConfig) => {
+    toValue: Length;
+    config: WithTimingConfig;
+};
+/**
+ * Creates a sequence of animations that run one after another.
+ * @param {Array<{ toValue: Length; config?: FluidValueConfig }>} configs - An array of animation configurations.
+ * @returns {Function} An async function that runs the animations in sequence.
+ */
+export declare const withSequence: ([...configs]: Array<{
+    toValue: Length;
+    config?: FluidValueConfig;
+}>) => (next: (arg: {
+    toValue: Length;
+    config?: FluidValueConfig;
+}) => void) => Promise<void>;
+/**
+ * Adds a delay before the given animation.
+ * @param {number} delay - The delay in milliseconds.
+ * @param {{ toValue: Length; config?: FluidValueConfig }} animation - The animation configuration ( withTiming | withSpring )
+ * @returns {{ toValue: Length; config: FluidValueConfig }} The updated animation configuration with delay.
+ */
+export declare const withDelay: (delay: number, animation: {
+    toValue: Length;
+    config?: FluidValueConfig;
+}) => {
+    config: {
+        delay: number;
+        mass?: number;
+        tension?: number;
+        friction?: number;
+        duration?: number;
+        easing?: import("../core/types/common").Fn<number, number>;
+        immediate?: boolean;
+        restDistance?: number;
+        onChange?: import("../core/types/common").Fn<number, void>;
+        onRest?: import("../core/types/common").Fn<import("../core/types/animation").ResultType, void>;
+        onStart?: import("../core/types/common").Fn<number, void>;
+    };
+    toValue: Length;
+};
+export {};

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { AnimatedBlock, AnimatedImage, AnimatedInline, AnimationConfigUtils, Mou
 export { bInterpolate, interpolate } from './animation/lib';
 export { useAnimatedValue, useMountedValue } from './animation/lib';
 export { delay } from './utils';
+export { withSpring, withTiming, withSequence, withDelay, } from './animation/lib';
 export { useMeasure, useOutsideClick, useWindowDimension } from './hooks';
 export { useDrag, useGesture, useMouseMove, useScroll, useWheel, } from './gestures/hooks';
 export { bin, clamp, mix, rubberClamp, move, snapTo } from './gestures/helpers';