react-native-smooth-clip-view 0.2.4 → 0.2.6

package/README.md

@@ -2,14 +2,13 @@
 
 [![npm version](https://img.shields.io/npm/v/react-native-smooth-clip-view.svg)](https://www.npmjs.com/package/react-native-smooth-clip-view)
 
-Layout-free animated rounded clipping for React Native Fabric.
+## High-performance geometry animations for React Native
 
-`SmoothClipView` keeps a fixed maximum Yoga footprint while a reusable driver
-updates only the native clipping layer. It is
-useful for expanding cards, sheets, maps, media, zoom transitions, and other reveals where
-animating layout width and height cause lag because of yoga/fabric calculating layout every frame.
+`react-native-smooth-clip-view` lets you animate `x`, `y`, `width`, `height`, and `borderRadius` with Reanimated without triggering expensive layout work on every frame.
 
-In other words, it makes animating width height on Reanimated a cheap operation.
+Instead of resizing the Yoga layout, `SmoothClipView` keeps a fixed footprint and updates only the native clipping layer. This makes geometry-heavy animations smooth and inexpensive—even for shared-element transitions, zoom transitions, expanding cards, reveals, sheets, maps, and media.
+
+Use it for transitions that previously struggled with performance when animating layout dimensions directly.
 
 ## Requirements
 
@@ -166,6 +165,15 @@ const gesture = Gesture.Pan()
 | `driver`   | `SmoothClipDriver` | Reusable hybrid clip driver.            |
 | `children` | `ReactNode`        | Content rendered inside the fixed host. |
 
+The host hides itself, drops out of the accessibility tree, and stops accepting
+touches while the clip is empty. The two platforms draw the boundary where they
+actually stop rendering, which differs below one pixel: Android emits an integer
+`Outline`, which collapses to nothing under half a physical pixel, so an extent
+in `(0, 0.5)` px counts as empty there; iOS masks in floats and treats only a
+zero-or-negative extent as empty. A clip animating through that band therefore
+turns non-interactive one frame earlier on Android — matching what each platform
+puts on screen, which is the property worth keeping identical.
+
 ### Driver
 
 - `useSmoothClipDriver(initialPresentation, options)` returns one hybrid driver
@@ -191,11 +199,19 @@ const gesture = Gesture.Pan()
   remaining distance in one second). Every geometry channel continues with the
   same normalized rate, so grab/release preserves the felt direction and
   speed. `'inherit'` (the default) estimates the scalar from the last two
-  interactive samples on iOS and Android; samples older than 100 ms — and the
-  web fallback — fall back to zero. Two writes landing inside the same frame
+  interactive samples on iOS and Android; the web fallback always inherits
+  zero. How long the finger has been still since that last sample scales the
+  result: full credit for one frame (16.7 ms), then a linear decay to zero at
+  100 ms. A release straight out of a drag is therefore untouched, and holding
+  still before releasing bleeds the momentum off smoothly instead of keeping
+  all of it until 99 ms and none at 101 ms. Two writes landing inside the same frame
   (< 4 ms apart, e.g. a release-sample `from` seed right after the last drag
   write) coalesce into one sample, and an identical re-write is ignored, so a
   fused handoff can neither zero nor inflate the inherited velocity.
+  `beginInteraction()` records the frozen presentation as a plain sample on
+  both platforms, so a grab-and-instant-refling inherits bounded recent
+  motion (the staleness guard still zeroes a stale pair) instead of
+  launching dead.
 - `driver.react` exposes `beginInteraction`, `set`, `animateTo`, and `cancel`
   as Promises (`setScalars` is UI-worklet-only). React code never blocks
   waiting for main/UI-thread work. An immediate animation request resolves
@@ -206,37 +222,58 @@ const gesture = Gesture.Pan()
   animation can run the identical curve without hand-deriving it; springs
   accept mass, stiffness, damping, and an
   explicit normalized velocity or `'inherit'` (the default). Keyframes accept
-  validated, monotonically increasing offsets from zero through one. Every
+  validated, monotonically increasing offsets from zero through one; there is
+  deliberately no keyframe easing field — playback is linear between offsets
+  and the frames encode the curve, which also expresses per-channel-nonlinear
+  paths that no single time-warp could reproduce. Every
   kind accepts an optional `from` presentation — a fused take-ownership hot
   write issued immediately before the handoff, so the animation starts from
   exactly that value (pass `frames[0].presentation` for keyframes, which
   interpolate absolutely). A non-finite `from` rejects the whole call; against
-  a held pending-animation latch the seed is dropped — the latch is newer
-  intent, and nothing is displayable yet anyway. `from` behaves the same on
-  both platforms (it is driver-layer, not native): on iOS the seed stops any
-  running Core Animation and writes the model layer first; keyframes then
-  start exactly at `from`, while timing/spring sample their from-value off
-  the presentation layer — the last committed frame, at most one frame
-  behind `from` — identical to the explicit two-call pattern.
+  a held pending-animation latch, explicit `from` is the newer intent: it
+  cancels that latch once with `finished: false`, records/applies `from`, then
+  starts the replacement from that native value. Passive hook seeds and public
+  `set`/`setScalars` writes still leave a held latch intact. `from` behaves the
+  same on both platforms (it is driver-layer, not native): on iOS the seed
+  stops any running Core Animation and writes the model layer first; keyframes
+  then start exactly at `from`, while timing/spring sample their from-value off
+  the presentation layer — the last committed frame, at most one frame behind
+  `from` — identical to the explicit two-call pattern.
 - `cancel()` freezes visible presentation by default. Pass `'target'` as its
   behavior to jump to the requested endpoint.
 - `options.onAnimationComplete` fires exactly once per animation with its ID
   and `finished` state, including cancellation, replacement, and native-side
   rejection (`animateTo` then returns a fresh non-zero id whose single
   `finished: false` completion follows — key completion handling by the
-  returned id, never by `0`). `animateTo` returns `0` — and delivers no
-  completion — only when the driver entry no longer exists (destroyed) or the
-  call ran off the main thread. Unmounting the last host mid-flight does not complete the
-  animation: the remainder is re-latched and the next displayable host resumes
-  it, so the completion arrives when it finishes there — or unfinished on
+  returned id, never by `0`). A valid pre-registration request carries its
+  authoritative interactive start, creates the missing driver state and
+  returns a real id. `0` — with no completion — is reserved for off-main,
+  invalid-id, or otherwise unsupported dispatch: a missing-state native request
+  with no authoritative start, and any `driver.ui.animateTo` issued after the
+  driver's hook has unmounted. (The second case is decided on the UI runtime,
+  because a destroyed driver and a not-yet-seeded one are the same missing
+  registry entry to native — accepting it would build a latch nothing can start
+  and nothing can cancel.) Removing the last displayable
+  host mid-flight does not complete the animation: the remainder is re-latched
+  even if detached or unsized peers remain registered, and the next displayable
+  host resumes it, so the completion arrives when it finishes there — or unfinished on
   replacement, cancellation, `beginInteraction()`, or driver destruction.
+  With multiple hosts on one driver, unregistering any host that installed the
+  running animation makes the eventual completion `finished: false` — a
+  detached or un-laid-out host does not become a completion participant until
+  its native animation is actually installed. `finished: true` means every
+  installed participant ran the animation to its end.
 - An `animateTo` issued before any host view can produce a visible frame (for
   example from an effect in the same commit that mounts the host, or inside a
   modal route whose subtree attaches to its window late) is held pending and
-  starts with its full duration at the first displayable registration or
-  window attach. A pending animation owns the driver: take-ownership writes
-  (`set`, `setScalars`, the hook's seed) are dropped while it is held —
-  replace it with another `animateTo`, or cancel it via `beginInteraction()`
+  starts with its full duration at the first moment a registered host can
+  produce a frame — registration, first layout, or window attach, whichever
+  comes last. This also covers an animation worklet that runs before the
+  hook's seed worklet: the animation creates the state and the later passive
+  seed cannot reset its ownership or active id. A pending animation owns the
+  driver: ordinary take-ownership writes (`set`, `setScalars`, the hook's seed)
+  are dropped while it is held. Replace it with another `animateTo`, override
+  it with an explicit `animation.from`, or cancel it via `beginInteraction()`
   or `cancel()`. If no view ever becomes displayable, it survives until it is
   replaced, cancelled, or the driver is destroyed — at which point its single
   `finished: false` completion is delivered.

package/android/CMakeLists.txt

@@ -36,7 +36,6 @@ target_include_directories(
 
 target_link_libraries(
   smoothclipview
-  android
   log
   fbjni::fbjni
   ReactAndroid::jsi

package/android/src/main/cpp/SmoothClipAndroid.h

@@ -53,6 +53,11 @@ void viewBecameDisplayableAndroid(
     uint64_t driverId,
     facebook::jni::alias_ref<JSmoothClipView> view);
 
+// Advances the registry frame loop. Called from Kotlin (SmoothClipBindings)
+// inside Choreographer#doFrame with the frame's vsync timestamp converted to
+// seconds; never lets a failure unwind back into doFrame.
+void onFrameAndroid(double frameTimeS);
+
 // Installs `global.__SmoothClipView` (worklet-callable host functions) into the
 // JS runtime and wires native animation completion delivery through the
 // CallInvoker. Invoked by the TurboModule BindingsInstaller.

package/android/src/main/cpp/SmoothClipBindings.cpp

@@ -6,6 +6,7 @@
 #include <jsi/jsi.h>
 
 #include <cmath>
+#include <limits>
 #include <memory>
 #include <unordered_map>
 #include <utility>
@@ -45,6 +46,18 @@ bool boolArg(const Value *args, size_t count, size_t index) {
   return index < count && args[index].isBool() && args[index].getBool();
 }
 
+// Optional trailing start stamp (Reanimated-rule milliseconds captured in the
+// issuing worklet), converted to the registry's CLOCK_MONOTONIC seconds. A
+// missing or non-numeric argument — and the JS side's deliberate NaN fallback
+// when the worklet globals are absent — resolves to NaN, which
+// resolveStartStamp() treats as "no hint": nowSeconds() plus the min() anchor,
+// exactly the pre-hint behavior.
+double startStampArg(const Value *args, size_t count, size_t index) {
+  return index < count && args[index].isNumber()
+      ? args[index].asNumber() / 1000.0
+      : std::numeric_limits<double>::quiet_NaN();
+}
+
 Presentation presentationFromArgs(const Value *args, size_t offset) {
   return Presentation{
       {args[offset].asNumber(),
@@ -153,15 +166,17 @@ void installBindings(
   Object bindings(runtime);
 
   setHostFunction(
-      runtime, bindings, "setClipPresentation", 9,
+      runtime, bindings, "setClipPresentation", 10,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 9) return Value::undefined();
         const double driverId = args[0].asNumber();
         const Presentation presentation = presentationFromArgs(args, 1);
         const bool takeOwnership = boolArg(args, count, 8);
+        const bool overridePendingAnimation = boolArg(args, count, 9);
         if (validDriverId(driverId) && finitePresentation(presentation)) {
           setPresentation(
-              static_cast<uint64_t>(driverId), presentation, takeOwnership);
+              static_cast<uint64_t>(driverId), presentation, takeOwnership,
+              overridePendingAnimation);
         }
         return Value::undefined();
       });
@@ -177,7 +192,7 @@ void installBindings(
       });
 
   setHostFunction(
-      runtime, bindings, "animateTiming", 22,
+      runtime, bindings, "animateTiming", 23,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 22) return Value(0);
         const double driverId = args[0].asNumber();
@@ -194,13 +209,13 @@ void installBindings(
         }
         return Value(animateTiming(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 22)},
             target,
             animation));
       });
 
   setHostFunction(
-      runtime, bindings, "animateSpring", 22,
+      runtime, bindings, "animateSpring", 23,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 22) return Value(0);
         const double driverId = args[0].asNumber();
@@ -221,13 +236,13 @@ void installBindings(
         }
         return Value(animateSpring(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 22)},
             target,
             animation));
       });
 
   setHostFunction(
-      runtime, bindings, "animateKeyframes", 19,
+      runtime, bindings, "animateKeyframes", 20,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 19 || !args[17].isObject() ||
             !args[17].getObject(rt).isArray(rt)) {
@@ -270,7 +285,7 @@ void installBindings(
         }
         return Value(animateKeyframes(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 19)},
             target,
             durationMs,
             std::move(keyframes),
@@ -419,6 +434,10 @@ void nativeInvalidate(jni::alias_ref<jni::JObject>) {
   smoothclip::invalidateBindings();
 }
 
+void nativeOnFrame(jni::alias_ref<jni::JObject>, jlong frameTimeNanos) {
+  smoothclip::onFrameAndroid(static_cast<double>(frameTimeNanos) / 1e9);
+}
+
 } // namespace
 
 JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
@@ -434,6 +453,7 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
             makeNativeMethod(
                 "nativeViewBecameDisplayable", nativeViewBecameDisplayable),
             makeNativeMethod("nativeInvalidate", nativeInvalidate),
+            makeNativeMethod("nativeOnFrame", nativeOnFrame),
         });
   });
 }