react-native-smooth-clip-view 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## [0.4.3](https://github.com/kbrattli/react-native-smooth-clip-view/releases/tag/v0.4.3) — 2026-09-11
+
+### Rotate and fade the whole clip
+
+Animate rotation and opacity alongside clip geometry on iOS and Android. The
+aperture, its content, and its shadow move and fade together inside the fixed
+host, using the existing controller and atomic group APIs.
+
+- **Rotation:** pass degree or radian strings such as `'12deg'` or `'0.2rad'`.
+  Rotation is clockwise around the current aperture center, after content
+  translation and scale. Angles interpolate numerically, so `'720deg'` animates
+  two full turns from zero. Interruption snapshots preserve those turns.
+- **Group opacity:** set `opacity` to fade content and shadow together, including
+  overlapping children. Finite values clamp to `[0, 1]`; spring rendering clamps
+  opacity while preserving the spring's internal motion state.
+- **Animation continuity:** rotation and opacity participate in timing and
+  spring animations, cancellation snapshots, and background spring pause/resume.
+  Explicit spring velocity applies to these channels too.
+- **Touch and accessibility:** hit testing follows the rotated aperture, including
+  clips rotated back into the viewport. Fully transparent content accepts no new
+  touches and is hidden from accessibility.
+- **Rendering:** appearance updates use native compositor properties without
+  Yoga layout work or rebuilding unchanged clipping paths. Translucent groups
+  may require offscreen compositing.
+- **Types and validation:** export `ClipRotation`, include rotation and opacity in
+  canonical presentations, and reject malformed angles or nonfinite values
+  atomically. Add JavaScript and native regression coverage for these behaviors.
+
+### Usage and upgrade notes
+
+`rotation` defaults to `'0deg'` and `opacity` to `1`. Presentations are complete:
+omitting either field resets it to its default. Snapshots return rotation in
+radians. See [Rotate and fade a clip](./README.md#rotate-and-fade-a-clip) for a
+controller example.
+
+**Rebuild your native app after upgrading**, and run `pod install` on iOS. The
+native presentation protocol has changed; JavaScript from 0.4.3 must run with the
+matching native library, rather than an older binary updated only through OTA.
+
+[All changes since 0.4.2](https://github.com/kbrattli/react-native-smooth-clip-view/compare/v0.4.2...v0.4.3)
+
+Earlier release notes are available on [GitHub Releases](https://github.com/kbrattli/react-native-smooth-clip-view/releases).

package/README.md

@@ -134,6 +134,21 @@ defaults match Reanimated 4.5: mass `4`, stiffness `900`, damping `120`, and
 relative energy threshold `6e-9`. A spring is rejected when its resolved native
 trajectory could make `contentScale` nonpositive.
 
+`velocity` is a shared initial progress velocity in inverse seconds, defaulting
+to `0`. Each changing channel starts with velocity proportional to its remaining
+distance: `velocity * (target - start)`. This includes rotation (in radians) and
+opacity. Public controllers and groups do not automatically inherit gesture
+velocity; starting a new spring after `beginInteraction()` still defaults to `0`
+unless `velocity` is supplied. Pausing and resuming an existing native spring
+preserves its internal motion state; public snapshots return clamped opacity.
+
+The internal native standalone path also supports inherited velocity. Its
+projection uses only clip position, size, corner radii, and content translation.
+Rotation, opacity, content scale, and shadow channels do not contribute to that
+projection. The resulting normalized velocity can drive all changing channels,
+including rotation and opacity, without mixing their units into the projection.
+Rotation/opacity-only motion therefore supplies no inherited velocity.
+
 An animation requested before the host has a positive layout waits, then starts
 with its full duration. While the application is inactive, native animation
 transactions stay pending and do not report cancellation. Timing animations
@@ -189,6 +204,15 @@ APIs share validation, run ownership, and completion behavior.
 - Corner-overlap scaling follows CSS rules against the requested rectangle.
 - `contentTranslateX`, `contentTranslateY`, and positive `contentScale` animate
   with the aperture.
+- `rotation` accepts degree or radian strings (for example, `'12deg'` or
+  `'0.2rad'`) and defaults to `'0deg'`. It rotates the aperture, content, and
+  shadow together, clockwise around the current aperture center. Existing
+  content translation and scale happen before this rotation. The host stays
+  fixed and crops the rotated result.
+- `opacity` defaults to `1` and fades the aperture's content and shadow as one
+  group. Finite values clamp to `[0, 1]`; malformed angles and nonfinite values
+  reject the complete presentation. Spring opacity is clamped for rendering
+  without clamping its internal spring state.
 - Circular and continuous curves and independent corner radii are supported.
 - One outset `boxShadow` is supported. It escapes the aperture but not the host.
 - A fully off-host aperture is not touchable, even when only its shadow overlaps.
@@ -198,6 +222,52 @@ APIs share validation, run ownership, and completion behavior.
 Use `getSmoothClipCapabilities()` when a consumer needs to decide whether a
 complex native path can be promoted on the current platform.
 
+### Rotate and fade a clip
+
+Rotation and opacity are presentation fields, so they use the same controller
+and group methods as geometry. For example, start a tilted, translucent card
+and animate it upright:
+
+```ts
+const clip = useSmoothClipController({
+  clip: { x: 24, y: 80, width: 240, height: 320, radius: 24 },
+  contentTranslateX: 0,
+  contentTranslateY: 0,
+  rotation: '-12deg',
+  opacity: 0.4,
+});
+
+// Attach this controller to <SmoothClipView controller={clip}> as above.
+const reveal = () =>
+  clip.react.animateTo(
+    {
+      clip: { x: 24, y: 80, width: 240, height: 320, radius: 24 },
+      contentTranslateX: 0,
+      contentTranslateY: 0,
+      rotation: '0deg',
+      opacity: 1,
+    },
+    { type: 'spring', stiffness: 180, damping: 22 }
+  );
+```
+
+For gesture-driven updates, supply the same fields from a UI-runtime worklet:
+
+```ts
+clip.ui.setFrame({ ...frame, rotation: '12deg', opacity: 0.5 });
+```
+
+Angles interpolate numerically, so `'720deg'` requests two full turns from zero;
+there is no automatic shortest-path wrapping. Interruption snapshots preserve
+full turns and return rotation as a radian string. Each presentation is complete:
+omitting rotation or opacity resets that field to its default. At zero opacity,
+the content admits no new touches and is hidden from accessibility.
+
+When upgrading to **0.4.3**, rebuild the native app (and run `pod install` on
+iOS). The native presentation protocol includes new rotation and opacity
+channels, so a JavaScript-only OTA update cannot upgrade an older native build.
+See the [changelog](./CHANGELOG.md) for release details.
+
 ## Performance contract
 
 - One worklet-to-native call per `ui.setFrame`, or per group batch.
@@ -205,6 +275,10 @@ complex native path can be promoted on the current platform.
 - The shadow-disabled rendering path keeps no shadow drawing resources.
 - The fixed host is the maximum rendering viewport; consumers should size it to
   the region in which content and shadow may appear.
+- Rotation and opacity update native compositor properties without Yoga work
+  or rebuilding unchanged clipping paths. Correctly fading overlapping children
+  may require offscreen compositing; large translucent groups can cost more GPU
+  time than opaque ones. No rasterization or software layer is forced.
 
 ## License
 

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

@@ -22,7 +22,7 @@ struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
       double contentTranslateXPx,
       double contentTranslateYPx,
       double contentScale,
-      const Shadow &shadowPx) const;
+      const Shadow &shadowPx, double rotation, double opacity) const;
   void setAutonomousMotion(bool active) const;
 };
 

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

@@ -27,7 +27,7 @@ namespace smoothclip {
 namespace {
 
 constexpr double kMaxSafeJavaScriptInteger = 9007199254740991.0;
-constexpr size_t kPresentationStride = 21;
+constexpr size_t kPresentationStride = 23;
 constexpr size_t kSnapshotStride = kPresentationStride + 1;
 constexpr size_t kMotionEntryStride = kPresentationStride * 2 + 2;
 
@@ -61,7 +61,8 @@ bool finiteBasePresentation(const Presentation &presentation) {
       std::isfinite(presentation.contentTranslateX) &&
       std::isfinite(presentation.contentTranslateY) &&
       std::isfinite(presentation.contentScale) &&
-      presentation.contentScale > 0;
+      presentation.contentScale > 0 &&
+      std::isfinite(presentation.rotation) && std::isfinite(presentation.opacity);
 }
 
 bool finitePresentation(const Presentation &presentation) {
@@ -154,7 +155,7 @@ bool presentationAt(
       Shadow{
           packet[12] == 1.0,
           packet[13], packet[14], packet[15], packet[16],
-          packet[17], packet[18], packet[19], packet[20]}};
+          packet[17], packet[18], packet[19], packet[20]}, packet[21], packet[22]};
   return finitePresentation(result);
 }
 
@@ -190,6 +191,8 @@ void appendPresentation(
   result.setValueAtIndex(runtime, offset++, presentation.shadow.offsetY);
   result.setValueAtIndex(runtime, offset++, presentation.shadow.blurRadius);
   result.setValueAtIndex(runtime, offset++, presentation.shadow.spreadDistance);
+  result.setValueAtIndex(runtime, offset++, presentation.rotation);
+  result.setValueAtIndex(runtime, offset++, presentation.opacity);
 }
 
 Array presentationArray(Runtime &runtime, const Presentation &presentation) {
@@ -551,9 +554,9 @@ void installBindings(
       });
 
   setHostFunction(
-      runtime, bindings, "setClipFrameScalars", 22,
+      runtime, bindings, "setClipFrameScalars", 24,
       [](Runtime &, const Value &, const Value *args, size_t count) -> Value {
-        if (count < 22) return Value::undefined();
+        if (count < 24) return Value::undefined();
         const double driverId = args[0].asNumber();
         Geometry geometry{
             args[1].asNumber(), args[2].asNumber(), args[3].asNumber(),
@@ -584,7 +587,7 @@ void installBindings(
                 args[19].asNumber(),
                 args[20].asNumber(),
                 args[21].asNumber(),
-            }};
+            }, args[22].asNumber(), args[23].asNumber()};
         if (validDriverId(driverId) && validCurve(args[9].asNumber()) &&
             finitePresentation(presentation)) {
           setPresentation(
@@ -828,6 +831,8 @@ void nativeRegisterView(
     jdouble shadowOffsetY,
     jdouble shadowBlurRadius,
     jdouble shadowSpreadDistance,
+    jdouble rotation,
+    jdouble opacity,
     jdouble density,
     jdouble widthPx,
     jdouble heightPx,
@@ -842,7 +847,8 @@ void nativeRegisterView(
       !std::isfinite(shadowBlue) || !std::isfinite(shadowAlpha) ||
       !std::isfinite(shadowOffsetX) ||
       !std::isfinite(shadowOffsetY) || !std::isfinite(shadowBlurRadius) ||
-      !std::isfinite(shadowSpreadDistance) || contentScale <= 0 ||
+      !std::isfinite(shadowSpreadDistance) ||
+      !std::isfinite(rotation) || !std::isfinite(opacity) || contentScale <= 0 ||
       shadowRed < 0 || shadowRed > 1 || shadowGreen < 0 || shadowGreen > 1 ||
       shadowBlue < 0 || shadowBlue > 1 || shadowAlpha < 0 || shadowAlpha > 1 ||
       shadowBlurRadius < 0 ||
@@ -874,7 +880,7 @@ void nativeRegisterView(
       static_cast<uint64_t>(driverId),
       view,
       smoothclip::Presentation{
-          geometry, contentTranslateX, contentTranslateY, contentScale, shadow},
+          geometry, contentTranslateX, contentTranslateY, contentScale, shadow, rotation, opacity},
       density,
       widthPx,
       heightPx,

package/android/src/main/cpp/SmoothClipRegistry.cpp

@@ -458,7 +458,7 @@ void deliverToView(const ViewEntry &entry, const Presentation &presentation) {
       translateX,
       translateY,
       presentation.contentScale,
-      shadowPx);
+      shadowPx, presentation.rotation, presentation.opacity);
 }
 
 void applyToViews(DriverState &state, const Presentation &presentation) {
@@ -1705,7 +1705,7 @@ void JSmoothClipView::applyClip(const Presentation &presentation) const {
               jdouble,
               jdouble,
               jdouble,
-              jdouble)>("setClipPresentationDip");
+              jdouble, jdouble, jdouble)>("setClipPresentationDip");
   method(
       self(),
       presentation.clip.x,
@@ -1732,7 +1732,7 @@ void JSmoothClipView::applyClip(const Presentation &presentation) const {
       presentation.shadow.offsetX,
       presentation.shadow.offsetY,
       presentation.shadow.blurRadius,
-      presentation.shadow.spreadDistance);
+      presentation.shadow.spreadDistance, presentation.rotation, presentation.opacity);
 }
 
 void JSmoothClipView::applyClipPx(
@@ -1740,7 +1740,7 @@ void JSmoothClipView::applyClipPx(
     double contentTranslateXPx,
     double contentTranslateYPx,
     double contentScale,
-    const Shadow &shadowPx) const {
+    const Shadow &shadowPx, double rotation, double opacity) const {
   static const auto method =
       javaClassStatic()
           ->getMethod<void(
@@ -1764,7 +1764,7 @@ void JSmoothClipView::applyClipPx(
               jfloat,
               jfloat,
               jfloat,
-              jfloat)>("setClipPresentationPx");
+              jfloat, jdouble, jfloat)>("setClipPresentationPx");
   method(
       self(),
       static_cast<jfloat>(clip.left),
@@ -1787,7 +1787,7 @@ void JSmoothClipView::applyClipPx(
       static_cast<jfloat>(shadowPx.offsetX),
       static_cast<jfloat>(shadowPx.offsetY),
       static_cast<jfloat>(shadowPx.blurRadius),
-      static_cast<jfloat>(shadowPx.spreadDistance));
+      static_cast<jfloat>(shadowPx.spreadDistance), rotation, static_cast<jfloat>(opacity));
 }
 
 void JSmoothClipView::setAutonomousMotion(bool active) const {

package/android/src/main/java/com/smoothclipview/ClipGeometryNormalizer.kt

@@ -240,3 +240,26 @@ internal fun clipAccessibility(
     } else {
         requestedAccessibility
     }
+
+/** Conservative for rounded corners, exact for the rotated bounding rectangle. */
+internal fun rotatedRectIntersectsHost(
+    left: Double, top: Double, right: Double, bottom: Double,
+    pivotX: Double, pivotY: Double, rotation: Double, hostWidth: Double, hostHeight: Double,
+): Boolean {
+    if (right <= left || bottom <= top || hostWidth <= 0 || hostHeight <= 0) return false
+    if (rotation == 0.0) return right > 0 && bottom > 0 && left < hostWidth && top < hostHeight
+    val c = kotlin.math.cos(rotation)
+    val s = kotlin.math.sin(rotation)
+    val dx = (left + right) / 2 - pivotX
+    val dy = (top + bottom) / 2 - pivotY
+    val x = pivotX + c * dx - s * dy - hostWidth / 2
+    val y = pivotY + s * dx + c * dy - hostHeight / 2
+    val hw = (right - left) / 2
+    val hh = (bottom - top) / 2
+    val ac = kotlin.math.abs(c)
+    val ass = kotlin.math.abs(s)
+    return kotlin.math.abs(x) < hostWidth / 2 + ac * hw + ass * hh &&
+        kotlin.math.abs(y) < hostHeight / 2 + ass * hw + ac * hh &&
+        kotlin.math.abs(c * x + s * y) < hw + ac * hostWidth / 2 + ass * hostHeight / 2 &&
+        kotlin.math.abs(-s * x + c * y) < hh + ass * hostWidth / 2 + ac * hostHeight / 2
+}

package/android/src/main/java/com/smoothclipview/SmoothClipBindings.kt

@@ -43,6 +43,8 @@ internal object SmoothClipBindings {
         shadowOffsetY: Double,
         shadowBlurRadius: Double,
         shadowSpreadDistance: Double,
+        rotation: Double,
+        opacity: Double,
         density: Double,
         widthPx: Double,
         heightPx: Double,

package/android/src/main/java/com/smoothclipview/SmoothClipModule.kt

@@ -140,6 +140,8 @@ class SmoothClipModule(context: ReactApplicationContext) :
         shadowOffsetY: Double,
         shadowBlurRadius: Double,
         shadowSpreadDistance: Double,
+        rotation: Double,
+        opacity: Double,
     ) = Unit
 
     override fun beginInteraction(driverId: Double): WritableArray =