### Base Drop Example Component Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/base-drop.md

Imports the main example component for the base drop functionality.

```javascript
import Example from '@examples-v2/BaseDrop/Example.vue';
```

--------------------------------

### Quick Start: Droppable Zone Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/README.md

Set up a droppable zone using `DnDProvider` and `makeDroppable`. The `onDrop` event handler uses `suggestSort` to update the items array.

```vue
<script setup lang="ts">
  import { ref, useTemplateRef } from 'vue';
  import { DnDProvider, makeDroppable } from '@vue-dnd-kit/core';
  import SortableItem from './SortableItem.vue';

  const items = ref(['One', 'Two', 'Three', 'Four']);
  const zoneRef = useTemplateRef<HTMLElement>('zone');

  makeDroppable(zoneRef, {
    events: {
      onDrop(e) {
        const r = e.helpers.suggestSort('vertical');
        if (r) items.value = r.targetItems as string[];
      },
    },
  }, () => items.value);
</script>

<template>
  <DnDProvider>
    <div ref="zone" class="list">
      <SortableItem
        v-for="(item, i) in items"
        :key="item"
        :index="i"
        :items="items"
      >
        {{ item }}
      </SortableItem>
    </div>
  </DnDProvider>
</template>
```

--------------------------------

### Vue Component Setup for Auto Scroll

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/auto-scroll.md

Imports the necessary Example component for the auto-scroll demo. This setup is typically used at the top level of a Vue component to render the interactive example.

```javascript
import Example from '@examples-v2/AutoScroll/Example.vue';
```

--------------------------------

### Install Core Package with npm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/installation.md

Install the core package using npm. Ensure you have Vue 3 and a compatible build setup.

```bash
npm install @vue-dnd-kit/core
```

--------------------------------

### Basic Draggable Element Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-draggable.md

This snippet demonstrates the basic setup for making an HTML element draggable using the makeDraggable function. It includes setting a drag handle and logging drag start and end events.

```vue
<script setup lang="ts">
  import { useTemplateRef } from 'vue';
  import { makeDraggable } from '@vue-dnd-kit/core';

  const itemRef = useTemplateRef<HTMLElement>('itemRef');

  makeDraggable(itemRef, {
    dragHandle: '.handle',
    activation: { distance: 5 },
    events: {
      onSelfDragStart: (e) => console.log('drag start', e.draggedItems),
      onSelfDragEnd: (e) => console.log('drag end', e.draggedItems),
    },
  });
</script>

<template>
  <div ref="itemRef" tabindex="0">
    <span class="handle">⋮⋮</span>
    <span>Item</span>
  </div>
</template>
```

--------------------------------

### Install Core Package

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/quick-start.md

Install the core @vue-dnd-kit/core package using npm, yarn, or pnpm.

```bash
npm install @vue-dnd-kit/core
```

```bash
yarn add @vue-dnd-kit/core
# or
pnpm add @vue-dnd-kit/core
```

--------------------------------

### Quick Start: Draggable Item Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/README.md

Make an item draggable using `makeDraggable`. The `isDragging` state can be used to control the item's opacity.

```vue
<!-- SortableItem.vue -->
<script setup lang="ts">
  import { useTemplateRef } from 'vue';
  import { makeDraggable } from '@vue-dnd-kit/core';

  const props = defineProps<{ index: number; items: string[] }>();
  const el = useTemplateRef<HTMLElement>('el');
  const { isDragging } = makeDraggable(el, {}, () => [props.index, props.items]);
</script>

<template>
  <div ref="el" :style="{ opacity: isDragging ? 0 : 1 }">
    <slot />
  </div>
</template>
```

--------------------------------

### Install Nuxt Module with pnpm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/nuxt.md

Install the Nuxt module and core package using pnpm.

```bash
pnpm add @vue-dnd-kit/nuxt @vue-dnd-kit/core
```

--------------------------------

### Droppable without Payload

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-droppable.md

This example shows a basic droppable setup that only logs the dragged items upon a drop event, without providing a specific payload.

```ts
makeDroppable(zoneRef, {
  events: { onDrop: (e) => console.log('dropped', e.draggedItems) },
});
```

--------------------------------

### Basic makeDraggable Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/promise-drop.md

A standard setup for `makeDraggable` that includes event handlers for tracking the dragging state. No special configuration is needed for Promise-based validation on the droppable side.

```typescript
import { makeDraggable } from '@vue-dnd-kit/core';
import { useTemplateRef, ref } from 'vue';

const draggableRef = useTemplateRef<HTMLElement>('draggableRef');
const isDragging = ref(false);

makeDraggable(draggableRef, {
  events: {
    onSelfDragStart() {
      isDragging.value = true;
    },
    onSelfDragEnd() {
      isDragging.value = false;
    },
    onSelfDragCancel() {
      isDragging.value = false;
    },
  },
});
```

--------------------------------

### Install Nuxt Module with npm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/nuxt.md

Install the Nuxt module and core package using npm.

```bash
npm install @vue-dnd-kit/nuxt @vue-dnd-kit/core
```

--------------------------------

### Install Nuxt Module with yarn

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/nuxt.md

Install the Nuxt module and core package using yarn.

```bash
yarn add @vue-dnd-kit/nuxt @vue-dnd-kit/core
```

--------------------------------

### Install Utilities with npm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/packages/utilities/README.md

Install the @vue-dnd-kit/utilities package using npm. Ensure you have Vue 3 and @vue-dnd-kit/core installed as peer dependencies.

```bash
npm install @vue-dnd-kit/utilities
```

--------------------------------

### Basic Usage Example

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-auto-scroll.md

Demonstrates how to use makeAutoScroll with a scrollable div, configuring threshold and speed.

```APIDOC
## Example: Basic Usage

```vue
<script setup lang="ts">
  import { ref } from 'vue';
  import { makeAutoScroll } from '@vue-dnd-kit/core';

  const listRef = ref<HTMLElement | null>(null);

  const { isScrolling } = makeAutoScroll(listRef, {
    threshold: 60,
    speed: 1.5,
  });
</script>

<template>
  <div
    ref="listRef"
    class="overflow-y-auto h-64"
    :class="{ 'scroll-active': isScrolling }"
  >
    <!-- draggable items -->
  </div>
</template>
```
```

--------------------------------

### Wiring onDrop Handler into makeDroppable

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/promise-drop.md

Integrate the Promise-returning `handleDrop` function into the `makeDroppable` setup to manage drop events. This example shows how to update a local `isOver` state and return the Promise from the `onDrop` event handler.

```typescript
import { makeDroppable } from '@vue-dnd-kit/core';
import { useTemplateRef, ref } from 'vue';

const droppableRef = useTemplateRef<HTMLElement>('droppableRef');
const isOver = ref(false);

makeDroppable(droppableRef, {
  events: {
    onEnter() {
      isOver.value = true;
    },
    onLeave() {
      isOver.value = false;
    },
    onDrop(e) {
      isOver.value = false;
      return handleDrop(e);
    },
  },
});
```

--------------------------------

### Install Vue DnD Kit

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/README.md

Install the core library using npm, yarn, or pnpm. Vue 3.5 is a peer dependency.

```bash
npm install @vue-dnd-kit/core
# or
yarn add @vue-dnd-kit/core
# or
pnpm add @vue-dnd-kit/core
```

--------------------------------

### Install Utilities with pnpm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/packages/utilities/README.md

Install the @vue-dnd-kit/utilities package using pnpm. Vue 3 and @vue-dnd-kit/core are required peer dependencies.

```bash
pnpm add @vue-dnd-kit/utilities
```

--------------------------------

### Install Core Package with pnpm

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/installation.md

Install the core package using pnpm. The library is built for Vue 3 and has no external dependencies.

```bash
pnpm add @vue-dnd-kit/core
```

--------------------------------

### Install Utilities with Yarn

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/packages/utilities/README.md

Install the @vue-dnd-kit/utilities package using Yarn. This package requires Vue 3 and @vue-dnd-kit/core as peer dependencies.

```bash
yarn add @vue-dnd-kit/utilities
```

--------------------------------

### Per-Side Thresholds Example

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-auto-scroll.md

Illustrates configuring different scroll thresholds for each side of the container.

```APIDOC
## Example: Per-Side Thresholds

```ts
makeAutoScroll(listRef, {
  threshold: { top: 80, bottom: 80, left: 0, right: 0 },
  speed: 2,
});
```
```

--------------------------------

### Install Core Package with Yarn

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/installation.md

Install the core package using yarn. This package requires Vue 3 as a peer dependency.

```bash
yarn add @vue-dnd-kit/core
```

--------------------------------

### Layout Setup with DnDProvider and DragPreview

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/packages/nuxt/README.md

Wrap your application's layout with DnDProvider and include DragPreview to enable drag and drop functionality. This setup ensures that all child components can access the necessary context for drag and drop operations.

```vue
<template>
  <DnDProvider>
    <slot />
    <DragPreview />
  </DnDProvider>
</template>
```

--------------------------------

### Accessing DnD Context with useDnDProvider

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/use-dnd-provider.md

Use `useDnDProvider` to get the current DnD context. This example shows how to react to the 'dragging' state and log pointer coordinates.

```vue
<script setup lang="ts">
  import { useDnDProvider } from '@vue-dnd-kit/core';

  const provider = useDnDProvider();

  // React to drag state
  watchEffect(() => {
    if (provider.state.value === 'dragging') {
      console.log('dragging', provider.pointer.value?.current);
    }
  });
</script>
```

--------------------------------

### Raw Rendering Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/performance.md

Configures droppable behavior and auto-scroll for the entire list container in a raw rendering scenario. This is suitable for a moderate number of items.

```typescript
import { makeDroppable, makeAutoScroll } from '@vue-dnd-kit/core';

// All N items rendered — makeDroppable on the scroll container
const el = useTemplateRef<HTMLElement>('el');
makeDroppable(el, { events: { onDrop } }, () => items.value);
makeAutoScroll(el, { threshold: 60, speed: 1.5 });
```

--------------------------------

### Virtualized Rendering Setup with VueUse

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/performance.md

Implements virtualized rendering using VueUse's `useVirtualList` to optimize performance for large lists. It configures droppable and auto-scroll behavior on the scrollable container.

```typescript
import { useVirtualList } from '@vueuse/core';

const ITEM_HEIGHT = 44;

const { list, containerProps, wrapperProps } = useVirtualList(
  toRef(props, 'items'),
  { itemHeight: ITEM_HEIGHT, overscan: 5 }
);

// containerProps.ref points to the scrollable element
makeDroppable(containerProps.ref, { events: { onDrop } }, () => props.items);
makeAutoScroll(containerProps.ref, { threshold: 60, speed: 1.5 });
```

--------------------------------

### Drag with Any Alt Key

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/modifier.md

This example configures `makeDraggable` so that a drag operation can only start if either the left or right Alt key is held down. It uses the 'some' method to check if any of the specified keys are pressed.

```typescript
// Either Alt key — drag only when Alt is held
makeDraggable(ref, {
  modifier: { keys: ['AltLeft', 'AltRight'], method: 'some' },
});
```

--------------------------------

### Snapped Overlay Component Example

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-snapped-overlay-position.md

A reusable `SnappedOverlay` component that applies a 20px grid snap to its preview content. It uses `useDnDProvider` and `makeSnappedOverlayPosition`, and applies fixed positioning styles.

```vue
<!-- SnappedOverlay.vue -->
<script setup lang="ts">
  import { type Component, computed } from 'vue';
  import {
    useDnDProvider,
    makeSnappedOverlayPosition,
  } from '@vue-dnd-kit/core';

  defineProps<{ preview: Component }>();

  const provider = useDnDProvider();
  const pos = makeSnappedOverlayPosition(provider.preview.position, {
    grid: 20,
  });

  const style = computed(() => ({
    transform: `translate3d(${pos.value.x}px, ${pos.value.y}px, 0)`,
    position: 'fixed' as const,
    top: 0,
    left: 0,
    pointerEvents: 'none' as const,
  }));
</script>

<template>
  <div :style="style">
    <component :is="preview" />
  </div>
</template>
```

--------------------------------

### Setup makeDraggable with Custom Render Component

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-render.md

Demonstrates how to configure `makeDraggable` to use a custom Vue component for the drag preview by passing `render: markRaw(MyComponent)`.

```ts
import { markRaw } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';
import TaskOverlay from './TaskOverlay.vue';

makeDraggable(itemRef, {
  render: markRaw(TaskOverlay),
  data: () => ({ id: props.id, label: props.label, priority: props.priority }),
});
```

--------------------------------

### makeDraggable with Activation Delay

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-draggable.md

Configures the drag activation to require a minimum delay (in ms) before the drag can start.

```typescript
import { makeDraggable } from "@vue-dnd-kit/core";
import { ref } from "vue";

const elementRef = ref<HTMLElement | null>(null);

makeDraggable(elementRef, {
  activation: {
    delay: 200, // 200ms delay
  },
});

```

--------------------------------

### Correct Component Structure for DnDProvider

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/patterns.md

Ensure draggable and droppable components are rendered as descendants of DnDProvider. This example shows the incorrect and correct ways to structure your Vue components.

```vue
<!-- ❌ Wrong — makeDraggable and DnDProvider in the same component -->
<script setup>
makeDraggable(ref, ...); // inject will fail
</script>
<template>
  <DnDProvider>
    <div ref="ref" />
  </DnDProvider>
</template>

<!-- ✅ Correct — split into parent + child -->
<!-- Parent.vue -->
<template>
  <DnDProvider>
    <DraggableItem />
  </DnDProvider>
</template>

<!-- DraggableItem.vue -->
<script setup>
makeDraggable(ref, ...); // inject works — this component is a child of DnDProvider
</script>
```

--------------------------------

### Draggable and Droppable Element Setup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/draggable-zone.md

Registers both `makeDraggable` and `makeDroppable` on the same element reference. The `placementMargins` option is used to define distinct zones for sorting and nesting.

```typescript
const rowRef = useTemplateRef<HTMLElement>('rowRef');

// Dual-role: edge → sort siblings; center → nest inside this node
const { isDragging, isDragOver: placement } = makeDraggable(
  rowRef,
  {
    dragHandle: '.drag-handle',
    placementMargins: { top: 12, bottom: 12 },
  },
  () => [props.index, props.siblings]
);

// Center drop fires when pointer is NOT in the edge margins
const { isDragOver: isOver } = makeDroppable(
  rowRef,
  { events: { onDrop: (e) => emit('drop', e) } },
  () => props.node.children
);
```

--------------------------------

### Visual Feedback for Allowed Drops

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/groups.md

Utilize the `isAllowed` computed ref returned by `makeDroppable` to provide visual feedback on whether a dragged item is compatible with the zone. This example combines `isAllowed` with the global drag state to show 'allowed', 'blocked', or 'idle' statuses.

```typescript
const { isAllowed } = makeDroppable(zoneRef, { groups: ['dev'] });

const provider = useDnDProvider();
const isDragging = computed(() => provider.state.value !== 'idle');

const status = computed(() => {
  if (!isDragging.value) return 'idle';
  return isAllowed.value ? 'allowed' : 'blocked';
});
```

```vue
<div :class="`zone--${status}`">
  <span v-if="status === 'allowed'">✓ drop here</span>
  <span v-else-if="status === 'blocked'">✗ wrong group</span>
</div>
```

--------------------------------

### Root Usage of VModelGroup

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/v-model-group.md

This snippet illustrates the basic setup for using the VModelGroup at the root level of the application. It requires a DnDProvider and passes the main board data array to the VModelGroup.

```vue
<DnDProvider>
  <VModelGroup
    v-model="board"
    direction="horizontal"
    group="column"
  />
</DnDProvider>
```

--------------------------------

### Vue Drag Handle Best Practice

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/mobile.md

This example demonstrates how to implement drag and drop in Vue.js where only a specific drag handle is restricted for touch gestures, allowing the rest of the card content to be scrollable.

```vue
<template>
  <div ref="itemRef" class="item">
    <!-- Only the handle is touch-restricted -->
    <span class="drag-handle">⠿</span>
    <span>Card content users can still scroll over</span>
  </div>
</template>

<script setup lang="ts">
  import { useTemplateRef } from 'vue';
  import { makeDraggable } from '@vue-dnd-kit/core';

  const itemRef = useTemplateRef<HTMLElement>('itemRef');
  makeDraggable(itemRef, { dragHandle: '.drag-handle' });
</script>

<style scoped>
  .drag-handle {
    touch-action: none;
    user-select: none;
    cursor: grab;
  }
</style>
```

--------------------------------

### Custom Render Component Example

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-render.md

A Vue component designed to be used as a custom drag preview. It reads drag state and payload data using `useDnDProvider` and `data` to display relevant information.

```vue
<script setup lang="ts">
  import { computed } from 'vue';
  import { useDnDProvider } from '@vue-dnd-kit/core';

  const { entities } = useDnDProvider();

  // Read the data() payload registered on the draggable
  const draggingData = computed(() => {
    const [node] = entities.draggingMap.keys();
    if (!node) return null;
    return entities.draggableMap.get(node)?.data?.() as {
      label: string;
      priority: string;
    } | null;
  });
</script>

<template>
  <div class="task-preview">
    📋 {{ draggingData?.label }}
    <span>{{ draggingData?.priority }}</span>
  </div>
</template>
```

--------------------------------

### Global CSS for Preview Transition

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/overlay-transition.md

Apply a CSS transition to the `.dnd-kit-preview` class for a smooth cursor-following movement effect. Use this if a slight spring feel is desired; omit the transition for responsive dragging.

```css
/* Add to your global stylesheet */
.dnd-kit-preview {
  /* Smooth cursor-following movement */
  transition: transform 0.06s linear;
}
```

--------------------------------

### Setup Drag Handle with CSS Selector

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/drag-handle.md

Configure `makeDraggable` to use a CSS selector for the drag handle. Only pointer events originating within elements matching this selector will start a drag.

```typescript
makeDraggable(itemRef, {
  dragHandle: '.drag-handle',
});
```

--------------------------------

### Vue Component with Uniform Grid Snap

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-snapped-overlay-position.md

Demonstrates using `makeSnappedOverlayPosition` with a uniform 20px grid for an overlay. Requires `useDnDProvider` and `makeSnappedOverlayPosition` imports.

```vue
<script setup lang="ts">
  import { computed } from 'vue';
  import {
    useDnDProvider,
    makeSnappedOverlayPosition,
  } from '@vue-dnd-kit/core';

  const provider = useDnDProvider();

  const snappedPosition = makeSnappedOverlayPosition(
    provider.preview.position,
    { grid: 20 }
  );

  const overlayStyle = computed(() => ({
    transform: `translate3d(${snappedPosition.value.x}px, ${snappedPosition.value.y}px, 0)`,
  }));
</script>

<template>
  <div
    v-if="provider.state.value === 'dragging'"
    :style="overlayStyle"
  >
    <component :is="provider.preview.render.value" />
  </div>
</template>
```

--------------------------------

### makeDraggable with Activation Distance

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-draggable.md

Configures the drag activation to require a minimum movement distance (in pixels) before the drag can start.

```typescript
import { makeDraggable } from "@vue-dnd-kit/core";
import { ref } from "vue";

const elementRef = ref<HTMLElement | null>(null);

makeDraggable(elementRef, {
  activation: {
    distance: 5, // 5px distance
  },
});

```

--------------------------------

### makeAutoScroll with Per-Side Thresholds

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-auto-scroll.md

Configure `makeAutoScroll` with specific thresholds for each side of the scrollable container. This example disables scrolling on the left and right sides.

```typescript
makeAutoScroll(listRef, {
  threshold: { top: 80, bottom: 80, left: 0, right: 0 },
  speed: 2,
});
```

--------------------------------

### DnDProvider with Props

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/dnd-provider.md

Configure DnDProvider with props to enable viewport auto-scrolling and teleport the drag preview to a different DOM element.

```vue
<template>
  <DnDProvider :autoScrollViewport="true" previewTo="body">
    <YourApp />
  </DnDProvider>
</template>
```

--------------------------------

### Delay Activation

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/activation.md

Sets a minimum time in milliseconds the pointer must be held down before a drag can start. This is particularly useful for improving touch interactions.

```typescript
// Hold 300ms before drag starts (good for mobile / long-press)
makeDraggable(ref, { activation: { delay: 300 } });
```

--------------------------------

### Set up DnDProvider in App.vue

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/installation.md

Wrap your application or a specific subtree with DnDProvider to enable drag and drop functionality. This component does not require global registration.

```vue
<script setup>
  import { DnDProvider } from '@vue-dnd-kit/core';
</script>

<template>
  <DnDProvider>
    <YourApp />
  </DnDProvider>
</template>
```

--------------------------------

### CSS for Swap Animations

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/swap.md

Provides CSS transitions and animations for the swap effect, including entry, exit, and move transitions, with visual cues like opacity and scaling.

```css
.swap-move {
  transition: all 0.35s cubic-bezier(0.165, 0.84, 0.44, 1);
}

.swap-enter-active, .swap-leave-active {
  transition: all 0.3s cubic-bezier(0.165, 0.84, 0.44, 1);
}

.swap-enter-from, .swap-leave-to {
  opacity: 0;
  transform: scale(0.9);
}

.swap-leave-active {
  position: absolute;
  width: 100%;
  pointer-events: none;
}
```

--------------------------------

### Per-Axis Distance Activation

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/activation.md

Configures distinct minimum pointer movement thresholds for the X and Y axes. This example only allows horizontal movement to activate the drag.

```typescript
makeDraggable(ref,
  {
    activation: {
      distance: { x: 10, y: 0 },
    },
  }
);
```

--------------------------------

### Simple Overlay Component Reference

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-overlay.md

The simplest way to specify a render component is by providing a plain imported component reference, wrapped with `markRaw`.

```typescript
import { markRaw } from 'vue';
import MyOverlay from './MyOverlay.vue';

makeDraggable(itemRef, {
  render: markRaw(MyOverlay),
});
```

--------------------------------

### Custom Preview Positioning with useDnDProvider

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/use-dnd-provider.md

Demonstrates how to use `provider.preview.position` to dynamically style a custom drag preview element. The preview is conditionally rendered when the state is 'dragging'.

```vue
<script setup lang="ts">
  import { computed } from 'vue';
  import { useDnDProvider } from '@vue-dnd-kit/core';

  const provider = useDnDProvider();

  const style = computed(() => {
    const { x, y } = provider.preview.position.value;
    return { transform: `translate3d(${x}px, ${y}px, 0)` };
  });
</script>

<template>
  <div v-if="provider.state.value === 'dragging'" :style="style" class="my-preview">
    <component :is="provider.preview.render.value" />
  </div>
</template>
```

--------------------------------

### Import DragPreview

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/drag-preview.md

Import the DragPreview component from the core library.

```typescript
import { DragPreview } from '@vue-dnd-kit/core';
```

--------------------------------

### Basic Distance Activation

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/activation.md

Sets a minimum pointer movement threshold in pixels for drag activation. Drag starts if either the X or Y axis exceeds this value.

```typescript
makeDraggable(ref, { activation: { distance: 8 } });
```

--------------------------------

### Customizing Keyboard Bindings

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/keyboard.md

Shows how to access and modify the default keyboard bindings for drag-and-drop actions using `useDnDProvider`. This includes changing keys for starting/dropping, moving, and canceling drags, as well as adjusting movement speed.

```typescript
import { useDnDProvider } from '@vue-dnd-kit/core';

const provider = useDnDProvider();

// Replace defaults
provider.keyboard.keys.forDrag = ['KeyG'];        // G to grab
provider.keyboard.keys.forDrop = ['KeyG'];        // G to drop
provider.keyboard.keys.forCancel = ['Escape'];
provider.keyboard.keys.forMove = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'];
provider.keyboard.keys.forMoveFaster = ['ShiftLeft'];

// Adjust movement speed (px per keypress)
provider.keyboard.step = 8;
provider.keyboard.moveFaster = 4; // multiplier when Shift held
```

--------------------------------

### Accessibility Attributes for Drag State

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/keyboard.md

Adds the `aria-grabbed` attribute to communicate the drag state to screen readers, enhancing accessibility. This example integrates `makeDraggable` with a button element.

```vue
<script setup lang="ts">
  import { useTemplateRef } from 'vue';
  import { makeDraggable } from '@vue-dnd-kit/core';

  const itemRef = useTemplateRef<HTMLElement>('itemRef');
  const { isDragging } = makeDraggable(itemRef);
</script>

<template>
  <button
    ref="itemRef"
    type="button"
    :aria-grabbed="isDragging"
    aria-label="Drag this item"
  >
    Drag me
  </button>
</template>
```

--------------------------------

### Registering Custom Preview Component

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/overlay-transition.md

Register the custom `TransitionOverlay` component via the `#preview` slot on the `DnDProvider` component.

```vue
<DnDProvider>
  <template #preview>
    <TransitionOverlay />
  </template>
</DnDProvider>
```

--------------------------------

### Basic Droppable with Events and Payload

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-droppable.md

This snippet demonstrates how to make an element a drop zone, including handling enter, drop, and leave events, and providing a payload with zone items and custom data. The payload is used by helper functions for sorting or swapping.

```vue
<script setup lang="ts">
  import { ref } from 'vue';
  import { useTemplateRef } from 'vue';
  import { makeDroppable } from '@vue-dnd-kit/core';

  const zoneRef = useTemplateRef<HTMLElement>('zoneRef');
  const zoneItems = ref<string[]>([]);

  makeDroppable(zoneRef, {
    events: {
      onEnter: (e) => console.log('enter', e.dropZone),
      onDrop: (e) => {
        // e.draggedItems → what we're dragging
        // e.dropZone     → where we're dropping
        // e.helpers.suggestSort() → ready-made sort result
      },
      onLeave: (e) => console.log('leave', e.dropZone),
    },
  }, () => [zoneItems.value, { id: 'main-zone' }]);
</script>

<template>
  <div ref="zoneRef" class="drop-zone">Drop here</div>
</template>
```

--------------------------------

### Using TSX for Inline Custom Render Components

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-render.md

Shows how to integrate custom render components using TSX syntax, allowing for inline definitions or passing static props directly without needing `defineComponent`.

```ts
import { markRaw } from 'vue';
import MyOverlay from './MyOverlay.vue';

// Just reference the component — no h(), no defineComponent
makeDraggable(itemRef, {
  render: markRaw(MyOverlay),
});

// Or inline with JSX if you need to bake in static props:
makeDraggable(itemRef, {
  render: markRaw(() => <MyOverlay color="blue" label={props.label} />),
});
```

--------------------------------

### makeConstraintArea with Both Restrictions

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-constraint-area.md

Combine axis and area restrictions to create a highly controlled drag environment. This example restricts movement to the 'y' axis and ensures the dragged item stays within the constraint area.

```typescript
import { makeConstraintArea } from "@dnd-kit/core";

// In your component setup
const containerRef = ref<HTMLElement | null>(null);

makeConstraintArea(containerRef, {
  axis: 'y',
  restrictToArea: true
});

```

--------------------------------

### Usage with 'select' strategy

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/selection-strategy.md

Demonstrates how to use the `makeSelectionArea` function with the 'select' strategy for live selection, where only elements currently inside the box are selected.

```typescript
const { isSelecting, style } = makeSelectionArea(el, {
  strategy: 'select',
  modifier: { keys: ['ControlLeft', 'ControlRight'], method: 'some' },
});
```

--------------------------------

### Custom Preview Component with Vue Transition

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/overlay-transition.md

Create a custom preview component using Vue's `<Transition>` for pop-in/pop-out animations. This approach uses separate CSS `scale` and `opacity` properties to avoid conflicts with the cursor-tracking `transform` property.

```vue
<!-- TransitionOverlay.vue -->
<script setup lang="ts">
  import { DragPreview } from '@vue-dnd-kit/core';
</script>

<template>
  <Transition name="preview-pop" appear>
    <DragPreview />
  </Transition>
</template>

<style>
  /* Use `scale` (not `transform`) to avoid conflict with the translate */
  .preview-pop-enter-active {
    transition: opacity 0.15s ease, scale 0.15s cubic-bezier(0.34, 1.56, 0.64, 1);
  }
  .preview-pop-leave-active {
    transition: opacity 0.1s ease, scale 0.1s ease;
  }
  .preview-pop-enter-from, .preview-pop-leave-to {
    opacity: 0;
    scale: 0.85;
  }
</style>
```

--------------------------------

### Global Preview Override using Slot

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-overlay.md

Replace the preview for the entire provider by using the `#preview` slot on the `DnDProvider` component.

```vue
<!-- Slot approach -->
<DnDProvider>
  <template #preview>
    <MyGlobalOverlay />
  </template>
</DnDProvider>
```

--------------------------------

### Custom Preview with Spring Animation

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/animation.md

Animates the drag preview on both drag start and drag end using AnimatePresence and motion-v. Wrap DragPreview in AnimatePresence to enable exit animations when the element unmounts.

```vue
<script setup lang="ts">
  import { motion, AnimatePresence } from 'motion-v';
  import { DragPreview } from '@vue-dnd-kit/core';
</script>

<template>
  <AnimatePresence mode="popLayout">
    <DragPreview v-slot="{ draggingMap }">
      <motion.div
        v-for="[node, draggable] in draggingMap"
        :key="node"
        class="preview-wrapper"
        :initial="{ scale: 0.9, opacity: 0, rotate: -2 }"
        :animate="{ scale: 1.06, opacity: 1, rotate: 1.5 }"
        :exit="{ scale: 0.9, opacity: 0, rotate: -2 }"
        :transition="{ type: 'spring', stiffness: 480, damping: 26 }"
      >
        <component v-if="draggable.render" :is="draggable.render" />
        <component
          v-else
          :is="node.tagName"
          v-html="draggable.initialOuterHTML"
          :style="{
            width: draggable.initialRect.width + 'px',
            height: draggable.initialRect.height + 'px',
          }"
        />
      </motion.div>
    </DragPreview>
  </AnimatePresence>
</template>

<style scoped>
  .preview-wrapper {
    filter: drop-shadow(0 16px 40px rgba(0, 0, 0, 0.22));
  }
</style>
```

--------------------------------

### Recursive Tree Walk (Incorrect Pattern)

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/patterns.md

This is an example of an inefficient and error-prone way to update nested tree data. It involves a recursive walk through the entire tree to find and replace arrays, leading to O(depth) complexity.

```typescript
// ❌ Recursive walk — O(depth), easy to get wrong
function applyToTree(oldArr: Node[], newArr: Node[]) {
  if (oldArr === tree.value) { tree.value = newArr; return; }
  findAndReplace(tree.value, oldArr, newArr);
}

function findAndReplace(nodes: Node[], oldArr: Node[], newArr: Node[]): boolean {
  for (const node of nodes) {
    if (node.children === oldArr) { node.children = newArr; return true; }
    if (findAndReplace(node.children, oldArr, newArr)) return true;
  }
  return false;
}
```

--------------------------------

### Asymmetric Grid Snap Configuration

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-snapped-overlay-position.md

Configures `makeSnappedOverlayPosition` for an asymmetric grid, snapping horizontally every 40px and vertically every 20px. Assumes `provider.preview.position` is available.

```typescript
const snappedPosition = makeSnappedOverlayPosition(provider.preview.position, {
  gridX: 40,
  gridY: 20,
});
```

--------------------------------

### Draggable ID for Virtual Lists

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-draggable.md

This example highlights the importance of providing a stable `id` when using makeDraggable with virtual lists to maintain element identity across remounts. It shows the incorrect and correct ways to configure the ID.

```typescript
// ❌ Without id — broken in virtual lists
makeDraggable(el, { groups: ['item'] }, () => [index, items.value])

// ✅ With id — correct in virtual lists
makeDraggable(el, { id: item.id, groups: ['item'] }, () => [index, items.value])
```

--------------------------------

### Basic Usage of makeSelectionArea

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-selection-area.md

This snippet demonstrates the basic usage of `makeSelectionArea` with a specified element reference. It enables the default 'toggle' strategy for selection.

```typescript
makeSelectionArea(el)
```

--------------------------------

### Draggable with Payload for Lists

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-draggable.md

This example shows how to provide a data payload when making an element draggable, which is useful for lists or drop handlers that need to know the item's index and the full list of items. The payload is returned as a function.

```vue
const items = ref([1, 2, 3]);
makeDraggable(itemRef, { dragHandle: '.handle' }, () => [0, items.value]);

// later in onDrop:
// e.draggedItems[0].index, e.draggedItems[0].item, e.draggedItems[0].items
```

--------------------------------

### Handle Drop for Swapping Items

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/swap.md

This function handles the drop event to perform a swap between items. It checks if an item is being hovered over and uses `suggestSwap()` to get the new list states. It updates both source and target lists if the swap is cross-list.

```typescript
function handleDrop(e: IDragEvent) {
  // Swap only makes sense when hovering over another item
  if (!e.hoveredDraggable) return;

  const r = e.helpers.suggestSwap();
  if (!r) return;

  const srcItems = e.draggedItems[0]?.items as Player[];

  // Always update the source list
  if (srcItems === teamAlpha.value) teamAlpha.value = r.sourceItems as Player[];
  else if (srcItems === teamBeta.value) teamBeta.value = r.sourceItems as Player[];

  // Cross-list swap: update the target list too
  if (!r.sameList) {
    const tgtItems = e.hoveredDraggable.items as Player[];
    if (tgtItems === teamAlpha.value) teamAlpha.value = r.targetItems as Player[];
    else if (tgtItems === teamBeta.value) teamBeta.value = r.targetItems as Player[];
  }
}
```

--------------------------------

### Chess Pawn Promotion Logic

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/chess.md

Handles the automatic promotion of pawns to queens when they reach the opposite end of the board.

```typescript
const promoted =
  piece.type === 'pawn' &&
  ((piece.color === 'white' && toRow === 0) || (piece.color === 'black' && toRow === 7));

// ...map: promoted ? 'queen' : p.type
```

--------------------------------

### Virtualized Rendering List Structure

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/performance.md

Defines the HTML structure for a virtualized list, rendering only the visible items. This significantly improves performance by reducing DOM nodes.

```html
<div v-bind="containerProps" class="virtual-list">
  <div v-bind="wrapperProps">
    <!--
      item.index is the REAL index in the full array.
      suggestSort uses it correctly even though only a window is rendered.
    -->
    <div
      v-for="{ data, index } in list"
      :key="data.id"
      :style="{ height: ITEM_HEIGHT + 'px' }"
    >
      <PerfItem :index="index" :items="props.items" :item="data" />
    </div>
  </div>
</div>
```

--------------------------------

### Usage with 'toggle' strategy

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/selection-strategy.md

Demonstrates how to use the `makeSelectionArea` function with the 'toggle' strategy for XORed selection behavior. This is the default strategy.

```typescript
const { isSelecting, style } = makeSelectionArea(el, {
  strategy: 'toggle',
  modifier: { keys: ['ControlLeft', 'ControlRight'], method: 'some' },
});
```

--------------------------------

### Making Elements Focusable

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/keyboard.md

Demonstrates two methods to make draggable elements focusable for keyboard interaction: using a native button or adding `tabindex="0"` to any element.

```vue
<!-- Option A: native button — focusable and keyboard-activated by default -->
<button ref="itemRef" type="button">Drag me</button>

<!-- Option B: any element with tabindex -->
<div ref="itemRef" tabindex="0">Drag me</div>
```

--------------------------------

### Basic makeConstraintArea Usage

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/core/make-constraint-area.md

This snippet demonstrates the basic usage of `makeConstraintArea` to define a constraint area. It requires a template ref to the container element and can optionally accept configuration options.

```typescript
import { makeConstraintArea } from "@dnd-kit/core";

// In your component setup
const containerRef = ref<HTMLElement | null>(null);

makeConstraintArea(containerRef);

```

--------------------------------

### Simplified DragPreview Logic

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/custom-render.md

Illustrates the core logic within `DragPreview` for determining whether to render a custom component or a cloned HTML element based on registered render options.

```ts
// Simplified DragPreview logic
for (const [node, draggable] of entities.draggingMap) {
  const customRender = entities.draggableMap.get(node)?.render;
  if (customRender) {
    // → renders <component :is="customRender" />
  } else {
    // → renders a clone: <div v-html="draggable.initialOuterHTML" />
  }
}
```

--------------------------------

### Snap Drag Preview to Uniform Grid

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/examples/snap-grid.md

Use the 'grid' prop with a single number to define a uniform grid for snapping. This is useful for creating consistent spacing.

```vue
<DnDProvider>
  <template #preview>
    <!-- uniform 40 × 40 px grid -->
    <DragPreview :grid="40" />
  </template>
</DnDProvider>
```

--------------------------------

### Using `items` and `data` Payloads

Source: https://github.com/zizigy/vue-dnd-kit/blob/master/docs/v2/guide/patterns.md

Demonstrates how to use the `items` argument for helper functions like `suggestSort` and the `data` option for custom application logic. The `items` argument is required for sorting helpers, while `data` provides a custom payload accessible in the drop handler.

```typescript
makeDraggable(ref, { data: () => ({ id: 'card-1', priority: 'high' }) }, () => [i, list]);

// In drop handler:
const r = e.helpers.suggestSort('vertical'); // uses items
const id = (e.draggedItems[0].data as { id: string }).id; // uses data
```