feat: onDragMove prop (#324)

This pull request introduces the `onDragMove` callback to the sortable
components, allowing for more granular control and feedback during drag
operations. The key changes include adding the `onDragMove` callback to
various components, updating type definitions, and documenting the new
callback.

### Callback Integration:

*
[`example/app/src/examples/SortableFlex/features/CallbacksExample.tsx`](diffhunk://#diff-909e9ac37b95e3b1e1de1bbac752161e284101aa59ff16a835ec2ff60370c24dR14):
Added `onDragMove` callback and integrated it into the
`CallbacksExample` component.
[[1]](diffhunk://#diff-909e9ac37b95e3b1e1de1bbac752161e284101aa59ff16a835ec2ff60370c24dR14)
[[2]](diffhunk://#diff-909e9ac37b95e3b1e1de1bbac752161e284101aa59ff16a835ec2ff60370c24dR42-R48)
[[3]](diffhunk://#diff-909e9ac37b95e3b1e1de1bbac752161e284101aa59ff16a835ec2ff60370c24dR62)
*
[`example/app/src/examples/SortableGrid/features/CallbacksExample.tsx`](diffhunk://#diff-e33ed4a677abd501d9340a3814a5001ab07d7b208f855caa1cd3760af9a4fc88R13):
Added `onDragMove` callback and integrated it into the
`CallbacksExample` component.
[[1]](diffhunk://#diff-e33ed4a677abd501d9340a3814a5001ab07d7b208f855caa1cd3760af9a4fc88R13)
[[2]](diffhunk://#diff-e33ed4a677abd501d9340a3814a5001ab07d7b208f855caa1cd3760af9a4fc88R42-R48)
[[3]](diffhunk://#diff-e33ed4a677abd501d9340a3814a5001ab07d7b208f855caa1cd3760af9a4fc88R70)

### Type Definitions:

*
[`packages/react-native-sortables/src/types/props/shared.ts`](diffhunk://#diff-544f2eb90180c2dd21d666753ae5105128f3b522247fc9868e93bf516c72f1b8R8):
Added `DragMoveCallback` and `DragMoveParams` type definitions, and
updated `SortableCallbacks` to include the new `onDragMove` callback.
[[1]](diffhunk://#diff-544f2eb90180c2dd21d666753ae5105128f3b522247fc9868e93bf516c72f1b8R8)
[[2]](diffhunk://#diff-544f2eb90180c2dd21d666753ae5105128f3b522247fc9868e93bf516c72f1b8R136-R145)
[[3]](diffhunk://#diff-544f2eb90180c2dd21d666753ae5105128f3b522247fc9868e93bf516c72f1b8R180-R185)
[[4]](diffhunk://#diff-544f2eb90180c2dd21d666753ae5105128f3b522247fc9868e93bf516c72f1b8R204-R208)

### Component Updates:

*
[`packages/react-native-sortables/src/constants/props.ts`](diffhunk://#diff-09a936c481316c018f0c31756ee59f904d5906ac2013ed97131ca1926b7699ccR64):
Added `onDragMove` to the default shared props.
*
[`packages/react-native-sortables/src/providers/SharedProvider.tsx`](diffhunk://#diff-b91ba790038255caebcc4ae026433dab840df2ed341d09bb3f58b75eff1416faR60):
Integrated `onDragMove` into the `SharedProvider` component.
[[1]](diffhunk://#diff-b91ba790038255caebcc4ae026433dab840df2ed341d09bb3f58b75eff1416faR60)
[[2]](diffhunk://#diff-b91ba790038255caebcc4ae026433dab840df2ed341d09bb3f58b75eff1416faR104)
*
[`packages/react-native-sortables/src/providers/shared/DragProvider.ts`](diffhunk://#diff-c764e053814b2d438bc15e419a151ba1aac64acbac7bcdeb8646047a6f8b845fL48-R48):
Integrated `onDragMove` into the `DragProvider` component and ensured it
is called during drag operations.
[[1]](diffhunk://#diff-c764e053814b2d438bc15e419a151ba1aac64acbac7bcdeb8646047a6f8b845fL48-R48)
[[2]](diffhunk://#diff-c764e053814b2d438bc15e419a151ba1aac64acbac7bcdeb8646047a6f8b845fR105)
[[3]](diffhunk://#diff-c764e053814b2d438bc15e419a151ba1aac64acbac7bcdeb8646047a6f8b845fR389-R396)##
Description

Author: lorenzogonnelli

example/app/src/examples/SortableFlex/features/CallbacksExample.tsx

@@ -2,6 +2,7 @@ import { useCallback } from 'react';
 import { useSharedValue } from 'react-native-reanimated';
 import Sortable, {
   type DragEndCallback,
+  type DragMoveCallback,
   type DragStartCallback,
   type OrderChangeCallback
 } from 'react-native-sortables';
@@ -38,6 +39,13 @@ export default function CallbacksExample() {
     [text]
   );
 
+  const onDragMove = useCallback<DragMoveCallback>(
+    params => {
+      text.value = `onDragMove:${formatCallbackParams(params)}`;
+    },
+    [text]
+  );
+
   return (
     <Screen includeNavBarHeight>
       <Stagger wrapperStye={index => (index === 0 ? flex.fill : {})}>
@@ -51,6 +59,7 @@ export default function CallbacksExample() {
             columnGap={spacing.sm}
             rowGap={spacing.xs}
             onDragEnd={onDragEnd}
+            onDragMove={onDragMove}
             onDragStart={onDragStart}
             onOrderChange={onOrderChange}>
             {DATA.map(item => (

example/app/src/examples/SortableGrid/features/CallbacksExample.tsx

@@ -2,6 +2,7 @@ import { useCallback } from 'react';
 import { useSharedValue } from 'react-native-reanimated';
 import Sortable, {
   type DragEndCallback,
+  type DragMoveCallback,
   type DragStartCallback,
   type OrderChangeCallback,
   type SortableGridRenderItem
@@ -38,6 +39,13 @@ export default function CallbacksExample() {
     [text]
   );
 
+  const onDragMove = useCallback<DragMoveCallback>(
+    params => {
+      text.value = `onDragMove:${formatCallbackParams(params)}`;
+    },
+    [text]
+  );
+
   const renderItem = useCallback<SortableGridRenderItem<(typeof DATA)[number]>>(
     ({ item }) => <GridCard>{item}</GridCard>,
     []
@@ -59,6 +67,7 @@ export default function CallbacksExample() {
             renderItem={renderItem}
             rowGap={spacing.xs}
             onDragEnd={onDragEnd}
+            onDragMove={onDragMove}
             onDragStart={onDragStart}
             onOrderChange={onOrderChange}
           />

packages/react-native-sortables/src/constants/props.ts

@@ -60,6 +60,7 @@ export const DEFAULT_SHARED_PROPS = {
   itemExiting: IS_WEB ? null : SortableItemExiting,
   itemsLayout: IS_WEB ? null : LinearTransition,
   itemsLayoutTransitionMode: 'all',
+  onDragMove: undefined,
   onDragStart: undefined,
   onOrderChange: undefined,
   overDrag: 'both',

packages/react-native-sortables/src/index.ts

@@ -14,8 +14,8 @@ export type { SortableHandleProps, SortableLayerProps } from './components';
 export * from './constants/layoutAnimations';
 export type {
   DragEndCallback,
+  DragMoveCallback,
   DragStartCallback,
-  DragStartParams,
   DropIndicatorComponentProps,
   OrderChangeCallback,
   OrderChangeParams,

packages/react-native-sortables/src/providers/SharedProvider.tsx

@@ -57,6 +57,7 @@ export default function SharedProvider({
   hapticsEnabled,
   itemKeys,
   onDragEnd,
+  onDragMove,
   onDragStart,
   onOrderChange,
   overDrag,
@@ -100,6 +101,7 @@ export default function SharedProvider({
       hapticsEnabled={hapticsEnabled}
       overDrag={overDrag}
       onDragEnd={onDragEnd}
+      onDragMove={onDragMove}
       onDragStart={onDragStart}
       onOrderChange={onOrderChange}
     />

packages/react-native-sortables/src/providers/shared/DragProvider.ts

@@ -45,7 +45,14 @@ type DragProviderProps = PropsWithChildren<
 const { DragProvider, useDragContext } = createProvider('Drag')<
   DragProviderProps,
   DragContextType
->(({ hapticsEnabled, onDragEnd, onDragStart, onOrderChange, overDrag }) => {
+>(({
+  hapticsEnabled,
+  onDragEnd,
+  onDragMove,
+  onDragStart,
+  onOrderChange,
+  overDrag
+}) => {
   const {
     activationAnimationDuration,
     activationState,
@@ -102,6 +109,7 @@ const { DragProvider, useDragContext } = createProvider('Drag')<
   // function is not memoized
   const stableOnDragStart = useJSStableCallback(onDragStart);
   const stableOnDragEnd = useJSStableCallback(onDragEnd);
+  const stableOnDragMove = useJSStableCallback(onDragMove);
   const stableOnOrderChange = useJSStableCallback(onOrderChange);
 
   // ACTIVE ITEM POSITION UPDATER
@@ -385,6 +393,14 @@ const { DragProvider, useDragContext } = createProvider('Drag')<
         return;
       }
 
+      if (activeItemKey.value) {
+        stableOnDragMove({
+          fromIndex: dragStartIndex.value,
+          key: activeItemKey.value,
+          touchData: touch
+        });
+      }
+
       if (activationState.value === DragActivationState.TOUCHED) {
         if (!touchStartTouch.value) {
           fail();
@@ -412,7 +428,9 @@ const { DragProvider, useDragContext } = createProvider('Drag')<
       activeItemKey,
       currentTouch,
       dragActivationFailOffset,
-      touchStartTouch
+      touchStartTouch,
+      dragStartIndex,
+      stableOnDragMove
     ]
   );
 

packages/react-native-sortables/src/types/props/shared.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from 'react';
 import type { ViewStyle } from 'react-native';
+import type { TouchData } from 'react-native-gesture-handler';
 import type { AnimatedRef, SharedValue } from 'react-native-reanimated';
 
 import type { Vector } from '../layout/shared';
@@ -132,6 +133,16 @@ export type DragStartParams = {
   fromIndex: number;
 };
 
+/** Parameters provided when an item is being dragged. */
+export type DragMoveParams = {
+  /** Unique identifier of the dragged item */
+  key: string;
+  /** Original index of the dragged item */
+  fromIndex: number;
+  /** Touch data */
+  touchData: TouchData;
+};
+
 /** Parameters provided when drag gesture completes and item is dropped */
 export type DragEndParams = {
   /** Unique identifier of the dragged item */
@@ -166,6 +177,12 @@ export type OrderChangeParams = {
  */
 export type DragStartCallback = (params: DragStartParams) => void;
 
+/**
+ * Callback function called when the item is being dragged
+ * @param params - Parameters for the drag move event
+ */
+export type DragMoveCallback = (params: DragMoveParams) => void;
+
 /**
  * Callback function called when the item drag ends
  * @param params - Parameters for the drag end event
@@ -184,6 +201,11 @@ export type SortableCallbacks = {
    */
   onDragStart?: DragStartCallback;
 
+  /** Called multiple times during dragging when an item is being dragged.
+   * @param params Parameters for the drag move event
+   */
+  onDragMove?: DragMoveCallback;
+
   /** Called once when the drag gesture ends.
    * You can use this callback to update items order in state.
    * @param params Parameters for the drag end event