feat: add hardware layer optimization on Android

Enable LAYER_TYPE_HARDWARE during animations so property changes are
composited on the RenderThread via a cached GPU texture. On by default,
can be disabled with useHardwareLayer={false}. Saves and restores the
original layer type. Also add TSDoc to all public types and props.

Author: janicduplessis

android/src/main/java/com/ease/EaseView.kt

@@ -1,8 +1,11 @@
 package com.ease
 
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
 import android.animation.ObjectAnimator
 import android.animation.TimeInterpolator
 import android.content.Context
+import android.view.View
 import android.view.animation.LinearInterpolator
 import android.view.animation.PathInterpolator
 import androidx.dynamicanimation.animation.DynamicAnimation
@@ -31,6 +34,11 @@ class EaseView(context: Context) : ReactViewGroup(context) {
     var transitionStiffness: Float = 120.0f
     var transitionMass: Float = 1.0f
 
+    // --- Hardware layer ---
+    var useHardwareLayer: Boolean = true
+    private var activeAnimationCount: Int = 0
+    private var savedLayerType: Int = View.LAYER_TYPE_NONE
+
     // --- Initial animate values (set by ViewManager) ---
     var initialAnimateOpacity: Float = 1.0f
     var initialAnimateTranslateX: Float = 0.0f
@@ -58,6 +66,26 @@ class EaseView(context: Context) : ReactViewGroup(context) {
         else -> PathInterpolator(0.42f, 0f, 0.58f, 1.0f)
     }
 
+    // --- Hardware layer management ---
+
+    private fun onEaseAnimationStart() {
+        if (activeAnimationCount == 0 && useHardwareLayer) {
+            savedLayerType = layerType
+            setLayerType(View.LAYER_TYPE_HARDWARE, null)
+        }
+        activeAnimationCount++
+    }
+
+    private fun onEaseAnimationEnd() {
+        activeAnimationCount--
+        if (activeAnimationCount <= 0) {
+            activeAnimationCount = 0
+            if (useHardwareLayer && layerType == View.LAYER_TYPE_HARDWARE) {
+                setLayerType(savedLayerType, null)
+            }
+        }
+    }
+
     fun applyPendingAnimateValues() {
         applyAnimateValues(pendingOpacity, pendingTranslateX, pendingTranslateY, pendingScale, pendingRotate)
     }
@@ -192,6 +220,14 @@ class EaseView(context: Context) : ReactViewGroup(context) {
         val animator = ObjectAnimator.ofFloat(this, propertyName, fromValue, toValue).apply {
             duration = transitionDuration.toLong()
             interpolator = getInterpolator(transitionEasing)
+            addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationStart(animation: Animator) {
+                    this@EaseView.onEaseAnimationStart()
+                }
+                override fun onAnimationEnd(animation: Animator) {
+                    this@EaseView.onEaseAnimationEnd()
+                }
+            })
         }
 
         runningAnimators[propertyName] = animator
@@ -215,8 +251,18 @@ class EaseView(context: Context) : ReactViewGroup(context) {
                 this.dampingRatio = dampingRatio
                 this.stiffness = transitionStiffness
             }
+            addUpdateListener { _, _, _ ->
+                // First update — enable hardware layer
+                if (activeAnimationCount == 0) {
+                    this@EaseView.onEaseAnimationStart()
+                }
+            }
+            addEndListener { _, _, _, _ ->
+                this@EaseView.onEaseAnimationEnd()
+            }
         }
 
+        onEaseAnimationStart()
         runningSpringAnimations[viewProperty] = spring
         spring.start()
     }
@@ -266,6 +312,11 @@ class EaseView(context: Context) : ReactViewGroup(context) {
         }
         runningSpringAnimations.clear()
 
+        if (activeAnimationCount > 0 && layerType == View.LAYER_TYPE_HARDWARE) {
+            setLayerType(savedLayerType, null)
+        }
+        activeAnimationCount = 0
+
         prevOpacity = null
         prevTranslateX = null
         prevTranslateY = null

android/src/main/java/com/ease/EaseViewManager.kt

@@ -100,6 +100,13 @@ class EaseViewManager : ReactViewManager() {
         view.transitionMass = value
     }
 
+    // --- Hardware layer ---
+
+    @ReactProp(name = "useHardwareLayer", defaultBoolean = true)
+    fun setUseHardwareLayer(view: EaseView, value: Boolean) {
+        view.useHardwareLayer = value
+    }
+
     // --- Lifecycle ---
 
     override fun onAfterUpdateTransaction(view: ReactViewGroup) {

src/EaseView.tsx

@@ -13,16 +13,29 @@ const IDENTITY: Required<AnimateProps> = {
 };
 
 export type EaseViewProps = Omit<ViewProps, 'style'> & {
+  /** Target values for animated properties. */
   animate?: AnimateProps;
+  /** Starting values for enter animations. Animates to `animate` on mount. */
   initialAnimate?: AnimateProps;
+  /** Animation configuration (timing or spring). */
   transition?: Transition;
+  /**
+   * Use a hardware layer during animations on Android for smoother rendering.
+   * The view is rasterized to a GPU texture while animating so property changes
+   * are composited on the RenderThread. No-op on iOS where Core Animation
+   * already runs off the main thread.
+   * @default true
+   */
+  useHardwareLayer?: boolean;
+  /** Non-animated styles (layout, colors, borders, etc.). `opacity` and `transform` are excluded — use `animate` instead. */
   style?: EaseViewStyle | EaseViewStyle[];
 };
 
 export function EaseView({
   animate,
   initialAnimate,
   transition,
+  useHardwareLayer = true,
   style,
   ...rest
 }: EaseViewProps) {
@@ -81,6 +94,7 @@ export function EaseView({
       transitionDamping={transitionDamping}
       transitionStiffness={transitionStiffness}
       transitionMass={transitionMass}
+      useHardwareLayer={useHardwareLayer}
       {...rest}
     />
   );

src/EaseViewNativeComponent.ts

@@ -30,6 +30,9 @@ export interface NativeProps extends ViewProps {
   transitionDamping?: CodegenTypes.WithDefault<CodegenTypes.Float, 15.0>;
   transitionStiffness?: CodegenTypes.WithDefault<CodegenTypes.Float, 120.0>;
   transitionMass?: CodegenTypes.WithDefault<CodegenTypes.Float, 1.0>;
+
+  // Android hardware layer optimization (no-op on iOS)
+  useHardwareLayer?: CodegenTypes.WithDefault<boolean, true>;
 }
 
 export default codegenNativeComponent<NativeProps>(

src/types.ts

@@ -1,24 +1,39 @@
+/** Easing curve for timing animations. */
 export type EasingType = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
 
+/** Timing-based transition with fixed duration and easing curve. */
 export type TimingTransition = {
   type: 'timing';
+  /** Duration in milliseconds. @default 300 */
   duration?: number;
+  /** Easing curve. @default 'easeInOut' */
   easing?: EasingType;
 };
 
+/** Physics-based spring transition. */
 export type SpringTransition = {
   type: 'spring';
+  /** Friction — higher values reduce oscillation. @default 15 */
   damping?: number;
+  /** Spring constant — higher values mean faster animation. @default 120 */
   stiffness?: number;
+  /** Mass of the object — higher values mean slower, more momentum. @default 1 */
   mass?: number;
 };
 
+/** Animation transition configuration. */
 export type Transition = TimingTransition | SpringTransition;
 
+/** Animatable view properties. Unspecified properties default to their identity values. */
 export type AnimateProps = {
+  /** View opacity (0–1). @default 1 */
   opacity?: number;
+  /** Horizontal translation in pixels. @default 0 */
   translateX?: number;
+  /** Vertical translation in pixels. @default 0 */
   translateY?: number;
+  /** Uniform scale factor. @default 1 */
   scale?: number;
+  /** Rotation in degrees. @default 0 */
   rotate?: number;
 };