react-ui-animate 3.0.0-rc.1 → 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/helpers/isDefined.d.ts

@@ -9,4 +9,4 @@
  * @returns {boolean} - Returns `true` if the value is neither `null` nor `undefined`, otherwise returns `false`.
  *
  */
-export declare const isDefined: <T>(value: T) => value is T & {};
+export declare const isDefined: <T>(value: T) => value is NonNullable<T>;

package/dist/animation/core/helpers/isFluidValue.d.ts

@@ -1,6 +1,10 @@
+import { FluidValue } from '../controllers/FluidValue';
 /**
- * isFluidValue to check the value is FluidValue or not
- * @param value - any
- * @returns - boolean
+ * Checks if the given value is of type FluidValue.
+ * A value is considered a FluidValue if it is defined,
+ * an object, and contains the '_subscribe' property.
+ *
+ * @param value - The value to check.
+ * @returns - True if the value is a FluidValue, false otherwise.
  */
-export declare const isFluidValue: (value: any) => any;
+export declare const isFluidValue: (value: unknown) => value is FluidValue;

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,20 +1,26 @@
 import { ExtrapolateConfig, FluidValue } from '../core';
+import { ValueType } from './useAnimatedValue';
 /**
- * interpolate functions maps input range to given output range
- * @param value - number | TransitionValue
- * @param inputRange - Array<number>
- * @param outputRange - Array<number | string>
- * @param extrapolateConfig - "clamp" | "identity" | "extend"
- * @returns - number | TransitionValue
+ * 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.
+ *
+ * @param value - The value to be interpolated, which must be a number or FluidValue.
+ * @param inputRange - An array of numbers defining the input range.
+ * @param outputRange - An array of numbers or strings defining the output range.
+ * @param extrapolateConfig - The extrapolation configuration, which can be "clamp", "identity", or "extend".
+ * @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: number | FluidValue, 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;
 /**
- * bInterpolate functions maps input range [0, 1] to given [minOutput, maxOutput]
- * sorthand function to interpolate input range [0, 1]
- * @param value - number | TransitionValue
- * @param minOutput - number | string
- * @param maxOutput - number | string
- * @param extrapolateConfig - "clamp" | "identity" | "extend"
- * @returns - number | TransitionValue
+ * 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.
+ *
+ * @param value - The value to be interpolated, which must be a number or FluidValue.
+ * @param minOutput - The minimum value of the output range, which can be a number or string.
+ * @param maxOutput - The maximum value of the output range, which can be a number or string.
+ * @param extrapolateConfig - The extrapolation configuration, which can be "clamp", "identity", or "extend".
+ * @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: number | FluidValue, 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';