### Install @horuse/svelte-dnd package

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/getting-started/+page.md

Commands to install the library using common JavaScript package managers.

```bash
bun add @horuse/svelte-dnd
```

```bash
npm install @horuse/svelte-dnd
```

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

### Implement basic drag-and-drop list in Svelte

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/getting-started/+page.md

A complete implementation showing how to manage state, handle drag events with DragController, and render draggable components with previews.

```svelte
<script lang="ts">
    import {
        DndProvider,
        DndDroppable,
        DndDraggable,
        DndPreview,
        DragController
    } from '@horuse/svelte-dnd';
    import { onDestroy } from 'svelte';

    let items = $state([
        { id: '1', label: 'First item' },
        { id: '2', label: 'Second item' },
        { id: '3', label: 'Third item' }
    ]);

    const controller = new DragController();
    const dropPreview = $derived(controller.dropPreview);

    let hiddenId = $state<string | null>(null);
    const visibleItems = $derived(
        items.filter((item) => item.id !== hiddenId)
    );

    const unsubStart = controller.onDragStart((id) => {
        hiddenId = id;
    });
    const unsubEnd = controller.onDragEnd(() => {
        hiddenId = null;
    });

    controller.onDrop((sourceId, sourceData, targetContainerId, position) => {
        const fromIndex = items.findIndex((item) => item.id === sourceId);
        if (fromIndex === -1) return;

        const updated = [...items];
        const [moved] = updated.splice(fromIndex, 1);
        updated.splice(position, 0, moved);
        items = updated;
    });

    onDestroy(() => {
        unsubStart();
        unsubEnd();
    });
</script>

<DndProvider {controller}>
    <DndDroppable id="list" direction="vertical">
        {#each visibleItems as item, index (item.id)}
            <DndPreview
                containerId="list"
                position={index}
                show={dropPreview?.containerId === 'list'
                && dropPreview?.position === index}
            />

            <DndDraggable id={item.id}>
                {item.label}
            </DndDraggable>
        {/each}

        <DndPreview
            containerId="list"
            position={visibleItems.length}
            show={dropPreview?.containerId === 'list'
            && dropPreview?.position === visibleItems.length}
        />
    </DndDroppable>
</DndProvider>
```

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

### Basic Svelte 5 Drag and Drop Example

Source: https://github.com/horuse/svelte-dnd/blob/main/README.md

A minimal Svelte 5 example demonstrating drag-and-drop functionality using @horuse/svelte-dnd. It includes DndProvider, DndDroppable, DndDraggable, and DndPreview components to set up a reorderable list.

```svelte
<script lang="ts">
    import {
        DndProvider,
        DndDroppable,
        DndDraggable,
        DndPreview,
        DragController
    } from '@horuse/svelte-dnd';
    import { onDestroy } from 'svelte';

    let items = $state([
        { id: '1', label: 'First item' },
        { id: '2', label: 'Second item' },
        { id: '3', label: 'Third item' }
    ]);

    const controller = new DragController();
    const dropPreview = $derived(controller.dropPreview);

    // Hide the dragged item from the list during drag
    let hiddenId = $state<string | null>(null);
    const visibleItems = $derived(
        items.filter((item) => item.id !== hiddenId)
    );

    const unsubStart = controller.onDragStart((id) => {
        hiddenId = id;
    });
    const unsubEnd = controller.onDragEnd(() => {
        hiddenId = null;
    });

    controller.onDrop((sourceId, sourceData, targetContainerId, position) => {
        const fromIndex = items.findIndex((item) => item.id === sourceId);
        if (fromIndex === -1) return;

        const updated = [...items];
        const [moved] = updated.splice(fromIndex, 1);
        updated.splice(position, 0, moved);
        items = updated;
    });

    onDestroy(() => {
        unsubStart();
        unsubEnd();
    });
</script>

<DndProvider {controller}>
    <DndDroppable id="list" direction="vertical">
        {#each visibleItems as item, index (item.id)}
            <DndPreview
                containerId="list"
                position={index}
                show={dropPreview?.containerId === 'list'
                && dropPreview?.position === index}
            />

            <DndDraggable id={item.id}>
                {item.label}
            </DndDraggable>
        {/each}

        <DndPreview
            containerId="list"
            position={visibleItems.length}
            show={dropPreview?.containerId === 'list'
            && dropPreview?.position === visibleItems.length}
        />
    </DndDroppable>
</DndProvider>
```

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

### Handle Drag Start Event

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

An example of subscribing to the `onDragStart` event of the DragController. This callback is invoked when a drag operation begins, providing the ID of the item being dragged. The returned function can be used to unsubscribe.

```typescript
const unsubscribe = controller.onDragStart((itemId: string) => {
  console.log('Started dragging:', itemId);
});

// To unsubscribe later:
// unsubscribe();
```

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

### Install @horuse/svelte-dnd

Source: https://github.com/horuse/svelte-dnd/blob/main/README.md

Installs the @horuse/svelte-dnd library using npm. This is the first step to integrate drag-and-drop functionality into your Svelte 5 application.

```bash
npm install @horuse/svelte-dnd
```

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

### Style Dnd-dnd state-based classes

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/css-custom-props/+page.md

Examples of using library-provided CSS classes to style elements based on their current state, such as disabled items or the active ghost element.

```css
.dnd-draggable--disabled {
  opacity: 0.4;
  cursor: not-allowed;
}
```

```css
.dnd-ghost {
  opacity: 0.85;
  transform-origin: top left;
}

.dnd-ghost--returning {
  transition: none; /* library controls the animation */
}
```

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

### Customize Dnd-dnd appearance with CSS variables

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/css-custom-props/+page.md

Examples of overriding default drag-and-drop behavior by setting CSS custom properties on the root element or scoped containers.

```css
:root {
  --dnd-ghost-opacity: 0.6;
  --dnd-ghost-rotation: 0deg;
  --dnd-ghost-scale: 0.95;
}
```

```css
:root {
  --dnd-preview-bg: rgba(59, 130, 246, 0.1);
  --dnd-preview-border: 2px dashed rgba(59, 130, 246, 0.4);
  --dnd-preview-border-radius: 4px;
}
```

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

### Restrict Drag to Handle Element (Svelte)

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/html-attributes/+page.md

This Svelte example illustrates how to restrict the drag initiation to specific elements within a draggable component. By adding the `data-dnd-handle` attribute to elements like a header, dragging will only start when interacting with these designated handles.

```svelte
<DndDraggable id={column.id}>
  <h2 data-dnd-handle>&#x2630; Drag here</h2>
  <div>clicks here won't drag</div>
</DndDraggable>
```

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

### Enable Auto-Scroll on External Containers (HTML)

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/html-attributes/+page.md

This example demonstrates how to enable auto-scrolling for an external wrapper element that contains multiple droppable components. By adding the `data-dnd-scroll` attribute to the wrapper, the library can detect and manage scrolling within that container.

```html
<div class="scroll-wrapper" data-dnd-scroll style="overflow: auto;">
  <DndDroppable ... />
  <DndDroppable ... />
</div>
```

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

### Support Multiple Drag Handles (Svelte)

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/html-attributes/+page.md

This Svelte code demonstrates how to define multiple elements within a draggable component that can initiate a drag operation. By applying the `data-dnd-handle` attribute to each desired element (e.g., header and footer), users can start dragging from any of these specified locations.

```svelte
<DndDraggable id={item.id}>
  <header data-dnd-handle>&#x2630; Top handle</header>
  <p>content</p>
  <footer data-dnd-handle>&#x2630; Bottom handle</footer>
</DndDraggable>
```

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

### Implement DndPreview usage pattern

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/components-api/+page.md

Demonstrates the correct placement of DndPreview components within a list to indicate drop positions. Previews should be placed before each draggable item and after the final item.

```svelte
{#each items as item, index (item.id)}
    <DndPreview containerId="list" position={index} />
    <DndDraggable id={item.id}>...</DndDraggable>
{/each}

<DndPreview containerId="list" position={items.length} />
```

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

### DragController Constructor and Provider Integration

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

How to create a DragController instance and pass it to the DndProvider.

```APIDOC
## Constructor and Provider Integration

### Description
Instantiate the `DragController` and integrate it with the `DndProvider` to manage drag-and-drop functionality.

### Method
`new DragController()`

### Endpoint
N/A (Class Constructor)

### Parameters
None

### Request Example
```ts
import { DragController } from '@horuse/svelte-dnd';

const controller = new DragController();
```

### Response
#### Success Response (Instance)
- **controller** (`DragController`) - An instance of the DragController.

### Response Example
```svelte
<script>
  import { DndProvider } from '@horuse/svelte-dnd';
  import { DragController } from '@horuse/svelte-dnd';

  const controller = new DragController();
</script>

<DndProvider {controller}>
    <!-- your DnD content -->
</DndProvider>
```
```

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

### Initialize DragController

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Demonstrates how to create a new instance of the DragController. This controller manages the entire drag-and-drop state and logic. It can be created explicitly and passed to the DndProvider.

```typescript
import { DragController } from '@horuse/svelte-dnd';

const controller = new DragController();
```

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

### DragController Event Callbacks

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Documentation for event callbacks like onDragStart, onDragEnd, and onDrop.

```APIDOC
## Event Callbacks

### Description
Register callbacks to react to specific drag-and-drop events. All event methods return an unsubscribe function to clean up listeners.

### Method
`onDragStart(callback: (itemId: string) => void): () => void`
`onDragEnd(callback: (itemId: string) => void): () => void`
`onDrop(callback: (sourceId: string, sourceData: any, targetContainerId: string, position: number) => void): () => void`

### Endpoint
N/A (Event Listeners)

### Parameters
- **callback** (function) - The function to execute when the event occurs.
  - `onDragStart`: Receives the `itemId` of the dragged item.
  - `onDragEnd`: Receives the `itemId` of the dragged item.
  - `onDrop`: Receives `sourceId`, `sourceData`, `targetContainerId`, and `position`.

### Request Example
```ts
import { DragController } from '@horuse/svelte-dnd';

const controller = new DragController();

const unsubscribeDragStart = controller.onDragStart((itemId) => {
  console.log('Started dragging:', itemId);
});

controller.onDrop((sourceId, sourceData, targetContainerId, position) => {
  console.log('Dropped:', sourceId, 'into', targetContainerId, 'at position', position);
});

// To stop listening:
unsubscribeDragStart();
```

### Response
#### Success Response (Unsubscribe Function)
- **unsubscribe** (`() => void`) - A function that, when called, removes the event listener.

#### Response Example
N/A (Callbacks do not return data, but return an unsubscribe function).
```

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

### DragController Methods

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Reference for the core methods available on the DragController.

```APIDOC
## Methods

### Description
These methods provide programmatic control over the drag-and-drop lifecycle and state.

### `startDrag`

#### Description
Initiates a drag operation. Typically called internally by `DndDraggable`.

#### Method
`startDrag(element: HTMLElement, itemId: string, initialPosition: { x: number; y: number }, data?: Record<string, any>): void`

#### Parameters
- **element** (`HTMLElement`) - The DOM element being dragged.
- **itemId** (`string`) - A unique identifier for the item being dragged.
- **initialPosition** (`{ x: number; y: number }`) - The starting coordinates of the drag.
- **data** (`Record<string, any>`, optional) - Additional data associated with the dragged item.

#### Request Example
```ts
controller.startDrag(myElement, 'item-123', { x: 100, y: 150 }, { type: 'task', priority: 'high' });
```

### `updateTransform`

#### Description
Updates the position of the ghost element during a drag operation.

#### Method
`updateTransform(transform: { x: number; y: number }): void`

#### Parameters
- **transform** (`{ x: number; y: number }`) - The new x and y coordinates for the ghost element.

#### Request Example
```ts
controller.updateTransform({ x: 110, y: 160 });
```

### `updateMousePosition`

#### Description
Updates the current mouse position, used for drop zone detection and auto-scrolling.

#### Method
`updateMousePosition(mouseX: number, mouseY: number): void`

#### Parameters
- **mouseX** (`number`) - The current X coordinate of the mouse cursor.
- **mouseY** (`number`) - The current Y coordinate of the mouse cursor.

#### Request Example
```ts
controller.updateMousePosition(event.clientX, event.clientY);
```

### `performDrop`

#### Description
Executes the drop action, including animating the ghost element to the target zone.

#### Method
`performDrop(sourceId: string, sourceData: any, targetContainerId: string, position: number): void`

#### Parameters
- **sourceId** (`string`) - The ID of the item that was dragged.
- **sourceData** (`any`) - The data associated with the dragged item.
- **targetContainerId** (`string`) - The ID of the container where the item was dropped.
- **position** (`number`) - The index where the item was dropped within the target container.

#### Request Example
```ts
controller.performDrop('item-123', { type: 'task' }, 'container-abc', 2);
```

### `endDrag`

#### Description
Concludes the drag operation. By default, the ghost element animates back to its origin.

#### Method
`endDrag(shouldAnimate?: boolean): void`

#### Parameters
- **shouldAnimate** (`boolean`, optional) - If `true` (default), the ghost element animates back. If `false`, it disappears instantly.

#### Request Example
```ts
controller.endDrag(); // Animates back
controller.endDrag(false); // Disappears instantly
```

### `setSkipDropPreviewAnimation`

#### Description
Controls whether animations for `DndPreview` components are skipped. Useful for instant visual feedback during rapid UI changes.

#### Method
`setSkipDropPreviewAnimation(value: boolean): void`

#### Parameters
- **value** (`boolean`) - Set to `true` to skip animations, `false` to enable them.

#### Request Example
```ts
controller.setSkipDropPreviewAnimation(true);
```

### `toggleDebugZones`

#### Description
Toggles the visual overlay that highlights all registered drop zones. Helpful for debugging layout and drop target areas.

#### Method
`toggleDebugZones(): void`

#### Parameters
None

#### Request Example
```ts
controller.toggleDebugZones();
```

### `destroy`

#### Description
Cleans up all internal state, event listeners, and registered drop zones. This is automatically called when the `DndProvider` unmounts if it created the controller.

#### Method
`destroy(): void`

#### Parameters
None

#### Request Example
```ts
controller.destroy();
```
```

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

### DragController Transition Utilities

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Helper functions for creating custom Svelte transitions aware of the controller's animation state.

```APIDOC
## Transition Utilities

### Description
Two helper functions are exported to assist in building custom drop preview components. These functions generate Svelte transition functions that intelligently handle animation based on the controller's current state, such as skipping animations when previews need to appear instantly or using shorter durations during the ghost return animation.

### Usage
These utilities are typically used within Svelte transition directives (`in:`, `out:`) in custom preview components.

### Request Example (Conceptual)
```svelte
<script>
  import { transition } from 'svelte/transition';
  import { getTransitionFactory } from '@horuse/svelte-dnd';

  // Assuming controller is accessible
  const controller = ...;

  // Create a transition factory aware of the controller
  const previewTransition = getTransitionFactory(controller, transition.fade);
</script>

{#if showPreview}
  <div in:previewTransition out:previewTransition>
    <!-- Preview Content -->
  </div>
{/if}
```
```

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

### Configure DndProvider Component

Source: https://context7.com/horuse/svelte-dnd/llms.txt

The DndProvider wraps your application area and initializes the DragController. It supports custom ghost element rendering via Svelte snippets.

```svelte
<script lang="ts">
    import { DndProvider, DragController } from '@horuse/svelte-dnd';

    const controller = new DragController();
</script>

<DndProvider {controller}>
    {#snippet ghost({ element, data, itemId })}
        <div class="custom-ghost" style="background: {data?.color ?? '#888'};">
            {data?.label ?? itemId}
        </div>
    {/snippet}
</DndProvider>
```

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

### Initiate Drag Operation

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Shows the `startDrag` method, used to programmatically begin a drag operation. It requires the DOM element being dragged, its unique ID, its initial screen position, and optional associated data.

```typescript
controller.startDrag(
    element: HTMLElement,
    itemId: string,
    initialPosition: { x: number; y: number },
    data?: Record<string, any>
): void;
```

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

### Transition Utilities for Custom Previews

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Exports helper functions designed for creating custom drop preview components. These utilities generate Svelte transition functions that intelligently adapt to the controller's animation state, skipping animations when necessary and adjusting durations.

```typescript
// Example usage within a Svelte component for custom transitions:
// import { getTransition } from '@horuse/svelte-dnd/utils';
// const fade = getTransition(controller, { duration: 200 });
```

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

### Types and Interfaces

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Core data structures used for managing drop previews and zones.

```APIDOC
## INTERFACE DropPreview
- **containerId** (string)
- **position** (number)
- **visible** (boolean)
- **draggedElementHeight** (number, optional)
- **draggedElementWidth** (number, optional)

## INTERFACE DropZone
- **containerId** (string)
- **position** (number)
- **direction** (DndDirection)
- **itemId** (string, optional)
- **rect** (Object: { x: number, y: number, width: number, height: number })
```

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

### Verify Drop Preview Configuration in Svelte

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/faq/+page.md

Ensure the drop preview appears correctly by verifying that the `containerId` prop on `DndPreview` exactly matches the `id` prop of the target `DndDroppable`. Also, confirm the `position` prop is within the valid range of `0` to `items.length`.

```svelte
<DndDroppable id="my-list" .../>

<!-- must match exactly -->
<DndPreview containerId="my-list" position={previewIndex} />
```

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

### Svelte Multi-Container Kanban Board Implementation

Source: https://context7.com/horuse/svelte-dnd/llms.txt

This Svelte component implements a multi-container Kanban board. It uses the @horuse/svelte-dnd library to manage drag and drop operations between columns. The component handles state management for tasks within each column and updates the UI accordingly. Dependencies include @horuse/svelte-dnd and svelte.

```svelte
<script lang="ts">
    import {
        DndProvider,
        DndDroppable,
        DndDraggable,
        DndPreview,
        DragController
    } from '@horuse/svelte-dnd';
    import { onDestroy } from 'svelte';

    let columns = $state<Record<string, { id: string; label: string }[]>>({
        todo: [
            { id: '1', label: 'Research API design' },
            { id: '2', label: 'Write unit tests' }
        ],
        'in-progress': [
            { id: '3', label: 'Implement drag handler' }
        ],
        done: [
            { id: '4', label: 'Set up project' }
        ]
    });

    const columnMeta: Record<string, string> = {
        todo: 'To Do',
        'in-progress': 'In Progress',
        done: 'Done'
    };

    const controller = new DragController();
    const dropPreview = $derived(controller.dropPreview);

    let hiddenId = $state<string | null>(null);

    function getVisibleItems(items: { id: string; label: string }[]) {
        return items.filter((item) => item.id !== hiddenId);
    }

    const unsubStart = controller.onDragStart((id: string) => {
        hiddenId = id;
    });
    const unsubEnd = controller.onDragEnd(() => {
        hiddenId = null;
    });

    controller.onDrop((sourceId: string, _sourceData: any, targetContainerId: string, position: number) => {
        // Find source column and index
        let sourceColumn = '';
        let sourceIndex = -1;

        for (const [colId, colItems] of Object.entries(columns)) {
            const idx = colItems.findIndex((item) => item.id === sourceId);
            if (idx !== -1) {
                sourceColumn = colId;
                sourceIndex = idx;
                break;
            }
        }

        if (sourceIndex === -1) return;

        // Move item between columns
        const updated = { ...columns };
        updated[sourceColumn] = [...updated[sourceColumn]];
        updated[targetContainerId] = sourceColumn === targetContainerId
            ? updated[targetContainerId]
            : [...updated[targetContainerId]];

        const [moved] = updated[sourceColumn].splice(sourceIndex, 1);
        updated[targetContainerId].splice(position, 0, moved);
        columns = updated;
    });

    onDestroy(() => {
        unsubStart();
        unsubEnd();
    });
</script>

<DndProvider {controller}>
    <div class="flex gap-4 overflow-x-auto p-4">
        {#each Object.entries(columns) as [columnId, columnItems] (columnId)}
            {@const visible = getVisibleItems(columnItems)}
            <div class="w-72 shrink-0 bg-gray-100 rounded-lg">
                <h2 class="text-lg p-4 font-semibold">{columnMeta[columnId]}</h2>
                <DndDroppable id={columnId} direction="vertical" class="space-y-2 p-3 min-h-32">
                    {#each visible as item, index (item.id)}
                        <DndPreview
                            containerId={columnId}
                            position={index}
                            show={dropPreview?.containerId === columnId && dropPreview?.position === index}
                        />
                        <DndDraggable id={item.id}>
                            <div class="p-3 bg-white rounded shadow">{item.label}</div>
                        </DndDraggable>
                    {/each}
                    <DndPreview
                        containerId={columnId}
                        position={visible.length}
                        show={dropPreview?.containerId === columnId && dropPreview?.position === visible.length}
                    />
                </DndDroppable>
            </div>
        {/each}
    </div>
</DndProvider>

```

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

### Drop Zone Management Methods

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Provides an overview of methods used for managing drop zones, primarily internally by `DndDroppable`. These include registering zones, calculating their positions, merging new zones, refreshing the set, and managing associated data.

```typescript
// Register all drop zones
controller.registerDropZones(zones);

// Calculate zones for a container
controller.calculateDropZones(containerId, element, direction?);

// Merge new zones into existing set
controller.mergeDropZones(existing, newZones, containerId);

// Recalculate all drop zones
controller.refreshDropZones();

// Register container data
controller.registerDroppableData(id, data);

// Unregister container data
controller.unregisterDroppableData(id);
```

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

### Implement DndDroppable Containers

Source: https://context7.com/horuse/svelte-dnd/llms.txt

Defines drop zones with support for layout orientation, type-based filtering, and disabled states.

```svelte
<DndDroppable id="vertical-list" direction="vertical" class="space-y-2">
    <!-- Content -->
</DndDroppable>

<DndDroppable id="tasks" data={{ accepts: 'task' }}>
    <!-- Only task-type items -->
</DndDroppable>

<DndDroppable id="archived" disabled={true}>
    <!-- Disabled container -->
</DndDroppable>
```

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

### Implement DndDraggable with interaction controls

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/components-api/+page.md

Demonstrates how to use DndDraggable with specific interaction modifiers. Shows how to exclude elements from triggering drag using data-dnd-no-drag or restrict dragging to specific handles using data-dnd-handle.

```svelte
<DndDraggable class="drag-item" id={task.id} data={{ type: 'task' }}>
    <button data-dnd-no-drag onclick={() => alert("Test")}>Alert</button>
    {task.label}
</DndDraggable>

<DndDraggable id={column.id} data={{ type: 'column' }}>
    <h2 data-dnd-handle>&#x2630; {column.title}</h2>
    <div><!-- clicking here won't drag the column --></div>
</DndDraggable>
```

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

### Pass DragController to DndProvider

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Shows how to integrate a manually created DragController with the DndProvider component. This allows direct access to the controller's methods and reactive state within the provider's children.

```svelte
<script>
    import { DndProvider } from '@horuse/svelte-dnd';
    import { DragController } from '@horuse/svelte-dnd';

    const controller = new DragController();
</script>

<DndProvider {controller}>
    <!-- your DnD content -->
</DndProvider>
```

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

### Handle Drop Event

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Illustrates the usage of the `onDrop` event callback, which is crucial for managing item reordering or movement between containers. It provides details about the source item, its data, the target container, and the drop position.

```typescript
controller.onDrop((sourceId, sourceData, targetContainerId, position) => {
    // sourceId: ID of the dragged item
    // sourceData: data attached to the dragged item
    // targetContainerId: ID of the container where item was dropped
    // position: index within the target container
    console.log('Dropped:', sourceId, 'to', targetContainerId, 'at position', position);
});
```

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

### Skip Drop Preview Animation

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Use `setSkipDropPreviewAnimation` to control whether animations for `DndPreview` components are shown. Setting this to `true` makes previews appear or disappear instantly, which is useful in scenarios like rapid container switching.

```typescript
controller.setSkipDropPreviewAnimation(value: boolean): void;
```

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

### Toggle Debug Zones Visualization

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

The `toggleDebugZones` method provides a visual overlay of all registered drop zones on the screen. This is an invaluable tool during development for verifying drop zone boundaries and behavior.

```typescript
controller.toggleDebugZones(): void;
```

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

### createConditionalScale

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Creates a Svelte scale-based transition function that adjusts duration based on controller state.

```APIDOC
## FUNCTION createConditionalScale

### Description
Returns a Svelte `scale`-based transition function. It dynamically adjusts duration based on the `controller` state: 0ms if `skipDropPreviewAnimation` is true, 100ms if `animatingReturn` is true, or default options otherwise.

### Parameters
- **controller** (Object) - Required - The drag-and-drop controller instance.

### Request Example
```ts
import { createConditionalScale } from '@horuse/svelte-dnd';
const scale = createConditionalScale(controller);
```
```

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

### DragController Reactive Getters

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Overview of the reactive getters available on the DragController for observing drag-and-drop state.

```APIDOC
## Reactive Getters

### Description
These getters provide reactive access to the current state of the drag-and-drop operation. They are designed to be used within Svelte components, leveraging Svelte 5's reactivity system.

### Method
N/A (Getters)

### Endpoint
N/A

### Parameters
None

### Request Example
```svelte
<script>
  import { DragController } from '@horuse/svelte-dnd';
  
  const controller = new DragController();
  // Assume controller is passed to DndProvider

  $: isDragging = controller.dragging;
  $: draggedItemId = controller.draggedItem;
</script>

{#if isDragging}
  <p>Currently dragging item: {draggedItemId}</p>
{/if}

```

```APIDOC
### Getter Details

| Getter | Type | Description |
|---|---|---|
| `dragging` | `boolean` | Whether a drag is currently in progress |
| `element` | `HTMLElement | null` | The DOM element being dragged |
| `transform` | `{ x: number; y: number } | null` | Current ghost position |
| `draggedItem` | `string | null` | ID of the item being dragged |
| `draggedType` | `string | null` | Type of the dragged item (from `data.type`) |
| `draggedItemData` | `Record<string, any> | undefined` | Data attached to the dragged item |
| `size` | `{ width: number; height: number } | null` | Size of the dragged element |
| `animatingReturn` | `boolean` | Whether the ghost is animating back to origin |
| `dropPreview` | `DropPreview | null` | Current drop preview state |
| `dropZones` | `DropZone[]` | All registered drop zones |
| `filteredDropZones` | `DropZone[]` | Drop zones filtered by the dragged item's type |
| `debugZones` | `boolean` | Whether debug zone visualization is enabled |
| `performingDrop` | `boolean` | Whether a drop animation is in progress |
| `skipDropPreviewAnimation` | `boolean` | Whether preview animations are skipped |
```

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

### createConditionalSlide

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Creates a Svelte slide-based transition function that adjusts duration based on controller state.

```APIDOC
## FUNCTION createConditionalSlide

### Description
Returns a Svelte `slide`-based transition function. It dynamically adjusts duration based on the `controller` state: 0ms if `skipDropPreviewAnimation` is true, 200ms if `animatingReturn` is true, or default options otherwise.

### Parameters
- **controller** (Object) - Required - The drag-and-drop controller instance.

### Request Example
```ts
import { createConditionalSlide } from '@horuse/svelte-dnd';
const slide = createConditionalSlide(controller);
```
```

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

### Create DndDraggable Items

Source: https://context7.com/horuse/svelte-dnd/llms.txt

Wraps elements to make them draggable, supporting data payloads, drag handles, and no-drag zones for interactive children.

```svelte
<DndDraggable id="card-1" data={{ type: 'card' }}>
    <div class="card">
        <button data-dnd-no-drag>Click me</button>
    </div>
</DndDraggable>

<DndDraggable id="column-1">
    <div class="column">
        <h2 data-dnd-handle>Drag here</h2>
    </div>
</DndDraggable>
```

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

### Implement DndPreview for drop indicators in Svelte

Source: https://context7.com/horuse/svelte-dnd/llms.txt

The DndPreview component renders a placeholder to indicate drop positions. It requires a containerId and position, and is typically placed before and after draggable items to support both vertical and horizontal layouts.

```svelte
<script lang="ts">
    import { DndDroppable, DndDraggable, DndPreview, DragController } from '@horuse/svelte-dnd';

    const controller = new DragController();
    const dropPreview = $derived(controller.dropPreview);

    let items = $state([
        { id: '1', label: 'Item 1' },
        { id: '2', label: 'Item 2' },
        { id: '3', label: 'Item 3' }
    ]);
</script>

<DndDroppable id="list" direction="vertical">
    {#each items as item, index (item.id)}
        <DndPreview
            containerId="list"
            position={index}
            show={dropPreview?.containerId === 'list' && dropPreview?.position === index}
        />
        <DndDraggable id={item.id}>
            <div class="drag-item">{item.label}</div>
        </DndDraggable>
    {/each}

    <DndPreview
        containerId="list"
        position={items.length}
        show={dropPreview?.containerId === 'list' && dropPreview?.position === items.length}
    />
</DndDroppable>
```

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

### DragController Drop Zone Management

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Utilities for managing drop zones, primarily used internally by DndDroppable.

```APIDOC
## Drop Zone Management

### Description
These methods are primarily used internally by the `DndDroppable` component to manage the registration and calculation of drop zones. They can be utilized directly for advanced customization scenarios.

### Method Details

| Method | Description |
|---|---|
| `registerDropZones(zones)` | Registers a set of drop zones with the controller. |
| `calculateDropZones(containerId, element, direction?)` | Computes the bounding boxes and properties of drop zones within a specific container. |
| `mergeDropZones(existing, newZones, containerId)` | Integrates newly calculated drop zones with an existing set for a container. |
| `refreshDropZones()` | Recalculates all registered drop zones, useful after layout changes. |
| `registerDroppableData(id, data)` | Associates data with a specific droppable container ID. |
| `unregisterDroppableData(id)` | Removes the data associated with a droppable container ID. |

### Request Example (Conceptual)
```ts
// Example of registering drop zones (internal usage)
const newZones = controller.calculateDropZones('my-container', containerElement);
controller.registerDropZones(newZones);

// Example of registering data for a container
controller.registerDroppableData('my-container', { items: [...] });
```
```

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

### Perform Drop with Animation

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

The `performDrop` method triggers the visual drop animation to the target location. It requires the source item's ID and data, the target container's ID, and the final position within that container.

```typescript
controller.performDrop(
    sourceId: string,
    sourceData: any,
    targetContainerId: string,
    position: number
): void;
```

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

### Nested Sortable Containers with Type Filtering in Svelte

Source: https://context7.com/horuse/svelte-dnd/llms.txt

This Svelte component demonstrates a nested drag-and-drop interface using the @horuse/svelte-dnd library. It allows for reordering of columns and moving of tasks between columns, with type filtering to enforce drop rules. Dependencies include the svelte-dnd library. It manages state for columns and tasks, handles drag start/end events, and processes drop events to update the UI.

```svelte
<script lang="ts">
    import {
        DndProvider,
        DndDroppable,
        DndDraggable,
        DndPreview,
        DragController
    } from '@horuse/svelte-dnd';
    import {onDestroy } from 'svelte';

    type Task = { id: string; label: string };
    type Column = { id: string; title: string; tasks: Task[] };

    let columns = $state<Column[]>([
        { id: 'backlog', title: 'Backlog', tasks: [
            { id: 't1', label: 'Research API design' },
            { id: 't2', label: 'Write migration scripts' }
        ]},
        { id: 'in-progress', title: 'In Progress', tasks: [
            { id: 't3', label: 'Implement auth flow' }
        ]}
    ]);

    const controller = new DragController();
    const dropPreview = $derived(controller.dropPreview);

    let hiddenId = $state<string | null>(null);
    let draggedType = $state<string | null>(null);

    // Filter columns when dragging a column
    const visibleColumns = $derived(
        draggedType === 'column'
            ? columns.filter((col) => col.id !== hiddenId)
            : columns
    );

    // Filter tasks when dragging a task
    function getVisibleTasks(tasks: Task[]) {
        if (draggedType === 'task') {
            return tasks.filter((t) => t.id !== hiddenId);
        }
        return tasks;
    }

    const unsubStart = controller.onDragStart((id: string) => {
        hiddenId = id;
        draggedType = controller.draggedType; // 'column' or 'task'
    });
    const unsubEnd = controller.onDragEnd(() => {
        hiddenId = null;
        draggedType = null;
    });

    controller.onDrop((sourceId: string, sourceData: any, targetContainerId: string, position: number) => {
        if (sourceData.type === 'column') {
            // Reorder columns
            const fromIndex = columns.findIndex((col) => col.id === sourceId);
            if (fromIndex === -1) return;

            const updated = [...columns];
            const [moved] = updated.splice(fromIndex, 1);
            updated.splice(position, 0, moved);
            columns = updated;
        } else {
            // Move task between columns
            let sourceColIndex = -1;
            let sourceTaskIndex = -1;

            for (let i = 0; i < columns.length; i++) {
                const idx = columns[i].tasks.findIndex((t) => t.id === sourceId);
                if (idx !== -1) {
                    sourceColIndex = i;
                    sourceTaskIndex = idx;
                    break;
                }
            }

            if (sourceColIndex === -1) return;

            const updated = columns.map((col) => ({
                ...col,
                tasks: [...col.tasks]
            }));

            const [movedTask] = updated[sourceColIndex].tasks.splice(sourceTaskIndex, 1);
            const targetCol = updated.find((col) => col.id === targetContainerId);
            if (targetCol) {
                targetCol.tasks.splice(position, 0, movedTask);
            }
            columns = updated;
        }
    });

    onDestroy(() => {
        unsubStart();
        unsubEnd();
    });
</script>

<DndProvider {controller}>
    <!-- Board container: only accepts columns -->
    <DndDroppable id="board" direction="horizontal" data={{ accepts: 'column' }} class="flex gap-4">
        {#each visibleColumns as column, colIndex (column.id)}
            <DndPreview
                containerId="board"
                position={colIndex}
                direction="horizontal"
                show={dropPreview?.containerId === 'board' && dropPreview?.position === colIndex}
            />
            <!-- Column: draggable with drag handle -->
            <DndDraggable id={column.id} data={{ type: 'column' }} class="w-72 bg-gray-100 rounded-lg">
                <h2 data-dnd-handle class="p-4 cursor-grab">
                    &#x2630; {column.title}
                </h2>
                <!-- Task container: only accepts tasks -->
                <DndDroppable id={column.id} direction="vertical" data={{ accepts: 'task' }} class="p-3 space-y-2">
                    {@const visible = getVisibleTasks(column.tasks)}
                    {#each visible as task, taskIndex (task.id)}
                        <DndPreview
                            containerId={column.id}
                            position={taskIndex}
                            show={dropPreview?.containerId === column.id && dropPreview?.position === taskIndex}
                        />
                        <DndDraggable id={task.id} data={{ type: 'task' }} class="p-3 bg-white rounded shadow">
                            <span>{task.label}</span>
                            <button data-dnd-no-drag onclick={() => alert('Clicked!')}>Action</button>
                        </DndDraggable>
                    {/each}
                </DndDroppable>
            </DndDraggable>
        {/each}
    </DndDroppable>
</DndProvider>

```

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

### Debug Drop Zones in Svelte

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/faq/+page.md

To visualize the boundaries of drop zones, call the `controller.toggleDebugZones()` method. This will overlay blue areas on all active drop zones, allowing you to verify their hit areas.

```javascript
<button onclick={() => controller.toggleDebugZones()}>
  Toggle debug zones
</button>
```

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

### Create Custom Ghost Element in Svelte

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/faq/+page.md

Customize the appearance of the ghost element during drag by passing a `ghost` snippet to `DndProvider`. This snippet receives `{ element, data, itemId }` as props, allowing you to define its content and style.

```svelte
<DndProvider {controller}>
  {#snippet ghost({ element, data })}
    <div class="my-ghost">
      {data.label}
    </div>
  {/snippet}

  <!-- your droppables here -->
</DndProvider>
```

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

### Manage drag-and-drop state with DragController

Source: https://context7.com/horuse/svelte-dnd/llms.txt

The DragController class provides a reactive engine for managing drag operations. It exposes state getters, event callbacks for lifecycle hooks, and methods for handling drops and debugging.

```svelte
<script lang="ts">
    import { DndProvider, DragController } from '@horuse/svelte-dnd';
    import { onDestroy } from 'svelte';

    const controller = new DragController();

    const dropPreview = $derived(controller.dropPreview);
    const isDragging = $derived(controller.dragging);

    const unsubStart = controller.onDragStart((itemId: string) => {
        console.log('Drag started:', itemId);
    });

    controller.onDrop((sourceId, sourceData, targetContainerId, position) => {
        console.log(`Dropped ${sourceId} into ${targetContainerId} at position ${position}`);
    });

    onDestroy(() => {
        unsubStart();
    });
</script>

<DndProvider {controller}>
    <!-- Drag-and-drop content -->
</DndProvider>
```

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

### Update Mouse Position

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

This method, `updateMousePosition`, is used to track the current cursor coordinates. This information is vital for accurate drop zone detection and enabling auto-scrolling behavior when the cursor nears container edges.

```typescript
controller.updateMousePosition(mouseX: number, mouseY: number): void;
```

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

### TypeScript Interfaces for Svelte DND

Source: https://context7.com/horuse/svelte-dnd/llms.txt

The library exports TypeScript interfaces to ensure type-safe development and provide full IDE support. These interfaces define the structure for drag events, drop events, drop zones, and preview states.

```typescript
import type {
    DndDirection,
    DndDragEvent,
    DndDropEvent,
    DropZone,
    DropPreview,
    GhostSnippetProps
} from '@horuse/svelte-dnd';

// Direction for layouts
type DndDirection = 'vertical' | 'horizontal' | 'grid';

// Event fired during drag operations
interface DndDragEvent {
    source: {
        id: string;
        element: HTMLElement;
        data?: Record<string, any>;
    };
    target?: {
        id: string;
        element: HTMLElement;
        data?: Record<string, any>;
    } | null;
    transform: { x: number; y: number };
}

// Event fired on drop
interface DndDropEvent {
    source: {
        id: string;
        element: HTMLElement;
        data?: Record<string, any>;
    };
    target: {
        id: string;
        element: HTMLElement;
        data?: Record<string, any>;
    } | null;
}

// Drop zone information
interface DropZone {
    containerId: string;
    position: number;
    direction: DndDirection;
    itemId?: string;
    rect: { x: number; y: number; width: number; height: number };
}

// Current drop preview state
interface DropPreview {
    containerId: string;
    position: number;
    visible: boolean;
    draggedElementHeight?: number;
    draggedElementWidth?: number;
}

// Props for custom ghost snippets
interface GhostSnippetProps {
    element: HTMLElement;
    data?: Record<string, any>;
    itemId: string;
}
```

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

### Drag and Drop Type Definitions

Source: https://github.com/horuse/svelte-dnd/blob/main/src/routes/docs/drag-controller-api/+page.md

Defines the core interfaces and types for drop previews and drop zones within the drag-and-drop system. These types ensure type safety for element positioning and layout calculations.

```typescript
interface DropPreview {
    containerId: string;
    position: number;
    visible: boolean;
    draggedElementHeight?: number;
    draggedElementWidth?: number;
}

interface DropZone {
    containerId: string;
    position: number;
    direction: DndDirection;
    itemId?: string;
    rect: { x: number; y: number; width: number; height: number };
}

type DndDirection = 'vertical' | 'horizontal';
```