Suspend overlapping view transitions (#56462)

Summary:
Pull Request resolved: #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<PendingTransition>` 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

Author: zeyap

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(

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

packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.cpp

@@ -328,6 +328,21 @@ void ViewTransitionModule::startViewTransition(
     std::function<void()> mutationCallback,
     std::function<void()> onReadyCallback,
     std::function<void()> 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<UIManagerViewTransitionDelegate::ViewTransitionInstance>

packages/react-native/ReactCommon/react/renderer/viewtransition/ViewTransitionModule.h

@@ -7,6 +7,7 @@
 
 #pragma once
 
+#include <queue>
 #include <unordered_set>
 
 #include <react/renderer/core/LayoutMetrics.h>
@@ -78,6 +79,8 @@ class ViewTransitionModule : public UIManagerViewTransitionDelegate,
 
   std::shared_ptr<const ShadowNode> 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<void()> mutationCallback;
+    std::function<void()> onReadyCallback;
+    std::function<void()> onCompleteCallback;
+  };
+  std::queue<PendingTransition> pendingTransitions_{};
 };
 
 } // namespace facebook::react