@vue-dnd-kit/core 1.7.0 → 2.0.0-alpha10

package/README.md

@@ -1,305 +1,74 @@
-# Vue Drag & Drop Library - Core Package
-
-[![Release](https://img.shields.io/badge/status-release-green.svg)](https://github.com/zizigy/vue-dnd-kit)
-
-<p align="center">
-  <a href="https://zizigy.github.io/vue-dnd-kit/">
-    <img src="https://raw.githubusercontent.com/ZiZiGY/vue-dnd-kit/master/public/logo.svg" width="400" alt="Vue Drag & Drop Logo">
-  </a>
-</p>
-
-<p align="center">
-  Core package of the Vue Drag & Drop library with essential hooks and functionality.
-</p>
-
-<p align="center">
-  <a href="https://zizigy.github.io/vue-dnd-kit/" target="_blank">
-    <img src="https://img.shields.io/badge/Documentation-Visit-blue?style=flat-square" alt="Documentation">
-  </a>
-</p>
-
-<p align="center">
-  Inspired by the popular <a href="https://dndkit.com/" target="_blank">React DnD Kit</a> library, adapted for Vue.js
-</p>
-
-## Lightweight & High Performance
-
-Vue DnD Kit is designed to be extremely lightweight while delivering exceptional performance. The library has been optimized for:
-
-- 🚀 **Minimal bundle size** - keep your application fast and responsive
-- ⚡ **Efficient DOM operations** - optimized for handling large lists and complex interactions
-- 🔄 **Smart rendering** - prevents unnecessary re-renders during drag operations
-- 📱 **Smooth experience** - even on mobile and low-powered devices
-
-## Unlimited Flexibility
-
-The library is built with flexibility as a core principle, allowing you to implement virtually any drag and drop scenario:
-
-- 🎯 **Any UI pattern** - sortable lists, kanban boards, calendars, file uploads, and more
-- 🎨 **Any design system** - works with any UI library or custom components
-- 📐 **Any layout** - grid, flex, or custom positioning systems
-- 🔄 **Any interaction model** - simple drag and drop, multi-select, nested containers
-
-## Features
-
-### Core Capabilities
-
-- 🎯 **Simple Composables API**
-
-  - Intuitive hooks-based approach
-  - Clean and declarative syntax
-  - Minimal boilerplate code
-
-- 🎨 **Full Customization**
-
-  - Custom drag overlays
-  - Flexible styling system
-  - Animation support
-  - Custom drag handles
-
-- 📱 **Advanced Input Support**
-
-  - Touch devices support
-  - Mouse events
-  - Multi-touch gestures
-  - **Full keyboard navigation** - complete drag and drop operations using only keyboard
-
-### Accessibility
-
-- ♿ **Keyboard Navigation**
-
-  - Start and control drag operations with keyboard
-  - Arrow keys for movement
-  - Space/Enter for selection and dropping
-  - Escape to cancel drag operations
-  - Tab navigation between draggable elements
-
-- 🔍 **Screen Reader Support**
-
-  - ARIA attributes for drag and drop operations
-  - Descriptive announcements during interactions
-  - Semantic HTML structure
-
-### Performance
-
-- ⚡ **Optimized Rendering**
-
-  - Virtual DOM friendly
-  - Minimal re-renders
-  - Efficient DOM updates
-  - Memory leak prevention
-
-- 🔄 **Smart Auto-scrolling**
-
-  - Smooth scroll animations
-  - Configurable thresholds
-  - Performance-optimized
-  - Works with nested scrollable containers
-
-### Developer Experience
-
-- 🔍 **TypeScript Ready**
-
-  - Full type coverage
-  - Type inference
-  - IDE autocompletion
-  - Type-safe events
-
-- 📐 **Layout Features**
-
-  - Grid system support
-  - Flex layout compatible
-  - Responsive design ready
-  - Dynamic constraints
-
-### Advanced Features
-
-- 🎯 **Smart Grouping**
-
-  - Element groups
-  - Zone filtering
-  - Nested groups
-  - Dynamic group validation
-
-- 📊 **Rich Events System**
-
-  - Comprehensive lifecycle events
-  - Custom event handlers
-  - Drag state tracking
-  - Position coordinates
-
-- 🛡️ **Built-in Utilities**
-
-  - Geometry calculations
-  - Bounding box tracking
-  - Position management
-  - Intersection detection
-
-### Integration
-
-- 🔌 **Framework Integration**
-  - Vue 3 Composition API
-  - Nuxt.js compatible
-  - Works with SSR
-  - Plugin ecosystem ready
-
-## Installation
-
-Choose your preferred package manager:
-
-```bash
-npm install @vue-dnd-kit/core @vueuse/core
-```
-
-```bash
-yarn add @vue-dnd-kit/core @vueuse/core
-```
-
-```bash
-pnpm install @vue-dnd-kit/core @vueuse/core
-```
-
-## Setup as a Plugin
-
-You can register the library as a Vue plugin in your main.ts/js file:
-
-```typescript
-import { createApp } from 'vue';
-import App from './App.vue';
-import VueDnDKitPlugin from '@vue-dnd-kit/core';
-
-const app = createApp(App);
-
-// Register the plugin
-app.use(VueDnDKitPlugin);
-
-app.mount('#app');
-```
-
-This will make all the components and composables globally available in your application.
-
-## Basic Usage
-
-### App.vue
-
-<sup>📄 Root Application Component</sup>
-
-```vue
-<script setup lang="ts">
-  import { ref } from 'vue';
-  import Draggable from './components/Draggable.vue';
-  import Droppable from './components/Droppable.vue';
-
-  const handleDrop = () => (elementInDropZone.value = true);
-
-  const handleEnd = () => (elementInDropZone.value = false);
-
-  const elementInDropZone = ref<boolean>(false);
-</script>
-
-<template>
-  <div>
-    <Draggable v-if="!elementInDropZone"> drag me </Draggable>
-    <Droppable @drop="handleDrop">
-      <Draggable
-        v-if="elementInDropZone"
-        @end="handleEnd"
-      >
-        im in drop zone
-      </Draggable>
-    </Droppable>
-  </div>
-</template>
-```
-
-### Draggable.vue
-
-<sup>🧩 components/Draggable.vue</sup>
-
-```vue
-<script setup lang="ts">
-  import { useDraggable } from '@vue-dnd-kit/core';
-
-  const emit = defineEmits<{
-    (e: 'end'): void;
-  }>();
-
-  const { elementRef, handleDragStart, isDragging } = useDraggable({
-    events: { onEnd: () => emit('end') },
-  });
-</script>
-
-<template>
-  <div
-    ref="elementRef"
-    @pointerdown="handleDragStart"
-    :class="{ dragging: isDragging }"
-    tabindex="0"
-    role="button"
-    aria-grabbed="false"
-    :aria-pressed="isDragging"
-  >
-    <slot />
-  </div>
-</template>
-
-<style scoped>
-  .dragging {
-    opacity: 0.5;
-  }
-</style>
-```
-
-### Droppable.vue
-
-<sup>🧩 components/Droppable.vue</sup>
-
-```vue
-<script setup lang="ts">
-  import { useDroppable } from '@vue-dnd-kit/core';
-
-  const emit = defineEmits<{
-    (e: 'drop'): void;
-  }>();
-
-  const { elementRef, isOvered } = useDroppable({
-    events: { onDrop: () => emit('drop') },
-  });
-</script>
-
-<template>
-  <div
-    ref="elementRef"
-    :class="{
-      droppable: true,
-      'is-overed': isOvered,
-    }"
-    role="region"
-    aria-dropeffect="move"
-  >
-    drop here
-    <slot />
-  </div>
-</template>
-
-<style scoped>
-  .droppable {
-    width: 100px;
-    height: 100px;
-    border: 1px solid black;
-  }
-  .is-overed {
-    background-color: #f0f0f0;
-    border: 1px dashed red;
-  }
-</style>
-```
-
-## 📄 License
-
-[MIT](LICENSE) © [ZiZiGY](https://github.com/ZiZiGY)
-
----
-
-<p align="center">🎉 Congratulations on the official release! 🎉</p>
-<p align="center">Made with ❤️ for the Vue.js community</p>
+# Vue DnD Kit - Core Package
+
+[![Release](https://img.shields.io/badge/status-release-green.svg)](https://github.com/zizigy/vue-dnd-kit)
+[![npm version](https://img.shields.io/npm/v/@vue-dnd-kit/core.svg)](https://www.npmjs.com/package/@vue-dnd-kit/core)
+
+<p align="center">
+  <a href="https://zizigy.github.io/vue-dnd-kit/">
+    <img src="https://raw.githubusercontent.com/ZiZiGY/vue-dnd-kit/v2/public/logo.svg" width="400" alt="Vue Drag & Drop Logo">
+  </a>
+</p>
+
+<p align="center">
+  Core package of the Vue Drag & Drop library with composables and provider-based API.
+</p>
+
+<p align="center">
+  <a href="https://zizigy.github.io/vue-dnd-kit/" target="_blank">
+    <img src="https://img.shields.io/badge/Documentation-Visit-blue?style=flat-square" alt="Documentation">
+  </a>
+</p>
+
+<p align="center">
+  Inspired by <a href="https://dndkit.com/" target="_blank">React DnD Kit</a>, adapted for Vue.js
+</p>
+
+---
+
+## About
+
+**Vue DnD Kit** — lightweight drag & drop library for Vue 3. Built around a provider (`DnDProvider`) and composables: `makeDraggable`, `makeDroppable`, `makeSelectionArea`, `makeConstraintArea`.
+
+- **Lightweight** — small bundle size, no extra dependencies (Vue as peer only)
+- **Flexible** — works with any layout and design system
+- **Accessible** — full keyboard support (start, move, cancel, drop)
+- **TypeScript** — fully typed
+
+---
+
+## Features
+
+- **Composables API** — `makeDraggable`, `makeDroppable`, `makeSelectionArea`, `makeConstraintArea`
+- **Provider-based** — `DnDProvider` + `useDnDProvider` for state access
+- **Keyboard support** — Enter/Space for start and drop, arrows for movement, Escape to cancel
+- **Modifier keys** — drag only when modifier held (e.g. Ctrl)
+- **Custom overlay** — custom drag preview via slot or `render` option
+
+---
+
+## Installation
+
+```bash
+npm install @vue-dnd-kit/core
+```
+
+```bash
+yarn add @vue-dnd-kit/core
+```
+
+```bash
+pnpm add @vue-dnd-kit/core
+```
+
+**Peer dependency:** Vue 3
+
+---
+
+## License
+
+[MIT](LICENSE) © [ZiZiGY](https://github.com/ZiZiGY)
+
+---
+
+<p align="center">🎉 Congratulations on the official release! 🎉</p>
+<p align="center">Made with ❤️ for the Vue.js community</p>

package/dist/external/components/DefaultOverlay.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/external/components/DnDProvider.vue.d.ts

@@ -0,0 +1,25 @@
+import { IDnDProviderProps } from '../types/provider';
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        overlay?(_: {
+            overlay: import('vue').Component;
+        }): any;
+    };
+    refs: {
+        overlayRef: HTMLDivElement;
+    };
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<IDnDProviderProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<IDnDProviderProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    overlayRef: HTMLDivElement;
+}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/external/composables/makeAutoScroll.d.ts

@@ -0,0 +1,13 @@
+import { Ref } from 'vue';
+import { IAutoScrollOptions } from '../types';
+export type { IAutoScrollOptions };
+/**
+ * Auto-scroll when the drag overlay is near container edges. Element scroll only.
+ *
+ * @param container - Ref to the scrollable element
+ * @param options - threshold, speed, disabled
+ * @returns { isScrolling }
+ */
+export declare const makeAutoScroll: (container: Ref<HTMLElement | null>, options?: IAutoScrollOptions) => {
+    isScrolling: import('vue').ShallowRef<boolean, boolean>;
+};

package/dist/external/composables/makeConstraintArea.d.ts

@@ -0,0 +1,7 @@
+import { TDnDNodeRef, TDragAxis } from '../types';
+import { Ref } from 'vue';
+export interface IMakeConstraintAreaOptions {
+    axis?: TDragAxis | Ref<TDragAxis>;
+    restrictToArea?: boolean | Ref<boolean>;
+}
+export declare function makeConstraintArea(ref: TDnDNodeRef, options?: IMakeConstraintAreaOptions): {};

package/dist/external/composables/makeDraggable.d.ts

@@ -0,0 +1,19 @@
+import { IBaseOptions, IDragActivationOptions, IDraggableEvents, IModifierOptions, IPlacement, IPlacementMargins, TDnDNodeRef, TDraggablePayload } from '../types';
+import { Component, ComputedRef, Ref, WritableComputedRef } from 'vue';
+interface IMakeDraggableOptions extends IBaseOptions {
+    events?: IDraggableEvents;
+    modifier?: IModifierOptions;
+    render?: Component;
+    dragHandle?: string | Ref<string>;
+    activation?: IDragActivationOptions;
+    placementMargins?: IPlacementMargins;
+}
+interface IMakeDraggableReturnType {
+    selected: WritableComputedRef<boolean>;
+    isDragging: ComputedRef<boolean>;
+    isAllowed: ComputedRef<boolean>;
+    isDragOver: ComputedRef<IPlacement | undefined>;
+}
+export declare function makeDraggable(ref: TDnDNodeRef, payload?: TDraggablePayload): IMakeDraggableReturnType;
+export declare function makeDraggable(ref: TDnDNodeRef, options: IMakeDraggableOptions, payload?: TDraggablePayload): IMakeDraggableReturnType;
+export {};

package/dist/external/composables/makeDroppable.d.ts

@@ -0,0 +1,13 @@
+import { IBaseOptions, IDroppableEvents, IPlacement, TDnDNodeRef, TDroppablePayload } from '../types';
+import { ComputedRef } from 'vue';
+interface IMakeDroppableOptions extends IBaseOptions {
+    events?: IDroppableEvents;
+}
+interface IMakeDroppableReturnType {
+    isAllowed: ComputedRef<boolean>;
+    isDragOver: ComputedRef<IPlacement | undefined>;
+}
+export declare function makeDroppable(ref: TDnDNodeRef): IMakeDroppableReturnType;
+export declare function makeDroppable(ref: TDnDNodeRef, options: IMakeDroppableOptions, payload?: TDroppablePayload): IMakeDroppableReturnType;
+export declare function makeDroppable(ref: TDnDNodeRef, payload: TDroppablePayload): IMakeDroppableReturnType;
+export {};

package/dist/external/composables/makeSelectionArea.d.ts

@@ -0,0 +1,14 @@
+import { Ref } from 'vue';
+import { IBaseOptions, ISelectableAreaEvents, TDnDNodeRef, TModifierKeys, TModifierMethod } from '../types';
+interface ISelectionAreaOptions extends IBaseOptions {
+    modifier?: {
+        keys: TModifierKeys | Ref<TModifierKeys>;
+        method: TModifierMethod | Ref<TModifierMethod>;
+    };
+    events?: ISelectableAreaEvents;
+}
+export declare const makeSelectionArea: (nodeRef: TDnDNodeRef, options?: ISelectionAreaOptions) => {
+    isSelecting: import('vue').ComputedRef<boolean>;
+    style: import('vue').ComputedRef<import('vue').CSSProperties>;
+};
+export {};

package/dist/external/composables/makeSnappedOverlayPosition.d.ts

@@ -0,0 +1,20 @@
+import { ComputedRef } from 'vue';
+import { ICoordinates } from '@vue-dnd-kit/core';
+/** Per-axis grid (no grid = step 1, no snap) */
+export type TSnapOverlayOptions = {
+    grid: number;
+    gridX?: never;
+    gridY?: never;
+} | {
+    grid?: never;
+    gridX: number;
+    gridY: number;
+};
+/**
+ * Returns a computed that maps overlay position (x, y) to grid‑snapped coordinates.
+ * Core keeps writing raw coordinates; use this for overlay display only.
+ *
+ * @param options - grid (or gridX / gridY)
+ * @returns ComputedRef<ICoordinates> — use for --position-x / --position-y in overlay
+ */
+export declare function makeSnappedOverlayPosition(position: ComputedRef<ICoordinates>, options?: TSnapOverlayOptions): ComputedRef<ICoordinates>;

package/dist/external/composables/useDnDProvider.d.ts

@@ -0,0 +1,2 @@
+import { IDnDProviderExternal } from '../types';
+export declare const useDnDProvider: () => IDnDProviderExternal;

package/dist/external/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/dist/external/index.d.ts

@@ -0,0 +1,11 @@
+import { default as DnDProvider } from './components/DnDProvider.vue';
+export { DnDProvider };
+export { makeDraggable } from './composables/makeDraggable';
+export { makeSelectionArea } from './composables/makeSelectionArea';
+export { makeConstraintArea } from './composables/makeConstraintArea';
+export { makeDroppable } from './composables/makeDroppable';
+export { useDnDProvider } from './composables/useDnDProvider';
+export { makeAutoScroll, type IAutoScrollOptions, } from './composables/makeAutoScroll';
+export { makeSnappedOverlayPosition, type TSnapOverlayOptions, } from './composables/makeSnappedOverlayPosition';
+export { createSensor, defaultCollisionDetection, type CollisionDetectionFn, type TMergeStrategy, } from '../internal/sensors';
+export type * from './types';