react-native-smooth-clip-view 0.2.9 → 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:
@@ -211,13 +217,18 @@ 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. On Android, sampling on the `setScalars` hot path is **opt-in**: pass
+  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
@@ -261,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
@@ -326,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
@@ -333,6 +367,7 @@ type SmoothClipPresentation = Readonly<{
   clip: ClipGeometry;
   contentTranslateX: number;
   contentTranslateY: number;
+  contentScale?: number;
 }>;
 ```
 
@@ -349,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`
 
@@ -376,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:
@@ -402,7 +442,6 @@ npm run lint
 npm run typecheck
 npm test
 npm run prepare
-npm run example -- build:web
 ```
 
 ## License

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.

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.