@msobiecki/react-marauders-path 1.18.0 → 1.20.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
 
@@ -107,6 +108,20 @@ function MyComponent() {
 }
 ```
 
+### 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?)`
@@ -156,7 +171,7 @@ interface UseWheelOptions {
 }
 ```
 
-**Delta Data:**
+**Wheel Data:**
 
 ```typescript
 interface WheelData {
@@ -201,6 +216,45 @@ 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
+  raf?: boolean; // Default: false - Use requestAnimationFrame for batching
+}
+```
+
+**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
@@ -315,7 +369,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.18.0",
+  "version": "1.20.0",
   "type": "module",
   "engines": {
     "node": ">=22.17.1"
@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@anolilab/multi-semantic-release": "^4.1.1",
-    "@commitlint/cli": "^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",