From fd0bc698b092343521545f021fe041814281d5c2 Mon Sep 17 00:00:00 2001 From: Zeya Peng Date: Thu, 16 Apr 2026 08:53:31 -0700 Subject: [PATCH] Suspend overlapping view transitions (#56462) Summary: Pull Request resolved: https://github.com/facebook/react-native/pull/56462 ## Changelog: [Internal] [Added] - Suspend overlapping view transitions When a new view transition starts while another is still active, queue it instead of running immediately. The queued transition runs after the current one finishes via `startViewTransitionEnd` (triggered when transition truly finishes). - Add `suspendOnActiveViewTransition()` to `UIManagerViewTransitionDelegate`, exposed as a method on `nativeFabricUIManager` so the reconciler can signal suspension - `ViewTransitionModule` queues pending transitions in a `std::queue` when `suspendNextTransition_` is set - `startViewTransitionEnd` drains the queue sequentially, each transition triggering the next on completion Reviewed By: sammy-SC Differential Revision: D99366975 fbshipit-source-id: 24bc26b31088d6c46f94fd0805178771fc637df3 --- .../renderer/uimanager/UIManagerBinding.cpp | 18 ++++++++++ .../UIManagerViewTransitionDelegate.h | 4 +++ .../viewtransition/ViewTransitionModule.cpp | 36 +++++++++++++++++++ .../viewtransition/ViewTransitionModule.h | 14 ++++++++ 4 files changed, 72 insertions(+) diff --git a/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerBinding.cpp b/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerBinding.cpp index 9b6b08f4642..3735852dc41 100644 --- a/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerBinding.cpp +++ b/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerBinding.cpp @@ -1074,6 +1074,24 @@ jsi::Value UIManagerBinding::get( }); } + if (methodName == "suspendOnActiveViewTransition") { + return jsi::Function::createFromHostFunction( + runtime, + name, + 0, + [uiManager]( + jsi::Runtime& runtime, + const jsi::Value& /*thisValue*/, + const jsi::Value* /*arguments*/, + size_t /*count*/) -> jsi::Value { + auto* viewTransitionDelegate = uiManager->getViewTransitionDelegate(); + if (viewTransitionDelegate != nullptr) { + viewTransitionDelegate->suspendOnActiveViewTransition(); + } + return jsi::Value::undefined(); + }); + } + if (methodName == "startViewTransition") { auto paramCount = 1; return jsi::Function::createFromHostFunction( diff --git a/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerViewTransitionDelegate.h b/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerViewTransitionDelegate.h index d3685775c35..a21cd4e3d00 100644 --- a/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerViewTransitionDelegate.h +++ b/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerViewTransitionDelegate.h @@ -67,6 +67,10 @@ class UIManagerViewTransitionDelegate { { return nullptr; } + + // Called by the reconciler to signal that the next view transition should + // be suspended until the currently active one finishes. + virtual void suspendOnActiveViewTransition() {} }; } // namespace facebook::react diff --git a/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.cpp b/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.cpp index ee14c7bd585..2aa9e80f083 100644 --- a/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.cpp +++ b/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.cpp @@ -328,6 +328,21 @@ void ViewTransitionModule::startViewTransition( std::function mutationCallback, std::function onReadyCallback, std::function onCompleteCallback) { + // If the reconciler signalled suspension and a transition is still active, + // queue this transition to run after the current one finishes. + // Only queue if the previous transition is still running; if it already + // finished, the flag is stale and we should run normally. + if (suspendNextTransition_ && transitionStarted_) { + suspendNextTransition_ = false; + pendingTransitions_.push( + PendingTransition{ + std::move(mutationCallback), + std::move(onReadyCallback), + std::move(onCompleteCallback)}); + return; + } + suspendNextTransition_ = false; + // Mark transition as started transitionStarted_ = true; @@ -351,6 +366,15 @@ void ViewTransitionModule::startViewTransition( } } +void ViewTransitionModule::suspendOnActiveViewTransition() { + // Signal that the next transition should be suspended until the current + // one finishes. The actual queueing happens in startViewTransition. + if (transitionStarted_) { + // if there's no active transition, suspendOnActiveViewTransition is no-op + suspendNextTransition_ = true; + } +} + void ViewTransitionModule::startViewTransitionEnd() { for (const auto& [tag, names] : nameRegistry_) { for (const auto& name : names) { @@ -370,6 +394,18 @@ void ViewTransitionModule::startViewTransitionEnd() { } transitionStarted_ = false; + + if (!pendingTransitions_.empty()) { + auto pendingTransition = pendingTransitions_.front(); + pendingTransitions_.pop(); + startViewTransition( + std::move(pendingTransition.mutationCallback), + std::move(pendingTransition.onReadyCallback), + std::move(pendingTransition.onCompleteCallback)); + // when this transition finishes, it'll call startViewTransitionEnd + // during its complete callback and pendingTransitions_ will be processed + // again + } } std::optional diff --git a/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.h b/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.h index ae585978b40..7e8a332ee24 100644 --- a/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.h +++ b/packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.h @@ -7,6 +7,7 @@ #pragma once +#include #include #include @@ -78,6 +79,8 @@ class ViewTransitionModule : public UIManagerViewTransitionDelegate, std::shared_ptr findPseudoElementShadowNodeByTag(Tag tag) const override; + void suspendOnActiveViewTransition() override; + // Animation state structure for storing minimal view data struct AnimationKeyFrameViewLayoutMetrics { Point originFromRoot; @@ -124,6 +127,17 @@ class ViewTransitionModule : public UIManagerViewTransitionDelegate, UIManager *uiManager_{nullptr}; bool transitionStarted_{false}; + + // When suspendNextTransition_ is true and a transition is active, the next + // startViewTransition calls are queued instead of running immediately. + bool suspendNextTransition_{false}; + + struct PendingTransition { + std::function mutationCallback; + std::function onReadyCallback; + std::function onCompleteCallback; + }; + std::queue pendingTransitions_{}; }; } // namespace facebook::react