Introduce hysteresis window (#53345)

Summary:
Pull Request resolved: #53345

Changelog: [Internal] - Introduce hysteresis window that is nested between the prerender and hidden window sizes. Currently set to enlargening the prerender window by hysteresis ratio

When a VirtualView intersects with the hysteresis window, it mode remains unchanged.

This prevents us dispatch mode changes for things like overscroll.

I put the hysteresis between prerender and hidden because we already avoid dispatching mode changes from visible -> prerender. For prerender -> visible, we use renderState

Reviewed By: yungsters

Differential Revision: D80511627

fbshipit-source-id: cd14256abc898e7120705e277147d52a06c865a9

Author: lunaleaps

packages/react-native/React/Fabric/Mounting/ComponentViews/VirtualView/RCTVirtualViewComponentView.mm

@@ -230,21 +230,34 @@ - (void)dispatchOnModeChangeIfNeeded:(BOOL)checkForTargetRectChange
       scrollView.contentOffset.y,
       scrollView.frame.size.width,
       scrollView.frame.size.height);
+  const CGFloat visibleWidth = thresholdRect.size.width;
+  const CGFloat visibleHeight = thresholdRect.size.height;
+
   if (CGRectOverlaps(targetRect, thresholdRect)) {
     newMode = RCTVirtualViewModeVisible;
   } else {
     auto prerender = false;
     const CGFloat prerenderRatio = ReactNativeFeatureFlags::virtualViewPrerenderRatio();
     if (prerenderRatio > 0) {
-      thresholdRect = CGRectInset(
-          thresholdRect, -thresholdRect.size.width * prerenderRatio, -thresholdRect.size.height * prerenderRatio);
+      thresholdRect = CGRectInset(thresholdRect, -visibleWidth * prerenderRatio, -visibleHeight * prerenderRatio);
       prerender = CGRectOverlaps(targetRect, thresholdRect);
     }
     if (prerender) {
       newMode = RCTVirtualViewModePrerender;
     } else {
-      newMode = RCTVirtualViewModeHidden;
-      thresholdRect = CGRectZero;
+      const CGFloat hysteresisRatio = ReactNativeFeatureFlags::virtualViewHysteresisRatio();
+      if (_mode.has_value() && hysteresisRatio > 0) {
+        thresholdRect = CGRectInset(thresholdRect, -visibleWidth * hysteresisRatio, -visibleHeight * hysteresisRatio);
+        if (CGRectOverlaps(targetRect, thresholdRect)) {
+          newMode = _mode.value();
+        } else {
+          newMode = RCTVirtualViewModeHidden;
+          thresholdRect = CGRectZero;
+        }
+      } else {
+        newMode = RCTVirtualViewModeHidden;
+        thresholdRect = CGRectZero;
+      }
     }
   }
 

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlags.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<1e8a84a53072fa0c8665aead80d0199f>>
+ * @generated SignedSource<<34c12f5a31aab5bfb874953f1beefef1>>
  */
 
 /**
@@ -432,6 +432,12 @@ public object ReactNativeFeatureFlags {
   @JvmStatic
   public fun useTurboModules(): Boolean = accessor.useTurboModules()
 
+  /**
+   * Sets a hysteresis window for transition between prerender and hidden modes.
+   */
+  @JvmStatic
+  public fun virtualViewHysteresisRatio(): Double = accessor.virtualViewHysteresisRatio()
+
   /**
    * Initial prerender ratio for VirtualView.
    */

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsCxxAccessor.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<d07316109dce5cc1ce7b0dc010962c3c>>
+ * @generated SignedSource<<392da016e0bf4193b72c44a508811e10>>
  */
 
 /**
@@ -87,6 +87,7 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
   private var useShadowNodeStateOnCloneCache: Boolean? = null
   private var useTurboModuleInteropCache: Boolean? = null
   private var useTurboModulesCache: Boolean? = null
+  private var virtualViewHysteresisRatioCache: Double? = null
   private var virtualViewPrerenderRatioCache: Double? = null
 
   override fun commonTestFlag(): Boolean {
@@ -692,6 +693,15 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
     return cached
   }
 
+  override fun virtualViewHysteresisRatio(): Double {
+    var cached = virtualViewHysteresisRatioCache
+    if (cached == null) {
+      cached = ReactNativeFeatureFlagsCxxInterop.virtualViewHysteresisRatio()
+      virtualViewHysteresisRatioCache = cached
+    }
+    return cached
+  }
+
   override fun virtualViewPrerenderRatio(): Double {
     var cached = virtualViewPrerenderRatioCache
     if (cached == null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsCxxInterop.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<6e384a07f0e7bc237f72b49a1268e16b>>
+ * @generated SignedSource<<a0453230524ebca2bfb8fad656a6f54a>>
  */
 
 /**
@@ -162,6 +162,8 @@ public object ReactNativeFeatureFlagsCxxInterop {
 
   @DoNotStrip @JvmStatic public external fun useTurboModules(): Boolean
 
+  @DoNotStrip @JvmStatic public external fun virtualViewHysteresisRatio(): Double
+
   @DoNotStrip @JvmStatic public external fun virtualViewPrerenderRatio(): Double
 
   @DoNotStrip @JvmStatic public external fun override(provider: Any)

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsDefaults.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<2daac10f81c205728db8127da4dd36cc>>
+ * @generated SignedSource<<719706a983a073b6c286c49d993f7f80>>
  */
 
 /**
@@ -157,5 +157,7 @@ public open class ReactNativeFeatureFlagsDefaults : ReactNativeFeatureFlagsProvi
 
   override fun useTurboModules(): Boolean = false
 
+  override fun virtualViewHysteresisRatio(): Double = 0.0
+
   override fun virtualViewPrerenderRatio(): Double = 5.0
 }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsLocalAccessor.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<1a19e0569371a038ba8d3849fb26eb5c>>
+ * @generated SignedSource<<594815ba6a984c460ab8bddd91c5cae2>>
  */
 
 /**
@@ -91,6 +91,7 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
   private var useShadowNodeStateOnCloneCache: Boolean? = null
   private var useTurboModuleInteropCache: Boolean? = null
   private var useTurboModulesCache: Boolean? = null
+  private var virtualViewHysteresisRatioCache: Double? = null
   private var virtualViewPrerenderRatioCache: Double? = null
 
   override fun commonTestFlag(): Boolean {
@@ -763,6 +764,16 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
     return cached
   }
 
+  override fun virtualViewHysteresisRatio(): Double {
+    var cached = virtualViewHysteresisRatioCache
+    if (cached == null) {
+      cached = currentProvider.virtualViewHysteresisRatio()
+      accessedFeatureFlags.add("virtualViewHysteresisRatio")
+      virtualViewHysteresisRatioCache = cached
+    }
+    return cached
+  }
+
   override fun virtualViewPrerenderRatio(): Double {
     var cached = virtualViewPrerenderRatioCache
     if (cached == null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsProvider.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<5f84a9a17209b9ecb95e13e6567e7c3c>>
+ * @generated SignedSource<<dfbd5e84392f1fda0e68324582c328b2>>
  */
 
 /**
@@ -157,5 +157,7 @@ public interface ReactNativeFeatureFlagsProvider {
 
   @DoNotStrip public fun useTurboModules(): Boolean
 
+  @DoNotStrip public fun virtualViewHysteresisRatio(): Double
+
   @DoNotStrip public fun virtualViewPrerenderRatio(): Double
 }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/virtual/view/ReactVirtualView.kt

@@ -41,6 +41,7 @@ public class ReactVirtualView(context: Context) :
   internal var modeChangeEmitter: VirtualViewModeChangeEmitter? = null
   internal var prerenderRatio: Double = ReactNativeFeatureFlags.virtualViewPrerenderRatio()
   internal val debugLogEnabled: Boolean = ReactNativeFeatureFlags.enableVirtualViewDebugFeatures()
+  private val hysteresisRatio: Double = ReactNativeFeatureFlags.virtualViewHysteresisRatio()
 
   private val onWindowFocusChangeListener =
       if (ReactNativeFeatureFlags.enableVirtualViewWindowFocusDetection()) {
@@ -222,6 +223,8 @@ public class ReactVirtualView(context: Context) :
         bottom + offsetY,
     )
     scrollView.getDrawingRect(thresholdRect)
+    val visibleHeight = thresholdRect.height()
+    val visibleWidth = thresholdRect.width()
 
     // TODO: Validate whether this is still the case and whether these checks are still needed.
     // updateRects will initially get called before the targetRect has any dimensions set, so if
@@ -260,16 +263,32 @@ public class ReactVirtualView(context: Context) :
       var prerender = false
       if (prerenderRatio > 0.0) {
         thresholdRect.inset(
-            (-thresholdRect.width() * prerenderRatio).toInt(),
-            (-thresholdRect.height() * prerenderRatio).toInt(),
+            (-visibleWidth * prerenderRatio).toInt(),
+            (-visibleHeight * prerenderRatio).toInt(),
         )
         prerender = rectsOverlap(targetRect, thresholdRect)
       }
       if (prerender) {
         newMode = VirtualViewMode.Prerender
       } else {
-        newMode = VirtualViewMode.Hidden
-        thresholdRect.setEmpty()
+        val _mode = mode // local variable so Kotlin knows its not nullable
+        if (_mode != null && hysteresisRatio > 0.0) {
+          thresholdRect.inset(
+              (-visibleWidth * hysteresisRatio).toInt(),
+              (-visibleHeight * hysteresisRatio).toInt(),
+          )
+          if (rectsOverlap(targetRect, thresholdRect)) {
+            // In hysteresis window, no change to mode
+            newMode = _mode
+            debugLog("dispatchOnModeChangeIfNeeded") { "hysteresis, mode=$newMode" }
+          } else {
+            newMode = VirtualViewMode.Hidden
+            thresholdRect.setEmpty()
+          }
+        } else {
+          newMode = VirtualViewMode.Hidden
+          thresholdRect.setEmpty()
+        }
       }
     }
     debugLog("dispatchOnModeChangeIfNeeded") {

packages/react-native/ReactAndroid/src/main/jni/react/featureflags/JReactNativeFeatureFlagsCxxInterop.cpp

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<1eff5bade524e3ad8e827ad4adb37f1a>>
+ * @generated SignedSource<<16b12024bb363358ef09b9a42cb2fc97>>
  */
 
 /**
@@ -441,6 +441,12 @@ class ReactNativeFeatureFlagsJavaProvider
     return method(javaProvider_);
   }
 
+  double virtualViewHysteresisRatio() override {
+    static const auto method =
+        getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jdouble()>("virtualViewHysteresisRatio");
+    return method(javaProvider_);
+  }
+
   double virtualViewPrerenderRatio() override {
     static const auto method =
         getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jdouble()>("virtualViewPrerenderRatio");
@@ -786,6 +792,11 @@ bool JReactNativeFeatureFlagsCxxInterop::useTurboModules(
   return ReactNativeFeatureFlags::useTurboModules();
 }
 
+double JReactNativeFeatureFlagsCxxInterop::virtualViewHysteresisRatio(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
+  return ReactNativeFeatureFlags::virtualViewHysteresisRatio();
+}
+
 double JReactNativeFeatureFlagsCxxInterop::virtualViewPrerenderRatio(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
   return ReactNativeFeatureFlags::virtualViewPrerenderRatio();
@@ -1023,6 +1034,9 @@ void JReactNativeFeatureFlagsCxxInterop::registerNatives() {
       makeNativeMethod(
         "useTurboModules",
         JReactNativeFeatureFlagsCxxInterop::useTurboModules),
+      makeNativeMethod(
+        "virtualViewHysteresisRatio",
+        JReactNativeFeatureFlagsCxxInterop::virtualViewHysteresisRatio),
       makeNativeMethod(
         "virtualViewPrerenderRatio",
         JReactNativeFeatureFlagsCxxInterop::virtualViewPrerenderRatio),

packages/react-native/ReactAndroid/src/main/jni/react/featureflags/JReactNativeFeatureFlagsCxxInterop.h

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<05dba4cd49bd4f490e1ea943dd02cae0>>
+ * @generated SignedSource<<54118ccd475a8bf1d7db83304b1f17d0>>
  */
 
 /**
@@ -231,6 +231,9 @@ class JReactNativeFeatureFlagsCxxInterop
   static bool useTurboModules(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
 
+  static double virtualViewHysteresisRatio(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
+
   static double virtualViewPrerenderRatio(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);