Merge pull request #3294 from motiondivision/feature/delay-children

Adding support for `stagger` via `delayChildren`

Author: mattgperry

dev/react/src/examples/AnimatePresence-variants.tsx

@@ -1,4 +1,4 @@
-import { motion, AnimatePresence } from "framer-motion"
+import { AnimatePresence, motion, stagger } from "framer-motion"
 import { useEffect, useState } from "react"
 
 /**
@@ -26,14 +26,13 @@ const itemVariants = {
 const listVariants = {
     open: {
         opacity: 1,
-        transition: { staggerChildren: 1, when: "beforeChildren" },
+        transition: { delayChildren: stagger(1), when: "beforeChildren" },
     },
     closed: {
         opacity: 0,
         transition: {
             when: "afterChildren",
-            staggerChildren: 0.3,
-            staggerDirection: -1,
+            delayChildren: stagger(0.3, { from: "last" }),
         },
     },
 }

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

@@ -1,7 +1,7 @@
+import { stagger } from "motion-dom"
 import { nextFrame } from "../../gestures/__tests__/utils"
 import { animate } from "../animate"
 import { defaultOptions } from "../animators/waapi/__tests__/setup"
-import { stagger } from "../utils/stagger"
 
 describe("animate() with WAAPI", () => {
     test("Can override transition options per-value", async () => {

packages/framer-motion/src/animation/interfaces/visual-element-variant.ts

@@ -1,3 +1,4 @@
+import { DynamicOption } from "motion-dom"
 import { resolveVariant } from "../../render/utils/resolve-dynamic-variants"
 import { VisualElement } from "../../render/VisualElement"
 import { VisualElementAnimationOptions } from "./types"
@@ -47,7 +48,8 @@ export function animateVariant(
                   return animateChildren(
                       visualElement,
                       variant,
-                      delayChildren + forwardDelay,
+                      forwardDelay,
+                      delayChildren,
                       staggerChildren,
                       staggerDirection,
                       options
@@ -75,20 +77,24 @@ export function animateVariant(
 function animateChildren(
     visualElement: VisualElement,
     variant: string,
-    delayChildren = 0,
+    delay: number = 0,
+    delayChildren: number | DynamicOption<number> = 0,
     staggerChildren = 0,
     staggerDirection = 1,
     options: VisualElementAnimationOptions
 ) {
     const animations: Promise<any>[] = []
+    const numChildren = visualElement.variantChildren!.size
 
-    const maxStaggerDuration =
-        (visualElement.variantChildren!.size - 1) * staggerChildren
+    const maxStaggerDuration = (numChildren - 1) * staggerChildren
+    const delayIsFunction = typeof delayChildren === "function"
 
-    const generateStaggerDuration =
+    const generateStaggerDuration = delayIsFunction
+        ? (i: number) => delayChildren(i, numChildren)
+        : // Support deprecated staggerChildren
         staggerDirection === 1
-            ? (i = 0) => i * staggerChildren
-            : (i = 0) => maxStaggerDuration - i * staggerChildren
+        ? (i = 0) => i * staggerChildren
+        : (i = 0) => maxStaggerDuration - i * staggerChildren
 
     Array.from(visualElement.variantChildren!)
         .sort(sortByTreeOrder)
@@ -97,7 +103,10 @@ function animateChildren(
             animations.push(
                 animateVariant(child, variant, {
                     ...options,
-                    delay: delayChildren + generateStaggerDuration(i),
+                    delay:
+                        delay +
+                        (delayIsFunction ? 0 : delayChildren) +
+                        generateStaggerDuration(i),
                 }).then(() => child.notify("AnimationComplete", variant))
             )
         })

packages/framer-motion/src/animation/sequence/__tests__/index.test.ts

@@ -1,6 +1,5 @@
-import { motionValue, spring } from "motion-dom"
+import { motionValue, spring, stagger } from "motion-dom"
 import { Easing } from "motion-utils"
-import { stagger } from "../../utils/stagger"
 import { createAnimationsFromSequence } from "../create"
 
 describe("createAnimationsFromSequence", () => {

packages/framer-motion/src/dom.ts

@@ -15,6 +15,5 @@ export * from "./animation/sequence/types"
 /**
  * Utils
  */
-export { stagger } from "./animation/utils/stagger"
 export { delayInSeconds as delay, DelayedFunction } from "./utils/delay"
 export * from "./utils/distance"

packages/framer-motion/src/motion/__tests__/delay.test.tsx

@@ -1,4 +1,4 @@
-import { motionValue, Variants } from "motion-dom"
+import { motionValue, stagger, Variants } from "motion-dom"
 import { motion } from "../.."
 import { render } from "../../jest.setup"
 
@@ -165,6 +165,43 @@ describe("delay attr", () => {
             requestAnimationFrame(() => resolve(x.get()))
         })
 
+        return expect(promise).resolves.toBe(0)
+    })
+    test("in variant children via delayChildren: stagger(interval)", async () => {
+        const promise = new Promise((resolve) => {
+            const x = motionValue(0)
+
+            const parent: Variants = {
+                visible: {
+                    x: 10,
+                    transition: {
+                        delay: 0,
+                        delayChildren: stagger(1),
+                        type: false,
+                    },
+                },
+            }
+
+            const child: Variants = {
+                visible: {
+                    x: 10,
+                    transition: { type: false },
+                },
+            }
+
+            const Component = () => (
+                <motion.div variants={parent} animate="visible">
+                    <motion.div variants={child} />
+                    <motion.div variants={child} style={{ x }} />
+                </motion.div>
+            )
+
+            const { rerender } = render(<Component />)
+            rerender(<Component />)
+
+            requestAnimationFrame(() => resolve(x.get()))
+        })
+
         return expect(promise).resolves.toBe(0)
     })
 })

packages/framer-motion/src/motion/__tests__/static-prop.test.tsx

@@ -1,4 +1,4 @@
-import { motionValue } from "motion-dom"
+import { motionValue, stagger } from "motion-dom"
 import { useEffect } from "react"
 import { motion, useMotionValue } from "../.."
 import { MotionConfig } from "../../components/MotionConfig"
@@ -181,9 +181,8 @@ describe("isStatic prop", () => {
 
     it("accepts externally-defined transition", () => {
         const transition = {
-            staggerChildren: 10,
+            delayChildren: stagger(10, { from: "last" }),
             when: "beforeChildren",
-            staggerDirection: 1,
         }
         function Test() {
             return (

packages/framer-motion/src/motion/__tests__/variant.test.tsx

@@ -1,4 +1,4 @@
-import { motionValue, Variants } from "motion-dom"
+import { motionValue, stagger, Variants } from "motion-dom"
 import { Fragment, memo, useEffect, useState } from "react"
 import { frame, motion, MotionConfig, useMotionValue } from "../../"
 import { nextFrame } from "../../gestures/__tests__/utils"
@@ -594,7 +594,110 @@ describe("animate prop as variant", () => {
         return expect(promise).resolves.toEqual([0.3, 0.5])
     })
 
-    test("Child variants correctly calculate delay based on staggerChildren", async () => {
+    test("Child variants correctly calculate delay based on delayChildren: stagger()", async () => {
+        const isCorrectlyStaggered = await new Promise((resolve) => {
+            const childVariants = {
+                hidden: { opacity: 0 },
+                visible: { opacity: 1, transition: { duration: 0.1 } },
+            }
+
+            function Component() {
+                const a = useMotionValue(0)
+                const b = useMotionValue(0)
+
+                useEffect(
+                    () =>
+                        a.on("change", (latest) => {
+                            if (latest >= 1 && b.get() === 0) resolve(true)
+                        }),
+                    [a, b]
+                )
+
+                return (
+                    <motion.div
+                        variants={{
+                            hidden: {},
+                            visible: {
+                                x: 100,
+                                transition: { delayChildren: stagger(0.15) },
+                            },
+                        }}
+                        initial="hidden"
+                        animate="visible"
+                    >
+                        <motion.div
+                            variants={childVariants}
+                            style={{ opacity: a }}
+                        />
+                        <motion.div
+                            variants={childVariants}
+                            style={{ opacity: b }}
+                        />
+                    </motion.div>
+                )
+            }
+
+            const { rerender } = render(<Component />)
+            rerender(<Component />)
+        })
+
+        expect(isCorrectlyStaggered).toBe(true)
+    })
+
+    test("Child variants with value-specific transitions correctly calculate delay based on delayChildren: stagger()", async () => {
+        const isCorrectlyStaggered = await new Promise((resolve) => {
+            const childVariants = {
+                hidden: { opacity: 0 },
+                visible: {
+                    opacity: 1,
+                    transition: { opacity: { duration: 0.1 } },
+                },
+            }
+
+            function Component() {
+                const a = useMotionValue(0)
+                const b = useMotionValue(0)
+
+                useEffect(
+                    () =>
+                        a.on("change", (latest) => {
+                            if (latest >= 1 && b.get() === 0) resolve(true)
+                        }),
+                    [a, b]
+                )
+
+                return (
+                    <motion.div
+                        variants={{
+                            hidden: {},
+                            visible: {
+                                x: 100,
+                                transition: { delayChildren: stagger(0.15) },
+                            },
+                        }}
+                        initial="hidden"
+                        animate="visible"
+                    >
+                        <motion.div
+                            variants={childVariants}
+                            style={{ opacity: a }}
+                        />
+                        <motion.div
+                            variants={childVariants}
+                            style={{ opacity: b }}
+                        />
+                    </motion.div>
+                )
+            }
+
+            const { rerender } = render(<Component />)
+            rerender(<Component />)
+        })
+
+        expect(isCorrectlyStaggered).toBe(true)
+    })
+
+    test("Child variants correctly calculate delay based on staggerChildren (deprecated)", async () => {
         const isCorrectlyStaggered = await new Promise((resolve) => {
             const childVariants = {
                 hidden: { opacity: 0 },
@@ -644,7 +747,7 @@ describe("animate prop as variant", () => {
         expect(isCorrectlyStaggered).toBe(true)
     })
 
-    test("Child variants with value-specific transitions correctly calculate delay based on staggerChildren", async () => {
+    test("Child variants with value-specific transitions correctly calculate delay based on staggerChildren (deprecated)", async () => {
         const isCorrectlyStaggered = await new Promise((resolve) => {
             const childVariants = {
                 hidden: { opacity: 0 },

packages/motion-dom/src/animation/types.ts

@@ -378,11 +378,13 @@ export interface AnimationOrchestrationOptions {
 
     /**
      * 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.
+     * (in seconds). You can add the `transition` property to both the `motion.div` and the
+     * `variant` directly. Adding it to the `variant` generally offers more flexibility,
+     * as it allows you to customize the delay per visual state.
      *
      * @public
      */
-    delayChildren?: number
+    delayChildren?: number | DynamicOption<number>
 
     /**
      * When using variants, animations of child components can be staggered by this
@@ -394,7 +396,7 @@ export interface AnimationOrchestrationOptions {
      *
      * The calculated stagger delay will be added to `delayChildren`.
      *
-     * @public
+     * @deprecated - Use `delayChildren: stagger(interval)` instead.
      */
     staggerChildren?: number
 
@@ -404,7 +406,7 @@ export interface AnimationOrchestrationOptions {
      * A value of `1` staggers from the first to the last while `-1`
      * staggers from the last to the first.
      *
-     * @public
+     * @deprecated - Use `delayChildren: stagger(interval, { from: "last" })` instead.
      */
     staggerDirection?: number
 }

packages/motion-dom/src/index.ts

@@ -88,6 +88,7 @@ export * from "./utils/mix/number"
 export * from "./utils/mix/types"
 export * from "./utils/mix/visibility"
 export * from "./utils/resolve-elements"
+export * from "./utils/stagger"
 export * from "./utils/supports/flags"
 export * from "./utils/supports/linear-easing"
 export * from "./utils/supports/scroll-timeline"