react-native-smooth-clip-view 0.1.0 → 0.2.1

package/README.md

@@ -1,16 +1,21 @@
 # react-native-smooth-clip-view
 
+[![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.
 
-`SmoothClipView` keeps a fixed maximum Yoga footprint while Reanimated sends
-one atomic clip geometry update to the native view on the UI runtime. It is
-useful for expanding cards, sheets, maps, media, and other reveals where
-animating layout width and height would reflow descendants.
+`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.
+
+In other words, it makes animating width height on Reanimated a cheap operation.
 
 ## Requirements
 
-- React Native 0.85 or newer with the New Architecture enabled
-- React Native Reanimated 4.3 or newer
+- React Native 0.86 or newer with the New Architecture enabled
+- React Native Reanimated 4.5 or newer
+- React Native Worklets 0.10 or newer
 - iOS 16.4 or newer
 - Android API 26 or newer
 
@@ -19,6 +24,8 @@ legacy Paper implementation.
 
 ## Installation
 
+Available from [npm](https://www.npmjs.com/package/react-native-smooth-clip-view):
+
 ```sh
 npm install react-native-smooth-clip-view react-native-reanimated react-native-worklets
 ```
@@ -40,13 +47,9 @@ import { Button, StyleSheet, View } from 'react-native';
 import {
   type ClipGeometry,
   SmoothClipView,
+  createClipPresentation,
+  useSmoothClipDriver,
 } from 'react-native-smooth-clip-view';
-import {
-  interpolate,
-  useDerivedValue,
-  useSharedValue,
-  withTiming,
-} from 'react-native-reanimated';
 
 const initialClip: ClipGeometry = {
   x: 120,
@@ -58,28 +61,29 @@ const initialClip: ClipGeometry = {
 
 export function ClipExample() {
   const [expanded, setExpanded] = useState(false);
-  const progress = useSharedValue(0);
-  const animatedClip = useDerivedValue<ClipGeometry>(() => ({
-    x: interpolate(progress.value, [0, 1], [120, 0]),
-    y: interpolate(progress.value, [0, 1], [180, 0]),
-    width: interpolate(progress.value, [0, 1], [80, 320]),
-    height: interpolate(progress.value, [0, 1], [80, 480]),
-    radius: interpolate(progress.value, [0, 1], [40, 24]),
-  }));
+  const driver = useSmoothClipDriver(
+    createClipPresentation(initialClip, -initialClip.x, -initialClip.y)
+  );
 
   const toggle = () => {
     const next = !expanded;
     setExpanded(next);
-    progress.value = withTiming(next ? 1 : 0);
+    const clip = next
+      ? { x: 0, y: 0, width: 320, height: 480, radius: 24 }
+      : initialClip;
+    void driver.react.animateTo(
+      createClipPresentation(clip, -clip.x, -clip.y),
+      {
+        type: 'timing',
+        duration: 450,
+        controlPoints: [0.42, 0, 0.58, 1],
+      }
+    );
   };
 
   return (
     <View>
-      <SmoothClipView
-        initialClip={initialClip}
-        animatedClip={animatedClip}
-        style={styles.host}
-      >
+      <SmoothClipView driver={driver} style={styles.host}>
         <View style={styles.content} />
       </SmoothClipView>
       <Button title="Toggle clip" onPress={toggle} />
@@ -93,9 +97,57 @@ const styles = StyleSheet.create({
 });
 ```
 
-`initialClip` must equal `animatedClip.value` when the component mounts. This
-lets native rendering start with the correct clip before the first UI-runtime
-command is dispatched.
+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.
+
+For transitions whose endpoint is known, let Core Animation interpolate on the
+render server:
+
+```tsx
+const expandFromReact = () =>
+  driver.react.animateTo(
+    createClipPresentation(
+      { x: 0, y: 0, width: 320, height: 480, radius: 24 },
+      0,
+      0
+    ),
+    {
+      type: 'timing',
+      duration: 450,
+      controlPoints: [0.42, 0, 0.58, 1],
+    }
+  );
+```
+
+Native timing, spring, and keyframed transitions have no app callback between
+setup and completion on iOS. Core Animation interpolates the clip and content
+translation as one presentation. Android runs one C++ frame-loop driven by the
+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.
+The same driver can be grabbed by a gesture without a visual jump:
+
+```tsx
+const gesture = Gesture.Pan()
+  .onStart(() => {
+    const visible = driver.ui.beginInteraction();
+    dragStart.value = visible.clip.height;
+  })
+  .onUpdate((event) => {
+    const clip = geometryForDrag(dragStart.value, event.translationY);
+    // Per-frame hot path: writes straight to native without SharedValue
+    // bookkeeping. Assigning driver.presentation.value also works.
+    driver.ui.setScalars(clip.x, clip.y, clip.width, clip.height, clip.radius, 0, 0);
+  })
+  .onEnd(() => {
+    driver.ui.animateTo(createClipPresentation(expandedClip), {
+      type: 'spring',
+      initialVelocity: 'inherit',
+    });
+  });
+```
 
 ## API
 
@@ -103,11 +155,78 @@ command is dispatched.
 
 `SmoothClipViewProps` extends React Native `ViewProps` and adds:
 
-| Prop | Type | Description |
-| --- | --- | --- |
-| `initialClip` | `ClipGeometry` | Clip rendered synchronously at mount. |
-| `animatedClip` | `SharedValue<ClipGeometry>` | Geometry observed on the Reanimated UI runtime. |
-| `children` | `ReactNode` | Content rendered inside the fixed host. |
+| Prop       | Type               | Description                             |
+| ---------- | ------------------ | --------------------------------------- |
+| `driver`   | `SmoothClipDriver` | Reusable hybrid clip driver.            |
+| `children` | `ReactNode`        | Content rendered inside the fixed host. |
+
+### Driver
+
+- `useSmoothClipDriver(initialPresentation, options)` returns one hybrid driver
+  whose writable `presentation` SharedValue contains clip geometry and content
+  translation. Passing a `ClipGeometry` remains supported and initializes both
+  translations to zero.
+- `driver.ui` is the synchronous UI-worklet interface. `beginInteraction()`
+  freezes a transition at visible presentation state; `set()`, `animateTo()`,
+  and `cancel()` change ownership atomically.
+- `driver.ui.setScalars(x, y, width, height, radius, tx, ty)` is the per-frame
+  hot path: it writes geometry straight to native without touching
+  `driver.presentation`, skipping SharedValue bookkeeping for high-frequency
+  streams such as gestures. `driver.presentation.value` is stale after hot
+  writes by design; `beginInteraction()` remains the source of truth for
+  visible geometry, and `animateTo()` after hot writes starts from the native
+  registry's latest value rather than the stale SharedValue. Do not interleave
+  `setScalars` with `presentation.value` writes on the same driver.
+- 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; samples older than 100 ms — and the
+  web fallback — fall back to zero.
+- `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
+  before its completion callback is delivered.
+- `animateTo()` transfers ownership to native animation. Timing uses
+  cubic Bézier control points; springs accept mass, stiffness, damping, and an
+  explicit normalized velocity or `'inherit'` (the default). Keyframes accept
+  validated, monotonically increasing offsets from zero through one.
+- `cancel()` freezes visible presentation by default. Pass `'target'` as its
+  behavior to jump to the requested endpoint.
+- `options.onAnimationComplete` fires once per animation with its ID and
+  `finished` state, including cancellation, replacement, participant unmount,
+  and native-side rejection (`animateTo` then returns `0` and one
+  `finished: false` completion is delivered).
+- An `animateTo` issued before any host view has registered (for example from
+  an effect in the same commit that mounts the host, or inside a modal route
+  that attaches late) is held pending and starts with its full duration when
+  the first view registers. If no view ever registers, the pending animation
+  survives until it is replaced, cancelled, overridden by a take-ownership
+  write, or the driver is destroyed — at which point its single
+  `finished: false` completion is delivered.
+
+Do not call `driver.ui` from React code — it throws on the React runtime; use
+`driver.react` there. During a native transition, `driver.presentation.value`
+is the requested target, not a per-frame mirror of the native presentation
+layer. `beginInteraction()` returns geometry normalized against the host
+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.
+
+### `SmoothClipPresentation`
+
+```ts
+type SmoothClipPresentation = Readonly<{
+  clip: ClipGeometry;
+  contentTranslateX: number;
+  contentTranslateY: number;
+}>;
+```
+
+Use the content translation fields when a clipped viewport must reveal a
+fixed-size child without a separate Reanimated transform. Native transitions
+animate clip position, bounds, radius, and content translation together.
 
 ### `ClipGeometry`
 
@@ -131,6 +250,15 @@ negative sizes, and clamps `radius` to half of the visible shortest edge.
 contract for tests and non-native calculations. Native bounds remain
 authoritative at render time.
 
+## Migrating from 0.0.x
+
+Version 0.1.0 removes the `initialClip` and `animatedClip` props in favor of
+the driver API: create a driver with `useSmoothClipDriver(initialPresentation)`,
+pass it as the `driver` prop, and move per-frame updates from the
+`animatedClip` SharedValue to `driver.presentation.value` (or
+`driver.ui.setScalars`). Autonomous transitions move from Reanimated
+`withTiming`/`withSpring` to `driver.ui.animateTo` / `driver.react.animateTo`.
+
 ## Layout and styling contract
 
 - Give the host its fixed maximum `width` and `height`; clipping never changes
@@ -149,20 +277,20 @@ The [`example`](./example) workspace is an Expo SDK 57 app that exercises the
 package through its public import on iOS, Android, and web.
 
 ```sh
-yarn
-yarn example ios
-yarn example android
-yarn example web
+npm install
+npm run example -- ios
+npm run example -- android
+npm run example -- web
 ```
 
 Run the repository checks with:
 
 ```sh
-yarn lint
-yarn typecheck
-yarn test
-yarn prepare
-yarn example build:web
+npm run lint
+npm run typecheck
+npm test
+npm run prepare
+npm run example -- build:web
 ```
 
 ## License

package/SmoothClipView.podspec

@@ -12,8 +12,14 @@ Pod::Spec.new do |s|
 
   s.platforms    = { :ios => "16.4" }
   s.source       = { :git => "https://github.com/kbrattli/react-native-smooth-clip-view.git", :tag => "v#{s.version}" }
-  s.source_files = "ios/*.{h,m,mm,swift,cpp}"
-  s.private_header_files = "ios/*.h"
+  s.source_files = ["ios/*.{h,m,mm,swift,cpp}", "cpp/*.{h,cpp}"]
+  s.private_header_files = ["ios/*.h", "cpp/*.h"]
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/cpp\" \"$(PODS_TARGET_SRCROOT)/ios\"",
+    # Signpost instrumentation is compiled into Debug only; Release interactive
+    # frames must not generate signpost IDs or intervals.
+    "GCC_PREPROCESSOR_DEFINITIONS[config=Debug]" => "$(inherited) SMOOTH_CLIP_ENABLE_SIGNPOSTS=1"
+  }
 
   install_modules_dependencies(s)
 

package/android/CMakeLists.txt

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.16)
+project(smoothclipview)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(fbjni REQUIRED CONFIG)
+find_package(ReactAndroid REQUIRED CONFIG)
+
+# Folly compile flags used across the React Native C++ surface.
+include("${REACT_NATIVE_DIR}/ReactAndroid/cmake-utils/folly-flags.cmake")
+add_compile_options(${folly_FLAGS})
+
+file(GLOB smoothclip_SOURCES CONFIGURE_DEPENDS
+     "${CMAKE_CURRENT_SOURCE_DIR}/src/main/cpp/*.cpp")
+
+add_library(smoothclipview SHARED ${smoothclip_SOURCES})
+
+# C++20, RTTI, exceptions and React Native macros.
+include("${REACT_NATIVE_DIR}/ReactCommon/cmake-utils/react-native-flags.cmake")
+target_compile_reactnative_options(smoothclipview PUBLIC)
+
+target_include_directories(
+  smoothclipview
+  PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src/main/cpp"
+          "${CMAKE_CURRENT_SOURCE_DIR}/../cpp"
+          "${REACT_NATIVE_DIR}/ReactCommon"
+          "${REACT_NATIVE_DIR}/ReactCommon/jsi"
+          "${REACT_NATIVE_DIR}/ReactCommon/callinvoker"
+          "${REACT_NATIVE_DIR}/ReactCommon/react/nativemodule/core/ReactCommon"
+          "${REACT_NATIVE_DIR}/ReactAndroid/src/main/jni/react/turbomodule")
+
+target_link_libraries(
+  smoothclipview
+  android
+  log
+  fbjni::fbjni
+  ReactAndroid::jsi
+  ReactAndroid::reactnative)

package/android/build.gradle

@@ -28,17 +28,74 @@ apply plugin: "com.android.library"
 apply plugin: "kotlin-android"
 apply plugin: "com.facebook.react"
 
+def resolveReactNativeDirectory() {
+  def reactNativeLocation = rootProject.ext.has("REACT_NATIVE_NODE_MODULES_DIR")
+    ? rootProject.ext.get("REACT_NATIVE_NODE_MODULES_DIR")
+    : null
+  if (reactNativeLocation != null) {
+    return file(reactNativeLocation)
+  }
+
+  // Fallback to node resolver for custom directory structures like monorepos.
+  def reactNativePackage = file(
+    providers.exec {
+      workingDir(rootDir)
+      commandLine("node", "--print", "require.resolve('react-native/package.json')")
+    }.standardOutput.asText.get().trim()
+  )
+  if (reactNativePackage.exists()) {
+    return reactNativePackage.parentFile
+  }
+
+  throw new GradleException("[react-native-smooth-clip-view] Unable to resolve react-native in node_modules.")
+}
+
+def reactNativeRootDir = resolveReactNativeDirectory()
+
+def reactNativeArchitectures() {
+  def value = rootProject.findProperty("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
 android {
   namespace "com.smoothclipview"
   compileSdkVersion getExtOrDefault("compileSdkVersion")
 
+  if (rootProject.hasProperty("ndkPath")) {
+    ndkPath rootProject.ext.ndkPath
+  }
+  if (rootProject.hasProperty("ndkVersion")) {
+    ndkVersion rootProject.ext.ndkVersion
+  } else {
+    ndkVersion "27.1.12297006"
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
   defaultConfig {
     minSdkVersion getExtOrDefault("minSdkVersion")
     targetSdkVersion getExtOrDefault("targetSdkVersion")
+    // C++ resolves SmoothClipView by name and calls setClipPresentationDip via
+    // a cached jmethodID; consumer minification must not rename or strip them.
+    consumerProguardFiles "proguard-rules.pro"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-O2", "-frtti", "-fexceptions", "-Wall", "-std=c++20"
+        arguments "-DANDROID_STL=c++_shared",
+                  "-DREACT_NATIVE_DIR=${reactNativeRootDir}"
+        abiFilters(*reactNativeArchitectures())
+      }
+    }
   }
 
-  buildFeatures {
-    buildConfig true
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
   }
 
   buildTypes {
@@ -55,6 +112,16 @@ android {
     sourceCompatibility JavaVersion.VERSION_1_8
     targetCompatibility JavaVersion.VERSION_1_8
   }
+
+  packagingOptions {
+    // Provided by the host application at runtime.
+    excludes += [
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libreactnative.so",
+    ]
+  }
 }
 
 dependencies {

package/android/proguard-rules.pro

@@ -0,0 +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.
+-keep class com.smoothclipview.SmoothClipView { *; }
+-keep class com.smoothclipview.SmoothClipBindings { *; }

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

@@ -0,0 +1,59 @@
+#pragma once
+
+#include <ReactCommon/CallInvoker.h>
+#include <fbjni/fbjni.h>
+#include <jsi/jsi.h>
+
+#include <memory>
+
+#include "SmoothClipRegistry.h"
+#include "SmoothClipSharedGeometry.h"
+
+namespace smoothclip {
+
+// fbjni wrapper around com.smoothclipview.SmoothClipView. Only the primitive
+// clip setter is invoked from native, so the Kotlin view stays a thin outline
+// clipper while all driver state lives in the shared C++ registry.
+struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
+  static constexpr auto kJavaDescriptor = "Lcom/smoothclipview/SmoothClipView;";
+
+  void applyClip(const Presentation &presentation) const;
+  void applyClipPx(
+      const NormalizedClip &clip,
+      double contentTranslateXPx,
+      double contentTranslateYPx) const;
+};
+
+// Called from Kotlin (SmoothClipViewManager) on the UI thread when a Fabric
+// view mounts/unmounts. The registry retains a global ref for the view.
+void registerViewAndroid(
+    uint64_t driverId,
+    facebook::jni::alias_ref<JSmoothClipView> view,
+    Presentation initialPresentation,
+    double density,
+    double hostWidthPx,
+    double hostHeightPx);
+// Refreshes a registered view's density / host size (px) and synchronously
+// redelivers the driver's visible value pre-normalized against them.
+void setViewHostGeometryAndroid(
+    uint64_t driverId,
+    facebook::jni::alias_ref<JSmoothClipView> view,
+    double density,
+    double hostWidthPx,
+    double hostHeightPx);
+void unregisterViewAndroid(
+    uint64_t driverId,
+    facebook::jni::alias_ref<JSmoothClipView> view);
+
+// 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.
+void installBindings(
+    facebook::jsi::Runtime &runtime,
+    const std::shared_ptr<facebook::react::CallInvoker> &callInvoker);
+
+// Releases the listener functions and completion sink while the JS runtime is
+// still alive. Called from SmoothClipModule.invalidate() during host teardown.
+void invalidateBindings();
+
+} // namespace smoothclip