react-native-smooth-clip-view 0.2.8 → 0.3.0

package/README.md

@@ -2,6 +2,10 @@
 
 [![npm version](https://img.shields.io/npm/v/react-native-smooth-clip-view.svg)](https://www.npmjs.com/package/react-native-smooth-clip-view)
 
+https://github.com/user-attachments/assets/899235b3-de69-46d7-b6db-61bc54d80df8
+
+<sub>Card zoom and shared-element gallery transitions, captured at 60fps — [direct clip](https://github.com/kbrattli/react-native-smooth-clip-view/blob/main/docs/media/smooth-clip-demo.mp4).</sub>
+
 ## High-performance geometry animations for React Native
 
 `react-native-smooth-clip-view` lets you animate `x`, `y`, `width`, `height`, and `borderRadius` with Reanimated without triggering expensive layout work on every frame.
@@ -16,10 +20,11 @@ Use it for transitions that previously struggled with performance when animating
 - React Native Reanimated 4.5 or newer
 - React Native Worklets 0.10 or newer
 - iOS 16.4 or newer
-- Android API 26 or newer
+- Android API 33 or newer
 
-The package supports iOS, Android, and React Native Web. It does not include a
-legacy Paper implementation.
+The package supports iOS and Android. React Native Web and the legacy Paper
+architecture are not supported; keep imports and rendered usage behind native
+platform boundaries.
 
 ## Installation
 
@@ -97,8 +102,9 @@ const styles = StyleSheet.create({
 ```
 
 The same driver can be passed to multiple hosts. One native registry update
-fans the seven-scalar presentation out to all mounted hosts. Interactive
-updates avoid Yoga and ShadowTree commits.
+fans the presentation out to all mounted hosts. The original seven-scalar V1
+protocol remains unchanged; V2 adds per-corner radii, continuous curves, and
+centered content scale. Interactive updates avoid Yoga and ShadowTree commits.
 
 For transitions whose endpoint is known, let Core Animation interpolate on the
 render server:
@@ -126,6 +132,20 @@ vsync clock with registry fanout; outline calculation and invalidation still
 run on its UI thread. Springs are physically integrated per geometry channel
 and finish when they settle below sub-pixel thresholds on both platforms.
 Retargeting starts from visible state.
+
+Blocked-thread behavior: a blocked JS thread never stalls a running
+transition on either platform — no JS runs on the frame path. A blocked
+main thread stalls it on Android (the frame loop and the View property
+writes are main-thread-only by platform design; the RenderThread only
+replays what the main thread records) but not on iOS, where the render
+server advances installed Core Animations out of process. The Android
+behavior is not recoverable through public APIs — RenderThread-driven
+property animation (`RenderNodeAnimator`, what ripples use) is hidden API —
+and it is also the coherent choice for this library: parallel Reanimated
+content runs on the main thread on both platforms, so on Android the clip
+and its content stall and resume together, while on iOS a main-thread stall
+lets the natively animated channels keep moving past any Reanimated-driven
+ones.
 The same driver can be grabbed by a gesture without a visual jump:
 
 ```tsx
@@ -146,6 +166,9 @@ const gesture = Gesture.Pan()
     // geometry as `from` so the animation starts from exactly that value —
     // it fuses a setScalars hot write with the handoff in one call.
     const clip = geometryForDrag(dragStart.value, event.translationY);
+    // 'inherit' projects launch speed from the drag's last two samples. On
+    // Android that sampling is opt-in — create the driver with
+    // useSmoothClipDriver(initial, { velocityTracking: true }).
     driver.ui.animateTo(createClipPresentation(expandedClip), {
       type: 'spring',
       initialVelocity: 'inherit',
@@ -194,13 +217,27 @@ puts on screen, which is the property worth keeping identical.
   as `animation.from` — `animateTo` then performs the hot write and the
   handoff in one call. Do not interleave `setScalars` with
   `presentation.value` writes on the same driver.
+- `driver.ui.setPresentationScalars(x, y, width, height, topLeft, topRight,
+  bottomRight, bottomLeft, curveCode, tx, ty, scale)` is the V2 hot path.
+  `curveCode` is `0` for circular and `1` for continuous. V2 values are
+  validated as one transaction; widened values are never silently downgraded
+  onto a V1 native binary.
 - Spring `initialVelocity` is one normalized scalar along the current-to-target
   trajectory, in units of the remaining distance per second (`1` covers the
   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; the web fallback always inherits
-  zero. How long the finger has been still since that last sample scales the
+  interactive samples on iOS and Android. On Android, sampling on the
+  `setScalars` hot path is **opt-in**: pass
+  `velocityTracking: true` to `useSmoothClipDriver` or `'inherit'` inherits
+  zero after a hot-write drag (a dev-mode warning flags this). **Behavior
+  change:** earlier releases always recorded on Android, so an existing
+  `setScalars`-drag → inherit-spring handoff keeps its momentum only after
+  adding the flag. The recording
+  is a clock read plus channel copies on every per-frame write, so drivers
+  that never hand off into an inherit spring skip it by default. iOS always
+  records, and Android's declarative `presentation.value` channel always
+  records too. 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
@@ -235,10 +272,9 @@ puts on screen, which is the property worth keeping identical.
   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.
+  stops any running Core Animation, applies `from` to the model layer, and
+  installs timing, spring, or keyframe playback from that exact presentation in
+  the same start transaction.
 - `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
@@ -300,6 +336,30 @@ bounds, so a clip that extended beyond the host comes back clamped. Start
 gestures with `beginInteraction()`: interactive writes issued while native
 still owns rendering are dropped.
 
+### Group driver
+
+`useSmoothClipGroupDriver({ reduceMotion, onAnimationComplete })` coordinates
+multiple drivers with one native group ID and one completion. Its worklet-safe
+`ui` and Promise-based `react` interfaces expose:
+
+- `beginInteraction(drivers)` to freeze every overlapping group atomically and
+  return canonical visible snapshots in input order.
+- `snapshotCurrent(drivers)` to sample presentation and readiness without
+  changing ownership.
+- `setBatch(entries)` to validate every entry before committing one native
+  transaction.
+- `animateTo(entries, animation)` for shared timing, spring, or linear
+  keyframe progress. Membership is immutable for that group ID; a replacement
+  is a new atomically installed group.
+- `cancel(groupId, 'freeze' | 'finish')` to return every participant snapshot.
+
+Groups wait until all participants have a visible, attached, laid-out,
+positive-size host. The default `suspensionPolicy: 'pause'` freezes and
+re-latches the whole group if any participant loses readiness; `'finish'`
+applies every target. Complex-path native settlement is capability-gated—use
+`getSmoothClipCapabilities()` and keep streaming with `setBatch` when
+`autonomousComplexPathAnimation` is false.
+
 ### `SmoothClipPresentation`
 
 ```ts
@@ -307,6 +367,7 @@ type SmoothClipPresentation = Readonly<{
   clip: ClipGeometry;
   contentTranslateX: number;
   contentTranslateY: number;
+  contentScale?: number;
 }>;
 ```
 
@@ -323,12 +384,19 @@ type ClipGeometry = Readonly<{
   width: number;
   height: number;
   radius: number;
+  topLeftRadius?: number;
+  topRightRadius?: number;
+  bottomRightRadius?: number;
+  bottomLeftRadius?: number;
+  curve?: 'circular' | 'continuous';
 }>;
 ```
 
 Values use React Native points/DIPs. Native code rejects non-finite updates,
 intersects the requested rectangle with the actual host bounds, prevents
-negative sizes, and clamps `radius` to half of the visible shortest edge.
+negative sizes, and proportionally scales overlapping corners with the CSS
+corner-normalization rule. Content scale is centered on the native content
+container; translation is independent and is not multiplied by scale.
 
 ### `normalizeClipGeometry`
 
@@ -350,23 +418,21 @@ pass it as the `driver` prop, and move per-frame updates from the
 - Give the host its fixed maximum `width` and `height`; clipping never changes
   Yoga layout.
 - Put visual backgrounds inside `SmoothClipView`.
-- Borders, shadows, host corner styles, host `overflow`, per-corner radii, and
-  externally applied anisotropic transforms are unsupported.
-- Version 0.1.0 supports one uniform corner radius.
-- On web, the implementation uses CSS `clip-path` on the fixed host, so
-  descendant percentages and right/bottom anchoring still resolve against the
-  maximum footprint.
+- Keep borders, shadows, rotation, and anisotropic transforms on an outer
+  visual carrier rather than the clip host.
+- Uniform circular corners use platform fast paths. Unequal or continuous
+  corners use a fixed-topology portable path; Android intentionally does not
+  claim pixel identity with Apple's proprietary continuous curve.
 
 ## Example and development
 
 The [`example`](./example) workspace is an Expo SDK 57 app that exercises the
-package through its public import on iOS, Android, and web.
+package through its public import on iOS and Android.
 
 ```sh
 npm install
 npm run example -- ios
 npm run example -- android
-npm run example -- web
 ```
 
 Run the repository checks with:
@@ -376,7 +442,6 @@ npm run lint
 npm run typecheck
 npm test
 npm run prepare
-npm run example -- build:web
 ```
 
 ## License

package/android/CMakeLists.txt

@@ -40,3 +40,10 @@ target_link_libraries(
   fbjni::fbjni
   ReactAndroid::jsi
   ReactAndroid::reactnative)
+
+# Debug-only hot-path ATrace slices; see SmoothClipTrace.h.
+# Passed from the debug build type in build.gradle, never for release.
+if(SMOOTH_CLIP_ENABLE_ATRACE)
+  target_compile_definitions(smoothclipview PRIVATE SMOOTH_CLIP_ENABLE_ATRACE=1)
+  target_link_libraries(smoothclipview android)
+endif()

package/android/build.gradle

@@ -1,7 +1,7 @@
 buildscript {
   ext.SmoothClipView = [
     kotlinVersion: "2.0.21",
-    minSdkVersion: 26,
+    minSdkVersion: 33,
     compileSdkVersion: 36,
     targetSdkVersion: 36
   ]
@@ -76,7 +76,11 @@ android {
   }
 
   defaultConfig {
-    minSdkVersion getExtOrDefault("minSdkVersion")
+    // Outline.setPath only guarantees arbitrary path clipping from API 33.
+    // Keep this as a hard library floor: allowing a consuming root project to
+    // override it lower would make the V2 per-corner/continuous path silently
+    // unsupported at runtime.
+    minSdkVersion SmoothClipView.minSdkVersion
     targetSdkVersion getExtOrDefault("targetSdkVersion")
     // C++ resolves SmoothClipView by name and calls setClipPresentationDip via
     // a cached jmethodID; consumer minification must not rename or strip them.
@@ -100,6 +104,14 @@ android {
   }
 
   buildTypes {
+    debug {
+      externalNativeBuild {
+        cmake {
+          // Hot-path ATrace slices; see SmoothClipTrace.h.
+          arguments "-DSMOOTH_CLIP_ENABLE_ATRACE=ON"
+        }
+      }
+    }
     release {
       minifyEnabled false
     }

package/android/proguard-rules.pro

@@ -1,6 +1,6 @@
 # SmoothClipView is resolved from C++ by name (fbjni findClassStatic) and its
-# setClipPresentationDip / setClipPresentationPx are invoked through cached
-# jmethodIDs; SmoothClipBindings registers native methods by name. None of them
-# may be renamed or stripped in consumer release builds.
+# V1/V2 setClipPresentation*Dip / setClipPresentation*Px are invoked through
+# cached jmethodIDs; SmoothClipBindings registers native methods by name. None
+# of them may be renamed or stripped in consumer release builds.
 -keep class com.smoothclipview.SmoothClipView { *; }
 -keep class com.smoothclipview.SmoothClipBindings { *; }

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

@@ -18,10 +18,16 @@ struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
   static constexpr auto kJavaDescriptor = "Lcom/smoothclipview/SmoothClipView;";
 
   void applyClip(const Presentation &presentation) const;
+  void applyClipV2(const Presentation &presentation) const;
   void applyClipPx(
       const NormalizedClip &clip,
       double contentTranslateXPx,
       double contentTranslateYPx) const;
+  void applyClipV2Px(
+      const NormalizedClip &clip,
+      double contentTranslateXPx,
+      double contentTranslateYPx,
+      double contentScale) const;
 };
 
 // Called from Kotlin (SmoothClipViewManager) on the UI thread when a Fabric
@@ -57,6 +63,10 @@ void setViewLifecycleVisibilityAndroid(
 // seconds; never lets a failure unwind back into doFrame.
 void onFrameAndroid(double frameTimeS);
 
+// Non-destructive V2 snapshot for the public snapshotCurrentV2 binding.
+// beginInteraction remains the explicit ownership-taking/cancelling operation.
+Presentation snapshotCurrentAndroid(uint64_t driverId);
+
 // 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.