[General] Update button's animation duration props (#4046)

## Description

Native platforms delay touches when the button is inside a ScrollView.
This may cause situations where press-out is triggered immediately after
press-in, effectively running with no animation.

This PR:
- changes the easing on web to better align with native platforms
- changes `animationDuration` to `pressAndHoldAnimationDuration`
- adds `tapAnimationDuration`

`pressAndHoldAnimationDuration` defaults to `tapAnimationDuration` when
unspecified; `tapAnimationDuration` defaults to 100ms.

Press out handler now has three branches:
1. pressDuration >= `pressAndHoldAnimationDuration` -> press out
animation is started immediately with the duration of
`pressAndHoldAnimationDuration`
2. pressDuration * 2 in [`tapAnimationDuration`,
`pressAndHoldAnimationDuration`] (*2 so there's at least half of
`tapAnimationDuration` for the remaining animation) -> press out
animation is started immediately with the duration of the press so far
3. pressDuration < `tapAnimationDuration / 2` -> pressIn animation is
played fully in the remaining time in `tapAnimationDuration`, and
pressOut is scheduled after with the duration of `tapAnimationDuration`

## Test plan

Updated the button underlay example

Author: j-piasecki

apps/common-app/src/new_api/components/button_underlay/index.tsx

@@ -8,8 +8,10 @@ import {
 
 const UNDERLAY_PROPS = {
   underlayColor: 'red',
-  activeUnderlayOpacity: 0.5,
-  animationDuration: 200,
+  activeUnderlayOpacity: 0.2,
+  activeScale: 0.9,
+  pressAndHoldAnimationDuration: 200,
+  tapAnimationDuration: 100,
   rippleColor: 'transparent',
 } as const;
 

packages/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/react/RNGestureHandlerButtonViewManager.kt

@@ -15,6 +15,7 @@ import android.graphics.drawable.RippleDrawable
 import android.graphics.drawable.ShapeDrawable
 import android.graphics.drawable.shapes.RectShape
 import android.os.Build
+import android.os.SystemClock
 import android.util.TypedValue
 import android.view.KeyEvent
 import android.view.MotionEvent
@@ -266,9 +267,14 @@ class RNGestureHandlerButtonViewManager :
     view.isSoundEffectsEnabled = !touchSoundDisabled
   }
 
-  @ReactProp(name = "animationDuration")
-  override fun setAnimationDuration(view: ButtonViewGroup, animationDuration: Int) {
-    view.animationDuration = animationDuration
+  @ReactProp(name = "pressAndHoldAnimationDuration")
+  override fun setPressAndHoldAnimationDuration(view: ButtonViewGroup, pressAndHoldAnimationDuration: Int) {
+    view.pressAndHoldAnimationDuration = pressAndHoldAnimationDuration
+  }
+
+  @ReactProp(name = "tapAnimationDuration")
+  override fun setTapAnimationDuration(view: ButtonViewGroup, tapAnimationDuration: Int) {
+    view.tapAnimationDuration = if (tapAnimationDuration > 0) tapAnimationDuration else 0
   }
 
   @ReactProp(name = "defaultOpacity")
@@ -346,7 +352,9 @@ class RNGestureHandlerButtonViewManager :
     var useBorderlessDrawable = false
 
     var exclusive = true
-    var animationDuration: Int = 100
+    var tapAnimationDuration: Int = 100
+    var pressAndHoldAnimationDuration: Int = -1
+      get() = if (field < 0) tapAnimationDuration else field
     var activeOpacity: Float = 1.0f
     var defaultOpacity: Float = 1.0f
     var activeScale: Float = 1.0f
@@ -369,6 +377,8 @@ class RNGestureHandlerButtonViewManager :
     private var receivedKeyEvent = false
     private var currentAnimator: AnimatorSet? = null
     private var underlayDrawable: PaintDrawable? = null
+    private var pressInTimestamp = 0L
+    private var pendingPressOut: Runnable? = null
 
     // When non-null the ripple is drawn in dispatchDraw (above background, below children).
     // When null the ripple lives on the foreground drawable instead.
@@ -487,7 +497,7 @@ class RNGestureHandlerButtonViewManager :
       underlayDrawable?.alpha = (defaultUnderlayOpacity * 255).toInt()
     }
 
-    private fun animateTo(opacity: Float, scale: Float, underlayOpacity: Float) {
+    private fun animateTo(opacity: Float, scale: Float, underlayOpacity: Float, durationMs: Long) {
       val hasOpacity = activeOpacity != 1.0f || defaultOpacity != 1.0f
       val hasScale = activeScale != 1.0f || defaultScale != 1.0f
       val hasUnderlay = activeUnderlayOpacity != defaultUnderlayOpacity && underlayDrawable != null
@@ -509,18 +519,43 @@ class RNGestureHandlerButtonViewManager :
       }
       currentAnimator = AnimatorSet().apply {
         playTogether(animators)
-        duration = animationDuration.toLong()
+        duration = durationMs
         interpolator = LinearOutSlowInInterpolator()
         start()
       }
     }
 
     private fun animatePressIn() {
-      animateTo(activeOpacity, activeScale, activeUnderlayOpacity)
+      pendingPressOut?.let {
+        handler.removeCallbacks(it)
+        pendingPressOut = null
+      }
+      pressInTimestamp = SystemClock.uptimeMillis()
+      animateTo(activeOpacity, activeScale, activeUnderlayOpacity, pressAndHoldAnimationDuration.toLong())
     }
 
     private fun animatePressOut() {
-      animateTo(defaultOpacity, defaultScale, defaultUnderlayOpacity)
+      pendingPressOut?.let { handler.removeCallbacks(it) }
+      val pressAndHoldMs = pressAndHoldAnimationDuration.toLong()
+      val tapMs = tapAnimationDuration.toLong()
+      val elapsed = SystemClock.uptimeMillis() - pressInTimestamp
+
+      if (elapsed >= pressAndHoldMs) {
+        animateTo(defaultOpacity, defaultScale, defaultUnderlayOpacity, pressAndHoldMs)
+        // elapsed * 2 to ensure there is at least half of the tapAnimationDuration left for the animation to play
+      } else if (elapsed * 2 >= tapMs) {
+        animateTo(defaultOpacity, defaultScale, defaultUnderlayOpacity, elapsed)
+      } else {
+        val remaining = tapMs - elapsed
+        animateTo(activeOpacity, activeScale, activeUnderlayOpacity, remaining)
+
+        val runnable = Runnable {
+          pendingPressOut = null
+          animateTo(defaultOpacity, defaultScale, defaultUnderlayOpacity, tapMs)
+        }
+        pendingPressOut = runnable
+        handler.postDelayed(runnable, remaining)
+      }
     }
 
     private fun createUnderlayDrawable(): PaintDrawable {
@@ -630,6 +665,14 @@ class RNGestureHandlerButtonViewManager :
       return drawable
     }
 
+    override fun onDetachedFromWindow() {
+      super.onDetachedFromWindow()
+      pendingPressOut?.let { handler.removeCallbacks(it) }
+      pendingPressOut = null
+      currentAnimator?.cancel()
+      currentAnimator = null
+    }
+
     override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
       super.onSizeChanged(w, h, oldw, oldh)
       needBackgroundUpdate = true

packages/react-native-gesture-handler/apple/RNGestureHandlerButton.h

@@ -27,7 +27,8 @@
 @property (nonatomic) BOOL userEnabled;
 @property (nonatomic, assign) RNGestureHandlerPointerEvents pointerEvents;
 
-@property (nonatomic, assign) NSInteger animationDuration;
+@property (nonatomic, assign) NSInteger pressAndHoldAnimationDuration;
+@property (nonatomic, assign) NSInteger tapAnimationDuration;
 @property (nonatomic, assign) CGFloat activeOpacity;
 @property (nonatomic, assign) CGFloat defaultOpacity;
 @property (nonatomic, assign) CGFloat activeScale;

packages/react-native-gesture-handler/apple/RNGestureHandlerButton.mm

@@ -44,22 +44,29 @@ @implementation RNGestureHandlerButton {
   CALayer *_underlayLayer;
   CGFloat _underlayCornerRadii[8]; // [tlH, tlV, trH, trV, blH, blV, brH, brV] outer radii in points
   UIEdgeInsets _underlayBorderInsets; // border widths for padding-box inset
+  NSTimeInterval _pressInTimestamp;
+  dispatch_block_t _pendingPressOutBlock;
 }
 
+@synthesize pressAndHoldAnimationDuration = _pressAndHoldAnimationDuration;
+
 - (void)commonInit
 {
   _isTouchInsideBounds = NO;
   _hitTestEdgeInsets = UIEdgeInsetsZero;
   _userEnabled = YES;
   _pointerEvents = RNGestureHandlerPointerEventsAuto;
-  _animationDuration = 100;
+  _pressAndHoldAnimationDuration = -1;
+  _tapAnimationDuration = 100;
   _activeOpacity = 1.0;
   _defaultOpacity = 1.0;
   _activeScale = 1.0;
   _defaultScale = 1.0;
   _activeUnderlayOpacity = 0.0;
   _defaultUnderlayOpacity = 0.0;
   _underlayColor = nil;
+  _pressInTimestamp = 0;
+  _pendingPressOutBlock = nil;
 #if TARGET_OS_OSX
   self.wantsLayer = YES; // Crucial for macOS layer-backing
 #endif
@@ -96,6 +103,40 @@ - (instancetype)initWithFrame:(CGRect)frame
   return self;
 }
 
+- (void)cancelPendingPressOutAnimation
+{
+  if (_pendingPressOutBlock) {
+    dispatch_block_cancel(_pendingPressOutBlock);
+    _pendingPressOutBlock = nil;
+  }
+  RNGHUIView *target = self.animationTarget ?: self;
+  [target.layer removeAllAnimations];
+  [_underlayLayer removeAllAnimations];
+}
+
+#if TARGET_OS_OSX
+- (void)viewWillMoveToWindow:(RNGHWindow *)newWindow
+{
+  [super viewWillMoveToWindow:newWindow];
+  if (newWindow == nil) {
+    [self cancelPendingPressOutAnimation];
+  }
+}
+#else
+- (void)willMoveToWindow:(RNGHWindow *)newWindow
+{
+  [super willMoveToWindow:newWindow];
+  if (newWindow == nil) {
+    [self cancelPendingPressOutAnimation];
+  }
+}
+#endif
+
+- (NSInteger)pressAndHoldAnimationDuration
+{
+  return _pressAndHoldAnimationDuration < 0 ? _tapAnimationDuration : _pressAndHoldAnimationDuration;
+}
+
 - (void)setUnderlayColor:(RNGHColor *)underlayColor
 {
   _underlayColor = underlayColor;
@@ -149,12 +190,16 @@ - (BOOL)shouldHandleTouch:(RNGHUIView *)view
 #endif
 }
 
-- (void)animateUnderlayToOpacity:(float)toOpacity
+- (void)animateUnderlayToOpacity:(float)toOpacity duration:(NSTimeInterval)durationMs
 {
+  _underlayLayer.opacity =
+      _underlayLayer.presentationLayer ? [_underlayLayer.presentationLayer opacity] : _underlayLayer.opacity;
+  [_underlayLayer removeAllAnimations];
+
   CABasicAnimation *anim = [CABasicAnimation animationWithKeyPath:@"opacity"];
-  anim.fromValue = @([_underlayLayer.presentationLayer opacity]);
+  anim.fromValue = @(_underlayLayer.opacity);
   anim.toValue = @(toOpacity);
-  anim.duration = _animationDuration / 1000.0;
+  anim.duration = durationMs / 1000.0;
   anim.timingFunction = [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionEaseInEaseOut];
   _underlayLayer.opacity = toOpacity;
   [_underlayLayer addAnimation:anim forKey:@"opacity"];
@@ -199,14 +244,22 @@ - (void)applyStartAnimationState
 #endif
 }
 
-- (void)animateTarget:(RNGHUIView *)target toOpacity:(CGFloat)opacity scale:(CGFloat)scale
+- (void)animateTarget:(RNGHUIView *)target
+            toOpacity:(CGFloat)opacity
+                scale:(CGFloat)scale
+             duration:(NSTimeInterval)durationMs
 {
-  NSTimeInterval duration = _animationDuration / 1000.0;
+  target.layer.transform =
+      target.layer.presentationLayer ? target.layer.presentationLayer.transform : target.layer.transform;
+  NSTimeInterval duration = durationMs / 1000.0;
 
 #if !TARGET_OS_OSX
+  target.alpha = target.layer.presentationLayer ? target.layer.presentationLayer.opacity : target.alpha;
+  [target.layer removeAllAnimations];
+
   [UIView animateWithDuration:duration
                         delay:0
-                      options:UIViewAnimationOptionCurveEaseInOut | UIViewAnimationOptionBeginFromCurrentState
+                      options:UIViewAnimationOptionCurveEaseInOut
                    animations:^{
                      if (_activeOpacity != 1.0 || _defaultOpacity != 1.0) {
                        target.alpha = opacity;
@@ -218,6 +271,9 @@ - (void)animateTarget:(RNGHUIView *)target toOpacity:(CGFloat)opacity scale:(CGF
                    completion:nil];
 #else
   target.wantsLayer = YES;
+  target.alphaValue = target.layer.presentationLayer ? target.layer.presentationLayer.opacity : target.alphaValue;
+  [target.layer removeAllAnimations];
+
   [NSAnimationContext
       runAnimationGroup:^(NSAnimationContext *context) {
         context.allowsImplicitAnimation = YES;
@@ -236,19 +292,72 @@ - (void)animateTarget:(RNGHUIView *)target toOpacity:(CGFloat)opacity scale:(CGF
 
 - (void)handleAnimatePressIn
 {
+  if (_pendingPressOutBlock) {
+    dispatch_block_cancel(_pendingPressOutBlock);
+    _pendingPressOutBlock = nil;
+  }
+  _pressInTimestamp = CACurrentMediaTime();
   RNGHUIView *target = self.animationTarget ?: self;
-  [self animateTarget:target toOpacity:_activeOpacity scale:_activeScale];
+  [self animateTarget:target toOpacity:_activeOpacity scale:_activeScale duration:self.pressAndHoldAnimationDuration];
   if (_activeUnderlayOpacity != _defaultUnderlayOpacity) {
-    [self animateUnderlayToOpacity:_activeUnderlayOpacity];
+    [self animateUnderlayToOpacity:_activeUnderlayOpacity duration:self.pressAndHoldAnimationDuration];
   }
 }
 
 - (void)handleAnimatePressOut
 {
-  RNGHUIView *target = self.animationTarget ?: self;
-  [self animateTarget:target toOpacity:_defaultOpacity scale:_defaultScale];
-  if (_activeUnderlayOpacity != _defaultUnderlayOpacity) {
-    [self animateUnderlayToOpacity:_defaultUnderlayOpacity];
+  if (_pendingPressOutBlock) {
+    dispatch_block_cancel(_pendingPressOutBlock);
+  }
+
+  NSTimeInterval elapsed = (CACurrentMediaTime() - _pressInTimestamp) * 1000.0;
+  NSInteger pressAndHoldAnimationDuration = self.pressAndHoldAnimationDuration;
+
+  if (elapsed >= pressAndHoldAnimationDuration) {
+    // Press-in animation fully finished, animate out in pressAndHoldAnimationDuration
+    RNGHUIView *target = self.animationTarget ?: self;
+    [self animateTarget:target toOpacity:_defaultOpacity scale:_defaultScale duration:pressAndHoldAnimationDuration];
+    if (_activeUnderlayOpacity != _defaultUnderlayOpacity) {
+      [self animateUnderlayToOpacity:_defaultUnderlayOpacity duration:pressAndHoldAnimationDuration];
+    }
+    // elapsed * 2 to ensure there is at least half of the minDuration left for the animation to play
+  } else if (elapsed * 2 >= _tapAnimationDuration) {
+    // Past minimum but press-in animation still playing, animate out in elapsed time
+    RNGHUIView *target = self.animationTarget ?: self;
+    [self animateTarget:target toOpacity:_defaultOpacity scale:_defaultScale duration:elapsed];
+    if (_activeUnderlayOpacity != _defaultUnderlayOpacity) {
+      [self animateUnderlayToOpacity:_defaultUnderlayOpacity duration:elapsed];
+    }
+  } else {
+    // Before minimum duration, finish press-in in remaining time then animate out in minDuration
+    NSTimeInterval remaining = _tapAnimationDuration - elapsed;
+
+    RNGHUIView *target = self.animationTarget ?: self;
+    [self animateTarget:target toOpacity:_activeOpacity scale:_activeScale duration:remaining];
+    if (_activeUnderlayOpacity != _defaultUnderlayOpacity) {
+      [self animateUnderlayToOpacity:_activeUnderlayOpacity duration:remaining];
+    }
+
+    __weak auto weakSelf = self;
+    _pendingPressOutBlock = dispatch_block_create(DISPATCH_BLOCK_ASSIGN_CURRENT, ^{
+      __strong auto strongSelf = weakSelf;
+      if (strongSelf) {
+        strongSelf->_pendingPressOutBlock = nil;
+        RNGHUIView *target = strongSelf.animationTarget ?: strongSelf;
+        [strongSelf animateTarget:target
+                        toOpacity:strongSelf->_defaultOpacity
+                            scale:strongSelf->_defaultScale
+                         duration:strongSelf->_tapAnimationDuration];
+        if (strongSelf->_activeUnderlayOpacity != strongSelf->_defaultUnderlayOpacity) {
+          [strongSelf animateUnderlayToOpacity:strongSelf->_defaultUnderlayOpacity
+                                      duration:strongSelf->_tapAnimationDuration];
+        }
+      }
+    });
+    dispatch_after(
+        dispatch_time(DISPATCH_TIME_NOW, (int64_t)(remaining * NSEC_PER_MSEC)),
+        dispatch_get_main_queue(),
+        _pendingPressOutBlock);
   }
 }
 

packages/react-native-gesture-handler/apple/RNGestureHandlerButtonComponentView.mm

@@ -241,7 +241,8 @@ - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &
   const auto &newProps = *std::static_pointer_cast<const RNGestureHandlerButtonProps>(props);
 
   _buttonView.userEnabled = newProps.enabled;
-  _buttonView.animationDuration = newProps.animationDuration;
+  _buttonView.pressAndHoldAnimationDuration = newProps.pressAndHoldAnimationDuration;
+  _buttonView.tapAnimationDuration = newProps.tapAnimationDuration > 0 ? newProps.tapAnimationDuration : 0;
   _buttonView.activeOpacity = newProps.activeOpacity;
   _buttonView.defaultOpacity = newProps.defaultOpacity;
   _buttonView.activeScale = newProps.activeScale;

packages/react-native-gesture-handler/src/components/GestureHandlerButton.tsx

@@ -59,9 +59,18 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
   touchSoundDisabled?: boolean | undefined;
 
   /**
-   * Duration of the animation when the button is pressed.
+   * Duration of the press-in animation when the button is held down, in
+   * milliseconds. Defaults to `tapAnimationDuration` when not set (or set
+   * to any negative value).
    */
-  animationDuration?: number | undefined;
+  pressAndHoldAnimationDuration?: number | undefined;
+
+  /**
+   * Minimum duration (in milliseconds) that the press animation must run
+   * before the press-out animation is allowed to start. Ensures the pressed
+   * state is visible on quick taps. Defaults to 100ms.
+   */
+  tapAnimationDuration?: number | undefined;
 
   /**
    * Opacity applied to the button when it is pressed.