framer-motion 10.2.3 → 10.2.4

package/dist/dom-entry.d.ts

@@ -28,6 +28,176 @@ declare type Sync = {
     [key in StepId]: Schedule;
 };
 
+/**
+ * Options for orchestrating the timing of animations.
+ *
+ * @public
+ */
+interface Orchestration {
+    /**
+     * Delay the animation by this duration (in seconds). Defaults to `0`.
+     *
+     * @remarks
+     * ```javascript
+     * const transition = {
+     *   delay: 0.2
+     * }
+     * ```
+     *
+     * @public
+     */
+    delay?: number;
+    /**
+     * Describes the relationship between the transition and its children. Set
+     * to `false` by default.
+     *
+     * @remarks
+     * When using variants, the transition can be scheduled in relation to its
+     * children with either `"beforeChildren"` to finish this transition before
+     * starting children transitions, `"afterChildren"` to finish children
+     * transitions before starting this transition.
+     *
+     * ```jsx
+     * const list = {
+     *   hidden: {
+     *     opacity: 0,
+     *     transition: { when: "afterChildren" }
+     *   }
+     * }
+     *
+     * const item = {
+     *   hidden: {
+     *     opacity: 0,
+     *     transition: { duration: 2 }
+     *   }
+     * }
+     *
+     * return (
+     *   <motion.ul variants={list} animate="hidden">
+     *     <motion.li variants={item} />
+     *     <motion.li variants={item} />
+     *   </motion.ul>
+     * )
+     * ```
+     *
+     * @public
+     */
+    when?: false | "beforeChildren" | "afterChildren" | string;
+    /**
+     * When using variants, children animations will start after this duration
+     * (in seconds). You can add the `transition` property to both the `Frame` and the `variant` directly. Adding it to the `variant` generally offers more flexibility, as it allows you to customize the delay per visual state.
+     *
+     * ```jsx
+     * const container = {
+     *   hidden: { opacity: 0 },
+     *   show: {
+     *     opacity: 1,
+     *     transition: {
+     *       delayChildren: 0.5
+     *     }
+     *   }
+     * }
+     *
+     * const item = {
+     *   hidden: { opacity: 0 },
+     *   show: { opacity: 1 }
+     * }
+     *
+     * return (
+     *   <motion.ul
+     *     variants={container}
+     *     initial="hidden"
+     *     animate="show"
+     *   >
+     *     <motion.li variants={item} />
+     *     <motion.li variants={item} />
+     *   </motion.ul>
+     * )
+     * ```
+     *
+     * @public
+     */
+    delayChildren?: number;
+    /**
+     * When using variants, animations of child components can be staggered by this
+     * duration (in seconds).
+     *
+     * For instance, if `staggerChildren` is `0.01`, the first child will be
+     * delayed by `0` seconds, the second by `0.01`, the third by `0.02` and so
+     * on.
+     *
+     * The calculated stagger delay will be added to `delayChildren`.
+     *
+     * ```jsx
+     * const container = {
+     *   hidden: { opacity: 0 },
+     *   show: {
+     *     opacity: 1,
+     *     transition: {
+     *       staggerChildren: 0.5
+     *     }
+     *   }
+     * }
+     *
+     * const item = {
+     *   hidden: { opacity: 0 },
+     *   show: { opacity: 1 }
+     * }
+     *
+     * return (
+     *   <motion.ol
+     *     variants={container}
+     *     initial="hidden"
+     *     animate="show"
+     *   >
+     *     <motion.li variants={item} />
+     *     <motion.li variants={item} />
+     *   </motion.ol>
+     * )
+     * ```
+     *
+     * @public
+     */
+    staggerChildren?: number;
+    /**
+     * The direction in which to stagger children.
+     *
+     * A value of `1` staggers from the first to the last while `-1`
+     * staggers from the last to the first.
+     *
+     * ```jsx
+     * const container = {
+     *   hidden: { opacity: 0 },
+     *   show: {
+     *     opacity: 1,
+     *     transition: {
+     *       staggerChildren: 0.5,
+     *       staggerDirection: -1
+     *     }
+     *   }
+     * }
+     *
+     * const item = {
+     *   hidden: { opacity: 0 },
+     *   show: { opacity: 1 }
+     * }
+     *
+     * return (
+     *   <motion.ul
+     *     variants={container}
+     *     initial="hidden"
+     *     animate="show"
+     *   >
+     *     <motion.li variants={item} size={50} />
+     *     <motion.li variants={item} size={50} />
+     *   </motion.ul>
+     * )
+     * ```
+     *
+     * @public
+     */
+    staggerDirection?: number;
+}
 interface Repeat {
     /**
      * The number of times to repeat the transition. Set to `Infinity` for perpetual repeating.
@@ -344,59 +514,298 @@ interface Spring extends Repeat {
      */
     velocity?: number;
 }
-
 /**
+ * An animation that decelerates a value based on its initial velocity,
+ * usually used to implement inertial scrolling.
+ *
+ * Optionally, `min` and `max` boundaries can be defined, and inertia
+ * will snap to these with a spring animation.
+ *
+ * This animation will automatically precalculate a target value,
+ * which can be modified with the `modifyTarget` property.
+ *
+ * This allows you to add snap-to-grid or similar functionality.
+ *
+ * Inertia is also the animation used for `dragTransition`, and can be configured via that prop.
+ *
  * @public
  */
-interface AnimationPlaybackControls {
-    currentTime?: number | null;
-    stop: () => void;
+interface Inertia {
+    /**
+     * Set `type` to animate using the inertia animation. Set to `"tween"` by
+     * default. This can be used for natural deceleration, like momentum scrolling.
+     *
+     * ```jsx
+     * <motion.div
+     *   animate={{ rotate: 180 }}
+     *   transition={{ type: "inertia", velocity: 50 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    type: "inertia";
+    /**
+     * A function that receives the automatically-calculated target and returns a new one. Useful for snapping the target to a grid.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{
+     *     power: 0,
+     *     // Snap calculated target to nearest 50 pixels
+     *     modifyTarget: target => Math.round(target / 50) * 50
+     *   }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    modifyTarget?(v: number): number;
+    /**
+     * If `min` or `max` is set, this affects the stiffness of the bounce
+     * spring. Higher values will create more sudden movement. Set to `500` by
+     * default.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{
+     *     min: 0,
+     *     max: 100,
+     *     bounceStiffness: 100
+     *   }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    bounceStiffness?: number;
+    /**
+     * If `min` or `max` is set, this affects the damping of the bounce spring.
+     * If set to `0`, spring will oscillate indefinitely. Set to `10` by
+     * default.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{
+     *     min: 0,
+     *     max: 100,
+     *     bounceDamping: 8
+     *   }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    bounceDamping?: number;
+    /**
+     * A higher power value equals a further target. Set to `0.8` by default.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{ power: 0.2 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    power?: number;
+    /**
+     * Adjusting the time constant will change the duration of the
+     * deceleration, thereby affecting its feel. Set to `700` by default.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{ timeConstant: 200 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    timeConstant?: number;
+    /**
+     * End the animation if the distance to the animation target is below this value, and the absolute speed is below `restSpeed`.
+     * When the animation ends, the value gets snapped to the animation target. Set to `0.01` by default.
+     * Generally the default values provide smooth animation endings, only in rare cases should you need to customize these.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{ restDelta: 10 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    restDelta?: number;
+    /**
+     * Minimum constraint. If set, the value will "bump" against this value (or immediately spring to it if the animation starts as less than this value).
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{ min: 0, max: 100 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    min?: number;
+    /**
+     * Maximum constraint. If set, the value will "bump" against this value (or immediately snap to it, if the initial animation value exceeds this value).
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragTransition={{ min: 0, max: 100 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    max?: number;
+    /**
+     * The value to animate from. By default, this is the current state of the animating value.
+     *
+     * ```jsx
+     * <Frame
+     *   drag
+     *   dragTransition={{ from: 50 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    from?: number | string;
+    /**
+     * The initial velocity of the animation.
+     * By default this is the current velocity of the component.
+     *
+     * ```jsx
+     * <motion.div
+     *   animate={{ rotate: 180 }}
+     *   transition={{ type: 'inertia', velocity: 200 }}
+     * />
+     * ```
+     *
+     * @public
+     */
+    velocity?: number;
+}
+/**
+ * Keyframes tweens between multiple `values`.
+ *
+ * These tweens can be arranged using the `duration`, `easings`, and `times` properties.
+ */
+interface Keyframes {
+    /**
+     * Set `type` to `"keyframes"` to animate using the keyframes animation.
+     * Set to `"tween"` by default. This can be used to animate between a series of values.
+     *
+     * @public
+     */
+    type: "keyframes";
+    /**
+     * An array of numbers between 0 and 1, where `1` represents the `total` duration.
+     *
+     * Each value represents at which point during the animation each item in the animation target should be hit, so the array should be the same length as `values`.
+     *
+     * Defaults to an array of evenly-spread durations.
+     *
+     * @public
+     */
+    times?: number[];
+    /**
+     * An array of easing functions for each generated tween, or a single easing function applied to all tweens.
+     *
+     * This array should be one item less than `values`, as these easings apply to the transitions *between* the `values`.
+     *
+     * ```jsx
+     * const transition = {
+     *   backgroundColor: {
+     *     type: 'keyframes',
+     *     easings: ['circIn', 'circOut']
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     */
+    ease?: Easing | Easing[];
+    /**
+     * The total duration of the animation. Set to `0.3` by default.
+     *
+     * ```jsx
+     * const transition = {
+     *   type: "keyframes",
+     *   duration: 2
+     * }
+     *
+     * <Frame
+     *   animate={{ opacity: 0 }}
+     *   transition={transition}
+     * />
+     * ```
+     *
+     * @public
+     */
+    duration?: number;
+    /**
+     * @public
+     */
+    repeatDelay?: number;
 }
 /**
  * @public
  */
-interface AnimationPlaybackLifecycles<V> {
-    onUpdate?: (latest: V) => void;
-    onPlay?: () => void;
-    onComplete?: () => void;
-    onRepeat?: () => void;
-    onStop?: () => void;
+interface Just {
+    /**
+     * @public
+     */
+    type: "just";
 }
 /**
  * @public
  */
-declare type AnimationOptions<V> = (Tween | Spring) & AnimationPlaybackLifecycles<V> & {
-    delay?: number;
-    type?: "tween" | "spring";
+interface None {
+    /**
+     * Set `type` to `false` for an instant transition.
+     *
+     * @public
+     */
+    type: false;
+}
+/**
+ * @public
+ */
+declare type PermissiveTransitionDefinition = {
+    [key: string]: any;
 };
 /**
- * Animate a single value or a `MotionValue`.
- *
- * The first argument is either a `MotionValue` to animate, or an initial animation value.
- *
- * The second is either a value to animate to, or an array of keyframes to animate through.
- *
- * The third argument can be either tween or spring options, and optional lifecycle methods: `onUpdate`, `onPlay`, `onComplete`, `onRepeat` and `onStop`.
- *
- * Returns `AnimationPlaybackControls`, currently just a `stop` method.
- *
- * ```javascript
- * const x = useMotionValue(0)
- *
- * useEffect(() => {
- *   const controls = animate(x, 100, {
- *     type: "spring",
- *     stiffness: 2000,
- *     onComplete: v => {}
- *   })
- *
- *   return controls.stop
- * })
- * ```
+ * @public
+ */
+declare type TransitionDefinition = Tween | Spring | Keyframes | Inertia | Just | None | PermissiveTransitionDefinition;
+declare type TransitionMap = Orchestration & {
+    [key: string]: TransitionDefinition;
+};
+/**
+ * Transition props
  *
  * @public
  */
-declare function animate<V>(from: MotionValue<V> | V, to: V | V[], transition?: AnimationOptions<V>): AnimationPlaybackControls;
+declare type Transition = (Orchestration & Repeat & TransitionDefinition) | (Orchestration & Repeat & TransitionMap);
+
+/**
+ * @public
+ */
+interface AnimationPlaybackControls {
+    currentTime: number;
+    stop: () => void;
+}
 
 /**
  * @public
@@ -560,6 +969,45 @@ declare class MotionValue<V = any> {
 }
 declare function motionValue<V>(init: V, options?: MotionValueOptions): MotionValue<V>;
 
+/**
+ * @public
+ */
+interface AnimationPlaybackLifecycles<V> {
+    onUpdate?: (latest: V) => void;
+    onPlay?: () => void;
+    onComplete?: () => void;
+    onRepeat?: () => void;
+    onStop?: () => void;
+}
+/**
+ * Animate a single value or a `MotionValue`.
+ *
+ * The first argument is either a `MotionValue` to animate, or an initial animation value.
+ *
+ * The second is either a value to animate to, or an array of keyframes to animate through.
+ *
+ * The third argument can be either tween or spring options, and optional lifecycle methods: `onUpdate`, `onPlay`, `onComplete`, `onRepeat` and `onStop`.
+ *
+ * Returns `AnimationPlaybackControls`, currently just a `stop` method.
+ *
+ * ```javascript
+ * const x = useMotionValue(0)
+ *
+ * useEffect(() => {
+ *   const controls = animate(x, 100, {
+ *     type: "spring",
+ *     stiffness: 2000,
+ *     onComplete: v => {}
+ *   })
+ *
+ *   return controls.stop
+ * })
+ * ```
+ *
+ * @public
+ */
+declare function animate<V>(from: MotionValue<V> | V, to: V | V[], transition?: Transition & AnimationPlaybackLifecycles<V>): AnimationPlaybackControls;
+
 interface AxisScrollInfo {
     current: number;
     offset: number[];

package/dist/es/animation/GroupPlaybackControls.mjs

@@ -0,0 +1,25 @@
+class GroupPlaybackControls {
+    constructor(animations) {
+        this.animations = animations.filter(Boolean);
+    }
+    /**
+     * TODO: Filter out cancelled or stopped animations before returning
+     */
+    get currentTime() {
+        return this.animations[0].currentTime;
+    }
+    /**
+     * currentTime assignment could reasonably run every frame, so
+     * we iterate using a normal loop to avoid function creation.
+     */
+    set currentTime(time) {
+        for (let i = 0; i < this.animations.length; i++) {
+            this.animations[i].currentTime = time;
+        }
+    }
+    stop() {
+        this.animations.forEach((controls) => controls.stop());
+    }
+}
+
+export { GroupPlaybackControls };

package/dist/es/animation/animate.mjs

@@ -1,6 +1,7 @@
 import { createMotionValueAnimation } from './index.mjs';
 import { motionValue } from '../value/index.mjs';
 import { isMotionValue } from '../value/utils/is-motion-value.mjs';
+import { GroupPlaybackControls } from './GroupPlaybackControls.mjs';
 
 /**
  * Animate a single value or a `MotionValue`.
@@ -32,9 +33,7 @@ import { isMotionValue } from '../value/utils/is-motion-value.mjs';
 function animate(from, to, transition = {}) {
     const value = isMotionValue(from) ? from : motionValue(from);
     value.start(createMotionValueAnimation("", value, to, transition));
-    return {
-        stop: () => value.stop(),
-    };
+    return value.animation || new GroupPlaybackControls([]);
 }
 
 export { animate };

package/dist/es/animation/create-instant-animation.mjs

@@ -1,11 +1,21 @@
-import { delay } from '../utils/delay.mjs';
+import { animateValue } from './js/index.mjs';
 
-function createInstantAnimation({ keyframes, elapsed, onUpdate, onComplete, }) {
+function createInstantAnimation({ keyframes, delay: delayBy, onUpdate, onComplete, }) {
     const setValue = () => {
         onUpdate && onUpdate(keyframes[keyframes.length - 1]);
         onComplete && onComplete();
+        return {
+            stop: () => { },
+            currentTime: 0,
+        };
     };
-    return elapsed ? { stop: delay(setValue, -elapsed) } : setValue();
+    return delayBy
+        ? animateValue({
+            keyframes: [0, 1],
+            duration: delayBy,
+            onComplete: setValue,
+        })
+        : setValue();
 }
 
 export { createInstantAnimation };

package/dist/es/animation/generators/inertia.mjs

@@ -0,0 +1,87 @@
+import { spring } from './spring/index.mjs';
+import { calcGeneratorVelocity } from './utils/velocity.mjs';
+
+function inertia({ keyframes, velocity = 0.0, power = 0.8, timeConstant = 325, bounceDamping = 10, bounceStiffness = 500, modifyTarget, min, max, restDelta = 0.5, restSpeed, }) {
+    const origin = keyframes[0];
+    const state = {
+        done: false,
+        value: origin,
+    };
+    const isOutOfBounds = (v) => (min !== undefined && v < min) || (max !== undefined && v > max);
+    const nearestBoundary = (v) => {
+        if (min === undefined)
+            return max;
+        if (max === undefined)
+            return min;
+        return Math.abs(min - v) < Math.abs(max - v) ? min : max;
+    };
+    let amplitude = power * velocity;
+    const ideal = origin + amplitude;
+    const target = modifyTarget === undefined ? ideal : modifyTarget(ideal);
+    /**
+     * If the target has changed we need to re-calculate the amplitude, otherwise
+     * the animation will start from the wrong position.
+     */
+    if (target !== ideal)
+        amplitude = target - origin;
+    const calcDelta = (t) => -amplitude * Math.exp(-t / timeConstant);
+    const calcLatest = (t) => target + calcDelta(t);
+    const applyFriction = (t) => {
+        const delta = calcDelta(t);
+        const latest = calcLatest(t);
+        state.done = Math.abs(delta) <= restDelta;
+        state.value = state.done ? target : latest;
+    };
+    /**
+     * Ideally this would resolve for t in a stateless way, we could
+     * do that by always precalculating the animation but as we know
+     * this will be done anyway we can assume that spring will
+     * be discovered during that.
+     */
+    let timeReachedBoundary;
+    let spring$1;
+    const checkCatchBoundary = (t) => {
+        if (!isOutOfBounds(state.value))
+            return;
+        timeReachedBoundary = t;
+        spring$1 = spring({
+            keyframes: [state.value, nearestBoundary(state.value)],
+            velocity: calcGeneratorVelocity(calcLatest, t, state.value),
+            damping: bounceDamping,
+            stiffness: bounceStiffness,
+            restDelta,
+            restSpeed,
+        });
+    };
+    checkCatchBoundary(0);
+    return {
+        calculatedDuration: null,
+        next: (t) => {
+            /**
+             * We need to resolve the friction to figure out if we need a
+             * spring but we don't want to do this twice per frame. So here
+             * we flag if we updated for this frame and later if we did
+             * we can skip doing it again.
+             */
+            let hasUpdatedFrame = false;
+            if (!spring$1 && timeReachedBoundary === undefined) {
+                hasUpdatedFrame = true;
+                applyFriction(t);
+                checkCatchBoundary(t);
+            }
+            /**
+             * If we have a spring and the provided t is beyond the moment the friction
+             * animation crossed the min/max boundary, use the spring.
+             */
+            if (timeReachedBoundary !== undefined && t > timeReachedBoundary) {
+                return spring$1.next(t - timeReachedBoundary);
+            }
+            else {
+                !hasUpdatedFrame && applyFriction(t);
+                return state;
+            }
+        },
+    };
+}
+
+export { inertia };