@marsio/vue-draggable 1.0.2 → 1.0.3

package/README.md

@@ -1,11 +1,89 @@
-# Vue-Draggable
-
+# Vue-Draggable 
 
+Draggable and DraggableCore are **Vue3** components designed to make elements draggable within a Vue application. They provide a flexible and powerful way to add drag-and-drop functionality to your Vue components.
 
 <p align="center">
   <img src="https://user-images.githubusercontent.com/6365230/95649276-f3a02480-0b06-11eb-8504-e0614a780ba4.gif" />
 </p>
 
+## Features
+- **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.
+- **Position Control**: Supports controlled (`position`) and uncontrolled (`defaultPosition`) modes for element positioning, giving developers the choice to manage the draggable element's position externally or let the component handle it internally.
+- **Axis Constraints**: Allows dragging to be constrained along a specific axis (`axis`) with options for 'x', 'y', 'both', or 'none', enabling more precise control over the draggable behavior.
+- **Bounds Limitation**: Supports constraining the draggable area within specified bounds (`bounds`), which can be defined as an object with `left`, `right`, `top`, and `bottom` properties, a selector string, or `false` for no bounds.
+- **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.
+
+## Quick Start
+
+To quickly start using `@marsio/vue-draggable`, follow the steps below:
+
+### Step 1: Installation
+
+First, you need to install the package. Run the following command in your project directory:
+
+```bash
+npm install @marsio/vue-draggable
+```
+
+or if you prefer using Yarn:
+
+```bash
+yarn add @marsio/vue-draggable
+```
+
+or if you prefer using Pnpm:
+
+```bash
+pnpm add @marsio/vue-draggable
+```
+
+
+### Step 2: Importing
+
+In your Vue component, import `@marsio/vue-draggable`:
+
+```javascript
+import Draggable from '@marsio/vue-draggable';
+```
+
+### Step 3: Using `@marsio/vue-draggable`
+
+Now, you can use the `Draggable` component in your Vue application. Wrap any element with `<Draggable>` to make it draggable:
+
+```vue
+<template>
+  <Draggable>
+    <div class="draggable-item">I can now be moved around!</div>
+  </Draggable>
+</template>
+
+<script>
+import Draggable from '@marsio/vue-draggable';
+
+export default {
+  components: {
+    Draggable
+  }
+}
+</script>
+
+<style>
+.draggable-item {
+  /* Your styles for draggable items */
+}
+</style>
+```
+
+### Step 4: Enjoy!
+
+That's it! You've successfully integrated draggable functionality into your Vue application. Customize it further according to your needs.
+
+For more detailed documentation, refer to the [Technical Documentation](#technical-documentation) section.
+
+
+
 A simple component for making elements draggable.
 
 ```js
@@ -26,20 +104,6 @@ A simple component for making elements draggable.
 - [DraggableCore API](#draggablecore-api)
 
 
-
-### Installing
-
-```bash
-$ npm install @marsio/vue-draggable
-```
-
-If you aren't using browserify/webpack, a
-[UMD version of vue-draggable](dist/vue-draggable.js) is available. It is updated per-release only.
-This bundle is also what is loaded when installing from npm. It expects external Vue3.
-
-If you want a UMD version of the latest `master` revision, you can generate it yourself from master by cloning this
-repository and running `$ make`. This will create umd dist files in the `build/` folder.
-
 ### Exports
 
 The default export is `<Draggable>`. At the `.DraggableCore` property is [`<DraggableCore>`](#draggablecore).
@@ -201,28 +265,6 @@ dragFn: DraggableEventHandler,
 // Called when dragging stops.
 stopFn: DraggableEventHandler,
 
-// import { defineComponent, ref } from 'vue';
-// import Draggable from 'vue-draggable'
-
-// const Component1 = defineComponent({
-//   props: {
-//     title: String
-//   },
-//   setup(props) {
-//     return { title };
-//   }
-// });
-
-// export default defineComponent({
-//   setup(props) {
-//     const nodeRef = ref(null)
-//     return () => (
-//       <DraggableCore dragFn={onDrag} nodeRef={nodeRef}>
-//         <Component1 ref={nodeRef} />
-//       </DraggableCore>
-//     )
-//   }
-// });
 // `nodeRef` is also available on <DraggableCore>.
 nodeRef: Ref<HTMLElement | null>,
 
@@ -301,19 +343,17 @@ Drag callbacks (`startFn`, `dragFn`, `stopFn`) are called with the [same argumen
 
 ----
 
-### Contributing
+### Modern browsers.
 
-- Fork the project
-- Run the project in development mode: `$ npm run dev`
-- Make changes.
-- Update README with appropriate docs.
-- Commit and PR
+| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt="Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_48x48.png" alt="Opera" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)</br>Opera |
+| --- | --- | --- | --- | --- |
+| Edge | last 2 versions | last 2 versions | last 2 versions | last 2 versions |
 
 ### Release checklist
 
 - Update CHANGELOG
-- `make release-patch`
-- `make publish`
+- `pnpm release`
+- `pnpm publish`
 
 ### License
 

package/build/cjs/Draggable.js

@@ -20,8 +20,43 @@ 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 && Object.prototype.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; }
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+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; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Draggable is a Vue component that allows elements to be dragged and dropped.
+ * It extends DraggableCore by adding Vue-specific props for more customized behavior.
+ * 
+ * Props:
+ * - axis: Specifies the axis along which the element can be dragged. Options are 'both', 'x', 'y', or 'none'. Default is 'both'.
+ * - bounds: Constrains the draggable area. Can be an object specifying left, right, top, and bottom bounds, a string selector, or false for no bounds. Default is false.
+ * - defaultClassName: The default class name applied to the element. Default is 'vue-draggable'.
+ * - defaultClassNameDragging: The class name applied to the element while dragging. Default is 'vue-draggable-dragging'.
+ * - defaultClassNameDragged: The class name applied to the element after it has been dragged. Default is 'vue-draggable-dragged'.
+ * - defaultPosition: The default position of the element. An object with x and y properties. Default is {x: 0, y: 0}.
+ * - positionOffset: Offset of the position. An object with x and y properties, each can be a number or a string. Default is {x: 0, y: 0}.
+ * - position: Controls the position of the draggable element. An object with x and y properties.
+ * - cancel: Specifies a selector to be used to prevent drag initialization.
+ * - offsetParent: Specifies the offset parent of the draggable element. Must be a DOM Node.
+ * - grid: Specifies the grid to snap the draggable element to during drag. An array of two numbers.
+ * - handle: Specifies a selector to be used as the handle that initiates drag.
+ * - nodeRef: A reference to the draggable node.
+ * - allowAnyClick: Allows dragging to be initiated with any mouse button. Default is false.
+ * - disabled: If true, the element cannot be dragged. Default is false.
+ * - enableUserSelectHack: Enables a hack that prevents text selection during drag. Default is true.
+ * - startFn, dragFn, stopFn: Functions that are called on drag start, during drag, and on drag stop, respectively. Each defaults to a no-op function.
+ * - scale: The scale of the draggable element. Default is 1.
+ * 
+ * Usage:
+ * Wrap a single child component or element with <Draggable> to make it draggable. Configure behavior with props.
+ * 
+ * Example:
+ * <Draggable axis="x" :defaultPosition="{x: 100, y: 0}">
+ *   <div>Drag me!</div>
+ * </Draggable>
+ * 
+ * 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);
 }
@@ -51,7 +86,7 @@ const draggableProps = exports.draggableProps = {
   position: _vueTypes.default.shape({
     x: _vueTypes.default.number,
     y: _vueTypes.default.number
-  }).def(null)
+  }).def(undefined)
 };
 const componentName = 'Draggable';
 const Draggable = exports.default = (0, _vue.defineComponent)({
@@ -111,7 +146,7 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
       (0, _log.default)('Draggable: onDragStart: %j', coreData);
 
       // Short-circuit if user's callback killed it.
-      const shouldStart = props.startFn(e, (0, _positionFns.createDraggableData)({
+      const shouldStart = props.startFn?.(e, (0, _positionFns.createDraggableData)({
         props,
         state
       }, coreData));
@@ -162,12 +197,12 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         // 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;
-        uiData.deltaY = newState.y - state.y;
+        uiData.deltaX = newState.x - (state.x ?? 0);
+        uiData.deltaY = newState.y - (state.y ?? 0);
       }
 
       // Short-circuit if user's callback killed it.
-      const shouldUpdate = props.dragFn(e, uiData);
+      const shouldUpdate = props.dragFn?.(e, uiData);
       if (shouldUpdate === false) return false;
       Object.keys(newState).forEach(key => {
         state[key] = newState[key];
@@ -177,7 +212,7 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
       if (!state.dragging) return false;
 
       // Short-circuit if user's callback killed it.
-      const shouldContinue = props.stopFn(e, (0, _positionFns.createDraggableData)({
+      const shouldContinue = props.stopFn?.(e, (0, _positionFns.createDraggableData)({
         props,
         state
       }, coreData));
@@ -205,10 +240,10 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
       });
     };
     return () => {
+      /* eslint-disable @typescript-eslint/no-unused-vars */
       const {
         axis,
         bounds,
-        // children,
         defaultPosition,
         defaultClassName,
         defaultClassNameDragging,
@@ -218,20 +253,22 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         scale,
         ...draggableCoreProps
       } = props;
+      /* eslint-enable @typescript-eslint/no-unused-vars */
+
       let style = {};
-      let svgTransform = null;
+      let svgTransform = '';
       const controlled = Boolean(position);
       const draggable = !controlled || state.dragging;
       const validPosition = position || defaultPosition;
       const transformOpts = {
         // Set left if horizontal drag is enabled
-        x: (0, _positionFns.canDragX)({
+        x: ((0, _positionFns.canDragX)({
           props
-        }) && draggable ? state.x : validPosition.x,
+        }) && draggable ? state.x : validPosition.x) ?? 0,
         // Set top if vertical drag is enabled
-        y: (0, _positionFns.canDragY)({
+        y: ((0, _positionFns.canDragY)({
           props
-        }) && draggable ? state.y : validPosition.y
+        }) && draggable ? state.y : validPosition.y) ?? 0
       };
 
       // If this element was SVG, we use the `transform` attribute.
@@ -244,23 +281,18 @@ const Draggable = exports.default = (0, _vue.defineComponent)({
         // has a clean slate.
         style = (0, _domFns.createCSSTransform)(transformOpts, positionOffset);
       }
-      const slotContent = (0, _vue.renderSlot)(slots, 'default');
-      let children = slotContent.children;
-      if (!Array.isArray(children)) {
-        children = []; // 如果不是数组，则使用空数组
-      }
 
       // Mark with class while dragging
       const className = (0, _clsx.default)(defaultClassName, {
         [defaultClassNameDragging]: state.dragging,
         [defaultClassNameDragged]: state.dragged
       });
-      const clonedChildren = children.flatMap(child => {
-        return (0, _vue.isVNode)(child) ? (0, _vue.cloneVNode)(child, {
-          class: className,
-          style: style,
-          transform: svgTransform
-        }) : child;
+      const child = slots.default ? slots.default()[0] : null;
+      if (!child) return null;
+      const clonedChildren = (0, _vue.cloneVNode)(child, {
+        class: className,
+        style,
+        transform: svgTransform
       });
       const coreProps = {
         ...draggableCoreProps,

package/build/cjs/DraggableCore.js

@@ -11,7 +11,42 @@ var _domFns = require("./utils/domFns");
 var _positionFns = require("./utils/positionFns");
 var _shims = require("./utils/shims");
 var _log = _interopRequireDefault(require("./utils/log"));
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * DraggableCore is a low-level wrapper for draggable functionality, allowing for more fine-grained control over drag events.
+ * It provides the core functionality needed to make an element draggable, such as mouse and touch event handling, without
+ * imposing any specific styling or structure on the element being dragged. It's designed to be used as a building block
+ * for more complex draggable components.
+ *
+ * @compatConfig {MODE: 3} - Compatibility mode setting for Vue 3.
+ * @name DraggableCore - The name of the component.
+ * @inheritAttrs false - Instructs Vue not to add inherited attributes to the component's root element.
+ *
+ * @props
+ * - `allowAnyClick` (Boolean): Allows dragging using any mouse button. Default is `false`, which means only the left mouse button can initiate dragging.
+ * - `disabled` (Boolean): Disables the draggable functionality when set to `true`.
+ * - `enableUserSelectHack` (Boolean): Enables a hack that prevents user text selection during dragging. Default is `true`.
+ * - `startFn` (Function): A function that is called at the start of a drag operation. Default is a no-op function.
+ * - `dragFn` (Function): A function that is called during a drag operation. Default is a no-op function.
+ * - `stopFn` (Function): A function that is called at the end of a drag operation. Default is a no-op function.
+ * - `scale` (Number): The scale of the draggable element, affecting drag sensitivity. Default is `1`.
+ * - `cancel` (String): CSS selector that defines elements within the draggable element that should prevent dragging when clicked.
+ * - `offsetParent` (HTMLElement): The offset parent of the draggable element, used to calculate drag distances. Must be a DOM Node.
+ * - `grid` (Array[Number, Number]): Specifies a grid [x, y] to which the element's movement will be snapped.
+ * - `handle` (String): CSS selector that defines the handle element that initiates drag actions. If not defined, the entire element is draggable.
+ * - `nodeRef` (Object): A Vue ref object pointing to the draggable element. Used when direct DOM access is necessary.
+ *
+ * @setup
+ * The setup function initializes the component's reactive state and event handlers for drag operations. It handles the
+ * initialization and cleanup of event listeners for mouse and touch events that control the drag behavior.
+ *
+ * @returns
+ * The setup function returns a render function that clones the component's default slot's first child, applying the necessary
+ * event handlers and a ref to the root element to enable dragging functionality.
+ *
+ * Note: This component does not render any DOM elements itself; it merely wraps its default slot's content with draggable functionality.
+ */
+
 // Simple abstraction for dragging events names.
 const eventsFor = {
   touch: {
@@ -25,6 +60,8 @@ const eventsFor = {
     stop: 'mouseup'
   }
 };
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 const defaultDraggableEventHandler = (e, data) => true;
 exports.defaultDraggableEventHandler = defaultDraggableEventHandler;
 const funcVoid = function () {};
@@ -43,10 +80,10 @@ const draggableCoreDefaultProps = exports.draggableCoreDefaultProps = {
 const draggableCoreProps = exports.draggableCoreProps = {
   ...draggableCoreDefaultProps,
   cancel: _vueTypes.default.string,
-  offsetParent: _vueTypes.default.custom(_shims.prop_is_not_node, 'Draggable\'s offsetParent must be a DOM Node.'),
+  offsetParent: _vueTypes.default.custom(_shims.propIsNotNode, 'Draggable\'s offsetParent must be a DOM Node.'),
   grid: _vueTypes.default.arrayOf(_vueTypes.default.number),
   handle: _vueTypes.default.string,
-  nodeRef: _vueTypes.default.object.def(null)
+  nodeRef: _vueTypes.default.object.def(() => null)
 };
 const componentName = 'DraggableCore';
 var _default = exports.default = (0, _vue.defineComponent)({
@@ -57,9 +94,6 @@ var _default = exports.default = (0, _vue.defineComponent)({
   inheritAttrs: false,
   props: {
     ...draggableCoreProps
-    // style: dontSetMe('style', componentName),
-    // class: dontSetMe('class', componentName),
-    // transform: dontSetMe('transform', componentName),
   },
   setup(props, _ref) {
     let {
@@ -67,7 +101,6 @@ var _default = exports.default = (0, _vue.defineComponent)({
       emit
     } = _ref;
     const rootElement = (0, _vue.ref)(null);
-    const displayName = 'DraggableCore';
     const state = (0, _vue.reactive)({
       dragging: false,
       // Used while dragging to determine deltas.
@@ -178,7 +211,7 @@ var _default = exports.default = (0, _vue.defineComponent)({
       // Get nodes. Be sure to grab relative document (could be iframed)
       const thisNode = findDOMNode();
       if (!(0, _get.default)(thisNode, 'ownerDocument.body')) {
-        throw new Error('<DraggableCore> not mounted on DragStart!');
+        // throw new Error('<DraggableCore> not mounted on DragStart!');
       }
       const {
         ownerDocument
@@ -219,7 +252,7 @@ var _default = exports.default = (0, _vue.defineComponent)({
 
       // Call event handler. If it returns explicit false, cancel.
       (0, _log.default)('calling', props.startFn);
-      const shouldUpdate = props.startFn(e, coreEvent);
+      const shouldUpdate = props.startFn?.(e, coreEvent);
       if (shouldUpdate === false || state.mounted === false) return;
 
       // Add a style to the body to disable user-select. This prevents text from
@@ -243,12 +276,6 @@ var _default = exports.default = (0, _vue.defineComponent)({
       dragEventFor = eventsFor.mouse; // on touchscreen laptops we could switch back to mouse
       return handleDragStart(e);
     };
-
-    // const onMoueDown = (e: MouseTouchEvent) => {
-    //   dragEventFor = eventsFor.mouse // on touchscreen laptops we could switch back to mouse
-    //   return handleDragStart(e)
-    // }
-
     const onMouseup = e => {
       dragEventFor = eventsFor.mouse;
       return handleDragStop(e);
@@ -292,12 +319,8 @@ var _default = exports.default = (0, _vue.defineComponent)({
       }
     });
     return () => {
-      const slotContent = (0, _vue.renderSlot)(slots, 'default');
-      let children = slotContent.children;
-      if (!Array.isArray(children)) {
-        children = []; // 如果不是数组，则使用空数组
-      }
-      const child = (0, _get.default)(children, '0.children[0]');
+      const child = slots.default ? slots.default()[0] : null;
+      if (!child) return null;
       const clonedChildren = (0, _vue.isVNode)(child) ? (0, _vue.cloneVNode)(child, {
         onMousedown,
         onMouseup,