react-native-ease 0.2.0 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "react-native-ease-plugins",
+  "owner": {
+    "name": "AppAndFlow",
+    "email": "devops@appandflow.com"
+  },
+  "metadata": {
+    "description": "Claude Code skills for react-native-ease — migrate Reanimated/Animated code to react-native-ease"
+  },
+  "plugins": [
+    {
+      "name": "react-native-ease",
+      "source": "./",
+      "description": "Scan for Animated/Reanimated code and migrate to react-native-ease",
+      "version": "0.2.0",
+      "author": {
+        "name": "AppAndFlow"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "react-native-ease",
+  "description": "Declarative native animations for React Native — migration tools",
+  "version": "0.2.0"
+}

package/README.md

@@ -1,32 +1,17 @@
-# 🍃 react-native-ease
+<img width="100%" height="auto" alt="react-native-ease by App & Flow" src="https://github.com/user-attachments/assets/8006ed51-d373-4c97-9e80-9937eb9a569e" />
 
 Lightweight declarative animations powered by platform APIs. Uses Core Animation on iOS and Animator on Android — zero JS overhead.
 
-## Goals
+## About
+App & Flow is a Montreal-based React Native engineering and consulting studio. We partner with the world’s top companies and are recommended by [Expo](https://expo.dev/consultants). Need a hand? Let’s build together. team@appandflow.com
 
-- **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.
+## Demo
 
-## When to use this vs Reanimated
+![ease-demo](https://github.com/user-attachments/assets/09658b07-803e-4b7e-a23c-831a6c63df84)
 
-| 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 |
+## Getting started
 
-## Installation
+### Installation
 
 ```bash
 npm install react-native-ease
@@ -34,7 +19,25 @@ npm install react-native-ease
 yarn add react-native-ease
 ```
 
-## Quick Start
+### Migration Skill
+
+If you're already using `react-native-reanimated` or React Native's `Animated` API, this project includes an [Agent Skill](https://agentskills.io) that scans your codebase for animations that can be replaced with `react-native-ease` and migrates them automatically.
+
+```bash
+npx skills add appandflow/react-native-ease
+```
+
+Then invoke the skill in your agent (e.g., `/react-native-ease-refactor` in Claude Code).
+
+The skill will:
+
+1. Scan your project for Reanimated/Animated code
+2. Classify which animations can be migrated (and which can't, with reasons)
+3. Show a migration report with before/after details
+4. Let you select which components to migrate
+5. Apply the changes, preserving all non-animation logic
+
+### Example
 
 ```tsx
 import { EaseView } from 'react-native-ease';
@@ -54,6 +57,32 @@ function FadeCard({ visible, children }) {
 
 `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.
 
+## Why
+
+### 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 case                               | Ease | Reanimated |
+| -------------------------------------- | ---- | ---------- |
+| Fade/slide/scale on state change       | ✅   |            |
+| Enter/exit animations                  | ✅   |            |
+| Gesture-driven animations (pan, pinch) |      | ✅         |
+| Layout animations (width, height)      |      | ✅         |
+| Complex interpolations & chaining      |      | ✅         |
+
 ## Guide
 
 ### Timing Animations
@@ -67,11 +96,12 @@ Timing animations transition from one value to another over a fixed duration wit
 />
 ```
 
-| 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 |
+| Parameter  | Type         | Default       | Description                                                              |
+| ---------- | ------------ | ------------- | ------------------------------------------------------------------------ |
+| `duration` | `number`     | `300`         | Duration in milliseconds                                                 |
+| `easing`   | `EasingType` | `'easeInOut'` | Easing curve (preset name or `[x1, y1, x2, y2]` cubic bezier)            |
+| `delay`    | `number`     | `0`           | Delay in milliseconds before the animation starts                        |
+| `loop`     | `string`     | —             | `'repeat'` restarts from the beginning, `'reverse'` alternates direction |
 
 Available easing curves:
 
@@ -112,11 +142,12 @@ Spring animations use a physics-based model for natural-feeling motion. Great fo
 />
 ```
 
-| 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 |
+| 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 |
+| `delay`     | `number` | `0`     | Delay in milliseconds before the animation starts             |
 
 Spring presets for common feels:
 
@@ -147,6 +178,46 @@ Use `{ type: 'none' }` to apply values immediately without animation. Useful for
 
 `onTransitionEnd` fires immediately with `{ finished: true }`.
 
+### Per-Property Transitions
+
+Pass a map instead of a single config to use different animation types per property category.
+
+```tsx
+<EaseView
+  animate={{ opacity: visible ? 1 : 0, translateY: visible ? 0 : 30 }}
+  transition={{
+    opacity: { type: 'timing', duration: 150, easing: 'easeOut' },
+    transform: { type: 'spring', damping: 12, stiffness: 200 },
+  }}
+/>
+```
+
+Available category keys:
+
+| Key               | Properties                                                       |
+| ----------------- | ---------------------------------------------------------------- |
+| `default`         | Fallback for categories not explicitly listed                    |
+| `transform`       | translateX, translateY, scaleX, scaleY, rotate, rotateX, rotateY |
+| `opacity`         | opacity                                                          |
+| `borderRadius`    | borderRadius                                                     |
+| `backgroundColor` | backgroundColor                                                  |
+
+Use `default` as a fallback for categories not explicitly listed:
+
+```tsx
+<EaseView
+  animate={{ opacity: 1, scale: 1.2, translateY: -20 }}
+  transition={{
+    default: { type: 'spring', damping: 15, stiffness: 120 },
+    opacity: { type: 'timing', duration: 200, easing: 'easeOut' },
+  }}
+/>
+```
+
+When no `default` key is provided, the library default (timing 300ms easeInOut) applies to all categories.
+
+> **Android note:** Android animates `backgroundColor` with `ValueAnimator` (timing only). If a per-property map specifies `type: 'spring'` for `backgroundColor`, it silently falls back to timing 300ms.
+
 ### 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.
@@ -180,6 +251,8 @@ When `borderRadius` is in `animate`, any `borderRadius` in `style` is automatica
 
 On Android, background color uses `ValueAnimator.ofArgb()` (timing only — spring is not supported for colors). On iOS, it uses `CAAnimation` on the `backgroundColor` layer key path and supports both timing and spring transitions.
 
+> **Note:** On Android, background color animation uses `ValueAnimator.ofArgb()` which only supports timing transitions. Spring transitions for `backgroundColor` are not supported on Android and will fall back to timing with the default duration. On iOS, both timing and spring transitions work for background color.
+
 When `backgroundColor` is in `animate`, any `backgroundColor` in `style` is automatically stripped to avoid conflicts.
 
 ### Animatable Properties
@@ -189,16 +262,16 @@ 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)
+    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)
     backgroundColor: 'transparent', // any RN color value
   }}
 />
@@ -245,6 +318,26 @@ Use `initialAnimate` to set starting values. On mount, the view starts at `initi
 
 Without `initialAnimate`, the view renders at the `animate` values immediately with no animation on mount.
 
+### Delay
+
+Use `delay` to postpone the start of an animation. This is useful for staggering enter animations across multiple elements.
+
+```tsx
+// Staggered fade-in list
+{items.map((item, i) => (
+  <EaseView
+    key={item.id}
+    initialAnimate={{ opacity: 0, translateY: 20 }}
+    animate={{ opacity: 1, translateY: 0 }}
+    transition={{ type: 'timing', duration: 300, delay: i * 100 }}
+  >
+    <Text>{item.label}</Text>
+  </EaseView>
+))}
+```
+
+`delay` works with both timing and spring transitions.
+
 ### 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.
@@ -280,11 +373,11 @@ By default, scale and rotation animate from the view's center. Use `transformOri
 />
 ```
 
-| Value | Position |
-|---|---|
-| `{ x: 0, y: 0 }` | Top-left |
+| Value                | Position         |
+| -------------------- | ---------------- |
+| `{ x: 0, y: 0 }`     | Top-left         |
 | `{ x: 0.5, y: 0.5 }` | Center (default) |
-| `{ x: 1, y: 1 }` | Bottom-right |
+| `{ x: 1, y: 1 }`     | Bottom-right     |
 
 ### Style Handling
 
@@ -318,32 +411,32 @@ By default, scale and rotation animate from the view's center. Use `transformOri
 
 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 |
+| 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) |
+| 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)                       |
 | `backgroundColor` | `ColorValue` | `'transparent'` | Background color (any RN color value). Timing-only on Android, spring+timing on iOS. |
 
 Properties not specified in `animate` default to their identity values.
@@ -355,6 +448,7 @@ Properties not specified in `animate` default to their identity values.
   type: 'timing';
   duration?: number;  // default: 300 (ms)
   easing?: EasingType;  // default: 'easeInOut' — preset name or [x1, y1, x2, y2]
+  delay?: number;  // default: 0 (ms)
   loop?: 'repeat' | 'reverse';  // default: none
 }
 ```
@@ -367,6 +461,7 @@ Properties not specified in `animate` default to their identity values.
   damping?: number;    // default: 15
   stiffness?: number;  // default: 120
   mass?: number;       // default: 1
+  delay?: number;      // default: 0 (ms)
 }
 ```
 
@@ -385,10 +480,7 @@ Applies values instantly with no animation. `onTransitionEnd` fires immediately
 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
-/>
+<EaseView animate={{ opacity: isVisible ? 1 : 0 }} useHardwareLayer />
 ```
 
 **Trade-offs:**
@@ -399,6 +491,58 @@ Setting `useHardwareLayer` rasterizes the view into a GPU texture for the durati
 
 No-op on iOS where Core Animation already composites off the main thread.
 
+## Benchmarks
+
+The example app includes a benchmark that measures per-frame animation overhead across different approaches. All approaches run the same animation (translateX loop, linear, 2s) on a configurable number of views.
+
+### Android (release build, emulator, M4 MacBook Pro)
+
+UI thread time per frame: anim + layout + draw (ms). Lower is better.
+
+![Android benchmark](https://github.com/user-attachments/assets/f0e5cf26-76be-4dd3-ae04-e17c6d13b49c)
+
+<details>
+<summary>Detailed numbers</summary>
+
+| Views | Metric | Ease | Reanimated SV | Reanimated SV (FF) | Reanimated CSS | Reanimated CSS (FF) | RN Animated |
+|-------|--------|------|---------------|---------------------|----------------|----------------------|-------------|
+| 10 | Avg | 0.21 | 1.15 | 0.75 | 0.99 | 0.45 | 0.36 |
+| 10 | P95 | 0.33 | 1.70 | 1.53 | 1.44 | 0.80 | 0.62 |
+| 10 | P99 | 0.48 | 1.94 | 2.26 | 1.62 | 1.35 | 0.98 |
+| 100 | Avg | 0.36 | 2.71 | 1.81 | 2.19 | 1.01 | 0.71 |
+| 100 | P95 | 0.56 | 3.09 | 2.29 | 2.67 | 1.91 | 1.08 |
+| 100 | P99 | 0.71 | 3.20 | 2.63 | 2.97 | 2.25 | 1.36 |
+| 500 | Avg | 0.60 | 8.31 | 5.37 | 5.50 | 2.37 | 1.60 |
+| 500 | P95 | 0.75 | 9.26 | 6.36 | 6.34 | 2.86 | 1.88 |
+| 500 | P99 | 0.87 | 9.59 | 6.89 | 6.88 | 3.22 | 3.84 |
+
+</details>
+
+### iOS (release build, simulator, iPhone 16 Pro, M4 MacBook Pro)
+
+Display link callback time per frame (ms). Lower is better.
+
+![iOS benchmark](https://github.com/user-attachments/assets/c39a7a71-bf21-4276-b02f-b29983989832)
+
+<details>
+<summary>Detailed numbers</summary>
+
+| Views | Metric | Ease | Reanimated SV | Reanimated SV (FF) | Reanimated CSS | Reanimated CSS (FF) | RN Animated |
+|-------|--------|------|---------------|---------------------|----------------|----------------------|-------------|
+| 10 | Avg | 0.01 | 1.33 | 1.08 | 1.06 | 0.63 | 0.83 |
+| 10 | P95 | 0.02 | 1.67 | 1.59 | 1.34 | 1.01 | 1.18 |
+| 10 | P99 | 0.03 | 1.90 | 1.68 | 1.50 | 1.08 | 1.31 |
+| 100 | Avg | 0.01 | 3.72 | 3.33 | 2.71 | 2.48 | 3.32 |
+| 100 | P95 | 0.01 | 5.21 | 4.50 | 3.83 | 3.39 | 4.28 |
+| 100 | P99 | 0.02 | 5.68 | 4.75 | 4.91 | 3.79 | 4.55 |
+| 500 | Avg | 0.01 | 6.84 | 6.54 | 4.16 | 3.70 | 4.91 |
+| 500 | P95 | 0.01 | 7.69 | 7.32 | 4.59 | 4.22 | 5.66 |
+| 500 | P99 | 0.02 | 8.10 | 7.45 | 4.71 | 4.33 | 5.89 |
+
+</details>
+
+Ease stays near zero because animations run entirely on platform APIs. On iOS, Core Animation runs on a separate render server process off the main thread, which is why Ease shows ~0ms. On Android, ObjectAnimator runs on the UI thread but is significantly lighter than other approaches. Reanimated results shown with experimental [feature flags](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/) OFF (default) and ON (FF). Run the benchmark yourself in the [example app](example/).
+
 ## 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: