fix(core): expose new phase to useTransition render fn

.changeset/transition-phase-leave-render.md

@@ -0,0 +1,5 @@
+---
+'@react-spring/core': patch
+---
+
+Expose `phase === 'leave'` to the `useTransition` render function during the render that runs the leave animation. Previously `t.phase` was only updated to the new phase in a layout effect after render, so the render fn always saw the previous phase (`'enter'`) while a leaving item animated out — and by the time a follow-up render could surface `'leave'`, the transition had expired and been pruned. The render fn now receives a state whose `phase` matches the upcoming animation, so consumers can reliably branch on `state.phase === 'leave'`. Closes #1654.

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

@@ -195,6 +195,36 @@ describe('useTransition', () => {
     expect(rendered).toEqual([1])
   })
 
+  it('exposes phase === "leave" to the render fn during a normal leave', async () => {
+    // Regression test for https://github.com/pmndrs/react-spring/issues/1654
+    // The render function receives the transition state `t` as its third
+    // argument; consumers read `t.phase` to branch on lifecycle.
+    const phaseLog: string[] = []
+    const update = createUpdater(({ args }) => {
+      const t = toArray(useTransition(...args))[0] as TransitionFn
+      rendered = t((_, item, state) => {
+        phaseLog.push(`${item}:${state.phase}`)
+        return item
+      }).props.children
+      return null
+    })
+
+    const props = {
+      from: { n: 0 },
+      enter: { n: 1 },
+      leave: { n: 0 },
+    }
+
+    await update(true, props)
+    await global.advanceUntilIdle()
+
+    phaseLog.length = 0
+    await update(false, props)
+    await global.advanceUntilIdle()
+
+    expect(phaseLog.some(entry => entry.endsWith(':leave'))).toBe(true)
+  })
+
   it('should work with both exitBeforeEnter and trail together', async () => {
     const props = {
       from: { t: 0 },

packages/core/src/hooks/useTransition.tsx

@@ -90,7 +90,7 @@
 
   // Return a `SpringRef` if a deps array was passed.
   const ref = useMemo(
     () => (propsFn || arguments.length == 3 ? SpringRef() : void 0),
     []
   )
 
@@ -427,8 +427,13 @@
   const renderTransitions: TransitionFn = render => (
     <>
       {transitions.map((t, i) => {
-        const { springs } = changes.get(t) || t.ctrl
-        const elem: any = render({ ...springs }, t.item, t, i)
+        const change = changes.get(t) || exitingTransitions.current.get(t)
+        const { springs } = change || t.ctrl
+        // Expose the phase that will be assigned in the upcoming layout
+        // effect so the render fn sees `leave` during the leave animation,
+        // not the stale phase from the previous render. See #1654.
+        const state = change ? { ...t, phase: change.phase } : t
+        const elem: any = render({ ...springs }, t.item, state, i)
 
         const key = is.str(t.key) || is.num(t.key) ? t.key : t.ctrl.id
         const isLegacyReact = React.version < '19.0.0'