@msobiecki/react-marauders-path 1.17.0 → 1.19.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![License](https://img.shields.io/badge/license-%20%20GNU%20GPLv3%20-green.svg)](https://github.com/msobiecki/react-marauders-path/blob/master/LICENSE)
 
-A lightweight, type-safe React library for handling keyboard, wheel, and swipe events. Perfect for games, interactive applications, and input-driven interfaces.
+A lightweight, type-safe React library for handling keyboard, wheel, swipe, and drag events. Perfect for games, interactive applications, and input-driven interfaces.
 
 ![react-marauders-path](./docs/images/logotype.png)
 
@@ -11,6 +11,7 @@ A lightweight, type-safe React library for handling keyboard, wheel, and swipe e
 - 🎮 **Keyboard Event Handling** - Simple API for detecting single keys, key combinations, and sequences
 - 🎡 **Wheel Event Handling** - Mouse wheel scrolling with delta tracking and batching support
 - 🖐️ **Swipe Gesture Handling** - Touch swipe detection with distance and velocity thresholds
+- 🖱️ **Drag Event Handling** - Pointer drag tracking with movement and delta data
 
 ## Installation
 
@@ -85,8 +86,8 @@ useKey(
 import { useWheel } from '@msobiecki/react-marauders-path';
 
 function MyComponent() {
-  useWheel((event, delta) => {
-    console.log(`Scrolled - X: ${delta.x}, Y: ${delta.y}`);
+  useWheel((event, data) => {
+    console.log(`Scrolled - X: ${data.deltaX}, Y: ${data.deltaY}`);
   });
 
   return <div>Scroll to interact</div>;
@@ -99,14 +100,28 @@ function MyComponent() {
 import { useSwipe } from '@msobiecki/react-marauders-path';
 
 function MyComponent() {
-  useSwipe('left' (event, swipe) => {
-    console.log(`Swiped ${swipe.direction} with velocity ${swipe.velocity}`);
+  useSwipe('left' (event, direction, data) => {
+    console.log(`Swiped ${direction} with velocity ${data.velocity}`);
   });
 
   return <div>Swipe left</div>;
 }
 ```
 
+### Drag Event Hook
+
+```typescript
+import { useDrag } from '@msobiecki/react-marauders-path';
+
+function MyComponent() {
+  useDrag((event, data) => {
+    console.log(`Dragged by X: ${data.deltaX}, Y: ${data.deltaY}`);
+  });
+
+  return <div>Drag to interact</div>;
+}
+```
+
 ## API
 
 ### `useKey(keyEvent, callback, options?)`
@@ -140,7 +155,7 @@ Hook for handling mouse wheel events with support for different delta modes and
 
 **Parameters:**
 
-- `callback: (event: WheelEvent, delta: WheelData) => void | boolean` - Called when wheel event occurs
+- `callback: (event: WheelEvent, data: WheelData) => void | boolean` - Called when wheel event occurs
 - `options?: UseWheelOptions` - Optional configuration
 
 **Options:**
@@ -160,9 +175,9 @@ interface UseWheelOptions {
 
 ```typescript
 interface WheelData {
-  x: number; // Delta X value
-  y: number; // Delta Y value
-  z: number; // Delta Z value
+  deltaX: number; // Delta X value
+  deltaY: number; // Delta Y value
+  deltaZ: number; // Delta Z value
   deltaMode: number; // Delta mode value
 }
 ```
@@ -174,7 +189,7 @@ Hook for handling touch swipe gestures with configurable distance and velocity t
 **Parameters:**
 
 - `swipe: left | right | up | down | horizontal | vertical | both` - Allowed directions to listen
-- `callback: (event: TouchEvent, data: SwipeData) => void | boolean` - Called when a swipe event occurs
+- `callback: (event: PointerEvent, direction: SwipeDirection, data: SwipeData) => void | boolean` - Called when a swipe event occurs
 - `options?: UseSwipeOptions` - Optional configuration
 
 **Options:**
@@ -194,7 +209,6 @@ interface UseSwipeOptions {
 
 ```typescript
 interface SwipeData {
-  direction: SwipeDirection; // Resolved direction
   deltaX: number; // Horizontal travel
   deltaY: number; // Vertical travel
   velocity: number; // Average speed (distance / duration)
@@ -202,6 +216,44 @@ interface SwipeData {
 }
 ```
 
+### `useDrag(callback, options?)`
+
+Hook for handling pointer drag gestures with configurable threshold and pointer types.
+
+**Parameters:**
+
+- `callback: (event: PointerEvent, data: DragData) => void | boolean` - Called when drag event occurs
+- `options?: UseDragOptions` - Optional configuration
+
+**Options:**
+
+```typescript
+interface UseDragOptions {
+  eventPointerTypes?: Array<"touch" | "mouse" | "pen">; // Default: ["touch", "mouse", "pen"]
+  eventCapture?: boolean; // Default: false
+  eventOnce?: boolean; // Default: false
+  eventStopImmediatePropagation?: boolean; // Default: false
+  threshold?: number; // Default: 0 (px) - Minimum drag distance
+  container?: RefObject<HTMLElement>; // Default: window
+}
+```
+
+**Drag Data:**
+
+```typescript
+interface DragData {
+  deltaX: number; // Horizontal movement from drag start
+  deltaY: number; // Vertical movement from drag start
+  movementX: number; // Horizontal movement from previous drag event
+  movementY: number; // Vertical movement from previous drag event
+  duration: number; // Drag duration in ms
+  startX: number; // Drag start X
+  startY: number; // Drag start Y
+  endX: number; // Drag end X
+  endY: number; // Drag end Y
+}
+```
+
 ## Advanced Examples
 
 ### Using Options for Event Type and Propagation Control
@@ -316,7 +368,6 @@ npm lint
 - 🚧 **`useTap`** – single tap / click
 - 🚧 **`useDoubleTap`** – quick double tap
 - 🚧 **`usePress`** – press and hold (longPress)
-- 🚧 **`useDrag`** – dragging elements (MouseEvent / PointerEvent / TouchEvent)
 - 🚧 **`usePinch`** – two-finger pinch / zoom
 
 ### Pointer / Mouse Hooks (Unified)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msobiecki/react-marauders-path",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "type": "module",
   "engines": {
     "node": ">=22.17.1"
@@ -23,13 +23,13 @@
   },
   "devDependencies": {
     "@anolilab/multi-semantic-release": "^4.1.1",
-    "@commitlint/cli": "^20.4.1",
-    "@commitlint/config-conventional": "^20.4.1",
+    "@commitlint/cli": "^20.4.2",
+    "@commitlint/config-conventional": "^20.4.2",
     "@msobiecki/eslint-config": "^9.12.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react-swc": "^4.2.3",