@splicetree/plugin-dnd 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @splicetree/plugin-dnd
+
+## 0.0.1
+
+### Patch Changes
+
+- chore: 搭建 SpliceTree 框架基础架构与工程体系
+
+  框架架构：
+  - 建立无头树（Headless Tree）核心模型与数据结构
+  - 定义节点操作 API、事件系统和状态管理机制
+  - 设计并实现插件体系（生命周期、注册机制、能力扩展）
+  - 引入模块化架构，明确 core / plugins / adapters 的边界
+  - 预留扩展点与内部协议，构建可插拔式架构基础
+
+  适配层与生态：
+  - 添加 Vue 3 适配层（渲染无关、纯接口绑定）
+  - 设计独立的 UI 层解耦策略，确保跨框架可迁移
+  - 预留未来 React/Svelte/WebComponents 的适配接口
+
+  工程化与工具链：
+  - 初始化 monorepo 工程结构（packages + docs）
+  - 配置构建工具链 tsdown（多包构建、类型输出）
+  - 构建文档系统（VitePress）与基础导航结构
+  - 设置开发环境、代码规范（ESLint）、格式化流程

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael Cocova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @splicetree/plugin-dnd
+
+[![version](https://img.shields.io/npm/v/@splicetree/plugin-dnd.svg?label=version)](https://www.npmjs.com/package/@splicetree/plugin-dnd)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/plugin-dnd.svg)](https://npmcharts.com/compare/%40splicetree%2Fplugin-dnd?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/plugin-dnd.svg)](https://www.npmjs.com/package/@splicetree/plugin-dnd)
+[![Website](https://img.shields.io/static/v1?label=Website&message=splicetree.dev&color=blue)](https://www.splicetree.dev)
+[![GitHub](https://img.shields.io/static/v1?label=GitHub&message=splicetree%2Fsplicetree&logo=github)](https://github.com/michaelcocova/splicetree)
+
+为树节点提供拖拽移动能力，支持插入到目标之前、之后或作为子节点。
+
+## 安装
+
+`pnpm add @splicetree/plugin-dnd`
+
+## 使用
+
+```ts
+import { createSpliceTree } from '@splicetree/core'
+import dnd from '@splicetree/plugin-dnd'
+
+const tree = createSpliceTree(data, {
+  plugins: [dnd],
+})
+```
+
+## Api
+
+### Options
+
+| 选项               | 类型      | 默认值 | 说明                                                      |
+| ------------------ | --------- | ------ | --------------------------------------------------------- |
+| `autoUpdateParent` | `boolean` | `true` | 拖拽后自动更新源节点的父字段；为 `false` 时不写回且不移动 |
+| `autoExpandOnDrop` | `boolean` | `true` | 拖入后自动展开目标节点                                    |
+
+### Events
+
+| 事件   | 负载                                                                           | 说明     |
+| ------ | ------------------------------------------------------------------------------ | -------- |
+| `move` | `{ id: string, parentId?: string, position: DropPosition, beforeId?: string }` | 节点移动 |
+
+### 实例方法
+
+| 名称             | 参数                                                      | 说明                     |
+| ---------------- | --------------------------------------------------------- | ------------------------ |
+| `drop`           | `srcId: string; targetId: string; position: DropPosition` | 执行移动                 |
+| `onDragStart`    | `id: string`                                              | 标记拖拽源               |
+| `onDragOver`     | `id: string; el: HTMLElement; e: DragEvent \| MouseEvent` | 更新目标悬停位置         |
+| `onDragLeave`    | `id: string`                                              | 清理悬停位置             |
+| `onDrop`         | `targetId: string`                                        | 根据当前悬停位置执行移动 |
+| `hoverPositions` | `无`                                                      | 目标悬停位置缓存         |
+| `draggingId`     | `无`                                                      | 当前正在拖拽的节点 id    |
+| `dragProps`      | `无`                                                      | DOM 事件绑定集合         |
+
+### 节点方法
+
+| 名称                | 参数 | 说明                 |
+| ------------------- | ---- | -------------------- |
+| `getDropPosition()` | `无` | 当前节点的悬停位置   |
+| `isDragging()`      | `无` | 当前节点是否为拖拽源 |

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { SpliceTreePlugin } from "@splicetree/core";
+
+//#region src/index.d.ts
+
+/**
+ * 拖拽落点位置
+ * - BEFORE: 目标之前插入
+ * - INSIDE: 作为目标的子节点插入
+ * - AFTER:  目标之后插入
+ */
+declare enum DropPosition {
+  BEFORE = -1,
+  INSIDE = 0,
+  AFTER = 1,
+}
+declare module '@splicetree/core' {
+  /**
+   * 插件配置项扩展（DnD）
+   */
+  interface UseSpliceTreeOptions {
+    /**
+     * 自动更新父节点
+     * 如果为 false，则不会自动更新父节点
+     * 需要监听 move 事件，手动更新父节点
+     * @default true
+     */
+    autoUpdateParent?: boolean;
+    /**
+     * 拖入后自动展开目标节点
+     * @default true
+     */
+    autoExpandOnDrop?: boolean;
+  }
+  interface SpliceTreeEventPayloadMap {
+    /**
+     * 节点移动事件负载
+     * @property id 源节点 id
+     * @property parentId 新父级节点 id（INSIDE/BEFORE/AFTER 场景下可能不同）
+     * @property position 落点位置（BEFORE/INSIDE/AFTER）
+     * @property beforeId 插入到谁之前（AFTER/BEFORE 场景下提供）
+     */
+    move: {
+      id: string;
+      parentId?: string;
+      position: DropPosition;
+      beforeId?: string;
+    };
+  }
+  interface SpliceTreeInstance {
+    /**
+     * 执行拖拽移动
+     * @param srcId 源节点 id
+     * @param targetId 目标节点 id
+     * @param position 落点位置（前/内/后）
+     */
+    drop: (srcId: string, targetId: string, position: DropPosition) => void;
+    /**
+     * 当前拖拽源节点 id
+     */
+    draggingId?: string;
+    /**
+     * 目标节点的悬停位置映射
+     */
+    hoverPositions: Map<string, DropPosition>;
+    /**
+     * DOM 事件：开始拖拽
+     */
+    onDragStart: (id: string) => void;
+    /**
+     * DOM 事件：悬停计算并更新位置
+     */
+    onDragOver: (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => void;
+    /**
+     * DOM 事件：离开目标，清理悬停状态
+     */
+    onDragLeave: (id: string) => void;
+    /**
+     * DOM 事件：在目标上释放后执行移动
+     */
+    onDrop: (targetId: string) => void;
+    /**
+     * 可直接 v-bind 到节点的拖拽属性集合
+     */
+    dragProps: {
+      /**
+       * 是否可拖拽
+       */
+      draggable: boolean;
+      /**
+       * 原生拖拽开始事件处理
+       */
+      onDragstart: (e: DragEvent) => void;
+      /**
+       * 原生拖拽悬停事件处理
+       */
+      onDragover: (e: DragEvent) => void;
+      /**
+       * 原生拖拽离开事件处理
+       */
+      onDragleave: (e: DragEvent) => void;
+      /**
+       * 原生拖拽释放事件处理
+       */
+      onDrop: (e: DragEvent) => void;
+    };
+  }
+  /**
+   * 节点扩展（DnD）
+   */
+  interface SpliceTreeNode {
+    /**
+     * 获取当前节点的悬停落点位置
+     */
+    getDropPosition: () => (DropPosition | undefined);
+    /**
+     * 当前节点是否为拖拽源
+     */
+    isDragging: () => boolean;
+  }
+}
+declare const dnd: SpliceTreePlugin;
+//#endregion
+export { DropPosition, dnd as default, dnd };

package/dist/index.js

@@ -0,0 +1,208 @@
+//#region src/index.ts
+/**
+* 拖拽落点位置
+* - BEFORE: 目标之前插入
+* - INSIDE: 作为目标的子节点插入
+* - AFTER:  目标之后插入
+*/
+let DropPosition = /* @__PURE__ */ function(DropPosition$1) {
+	DropPosition$1[DropPosition$1["BEFORE"] = -1] = "BEFORE";
+	DropPosition$1[DropPosition$1["INSIDE"] = 0] = "INSIDE";
+	DropPosition$1[DropPosition$1["AFTER"] = 1] = "AFTER";
+	return DropPosition$1;
+}({});
+const dnd = {
+	name: "dnd",
+	setup(ctx) {
+		const { autoUpdateParent = true, autoExpandOnDrop = true } = ctx.tree.options || {};
+		const parentField = ctx.tree.options?.parentField ?? "parent";
+		let draggingId;
+		const hoverPositions = /* @__PURE__ */ new Map();
+		/**
+		* 开始拖拽：记录拖拽源并通知视图刷新（用于高亮拖拽源）
+		* @param id 源节点 id
+		*/
+		const onDragStart = (id) => {
+			draggingId = id;
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 依据指针相对目标节点的垂直比例计算落点
+		* - 上 1/3：BEFORE；下 1/3：AFTER；中间：INSIDE
+		* - 过滤自身与其父级为目标的情况（返回 undefined）
+		* @param id 目标节点 id
+		* @param el 目标节点元素
+		* @param e 拖拽/鼠标事件
+		*/
+		const computePosition = (id, el, e) => {
+			const rect = el.getBoundingClientRect();
+			const y = ("clientY" in e ? e.clientY : 0) - rect.top;
+			const ratio = Math.max(0, Math.min(1, y / rect.height));
+			if (ratio < .33) return DropPosition.BEFORE;
+			if (ratio > .66) return DropPosition.AFTER;
+			if (draggingId === id) return;
+			if (ctx.tree.getNode(draggingId)?.getParent()?.id === id) return;
+			return DropPosition.INSIDE;
+		};
+		/**
+		* 悬停：更新目标的悬停位置映射并刷新视图
+		* @param id 目标节点 id
+		* @param el 目标节点元素
+		* @param e 拖拽/鼠标事件
+		*/
+		const onDragOver = (id, el, e) => {
+			const pos = computePosition(id, el, e);
+			if (pos === void 0) hoverPositions.delete(id);
+			else hoverPositions.set(id, pos);
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 离开目标：清理该目标的悬停位置并刷新视图
+		* @param id 目标节点 id
+		*/
+		const onDragLeave = (id) => {
+			hoverPositions.delete(id);
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 执行移动：依据落点位置更新树结构，必要时写回父字段并派发事件
+		* - INSIDE：成为子节点；可选自动展开目标
+		* - BEFORE/AFTER：保持同父级，调整顺序
+		* @param srcId 源节点 id
+		* @param targetId 目标节点 id
+		* @param position 落点位置
+		*/
+		const drop = (srcId, targetId, position) => {
+			const src = ctx.tree.getNode(srcId);
+			const target = ctx.tree.getNode(targetId);
+			if (!src || !target) return;
+			if (srcId === targetId) return;
+			const srcParentId = src.getParent()?.id;
+			if (position === DropPosition.INSIDE) {
+				if (targetId === srcParentId) return;
+				if (autoUpdateParent) {
+					ctx.tree.moveNode(srcId, targetId);
+					Reflect.set(src.original, parentField, targetId);
+					if (autoExpandOnDrop) ctx.tree.expand(targetId);
+					ctx.events.emit({
+						name: "visibility",
+						keys: ctx.tree.expandedKeys()
+					});
+				}
+				ctx.events.emit({
+					name: "move",
+					id: srcId,
+					parentId: targetId,
+					position
+				});
+				return;
+			}
+			const parentId = target.getParent()?.id;
+			if (position === DropPosition.BEFORE) {
+				if (autoUpdateParent) {
+					ctx.tree.moveNode(srcId, parentId, targetId);
+					Reflect.set(src.original, parentField, parentId);
+					ctx.events.emit({
+						name: "visibility",
+						keys: ctx.tree.expandedKeys()
+					});
+				}
+				ctx.events.emit({
+					name: "move",
+					id: srcId,
+					parentId,
+					position,
+					beforeId: targetId
+				});
+				return;
+			}
+			const siblings = parentId ? ctx.tree.getNode(parentId).getChildren() : ctx.tree.items().filter((n) => !n.getParent());
+			const afterSibling = siblings[siblings.findIndex((n) => n.id === targetId) + 1]?.id;
+			if (autoUpdateParent) {
+				ctx.tree.moveNode(srcId, parentId, afterSibling);
+				Reflect.set(src.original, parentField, parentId);
+				ctx.events.emit({
+					name: "visibility",
+					keys: ctx.tree.expandedKeys()
+				});
+			}
+			ctx.events.emit({
+				name: "move",
+				id: srcId,
+				parentId,
+				position,
+				beforeId: afterSibling
+			});
+		};
+		/**
+		* 完成拖拽：依据最后一次悬停位置执行移动并清理状态
+		* @param targetId 释放时所处的目标节点 id
+		*/
+		const onDrop = (targetId) => {
+			if (!draggingId) return;
+			const pos = hoverPositions.get(targetId);
+			if (pos === DropPosition.BEFORE) drop(draggingId, targetId, DropPosition.BEFORE);
+			else if (pos === DropPosition.AFTER) drop(draggingId, targetId, DropPosition.AFTER);
+			else if (pos === DropPosition.INSIDE) drop(draggingId, targetId, DropPosition.INSIDE);
+			hoverPositions.clear();
+			draggingId = void 0;
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		return {
+			drop,
+			onDragStart,
+			onDragOver,
+			onDragLeave,
+			onDrop,
+			hoverPositions,
+			get draggingId() {
+				return draggingId;
+			},
+			dragProps: {
+				draggable: true,
+				onDragstart: (e) => {
+					const id = e.currentTarget?.dataset?.id;
+					if (id) {
+						e.dataTransfer?.setData("text/plain", id);
+						onDragStart(id);
+					}
+				},
+				onDragover: (e) => {
+					e.preventDefault();
+					const el = e.currentTarget;
+					const id = el?.dataset?.id;
+					if (id) onDragOver(id, el, e);
+				},
+				onDragleave: (e) => {
+					const id = e.currentTarget?.dataset?.id;
+					if (id) onDragLeave(id);
+				},
+				onDrop: (e) => {
+					e.preventDefault();
+					const id = e.currentTarget?.dataset?.id;
+					if (id) onDrop(id);
+				}
+			}
+		};
+	},
+	extendNode(node, ctx) {
+		node.getDropPosition = () => ctx.tree.hoverPositions.get(node.id);
+		node.isDragging = () => ctx.tree.draggingId === node.id;
+	}
+};
+var src_default = dnd;
+
+//#endregion
+export { DropPosition, src_default as default, dnd };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@splicetree/plugin-dnd",
+  "type": "module",
+  "version": "0.0.1",
+  "author": {
+    "email": "michael.cocova@gmail.com",
+    "name": "Michael Cocova"
+  },
+  "license": "MIT",
+  "homepage": "https://www.splicetree.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michaelcocova/splicetree"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@splicetree/core": "0.0.1"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown"
+  }
+}

package/src/index.ts

@@ -0,0 +1,340 @@
+import type { SpliceTreePlugin, SpliceTreePluginContext } from '@splicetree/core'
+import '@splicetree/core'
+
+/**
+ * 拖拽落点位置
+ * - BEFORE: 目标之前插入
+ * - INSIDE: 作为目标的子节点插入
+ * - AFTER:  目标之后插入
+ */
+export enum DropPosition {
+  BEFORE = -1,
+  INSIDE = 0,
+  AFTER = 1,
+}
+declare module '@splicetree/core' {
+  /**
+   * 插件配置项扩展（DnD）
+   */
+
+  interface UseSpliceTreeOptions {
+    /**
+     * 自动更新父节点
+     * 如果为 false，则不会自动更新父节点
+     * 需要监听 move 事件，手动更新父节点
+     * @default true
+     */
+    autoUpdateParent?: boolean
+    /**
+     * 拖入后自动展开目标节点
+     * @default true
+     */
+    autoExpandOnDrop?: boolean
+  }
+  interface SpliceTreeEventPayloadMap {
+    /**
+     * 节点移动事件负载
+     * @property id 源节点 id
+     * @property parentId 新父级节点 id（INSIDE/BEFORE/AFTER 场景下可能不同）
+     * @property position 落点位置（BEFORE/INSIDE/AFTER）
+     * @property beforeId 插入到谁之前（AFTER/BEFORE 场景下提供）
+     */
+    move: { id: string, parentId?: string, position: DropPosition, beforeId?: string }
+  }
+
+  interface SpliceTreeInstance {
+    /**
+     * 执行拖拽移动
+     * @param srcId 源节点 id
+     * @param targetId 目标节点 id
+     * @param position 落点位置（前/内/后）
+     */
+    drop: (srcId: string, targetId: string, position: DropPosition) => void
+    /**
+     * 当前拖拽源节点 id
+     */
+    draggingId?: string
+    /**
+     * 目标节点的悬停位置映射
+     */
+    hoverPositions: Map<string, DropPosition>
+    /**
+     * DOM 事件：开始拖拽
+     */
+    onDragStart: (id: string) => void
+    /**
+     * DOM 事件：悬停计算并更新位置
+     */
+    onDragOver: (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => void
+    /**
+     * DOM 事件：离开目标，清理悬停状态
+     */
+    onDragLeave: (id: string) => void
+    /**
+     * DOM 事件：在目标上释放后执行移动
+     */
+    onDrop: (targetId: string) => void
+    /**
+     * 可直接 v-bind 到节点的拖拽属性集合
+     */
+    dragProps: {
+      /**
+       * 是否可拖拽
+       */
+      draggable: boolean
+      /**
+       * 原生拖拽开始事件处理
+       */
+      onDragstart: (e: DragEvent) => void
+      /**
+       * 原生拖拽悬停事件处理
+       */
+      onDragover: (e: DragEvent) => void
+      /**
+       * 原生拖拽离开事件处理
+       */
+      onDragleave: (e: DragEvent) => void
+      /**
+       * 原生拖拽释放事件处理
+       */
+      onDrop: (e: DragEvent) => void
+    }
+  }
+
+  /**
+   * 节点扩展（DnD）
+   */
+  interface SpliceTreeNode {
+    /**
+     * 获取当前节点的悬停落点位置
+     */
+    getDropPosition: () => (DropPosition | undefined)
+    /**
+     * 当前节点是否为拖拽源
+     */
+    isDragging: () => boolean
+  }
+}
+
+export const dnd: SpliceTreePlugin = {
+  name: 'dnd',
+  /**
+   * 拖拽插件
+   * - 计算目标悬停位置：前（BEFORE）/内（INSIDE）/后（AFTER）
+   * - 根据配置自动更新父字段与目标展开
+   * - 通过 events 派发 move 与 visibility 事件驱动视图刷新
+   */
+  setup(ctx: SpliceTreePluginContext) {
+    const { autoUpdateParent = true, autoExpandOnDrop = true } = ctx.tree.options || {}
+    const parentField = ctx.tree.options?.parentField ?? 'parent'
+    let draggingId: string | undefined
+    const hoverPositions = new Map<string, DropPosition>()
+
+    /**
+     * 开始拖拽：记录拖拽源并通知视图刷新（用于高亮拖拽源）
+     * @param id 源节点 id
+     */
+    const onDragStart = (id: string) => {
+      draggingId = id
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 依据指针相对目标节点的垂直比例计算落点
+     * - 上 1/3：BEFORE；下 1/3：AFTER；中间：INSIDE
+     * - 过滤自身与其父级为目标的情况（返回 undefined）
+     * @param id 目标节点 id
+     * @param el 目标节点元素
+     * @param e 拖拽/鼠标事件
+     */
+    const computePosition = (id: string, el: HTMLElement, e: DragEvent | MouseEvent): DropPosition | undefined => {
+      const rect = el.getBoundingClientRect()
+      const y = ('clientY' in e ? e.clientY : 0) - rect.top
+      const ratio = Math.max(0, Math.min(1, y / rect.height))
+      if (ratio < 0.33) {
+        return DropPosition.BEFORE
+      }
+      if (ratio > 0.66) {
+        return DropPosition.AFTER
+      }
+      if (draggingId === id) {
+        return undefined
+      }
+      const parentId = ctx.tree.getNode(draggingId!)?.getParent()?.id
+      if (parentId === id) {
+        return undefined
+      }
+      return DropPosition.INSIDE
+    }
+
+    /**
+     * 悬停：更新目标的悬停位置映射并刷新视图
+     * @param id 目标节点 id
+     * @param el 目标节点元素
+     * @param e 拖拽/鼠标事件
+     */
+    const onDragOver = (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => {
+      const pos = computePosition(id, el, e)
+      if (pos === undefined) {
+        hoverPositions.delete(id)
+      } else {
+        hoverPositions.set(id, pos)
+      }
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 离开目标：清理该目标的悬停位置并刷新视图
+     * @param id 目标节点 id
+     */
+    const onDragLeave = (id: string) => {
+      hoverPositions.delete(id)
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 执行移动：依据落点位置更新树结构，必要时写回父字段并派发事件
+     * - INSIDE：成为子节点；可选自动展开目标
+     * - BEFORE/AFTER：保持同父级，调整顺序
+     * @param srcId 源节点 id
+     * @param targetId 目标节点 id
+     * @param position 落点位置
+     */
+    const drop = (srcId: string, targetId: string, position: DropPosition) => {
+      const src = ctx.tree.getNode(srcId)
+      const target = ctx.tree.getNode(targetId)
+      if (!src || !target) {
+        return
+      }
+      if (srcId === targetId) {
+        return
+      }
+      const srcParentId = src.getParent()?.id
+
+      if (position === DropPosition.INSIDE) {
+        if (targetId === srcParentId) {
+          return
+        }
+        if (autoUpdateParent) {
+          ctx.tree.moveNode(srcId, targetId)
+          Reflect.set(src.original, parentField, targetId)
+          if (autoExpandOnDrop) {
+            ctx.tree.expand(targetId)
+          }
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+        }
+        ctx.events.emit({ name: 'move', id: srcId, parentId: targetId, position })
+        return
+      }
+
+      const parent = target.getParent()
+      const parentId = parent?.id
+      if (position === DropPosition.BEFORE) {
+        if (autoUpdateParent) {
+          ctx.tree.moveNode(srcId, parentId, targetId)
+          Reflect.set(src.original, parentField, parentId)
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+        }
+        ctx.events.emit({ name: 'move', id: srcId, parentId, position, beforeId: targetId })
+        return
+      }
+
+      const siblings = parentId ? ctx.tree.getNode(parentId)!.getChildren() : ctx.tree.items().filter(n => !n.getParent())
+      const idx = siblings.findIndex(n => n.id === targetId)
+      const afterSibling = siblings[idx + 1]?.id
+      if (autoUpdateParent) {
+        ctx.tree.moveNode(srcId, parentId, afterSibling)
+        Reflect.set(src.original, parentField, parentId)
+        ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+      }
+      ctx.events.emit({ name: 'move', id: srcId, parentId, position, beforeId: afterSibling })
+    }
+
+    /**
+     * 完成拖拽：依据最后一次悬停位置执行移动并清理状态
+     * @param targetId 释放时所处的目标节点 id
+     */
+    const onDrop = (targetId: string) => {
+      if (!draggingId) {
+        return
+      }
+      const pos = hoverPositions.get(targetId)
+      if (pos === DropPosition.BEFORE) {
+        drop(draggingId, targetId, DropPosition.BEFORE)
+      } else if (pos === DropPosition.AFTER) {
+        drop(draggingId, targetId, DropPosition.AFTER)
+      } else if (pos === DropPosition.INSIDE) {
+        drop(draggingId, targetId, DropPosition.INSIDE)
+      }
+      hoverPositions.clear()
+      draggingId = undefined
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 绑定到节点的拖拽属性集，便于直接 v-bind
+     */
+    const dragProps = {
+      draggable: true,
+      onDragstart: (e: DragEvent) => {
+        const el = e.currentTarget as HTMLElement
+        const id = el?.dataset?.id
+        if (id) {
+          e.dataTransfer?.setData('text/plain', id)
+          onDragStart(id)
+        }
+      },
+      onDragover: (e: DragEvent) => {
+        e.preventDefault()
+        const el = e.currentTarget as HTMLElement
+        const id = el?.dataset?.id
+        if (id) {
+          onDragOver(id, el, e)
+        }
+      },
+      onDragleave: (e: DragEvent) => {
+        const el = e.currentTarget as HTMLElement
+        const id = el?.dataset?.id
+        if (id) {
+          onDragLeave(id)
+        }
+      },
+      onDrop: (e: DragEvent) => {
+        e.preventDefault()
+        const el = e.currentTarget as HTMLElement
+        const id = el?.dataset?.id
+        if (id) {
+          onDrop(id)
+        }
+      },
+    }
+
+    return {
+      // 公开 API：直接编程操作拖拽移动
+      drop,
+      // 事件处理：用于绑定到节点的 DOM 上
+      onDragStart,
+      onDragOver,
+      onDragLeave,
+      onDrop,
+      // 状态与查询：悬停位置与拖拽源
+      hoverPositions,
+      get draggingId() {
+        return draggingId
+      },
+      // 通用 DOM 绑定集合
+      dragProps,
+    }
+  },
+  /**
+   * 为节点扩展拖拽相关方法
+   * - getDropPosition：查询当前节点的悬停位置
+   * - isDragging：查询是否为当前拖拽源
+   */
+  extendNode(node, ctx) {
+    node.getDropPosition = () => ctx.tree.hoverPositions.get(node.id)
+    node.isDragging = () => ctx.tree.draggingId === node.id
+  },
+}
+
+export default dnd

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  clean: true,
+  sourcemap: false,
+  treeshake: true,
+  unused: true,
+  unbundle: false,
+  platform: 'neutral',
+  entry: ['./src/index.ts'],
+})