@marsio/vue-draggable 1.0.9 → 1.0.11

package/README.md

@@ -6,7 +6,7 @@ Draggable and DraggableCore are **Vue3** components designed to make elements dr
   <img src="https://user-images.githubusercontent.com/6365230/95649276-f3a02480-0b06-11eb-8504-e0614a780ba4.gif" />
 </p>
 
-[**[Demo](http://110.41.33.162:9001/) | [Changelog](/CHANGELOG.md) | [View Example](/example/example.js)**]
+[**[Demo](https://marsio.top/vue-draggable/) | [Changelog](/CHANGELOG.md) | [View Example](/example/example.js) | [MCP Server](./mcp/README.md)**]
 
 ## ✨ Features
 - **Compatibility**: Compatible with server-rendered apps, PC, and mobile devices.
@@ -17,7 +17,62 @@ Draggable and DraggableCore are **Vue3** components designed to make elements dr
 - **Position Offset**: Supports an offset for the draggable position (`positionOffset`), enabling adjustments to the element's position without altering its actual position properties.
 -  **Grid Snapping**: Allows the draggable element to snap to a grid (`grid` prop), facilitating alignment and precise placement during dragging.
 - **Accessibility and Interaction**: Includes props for disabling the draggable functionality (`disabled`), allowing any mouse button to initiate dragging (`allowAnyClick`), and enabling a hack to prevent text selection during drag (`enableUserSelectHack`), enhancing usability and accessibility.
+## 🤖 AI IDE Integration (MCP Server)
 
+**Supercharge your AI-powered development workflow!** Vue-Draggable now includes an official **Model Context Protocol (MCP) Server** that provides your AI assistant with comprehensive, real-time access to all component APIs, props, and examples.
+
+### ✨ What is MCP?
+
+The Model Context Protocol enables AI assistants like Claude Desktop, Cursor, and other AI IDEs to access live, accurate documentation and code examples directly from the source. No more outdated docs or hallucinated APIs!
+
+### 🚀 Key Benefits
+
+- **🎯 Accurate API Usage**: AI gets real-time access to all props, types, and default values
+- **📚 Contextual Examples**: Intelligent code suggestions based on actual component usage
+- **🔄 Always Up-to-Date**: Documentation syncs automatically with code changes
+- **⚡ Enhanced Productivity**: Write draggable components faster with AI assistance
+
+### 📋 Quick Setup
+
+#### For Cursor IDE:
+```json
+{
+  "mcpServers": {
+    "vue-draggable": {
+      "command": "npx",
+      "args": ["@marsio/vue-draggable-mcp"]
+    }
+  }
+}
+```
+
+#### For Claude Desktop:
+Add to your Claude Desktop configuration:
+```json
+{
+  "mcpServers": {
+    "vue-draggable": {
+      "command": "npx", 
+      "args": ["@marsio/vue-draggable-mcp"]
+    }
+  }
+}
+```
+
+### 🛠️ Available Tools
+
+- **`get_vue_draggable_docs`**: Complete documentation in Markdown format
+- **`list_vue_draggable_props`**: Structured props information with types and defaults  
+- **`get_vue_draggable_type`**: Specific type definitions and interfaces
+
+### 💡 Example AI Prompts
+
+After setup, try asking your AI assistant:
+- *"Create a draggable card component with grid snapping"*
+- *"Show me all available props for Draggable component"*
+- *"How do I constrain dragging to horizontal axis only?"*
+
+[Learn more about MCP setup →](./mcp/README.md)
 ## 📦 Quick Start
 
 To quickly start using `@marsio/vue-draggable`, follow the steps below:
@@ -98,6 +153,7 @@ A simple component for making elements draggable.
 #### Technical Documentation
 
 - [Installing](#installing)
+- [AI IDE Integration (MCP)](#🤖-ai-ide-integration-mcp-server)
 - [Exports](#exports)
 - [Draggable](#draggable)
 - [Draggable Usage](#draggable-usage)
@@ -204,8 +260,8 @@ type DraggableData = {
 // If set to `true`, will allow dragging on non left-button clicks.
 allowAnyClick: boolean,
 
-// Determines which axis the draggable can move. This only affects
-// flushing to the DOM. Callbacks will still include all values.
+// Determines which axis the draggable can move.
+// Disabled axis movement is ignored and callbacks will report 0 deltas.
 // Accepted values:
 // - `both` allows movement horizontally and vertically (default).
 // - `x` limits movement to horizontal axis.
@@ -213,6 +269,12 @@ allowAnyClick: boolean,
 // - 'none' stops all movement.
 axis: string,
 
+// If true, lock to the dominant axis after the drag starts (prevents diagonal drift).
+directionLock: boolean,
+
+// Distance (px) before directionLock chooses an axis.
+directionLockThreshold: number,
+
 // Specifies movement boundaries. Accepted values:
 // - `parent` restricts movement within the node's offsetParent
 //    (nearest node with position relative or absolute), or
@@ -227,6 +289,10 @@ bounds: {left?: number, top?: number, right?: number, bottom?: number} | string,
 // Example: '.body'
 cancel: string,
 
+// If true, prevents dragging from starting on common interactive elements
+// (inputs, buttons, links, contenteditable).
+cancelInteractiveElements: boolean,
+
 // Class names for draggable UI.
 // Default to 'vue-draggable', 'vue-draggable-dragging', and 'vue-draggable-dragged'
 defaultClassName: string,
@@ -242,6 +308,48 @@ defaultPosition: {x: number, y: number},
 // If true, will not call any drag handlers.
 disabled: boolean,
 
+// If true, do not preventDefault() during touch drags, allowing the page/containers to scroll.
+allowMobileScroll: boolean,
+
+// If true, auto-scroll nearest scrollable container (and window) when the pointer is near an edge.
+autoScroll: boolean,
+
+// Distance (px) from an edge to start auto-scrolling.
+autoScrollThreshold: number,
+
+// Max auto-scroll speed (px per frame).
+autoScrollMaxSpeed: number,
+
+// Auto-scroll axis.
+autoScrollAxis: 'both' | 'x' | 'y' | 'none',
+
+// If false, never auto-scroll the window.
+autoScrollIncludeWindow: boolean,
+
+// Optional: specify which container(s) to auto-scroll.
+// Supports selector string, element, 'window', or an array of those.
+autoScrollContainer: string | HTMLElement | Window | Array<string | HTMLElement | Window> | null,
+
+// Minimum distance in pixels before the drag starts.
+// Useful to prevent accidental drags on click/tap.
+dragStartThreshold: number,
+
+// Touch-only: delay (ms) before drag can start (long-press activation).
+dragStartDelay: number,
+
+// Touch-only: movement tolerance (px) allowed during dragStartDelay before cancelling the drag start.
+dragStartDelayTolerance: number,
+
+// If true, suppress the click event fired after a drag.
+enableClickSuppression: boolean,
+
+// How long (ms) to suppress the next click after drag stop.
+clickSuppressionDuration: number,
+
+// If true, coalesce drag updates to requestAnimationFrame (at most once per frame).
+// This significantly reduces work under high-frequency move events.
+useRafDrag: boolean,
+
 // Specifies the x and y that dragging should snap to.
 grid: [number, number],
 
@@ -290,6 +398,24 @@ scale: number
 Note that sending `class`, `style`, or `transform` as properties will error - set them on the child element
 directly.
 
+## Auto Scroll
+
+Enable auto-scroll while dragging near an edge:
+
+```vue
+<Draggable :autoScroll="true" :autoScrollThreshold="40" :autoScrollMaxSpeed="24" />
+```
+
+Scroll only a specific container (and never the window):
+
+```vue
+<Draggable :autoScroll="true" autoScrollContainer=".scroll-pane" :autoScrollIncludeWindow="false" />
+```
+
+## Pointer Events
+
+When supported, `<DraggableCore>` uses Pointer Events (with `setPointerCapture()` for more robust drags outside the element).
+For touch pointers, Pointer Events require `touch-action` to be non-`auto` (e.g. `touch-action: none`); otherwise it falls back to Touch Events.
 
 ## Controlled vs. Uncontrolled
 
@@ -326,7 +452,21 @@ on itself and thus must have callbacks attached to be useful.
   allowAnyClick: boolean,
   cancel: string,
   disabled: boolean,
+  allowMobileScroll: boolean,
+  autoScroll: boolean,
+  autoScrollThreshold: number,
+  autoScrollMaxSpeed: number,
+  autoScrollAxis: 'both' | 'x' | 'y' | 'none',
+  autoScrollIncludeWindow: boolean,
+  autoScrollContainer: string | HTMLElement | Window | Array<string | HTMLElement | Window> | null,
+  cancelInteractiveElements: boolean,
+  enableClickSuppression: boolean,
+  clickSuppressionDuration: number,
+  dragStartDelay: number,
+  dragStartDelayTolerance: number,
   enableUserSelectHack: boolean,
+  dragStartThreshold: number,
+  useRafDrag: boolean,
   offsetParent: HTMLElement,
   grid: [number, number],
   handle: string,