react-native-smooth-clip-view 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 kbrattli
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# 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.
+
+## Requirements
+
+- React Native 0.85 or newer with the New Architecture enabled
+- React Native Reanimated 4.3 or newer
+- iOS 16.4 or newer
+- Android API 26 or newer
+
+The package supports iOS, Android, and React Native Web. It does not include a
+legacy Paper implementation.
+
+## Installation
+
+```sh
+npm install react-native-smooth-clip-view react-native-reanimated react-native-worklets
+```
+
+For iOS, install pods after adding the package:
+
+```sh
+cd ios && pod install
+```
+
+Follow the Reanimated installation instructions for your React Native setup.
+Expo SDK 57 configures the required Babel plugin through `babel-preset-expo`.
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Button, StyleSheet, View } from 'react-native';
+import {
+  type ClipGeometry,
+  SmoothClipView,
+} from 'react-native-smooth-clip-view';
+import {
+  interpolate,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+
+const initialClip: ClipGeometry = {
+  x: 120,
+  y: 180,
+  width: 80,
+  height: 80,
+  radius: 40,
+};
+
+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 toggle = () => {
+    const next = !expanded;
+    setExpanded(next);
+    progress.value = withTiming(next ? 1 : 0);
+  };
+
+  return (
+    <View>
+      <SmoothClipView
+        initialClip={initialClip}
+        animatedClip={animatedClip}
+        style={styles.host}
+      >
+        <View style={styles.content} />
+      </SmoothClipView>
+      <Button title="Toggle clip" onPress={toggle} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  host: { width: 320, height: 480 },
+  content: { width: 320, height: 480, backgroundColor: '#112743' },
+});
+```
+
+`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.
+
+## API
+
+### `SmoothClipView`
+
+`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. |
+
+### `ClipGeometry`
+
+```ts
+type ClipGeometry = Readonly<{
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  radius: number;
+}>;
+```
+
+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.
+
+### `normalizeClipGeometry`
+
+`normalizeClipGeometry(geometry, bounds)` mirrors the native normalization
+contract for tests and non-native calculations. Native bounds remain
+authoritative at render time.
+
+## Layout and styling contract
+
+- 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.
+
+## 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.
+
+```sh
+yarn
+yarn example ios
+yarn example android
+yarn example web
+```
+
+Run the repository checks with:
+
+```sh
+yarn lint
+yarn typecheck
+yarn test
+yarn prepare
+yarn example build:web
+```
+
+## License
+
+MIT

package/SmoothClipView.podspec

@@ -0,0 +1,24 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "SmoothClipView"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  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"
+
+  install_modules_dependencies(s)
+
+  s.test_spec "Tests" do |test_spec|
+    test_spec.framework = "XCTest"
+    test_spec.source_files = "ios/tests/**/*.{m,mm}"
+  end
+end

package/android/build.gradle

@@ -0,0 +1,63 @@
+buildscript {
+  ext.SmoothClipView = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 26,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+    return SmoothClipView[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.smoothclipview"
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

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

@@ -0,0 +1,93 @@
+package com.smoothclipview
+
+import android.view.View
+import kotlin.math.max
+import kotlin.math.min
+
+/**
+ * Normalizes clip geometry without allocating a result object. The callback is
+ * inlined into the view's command path so per-frame updates stay allocation-free.
+ */
+internal inline fun normalizeClipGeometryPx(
+    x: Float,
+    y: Float,
+    width: Float,
+    height: Float,
+    radius: Float,
+    hostWidth: Float,
+    hostHeight: Float,
+    apply: (
+        left: Float,
+        top: Float,
+        right: Float,
+        bottom: Float,
+        radius: Float,
+    ) -> Unit,
+): Boolean {
+    if (!x.isFinite() || !y.isFinite() || !width.isFinite() ||
+        !height.isFinite() || !radius.isFinite() ||
+        !hostWidth.isFinite() || !hostHeight.isFinite()
+    ) {
+        return false
+    }
+
+    val boundedHostWidth = hostWidth.coerceAtLeast(0f)
+    val boundedHostHeight = hostHeight.coerceAtLeast(0f)
+    val requestedRight = x + width.coerceAtLeast(0f)
+    val requestedBottom = y + height.coerceAtLeast(0f)
+    val left = x.coerceIn(0f, boundedHostWidth)
+    val top = y.coerceIn(0f, boundedHostHeight)
+    val right = requestedRight.coerceIn(0f, boundedHostWidth)
+    val bottom = requestedBottom.coerceIn(0f, boundedHostHeight)
+    val visibleWidth = max(0f, right - left)
+    val visibleHeight = max(0f, bottom - top)
+    val normalizedRadius = min(
+        radius.coerceAtLeast(0f),
+        min(visibleWidth, visibleHeight) / 2f,
+    )
+
+    apply(left, top, right, bottom, normalizedRadius)
+    return true
+}
+
+internal fun clipVisibility(isEmpty: Boolean): Int =
+    if (isEmpty) View.INVISIBLE else View.VISIBLE
+
+internal fun clipAccessibility(
+    isEmpty: Boolean,
+    requestedAccessibility: Int,
+): Int =
+    if (isEmpty) {
+        View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
+    } else {
+        requestedAccessibility
+    }
+
+internal fun containsRoundedPointPx(
+    x: Float,
+    y: Float,
+    left: Float,
+    top: Float,
+    right: Float,
+    bottom: Float,
+    radius: Float,
+    isEmpty: Boolean,
+): Boolean {
+    if (isEmpty || x < left || x > right || y < top || y > bottom) {
+        return false
+    }
+
+    if (radius <= 0f) return true
+
+    val innerLeft = left + radius
+    val innerRight = right - radius
+    val innerTop = top + radius
+    val innerBottom = bottom - radius
+    if (x in innerLeft..innerRight || y in innerTop..innerBottom) return true
+
+    val centerX = if (x < innerLeft) innerLeft else innerRight
+    val centerY = if (y < innerTop) innerTop else innerBottom
+    val dx = x - centerX
+    val dy = y - centerY
+    return dx * dx + dy * dy <= radius * radius
+}

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

@@ -0,0 +1,190 @@
+package com.smoothclipview
+
+import android.graphics.Outline
+import android.view.MotionEvent
+import android.view.View
+import android.view.ViewOutlineProvider
+import com.facebook.react.uimanager.PixelUtil
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.views.view.ReactViewGroup
+import kotlin.math.roundToInt
+
+class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
+    private var requestedX = 0f
+    private var requestedY = 0f
+    private var requestedWidth = 0f
+    private var requestedHeight = 0f
+    private var requestedRadius = 0f
+    private var clipLeft = 0f
+    private var clipTop = 0f
+    private var clipRight = 0f
+    private var clipBottom = 0f
+    private var clipRadius = 0f
+    private var clipIsEmpty = true
+    private var requestedImportantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_AUTO
+    private var acceptingTouchStream = false
+
+    private val clipOutlineProvider = object : ViewOutlineProvider() {
+        override fun getOutline(view: View, outline: Outline) {
+            if (clipIsEmpty) {
+                outline.setEmpty()
+                return
+            }
+
+            outline.setRoundRect(
+                clipLeft.roundToInt(),
+                clipTop.roundToInt(),
+                clipRight.roundToInt(),
+                clipBottom.roundToInt(),
+                clipRadius,
+            )
+        }
+    }
+
+    init {
+        outlineProvider = clipOutlineProvider
+        clipToOutline = true
+        visibility = INVISIBLE
+        importantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
+    }
+
+    fun setClipGeometryDip(
+        x: Double,
+        y: Double,
+        width: Double,
+        height: Double,
+        radius: Double,
+    ) {
+        if (!x.isFinite() || !y.isFinite() || !width.isFinite() ||
+            !height.isFinite() || !radius.isFinite()
+        ) {
+            return
+        }
+
+        val nextX = PixelUtil.toPixelFromDIP(x).toFloat()
+        val nextY = PixelUtil.toPixelFromDIP(y).toFloat()
+        val nextWidth = PixelUtil.toPixelFromDIP(width).toFloat()
+        val nextHeight = PixelUtil.toPixelFromDIP(height).toFloat()
+        val nextRadius = PixelUtil.toPixelFromDIP(radius).toFloat()
+        if (!nextX.isFinite() || !nextY.isFinite() || !nextWidth.isFinite() ||
+            !nextHeight.isFinite() || !nextRadius.isFinite()
+        ) {
+            return
+        }
+
+        requestedX = nextX
+        requestedY = nextY
+        requestedWidth = nextWidth
+        requestedHeight = nextHeight
+        requestedRadius = nextRadius
+        applyRequestedGeometry()
+    }
+
+    private fun applyRequestedGeometry() {
+        normalizeClipGeometryPx(
+            requestedX,
+            requestedY,
+            requestedWidth,
+            requestedHeight,
+            requestedRadius,
+            width.toFloat(),
+            height.toFloat(),
+        ) { left, top, right, bottom, radius ->
+            val isEmpty = right <= left || bottom <= top
+            val geometryChanged =
+                left != clipLeft || top != clipTop || right != clipRight ||
+                    bottom != clipBottom || radius != clipRadius
+
+            if (!geometryChanged && isEmpty == clipIsEmpty) {
+                return@normalizeClipGeometryPx
+            }
+
+            clipLeft = left
+            clipTop = top
+            clipRight = right
+            clipBottom = bottom
+            clipRadius = radius
+
+            if (isEmpty != clipIsEmpty) {
+                clipIsEmpty = isEmpty
+                visibility = clipVisibility(isEmpty)
+                importantForAccessibility = clipAccessibility(
+                    isEmpty,
+                    requestedImportantForAccessibility,
+                )
+                if (isEmpty) acceptingTouchStream = false
+            }
+
+            invalidateOutline()
+        }
+    }
+
+    override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
+        super.onSizeChanged(w, h, oldw, oldh)
+        applyRequestedGeometry()
+    }
+
+    private fun containsRoundedPoint(x: Float, y: Float): Boolean {
+        return containsRoundedPointPx(
+            x,
+            y,
+            clipLeft,
+            clipTop,
+            clipRight,
+            clipBottom,
+            clipRadius,
+            clipIsEmpty,
+        )
+    }
+
+    override fun dispatchTouchEvent(event: MotionEvent): Boolean {
+        when (event.actionMasked) {
+            MotionEvent.ACTION_DOWN -> {
+                acceptingTouchStream = containsRoundedPoint(event.x, event.y)
+                if (!acceptingTouchStream) return false
+            }
+            MotionEvent.ACTION_CANCEL, MotionEvent.ACTION_UP -> {
+                val result = if (acceptingTouchStream) {
+                    super.dispatchTouchEvent(event)
+                } else {
+                    false
+                }
+                acceptingTouchStream = false
+                return result
+            }
+        }
+
+        return acceptingTouchStream && super.dispatchTouchEvent(event)
+    }
+
+    fun setRequestedImportantForAccessibility(value: Int) {
+        requestedImportantForAccessibility = value
+        reapplyClipPresentation()
+    }
+
+    fun reapplyClipPresentation() {
+        val expectedVisibility = clipVisibility(clipIsEmpty)
+        if (visibility != expectedVisibility) {
+            visibility = expectedVisibility
+        }
+
+        val expectedAccessibility = clipAccessibility(
+            clipIsEmpty,
+            requestedImportantForAccessibility,
+        )
+        if (importantForAccessibility != expectedAccessibility) {
+            importantForAccessibility = expectedAccessibility
+        }
+    }
+
+    fun resetClipState() {
+        acceptingTouchStream = false
+        requestedX = 0f
+        requestedY = 0f
+        requestedWidth = 0f
+        requestedHeight = 0f
+        requestedRadius = 0f
+        requestedImportantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_AUTO
+        applyRequestedGeometry()
+    }
+}

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

@@ -0,0 +1,104 @@
+package com.smoothclipview
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.viewmanagers.SmoothClipViewManagerDelegate
+import com.facebook.react.viewmanagers.SmoothClipViewManagerInterface
+
+@ReactModule(name = SmoothClipViewManager.NAME)
+class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
+    SmoothClipViewManagerInterface<SmoothClipView> {
+    private val delegate =
+        SmoothClipViewManagerDelegate<SmoothClipView, SmoothClipViewManager>(this)
+
+    private data class PendingInitialClip(
+        var x: Double = 0.0,
+        var y: Double = 0.0,
+        var width: Double = 0.0,
+        var height: Double = 0.0,
+        var radius: Double = 0.0,
+    )
+
+    private val pendingInitialClips = java.util.WeakHashMap<SmoothClipView, PendingInitialClip>()
+
+    override fun getName(): String = NAME
+
+    override fun getDelegate(): ViewManagerDelegate<SmoothClipView> = delegate
+
+    override fun createViewInstance(context: ThemedReactContext): SmoothClipView =
+        SmoothClipView(context).also { pendingInitialClips[it] = PendingInitialClip() }
+
+    override fun setImportantForAccessibility(
+        view: SmoothClipView,
+        importantForAccessibility: String?,
+    ) {
+        super.setImportantForAccessibility(view, importantForAccessibility)
+        view.setRequestedImportantForAccessibility(view.importantForAccessibility)
+    }
+
+    @ReactProp(name = "initialClipX")
+    override fun setInitialClipX(view: SmoothClipView, value: Double) {
+        pendingInitialClips.getOrPut(view) { PendingInitialClip() }.x = value
+    }
+
+    @ReactProp(name = "initialClipY")
+    override fun setInitialClipY(view: SmoothClipView, value: Double) {
+        pendingInitialClips.getOrPut(view) { PendingInitialClip() }.y = value
+    }
+
+    @ReactProp(name = "initialClipWidth")
+    override fun setInitialClipWidth(view: SmoothClipView, value: Double) {
+        pendingInitialClips.getOrPut(view) { PendingInitialClip() }.width = value
+    }
+
+    @ReactProp(name = "initialClipHeight")
+    override fun setInitialClipHeight(view: SmoothClipView, value: Double) {
+        pendingInitialClips.getOrPut(view) { PendingInitialClip() }.height = value
+    }
+
+    @ReactProp(name = "initialClipRadius")
+    override fun setInitialClipRadius(view: SmoothClipView, value: Double) {
+        pendingInitialClips.getOrPut(view) { PendingInitialClip() }.radius = value
+    }
+
+    override fun setClipGeometry(
+        view: SmoothClipView,
+        x: Double,
+        y: Double,
+        width: Double,
+        height: Double,
+        radius: Double,
+    ) {
+        pendingInitialClips.remove(view)
+        view.setClipGeometryDip(x, y, width, height, radius)
+    }
+
+    override fun onAfterUpdateTransaction(view: SmoothClipView) {
+        super.onAfterUpdateTransaction(view)
+        val initial = pendingInitialClips.remove(view)
+        if (initial == null) {
+            view.reapplyClipPresentation()
+        } else {
+            view.setClipGeometryDip(
+                initial.x,
+                initial.y,
+                initial.width,
+                initial.height,
+                initial.radius,
+            )
+        }
+    }
+
+    override fun onDropViewInstance(view: SmoothClipView) {
+        pendingInitialClips.remove(view)
+        view.resetClipState()
+        super.onDropViewInstance(view)
+    }
+
+    companion object {
+        const val NAME = "SmoothClipView"
+    }
+}

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

@@ -0,0 +1,21 @@
+package com.smoothclipview
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+class SmoothClipViewPackage : BaseReactPackage() {
+    override fun createViewManagers(
+        reactContext: ReactApplicationContext,
+    ): List<ViewManager<*, *>> = listOf(SmoothClipViewManager())
+
+    override fun getModule(
+        name: String,
+        reactContext: ReactApplicationContext,
+    ): NativeModule? = null
+
+    override fun getReactModuleInfoProvider() =
+        ReactModuleInfoProvider { emptyMap() }
+}