===============
LIBRARY RULES
===============
From library maintainers:
- Always import from '@thisux/sveltednd' not from internal paths
- Use Svelte 5 runes ($state, $effect) not legacy stores
- draggable and droppable are Svelte actions used with use: directive
- For grid/flex-wrap layouts set direction: 'grid' on droppable
- Import '@thisux/sveltednd/dnd.css' for drop position indicator styles

### Install @thisux/sveltednd

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Installation commands for various package managers.

```bash
npm install @thisux/sveltednd
# or
bun add @thisux/sveltednd
# or
yarn add @thisux/sveltednd
# or
pnpm add @thisux/sveltednd
```

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

### Initialize Project Environment

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Clone the repository and install dependencies to begin development.

```bash
git clone https://github.com/thisuxhq/sveltednd.git
cd sveltednd
bun install
```

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

### Installation

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Install the @thisux/sveltednd package using your preferred package manager.

```APIDOC
## Installation

Install the package from npm using your preferred package manager.

```bash
npm install @thisux/sveltednd
# or
bun add @thisux/sveltednd
# or
yarn add @thisux/sveltednd
# or
pnpm add @thisux/sveltednd
```
```

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

### Kanban Board Example

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Demonstrates a Kanban board with multiple containers (columns) for different task statuses. The handleDrop function updates the card's status based on the target container.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Card {
	id: string;
	title: string;
	status: 'todo' | 'in-progress' | 'done';
	}

	let cards = $state<Card[]>([
		{ id: '1', title: 'Task A', status: 'todo' },
		{ id: '2', title: 'Task B', status: 'in-progress' },
		{ id: '3', title: 'Task C', status: 'done' }
	]);

	const columns = ['todo', 'in-progress', 'done'] as const;

	function handleDrop(state: DragDropState<Card>) {
		const { draggedItem, targetContainer } = state;
		if (!targetContainer) return;

		cards = cards.map((c) =>
			c.id === draggedItem.id ? { ...c, status: targetContainer as Card['status'] } : c
		);
	}
</script>

<div class="board">
	{#each columns as column}
		<div use:droppable={{ container: column, callbacks: { onDrop: handleDrop } }} class="column">
			<h3>{column}</h3>
			{#each cards.filter((c) => c.status === column) as card (card.id)}
				<div use:draggable={{ container: column, dragData: card }} class="card">
					{card.title}
				</div>
			{/each}
		</div>
	{/each}
</div>
```

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

### Drag Handle Pattern Example

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

This example demonstrates the Drag Handle pattern, where dragging is initiated only by a specific element (e.g., a grip icon), allowing other parts of the draggable item to remain interactive.

```APIDOC
## Drag Handle Pattern

Use the `handle` option to restrict drag initiation to a specific element. This enables patterns where only a grip icon or handle starts the drag, keeping the rest of the content interactive (text remains selectable, buttons remain clickable).

### Svelte Component Example

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Item {
		id: string;
		title: string;
		description: string;
	}

	let items = $state<Item[]>([
		{ id: '1', title: 'Review PRs', description: 'Check open pull requests' },
		{ id: '2', title: 'Update docs', description: 'Add new API examples' },
		{ id: '3', title: 'Fix bug', description: 'Users unable to reset password' }
	]);

	function handleDrop(state: DragDropState<Item>) {
		const { draggedItem, targetContainer, dropPosition } = state;
		const dragIndex = items.findIndex((item) => item.id === draggedItem.id);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex += 1;

		if (dragIndex !== -1 && !isNaN(dropIndex)) {
			const [item] = items.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			items.splice(adjusted, 0, item);
		}
	}
</script>

{#each items as item, index (item.id)}
	<div
		use:draggable={{
			container: index.toString(),
			dragData: item,
			handle: '.drag-handle' // Only the grip icon starts dragging
		}}
		use:droppable={{
			container: index.toString(),
			callbacks: { onDrop: handleDrop }
		}}
		class="list-item"
	>
		<!-- Drag handle - only this element initiates drag -->
		<button class="drag-handle" aria-label="Drag to reorder">
			<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
				<circle cx="9" cy="5" r="1.5" />
				<circle cx="15" cy="5" r="1.5" />
				<circle cx="9" cy="12" r="1.5" />
				<circle cx="15" cy="12" r="1.5" />
				<circle cx="9" cy="19" r="1.5" />
				<circle cx="15" cy="19" r="1.5" />
			</svg>
		</button>

		<!-- Text remains selectable -->
		<div class="content">
			<h3>{item.title}</h3>
			<p>{item.description}</p>
		</div>
	</div>
{/each}

<style>
	.drag-handle {
		cursor: grab;
	}
	.drag-handle:active {
		cursor: grabbing;
	}
</style>
```
```

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

### Commit Message Examples

Source: https://github.com/thisuxhq/sveltednd/blob/main/AGENTS.md

Examples of valid commit messages following the specified format. These messages indicate the type of change and a brief description.

```git commit
feat: add keyboard drag support
```

```git commit
fix: prevent stuck drag state on mobile
```

```git commit
docs: update README with touch examples
```

```git commit
chore: bump dependencies
```

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

### Implement Drag and Drop in Svelte

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

A complete example showing how to use draggable and droppable actions with Svelte 5 state.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	let items = $state(['Item 1', 'Item 2', 'Item 3']);

	function handleDrop(state: DragDropState<string>) {
		const { draggedItem, sourceContainer, targetContainer, dropPosition } = state;

		// Simple reordering logic
		const dragIndex = items.indexOf(draggedItem);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex++;

		if (dragIndex !== -1) {
			const [item] = items.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			items.splice(adjusted, 0, item);
		}
	}
</script>

{#each items as item, index (item)}
	<div
		use:draggable={{ container: index.toString(), dragData: item }}
		use:droppable={{ container: index.toString(), callbacks: { onDrop: handleDrop } }}
	>
		{item}
	</div>
{/each}
```

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

### Svelte Draggable and Droppable Example

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Example of using the `draggable` and `droppable` actions in a Svelte component to manage a list of tasks. The `handleDrop` function reorders the tasks based on drop position.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Task {
		id: string;
		title: string;
		description: string;
	}

	let tasks = $state<Task[]>([
		{ id: '1', title: 'Design review', description: 'Review new UI mockups' },
		{ id: '2', title: 'Code review', description: 'Check pull requests' },
		{ id: '3', title: 'Deploy', description: 'Push to production' }
	]);

	function handleDrop(state: DragDropState<Task>) {
		const { draggedItem, targetContainer, dropPosition } = state;
		const dragIndex = tasks.findIndex((task) => task.id === draggedItem.id);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex += 1;

		if (dragIndex !== -1 && !isNaN(dropIndex)) {
			const [task] = tasks.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			tasks.splice(adjusted, 0, task);
		}
	}
</script>

{#each tasks as task, index (task.id)}
	<div
		use:draggable={{
			container: index.toString(),
			dragData: task,
			callbacks: {
				onDragStart: (state) => console.log('Started dragging:', state.draggedItem.title),
				onDragEnd: (state) => console.log('Finished dragging')
			}
		}}
		use:droppable={{
			container: index.toString(),
			callbacks: { onDrop: handleDrop }
		}}
		class="task-item"
	>
		<h3>{task.title}</h3>
		<p>{task.description}</p>
	</div>
{/each}

<style>
	:global(.dragging) {
		opacity: 0.5;
		outline: 1px solid #0a0a0a;
	}
</style>
```

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

### Implement Svelte actions pattern

Source: https://github.com/thisuxhq/sveltednd/blob/main/AGENTS.md

Standard structure for Svelte actions, including setup, update, and destroy lifecycle methods.

```typescript
export function actionName<T>(node: HTMLElement, options: Options<T>) {
	// Setup logic
	function handleEvent(event: Event) {}

	node.addEventListener('event', handleEvent);

	return {
		update(newOptions: Options<T>) {
			options = newOptions;
		},
		destroy() {
			node.removeEventListener('event', handleEvent);
		}
	};
}
```

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

### Sortable List Example

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Implements a sortable list where items can be reordered within the same container. The handleDrop function updates the tasks array based on the drop state.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Task {
	id: string;
	title: string;
	}

	let tasks = $state<Task[]>([
		{ id: '1', title: 'Design review' },
		{ id: '2', title: 'Code review' },
		{ id: '3', title: 'Deploy to prod' }
	]);

	function handleDrop(state: DragDropState<Task>) {
		const { draggedItem, targetContainer, dropPosition } = state;
		const dragIndex = tasks.findIndex((t) => t.id === draggedItem.id);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex++;

		if (dragIndex !== -1) {
			const [task] = tasks.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			tasks.splice(adjusted, 0, task);
		}
	}
</script>

<div class="task-list">
	{#each tasks as task, index (task.id)}
		<div
			use:draggable={{ container: index.toString(), dragData: task }}
			use:droppable={{ container: index.toString(), callbacks: { onDrop: handleDrop } }}
			class="task-item"
		>
			{task.title}
		</div>
	{/each}
</div>
```

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

### Run Project Commands

Source: https://github.com/thisuxhq/sveltednd/blob/main/CLAUDE.md

Common CLI commands for development, building, testing, and linting the library.

```bash
bun run dev                # Dev server
bun run build              # Production build (vite build + svelte-package + publint)
bun run package            # Package library only
bun run check              # Type-check (svelte-check)
bun run lint               # Prettier check + ESLint
bun run format             # Auto-format with Prettier
bun run test               # Run all tests once (vitest --run)
bun run test:unit          # Tests in watch mode
bun run test:unit -- --run src/lib/actions/draggable.spec.ts  # Single test file
```

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

### Execute project build, lint, and test commands

Source: https://github.com/thisuxhq/sveltednd/blob/main/AGENTS.md

Use these Bun scripts for development, building, code quality checks, and testing.

```bash
# Development
bun run dev              # Start dev server

# Building
bun run build            # Build library for production (vite build + package)
bun run package          # Create package with svelte-package + publint

# Code Quality
bun run check            # Type-check with svelte-check
bun run check:watch      # Type-check in watch mode
bun run lint             # Run Prettier check + ESLint
bun run format           # Format with Prettier (write)

# Testing
bun run test             # Run all tests once (vitest --run)
bun run test:unit        # Run tests in watch mode
bun run test:unit -- --run src/lib/actions/draggable.spec.ts   # Single test file
```

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

### Run Tests

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Execute the test suite to verify changes.

```bash
bun run test
```

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

### Format and Lint Code

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Run project-standard formatting and linting tools.

```bash
bun run format
bun run lint
```

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

### Kanban Board (Multi-Column) with sveltednd

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Create a multi-column Kanban board where tasks can be moved between columns. Each task has an ID, title, and status.

```svelte
<script lang="ts">
  import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

  type Status = 'todo' | 'in-progress' | 'done';
  interface Task { id: string; title: string; status: Status; }

  let tasks = $state<Task[]>([
    { id: '1', title: 'Design', status: 'todo' },
    { id: '2', title: 'Build', status: 'in-progress' },
  ]);

  const columns: Status[] = ['todo', 'in-progress', 'done'];

  function handleDrop(state: DragDropState<Task>) {
    const { draggedItem, targetContainer } = state;
    if (!targetContainer) return;
    tasks = tasks.map(t =>
      t.id === draggedItem.id ? { ...t, status: targetContainer as Status } : t
    );
  }
</script>

{#each columns as column}
  <div use:droppable={{ container: column, callbacks: { onDrop: handleDrop } }}>
    <h2>{column}</h2>
    {#each tasks.filter(t => t.status === column) as task (task.id)}
      <div use:draggable={{ container: column, dragData: task }}>
        {task.title}
      </div>
    {/each}
  </div>
{/each}
```

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

### Implement a Kanban Board with droppable

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Uses the droppable action to create drop zones and handle item movement between columns in a Kanban-style layout.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	type TaskStatus = 'todo' | 'in-progress' | 'done';
	interface Task {
		id: string;
		title: string;
		status: TaskStatus;
	}

	let tasks = $state<Task[]>([
		{ id: '1', title: 'Design system updates', status: 'todo' },
		{ id: '2', title: 'User research', status: 'in-progress' },
		{ id: '3', title: 'Bug fixes', status: 'done' }
	]);

	const columns: TaskStatus[] = ['todo', 'in-progress', 'done'];

	async function handleDrop(state: DragDropState<Task>) {
		const { draggedItem, targetContainer } = state;
		if (!targetContainer) return;

		// Move task to new column
		tasks = tasks.map((task) =>
			task.id === draggedItem.id ? { ...task, status: targetContainer as TaskStatus } : task
		);
	}
</script>

<div class="kanban-board">
	{#each columns as status}
		<div
			class="column"
			use:droppable={{
				container: status,
				callbacks: {
					onDrop: handleDrop,
					onDragEnter: (state) => console.log('Entered:', status),
					onDragLeave: (state) => console.log('Left:', status),
					onDragOver: (state) => console.log('Over:', status)
				}
			}}
		>
			<h2>{status}</h2>
			{#each tasks.filter((t) => t.status === status) as task (task.id)}
				<div use:draggable={{ container: status, dragData: task }} class="task-card">
					{task.title}
				</div>
			{/each}
		</div>
	{/each}
</div>

<style>
	:global(.drag-over) {
		background-color: #f5f5f5;
		outline: 1px dashed #a3a3a3;
	}
</style>
```

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

### View project directory structure

Source: https://github.com/thisuxhq/sveltednd/blob/main/AGENTS.md

Overview of the source code organization for the library.

```text
src/
├── lib/
│   ├── actions/          # draggable.ts, droppable.ts, index.ts
│   ├── stores/           # dnd.svelte.ts (state runes)
│   ├── types/            # TypeScript interfaces
│   ├── styles/           # dnd.css
│   └── index.ts          # Public API exports
└── routes/               # Demo pages (SvelteKit)
```

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

### Droppable Action Options

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Configuration options for the `use:droppable` action to create drop zones.

```APIDOC
## Droppable Options (`DragDropOptions<T>`)

### Description
Options to configure the `use:droppable` Svelte action.

### Method
None (This is a Svelte action configuration)

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Property     | Type                                   | Description                                                            |
| ------------ | -------------------------------------- | ---------------------------------------------------------------------- |
| `container`  | `string`                               | **Required.** Container identifier                                     |
| `disabled`   | `boolean`                              | Disable dropping for this element                                      |
| `direction`  | `'vertical' | 'horizontal' | 'grid'` | Layout direction (default: `'vertical'`)                               |
| `callbacks`  | `object`                               | Event callbacks (`onDragEnter`, `onDragLeave`, `onDragOver`, `onDrop`) |
| `attributes` | `object`                               | CSS class overrides (`dragOverClass`)                                  |

### Request Example
```svelte
<script lang="ts">
	import { droppable, type DragDropState } from '@thisux/sveltednd';

	function handleDrop(state: DragDropState<any>) {
		console.log('Item dropped:', state);
	}
</script>

<div use:droppable={{ container: 'my-list', callbacks: { onDrop: handleDrop } }}>
	Drop items here
</div>
```

### Response
None (This is a Svelte action configuration)
```

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

### Access Global dndState

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Demonstrates how to use the reactive dndState object to track drag operations and update UI in real-time.

```svelte
<script lang="ts">
	import { dndState, draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Item {
		id: string;
		name: string;
	}

	let items = $state<Item[]>([
		{ id: '1', name: 'Item A' },
		{ id: '2', name: 'Item B' },
		{ id: '3', name: 'Item C' }
	]);

	function handleDrop(state: DragDropState<Item>) {
		// Access state properties
		console.log('Dropped item:', state.draggedItem);
		console.log('From container:', state.sourceContainer);
		console.log('To container:', state.targetContainer);
		console.log('Position:', state.dropPosition); // 'before' | 'after'
	}
</script>

<!-- Real-time drag status display -->
{#if dndState.isDragging}
	<div class="drag-status">
		<p>Dragging: {dndState.draggedItem?.name}</p>
		<p>From: {dndState.sourceContainer}</p>
		{#if dndState.targetContainer}
			<p>Over: {dndState.targetContainer}</p>
			<p>Position: {dndState.dropPosition}</p>
		{/if}
		{#if dndState.invalidDrop}
			<p class="error">Invalid drop zone!</p>
		{/if}
	</div>
{/if}

<div class="list">
	{#each items as item, index (item.id)}
		<div
			use:draggable={{ container: index.toString(), dragData: item }}
			use:droppable={{ container: index.toString(), callbacks: { onDrop: handleDrop } }}
		>
			{item.name}
		</div>
	{/each}
</div>
```

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

### Create Feature Branch

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Create a new branch for implementing features or fixes.

```bash
git checkout -b feature/my-new-feature
```

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

### Implement Grid Layout Sorting

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Uses direction: 'grid' to enable nearest-edge detection for 2D layouts. Requires CSS to style the drop indicators.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Card {
		id: string;
		color: string;
		icon: string;
	}

	let cards = $state<Card[]>([
		{ id: '1', color: 'bg-blue-500', icon: '■' },
		{ id: '2', color: 'bg-green-500', icon: '●' },
		{ id: '3', color: 'bg-red-500', icon: '▲' },
		{ id: '4', color: 'bg-purple-500', icon: '□' },
		{ id: '5', color: 'bg-yellow-500', icon: '○' },
		{ id: '6', color: 'bg-pink-500', icon: '△' }
	]);

	function handleDrop(state: DragDropState<Card>) {
		const { draggedItem, sourceContainer, targetContainer } = state;
		if (!targetContainer || sourceContainer === targetContainer) return;

		// Remove from original position and insert at new position
		cards = cards.filter((card) => card.id !== draggedItem.id);
		cards.splice(parseInt(targetContainer), 0, draggedItem);
	}
</script>

<div class="grid grid-cols-3 gap-4">
	{#each cards as card, index (card.id)}
		<div
			use:droppable={{
				container: index.toString(),
				direction: 'grid', // Enable nearest-edge detection
				callbacks: { onDrop: handleDrop }
			}}
			class="aspect-square border p-2"
		>
			<div
				use:draggable={{
					container: index.toString(),
					dragData: card
				}}
				class="h-full w-full {card.color} flex items-center justify-center text-4xl text-white cursor-move"
			>
				{card.icon}
			</div>
		</div>
	{/each}
</div>

<style>
	:global(.drop-left::before),
	:global(.drop-right::after) {
		content: '';
		position: absolute;
		top: 0;
		bottom: 0;
		width: 2px;
		background-color: #3b82f6;
	}
	:global(.drop-left::before) {
		left: -1px;
	}
	:global(.drop-right::after) {
		right: -1px;
	}
</style>
```

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

### Sortable List with sveltednd

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Implement a sortable list where items can be reordered by dragging and dropping. Ensure the 'dnd.css' is imported for default styling.

```svelte
<script lang="ts">
  import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';
  import '@thisux/sveltednd/dnd.css';

  let items = $state(['Apple', 'Banana', 'Cherry']);

  function handleDrop(state: DragDropState<string>) {
    const { draggedItem, targetContainer, dropPosition } = state;
    const fromIndex = items.indexOf(draggedItem);
    let toIndex = items.indexOf(targetContainer); // if using item as container key
    if (dropPosition === 'after') toIndex++;
    items.splice(fromIndex, 1);
    items.splice(toIndex, 0, draggedItem);
    items = [...items];
  }
</script>

{#each items as item (item)}
  <div
    use:draggable={{ container: item, dragData: item }}
    use:droppable={{ container: item, callbacks: { onDrop: handleDrop } }}
  >
    {item}
  </div>
{/each}
```

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

### Importing CSS Styles

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Import the required CSS stylesheet to enable drop position indicators.

```typescript
import '@thisux/sveltednd/dnd.css';
// or
import '$lib/styles/dnd.css';
```

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

### Push Changes

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Push the local branch to the remote repository.

```bash
git push origin feature/my-new-feature
```

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

### Draggable Action Options

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Configuration options for the `use:draggable` action to make elements draggable.

```APIDOC
## Draggable Options (`DraggableOptions<T>`)

### Description
Options to configure the `use:draggable` Svelte action.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Property      | Type       | Description                                                               |
| ------------- | ---------- | ------------------------------------------------------------------------- |
| `container`   | `string`   | **Required.** Container identifier for grouping items                     |
| `dragData`    | `T`        | **Required.** Data payload to transfer during drag                        |
| `disabled`    | `boolean`  | Disable dragging for this element                                         |
| `handle`      | `string`   | CSS selector for drag handle (e.g., `'.drag-handle'`)                     |
| `interactive` | `string[]` | Additional selectors for interactive elements that shouldn't trigger drag |
| `callbacks`   | `object`   | Event callbacks (`onDragStart`, `onDragEnd`)                              |
| `attributes`  | `object`   | CSS class overrides (`draggingClass`)                                     |

### Request Example
```svelte
<script lang="ts">
	import { draggable } from '@thisux/sveltednd';
	let item = { id: 1, name: 'Example Item' };
</script>

<div use:draggable={{ container: 'my-list', dragData: item, handle: '.handle' }}>
	<span class="handle">☰</span>
	{item.name}
</div>
```

### Response
None (This is a Svelte action configuration)
```

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

### Using fromAction with Svelte 5 Components

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Demonstrates how to use `fromAction` to enable Svelte actions like `draggable` and `droppable` on components. This is necessary because native Svelte actions only work on HTML elements. Ensure the component spreads props onto its root element to receive the action.

```svelte
<script lang="ts">
	import { fromAction } from 'svelte/attachments';
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';
	import Card from './Card.svelte';
	import Column from './Column.svelte';

	interface Task {
		id: string;
		title: string;
	}

	let tasks = $state<Task[]>([
		{ id: '1', title: 'Task 1' },
		{ id: '2', title: 'Task 2' }
	]);

	function handleDrop(state: DragDropState<Task>) {
		// Handle drop
	}
</script>

<!-- Works on components that spread props onto their root element -->
{#each tasks as task, index (task.id)}
	<Card
		{@attach fromAction(draggable, {
			container: index.toString(),
			dragData: task
		})}
	>
		{task.title}
	</Card>
{/each}

<Column
	{@attach fromAction(droppable, {
		container: 'todo',
		callbacks: { onDrop: handleDrop }
	})}
>
	<!-- draggable items -->
</Column>
```

```svelte
<!-- Card.svelte - Component that supports actions via props spreading -->
<script>
	let { children, ...props } = $props();
</script>

<div {...props}>
	{@render children?.()}
</div>
```

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

### Run Type Checking

Source: https://github.com/thisuxhq/sveltednd/blob/main/CONTRIBUTING.md

Execute TypeScript checks to identify potential errors.

```bash
bun run check
```

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

### Define Droppable Containers

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Apply the droppable action to an element to create a valid drop zone.

```svelte
<div use:droppable={{ container: 'my-list', callbacks: { onDrop: handleDrop } }}>
	<!-- Draggable items go here -->
</div>
```

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

### Implement Horizontal Layout Sorting

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Uses direction: 'horizontal' to enable drop indicators as vertical lines for left-to-right lists.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Tab {
		id: string;
		label: string;
	}

	let tabs = $state<Tab[]>([
		{ id: '1', label: 'Home' },
		{ id: '2', label: 'Products' },
		{ id: '3', label: 'About' },
		{ id: '4', label: 'Contact' }
	]);

	function handleDrop(state: DragDropState<Tab>) {
		const { draggedItem, targetContainer, dropPosition } = state;
		const dragIndex = tabs.findIndex((tab) => tab.id === draggedItem.id);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex += 1;

		if (dragIndex !== -1 && !isNaN(dropIndex)) {
			const [tab] = tabs.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			tabs.splice(adjusted, 0, tab);
		}
	}
</script>

<div class="flex gap-2">
	{#each tabs as tab, index (tab.id)}
		<div
			use:draggable={{ container: index.toString(), dragData: tab }}
			use:droppable={{
				container: index.toString(),
				direction: 'horizontal', // Horizontal layout mode
				callbacks: { onDrop: handleDrop }
			}}
			class="px-4 py-2 bg-gray-100 rounded cursor-move"
		>
			{tab.label}
		</div>
	{/each}
</div>
```

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

### Apply Custom CSS Classes

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Use the attributes option in draggable and droppable to inject custom CSS classes for dragging and drag-over states.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Item {
		id: string;
		name: string;
	}

	let items = $state<Item[]>([
		{ id: '1', name: 'Custom styled item 1' },
		{ id: '2', name: 'Custom styled item 2' }
	]);

	function handleDrop(state: DragDropState<Item>) {
		// Handle drop logic
	}
</script>

{#each items as item, index (item.id)}
	<div
		use:draggable={{
			container: index.toString(),
			dragData: item,
			attributes: {
				draggingClass: 'opacity-50 scale-105 shadow-xl ring-2 ring-blue-500'
			}
		}}
		use:droppable={{
			container: index.toString(),
			callbacks: { onDrop: handleDrop },
			attributes: {
				dragOverClass: 'bg-blue-50 border-blue-300 border-dashed'
			}
		}}
		class="p-4 border rounded transition-all"
	>
		{item.name}
	</div>
{/each}
```

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

### DragDropOptions Interface

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Defines the configuration options for both draggable and droppable actions, including layout direction, event callbacks, and CSS class overrides.

```APIDOC
## DragDropOptions Interface

### Description
Interface defining the configuration for drag and drop operations.

### Parameters
- **container** (string) - Required - Unique identifier for the container.
- **dragData** (T) - Optional - Data payload for draggable items.
- **disabled** (boolean) - Optional - Disables drag/drop functionality.
- **autoScroll** (boolean) - Optional - Enables auto-scroll when dragging near edges.
- **direction** ('vertical' | 'horizontal' | 'grid') - Optional - Layout direction for drop calculation.
- **callbacks** (object) - Optional - Lifecycle event handlers.
- **attributes** (object) - Optional - CSS class overrides for dragging and drag-over states.
```

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

### DraggableOptions Interface

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Defines the configuration options for the `draggable` action, including data transfer, drag handles, and event callbacks.

```APIDOC
## DraggableOptions Interface

The `DraggableOptions<T>` interface defines all configuration options for the draggable action. It extends the base `DragDropOptions` with additional properties for controlling drag initiation and interactive element handling.

```typescript
interface DraggableOptions<T = unknown> {
	// Required: Unique identifier for this container/group
	container: string;

	// Required: Data payload to transfer during drag (available in all callbacks)
	dragData: T;

	// Optional: Disable dragging for this element
	disabled?: boolean;

	// Optional: CSS selector for drag handle (e.g., '.drag-handle')
	// When provided, only clicks on the handle element start a drag
	handle?: string;

	// Optional: Additional selectors for interactive elements that shouldn't trigger drag
	// Default protected: input, textarea, select, button, [contenteditable], a[href], label, option
	interactive?: string[];

	// Optional: Whether to auto-scroll scrollable ancestors when dragging near edges
	autoScroll?: boolean;

	// Optional: Event callbacks for drag lifecycle
	callbacks?: {
		onDragStart?: (state: DragDropState<T>) => void;
		onDragEnd?: (state: DragDropState<T>) => void;
	};

	// Optional: CSS class customization
	attributes?: {
		draggingClass?: string; // Default: 'dragging'
	};
}
```
```

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

### Define DragDropOptions Interface

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Configuration interface for customizing drag-and-drop behavior, including callbacks, layout direction, and CSS classes.

```typescript
interface DragDropOptions<T = unknown> {
	// Required: Unique identifier for this container
	container: string;

	// Optional: Data payload (used by draggable)
	dragData?: T;

	// Optional: Disable drag/drop functionality
	disabled?: boolean;

	// Optional: Whether to auto-scroll when dragging near edges (default: true)
	autoScroll?: boolean;

	// Optional: Layout direction for drop position calculation
	// 'vertical' (default): top-to-bottom, horizontal drop indicator line
	// 'horizontal': left-to-right, vertical drop indicator line
	// 'grid': 2D layout with nearest-edge detection
	direction?: 'vertical' | 'horizontal' | 'grid';

	// Optional: Event callbacks
	callbacks?: {
		onDragStart?: (state: DragDropState<T>) => void;
		onDragEnter?: (state: DragDropState<T>) => void;
		onDragLeave?: (state: DragDropState<T>) => void;
		onDragOver?: (state: DragDropState<T>) => void;
		onDrop?: (state: DragDropState<T>) => Promise<void> | void;
		onDragEnd?: (state: DragDropState<T>) => void;
	};

	// Optional: CSS class overrides
	attributes?: {
		draggingClass?: string; // Default: 'dragging'
		dragOverClass?: string; // Default: 'drag-over'
	};
}
```

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

### Access Global Drag State

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Use the dndState store to reactively track drag operations throughout the application.

```svelte
<script>
	import { dndState } from '@thisux/sveltednd';
</script>

{#if dndState.isDragging}
	<p>Dragging {dndState.draggedItem?.name} from {dndState.sourceContainer}</p>
{/if}
```

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

### dndState

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Global reactive state object tracking the current drag operation.

```APIDOC
## dndState

### Description
A global reactive object (Svelte 5 $state rune) that tracks the current drag operation. Do not mutate manually.

### Fields
- **isDragging** (boolean) - True from dragstart until dragend.
- **draggedItem** (T | null) - The data payload being dragged.
- **sourceContainer** (string) - Container ID where the drag started.
- **targetContainer** (string | null) - Container ID currently being hovered over.
- **targetElement** (HTMLElement | null) - The specific DOM element under the cursor.
- **dropPosition** ('before' | 'after' | null) - Where the item will land relative to targetElement.
- **invalidDrop** (boolean) - Set to true when hovering over an invalid drop zone.
```

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

### DragDropOptions<T>

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Configuration options for the droppable action to define drop zone behavior and appearance.

```APIDOC
## DragDropOptions<T>

### Description
Configuration object passed to the droppable action to define container behavior, data handling, and visual feedback.

### Parameters
#### Options
- **container** (string) - Required - Identifier for this drop zone.
- **dragData** (T) - Optional - Data payload associated with the item.
- **disabled** (boolean) - Optional - When true, the element won't accept drops.
- **callbacks** (DragDropCallbacks<T>) - Optional - Lifecycle event handlers.
- **attributes** (DragDropAttributes) - Optional - Custom CSS class overrides.
- **direction** ('vertical' | 'horizontal' | 'grid') - Optional - Controls drop indicator direction.
```

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

### Implement Drag Handle Pattern

Source: https://context7.com/thisuxhq/sveltednd/llms.txt

Use the handle option in the draggable action to restrict drag initiation to a specific child element. This allows other parts of the component to remain interactive, such as text selection or button clicks.

```svelte
<script lang="ts">
	import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

	interface Item {
		id: string;
		title: string;
		description: string;
	}

	let items = $state<Item[]>([
		{ id: '1', title: 'Review PRs', description: 'Check open pull requests' },
		{ id: '2', title: 'Update docs', description: 'Add new API examples' },
		{ id: '3', title: 'Fix bug', description: 'Users unable to reset password' }
	]);

	function handleDrop(state: DragDropState<Item>) {
		const { draggedItem, targetContainer, dropPosition } = state;
		const dragIndex = items.findIndex((item) => item.id === draggedItem.id);
		let dropIndex = parseInt(targetContainer ?? '0');
		if (dropPosition === 'after') dropIndex += 1;

		if (dragIndex !== -1 && !isNaN(dropIndex)) {
			const [item] = items.splice(dragIndex, 1);
			const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
			items.splice(adjusted, 0, item);
		}
	}
</script>

{#each items as item, index (item.id)}
	<div
		use:draggable={{
			container: index.toString(),
			dragData: item,
			handle: '.drag-handle' // Only the grip icon starts dragging
		}}
		use:droppable={{
			container: index.toString(),
			callbacks: { onDrop: handleDrop }
		}}
		class="list-item"
	>
		<!-- Drag handle - only this element initiates drag -->
		<button class="drag-handle" aria-label="Drag to reorder">
			<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
				<circle cx="9" cy="5" r="1.5" />
				<circle cx="15" cy="5" r="1.5" />
				<circle cx="9" cy="12" r="1.5" />
				<circle cx="15" cy="12" r="1.5" />
				<circle cx="9" cy="19" r="1.5" />
				<circle cx="15" cy="19" r="1.5" />
			</svg>
		</button>

		<!-- Text remains selectable -->
		<div class="content">
			<h3>{item.title}</h3>
			<p>{item.description}</p>
		</div>
	</div>
{/each}

<style>
	.drag-handle {
		cursor: grab;
	}
	.drag-handle:active {
		cursor: grabbing;
	}
</style>
```

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

### Global Drag and Drop State

Source: https://github.com/thisuxhq/sveltednd/blob/main/README.md

Access to the current drag and drop state across the application.

```APIDOC
## Global State (`dndState`)

### Description
Provides real-time access to the drag and drop state of the application.

### Method
None (This is a reactive store)

### Endpoint
None

### Parameters
None

### Request Example
```svelte
<script>
	import { dndState } from '@thisux/sveltednd';
</script>

{#if dndState.isDragging}
	<p>Dragging item: {dndState.draggedItem?.id}</p>
	<p>From container: {dndState.sourceContainer}</p>
{:else}
	<p>Not currently dragging.</p>
{/if}
```

### Response
#### Success Response (200)
`dndState` object with the following properties:
- `isDragging` (boolean): Indicates if a drag operation is in progress.
- `draggedItem` (any): The data of the item being dragged.
- `sourceContainer` (string | null): The identifier of the container from which the item was dragged.
- `currentContainer` (string | null): The identifier of the container the item is currently over.

#### Response Example
```json
{
  "isDragging": true,
  "draggedItem": {
    "id": 1,
    "name": "Example Item"
  },
  "sourceContainer": "list-a",
  "currentContainer": "list-b"
}
```
```

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

### Display Real-Time Drag State in Svelte

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Use the `dndState` store to display information about the current drag operation, such as whether a drag is in progress and details about the dragged item and target container.

```svelte
<script>
  import { dndState } from '@thisux/sveltednd';
</script>

<!-- Show a global drag hint -->
{#if dndState.isDragging}
  <div class="fixed bottom-4 right-4 bg-black text-white p-2 rounded">
    Moving: {dndState.draggedItem?.title}
    → {dndState.targetContainer ?? 'none'}
  </div>
{/if}
```

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

### Grid Sort with sveltednd

Source: https://github.com/thisuxhq/sveltednd/blob/main/static/llms.txt

Enable sorting of items within a grid layout. The `direction: 'grid'` option is used for grid-specific drop behavior.

```svelte
<script lang="ts">
  import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

  let cells = $state([1, 2, 3, 4, 5, 6]);

  function handleDrop(state: DragDropState<number>) {
    const from = cells.indexOf(state.draggedItem);
    const to = cells.indexOf(Number(state.targetContainer));
    if (from === to) return;
    const next = [...cells];
    next.splice(from, 1);
    next.splice(to, 0, state.draggedItem);
    cells = next;
  }
</script>

<div style="display: grid; grid-template-columns: repeat(3, 1fr);">
  {#each cells as cell (cell)}
    <div
      use:draggable={{ container: String(cell), dragData: cell }}
      use:droppable={{ container: String(cell), direction: 'grid', callbacks: { onDrop: handleDrop } }}
    >
      {cell}
    </div>
  {/each}
</div>
```