react-native-reanimated-dnd 1.0.5 → 2.0.0

package/README.md

@@ -1,7 +1,9 @@
 # React Native Reanimated DnD 🎯
 
 <p align="center">
-  <img src="https://github.com/user-attachments/assets/dba6226e-c407-4a12-9feb-e8f588d6c1e3" alt="React Native Reanimated DnD Demo" style="max-width: 100%; width: 100%;" />
+
+https://github.com/user-attachments/assets/023c0a9c-194a-45a9-bb88-ac8f16f5ffd5
+
 </p>
 <div align="center">
   
@@ -12,15 +14,18 @@ _Powerful, performant, and built for the modern React Native developer_
 [![npm version](https://badge.fury.io/js/react-native-reanimated-dnd.svg)](https://badge.fury.io/js/react-native-reanimated-dnd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![React Native](https://img.shields.io/badge/React%20Native-0.60+-green.svg)](https://reactnative.dev/)
+[![React Native](https://img.shields.io/badge/React%20Native-0.80+-green.svg)](https://reactnative.dev/)
 
 <br />
 
-<a href="https://react-native-reanimated-dnd.netlify.app/" target="_blank">
-  <img src="https://img.shields.io/badge/📖%20Read%20the%20Docs-4f46e5?style=for-the-badge&logo=gitbook&logoColor=white&labelColor=1e293b&color=6366f1" alt="Documentation" />
+<a href="https://www.npmjs.com/package/react-native-reanimated-dnd" target="_blank">
+  <img src="https://img.shields.io/badge/📦%20View%20on%20NPM-cb3837?style=for-the-badge&logo=npm&logoColor=white&labelColor=1e293b&fontSize=24" alt="NPM Package" height="36"/>
+</a>
+<a href="https://reanimated-dnd-docs.vercel.app/" target="_blank">
+  <img src="https://img.shields.io/badge/📖%20Read%20the%20Docs-4f46e5?style=for-the-badge&logo=gitbook&logoColor=white&labelColor=1e293b&color=6366f1&fontSize=24" alt="Documentation"  height="36"/>
 </a>
 <a href="#-interactive-examples" target="_blank">
-  <img src="https://img.shields.io/badge/📱%20Try%20Live%20Demo-ff3b30?style=for-the-badge&logo=expo&logoColor=white&labelColor=1e293b" alt="Live Demo" />
+  <img src="https://img.shields.io/badge/📱%20Try%20Live%20Demo-fcba03?style=for-the-badge&logo=expo&logoColor=white&labelColor=1e293b&fontSize=24" alt="Live Demo" height="36"/>
 </a>
 
 </div>
@@ -35,15 +40,20 @@ After countless attempts with drag-and-drop solutions that don't work or are sim
 
 ## ✨ Features
 
-- 🚀 **High Performance** - Built with Reanimated 3 for buttery-smooth 60fps animations
+- 🚀 **High Performance** - Built with Reanimated 4 and Worklets for buttery-smooth 60fps animations
+- 🏗️ **New Architecture Ready** - Built for the modern React Native architecture used by Expo SDK 55+
+- 📦 **Expo Compatible** - Tested against Expo SDK 55 and React Native 0.83
+- 🪶 **Tiny Bundle Size** - Only 70kb unpacked size, won't bloat your app
 - 🎯 **Flexible API** - From simple drag-and-drop to complex sortable lists
 - 📱 **React Native First** - Designed specifically for mobile, not ported from web
 - 🔧 **TypeScript Ready** - Full type safety with comprehensive definitions
 - 🎨 **Infinitely Customizable** - Every animation, behavior, and style is configurable
 - 📦 **Complete Component Suite** - Draggable, Droppable, Sortable, and more
 - 🎪 **Smart Collision Detection** - Multiple algorithms (center, intersect, contain)
-- 📜 **Sortable Lists** - Drag and drop to sort a Vertical List, also
-  supports Automatic scrolling for out of screen dragging
+- 📜 **Vertical & Horizontal Sortable Lists** - Drag and drop to sort lists in any direction with automatic scrolling
+- 🔲 **Sortable Grids** - 2D grid drag-and-drop with flexible layouts, insert and swap modes
+- ↕ **Dynamic Heights** - Sortable lists with variable item heights
+- ⚡ **FlatList Performance** - Optional FlatList rendering for large datasets with virtualization
 - 🎭 **Drag Handles** - Precise control with dedicated drag areas
 - 🎬 **Custom Animations** - Spring, timing, or bring your own animation functions
 - 📐 **Pixel-Perfect Positioning** - 9-point alignment system with custom offsets
@@ -53,7 +63,7 @@ After countless attempts with drag-and-drop solutions that don't work or are sim
 
 ## 📱 Interactive Examples
 
-**See it in action!** A comprehensive example app with **15 interactive demos** showcasing every feature and use case.
+**See it in action!** A comprehensive example app with **18 interactive demos** showcasing every feature and use case.
 
 <div align="center">
 
@@ -65,19 +75,18 @@ After countless attempts with drag-and-drop solutions that don't work or are sim
 
 **📱 Scan & Play**
 
-<img src="https://github.com/user-attachments/assets/80f923f6-7c5f-42e9-9817-7770ee27a70b" alt="Expo QR Code" width="200" height="200" />
+<img src="https://raw.githubusercontent.com/entropyconquers/react-native-reanimated-dnd/main/documentation/images/expo-qr-code.png" alt="Expo QR Code" width="200" height="200" />
 
-*Scan with your camera or Expo Go app*
+_Scan with Expo Go to try the demo instantly_
 
 </td>
 <td align="center" width="50%">
 
 **🚀 Quick Start**
 
-1. Install [Expo Go](https://expo.dev/client) on your phone
+1. Install [Expo Go](https://expo.dev/go) on your phone (SDK 55)
 2. Scan the QR code with your camera
-3. Open the link in Expo Go
-4. Explore 15 interactive examples!
+3. Explore 18 interactive examples!
 
 **Or browse the code:**
 [**📂 View Example App →**](./example-app/README.md)
@@ -88,93 +97,173 @@ After countless attempts with drag-and-drop solutions that don't work or are sim
 
 ### 📚 Complete Documentation
 
-<a href="https://react-native-reanimated-dnd.netlify.app/" target="_blank">
+<a href="https://reanimated-dnd-docs.vercel.app/" target="_blank">
   <img src="https://img.shields.io/badge/📖%20Documentation-Visit%20Docs-4f46e5?style=for-the-badge&logo=gitbook&logoColor=white&labelColor=1e293b" alt="Documentation" />
 </a>
 
-*Comprehensive guides, API reference, and interactive examples*
+_Comprehensive guides, API reference, and interactive examples_
 
 </div>
 
 The example app includes:
 
-- 🎵 **Sortable Music Queue** - Complete list reordering with handles
-- 🎯 **Collision Detection** - Different algorithms in action
-- 🎬 **Custom Animations** - Spring, timing, and easing variations
+- 🎵 **Sortable Music Queue** - Complete list reordering with drag handles
+- ⇌ **Horizontal Sortable** - Reorderable horizontal scrolling list
+- 🔲 **Sortable Grid** - 2D grid reordering with insert/swap modes
+- ↕ **Dynamic Heights** - Sortable list with variable item heights
+- 🎯 **Basic Drag & Drop** - Drag items to drop zones with pre-drag delay
+- 🎪 **Drag Handles** - Dedicated drag regions for precise control
+- 🎬 **Custom Animations** - Spring, timing, bounce & easing curves
+- ✨ **Active Drop Styles** - Visual feedback on hover
+- 📐 **Alignment & Offset** - Precise drop positioning with offsets
 - 📦 **Boundary Constraints** - Axis-locked and bounded dragging
-- ✨ **Visual Feedback** - Active styles and state management
-- ⚙️ **Advanced Patterns** - Custom implementations and hooks
+- 🎯 **Collision Detection** - Center, intersect & contain algorithms
+- 🗺️ **Dropped Items Map** - Track items across multiple zones
+- ⚡ **Drag State** - State enum & onStateChange lifecycle
+- ⚙️ **Custom Draggable** - useDraggable hook implementation
 
-## 🎬 Video Showcase
-
-**See the library in action** with these demos showcasing some of the key features and use cases.
+## 🎬 Demo Showcase
 
 <div align="center">
 
 <table>
 <tr>
-<td align="center" width="50%">
+<td align="center" width="33%">
+
+### 🎵 Sortable Music Queue
 
-### 📋 Sortable Lists
-*Drag and drop to reorder items with smooth animations*
+_Vertical list reordering with drag handles_
 
-https://github.com/user-attachments/assets/1cd1929c-724b-4dda-a916-f3e69f917f7b
+https://github.com/user-attachments/assets/6493c05f-571c-416d-b81d-90bee98738b4
 
 **Features:** Auto-scrolling • Drag handles • Smooth transitions
 
 </td>
-<td align="center" width="50%">
+<td align="center" width="33%">
 
-### 🎯 Collision Detection
-*Multiple algorithms for precise drop targeting*
+### ⇌ Horizontal Sortable
 
-https://github.com/user-attachments/assets/379040d7-8489-430b-bae4-3fcbde34264e
+_Reorderable horizontal scrolling list_
 
-**Algorithms:** Center • Intersect • Contain
+https://github.com/user-attachments/assets/909c687e-146d-4233-a6e9-4bc3e7b69a35
+
+**Features:** Horizontal scroll • Handle & full item modes
+
+</td>
+<td align="center" width="33%">
+
+### 🔲 Grid Sortable
+
+_2D grid reordering with insert & swap_
+
+https://github.com/user-attachments/assets/9647af01-098c-485f-92ba-cfc39d1bba0c
+
+**Features:** Grid layout • Insert & swap modes
 
 </td>
 </tr>
 <tr>
-<td align="center" width="50%">
+<td align="center" width="33%">
 
-### 🎪 Drag Handles
-*Precise control with dedicated drag areas*
+### ↕ Dynamic Heights
 
-https://github.com/user-attachments/assets/ec051d5b-8ba0-41b7-86ae-379de26a97dd
+_Sortable list with variable item heights_
 
-**Features:** Touch-friendly • Visual feedback • Accessibility
+https://github.com/user-attachments/assets/b53078ca-51ab-4675-9389-e8fe69492370
+
+**Features:** Variable heights • Expand/collapse • Auto-scroll
 
 </td>
-<td align="center" width="50%">
+<td align="center" width="33%">
 
-### 📦 Bounded Dragging
-*Constrain movement within specific boundaries*
+### 🎯 Basic Drag & Drop
+
+_Drag items to drop zones_
+
+https://github.com/user-attachments/assets/05859d25-6749-41b7-ae7e-cad5f864a268
 
-https://github.com/user-attachments/assets/7bd5045b-47c4-4d9b-a0c5-eb89122ec9c0
+**Features:** Drop zones • Pre-drag delay • Visual feedback
 
-**Constraints:** Axis-locked • Container bounds • Custom limits
+</td>
+<td align="center" width="33%">
+
+### 🎭 Drag Handles
+
+_Dedicated regions for drag control_
+
+https://github.com/user-attachments/assets/f8be7bea-0f24-4446-83be-06ede43fa02a
+
+**Features:** Full handle • Bar handle • Header handle
 
 </td>
 </tr>
 <tr>
-<td align="center" width="50%">
+<td align="center" width="33%">
 
 ### ✨ Active Drop Styles
-*Visual feedback during drag operations*
 
-https://github.com/user-attachments/assets/3b8a3d00-38ad-4532-bd42-173037ea61b9
+_Visual hover effects on drop zones_
 
-**Feedback:** Hover states • Drop zones • Visual cues
+https://github.com/user-attachments/assets/d4124110-6eb7-4a15-8f97-3e58b392d62e
+
+**Feedback:** Pulse effect • Glow effect • Hover states
 
 </td>
-<td align="center" width="50%">
+<td align="center" width="33%">
+
+### 📐 Alignment & Offset
 
-### 🔄 State Management
-*Complete lifecycle tracking and callbacks*
+_Precise drop positioning with offsets_
 
-https://github.com/user-attachments/assets/da5e526f-f2d2-4dc5-96b5-3fecc4faf57a
+https://github.com/user-attachments/assets/07fd39d0-a0d8-471c-86be-b73d70027163
 
-**States:** Idle • Dragging • Animating • Dropped
+**Features:** 9-point alignment • X/Y offset controls
+
+</td>
+<td align="center" width="33%">
+
+### 📦 Bounded Dragging
+
+_Constrain movement within boundaries_
+
+https://github.com/user-attachments/assets/ce43a226-ec42-49c1-b528-df6599d294e1
+
+**Constraints:** Container bounds • Axis-locked • Custom limits
+
+</td>
+</tr>
+<tr>
+<td align="center" width="33%">
+
+### 🎪 Collision Detection
+
+_Center, intersect & contain algorithms_
+
+https://github.com/user-attachments/assets/1ac1860a-acc1-469a-ae3e-644a22393b86
+
+**Algorithms:** Center • Intersect • Contain
+
+</td>
+<td align="center" width="33%">
+
+### 🗺️ Dropped Items Map
+
+_Track items across multiple zones_
+
+https://github.com/user-attachments/assets/e4effc88-7161-4c5c-af6e-c06152cfbd09
+
+**Features:** Multi-zone tracking • Real-time mapping
+
+</td>
+<td align="center" width="33%">
+
+### ⚡ Drag State
+
+_State lifecycle tracking & callbacks_
+
+https://github.com/user-attachments/assets/bceb9e7c-8f29-4630-81b0-945a7bcf29c5
+
+**States:** Idle • Dragging • Dropped
 
 </td>
 </tr>
@@ -191,88 +280,98 @@ npm install react-native-reanimated-dnd
 ### Peer Dependencies
 
 ```bash
-npm install react-native-reanimated react-native-gesture-handler
+npm install react-native-reanimated react-native-gesture-handler react-native-worklets
 ```
 
 Follow the setup guides:
 
-- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/installation)
+- [React Native Worklets](https://docs.swmansion.com/react-native-worklets/docs/getting-started/installation/)
+- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)
 - [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/installation)
 
-## 🏃‍♂️ Quick Start
+Make sure your Babel config uses `"react-native-worklets/plugin"` as the last plugin and that your app is running on the New Architecture, which is required by Reanimated 4.
 
-### Basic Draggable
+## 📋 Requirements
 
-```tsx
-import React from "react";
-import { View, Text } from "react-native";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { Draggable, DropProvider } from "react-native-reanimated-dnd";
+### Data Structure
 
-export default function App() {
-  return (
-    <GestureHandlerRootView style={{ flex: 1 }}>
-      <DropProvider>
-        <View style={{ flex: 1, padding: 20 }}>
-          <Draggable data={{ id: "1", title: "Drag me!" }}>
-            <View
-              style={{
-                padding: 20,
-                backgroundColor: "#007AFF",
-                borderRadius: 8,
-              }}
-            >
-              <Text style={{ color: "white" }}>Drag me around!</Text>
-            </View>
-          </Draggable>
-        </View>
-      </DropProvider>
-    </GestureHandlerRootView>
-  );
+All items in your data array **MUST** have an `id` property of type string:
+
+```typescript
+interface YourDataType {
+  id: string; // Required!
+  // ... your other properties
 }
 ```
 
-### Drag & Drop with Multiple Zones
+This is essential for the library to track items during reordering.
+
+**Example:**
+
+```typescript
+// ✅ Good - Each item has a unique string id
+const tasks = [
+  { id: "1", title: "Learn React Native", completed: false },
+  { id: "2", title: "Build an app", completed: false },
+  { id: "3", title: "Deploy to store", completed: true },
+];
+
+// ❌ Bad - Missing id properties
+const badTasks = [{ title: "Task 1" }, { title: "Task 2" }];
+
+// ❌ Bad - Non-string ids
+const badTasksWithNumbers = [
+  { id: 1, title: "Task 1" },
+  { id: 2, title: "Task 2" },
+];
+```
+
+The library includes runtime validation in development mode that will warn you if items are missing valid ID properties.
+
+## State Management Guidelines
+
+**IMPORTANT**: Sortable components maintain their own internal state for optimal performance and animation consistency.
+
+### Do NOT Do This
+
+- Never update external state (arrays, Redux, Zustand, etc.) directly in `onMove` callbacks
+- Never call `setItems()`, `setTasks()`, or similar functions during drag operations
+- Never manually splice or reorder external arrays in response to drag events
+
+### Correct Approach
+
+- Use `onMove` for logging, analytics, or side effects only
+- Use `onDrop` with `allPositions` parameter for read-only position tracking
+- Let sortable components handle their internal reordering automatically
+- Use external state only for the initial data and for non-reordering updates
+
+### Future Features
+
+Programmatic list operations (add, update, delete, reorder items) that work correctly with internal state management will be added in upcoming releases. This will provide safe methods to modify sortable lists externally.
+
+## 🏃‍♂️ Quick Start
+
+### Basic Drag & Drop
 
 ```tsx
-import React from "react";
-import { View, Text } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
-import {
-  Draggable,
-  Droppable,
-  DropProvider,
-} from "react-native-reanimated-dnd";
-
-export default function DragDropExample() {
-  const handleDrop = (data: any) => {
-    console.log("Item dropped:", data);
-  };
+import { Draggable, Droppable, DropProvider } from "react-native-reanimated-dnd";
 
+export default function App() {
   return (
     <GestureHandlerRootView style={{ flex: 1 }}>
       <DropProvider>
-        <View style={{ flex: 1, padding: 20 }}>
-          {/* Draggable Item */}
-          <Draggable data={{ id: "1", title: "Drag me!" }}>
-            <View style={styles.draggableItem}>
-              <Text>📦 Drag me to a zone</Text>
-            </View>
-          </Draggable>
-
-          {/* Drop Zones */}
-          <Droppable onDrop={handleDrop}>
-            <View style={styles.dropZone}>
-              <Text>🎯 Drop Zone 1</Text>
-            </View>
-          </Droppable>
-
-          <Droppable onDrop={handleDrop}>
-            <View style={styles.dropZone}>
-              <Text>🎯 Drop Zone 2</Text>
-            </View>
-          </Droppable>
-        </View>
+        <Droppable onDrop={(data) => console.log("Dropped:", data)}>
+          <View style={styles.dropZone}>
+            <Text>Drop here</Text>
+          </View>
+        </Droppable>
+
+        <Draggable data={{ id: "1", title: "Drag me!" }}>
+          <View style={styles.item}>
+            <Text>Drag me around!</Text>
+          </View>
+        </Draggable>
       </DropProvider>
     </GestureHandlerRootView>
   );
@@ -282,333 +381,203 @@ export default function DragDropExample() {
 ### Sortable List
 
 ```tsx
-import React, { useState } from "react";
-import { View, Text } from "react-native";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { Sortable, SortableItem } from "react-native-reanimated-dnd";
+import { Sortable, SortableItem, SortableRenderItemProps } from "react-native-reanimated-dnd";
+
+const tasks = [
+  { id: "1", title: "Learn React Native" },
+  { id: "2", title: "Build an app" },
+  { id: "3", title: "Deploy to store" },
+];
+
+function TaskList() {
+  const renderItem = useCallback((props: SortableRenderItemProps<typeof tasks[0]>) => {
+    const { item, id, ...rest } = props;
+    return (
+      <SortableItem key={id} id={id} data={item} {...rest}>
+        <View style={styles.task}>
+          <Text>{item.title}</Text>
+          <SortableItem.Handle>
+            <Text>⋮⋮</Text>
+          </SortableItem.Handle>
+        </View>
+      </SortableItem>
+    );
+  }, []);
 
-interface Task {
-  id: string;
-  title: string;
+  return <Sortable data={tasks} renderItem={renderItem} itemHeight={60} />;
 }
+```
 
-export default function SortableExample() {
-  const [tasks, setTasks] = useState<Task[]>([
-    { id: "1", title: "Learn React Native" },
-    { id: "2", title: "Build an app" },
-    { id: "3", title: "Deploy to store" },
-  ]);
-
-  const renderTask = ({ item, id, positions, ...props }) => (
-    <SortableItem
-      key={id}
-      id={id}
-      positions={positions}
-      {...props}
-      onMove={(itemId, from, to) => {
-        const newTasks = [...tasks];
-        const [movedTask] = newTasks.splice(from, 1);
-        newTasks.splice(to, 0, movedTask);
-        setTasks(newTasks);
-      }}
-    >
-      <View style={styles.taskItem}>
-        <Text>{item.title}</Text>
-
-        {/* Drag Handle */}
-        <SortableItem.Handle style={styles.dragHandle}>
-          <Text>⋮⋮</Text>
-        </SortableItem.Handle>
-      </View>
-    </SortableItem>
-  );
+### Sortable Grid
+
+```tsx
+import { SortableGrid, SortableGridItem } from "react-native-reanimated-dnd";
+
+const apps = [
+  { id: "1", label: "Photos" },
+  { id: "2", label: "Music" },
+  { id: "3", label: "Settings" },
+  { id: "4", label: "Mail" },
+];
+
+function AppGrid() {
+  const renderItem = useCallback((props) => {
+    const { item, id, ...rest } = props;
+    return (
+      <SortableGridItem key={id} id={id} {...rest}>
+        <View style={styles.gridItem}>
+          <Text>{item.label}</Text>
+        </View>
+      </SortableGridItem>
+    );
+  }, []);
 
   return (
-    <GestureHandlerRootView style={{ flex: 1 }}>
-      <Sortable
-        data={tasks}
-        renderItem={renderTask}
-        itemHeight={60}
-        style={{ flex: 1, padding: 16 }}
-      />
-    </GestureHandlerRootView>
+    <SortableGrid
+      data={apps}
+      renderItem={renderItem}
+      dimensions={{ columns: 4, itemWidth: 80, itemHeight: 80, rowGap: 12, columnGap: 12 }}
+    />
   );
 }
 ```
 
-## 📚 API Reference
+> **More examples:** [Quick Start Guide](https://reanimated-dnd-docs.vercel.app/docs/getting-started/quick-start) · [Sortable Lists](https://reanimated-dnd-docs.vercel.app/docs/examples/sortable-lists) · [Sortable Grids](https://reanimated-dnd-docs.vercel.app/docs/api/components/sortable-grid) · [All Examples](https://reanimated-dnd-docs.vercel.app/docs/examples/basic-drag-drop)
 
-### Components
+## 📚 Documentation
 
-#### `<Draggable>`
+Visit **[reanimated-dnd-docs.vercel.app](https://reanimated-dnd-docs.vercel.app/)** for the full documentation:
 
-Makes any component draggable with extensive customization options.
+- **[Getting Started](https://reanimated-dnd-docs.vercel.app/docs/getting-started/installation)** — Installation, setup, and quick start
+- **[Components](https://reanimated-dnd-docs.vercel.app/docs/api/components/draggable)** — Draggable, Droppable, Sortable, SortableGrid, SortableItem
+- **[Hooks](https://reanimated-dnd-docs.vercel.app/docs/api/hooks/useDraggable)** — useDraggable, useDroppable, useSortable, useGridSortable
+- **[Guides](https://reanimated-dnd-docs.vercel.app/docs/guides/animations)** — Animations, collision algorithms, performance, accessibility
+- **[Examples](https://reanimated-dnd-docs.vercel.app/docs/examples/basic-drag-drop)** — Interactive code examples for every feature
+- **[API Reference](https://reanimated-dnd-docs.vercel.app/docs/api/overview)** — Complete types, enums, and utilities
 
-```tsx
-<Draggable
-  data={any}                                    // Data associated with the item
-  onDragStart={(data) => void}                  // Called when dragging starts
-  onDragEnd={(data) => void}                    // Called when dragging ends
-  onDragging={(position) => void}               // Called during dragging
-  onStateChange={(state) => void}               // Called on state changes
-  dragDisabled={boolean}                        // Disable dragging
-  collisionAlgorithm="center|intersect|contain" // Collision detection method
-  dragAxis="x|y|both"                          // Constrain movement axis
-  dragBoundsRef={RefObject}                    // Boundary container reference
-  animationFunction={(toValue) => Animation}    // Custom animation function
-  style={StyleProp<ViewStyle>}                 // Component styling
->
-  {children}
-</Draggable>
-```
-
-#### `<Droppable>`
+## 🏃‍♂️ Running the Example App
 
-Creates drop zones with visual feedback and capacity management.
+1. Clone the repository:
 
-```tsx
-<Droppable
-  onDrop={(data) => void}                      // Called when item is dropped
-  onActiveChange={(isActive) => void}          // Called on hover state change
-  dropDisabled={boolean}                       // Disable drop functionality
-  dropAlignment="top-left|center|bottom-right|..." // Drop positioning
-  dropOffset={{ x: number, y: number }}       // Position offset
-  activeStyle={StyleProp<ViewStyle>}           // Style when active
-  capacity={number}                            // Maximum items allowed
-  droppableId={string}                         // Unique identifier
->
-  {children}
-</Droppable>
+```bash
+git clone https://github.com/entropyconquers/react-native-reanimated-dnd.git
+cd react-native-reanimated-dnd
 ```
 
-#### `<Sortable>`
-
-High-level component for sortable lists with auto-scrolling.
+2. Install dependencies (uses npm workspaces):
 
-```tsx
-<Sortable
-  data={Array<{ id: string }>} // Array of items to render
-  renderItem={(props) => ReactNode} // Render function for items
-  itemHeight={number} // Height of each item
-  itemKeyExtractor={(item) => string} // Custom key extractor
-  style={StyleProp<ViewStyle>} // List container style
-  contentContainerStyle={StyleProp<ViewStyle>} // Content container style
-/>
+```bash
+npm install
 ```
 
-#### `<SortableItem>`
+3. Run the example app:
 
-Individual item within a sortable list with gesture handling.
+```bash
+# iOS
+npm run start --workspace example-app
+# then press 'i' for iOS or 'a' for Android
 
-```tsx
-<SortableItem
-  id={string}                                 // Unique identifier
-  data={any}                                  // Item data
-  positions={SharedValue}                     // Position tracking
-  onMove={(id, from, to) => void}            // Called when item moves
-  onDragStart={(id, position) => void}       // Called when dragging starts
-  onDrop={(id, position) => void}            // Called when item is dropped
-  onDragging={(id, overItemId, y) => void}   // Called during dragging
-  style={StyleProp<ViewStyle>}               // Item styling
-  animatedStyle={StyleProp<AnimatedStyle>}   // Animated styling
->
-  {children}
-</SortableItem>
+# Or run directly:
+npx expo run:ios --cwd example-app
+npx expo run:android --cwd example-app
 ```
 
-### Hooks
-
-#### `useDraggable(options)`
-
-Core hook for implementing draggable functionality.
-
-#### `useDroppable(options)`
-
-Core hook for implementing droppable functionality.
-
-#### `useSortable(options)`
-
-Hook for individual sortable items with position management.
-
-#### `useSortableList(options)`
-
-Hook for managing entire sortable lists with auto-scrolling.
+**Note:** Reanimated 4 requires the New Architecture, so you must use a development build (`npx expo run:ios` / `npx expo run:android`), not Expo Go.
 
-### Context
+The example app includes all 18 interactive examples showcasing every feature of the library.
 
-#### `<DropProvider>`
+## 🗺️ Project Roadmap
 
-Required context provider that manages global drag-and-drop state.
+I am constantly working to improve React Native Reanimated DnD. Here's what's coming next:
 
-```tsx
-<DropProvider>{/* All draggable and droppable components */}</DropProvider>
-```
+### ✅ v2.0.0 (Current)
 
-### Types & Enums
+**Reanimated 4 + Worklets Migration**
 
-#### `DraggableState`
+- 🚀 **Reanimated 4 & Worklets** - Migrated from Reanimated 3 to Reanimated 4 with react-native-worklets
+- 🏗️ **New Architecture** - Built for React Native's New Architecture (required by Reanimated 4)
+- 📦 **Expo SDK 55** - Tested and compatible with Expo SDK 55 and React Native 0.83
+- 🔧 **Handle Registration** - Replaced tree-walking handle detection with a registration pattern
+- ⚡ **Improved Scheduling** - Uses `scheduleOnRN`/`scheduleOnUI` for better worklet-to-JS communication
+- 🎯 **Pre-drag Delay** - New `preDragDelay` prop for distinguishing taps from drags
+- 📐 **npm Workspaces** - Example app now uses workspace-based development setup
+- 🔲 **Sortable Grids** - 2D grid drag-and-drop with flexible layouts and insert/swap modes
+- ↕ **Dynamic Heights** - Sortable list support for variable item heights
 
-```tsx
-enum DraggableState {
-  IDLE = "idle",
-  DRAGGING = "dragging",
-  ANIMATING = "animating",
-}
-```
+### 🎯 Next Release
 
-#### `CollisionAlgorithm`
+**Focus: Enhanced Functionality & New Features**
 
-```tsx
-type CollisionAlgorithm = "center" | "intersect" | "contain";
-```
+- 🐛 **Bug Fixes & Issues Resolution**
 
-#### `DropAlignment`
+  - Address existing reported issues
+  - Performance optimizations
+  - Gesture handling improvements
+  - API Improvements
 
-```tsx
-type DropAlignment =
-  | "top-left"
-  | "top-center"
-  | "top-right"
-  | "center-left"
-  | "center"
-  | "center-right"
-  | "bottom-left"
-  | "bottom-center"
-  | "bottom-right";
-```
+- 🪆 **Nested Sortable Lists**
 
-## 🎨 Advanced Usage
+  - Multi-level hierarchy support
+  - Collapse/expand functionality
+  - Parent-child relationship management
+  - Tree-like data structure handling
 
-### Custom Animations
+- 📋 **Kanban Board Support**
+  - Cross-list dragging capabilities
+  - Multiple column support
+  - Inter-list item transfer
+  - Board-level state management
 
-```tsx
-import { withTiming, withSpring, Easing } from "react-native-reanimated";
-
-// Smooth timing animation
-const smoothAnimation = (toValue) => {
-  "worklet";
-  return withTiming(toValue, {
-    duration: 300,
-    easing: Easing.bezier(0.25, 0.1, 0.25, 1),
-  });
-};
-
-// Spring animation
-const springAnimation = (toValue) => {
-  "worklet";
-  return withSpring(toValue, {
-    damping: 15,
-    stiffness: 150,
-  });
-};
-
-<Draggable animationFunction={springAnimation}>{/* content */}</Draggable>;
-```
+### 💡 Community Requests
 
-### Collision Detection Strategies
+Vote on features you'd like to see by raising an issue.
 
-```tsx
-// Precise center-point collision
-<Draggable collisionAlgorithm="center">
-  {/* Requires center point to be over drop zone */}
-</Draggable>
-
-// Forgiving intersection collision (default)
-<Draggable collisionAlgorithm="intersect">
-  {/* Any overlap triggers collision */}
-</Draggable>
-
-// Strict containment collision
-<Draggable collisionAlgorithm="contain">
-  {/* Entire draggable must be within drop zone */}
-</Draggable>
-```
+**Have an idea?** [Open a feature request](https://github.com/entropyconquers/react-native-reanimated-dnd/issues/new?assignees=&labels=enhancement&template=feature_request.md) and let me know!
 
-### Drag Handles
+## 🤖 AI Integration Skill
 
-```tsx
-<SortableItem id={item.id} {...props}>
-  <View style={styles.itemContainer}>
-    <Text>{item.title}</Text>
-
-    {/* Only this handle area can initiate dragging */}
-    <SortableItem.Handle style={styles.dragHandle}>
-      <View style={styles.handleIcon}>
-        <View style={styles.dot} />
-        <View style={styles.dot} />
-        <View style={styles.dot} />
-      </View>
-    </SortableItem.Handle>
-  </View>
-</SortableItem>
-```
+Speed up development with the official [agent skill](https://agentskills.io). It teaches AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and 30+ more) the full API so they generate correct code — no hallucinated props.
 
-### Bounded Dragging
+```bash
+# Install via npx skills (auto-detects your agents)
+npx skills add entropyconquers/react-native-reanimated-dnd
 
-```tsx
-const containerRef = useRef<View>(null);
-
-<View ref={containerRef} style={styles.container}>
-  <Draggable
-    data={data}
-    dragBoundsRef={containerRef}
-    dragAxis="x" // Constrain to horizontal movement
-  >
-    {/* content */}
-  </Draggable>
-</View>;
+# Or install globally
+npx skills add entropyconquers/react-native-reanimated-dnd -g
 ```
 
-### Drop Zone Capacity
+Once installed, just describe what you want:
 
-```tsx
-<Droppable
-  capacity={3}
-  onDrop={(data) => {
-    if (currentItems.length < 3) {
-      addItem(data);
-    }
-  }}
-  activeStyle={{
-    backgroundColor: currentItems.length < 3 ? "#e8f5e8" : "#ffe8e8",
-  }}
->
-  <Text>Drop Zone ({currentItems.length}/3)</Text>
-</Droppable>
-```
+> "Add a sortable list where I can reorder items by dragging"
 
-## 🏃‍♂️ Running the Example App
+> "Create a drag and drop interface with drop zones"
 
-1. Clone the repository:
+> "Make a reorderable 3-column grid"
 
-```bash
-git clone https://github.com/entropyconquers/react-native-reanimated-dnd.git
-cd react-native-reanimated-dnd
-```
-
-2. Install dependencies:
+Your agent will generate complete, working implementations with correct imports, props, and state management.
 
-```bash
-npm install
-cd example-app
-npm install
-```
+The skill ships in both `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex, Cursor, Gemini CLI, Copilot, and others) for universal agent compatibility. See the [AI Integration Skill docs](https://reanimated-dnd-docs.vercel.app/docs/getting-started/ai-skill) for all installation options and the full agent compatibility table.
 
-3. Run the example app:
+## 🤝 Contributing
 
-```bash
-# iOS
-npx expo run:ios
+Contributions are always welcome! We believe in building this library together with the community.
 
-# Android
-npx expo run:android
-```
+**Ways to contribute:**
 
-The example app includes all 15 interactive examples showcasing every feature of the library.
+- 🐛 Report bugs and issues
+- ✨ Suggest new features
+- 🔧 Submit pull requests
+- 📚 Improve documentation
+- 🧪 Write tests
+- 💬 Help others in discussions
 
-## 🤝 Contributing
+Please see our [**Contributing Guide**](CONTRIBUTING.md) for detailed information on:
 
-Contributions are always welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+- Setting up the development environment
+- Code style guidelines
+- Pull request process
+- Testing requirements
+- Community guidelines
 
 ## 📄 License
 
@@ -621,12 +590,30 @@ MIT © [Vishesh Raheja](https://github.com/entropyconquers)
 - Inspired by the React ecosystem's drag-and-drop libraries
 - Special thanks to the React Native community for feedback and contributions
 
+## ☕ Support the Project
+
+<div align="center">
+<body>
+If this library has helped you build amazing apps, consider supporting its development!
+</br></br>
+    <a href="https://www.buymeacoffee.com/entropyconquers" target="_blank">
+        <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" style="height: 60px; width: 217px;">
+    </a>
+    </br>
+</br>
+  Your support helps maintain and improve this library for the entire React Native community! 🚀
+</body>
+</html>
+
+</div>
+<br/>
+
 ---
 
 <div align="center">
 
 **Made with ❤️ for the React Native community**
 
-[⭐ Star on GitHub](https://github.com/entropyconquers/react-native-reanimated-dnd) • [📱 Try the Demo](https://github.com/entropyconquers/react-native-reanimated-dnd/tree/main/example-app) • [📖 Documentation](https://github.com/entropyconquers/react-native-reanimated-dnd#readme)
+[⭐ Star on GitHub](https://github.com/entropyconquers/react-native-reanimated-dnd) • [📱 Try the Demo](https://github.com/entropyconquers/react-native-reanimated-dnd/tree/main/example-app) • [📖 Documentation](https://reanimated-dnd-docs.vercel.app/)
 
 </div>