fix(core): auto-start useTransition when props is a function (#2287) (#2532)

Author: joshuaellis

.changeset/transition-function-autostart.md

@@ -0,0 +1,5 @@
+---
+'@react-spring/core': patch
+---
+
+Auto-start `useTransition` when `props` is a function. The function/`deps` form creates an internal `SpringRef`, which was assigned to every controller and treated like an injected ref, so the documented `useTransition(data, () => ({ ... }))` form never started its enter animation. `useTransition` now matches `useSpring`/`useSprings`: only an _injected_ ref (via `config.ref`) defers auto-start, so `useChain` and StrictMode remounts keep working. Note: if you previously worked around this by calling `api.start()` manually on the function form, the transition now also auto-starts. Closes #2287.

packages/core/src/hooks/useTransition.test.tsx

@@ -3,6 +3,8 @@ import { render } from 'vitest-browser-react'
 import { toArray } from '@react-spring/shared'
 import { TransitionFn, UseTransitionProps } from '../types'
 import { useTransition } from './useTransition'
+import { useSpring } from './useSpring'
+import { useChain } from './useChain'
 import { SpringRef } from '../SpringRef'
 
 describe('useTransition', () => {
@@ -153,6 +155,142 @@ describe('useTransition', () => {
     testIsRef(transRef)
   })
 
+  // See https://github.com/pmndrs/react-spring/issues/2287
+  it('auto-starts the enter animation when props is a function with deps', async () => {
+    let enterSpring: any = null
+    const update = createUpdater(({ args }) => {
+      const transition = toArray(useTransition(...args))[0]
+      transition(style => {
+        enterSpring = style.n
+        return null
+      })
+      return null
+    })
+
+    await update(
+      true,
+      () => ({
+        from: { n: 0 },
+        enter: { n: 1 },
+        leave: { n: 0 },
+      }),
+      []
+    )
+
+    await global.advanceUntilIdle()
+
+    expect(enterSpring.get()).toEqual(1)
+  })
+
+  // Guard for the #2287 fix: only the *internal* ref should auto-start. An
+  // injected ref must keep deferring so manual/imperative control still works.
+  // This is the inverse of the test above and locks issue #1944.
+  it('defers the enter animation when an injected ref is provided', async () => {
+    const ref = SpringRef()
+    let enterSpring: any = null
+    const update = createUpdater(({ args }) => {
+      const transition = toArray(useTransition(...args))[0]
+      transition(style => {
+        enterSpring = style.n
+        return null
+      })
+      return null
+    })
+
+    await update(true, {
+      ref,
+      from: { n: 0 },
+      enter: { n: 1 },
+      leave: { n: 0 },
+    })
+
+    // No `ref.start()` yet — the injected ref defers the enter animation.
+    await global.advanceUntilIdle()
+    expect(enterSpring.get()).toEqual(0)
+
+    // ...and the ref still drives it imperatively.
+    ref.start()
+    await global.advanceUntilIdle()
+    expect(enterSpring.get()).toEqual(1)
+  })
+
+  // Guard for the #2287 fix: `useChain` works by draining each controller's
+  // queue and replaying it in order, which only happens when injected refs
+  // defer (populate the queue). There was previously zero coverage for useChain.
+  it('sequences a transition behind a spring with useChain', async () => {
+    const springRef = SpringRef()
+    const transRef = SpringRef()
+    let enterSpring: any = null
+
+    function Component() {
+      useSpring({ ref: springRef, from: { x: 0 }, to: { x: 1 } })
+      const transition = toArray(
+        useTransition(true, {
+          ref: transRef,
+          from: { n: 0 },
+          enter: { n: 1 },
+          leave: { n: 0 },
+        })
+      )[0]
+      transition(style => {
+        enterSpring = style.n
+        return null
+      })
+      useChain([springRef, transRef])
+      return null
+    }
+
+    await render(<Component />)
+
+    // While the spring is mid-flight, the chained transition stays at `from`.
+    global.mockRaf.step()
+    expect(enterSpring.get()).toEqual(0)
+
+    // Once the chain reaches it, the transition animates to `enter`.
+    await global.advanceUntilIdle()
+    expect(enterSpring.get()).toEqual(1)
+  })
+
+  // Guard for the #2287 fix: injected-ref deferral must survive React
+  // StrictMode's mount → unmount → remount cycle. This is the reattachment
+  // behaviour `useTransition` adds on mount (#1890/#1944).
+  it('keeps an injected ref deferred across a StrictMode double-mount', async () => {
+    const ref = SpringRef()
+    let enterSpring: any = null
+
+    function Component() {
+      const transition = toArray(
+        useTransition(true, {
+          ref,
+          from: { n: 0 },
+          enter: { n: 1 },
+          leave: { n: 0 },
+        })
+      )[0]
+      transition(style => {
+        enterSpring = style.n
+        return null
+      })
+      return null
+    }
+
+    await render(
+      <React.StrictMode>
+        <Component />
+      </React.StrictMode>
+    )
+
+    // Deferred even after the simulated unmount/remount.
+    await global.advanceUntilIdle()
+    expect(enterSpring.get()).toEqual(0)
+
+    // Controllers are still attached to the ref, which still drives them.
+    expect(ref.current).toHaveLength(1)
+    ref.start()
+    await global.advanceUntilIdle()
+    expect(enterSpring.get()).toEqual(1)
+  })
+
   it('passes immediate through to payload', async () => {
     const props = {
       from: { n: 0 },

packages/core/src/hooks/useTransition.tsx

@@ -113,12 +113,18 @@ export function useTransition(
      * then reattach their refs on-mount, this was required
      * for react18 strict mode to work properly.
      *
+     * StrictMode's simulated unmount detaches the controller from its ref but
+     * leaves `ctrl.ref` set, so we reset it here to let the commit phase's
+     * `replaceRef` reattach an *injected* ref. We must NOT assign the local
+     * `ref` to `ctrl.ref` — that would make a function/deps-form transition
+     * defer its enter animation as if a ref were injected (see #2287).
+     *
      * See https://github.com/pmndrs/react-spring/issues/1890
      */
 
     each(transitions, t => {
       ref?.add(t.ctrl)
-      t.ctrl.ref = ref
+      t.ctrl.ref = undefined
     })
 
     // Destroy all transitions on dismount.
@@ -428,7 +434,7 @@ export function useTransition(
              * Unless we have exitBeforeEnter in which case will skip
              * to enter the new animation straight away as if they "overlapped"
              */
-            if ((ctrl.ref || ref) && !forceChange.current) {
+            if (ctrl.ref && !forceChange.current) {
               ctrl.update(payload)
             } else {
               ctrl.start(payload)