react-native-smooth-clip-view 0.4.5 → 0.5.0

package/cpp/SmoothClipAnimationCurve.h

@@ -138,10 +138,11 @@ inline double cubicBezier(
 
 // --- Presentation channels ------------------------------------------------
 
-// The first thirteen channels are geometry/content/appearance; the final eight are shadow.
-// Curve and shadow presence are categorical and stay outside the scalar array.
-constexpr std::size_t kBaseChannelCount = 13;
-constexpr std::size_t kChannelCount = 21;
+// The first fifteen channels are geometry/content/appearance/backdrop; the
+// final eight are shadow. Curve and shadow presence are categorical and stay
+// outside the scalar array.
+constexpr std::size_t kBaseChannelCount = 15;
+constexpr std::size_t kChannelCount = 23;
 using Channels = std::array<double, kChannelCount>;
 
 inline double resolvedRadius(double overrideValue, double shorthand) {
@@ -179,6 +180,8 @@ inline Channels toChannels(const Presentation &presentation) {
           presentation.contentScale,
           presentation.rotation,
           presentation.opacity,
+          presentation.backdropTranslateX,
+          presentation.backdropTranslateY,
           presentation.shadow.red,
           presentation.shadow.green,
           presentation.shadow.blue,
@@ -365,6 +368,27 @@ inline double relativeSpringEnergy(
   return currentEnergy / initialEnergy;
 }
 
+/**
+ * Seconds until the normalized spring trajectory started with `velocity`
+ * settles under the animation's relative-energy threshold, sampled at 120 Hz
+ * and capped at ten seconds. Every layer of a run (clip, content, shadow,
+ * backdrop) derives its Core Animation duration from this one rule, so they
+ * are removed in the same frame.
+ */
+inline double springSettleDuration(
+    const SpringAnimation &animation,
+    double velocity) {
+  ScalarSpringState state{0, velocity};
+  constexpr double step = 1.0 / 120.0;
+  double elapsed = 0;
+  while (elapsed < 10.0 &&
+         relativeSpringEnergy(state, animation) > animation.energyThreshold) {
+    state = advanceScalarSpring(state, animation, step);
+    elapsed += step;
+  }
+  return elapsed;
+}
+
 inline bool springScaleStaysPositive(
     const Presentation &start,
     const Presentation &target,
@@ -460,16 +484,17 @@ inline Presentation fromChannels(
   geometry.curve = curve;
   Shadow shadow{
       shadowEnabled,
-      std::clamp(channels[13], 0.0, 1.0),
-      std::clamp(channels[14], 0.0, 1.0),
       std::clamp(channels[15], 0.0, 1.0),
       std::clamp(channels[16], 0.0, 1.0),
-      channels[17],
-      channels[18],
-      std::max(0.0, channels[19]),
-      channels[20]};
+      std::clamp(channels[17], 0.0, 1.0),
+      std::clamp(channels[18], 0.0, 1.0),
+      channels[19],
+      channels[20],
+      std::max(0.0, channels[21]),
+      channels[22]};
   return Presentation{
-      geometry, channels[8], channels[9], channels[10], shadow, channels[11], clamp01(channels[12])};
+      geometry, channels[8], channels[9], channels[10], shadow, channels[11],
+      clamp01(channels[12]), channels[13], channels[14]};
 }
 
 inline Presentation interpolate(

package/cpp/SmoothClipRegistry.h

@@ -46,6 +46,12 @@ struct Presentation {
   Shadow shadow{};
   double rotation = 0; // Unwrapped radians, clockwise in host coordinates.
   double opacity = 1;
+  // Translation of every SmoothClipBackdropView bound to the driver, in
+  // host points. A channel of the same run as the aperture, so content that
+  // must stay locked to the window (a canvas centred in it) is sampled by
+  // the same native clock as the clip and never lands a frame late.
+  double backdropTranslateX = 0;
+  double backdropTranslateY = 0;
 };
 
 struct TimingAnimation {
@@ -73,10 +79,11 @@ struct AnimationStart {
   // Reanimated-rule start stamp, captured on the UI runtime at animateTo time
   // as `__frameTimestamp || _getAnimationTimestamp()` and converted to
   // CLOCK_MONOTONIC seconds. NaN means no stamp was captured (older callers,
-  // tests, platforms that ignore it): the integrator then falls back to its
-  // own clock plus the min() frame-clock anchor. iOS constructs this struct
-  // without the member and inherits the NaN default — CoreAnimation anchors
-  // its own animations, so the hint is Android-only by design.
+  // tests): the integrator then falls back to its own clock plus the min()
+  // frame-clock anchor. iOS does not use this member: it carries the same
+  // stamp on the animation group (`GroupState::beginTimeHint` in
+  // SmoothClipRegistry.mm) and applies it as the shared Core Animation
+  // `beginTime`, bounded by the same sanity window.
   double startedAtHintS = std::numeric_limits<double>::quiet_NaN();
 };
 

package/ios/SmoothClipBackdropView.h

@@ -0,0 +1,17 @@
+#import <React/RCTViewComponentView.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * A view translated by its controller's backdrop channel. The registry writes
+ * the channel to an inner content layer on every setFrame and adds a
+ * translation animation to every native run on the clip's shared Core
+ * Animation epoch, so the content is sampled by the same clock as the
+ * aperture and never lands a frame late. The view's own layer keeps React
+ * Native's transform.
+ */
+@interface SmoothClipBackdropView : RCTViewComponentView
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/SmoothClipBackdropView.mm

@@ -0,0 +1,267 @@
+#import "SmoothClipBackdropView.h"
+
+#import "SmoothClipViewRegistry.h"
+
+#include "SmoothClipAnimationCurve.h"
+
+#import <QuartzCore/QuartzCore.h>
+#import <React/RCTFabricComponentsPlugins.h>
+#import <react/renderer/components/SmoothClipViewSpec/ComponentDescriptors.h>
+#import <react/renderer/components/SmoothClipViewSpec/Props.h>
+#import <react/renderer/components/SmoothClipViewSpec/RCTComponentViewHelpers.h>
+
+#include <algorithm>
+#include <cmath>
+
+using namespace facebook::react;
+
+static NSString *const kSmoothClipBackdropAnimationKey = @"smoothClip.backdrop";
+
+@interface SmoothClipBackdropContentView : UIView
+@end
+
+@implementation SmoothClipBackdropContentView
+
+- (id<CAAction>)actionForLayer:(CALayer *)layer forKey:(NSString *)event {
+  // The registry drives the translation explicitly, by a model write or by
+  // the animations installed below; no implicit action per frame.
+  return (id<CAAction>)[NSNull null];
+}
+
+@end
+
+@implementation SmoothClipBackdropView {
+  SmoothClipBackdropContentView *_content;
+  uint64_t _driverId;
+  CGPoint _translation;
+  BOOL _animating;
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider {
+  return concreteComponentDescriptorProvider<
+      SmoothClipBackdropViewComponentDescriptor>();
+}
+
++ (BOOL)shouldBeRecycled {
+  return NO;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame {
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps =
+        std::make_shared<const SmoothClipBackdropViewProps>();
+    _props = defaultProps;
+    _content = [[SmoothClipBackdropContentView alloc] initWithFrame:self.bounds];
+    _content.autoresizesSubviews = NO;
+    [self addSubview:_content];
+    _driverId = 0;
+    _translation = CGPointZero;
+    _animating = NO;
+  }
+  return self;
+}
+
+- (void)dealloc {
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+  }
+}
+
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                          index:(NSInteger)index {
+  NSAssert(childComponentView.superview == nil,
+           @"SmoothClipBackdropView attempted to mount an already-mounted child");
+  [_content insertSubview:childComponentView atIndex:index];
+}
+
+- (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                            index:(NSInteger)index {
+  NSAssert(childComponentView.superview == _content,
+           @"SmoothClipBackdropView attempted to unmount a child from another parent");
+  [childComponentView removeFromSuperview];
+}
+
+- (void)updateLayoutMetrics:(const LayoutMetrics &)layoutMetrics
+           oldLayoutMetrics:(const LayoutMetrics &)oldLayoutMetrics {
+  [super updateLayoutMetrics:layoutMetrics oldLayoutMetrics:oldLayoutMetrics];
+  // Bounds and centre, never frame: the content layer carries the channel as
+  // a translation transform, and a frame write under a transform re-derives
+  // the position through the transform's inverse, folding the current
+  // translation into the position for good. Fabric sets props (and so the
+  // channel) before it lays the view out.
+  const CGRect bounds = self.bounds;
+  _content.bounds = bounds;
+  _content.center = CGPointMake(CGRectGetMidX(bounds), CGRectGetMidY(bounds));
+}
+
+- (void)updateProps:(const Props::Shared &)props
+           oldProps:(const Props::Shared &)oldProps {
+  const auto &newProps =
+      *std::static_pointer_cast<const SmoothClipBackdropViewProps>(props);
+  [super updateProps:props oldProps:oldProps];
+  const uint64_t nextDriverId =
+      isfinite(newProps.driverId) && newProps.driverId > 0
+      ? static_cast<uint64_t>(newProps.driverId)
+      : 0;
+  if (nextDriverId == _driverId) return;
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+  }
+  _driverId = nextDriverId;
+  if (_driverId != 0) {
+    smoothclip::registerBackdropView(_driverId, self);
+  }
+}
+
+- (void)prepareForRecycle {
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+    _driverId = 0;
+  }
+  [self stopBackdropAnimation];
+  [self writeTranslation:CGPointZero];
+  [super prepareForRecycle];
+}
+
+// MARK: - Registry hooks
+
+- (void)writeTranslation:(CGPoint)translation {
+  _translation = translation;
+  _content.layer.transform =
+      CATransform3DMakeTranslation(translation.x, translation.y, 0);
+}
+
+- (void)stopBackdropAnimation {
+  if (!_animating) return;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  _animating = NO;
+}
+
+- (CGPoint)smoothClipBackdropCurrentTranslation {
+  CALayer *layer = _animating ? _content.layer.presentationLayer : nil;
+  if (layer == nil) return _translation;
+  const CATransform3D transform = layer.transform;
+  return CGPointMake(transform.m41, transform.m42);
+}
+
+- (void)smoothClipApplyBackdrop:(CGPoint)translation {
+  [self stopBackdropAnimation];
+  [self writeTranslation:translation];
+}
+
+- (void)installBackdropGroup:(CAAnimationGroup *)group
+             sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  if (sharedBeginTime <= 0) sharedBeginTime = CACurrentMediaTime();
+  // The clip's epoch, translated into this layer's clock: a stamped epoch
+  // may sit up to one frame ahead of the commit, and until it arrives the
+  // run presents its first frame rather than the target the model holds.
+  group.beginTime = [_content.layer convertTime:sharedBeginTime fromLayer:nil];
+  group.fillMode = kCAFillModeBackwards;
+  [_content.layer addAnimation:group forKey:kSmoothClipBackdropAnimationKey];
+  _animating = YES;
+}
+
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             timing:(smoothclip::TimingAnimation)timing
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  const CGPoint from = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  [self writeTranslation:target];
+  if (self.window == nil) return NO;
+  CAMediaTimingFunction *function = [CAMediaTimingFunction
+      functionWithControlPoints:timing.controlPoint1X
+                               :timing.controlPoint1Y
+                               :timing.controlPoint2X
+                               :timing.controlPoint2Y];
+  CABasicAnimation *x =
+      [CABasicAnimation animationWithKeyPath:@"transform.translation.x"];
+  x.fromValue = @(from.x);
+  x.toValue = @(target.x);
+  x.timingFunction = function;
+  CABasicAnimation *y =
+      [CABasicAnimation animationWithKeyPath:@"transform.translation.y"];
+  y.fromValue = @(from.y);
+  y.toValue = @(target.y);
+  y.timingFunction = function;
+  CAAnimationGroup *group = [CAAnimationGroup animation];
+  group.animations = @[ x, y ];
+  group.duration = std::max(0.0, timing.durationMs) / 1000.0;
+  [self installBackdropGroup:group sharedBeginTime:sharedBeginTime];
+  return YES;
+}
+
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             spring:(smoothclip::SpringAnimation)spring
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  const CGPoint from = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  [self writeTranslation:target];
+  if (self.window == nil) return NO;
+  // The same normalized trajectory and settling rule as the clip host, so
+  // both layers stop in the same frame.
+  const double duration =
+      smoothclip::springSettleDuration(spring, spring.initialVelocity);
+  const auto animation = [&](NSString *keyPath, double fromValue, double toValue) {
+    CASpringAnimation *result = [CASpringAnimation animationWithKeyPath:keyPath];
+    result.fromValue = @(fromValue);
+    result.toValue = @(toValue);
+    result.mass = spring.mass;
+    result.stiffness = spring.stiffness;
+    result.damping = spring.damping;
+    result.initialVelocity = spring.initialVelocity;
+    result.duration = duration;
+    return result;
+  };
+  CAAnimationGroup *group = [CAAnimationGroup animation];
+  group.animations = @[
+    animation(@"transform.translation.x", from.x, target.x),
+    animation(@"transform.translation.y", from.y, target.y),
+  ];
+  group.duration = duration;
+  [self installBackdropGroup:group sharedBeginTime:sharedBeginTime];
+  return YES;
+}
+
+- (void)smoothClipCancelBackdropUsingTarget:(BOOL)useTarget {
+  if (!_animating) return;
+  const CGPoint visible = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  if (!useTarget) [self writeTranslation:visible];
+}
+
+- (BOOL)smoothClipPauseBackdropAtMediaTime:(CFTimeInterval)mediaTime {
+  CAAnimation *installed =
+      [_content.layer animationForKey:kSmoothClipBackdropAnimationKey];
+  if (!_animating || installed == nil) return NO;
+  CAAnimation *paused = [installed copy];
+  const CFTimeInterval localNow =
+      [_content.layer convertTime:mediaTime fromLayer:nil];
+  paused.speed = 0;
+  paused.timeOffset = std::clamp(
+      localNow - installed.beginTime, (CFTimeInterval)0, installed.duration);
+  paused.beginTime = 0;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  [_content.layer addAnimation:paused forKey:kSmoothClipBackdropAnimationKey];
+  return YES;
+}
+
+- (BOOL)smoothClipResumeBackdropAtMediaTime:(CFTimeInterval)mediaTime
+                                  catchUpBy:(CFTimeInterval)catchUp {
+  CAAnimation *installed =
+      [_content.layer animationForKey:kSmoothClipBackdropAnimationKey];
+  if (!_animating || installed == nil) return NO;
+  CAAnimation *resumed = [installed copy];
+  const CFTimeInterval localNow =
+      [_content.layer convertTime:mediaTime fromLayer:nil];
+  const CFTimeInterval resumedTime = std::min(
+      installed.duration,
+      std::max((CFTimeInterval)0, installed.timeOffset + catchUp));
+  resumed.speed = 1;
+  resumed.timeOffset = 0;
+  resumed.beginTime = localNow - resumedTime;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  [_content.layer addAnimation:resumed forKey:kSmoothClipBackdropAnimationKey];
+  return YES;
+}
+
+@end

package/ios/SmoothClipGeometry.h

@@ -149,13 +149,14 @@ NS_INLINE CGPathRef SmoothClipCreateRoundedRectPath(
   const CGFloat minY = CGRectGetMinY(rect);
   const CGFloat maxX = CGRectGetMaxX(rect);
   const CGFloat maxY = CGRectGetMaxY(rect);
-  // Circular is the exact cubic-circle coefficient. The portable continuous
-  // fallback uses kappa=1 so each cubic joins its straight edges with zero
-  // curvature, matching the portable Android path. Hit testing derives
-  // from this rendered path rather than maintaining a second curve model.
-  // Uniform
-  // continuous shapes use CALayer.cornerCurve for Apple's platform-native
-  // compositor shape and are intentionally not pixel-identical cross-platform.
+  // Circular is the exact cubic-circle coefficient. This continuous fallback
+  // uses kappa=1 so each cubic joins its straight edges with zero curvature
+  // in one segment, which keeps the topology Core Animation interpolates.
+  // It only feeds the unequal-radii mask and the shadow outline: uniform
+  // continuous shapes use CALayer.cornerCurve, Apple's platform-native
+  // compositor shape. Android draws continuous as a Figma smoothed corner
+  // instead, so this path does not mirror it. Hit testing derives from this
+  // rendered path rather than maintaining a second curve model.
   const CGFloat controlFactor =
       curve == SmoothClipCornerCurveContinuous
       ? 1.0