@marsio/vue-draggable 1.0.8 → 1.0.10

package/README.md

@@ -6,6 +6,8 @@ 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](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.
 - **Drag Handlers**: Offers customizable drag handlers (`startFn`, `dragFn`, `stopFn`) that allow developers to hook into drag start, during drag, and drag stop events, providing flexibility in handling these events.
@@ -15,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:
@@ -96,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)
@@ -202,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.
@@ -211,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
@@ -225,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,
@@ -240,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],
 
@@ -288,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
 
@@ -324,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,

package/build/cjs/Draggable.js

@@ -11,15 +11,14 @@ Object.defineProperty(exports, "DraggableCore", {
 });
 exports.draggableProps = exports.default = void 0;
 var _vue = require("vue");
-var _get = _interopRequireDefault(require("lodash/get"));
 var _clsx = _interopRequireDefault(require("clsx"));
 var _domFns = require("./utils/domFns");
 var _positionFns = require("./utils/positionFns");
 var _shims = require("./utils/shims");
 var _DraggableCore = _interopRequireWildcard(require("./DraggableCore"));
 var _log = _interopRequireDefault(require("./utils/log"));
-function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
-function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+var _noop = _interopRequireDefault(require("./utils/noop"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /**
  * Draggable is a Vue component that allows elements to be dragged and dropped.
@@ -56,15 +55,21 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * Note:
  * This component requires Vue 3 and is designed to work within a Vue 3 application.
  */
-function _isSlot(s) {
-  return typeof s === 'function' || Object.prototype.toString.call(s) === '[object Object]' && !(0, _vue.isVNode)(s);
-}
+
 const draggableProps = exports.draggableProps = {
   ..._DraggableCore.draggableCoreProps,
   axis: {
     type: String,
     default: 'both'
   },
+  directionLock: {
+    type: Boolean,
+    default: false
+  },
+  directionLockThreshold: {
+    type: Number,
+    default: 4
+  },
   bounds: {
     type: [Object, String, Boolean],
     default: false
@@ -113,31 +118,86 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
     let {
       slots
     } = _ref;
-    console.log('props', props);
-    const rootElement = (0, _vue.ref)(null);
-    if (props.position && !(props.dragFn || props.stopFn)) {
-      // eslint-disable-next-line no-console
-      console.warn('A `position` was applied to this <Draggable>, without drag handlers. This will make this ' + 'component effectively undraggable. Please attach `dragFn` or `stopFn` handlers so you can adjust the ' + '`position` of this element.');
-    }
+    const localNodeRef = (0, _vue.ref)(null);
     const state = (0, _vue.reactive)({
       // Whether or not we are currently dragging.
       dragging: false,
       // Whether or not we have been dragged before.
       dragged: false,
       // Current transform x and y.
-      x: props.position ? props.position.x : props.defaultPosition.x,
-      y: props.position ? props.position.y : props.defaultPosition.y,
-      prevPropsPosition: {
-        ...props.position
-      },
+      x: props.position?.x ?? props.defaultPosition.x ?? 0,
+      y: props.position?.y ?? props.defaultPosition.y ?? 0,
       // Used for compensating for out-of-bounds drags
       slackX: 0,
       slackY: 0,
       // Can only determine if SVG after mounting
       isElementSVG: false
     });
+    const isElementNode = v => {
+      return !!v && typeof v === 'object' && 'nodeType' in v && v.nodeType === 1;
+    };
+    const isRefLike = v => {
+      return !!v && typeof v === 'object' && 'value' in v;
+    };
     const findDOMNode = () => {
-      return (0, _get.default)(props, 'nodeRef.value') || rootElement.value;
+      const nodeRef = props.nodeRef;
+      if (isRefLike(nodeRef)) {
+        const v = nodeRef.value;
+        if (isElementNode(v)) return v;
+      } else if (isElementNode(nodeRef)) {
+        return nodeRef;
+      }
+      return localNodeRef.value;
+    };
+    const boundsContext = {
+      props,
+      findDOMNode,
+      __boundsCache: {
+        key: '',
+        node: null,
+        boundEl: null,
+        boundClientWidth: 0,
+        boundClientHeight: 0,
+        nodeClientWidth: 0,
+        nodeClientHeight: 0,
+        bounds: null
+      }
+    };
+    let rafId = null;
+    let internalX = state.x;
+    let internalY = state.y;
+    let internalSlackX = state.slackX;
+    let internalSlackY = state.slackY;
+    let directionLockAxis = null;
+    let directionLockFixedX = NaN;
+    let directionLockFixedY = NaN;
+    let directionLockTotalX = 0;
+    let directionLockTotalY = 0;
+    const resetDirectionLock = () => {
+      directionLockAxis = null;
+      directionLockFixedX = NaN;
+      directionLockFixedY = NaN;
+      directionLockTotalX = 0;
+      directionLockTotalY = 0;
+    };
+    const getDirectionLockThreshold = () => {
+      const threshold = typeof props.directionLockThreshold === 'number' ? props.directionLockThreshold : 0;
+      if (threshold <= 0) return 0;
+      const scale = typeof props.scale === 'number' ? props.scale : 1;
+      if (!scale) return threshold;
+      return threshold / scale;
+    };
+    const flushToReactiveState = () => {
+      rafId = null;
+      if (internalX === state.x && internalY === state.y && internalSlackX === state.slackX && internalSlackY === state.slackY) return;
+      state.x = internalX;
+      state.y = internalY;
+      state.slackX = internalSlackX;
+      state.slackY = internalSlackY;
+    };
+    const scheduleFlush = () => {
+      if (rafId != null) return;
+      rafId = window.requestAnimationFrame(flushToReactiveState);
     };
     (0, _vue.onMounted)(() => {
       if (typeof window.SVGElement !== 'undefined' && findDOMNode() instanceof window.SVGElement) {
@@ -146,83 +206,190 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
     });
     (0, _vue.onUnmounted)(() => {
       state.dragging = false;
+      if (rafId != null) {
+        window.cancelAnimationFrame(rafId);
+        rafId = null;
+      }
     });
     const onDragStart = (e, coreData) => {
       (0, _log.default)('Draggable: onDragStart: %j', coreData);
 
       // Short-circuit if user's callback killed it.
-      const shouldStart = props.startFn?.(e, (0, _positionFns.createDraggableData)({
-        props,
-        state
-      }, coreData));
-      // Kills start event on core as well, so move handlers are never bound.
-      if (shouldStart === false) return false;
+      const isControlled = Boolean(props.position);
+      if (isControlled) {
+        internalX = props.position.x;
+        internalY = props.position.y;
+      } else {
+        internalX = state.x;
+        internalY = state.y;
+      }
+      internalSlackX = state.slackX;
+      internalSlackY = state.slackY;
+      boundsContext.__boundsCache.key = '';
+      boundsContext.__boundsCache.node = null;
+      boundsContext.__boundsCache.boundEl = null;
+      boundsContext.__boundsCache.boundClientWidth = 0;
+      boundsContext.__boundsCache.boundClientHeight = 0;
+      boundsContext.__boundsCache.nodeClientWidth = 0;
+      boundsContext.__boundsCache.nodeClientHeight = 0;
+      boundsContext.__boundsCache.bounds = null;
+      resetDirectionLock();
+      flushToReactiveState();
+      if (props.startFn !== _noop.default) {
+        const scale = typeof props.scale === 'number' ? props.scale : 1;
+        const uiStart = {
+          node: coreData.node,
+          x: internalX + coreData.deltaX / scale,
+          y: internalY + coreData.deltaY / scale,
+          deltaX: coreData.deltaX / scale,
+          deltaY: coreData.deltaY / scale,
+          lastX: internalX,
+          lastY: internalY
+        };
+        const shouldStart = props.startFn?.(e, uiStart);
+        // Kills start event on core as well, so move handlers are never bound.
+        if (shouldStart === false) return false;
+      }
       state.dragging = true;
       state.dragged = true;
     };
     const onDrag = (e, coreData) => {
       if (!state.dragging) return false;
       (0, _log.default)('Draggable: dragFn: %j', coreData);
-      const uiData = (0, _positionFns.createDraggableData)({
-        props,
-        state
-      }, coreData);
-      const newState = {
-        x: uiData.x,
-        y: uiData.y,
-        slackX: 0,
-        slackY: 0
-      };
+      const scale = typeof props.scale === 'number' ? props.scale : 1;
+      const rawDeltaX = coreData.deltaX / scale;
+      const rawDeltaY = coreData.deltaY / scale;
+      let newX = internalX + rawDeltaX;
+      let newY = internalY + rawDeltaY;
+      let newSlackX = 0;
+      let newSlackY = 0;
+      let uiDeltaX = rawDeltaX;
+      let uiDeltaY = rawDeltaY;
+      const allowAxisX = (0, _positionFns.canDragX)({
+        props
+      });
+      const allowAxisY = (0, _positionFns.canDragY)({
+        props
+      });
+      let effectiveAxisX = allowAxisX;
+      let effectiveAxisY = allowAxisY;
+      if (props.directionLock && allowAxisX && allowAxisY) {
+        if (directionLockAxis == null) {
+          directionLockTotalX += rawDeltaX;
+          directionLockTotalY += rawDeltaY;
+          const threshold = getDirectionLockThreshold();
+          if (!threshold || Math.hypot(directionLockTotalX, directionLockTotalY) >= threshold) {
+            directionLockAxis = Math.abs(directionLockTotalX) >= Math.abs(directionLockTotalY) ? 'x' : 'y';
+            directionLockFixedX = internalX;
+            directionLockFixedY = internalY;
+          }
+        }
+        if (directionLockAxis === 'x' && Number.isFinite(directionLockFixedY)) {
+          newY = directionLockFixedY;
+          uiDeltaY = newY - internalY;
+        } else if (directionLockAxis === 'y' && Number.isFinite(directionLockFixedX)) {
+          newX = directionLockFixedX;
+          uiDeltaX = newX - internalX;
+        }
+      }
+      if (directionLockAxis === 'x') effectiveAxisY = false;
+      if (directionLockAxis === 'y') effectiveAxisX = false;
+      if (!effectiveAxisX) {
+        newX = internalX;
+        uiDeltaX = 0;
+      }
+      if (!effectiveAxisY) {
+        newY = internalY;
+        uiDeltaY = 0;
+      }
 
       // Keep within bounds.
       if (props.bounds) {
         // Save original x and y.
-        const {
-          x,
-          y
-        } = newState;
+        const x = newX;
+        const y = newY;
 
         // Add slack to the values used to calculate bound position. This will ensure that if
         // completely removed.
-        newState.x += state.slackX;
-        newState.y += state.slackY;
+        const slackX = effectiveAxisX ? internalSlackX : 0;
+        const slackY = effectiveAxisY ? internalSlackY : 0;
+        newX += slackX;
+        newY += slackY;
 
         // Get bound position. This will ceil/floor the x and y within the boundaries.
-        const [newStateX, newStateY] = (0, _positionFns.getBoundPosition)({
-          props,
-          findDOMNode
-        }, newState.x, newState.y);
-        newState.x = newStateX;
-        newState.y = newStateY;
+        const [boundX, boundY] = (0, _positionFns.getBoundPosition)(boundsContext, newX, newY);
+        newX = boundX;
+        newY = boundY;
 
         // Recalculate slack by noting how much was shaved by the boundPosition handler.
-        newState.slackX = state.slackX + (x - newState.x);
-        newState.slackY = state.slackY + (y - newState.y);
+        newSlackX = slackX + (x - newX);
+        newSlackY = slackY + (y - newY);
 
         // Update the event we fire to reflect what really happened after bounds took effect.
-        uiData.x = newState.x;
-        uiData.y = newState.y;
-        uiData.deltaX = newState.x - (state.x ?? 0);
-        uiData.deltaY = newState.y - (state.y ?? 0);
+        uiDeltaX = newX - internalX;
+        uiDeltaY = newY - internalY;
       }
+      if (!effectiveAxisX) newSlackX = 0;
+      if (!effectiveAxisY) newSlackY = 0;
 
       // Short-circuit if user's callback killed it.
-      const shouldUpdate = props.dragFn?.(e, uiData);
-      if (shouldUpdate === false) return false;
-      Object.keys(newState).forEach(key => {
-        state[key] = newState[key];
-      });
+      if (props.dragFn !== _noop.default) {
+        const uiData = {
+          node: coreData.node,
+          x: newX,
+          y: newY,
+          deltaX: uiDeltaX,
+          deltaY: uiDeltaY,
+          lastX: internalX,
+          lastY: internalY
+        };
+        const shouldUpdate = props.dragFn?.(e, uiData);
+        if (shouldUpdate === false) return false;
+      }
+      internalX = newX;
+      internalY = newY;
+      internalSlackX = newSlackX;
+      internalSlackY = newSlackY;
+      if (props.useRafDrag) {
+        if (rafId != null) {
+          window.cancelAnimationFrame(rafId);
+          rafId = null;
+        }
+        flushToReactiveState();
+      } else {
+        scheduleFlush();
+      }
     };
     const onDragStop = (e, coreData) => {
       if (!state.dragging) return false;
 
       // Short-circuit if user's callback killed it.
-      const shouldContinue = props.stopFn?.(e, (0, _positionFns.createDraggableData)({
-        props,
-        state
-      }, coreData));
-      if (shouldContinue === false) return false;
+      if (props.stopFn !== _noop.default) {
+        const scale = typeof props.scale === 'number' ? props.scale : 1;
+        const allowAxisX = (0, _positionFns.canDragX)({
+          props
+        });
+        const allowAxisY = (0, _positionFns.canDragY)({
+          props
+        });
+        const effectiveAxisX = allowAxisX && directionLockAxis !== 'y';
+        const effectiveAxisY = allowAxisY && directionLockAxis !== 'x';
+        const deltaX = effectiveAxisX ? coreData.deltaX / scale : 0;
+        const deltaY = effectiveAxisY ? coreData.deltaY / scale : 0;
+        const uiStop = {
+          node: coreData.node,
+          x: internalX + deltaX,
+          y: internalY + deltaY,
+          deltaX,
+          deltaY,
+          lastX: internalX,
+          lastY: internalY
+        };
+        const shouldContinue = props.stopFn?.(e, uiStop);
+        if (shouldContinue === false) return false;
+      }
       (0, _log.default)('Draggable: onDragStop: %j', coreData);
+      resetDirectionLock();
       const newState = {
         dragging: false,
         slackX: 0,
@@ -240,14 +407,55 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         newState.x = x;
         newState.y = y;
       }
-      Object.keys(newState).forEach(key => {
-        state[key] = newState[key];
-      });
+      state.dragging = newState.dragging;
+      internalSlackX = newState.slackX;
+      internalSlackY = newState.slackY;
+      if (typeof newState.x === 'number') internalX = newState.x;
+      if (typeof newState.y === 'number') internalY = newState.y;
+      if (rafId != null) {
+        window.cancelAnimationFrame(rafId);
+        rafId = null;
+      }
+      flushToReactiveState();
+    };
+    const getFirstUsableChild = () => {
+      const raw = slots.default ? slots.default() : [];
+      const stack = Array.isArray(raw) ? [...raw] : [raw];
+      while (stack.length) {
+        const item = stack.shift();
+        if (Array.isArray(item)) {
+          for (let i = item.length - 1; i >= 0; i -= 1) stack.unshift(item[i]);
+          continue;
+        }
+        if (!(0, _vue.isVNode)(item)) continue;
+
+        // Skip comment nodes and whitespace-only text nodes.
+        if (item.type === _vue.Comment) continue;
+        if (item.type === _vue.Text) {
+          const txt = typeof item.children === 'string' ? item.children : '';
+          if (!txt || !txt.trim()) continue;
+          // Draggable requires an element/component vnode, not bare text.
+          continue;
+        }
+
+        // Unwrap fragments to find the first real node.
+        if (item.type === _vue.Fragment) {
+          const fragChildren = item.children;
+          if (Array.isArray(fragChildren)) {
+            for (let i = fragChildren.length - 1; i >= 0; i -= 1) stack.unshift(fragChildren[i]);
+          }
+          continue;
+        }
+        return item;
+      }
+      return null;
     };
     return () => {
       /* eslint-disable @typescript-eslint/no-unused-vars */
       const {
         axis,
+        directionLock,
+        directionLockThreshold,
         bounds,
         defaultPosition,
         defaultClassName,
@@ -292,7 +500,7 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         [defaultClassNameDragging]: state.dragging,
         [defaultClassNameDragged]: state.dragged
       });
-      const child = slots.default ? slots.default()[0] : null;
+      const child = getFirstUsableChild();
       if (!child) return null;
       const clonedChildren = (0, _vue.cloneVNode)(child, {
         class: className,
@@ -305,10 +513,10 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         dragFn: onDrag,
         stopFn: onDragStop
       };
-      return (0, _vue.createVNode)(_DraggableCore.default, (0, _vue.mergeProps)({
-        "ref": rootElement
-      }, coreProps), _isSlot(clonedChildren) ? clonedChildren : {
-        default: () => [clonedChildren]
+      return (0, _vue.createVNode)(_DraggableCore.default, (0, _vue.mergeProps)(coreProps, {
+        "nodeRef": props.nodeRef || localNodeRef
+      }), {
+        default: () => clonedChildren
       });
     };
   }