react-native-ease 0.1.0-alpha.0

package/Ease.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Ease"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/janicduplessis/react-native-ease.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+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,411 @@
+# 🍃 react-native-ease
+
+Lightweight declarative animations powered by platform APIs. Uses Core Animation on iOS and Animator on Android — zero JS overhead.
+
+## Goals
+
+- **Fast** — Animations run entirely on native platform APIs (CAAnimation, ObjectAnimator/SpringAnimation). No JS animation loop, no worklets, no shared values.
+- **Simple** — CSS-transition-like API. Set target values, get smooth animations. One component, a few props.
+- **Lightweight** — Minimal native code, no C++ runtime, no custom animation engine. Just a thin declarative wrapper around what the OS already provides.
+- **Interruptible** — Changing values mid-animation smoothly redirects to the new target. No jumps.
+
+## Non-Goals
+
+- **Complex gesture-driven animations** — If you need pan/pinch-driven animations, animation worklets, or shared values across components, use [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated).
+- **Layout animations** — Animating width/height/layout changes is not supported.
+- **Shared element transitions** — Use Reanimated or React Navigation's shared element transitions.
+- **Old architecture** — Fabric (new architecture) only.
+
+## When to use this vs Reanimated
+
+| Use react-native-ease | Use Reanimated |
+|---|---|
+| Fade in a view | Gesture-driven animations |
+| Slide/translate on state change | Complex interpolations |
+| Scale/rotate on press | Shared values across components |
+| Simple enter animations | Layout animations |
+| You want zero config | You need animation worklets |
+
+## Installation
+
+```bash
+npm install react-native-ease
+# or
+yarn add react-native-ease
+```
+
+## Quick Start
+
+```tsx
+import { EaseView } from 'react-native-ease';
+
+function FadeCard({ visible, children }) {
+  return (
+    <EaseView
+      animate={{ opacity: visible ? 1 : 0 }}
+      transition={{ type: 'timing', duration: 300 }}
+      style={styles.card}
+    >
+      {children}
+    </EaseView>
+  );
+}
+```
+
+`EaseView` works like a regular `View` — it accepts children, styles, and all standard view props. When values in `animate` change, it smoothly transitions to the new values using native platform animations.
+
+## Guide
+
+### Timing Animations
+
+Timing animations transition from one value to another over a fixed duration with an easing curve.
+
+```tsx
+<EaseView
+  animate={{ opacity: isVisible ? 1 : 0 }}
+  transition={{ type: 'timing', duration: 300, easing: 'easeOut' }}
+/>
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `duration` | `number` | `300` | Duration in milliseconds |
+| `easing` | `EasingType` | `'easeInOut'` | Easing curve (preset name or `[x1, y1, x2, y2]` cubic bezier) |
+| `loop` | `string` | — | `'repeat'` restarts from the beginning, `'reverse'` alternates direction |
+
+Available easing curves:
+
+- `'linear'` — constant speed
+- `'easeIn'` — starts slow, accelerates
+- `'easeOut'` — starts fast, decelerates
+- `'easeInOut'` — slow start and end, fast middle
+- `[x1, y1, x2, y2]` — custom cubic bezier (same as CSS `cubic-bezier()`)
+
+### Custom Easing
+
+Pass a `[x1, y1, x2, y2]` tuple for custom cubic bezier curves. The values correspond to the two control points of the bezier curve, matching the CSS `cubic-bezier()` function.
+
+```tsx
+// Standard Material Design easing
+<EaseView
+  animate={{ opacity: isVisible ? 1 : 0 }}
+  transition={{ type: 'timing', duration: 300, easing: [0.4, 0, 0.2, 1] }}
+/>
+
+// Overshoot (y-values can exceed 0–1)
+<EaseView
+  animate={{ scale: active ? 1.2 : 1 }}
+  transition={{ type: 'timing', duration: 500, easing: [0.68, -0.55, 0.265, 1.55] }}
+/>
+```
+
+x-values (x1, x2) must be between 0 and 1. y-values can exceed this range to create overshoot effects.
+
+### Spring Animations
+
+Spring animations use a physics-based model for natural-feeling motion. Great for interactive elements.
+
+```tsx
+<EaseView
+  animate={{ translateX: isOpen ? 200 : 0 }}
+  transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
+/>
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `damping` | `number` | `15` | Friction — higher values reduce oscillation |
+| `stiffness` | `number` | `120` | Spring constant — higher values mean faster animation |
+| `mass` | `number` | `1` | Mass of the object — higher values mean slower, more momentum |
+
+Spring presets for common feels:
+
+```tsx
+// Snappy (no bounce)
+{ type: 'spring', damping: 20, stiffness: 300, mass: 1 }
+
+// Gentle bounce
+{ type: 'spring', damping: 12, stiffness: 120, mass: 1 }
+
+// Bouncy
+{ type: 'spring', damping: 8, stiffness: 200, mass: 1 }
+
+// Slow and heavy
+{ type: 'spring', damping: 20, stiffness: 60, mass: 2 }
+```
+
+### Disabling Animations
+
+Use `{ type: 'none' }` to apply values immediately without animation. Useful for skipping animations in reduced-motion modes or when you need an instant state change.
+
+```tsx
+<EaseView
+  animate={{ opacity: isVisible ? 1 : 0 }}
+  transition={{ type: 'none' }}
+/>
+```
+
+`onTransitionEnd` fires immediately with `{ finished: true }`.
+
+### Border Radius
+
+`borderRadius` can be animated just like other properties. It uses hardware-accelerated platform APIs — `ViewOutlineProvider` + `clipToOutline` on Android and `layer.cornerRadius` + `layer.masksToBounds` on iOS. Unlike RN's style-based `borderRadius` (which uses a Canvas drawable on Android), this clips children properly and is GPU-accelerated.
+
+```tsx
+<EaseView
+  animate={{ borderRadius: expanded ? 0 : 16 }}
+  transition={{ type: 'timing', duration: 300 }}
+  style={styles.card}
+>
+  <Image source={heroImage} style={styles.image} />
+  <Text>Content is clipped to rounded corners</Text>
+</EaseView>
+```
+
+When `borderRadius` is in `animate`, any `borderRadius` in `style` is automatically stripped to avoid conflicts.
+
+### Animatable Properties
+
+All properties are set in the `animate` prop as flat values (no transform array).
+
+```tsx
+<EaseView
+  animate={{
+    opacity: 1,       // 0 to 1
+    translateX: 0,    // pixels
+    translateY: 0,    // pixels
+    scale: 1,         // 1 = normal size (shorthand for scaleX + scaleY)
+    scaleX: 1,        // horizontal scale
+    scaleY: 1,        // vertical scale
+    rotate: 0,        // Z-axis rotation in degrees
+    rotateX: 0,       // X-axis rotation in degrees (3D)
+    rotateY: 0,       // Y-axis rotation in degrees (3D)
+    borderRadius: 0,  // pixels (hardware-accelerated, clips children)
+  }}
+/>
+```
+
+`scale` is a shorthand that sets both `scaleX` and `scaleY`. When `scaleX` or `scaleY` is also specified, it overrides the `scale` value for that axis.
+
+You can animate any combination of properties simultaneously. All properties share the same transition config.
+
+### Looping Animations
+
+Timing animations can loop infinitely. Use `'repeat'` to restart from the beginning or `'reverse'` to alternate direction.
+
+```tsx
+// Pulsing opacity
+<EaseView
+  initialAnimate={{ opacity: 0.3 }}
+  animate={{ opacity: 1 }}
+  transition={{ type: 'timing', duration: 1000, easing: 'easeInOut', loop: 'reverse' }}
+/>
+
+// Marquee-style scroll
+<EaseView
+  initialAnimate={{ translateX: 0 }}
+  animate={{ translateX: -300 }}
+  transition={{ type: 'timing', duration: 3000, easing: 'linear', loop: 'repeat' }}
+/>
+```
+
+Loop requires `initialAnimate` to define the starting value. Spring animations do not support looping.
+
+### Enter Animations
+
+Use `initialAnimate` to set starting values. On mount, the view starts at `initialAnimate` values and animates to `animate` values.
+
+```tsx
+// Fade in and slide up on mount
+<EaseView
+  initialAnimate={{ opacity: 0, translateY: 20 }}
+  animate={{ opacity: 1, translateY: 0 }}
+  transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
+/>
+```
+
+Without `initialAnimate`, the view renders at the `animate` values immediately with no animation on mount.
+
+### Interruption
+
+Animations are interruptible by default. If you change `animate` values while an animation is running, it smoothly redirects to the new target from wherever it currently is — no jumping or restarting.
+
+```tsx
+// Rapidly toggling this is fine — each toggle smoothly
+// redirects the animation from its current position
+<EaseView
+  animate={{ translateX: isLeft ? 0 : 200 }}
+  transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
+/>
+```
+
+### Transform Origin
+
+By default, scale and rotation animate from the view's center. Use `transformOrigin` to change the pivot point with 0–1 fractions.
+
+```tsx
+// Rotate from top-left corner
+<EaseView
+  animate={{ rotate: isOpen ? 45 : 0 }}
+  transformOrigin={{ x: 0, y: 0 }}
+  transition={{ type: 'spring', damping: 12, stiffness: 200, mass: 1 }}
+  style={styles.card}
+/>
+
+// Scale from bottom-right
+<EaseView
+  animate={{ scale: active ? 1.2 : 1 }}
+  transformOrigin={{ x: 1, y: 1 }}
+  transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
+  style={styles.card}
+/>
+```
+
+| Value | Position |
+|---|---|
+| `{ x: 0, y: 0 }` | Top-left |
+| `{ x: 0.5, y: 0.5 }` | Center (default) |
+| `{ x: 1, y: 1 }` | Bottom-right |
+
+### Style Handling
+
+`EaseView` accepts all standard `ViewStyle` properties. If a property appears in both `style` and `animate`, the animated value takes priority and the style value is stripped. A dev warning is logged when this happens.
+
+```tsx
+// opacity in style works because only translateY is animated
+<EaseView
+  animate={{ translateY: moved ? -10 : 0 }}
+  transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
+  style={{
+    opacity: 0.9,
+    backgroundColor: 'white',
+    borderRadius: 16,
+    padding: 16,
+  }}
+>
+  <Text>Notification card</Text>
+</EaseView>
+
+// ⚠️ opacity is in both — animate wins, style opacity is stripped, dev warning logged
+<EaseView
+  animate={{ opacity: 1 }}
+  style={{ opacity: 0.5, backgroundColor: 'white' }}
+/>
+```
+
+## API Reference
+
+### `<EaseView>`
+
+A `View` that animates property changes using native platform APIs.
+
+| Prop | Type | Description |
+|---|---|---|
+| `animate` | `AnimateProps` | Target values for animated properties |
+| `initialAnimate` | `AnimateProps` | Starting values for enter animations (animates to `animate` on mount) |
+| `transition` | `Transition` | Animation configuration (timing, spring, or none) |
+| `onTransitionEnd` | `(event) => void` | Called when all animations complete with `{ finished: boolean }` |
+| `transformOrigin` | `{ x?: number; y?: number }` | Pivot point for scale/rotation as 0–1 fractions. Default: `{ x: 0.5, y: 0.5 }` (center) |
+| `useHardwareLayer` | `boolean` | Android only — rasterize to GPU texture during animations. See [Hardware Layers](#hardware-layers-android). Default: `false` |
+| `style` | `ViewStyle` | Non-animated styles (layout, colors, borders, etc.) |
+| `children` | `ReactNode` | Child elements |
+| ...rest | `ViewProps` | All other standard View props |
+
+### `AnimateProps`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `opacity` | `number` | `1` | View opacity (0–1) |
+| `translateX` | `number` | `0` | Horizontal translation in pixels |
+| `translateY` | `number` | `0` | Vertical translation in pixels |
+| `scale` | `number` | `1` | Uniform scale factor (shorthand for `scaleX` + `scaleY`) |
+| `scaleX` | `number` | `1` | Horizontal scale factor (overrides `scale` for X axis) |
+| `scaleY` | `number` | `1` | Vertical scale factor (overrides `scale` for Y axis) |
+| `rotate` | `number` | `0` | Z-axis rotation in degrees |
+| `rotateX` | `number` | `0` | X-axis rotation in degrees (3D) |
+| `rotateY` | `number` | `0` | Y-axis rotation in degrees (3D) |
+| `borderRadius` | `number` | `0` | Border radius in pixels (hardware-accelerated, clips children) |
+
+Properties not specified in `animate` default to their identity values.
+
+### `TimingTransition`
+
+```tsx
+{
+  type: 'timing';
+  duration?: number;  // default: 300 (ms)
+  easing?: EasingType;  // default: 'easeInOut' — preset name or [x1, y1, x2, y2]
+  loop?: 'repeat' | 'reverse';  // default: none
+}
+```
+
+### `SpringTransition`
+
+```tsx
+{
+  type: 'spring';
+  damping?: number;    // default: 15
+  stiffness?: number;  // default: 120
+  mass?: number;       // default: 1
+}
+```
+
+### `NoneTransition`
+
+```tsx
+{
+  type: 'none';
+}
+```
+
+Applies values instantly with no animation. `onTransitionEnd` fires immediately with `{ finished: true }`.
+
+## Hardware Layers (Android)
+
+Setting `useHardwareLayer` rasterizes the view into a GPU texture for the duration of the animation. This means animated property changes (opacity, scale, rotation) are composited on the RenderThread without redrawing the view hierarchy — useful for complex views with many children.
+
+```tsx
+<EaseView
+  animate={{ opacity: isVisible ? 1 : 0 }}
+  useHardwareLayer
+/>
+```
+
+**Trade-offs:**
+
+- Faster rendering for opacity, scale, and rotation animations (RenderThread compositing).
+- Uses additional GPU memory for the off-screen texture (proportional to view size).
+- Children that overflow the view's layout bounds are **clipped** by the texture. This causes visual artifacts when animating `translateX`/`translateY` on views with overflowing content.
+
+No-op on iOS where Core Animation already composites off the main thread.
+
+## How It Works
+
+`EaseView` is a native Fabric component. The JS side flattens your `animate` and `transition` props into flat native props. When those props change, the native view:
+
+1. **Diffs** previous vs new values to find what changed
+2. **Reads** the current in-flight value (for smooth interruption)
+3. **Creates** a platform-native animation from the current value to the new target
+4. **Sets** the final value immediately on the model layer
+
+On iOS, this uses `CABasicAnimation`/`CASpringAnimation` on `CALayer` key paths. On Android, this uses `ObjectAnimator`/`SpringAnimation` on `View` properties. No JS thread involvement during the animation.
+
+## Requirements
+
+- React Native 0.76+ (new architecture / Fabric)
+- iOS 15.1+
+- Android minSdk 24+
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/build.gradle

@@ -0,0 +1,68 @@
+buildscript {
+  ext.Ease = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return Ease[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    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.ease"
+
+  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"
+  implementation "androidx.dynamicanimation:dynamicanimation:1.0.0"
+}

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/ease/EasePackage.kt

@@ -0,0 +1,17 @@
+package com.ease
+
+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 EaseViewPackage : BaseReactPackage() {
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return listOf(EaseViewManager())
+  }
+
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider { emptyMap() }
+}