Merge pull request #2045 from framer/feature/duration

Adding `.duration` to `animate()`

packages/framer-motion-3d/src/render/__tests__/index.test.tsx

@@ -1,4 +1,4 @@
-import { ResolvedValues } from "framer-motion"
+import { ResolvedValues, sync } from "framer-motion"
 import * as React from "react"
 import { useEffect, useRef } from "react"
 import { Euler, Vector3 } from "three"
@@ -240,7 +240,7 @@ describe("motion for three", () => {
             }
 
             ReactThreeTestRenderer.create(<Component />)
-            setTimeout(() => resolve([x.get(), y.get()]), 5)
+            sync.update(() => resolve([x.get(), y.get()]))
         })
 
         expect(result[0]).toEqual(100)

packages/framer-motion/src/animation/GroupPlaybackControls.ts

@@ -1,6 +1,6 @@
 import { AnimationPlaybackControls } from "./types"
 
-type PropNames = "time" | "speed"
+type PropNames = "time" | "speed" | "duration"
 
 export class GroupPlaybackControls implements AnimationPlaybackControls {
     animations: AnimationPlaybackControls[]
@@ -44,6 +44,14 @@ export class GroupPlaybackControls implements AnimationPlaybackControls {
         this.setAll("speed", speed)
     }
 
+    get duration() {
+        let max = 0
+        for (let i = 0; i < this.animations.length; i++) {
+            max = Math.max(max, this.animations[i].duration)
+        }
+        return max
+    }
+
     private runAll(
         methodName: keyof Omit<AnimationPlaybackControls, PropNames | "then">
     ) {

packages/framer-motion/src/animation/__tests__/GroupPlaybackControls.test.ts

@@ -7,6 +7,7 @@ function createTestAnimationControls(
     return {
         time: 1,
         speed: 1,
+        duration: 10,
         stop: () => {},
         play: () => {},
         pause: () => {},
@@ -193,4 +194,26 @@ describe("GroupPlaybackControls", () => {
         expect(a.speed).toEqual(-1)
         expect(b.speed).toEqual(-1)
     })
+
+    test("Gets max duration", async () => {
+        const a = createTestAnimationControls({
+            duration: 3,
+        })
+        const b = createTestAnimationControls({
+            duration: 2,
+        })
+        const c = createTestAnimationControls({
+            duration: 1,
+        })
+
+        const controls = new GroupPlaybackControls([a, b, c])
+
+        expect(controls.duration).toEqual(3)
+    })
+
+    test("Returns zero for no animations", async () => {
+        const controls = new GroupPlaybackControls([])
+
+        expect(controls.duration).toEqual(0)
+    })
 })

packages/framer-motion/src/animation/__tests__/animate-waapi.test.tsx

@@ -118,6 +118,15 @@ describe("animate() with WAAPI", () => {
         )
     })
 
+    test("Returns duration correctly", async () => {
+        const animation = animate(
+            document.createElement("div"),
+            { opacity: 1 },
+            { duration: 2, opacity: { duration: 3 } }
+        )
+        expect(animation.duration).toEqual(3)
+    })
+
     test("Can accept timeline sequences", async () => {
         const a = document.createElement("div")
         const b = document.createElement("div")

packages/framer-motion/src/animation/animators/__tests__/instant.test.ts

@@ -74,4 +74,18 @@ describe("instantAnimation", () => {
         expect(onUpdate).toBeCalledWith(1)
         expect(onComplete).toBeCalled()
     })
+
+    test("Returns duration: 0", async () => {
+        const animation = createInstantAnimation({
+            delay: 0,
+            keyframes: [0, 1],
+        })
+        expect(animation.duration).toEqual(0)
+
+        const animationWithDelay = createInstantAnimation({
+            delay: 0.2,
+            keyframes: [0, 1],
+        })
+        expect(animationWithDelay.duration).toEqual(0)
+    })
 })

packages/framer-motion/src/animation/animators/instant.ts

@@ -4,7 +4,7 @@ import { noop } from "../../utils/noop"
 
 export function createInstantAnimation<V>({
     keyframes,
-    delay: delayBy,
+    delay,
     onUpdate,
     onComplete,
 }: ValueAnimationOptions<V>): AnimationPlaybackControls {
@@ -22,6 +22,7 @@ export function createInstantAnimation<V>({
         return {
             time: 0,
             speed: 1,
+            duration: 0,
             play: noop<void>,
             pause: noop<void>,
             stop: noop<void>,
@@ -34,10 +35,11 @@ export function createInstantAnimation<V>({
         }
     }
 
-    return delayBy
+    return delay
         ? animateValue({
               keyframes: [0, 1],
-              duration: delayBy,
+              duration: 0,
+              delay,
               onComplete: setValue,
           })
         : setValue()

packages/framer-motion/src/animation/animators/js/__tests__/animate.test.ts

@@ -1242,4 +1242,56 @@ describe("animate", () => {
 
         await animation
     })
+
+    test("Correctly returns duration", async () => {
+        expect(
+            animateValue({
+                keyframes: [0, 100],
+                duration: 1000,
+            }).duration
+        ).toEqual(1)
+    })
+
+    test("Correctly returns duration when delay is defined", () => {
+        expect(
+            animateValue({
+                keyframes: [0, 100],
+                delay: 1000,
+                duration: 1000,
+            }).duration
+        ).toEqual(1)
+    })
+
+    test("Correctly returns duration when repeat is defined", () => {
+        expect(
+            animateValue({
+                keyframes: [0, 100],
+                delay: 1000,
+                duration: 1000,
+                repeat: Infinity,
+            }).duration
+        ).toEqual(1)
+    })
+
+    test("Correctly returns duration when animation is spring", () => {
+        expect(
+            animateValue({
+                keyframes: [0, 100],
+                delay: 1000,
+                duration: 1000,
+                type: "spring",
+            }).duration
+        ).toEqual(1)
+    })
+
+    test("Correctly returns duration when animation is dynamic spring", () => {
+        expect(
+            animateValue({
+                keyframes: [0, 100],
+                stiffness: 200,
+                damping: 10,
+                type: "spring",
+            }).duration
+        ).toEqual(1.2)
+    })
 })

packages/framer-motion/src/animation/animators/js/index.ts

@@ -38,7 +38,8 @@ function calculateDuration(generator: KeyframeGenerator<unknown>) {
         duration += timeStep
         state = generator.next(duration)
     }
-    return duration
+
+    return duration >= maxDuration ? Infinity : duration
 }
 
 export interface MainThreadAnimationControls<V>
@@ -147,28 +148,30 @@ export function animateValue<V = number>({
         totalDuration = resolvedDuration * (repeat + 1) - repeatDelay
     }
 
-    let time = 0
+    let currentTime = 0
     const tick = (timestamp: number) => {
         if (startTime === null) return
 
         if (holdTime !== null) {
-            time = holdTime
+            currentTime = holdTime
         } else {
-            time = (timestamp - startTime) * speed
+            currentTime = (timestamp - startTime) * speed
         }
 
         // Rebase on delay
-        time = Math.max(time - delay, 0)
+        const timeWithoutDelay = currentTime - delay
+        const isInDelayPhase = timeWithoutDelay < 0
+        currentTime = Math.max(timeWithoutDelay, 0)
 
         /**
          * If this animation has finished, set the current time
          * to the total duration.
          */
         if (playState === "finished" && holdTime === null) {
-            time = totalDuration
+            currentTime = totalDuration
         }
 
-        let elapsed = time
+        let elapsed = currentTime
 
         let frameGenerator = generator
 
@@ -178,7 +181,7 @@ export function animateValue<V = number>({
              * than duration we'll get values like 2.5 (midway through the
              * third iteration)
              */
-            const progress = time / resolvedDuration
+            const progress = currentTime / resolvedDuration
 
             /**
              * Get the current iteration (0 indexed). For instance the floor of
@@ -222,30 +225,37 @@ export function animateValue<V = number>({
 
             let p = clamp(0, 1, iterationProgress)
 
-            if (time > totalDuration) {
+            if (currentTime > totalDuration) {
                 p = repeatType === "reverse" && iterationIsOdd ? 1 : 0
             }
 
             elapsed = p * resolvedDuration
         }
 
-        const state = frameGenerator.next(elapsed)
+        /**
+         * If we're in negative time, set state as the initial keyframe.
+         * This prevents delay: x, duration: 0 animations from finishing
+         * instantly.
+         */
+        const state = isInDelayPhase
+            ? { done: false, value: keyframes[0] }
+            : frameGenerator.next(elapsed)
 
         if (mapNumbersToKeyframes) {
             state.value = mapNumbersToKeyframes(state.value)
         }
 
         let { done } = state
 
-        if (calculatedDuration !== null) {
-            done = time >= totalDuration
+        if (!isInDelayPhase && calculatedDuration !== null) {
+            done = currentTime >= totalDuration
         }
 
         const isAnimationFinished =
             holdTime === null &&
             (playState === "finished" ||
                 (playState === "running" && done) ||
-                (speed < 0 && time <= 0))
+                (speed < 0 && currentTime <= 0))
 
         if (onUpdate) {
             onUpdate(state.value)
@@ -311,33 +321,41 @@ export function animateValue<V = number>({
             return currentFinishedPromise.then(resolve, reject)
         },
         get time() {
-            return millisecondsToSeconds(time)
+            return millisecondsToSeconds(currentTime)
         },
         set time(newTime: number) {
             newTime = secondsToMilliseconds(newTime)
 
-            time = newTime
+            currentTime = newTime
             if (holdTime !== null || !animationDriver || speed === 0) {
                 holdTime = newTime
             } else {
                 startTime = animationDriver.now() - newTime / speed
             }
         },
+        get duration() {
+            const duration =
+                generator.calculatedDuration === null
+                    ? calculateDuration(generator)
+                    : generator.calculatedDuration
+
+            return millisecondsToSeconds(duration)
+        },
         get speed() {
             return speed
         },
         set speed(newSpeed: number) {
             if (newSpeed === speed || !animationDriver) return
             speed = newSpeed
-            controls.time = millisecondsToSeconds(time)
+            controls.time = millisecondsToSeconds(currentTime)
         },
         get state() {
             return playState
         },
         play,
         pause: () => {
             playState = "paused"
-            holdTime = time
+            holdTime = currentTime
         },
         stop: () => {
             hasStopped = true

packages/framer-motion/src/animation/animators/waapi/create-accelerated-animation.ts

@@ -169,6 +169,9 @@ export function createAcceleratedAnimation(
         set speed(newSpeed: number) {
             animation.playbackRate = newSpeed
         },
+        get duration() {
+            return millisecondsToSeconds(duration)
+        },
         play: () => {
             if (hasStopped) return
             animation.play()

packages/framer-motion/src/animation/interfaces/motion-value.ts

@@ -73,19 +73,6 @@ export const animateMotionValue = (
             },
         }
 
-        if (
-            !isOriginAnimatable ||
-            !isTargetAnimatable ||
-            instantAnimationState.current ||
-            valueTransition.type === false
-        ) {
-            /**
-             * If we can't animate this value, or the global instant animation flag is set,
-             * or this is simply defined as an instant transition, return an instant transition.
-             */
-            return createInstantAnimation(options)
-        }
-
         /**
          * If there's no transition defined for this value, we can generate
          * unqiue transition settings for this value.
@@ -110,6 +97,19 @@ export const animateMotionValue = (
             options.repeatDelay = secondsToMilliseconds(options.repeatDelay)
         }
 
+        if (
+            !isOriginAnimatable ||
+            !isTargetAnimatable ||
+            instantAnimationState.current ||
+            valueTransition.type === false
+        ) {
+            /**
+             * If we can't animate this value, or the global instant animation flag is set,
+             * or this is simply defined as an instant transition, return an instant transition.
+             */
+            return createInstantAnimation(options)
+        }
+
         /**
          * Animate via WAAPI if possible.
          */