react-native-smooth-clip-view 0.2.5 → 0.2.7

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

@@ -54,17 +54,67 @@ internal inline fun normalizeClipGeometryPx(
 internal fun clipVisibility(isEmpty: Boolean): Int =
     if (isEmpty) View.INVISIBLE else View.VISIBLE
 
+/** Rounded integer origin of an outline edge. */
+internal fun outlineOrigin(value: Float): Int = value.roundToInt()
+
+/**
+ * Rounded far edge, derived from the rounded origin plus the rounded extent.
+ *
+ * `Outline.setRoundRect` takes an int rect, and rounding the two edges
+ * independently makes `round(far) - round(origin)` alternate between the floor
+ * and the ceil of a *constant* extent as the origin's fraction sweeps: a pure
+ * translation breathes the emitted size by 1 px, frame after frame, while the
+ * content inside translates in floats. That oscillation is what reads as
+ * shimmer on the slow tail of an animation, where the per-frame delta drops
+ * below a pixel and the rounding becomes the motion.
+ *
+ * An int rect cannot hold origin, far edge and extent within half a pixel at
+ * once (extent = far - origin, so bounding both edges at 0.5 bounds the extent
+ * at 1.0); the only choice is which error oscillates. Deriving the far edge
+ * makes the emitted extent a pure function of the true extent — stable, error
+ * <= 0.5 px — and moves the slack onto the far edge, <= 1.0 px and static. A
+ * static bias does not read as jank; an alternating one does.
+ *
+ * Two consequences, both benign:
+ * - The far edge can overshoot the host bound by up to 1 px instead of 0.5. The
+ *   view's own bounds already clip, so an over-large outline just means that
+ *   edge is not clipped that frame — which independent rounding already
+ *   produced whenever `round(far)` rounded up.
+ * - A sub-pixel extent (0 < extent < 0.5) rounds to a degenerate rect, which
+ *   `Outline.setRoundRect` collapses to `setEmpty()`. Independent rounding hit
+ *   that state on some frames and a 1 px rect on others, i.e. it flickered;
+ *   deriving the far edge makes it consistent. The emitted integer rect also
+ *   governs visibility, accessibility and hit testing, so a view never remains
+ *   logically visible while its outline clips every pixel.
+ */
+internal fun outlineFarEdge(origin: Float, far: Float): Int =
+    outlineOrigin(origin) + (far - origin).roundToInt()
+
+/** Exactly mirrors the non-empty requirement of Outline.setRoundRect(Int...). */
+internal fun outlineRectIsEmpty(
+    left: Int,
+    top: Int,
+    right: Int,
+    bottom: Int,
+): Boolean = right <= left || bottom <= top
+
 /**
  * Outline dedupe on the rounded integer physical-pixel edges actually emitted
- * to the outline provider. Sub-pixel motion that rounds to the cached integers
- * must not invalidate the outline; the radius stays a float comparison because
- * it is emitted to the outline as a float.
+ * to the outline provider. Takes the already-derived edges rather than raw
+ * floats so the caller rounds once per frame and the predicate can never drift
+ * from what the provider emits; the radius stays a float comparison because it
+ * is emitted to the outline as a float.
+ *
+ * Sub-pixel motion that rounds to the cached integers must NOT invalidate the
+ * outline — it is carried on the view's translation instead (see
+ * SmoothClipView.applyClipPlacement), which is both cheaper and smoother than
+ * restaging an identical rect.
  */
 internal fun outlineChanged(
-    left: Float,
-    top: Float,
-    right: Float,
-    bottom: Float,
+    left: Int,
+    top: Int,
+    right: Int,
+    bottom: Int,
     radius: Float,
     cachedLeft: Int,
     cachedTop: Int,
@@ -72,10 +122,10 @@ internal fun outlineChanged(
     cachedBottom: Int,
     cachedRadius: Float,
 ): Boolean =
-    left.roundToInt() != cachedLeft ||
-        top.roundToInt() != cachedTop ||
-        right.roundToInt() != cachedRight ||
-        bottom.roundToInt() != cachedBottom ||
+    left != cachedLeft ||
+        top != cachedTop ||
+        right != cachedRight ||
+        bottom != cachedBottom ||
         radius != cachedRadius
 
 internal fun clipAccessibility(

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

@@ -1,5 +1,6 @@
 package com.smoothclipview
 
+import android.view.Choreographer
 import com.facebook.proguard.annotations.DoNotStrip
 import com.facebook.react.turbomodule.core.interfaces.BindingsInstallerHolder
 
@@ -31,6 +32,7 @@ internal object SmoothClipBindings {
         density: Double,
         widthPx: Double,
         heightPx: Double,
+        lifecycleVisible: Boolean,
     )
 
     /**
@@ -48,15 +50,37 @@ internal object SmoothClipBindings {
     external fun nativeUnregisterView(driverId: Double, view: SmoothClipView)
 
     /**
-     * Notifies the registry that a registered view attached to a window; a
-     * latched animation may only start once a view can produce a visible
-     * frame (attached and with real host geometry).
+     * Pushes both positive and negative attachment/window-visibility state.
+     * The registry combines it with real host geometry before a latch can run.
      */
-    external fun nativeViewBecameDisplayable(driverId: Double, view: SmoothClipView)
+    external fun nativeSetViewLifecycleVisibility(
+        driverId: Double,
+        view: SmoothClipView,
+        lifecycleVisible: Boolean,
+    )
 
     /**
      * Releases runtime-bound listener state during host teardown; must run
      * while the JS runtime is still alive (module invalidate).
      */
     external fun nativeInvalidate()
+
+    private val frameCallback = Choreographer.FrameCallback { frameTimeNanos ->
+        nativeOnFrame(frameTimeNanos)
+    }
+
+    /**
+     * Posts the registry frame loop into this thread's Java Choreographer.
+     * Plain postFrameCallback lands in the animation phase, so the advance
+     * runs in the same doFrame pass as Reanimated prop updates — always
+     * before the traversal draws. The C++ registry calls this (main thread
+     * only) and dedupes posts with its own scheduled flag.
+     */
+    @JvmStatic
+    fun scheduleFrame() {
+        Choreographer.getInstance().postFrameCallback(frameCallback)
+    }
+
+    /** Advances the frame loop with the doFrame vsync timestamp. */
+    external fun nativeOnFrame(frameTimeNanos: Long)
 }

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

@@ -39,6 +39,7 @@ class SmoothClipModule(context: ReactApplicationContext) :
         contentTranslateX: Double,
         contentTranslateY: Double,
         takeOwnership: Boolean,
+        overridePendingAnimation: Boolean,
     ) = Unit
 
     override fun beginInteraction(driverId: Double): WritableArray =

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

@@ -9,7 +9,6 @@ import com.facebook.proguard.annotations.DoNotStrip
 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) {
     internal val contentContainer = ReactViewGroup(context)
@@ -32,8 +31,17 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     private var outlineRight = 0
     private var outlineBottom = 0
     private var clipIsEmpty = true
+    // Sub-pixel remainder of the clip origin, carried on this view's own
+    // translation and subtracted back out of the content container.
+    private var clipResidualX = 0f
+    private var clipResidualY = 0f
+    // The consumer's `transform` translation, kept apart from the residual so
+    // the two compose instead of clobbering each other.
+    private var userTranslationX = 0f
+    private var userTranslationY = 0f
     private var requestedImportantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_AUTO
     private var acceptingTouchStream = false
+    private var retainedTouchEvent: MotionEvent? = null
 
     /** Driver this view is registered with in the native registry (0 = none). */
     internal var boundDriverId: Double = 0.0
@@ -110,14 +118,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         requestedWidth = nextWidth
         requestedHeight = nextHeight
         requestedRadius = nextRadius
-        if (requestedContentTranslateX != nextContentTranslateX) {
-            requestedContentTranslateX = nextContentTranslateX
-            contentContainer.translationX = nextContentTranslateX
-        }
-        if (requestedContentTranslateY != nextContentTranslateY) {
-            requestedContentTranslateY = nextContentTranslateY
-            contentContainer.translationY = nextContentTranslateY
-        }
+        requestedContentTranslateX = nextContentTranslateX
+        requestedContentTranslateY = nextContentTranslateY
         applyRequestedGeometry()
     }
 
@@ -136,14 +138,11 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         contentTranslateX: Float,
         contentTranslateY: Float,
     ) {
-        if (requestedContentTranslateX != contentTranslateX) {
-            requestedContentTranslateX = contentTranslateX
-            contentContainer.translationX = contentTranslateX
-        }
-        if (requestedContentTranslateY != contentTranslateY) {
-            requestedContentTranslateY = contentTranslateY
-            contentContainer.translationY = contentTranslateY
-        }
+        // Stored only; applyNormalizedClipPx computes the clip residual and
+        // applyClipPlacement writes both translations together, because the
+        // content's final offset depends on the residual as well.
+        requestedContentTranslateX = contentTranslateX
+        requestedContentTranslateY = contentTranslateY
         applyNormalizedClipPx(left, top, right, bottom, radius)
     }
 
@@ -168,12 +167,28 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         bottom: Float,
         radius: Float,
     ) {
-        val isEmpty = right <= left || bottom <= top
+        // Far edges are derived, not rounded independently: see outlineFarEdge.
+        // Independent rounding breathes the emitted size by 1 px under pure
+        // translation, which is the visible artifact once an animation's tail
+        // slows below a pixel per frame.
+        val nextOutlineLeft = outlineOrigin(left)
+        val nextOutlineTop = outlineOrigin(top)
+        val nextOutlineRight = outlineFarEdge(left, right)
+        val nextOutlineBottom = outlineFarEdge(top, bottom)
+        // Outline.setRoundRect collapses a degenerate integer rect to empty.
+        // Use the exact emitted geometry as the single semantic source for
+        // rendering, visibility, accessibility and hit testing.
+        val isEmpty = outlineRectIsEmpty(
+            nextOutlineLeft,
+            nextOutlineTop,
+            nextOutlineRight,
+            nextOutlineBottom,
+        )
         val outlineGeometryChanged = outlineChanged(
-            left,
-            top,
-            right,
-            bottom,
+            nextOutlineLeft,
+            nextOutlineTop,
+            nextOutlineRight,
+            nextOutlineBottom,
             radius,
             outlineLeft,
             outlineTop,
@@ -182,33 +197,84 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
             clipRadius,
         )
 
-        if (!outlineGeometryChanged && isEmpty == clipIsEmpty) {
-            return
-        }
-
         clipLeft = left
         clipTop = top
         clipRight = right
         clipBottom = bottom
         clipRadius = radius
-        outlineLeft = left.roundToInt()
-        outlineTop = top.roundToInt()
-        outlineRight = right.roundToInt()
-        outlineBottom = bottom.roundToInt()
+        // Whatever integer rounding threw away, carried on this view's own
+        // translation so the clip edge still lands where the driver asked
+        // instead of snapping to the pixel grid while the content it clips
+        // slides in floats. It is a single scalar per axis only because the far
+        // edges are derived from the origin — with independently rounded edges
+        // no one translation could place both.
+        clipResidualX = left - nextOutlineLeft
+        clipResidualY = top - nextOutlineTop
+        applyClipPlacement()
 
         if (isEmpty != clipIsEmpty) {
+            if (isEmpty) cancelAcceptedTouchStream()
             clipIsEmpty = isEmpty
             visibility = clipVisibility(isEmpty)
             importantForAccessibility = clipAccessibility(
                 isEmpty,
                 requestedImportantForAccessibility,
             )
-            if (isEmpty) acceptingTouchStream = false
         }
 
+        // An emptiness transition necessarily changes at least one emitted
+        // edge, so the existing edge/radius key cannot skip invalidateOutline.
+        if (!outlineGeometryChanged) return
+
+        outlineLeft = nextOutlineLeft
+        outlineTop = nextOutlineTop
+        outlineRight = nextOutlineRight
+        outlineBottom = nextOutlineBottom
+        // Schedules the traversal too: invalidateOutline() ends in
+        // invalidateViewProperty(), which damages this view in its parent up
+        // to ViewRootImpl.scheduleTraversals(). A plain invalidate() on top
+        // would only add PFLAG_INVALIDATED, forcing a display-list re-record
+        // every frame to restage an outline the RenderNode applies as a
+        // property.
         invalidateOutline()
     }
 
+    /**
+     * Single writer for both translations. The view carries the sub-pixel
+     * remainder of the clip origin; the content container subtracts it back out
+     * so only the clip edge moves and the content stays exactly where the
+     * driver put it. Every write self-dedupes inside View.setTranslationX, so
+     * calling this on an unchanged frame costs four float comparisons.
+     */
+    private fun applyClipPlacement() {
+        super.setTranslationX(userTranslationX + clipResidualX)
+        super.setTranslationY(userTranslationY + clipResidualY)
+        contentContainer.translationX = requestedContentTranslateX - clipResidualX
+        contentContainer.translationY = requestedContentTranslateY - clipResidualY
+    }
+
+    // The clip's sub-pixel placement and the consumer's `transform` prop share
+    // one property, so they are composed rather than allowed to overwrite each
+    // other. RN routes every transform write through these setters
+    // (BaseViewManager.setTransformProperty), so intercepting them is enough.
+    //
+    // The getters are deliberately NOT overridden to hide the residual:
+    // View.setTranslationX dedupes by calling getTranslationX() virtually, so
+    // reporting the consumer's value there would make every write look like a
+    // change and re-invalidate the view on frames where nothing moved. The cost
+    // of leaving them alone is that a read-modify-write of translationX picks up
+    // the residual twice — sub-pixel, and nothing in RN's transform path reads
+    // back before writing.
+    override fun setTranslationX(translationX: Float) {
+        userTranslationX = translationX
+        super.setTranslationX(translationX + clipResidualX)
+    }
+
+    override fun setTranslationY(translationY: Float) {
+        userTranslationY = translationY
+        super.setTranslationY(translationY + clipResidualY)
+    }
+
     override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
         super.onSizeChanged(w, h, oldw, oldh)
         contentContainer.layout(0, 0, w, h)
@@ -234,12 +300,24 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
 
     override fun onAttachedToWindow() {
         super.onAttachedToWindow()
+        pushLifecycleVisibility()
+    }
+
+    override fun onDetachedFromWindow() {
         if (boundDriverId != 0.0) {
-            // A latched animation may only start once this view can produce a
-            // visible frame; window attach is that signal for views that
-            // registered from a detached subtree.
-            SmoothClipBindings.nativeViewBecameDisplayable(boundDriverId, this)
+            SmoothClipBindings.nativeSetViewLifecycleVisibility(
+                boundDriverId,
+                this,
+                false,
+            )
         }
+        clearTouchState()
+        super.onDetachedFromWindow()
+    }
+
+    override fun onWindowVisibilityChanged(visibility: Int) {
+        super.onWindowVisibilityChanged(visibility)
+        pushLifecycleVisibility()
     }
 
     override fun onConfigurationChanged(newConfig: Configuration) {
@@ -259,10 +337,27 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
 
     internal fun densityScale(): Double = PixelUtil.toPixelFromDIP(1f).toDouble()
 
+    internal fun isHostLifecycleVisible(): Boolean =
+        isAttachedToWindow && windowVisibility == VISIBLE
+
+    private fun pushLifecycleVisibility() {
+        if (boundDriverId == 0.0) return
+        SmoothClipBindings.nativeSetViewLifecycleVisibility(
+            boundDriverId,
+            this,
+            isHostLifecycleVisible(),
+        )
+    }
+
     private fun containsRoundedPoint(x: Float, y: Float): Boolean {
+        // The event arrives in this view's local space, which the parent has
+        // already inverse-transformed by the residual translation. Adding it
+        // back maps the point into the space clipLeft/clipTop are expressed in,
+        // so hit testing stays against the geometry the driver delivered — the
+        // same test as before the residual existed.
         return containsRoundedPointPx(
-            x,
-            y,
+            x + clipResidualX,
+            y + clipResidualY,
             clipLeft,
             clipTop,
             clipRight,
@@ -275,8 +370,16 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     override fun dispatchTouchEvent(event: MotionEvent): Boolean {
         when (event.actionMasked) {
             MotionEvent.ACTION_DOWN -> {
+                clearTouchState()
                 acceptingTouchStream = containsRoundedPoint(event.x, event.y)
                 if (!acceptingTouchStream) return false
+                val accepted = super.dispatchTouchEvent(event)
+                if (accepted) {
+                    retainTouchEvent(event)
+                } else {
+                    clearTouchState()
+                }
+                return accepted
             }
             MotionEvent.ACTION_CANCEL, MotionEvent.ACTION_UP -> {
                 val result = if (acceptingTouchStream) {
@@ -284,12 +387,46 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
                 } else {
                     false
                 }
-                acceptingTouchStream = false
+                clearTouchState()
                 return result
             }
         }
 
-        return acceptingTouchStream && super.dispatchTouchEvent(event)
+        if (!acceptingTouchStream) return false
+        val result = super.dispatchTouchEvent(event)
+        retainTouchEvent(event)
+        return result
+    }
+
+    private fun retainTouchEvent(event: MotionEvent) {
+        retainedTouchEvent?.recycle()
+        retainedTouchEvent = MotionEvent.obtain(event)
+    }
+
+    private fun clearTouchState() {
+        acceptingTouchStream = false
+        retainedTouchEvent?.recycle()
+        retainedTouchEvent = null
+    }
+
+    private fun cancelAcceptedTouchStream() {
+        val latest = retainedTouchEvent
+        if (!acceptingTouchStream || latest == null) {
+            clearTouchState()
+            return
+        }
+        val cancel = MotionEvent.obtain(latest)
+        cancel.action = MotionEvent.ACTION_CANCEL
+        // Terminal BEFORE dispatch: a child's synchronous cancel handler can
+        // re-enter geometry application, and a nested emptiness transition
+        // must observe an already-ended stream instead of synthesizing a
+        // second cancel for it.
+        clearTouchState()
+        try {
+            super.dispatchTouchEvent(cancel)
+        } finally {
+            cancel.recycle()
+        }
     }
 
     fun setRequestedImportantForAccessibility(value: Int) {
@@ -313,7 +450,7 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     }
 
     fun resetClipState() {
-        acceptingTouchStream = false
+        clearTouchState()
         commandIsAuthoritative = false
         requestedX = 0f
         requestedY = 0f
@@ -322,8 +459,9 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         requestedRadius = 0f
         requestedContentTranslateX = 0f
         requestedContentTranslateY = 0f
-        contentContainer.translationX = 0f
-        contentContainer.translationY = 0f
+        clipResidualX = 0f
+        clipResidualY = 0f
+        applyClipPlacement()
         outlineLeft = 0
         outlineTop = 0
         outlineRight = 0

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

@@ -167,6 +167,7 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
                 view.densityScale(),
                 view.width.toDouble(),
                 view.height.toDouble(),
+                view.isHostLifecycleVisible(),
             )
         } else if (!view.commandIsAuthoritative) {
             // Command-driven mode (driverId 0): the initial props are the only