@veltra/compositions 1.3.8 → 1.3.9

package/dist/use-dnd/index.d.ts

@@ -1,21 +1,41 @@
-import { Ref } from "vue";
+import { MaybeRefOrGetter, Ref } from "vue";
 import { BaseDragState, DNDPlugin, DNDPluginData, DragState, DragendEvent, DragendEventData, DragstartEvent, DragstartEventData, DropSwapConfig, InsertConfig, InsertEvent, NativeDragEffects, Node, NodeData, NodeDragEventData, NodeEventData, NodePointerEventData, NodeRecord, NodeTargetData, ParentConfig, ParentData, ParentDragEventData, ParentEventData, ParentRecord, ParentTargetData, PointeroverNodeEvent, PointeroverParentEvent, SetupNode, SetupNodeData, ShouldSwapData, SortEvent, SortEventData, SynthDragState, TearDownNode, TearDownNodeData, TransferEvent, TransferEventData, animations, dragValues, dropOrSwap, insert, isBrowser, isDragState, isSynthDragState, parentValues, performSort, performTransfer, remapNodes, setParentValues, tearDown as tearDown$1, updateConfig } from "@formkit/drag-and-drop";
 import { VueDragAndDropData, VueElement, VueParentConfig, VueParentConfig as VueParentConfig$1, dragAndDrop as dragAndDrop$1, useDragAndDrop } from "@formkit/drag-and-drop/vue";
 //#region src/use-dnd/index.d.ts
 interface UseDnDOptions<T> extends VueParentConfig<T> {
   /**
-   * 列表数据。传入 ref 时与外部共享同一个引用，拖拽排序/转移后直接写回；
-   * 传入普通数组或不传时内部创建 ref。
+   * 列表数据。排序/跨容器转移后自动写回：
+   * - `Ref`：直接替换 `.value`
+   * - 响应式数组（如 props 上的数组）：原地 splice 写回
+   * - 非响应式纯数组：作为初始值由内部响应式副本持有，写回时顺带同步原数组
+   * - getter / 只读 computed：只读数据源，通过 `onReorder` 接收写回结果
+   * - 不传：内部创建数据源，通过返回的 `values` 读写
    */
-  values?: T[] | Ref<T[]>;
+  values?: MaybeRefOrGetter<T[]>;
+  /**
+   * 数据过滤：仅命中的项参与拖拽排序（须与 DOM 中实际渲染的可拖拽项一一对应）。
+   * 排序/转移结果自动合并回原数组，未命中的项保持相对顺序。
+   */
+  filter?: (item: T) => boolean;
+  /**
+   * 容器元素。支持 ref / getter（如 `() => btnRef.value?.parentElement`），
+   * 元素出现、替换、移除时自动初始化 / 重建 / 销毁拖拽实例。
+   * 不传时通过返回的 `parentRef` 以模板引用绑定。
+   */
+  parent?: MaybeRefOrGetter<HTMLElement | undefined>;
+  /**
+   * `values` 为只读数据源（getter / 只读 computed）时，
+   * 排序/转移结果通过该回调写回，收到的是合并后的完整数组
+   */
+  onReorder?: (values: T[]) => void;
 }
 interface UseDnDResult<T> {
-  /** 拖拽容器元素，通过 `ref` 绑定到列表容器元素上 */
+  /** 拖拽容器元素；未传 `parent` 选项时通过模板引用绑定到列表容器上 */
   parentRef: Ref<HTMLElement | undefined>;
-  /** 列表数据，排序/跨容器转移后自动更新 */
+  /** 拖拽数据。`filter` 模式下为参与拖拽的视图；排序/转移后自动更新 */
   values: Ref<T[]>;
   /**
-   * 运行时更新拖拽配置（整体替换，不与初始配置合并）
+   * 运行时更新拖拽配置（整体替换，不含 `values` / `filter` / `parent` / `onReorder`）
    * @param config 新配置
    */
   updateConfig: (config?: VueParentConfig<T>) => void;
@@ -23,16 +43,14 @@ interface UseDnDResult<T> {
 /**
  * 拖拽排序组合式方法，基于 `@formkit/drag-and-drop` 的 Vue 适配层封装。
  *
- * 相比官方 `useDragAndDrop` 的元组返回，这里使用 options 对象传参并返回命名结果。
+ * 排序/跨容器转移结果自动写回数据，无需手动处理 `onSort`；
+ * `filter` 支持只对数据的可见子集排序并自动合并回原数组；
+ * `parent` 支持动态容器（元素替换/重建时自动重新初始化）。
  * 组件卸载时自动销毁拖拽实例。
  *
- * @example
+ * @example 基础用法：列表即数据，排序自动写回
  * ```ts
- * const { parentRef, values } = useDnD({
- *   values: list,
- *   plugins: [animations()],
- *   onSort: ({ previousValues, values }) => {}
- * })
+ * const { parentRef, values } = useDnD({ values: list, plugins: [animations()] })
  * ```
  *
  * ```vue
@@ -40,6 +58,18 @@ interface UseDnDResult<T> {
  *   <li v-for="item in values" :key="item.id">{{ item.label }}</li>
  * </ul>
  * ```
+ *
+ * @example 可见子集排序 + 动态容器
+ * ```ts
+ * useDnD({
+ *   values: props.items, // 完整数据（含隐藏项），原地写回
+ *   filter: (item) => item.visible, // 仅可见项参与拖拽，排序自动合并回原数组
+ *   parent: () => addBtnRef.value?.parentElement ?? undefined, // 容器动态获取
+ *   dragHandle: '.u-form-item__label',
+ *   draggable: (el) => el.classList.contains('setting-trigger'), // 排除“新增”按钮
+ *   plugins: [animations()]
+ * })
+ * ```
  */
 declare function useDnD<T>(options?: UseDnDOptions<T>): UseDnDResult<T>;
 //#endregion

package/dist/use-dnd/index.js

@@ -1,20 +1,19 @@
-import { isRef, onBeforeUnmount, ref } from "vue";
+import { mergeView } from "./merge-view.js";
+import { computed, isReactive, isReadonly, isRef, onBeforeUnmount, ref, toValue, watch } from "vue";
 import { animations, dragValues, dropOrSwap, insert, isBrowser, isDragState, isSynthDragState, parentValues, performSort, performTransfer, remapNodes, setParentValues, tearDown, tearDown as tearDown$1, updateConfig } from "@formkit/drag-and-drop";
 import { dragAndDrop, dragAndDrop as dragAndDrop$1, useDragAndDrop } from "@formkit/drag-and-drop/vue";
 //#region src/use-dnd/index.ts
 /**
 * 拖拽排序组合式方法，基于 `@formkit/drag-and-drop` 的 Vue 适配层封装。
 *
-* 相比官方 `useDragAndDrop` 的元组返回，这里使用 options 对象传参并返回命名结果。
+* 排序/跨容器转移结果自动写回数据，无需手动处理 `onSort`；
+* `filter` 支持只对数据的可见子集排序并自动合并回原数组；
+* `parent` 支持动态容器（元素替换/重建时自动重新初始化）。
 * 组件卸载时自动销毁拖拽实例。
 *
-* @example
+* @example 基础用法：列表即数据，排序自动写回
 * ```ts
-* const { parentRef, values } = useDnD({
-*   values: list,
-*   plugins: [animations()],
-*   onSort: ({ previousValues, values }) => {}
-* })
+* const { parentRef, values } = useDnD({ values: list, plugins: [animations()] })
 * ```
 *
 * ```vue
@@ -22,25 +21,92 @@ import { dragAndDrop, dragAndDrop as dragAndDrop$1, useDragAndDrop } from "@form
 *   <li v-for="item in values" :key="item.id">{{ item.label }}</li>
 * </ul>
 * ```
+*
+* @example 可见子集排序 + 动态容器
+* ```ts
+* useDnD({
+*   values: props.items, // 完整数据（含隐藏项），原地写回
+*   filter: (item) => item.visible, // 仅可见项参与拖拽，排序自动合并回原数组
+*   parent: () => addBtnRef.value?.parentElement ?? undefined, // 容器动态获取
+*   dragHandle: '.u-form-item__label',
+*   draggable: (el) => el.classList.contains('setting-trigger'), // 排除“新增”按钮
+*   plugins: [animations()]
+* })
+* ```
 */
 function useDnD(options = {}) {
-	const { values: initialValues, ...config } = options;
+	const { values: valuesOption, filter, parent: parentOption, onReorder, ...initialConfig } = options;
 	const parentRef = ref();
-	const values = isRef(initialValues) ? initialValues : ref(initialValues ?? []);
-	function updateConfig(newConfig = {}) {
+	const internalValues = ref([]);
+	let currentConfig = initialConfig;
+	const useInternal = valuesOption === void 0 || Array.isArray(valuesOption) && !isReactive(valuesOption) && !isReadonly(valuesOption);
+	if (useInternal && valuesOption) internalValues.value = valuesOption;
+	function readSource() {
+		if (useInternal) return internalValues.value;
+		return toValue(valuesOption) ?? [];
+	}
+	function writeSource(next) {
+		if (useInternal) {
+			internalValues.value = next;
+			if (valuesOption) valuesOption.splice(0, valuesOption.length, ...next);
+			return;
+		}
+		if (isRef(valuesOption)) {
+			if (isReadonly(valuesOption)) onReorder?.(next);
+			else valuesOption.value = next;
+			return;
+		}
+		if (Array.isArray(valuesOption)) {
+			if (isReadonly(valuesOption)) onReorder?.(next);
+			else valuesOption.splice(0, valuesOption.length, ...next);
+			return;
+		}
+		onReorder?.(next);
+	}
+	/**
+	* 交给拖拽库的数据（视图）。库排序/转移后通过 setter 写回，
+	* setter 将视图结果合并回完整数据源。
+	*/
+	const dndValues = computed({
+		get: () => {
+			const source = readSource();
+			return filter ? source.filter(filter) : source;
+		},
+		set: (nextView) => {
+			if (!filter) {
+				writeSource(nextView);
+				return;
+			}
+			const source = readSource();
+			writeSource(mergeView(source, source.filter(filter), nextView));
+		}
+	});
+	/** 当前生效的容器元素：`parent` 选项优先，否则用模板引用 */
+	const resolvedParent = computed(() => parentOption === void 0 ? parentRef.value : toValue(parentOption));
+	function init(parent) {
 		dragAndDrop({
-			parent: parentRef,
-			values,
-			...newConfig
+			parent,
+			values: dndValues,
+			...currentConfig
 		});
 	}
-	updateConfig(config);
+	function updateConfig(newConfig = {}) {
+		currentConfig = newConfig;
+		if (resolvedParent.value) init(resolvedParent.value);
+	}
+	watch(resolvedParent, (parent, prev) => {
+		if (prev && prev !== parent) tearDown(prev);
+		if (parent) init(parent);
+	}, {
+		flush: "post",
+		immediate: true
+	});
 	onBeforeUnmount(() => {
-		parentRef.value && tearDown(parentRef.value);
+		if (resolvedParent.value) tearDown(resolvedParent.value);
 	});
 	return {
 		parentRef,
-		values,
+		values: dndValues,
 		updateConfig
 	};
 }

package/dist/use-dnd/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/use-dnd/index.ts"],"sourcesContent":["import { tearDown } from '@formkit/drag-and-drop'\nimport { dragAndDrop, type VueParentConfig } from '@formkit/drag-and-drop/vue'\nimport { isRef, onBeforeUnmount, ref, type Ref } from 'vue'\n\nexport interface UseDnDOptions<T> extends VueParentConfig<T> {\n  /**\n   * 列表数据。传入 ref 时与外部共享同一个引用，拖拽排序/转移后直接写回；\n   * 传入普通数组或不传时内部创建 ref。\n   */\n  values?: T[] | Ref<T[]>\n}\n\nexport interface UseDnDResult<T> {\n  /** 拖拽容器元素，通过 `ref` 绑定到列表容器元素上 */\n  parentRef: Ref<HTMLElement | undefined>\n  /** 列表数据，排序/跨容器转移后自动更新 */\n  values: Ref<T[]>\n  /**\n   * 运行时更新拖拽配置（整体替换，不与初始配置合并）\n   * @param config 新配置\n   */\n  updateConfig: (config?: VueParentConfig<T>) => void\n}\n\n/**\n * 拖拽排序组合式方法，基于 `@formkit/drag-and-drop` 的 Vue 适配层封装。\n *\n * 相比官方 `useDragAndDrop` 的元组返回，这里使用 options 对象传参并返回命名结果。\n * 组件卸载时自动销毁拖拽实例。\n *\n * @example\n * ```ts\n * const { parentRef, values } = useDnD({\n *   values: list,\n *   plugins: [animations()],\n *   onSort: ({ previousValues, values }) => {}\n * })\n * ```\n *\n * ```vue\n * <ul ref=\"parentRef\">\n *   <li v-for=\"item in values\" :key=\"item.id\">{{ item.label }}</li>\n * </ul>\n * ```\n */\nexport function useDnD<T>(options: UseDnDOptions<T> = {}): UseDnDResult<T> {\n  const { values: initialValues, ...config } = options\n\n  const parentRef = ref<HTMLElement>()\n  const values = isRef(initialValues) ? initialValues : (ref(initialValues ?? []) as Ref<T[]>)\n\n  function updateConfig(newConfig: VueParentConfig<T> = {}) {\n    dragAndDrop({ parent: parentRef, values, ...newConfig })\n  }\n\n  updateConfig(config)\n\n  onBeforeUnmount(() => {\n    parentRef.value && tearDown(parentRef.value)\n  })\n\n  return { parentRef, values, updateConfig }\n}\n\n// 重导出 `@formkit/drag-and-drop`，下游项目统一从 `@veltra/compositions` 获取，\n// 避免本库与下游各自安装导致版本不一致（体积膨胀 / 兼容问题）。\nexport {\n  // Vue 适配层原始 API\n  dragAndDrop,\n  useDragAndDrop,\n  type VueDragAndDropData,\n  type VueElement,\n  type VueParentConfig\n} from '@formkit/drag-and-drop/vue'\n\nexport {\n  // 插件\n  animations,\n  dropOrSwap,\n  insert,\n  // 操作与状态工具\n  performSort,\n  performTransfer,\n  remapNodes,\n  updateConfig,\n  parentValues,\n  setParentValues,\n  dragValues,\n  isDragState,\n  isSynthDragState,\n  isBrowser,\n  tearDown,\n  // 类型\n  type ParentConfig,\n  type ParentData,\n  type ParentRecord,\n  type Node,\n  type NodeData,\n  type NodeRecord,\n  type NodeTargetData,\n  type ParentTargetData,\n  type BaseDragState,\n  type DragState,\n  type SynthDragState,\n  type NativeDragEffects,\n  type DNDPlugin,\n  type DNDPluginData,\n  type NodeEventData,\n  type NodeDragEventData,\n  type NodePointerEventData,\n  type ParentEventData,\n  type ParentDragEventData,\n  type SortEvent,\n  type SortEventData,\n  type TransferEvent,\n  type TransferEventData,\n  type DragstartEvent,\n  type DragstartEventData,\n  type DragendEvent,\n  type DragendEventData,\n  type ShouldSwapData,\n  type DropSwapConfig,\n  type InsertConfig,\n  type InsertEvent,\n  type SetupNode,\n  type SetupNodeData,\n  type TearDownNode,\n  type TearDownNodeData,\n  type PointeroverNodeEvent,\n  type PointeroverParentEvent\n} from '@formkit/drag-and-drop'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,OAAU,UAA4B,CAAC,GAAoB;CACzE,MAAM,EAAE,QAAQ,eAAe,GAAG,WAAW;CAE7C,MAAM,YAAY,IAAiB;CACnC,MAAM,SAAS,MAAM,aAAa,IAAI,gBAAiB,IAAI,iBAAiB,CAAC,CAAC;CAE9E,SAAS,aAAa,YAAgC,CAAC,GAAG;EACxD,YAAY;GAAE,QAAQ;GAAW;GAAQ,GAAG;EAAU,CAAC;CACzD;CAEA,aAAa,MAAM;CAEnB,sBAAsB;EACpB,UAAU,SAAS,SAAS,UAAU,KAAK;CAC7C,CAAC;CAED,OAAO;EAAE;EAAW;EAAQ;CAAa;AAC3C"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/use-dnd/index.ts"],"sourcesContent":["import { tearDown } from '@formkit/drag-and-drop'\nimport { dragAndDrop, type VueParentConfig } from '@formkit/drag-and-drop/vue'\nimport {\n  computed,\n  isReactive,\n  isReadonly,\n  isRef,\n  onBeforeUnmount,\n  ref,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type Ref\n} from 'vue'\n\nimport { mergeView } from './merge-view'\n\nexport interface UseDnDOptions<T> extends VueParentConfig<T> {\n  /**\n   * 列表数据。排序/跨容器转移后自动写回：\n   * - `Ref`：直接替换 `.value`\n   * - 响应式数组（如 props 上的数组）：原地 splice 写回\n   * - 非响应式纯数组：作为初始值由内部响应式副本持有，写回时顺带同步原数组\n   * - getter / 只读 computed：只读数据源，通过 `onReorder` 接收写回结果\n   * - 不传：内部创建数据源，通过返回的 `values` 读写\n   */\n  values?: MaybeRefOrGetter<T[]>\n  /**\n   * 数据过滤：仅命中的项参与拖拽排序（须与 DOM 中实际渲染的可拖拽项一一对应）。\n   * 排序/转移结果自动合并回原数组，未命中的项保持相对顺序。\n   */\n  filter?: (item: T) => boolean\n  /**\n   * 容器元素。支持 ref / getter（如 `() => btnRef.value?.parentElement`），\n   * 元素出现、替换、移除时自动初始化 / 重建 / 销毁拖拽实例。\n   * 不传时通过返回的 `parentRef` 以模板引用绑定。\n   */\n  parent?: MaybeRefOrGetter<HTMLElement | undefined>\n  /**\n   * `values` 为只读数据源（getter / 只读 computed）时，\n   * 排序/转移结果通过该回调写回，收到的是合并后的完整数组\n   */\n  onReorder?: (values: T[]) => void\n}\n\nexport interface UseDnDResult<T> {\n  /** 拖拽容器元素；未传 `parent` 选项时通过模板引用绑定到列表容器上 */\n  parentRef: Ref<HTMLElement | undefined>\n  /** 拖拽数据。`filter` 模式下为参与拖拽的视图；排序/转移后自动更新 */\n  values: Ref<T[]>\n  /**\n   * 运行时更新拖拽配置（整体替换，不含 `values` / `filter` / `parent` / `onReorder`）\n   * @param config 新配置\n   */\n  updateConfig: (config?: VueParentConfig<T>) => void\n}\n\n/**\n * 拖拽排序组合式方法，基于 `@formkit/drag-and-drop` 的 Vue 适配层封装。\n *\n * 排序/跨容器转移结果自动写回数据，无需手动处理 `onSort`；\n * `filter` 支持只对数据的可见子集排序并自动合并回原数组；\n * `parent` 支持动态容器（元素替换/重建时自动重新初始化）。\n * 组件卸载时自动销毁拖拽实例。\n *\n * @example 基础用法：列表即数据，排序自动写回\n * ```ts\n * const { parentRef, values } = useDnD({ values: list, plugins: [animations()] })\n * ```\n *\n * ```vue\n * <ul ref=\"parentRef\">\n *   <li v-for=\"item in values\" :key=\"item.id\">{{ item.label }}</li>\n * </ul>\n * ```\n *\n * @example 可见子集排序 + 动态容器\n * ```ts\n * useDnD({\n *   values: props.items, // 完整数据（含隐藏项），原地写回\n *   filter: (item) => item.visible, // 仅可见项参与拖拽，排序自动合并回原数组\n *   parent: () => addBtnRef.value?.parentElement ?? undefined, // 容器动态获取\n *   dragHandle: '.u-form-item__label',\n *   draggable: (el) => el.classList.contains('setting-trigger'), // 排除“新增”按钮\n *   plugins: [animations()]\n * })\n * ```\n */\nexport function useDnD<T>(options: UseDnDOptions<T> = {}): UseDnDResult<T> {\n  const {\n    values: valuesOption,\n    filter,\n    parent: parentOption,\n    onReorder,\n    ...initialConfig\n  } = options\n\n  const parentRef = ref<HTMLElement>()\n  const internalValues = ref<T[]>([]) as Ref<T[]>\n  let currentConfig = initialConfig\n\n  // 非响应式纯数组无法被追踪：由内部 ref 持有数据驱动视图，写回时顺带同步原数组\n  const useInternal =\n    valuesOption === undefined ||\n    (Array.isArray(valuesOption) && !isReactive(valuesOption) && !isReadonly(valuesOption))\n  if (useInternal && valuesOption) internalValues.value = valuesOption\n\n  function readSource(): T[] {\n    if (useInternal) return internalValues.value\n    return toValue(valuesOption as MaybeRefOrGetter<T[]>) ?? []\n  }\n\n  function writeSource(next: T[]) {\n    if (useInternal) {\n      internalValues.value = next\n      if (valuesOption) (valuesOption as T[]).splice(0, (valuesOption as T[]).length, ...next)\n      return\n    }\n    if (isRef(valuesOption)) {\n      // 可写 ref / 可写 computed 直接写回；只读 computed 走 onReorder\n      if (isReadonly(valuesOption)) onReorder?.(next)\n      else (valuesOption as Ref<T[]>).value = next\n      return\n    }\n    if (Array.isArray(valuesOption)) {\n      if (isReadonly(valuesOption)) onReorder?.(next)\n      else valuesOption.splice(0, valuesOption.length, ...next)\n      return\n    }\n    onReorder?.(next)\n  }\n\n  /**\n   * 交给拖拽库的数据（视图）。库排序/转移后通过 setter 写回，\n   * setter 将视图结果合并回完整数据源。\n   */\n  const dndValues = computed<T[]>({\n    get: () => {\n      const source = readSource()\n      return filter ? source.filter(filter) : source\n    },\n    set: (nextView) => {\n      if (!filter) {\n        writeSource(nextView)\n        return\n      }\n      const source = readSource()\n      writeSource(mergeView(source, source.filter(filter), nextView))\n    }\n  })\n\n  /** 当前生效的容器元素：`parent` 选项优先，否则用模板引用 */\n  const resolvedParent = computed<HTMLElement | undefined>(() =>\n    parentOption === undefined ? parentRef.value : toValue(parentOption)\n  )\n\n  function init(parent: HTMLElement) {\n    dragAndDrop({ parent, values: dndValues, ...currentConfig })\n  }\n\n  function updateConfig(newConfig: VueParentConfig<T> = {}) {\n    currentConfig = newConfig\n    if (resolvedParent.value) init(resolvedParent.value)\n  }\n\n  // 容器出现 / 替换 / 移除时自动初始化 / 重建 / 销毁；\n  // flush: 'post' 保证模板引用与 DOM 已更新\n  watch(\n    resolvedParent,\n    (parent, prev) => {\n      if (prev && prev !== parent) tearDown(prev)\n      if (parent) init(parent)\n    },\n    { flush: 'post', immediate: true }\n  )\n\n  onBeforeUnmount(() => {\n    if (resolvedParent.value) tearDown(resolvedParent.value)\n  })\n\n  return { parentRef, values: dndValues, updateConfig }\n}\n\n// 重导出 `@formkit/drag-and-drop`，下游项目统一从 `@veltra/compositions` 获取，\n// 避免本库与下游各自安装导致版本不一致（体积膨胀 / 兼容问题）。\nexport {\n  // Vue 适配层原始 API\n  dragAndDrop,\n  useDragAndDrop,\n  type VueDragAndDropData,\n  type VueElement,\n  type VueParentConfig\n} from '@formkit/drag-and-drop/vue'\n\nexport {\n  // 插件\n  animations,\n  dropOrSwap,\n  insert,\n  // 操作与状态工具\n  performSort,\n  performTransfer,\n  remapNodes,\n  updateConfig,\n  parentValues,\n  setParentValues,\n  dragValues,\n  isDragState,\n  isSynthDragState,\n  isBrowser,\n  tearDown,\n  // 类型\n  type ParentConfig,\n  type ParentData,\n  type ParentRecord,\n  type Node,\n  type NodeData,\n  type NodeRecord,\n  type NodeTargetData,\n  type ParentTargetData,\n  type BaseDragState,\n  type DragState,\n  type SynthDragState,\n  type NativeDragEffects,\n  type DNDPlugin,\n  type DNDPluginData,\n  type NodeEventData,\n  type NodeDragEventData,\n  type NodePointerEventData,\n  type ParentEventData,\n  type ParentDragEventData,\n  type SortEvent,\n  type SortEventData,\n  type TransferEvent,\n  type TransferEventData,\n  type DragstartEvent,\n  type DragstartEventData,\n  type DragendEvent,\n  type DragendEventData,\n  type ShouldSwapData,\n  type DropSwapConfig,\n  type InsertConfig,\n  type InsertEvent,\n  type SetupNode,\n  type SetupNodeData,\n  type TearDownNode,\n  type TearDownNodeData,\n  type PointeroverNodeEvent,\n  type PointeroverParentEvent\n} from '@formkit/drag-and-drop'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,OAAU,UAA4B,CAAC,GAAoB;CACzE,MAAM,EACJ,QAAQ,cACR,QACA,QAAQ,cACR,WACA,GAAG,kBACD;CAEJ,MAAM,YAAY,IAAiB;CACnC,MAAM,iBAAiB,IAAS,CAAC,CAAC;CAClC,IAAI,gBAAgB;CAGpB,MAAM,cACJ,iBAAiB,KAAA,KAChB,MAAM,QAAQ,YAAY,KAAK,CAAC,WAAW,YAAY,KAAK,CAAC,WAAW,YAAY;CACvF,IAAI,eAAe,cAAc,eAAe,QAAQ;CAExD,SAAS,aAAkB;EACzB,IAAI,aAAa,OAAO,eAAe;EACvC,OAAO,QAAQ,YAAqC,KAAK,CAAC;CAC5D;CAEA,SAAS,YAAY,MAAW;EAC9B,IAAI,aAAa;GACf,eAAe,QAAQ;GACvB,IAAI,cAAc,aAAsB,OAAO,GAAI,aAAqB,QAAQ,GAAG,IAAI;GACvF;EACF;EACA,IAAI,MAAM,YAAY,GAAG;GAEvB,IAAI,WAAW,YAAY,GAAG,YAAY,IAAI;QACzC,aAA2B,QAAQ;GACxC;EACF;EACA,IAAI,MAAM,QAAQ,YAAY,GAAG;GAC/B,IAAI,WAAW,YAAY,GAAG,YAAY,IAAI;QACzC,aAAa,OAAO,GAAG,aAAa,QAAQ,GAAG,IAAI;GACxD;EACF;EACA,YAAY,IAAI;CAClB;;;;;CAMA,MAAM,YAAY,SAAc;EAC9B,WAAW;GACT,MAAM,SAAS,WAAW;GAC1B,OAAO,SAAS,OAAO,OAAO,MAAM,IAAI;EAC1C;EACA,MAAM,aAAa;GACjB,IAAI,CAAC,QAAQ;IACX,YAAY,QAAQ;IACpB;GACF;GACA,MAAM,SAAS,WAAW;GAC1B,YAAY,UAAU,QAAQ,OAAO,OAAO,MAAM,GAAG,QAAQ,CAAC;EAChE;CACF,CAAC;;CAGD,MAAM,iBAAiB,eACrB,iBAAiB,KAAA,IAAY,UAAU,QAAQ,QAAQ,YAAY,CACrE;CAEA,SAAS,KAAK,QAAqB;EACjC,YAAY;GAAE;GAAQ,QAAQ;GAAW,GAAG;EAAc,CAAC;CAC7D;CAEA,SAAS,aAAa,YAAgC,CAAC,GAAG;EACxD,gBAAgB;EAChB,IAAI,eAAe,OAAO,KAAK,eAAe,KAAK;CACrD;CAIA,MACE,iBACC,QAAQ,SAAS;EAChB,IAAI,QAAQ,SAAS,QAAQ,SAAS,IAAI;EAC1C,IAAI,QAAQ,KAAK,MAAM;CACzB,GACA;EAAE,OAAO;EAAQ,WAAW;CAAK,CACnC;CAEA,sBAAsB;EACpB,IAAI,eAAe,OAAO,SAAS,eAAe,KAAK;CACzD,CAAC;CAED,OAAO;EAAE;EAAW,QAAQ;EAAW;CAAa;AACtD"}

package/dist/use-dnd/merge-view.js

@@ -0,0 +1,43 @@
+//#region src/use-dnd/merge-view.ts
+/**
+* 将“拖拽视图”的新顺序稳定合并回完整数组。
+*
+* 视图是完整数组中参与拖拽排序的项（`filter` 命中的项），与 DOM 中可拖拽节点一一对应。
+* 合并规则：
+* - 未参与拖拽的项保持相对顺序（锚定在其前驱可见项之后）
+* - 旧视图成员按新视图顺序重排（排序）
+* - 新视图中缺少的旧成员被移除（跨容器移出）
+* - 新视图中多出的成员按相对位置插入（跨容器移入）
+*
+* @param source 完整数组
+* @param prevView 排序前的视图
+* @param nextView 排序/转移后的视图
+* @returns 合并后的新数组（不修改入参）
+*/
+function mergeView(source, prevView, nextView) {
+	const prevSet = new Set(prevView);
+	const nextSet = new Set(nextView);
+	const placed = /* @__PURE__ */ new Set();
+	const queue = [...nextView];
+	const result = [];
+	for (const item of source) {
+		if (!prevSet.has(item)) {
+			result.push(item);
+			continue;
+		}
+		if (!nextSet.has(item) || placed.has(item)) continue;
+		while (queue.length > 0 && queue[0] !== item) {
+			const head = queue.shift();
+			result.push(head);
+			if (prevSet.has(head)) placed.add(head);
+		}
+		queue.shift();
+		placed.add(item);
+		result.push(item);
+	}
+	return result.concat(queue);
+}
+//#endregion
+export { mergeView };
+
+//# sourceMappingURL=merge-view.js.map

package/dist/use-dnd/merge-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-view.js","names":[],"sources":["../../src/use-dnd/merge-view.ts"],"sourcesContent":["/**\n * 将“拖拽视图”的新顺序稳定合并回完整数组。\n *\n * 视图是完整数组中参与拖拽排序的项（`filter` 命中的项），与 DOM 中可拖拽节点一一对应。\n * 合并规则：\n * - 未参与拖拽的项保持相对顺序（锚定在其前驱可见项之后）\n * - 旧视图成员按新视图顺序重排（排序）\n * - 新视图中缺少的旧成员被移除（跨容器移出）\n * - 新视图中多出的成员按相对位置插入（跨容器移入）\n *\n * @param source 完整数组\n * @param prevView 排序前的视图\n * @param nextView 排序/转移后的视图\n * @returns 合并后的新数组（不修改入参）\n */\nexport function mergeView<T>(\n  source: readonly T[],\n  prevView: readonly T[],\n  nextView: readonly T[]\n): T[] {\n  const prevSet = new Set(prevView)\n  const nextSet = new Set(nextView)\n  const placed = new Set<T>()\n  const queue = [...nextView]\n  const result: T[] = []\n\n  for (const item of source) {\n    // 未参与拖拽的项原位保留\n    if (!prevSet.has(item)) {\n      result.push(item)\n      continue\n    }\n    // 已从新视图移除（跨容器移出），或已按新顺序放置过\n    if (!nextSet.has(item) || placed.has(item)) continue\n    // 先放出新视图中排在它前面的项（含跨容器移入的新成员）\n    while (queue.length > 0 && queue[0] !== item) {\n      const head = queue.shift()!\n      result.push(head)\n      if (prevSet.has(head)) placed.add(head)\n    }\n    queue.shift()\n    placed.add(item)\n    result.push(item)\n  }\n\n  // 新视图尾部多出的成员追加到末尾\n  return result.concat(queue)\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,SAAgB,UACd,QACA,UACA,UACK;CACL,MAAM,UAAU,IAAI,IAAI,QAAQ;CAChC,MAAM,UAAU,IAAI,IAAI,QAAQ;CAChC,MAAM,yBAAS,IAAI,IAAO;CAC1B,MAAM,QAAQ,CAAC,GAAG,QAAQ;CAC1B,MAAM,SAAc,CAAC;CAErB,KAAK,MAAM,QAAQ,QAAQ;EAEzB,IAAI,CAAC,QAAQ,IAAI,IAAI,GAAG;GACtB,OAAO,KAAK,IAAI;GAChB;EACF;EAEA,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,GAAG;EAE5C,OAAO,MAAM,SAAS,KAAK,MAAM,OAAO,MAAM;GAC5C,MAAM,OAAO,MAAM,MAAM;GACzB,OAAO,KAAK,IAAI;GAChB,IAAI,QAAQ,IAAI,IAAI,GAAG,OAAO,IAAI,IAAI;EACxC;EACA,MAAM,MAAM;EACZ,OAAO,IAAI,IAAI;EACf,OAAO,KAAK,IAAI;CAClB;CAGA,OAAO,OAAO,OAAO,KAAK;AAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/compositions",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "files": [
     "dist",
     "src"
@@ -22,7 +22,7 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.1.8",
     "@cat-kit/fe": ">=1.1.8",
-    "@veltra/utils": "1.3.8",
+    "@veltra/utils": "1.3.9",
     "vue": ">=3.5.40"
   }
 }

package/src/use-dnd/__test__/use-dnd.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it, vi } from 'vitest'
+import { computed, createApp, reactive, ref } from 'vue'
+
+import { useDnD, type UseDnDResult } from '../index'
+import { mergeView } from '../merge-view'
+
+/** 在组件 setup 上下文中执行组合式函数（提供生命周期与 effect scope） */
+function withSetup<T>(fn: () => T): T {
+  let result!: T
+  const app = createApp({
+    setup() {
+      result = fn()
+      return () => null
+    }
+  })
+  app.mount(document.createElement('div'))
+  return result
+}
+
+describe('mergeView', () => {
+  it('排序：视图重排合并回完整数组，未参与项保持相对顺序', () => {
+    const [a, b, c, h1, h2] = ['a', 'b', 'c', 'h1', 'h2']
+    const source = [h1, a, b, h2, c]
+    // 隐藏项锚定在其前驱可见项之后：h2 跟随 b
+    expect(mergeView(source, [a, b, c], [c, a, b])).toEqual([h1, c, a, b, h2])
+  })
+
+  it('完全逆序', () => {
+    const [a, b] = ['a', 'b']
+    expect(mergeView([a, b], [a, b], [b, a])).toEqual([b, a])
+  })
+
+  it('跨容器移出：新视图缺少的成员从源数组移除', () => {
+    const [a, b, c, h] = ['a', 'b', 'c', 'h']
+    expect(mergeView([a, h, b, c], [a, b, c], [a, c])).toEqual([a, h, c])
+  })
+
+  it('跨容器移入：新成员按相对位置插入（头部 / 中间 / 末尾）', () => {
+    const [a, b, x, y, z, h] = ['a', 'b', 'x', 'y', 'z', 'h']
+    expect(mergeView([a, b], [a, b], [x, a, b])).toEqual([x, a, b])
+    expect(mergeView([a, h, b], [a, b], [a, y, b])).toEqual([a, h, y, b])
+    expect(mergeView([a, b], [a, b], [a, b, z])).toEqual([a, b, z])
+  })
+
+  it('不修改入参', () => {
+    const [a, b] = ['a', 'b']
+    const source = [a, b]
+    mergeView(source, [a, b], [b, a])
+    expect(source).toEqual([a, b])
+  })
+})
+
+describe('useDnD 数据写回', () => {
+  function sortBySetter<T>(dnd: UseDnDResult<T>, next: T[]) {
+    // 模拟库排序后通过 setValues 写回
+    dnd.values.value = next
+  }
+
+  it('ref 数据源：排序结果直接写回 ref', () => {
+    const list = ref([{ id: 'a' }, { id: 'b' }])
+    const dnd = withSetup(() => useDnD({ values: list }))
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(list.value.map((i) => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('响应式数组数据源：原地 splice 写回', () => {
+    const items = reactive([{ id: 'a' }, { id: 'b' }])
+    const dnd = withSetup(() => useDnD({ values: items }))
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(items.map((i) => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('filter 模式：仅可见项参与排序，结果自动合并回原数组', () => {
+    const items = reactive([
+      { id: 'h1', visible: false },
+      { id: 'a', visible: true },
+      { id: 'h2', visible: false },
+      { id: 'b', visible: true }
+    ])
+    const dnd = withSetup(() => useDnD({ values: items, filter: (i) => i.visible }))
+
+    expect(dnd.values.value.map((i) => i.id)).toEqual(['a', 'b'])
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(items.map((i) => i.id)).toEqual(['h1', 'b', 'a', 'h2'])
+  })
+
+  it('filter 模式：跨容器移出时移除对应源数据项', () => {
+    const items = reactive([
+      { id: 'a', visible: true },
+      { id: 'h', visible: false },
+      { id: 'b', visible: true }
+    ])
+    const dnd = withSetup(() => useDnD({ values: items, filter: (i) => i.visible }))
+
+    const [, b] = dnd.values.value
+    // b 被移出到其他容器
+    sortBySetter(dnd, [b!].slice(0, 0).concat(dnd.values.value.filter((i) => i.id === 'a')))
+
+    expect(items.map((i) => i.id)).toEqual(['a', 'h'])
+  })
+
+  it('非响应式纯数组数据源：内部副本驱动视图，原数组保持同步', () => {
+    const items = [{ id: 'a' }, { id: 'b' }]
+    const dnd = withSetup(() => useDnD({ values: items }))
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    // 返回的 values 已更新（内部响应式副本）
+    expect(dnd.values.value.map((i) => i.id)).toEqual(['b', 'a'])
+    // 原数组同步
+    expect(items.map((i) => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('getter 数据源：通过 onReorder 接收合并后的完整数组', () => {
+    const items = reactive([
+      { id: 'a', visible: true },
+      { id: 'h', visible: false },
+      { id: 'b', visible: true }
+    ])
+    const onReorder = vi.fn()
+    const dnd = withSetup(() =>
+      useDnD({ values: () => items, filter: (i) => i.visible, onReorder })
+    )
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(onReorder).toHaveBeenCalledTimes(1)
+    expect(onReorder.mock.calls[0]![0].map((i: { id: string }) => i.id)).toEqual(['b', 'a', 'h'])
+  })
+
+  it('只读 computed 数据源：通过 onReorder 写回', () => {
+    const list = ref([{ id: 'a' }, { id: 'b' }])
+    const onReorder = vi.fn()
+    const dnd = withSetup(() => useDnD({ values: computed(() => list.value), onReorder }))
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(onReorder).toHaveBeenCalledTimes(1)
+    expect(list.value.map((i) => i.id)).toEqual(['a', 'b'])
+  })
+
+  it('可写 computed 数据源：排序结果进入其 setter', () => {
+    const list = ref([{ id: 'a' }, { id: 'b' }])
+    const setter = vi.fn()
+    const dnd = withSetup(() =>
+      useDnD({ values: computed({ get: () => list.value, set: setter }) })
+    )
+
+    const [a, b] = dnd.values.value
+    sortBySetter(dnd, [b!, a!])
+
+    expect(setter).toHaveBeenCalledTimes(1)
+    expect(setter.mock.calls[0]![0].map((i: { id: string }) => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('外部数据变化时视图自动更新', () => {
+    const items = reactive([{ id: 'a', visible: true }])
+    const dnd = withSetup(() => useDnD({ values: items, filter: (i) => i.visible }))
+
+    items.push({ id: 'b', visible: true })
+
+    expect(dnd.values.value.map((i) => i.id)).toEqual(['a', 'b'])
+  })
+})

package/src/use-dnd/index.ts

@@ -1,22 +1,55 @@
 import { tearDown } from '@formkit/drag-and-drop'
 import { dragAndDrop, type VueParentConfig } from '@formkit/drag-and-drop/vue'
-import { isRef, onBeforeUnmount, ref, type Ref } from 'vue'
+import {
+  computed,
+  isReactive,
+  isReadonly,
+  isRef,
+  onBeforeUnmount,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref
+} from 'vue'
+
+import { mergeView } from './merge-view'
 
 export interface UseDnDOptions<T> extends VueParentConfig<T> {
   /**
-   * 列表数据。传入 ref 时与外部共享同一个引用，拖拽排序/转移后直接写回；
-   * 传入普通数组或不传时内部创建 ref。
+   * 列表数据。排序/跨容器转移后自动写回：
+   * - `Ref`：直接替换 `.value`
+   * - 响应式数组（如 props 上的数组）：原地 splice 写回
+   * - 非响应式纯数组：作为初始值由内部响应式副本持有，写回时顺带同步原数组
+   * - getter / 只读 computed：只读数据源，通过 `onReorder` 接收写回结果
+   * - 不传：内部创建数据源，通过返回的 `values` 读写
+   */
+  values?: MaybeRefOrGetter<T[]>
+  /**
+   * 数据过滤：仅命中的项参与拖拽排序（须与 DOM 中实际渲染的可拖拽项一一对应）。
+   * 排序/转移结果自动合并回原数组，未命中的项保持相对顺序。
+   */
+  filter?: (item: T) => boolean
+  /**
+   * 容器元素。支持 ref / getter（如 `() => btnRef.value?.parentElement`），
+   * 元素出现、替换、移除时自动初始化 / 重建 / 销毁拖拽实例。
+   * 不传时通过返回的 `parentRef` 以模板引用绑定。
+   */
+  parent?: MaybeRefOrGetter<HTMLElement | undefined>
+  /**
+   * `values` 为只读数据源（getter / 只读 computed）时，
+   * 排序/转移结果通过该回调写回，收到的是合并后的完整数组
    */
-  values?: T[] | Ref<T[]>
+  onReorder?: (values: T[]) => void
 }
 
 export interface UseDnDResult<T> {
-  /** 拖拽容器元素，通过 `ref` 绑定到列表容器元素上 */
+  /** 拖拽容器元素；未传 `parent` 选项时通过模板引用绑定到列表容器上 */
   parentRef: Ref<HTMLElement | undefined>
-  /** 列表数据，排序/跨容器转移后自动更新 */
+  /** 拖拽数据。`filter` 模式下为参与拖拽的视图；排序/转移后自动更新 */
   values: Ref<T[]>
   /**
-   * 运行时更新拖拽配置（整体替换，不与初始配置合并）
+   * 运行时更新拖拽配置（整体替换，不含 `values` / `filter` / `parent` / `onReorder`）
    * @param config 新配置
    */
   updateConfig: (config?: VueParentConfig<T>) => void
@@ -25,16 +58,14 @@ export interface UseDnDResult<T> {
 /**
  * 拖拽排序组合式方法，基于 `@formkit/drag-and-drop` 的 Vue 适配层封装。
  *
- * 相比官方 `useDragAndDrop` 的元组返回，这里使用 options 对象传参并返回命名结果。
+ * 排序/跨容器转移结果自动写回数据，无需手动处理 `onSort`；
+ * `filter` 支持只对数据的可见子集排序并自动合并回原数组；
+ * `parent` 支持动态容器（元素替换/重建时自动重新初始化）。
  * 组件卸载时自动销毁拖拽实例。
  *
- * @example
+ * @example 基础用法：列表即数据，排序自动写回
  * ```ts
- * const { parentRef, values } = useDnD({
- *   values: list,
- *   plugins: [animations()],
- *   onSort: ({ previousValues, values }) => {}
- * })
+ * const { parentRef, values } = useDnD({ values: list, plugins: [animations()] })
  * ```
  *
  * ```vue
@@ -42,24 +73,112 @@ export interface UseDnDResult<T> {
  *   <li v-for="item in values" :key="item.id">{{ item.label }}</li>
  * </ul>
  * ```
+ *
+ * @example 可见子集排序 + 动态容器
+ * ```ts
+ * useDnD({
+ *   values: props.items, // 完整数据（含隐藏项），原地写回
+ *   filter: (item) => item.visible, // 仅可见项参与拖拽，排序自动合并回原数组
+ *   parent: () => addBtnRef.value?.parentElement ?? undefined, // 容器动态获取
+ *   dragHandle: '.u-form-item__label',
+ *   draggable: (el) => el.classList.contains('setting-trigger'), // 排除“新增”按钮
+ *   plugins: [animations()]
+ * })
+ * ```
  */
 export function useDnD<T>(options: UseDnDOptions<T> = {}): UseDnDResult<T> {
-  const { values: initialValues, ...config } = options
+  const {
+    values: valuesOption,
+    filter,
+    parent: parentOption,
+    onReorder,
+    ...initialConfig
+  } = options
 
   const parentRef = ref<HTMLElement>()
-  const values = isRef(initialValues) ? initialValues : (ref(initialValues ?? []) as Ref<T[]>)
+  const internalValues = ref<T[]>([]) as Ref<T[]>
+  let currentConfig = initialConfig
+
+  // 非响应式纯数组无法被追踪：由内部 ref 持有数据驱动视图，写回时顺带同步原数组
+  const useInternal =
+    valuesOption === undefined ||
+    (Array.isArray(valuesOption) && !isReactive(valuesOption) && !isReadonly(valuesOption))
+  if (useInternal && valuesOption) internalValues.value = valuesOption
+
+  function readSource(): T[] {
+    if (useInternal) return internalValues.value
+    return toValue(valuesOption as MaybeRefOrGetter<T[]>) ?? []
+  }
+
+  function writeSource(next: T[]) {
+    if (useInternal) {
+      internalValues.value = next
+      if (valuesOption) (valuesOption as T[]).splice(0, (valuesOption as T[]).length, ...next)
+      return
+    }
+    if (isRef(valuesOption)) {
+      // 可写 ref / 可写 computed 直接写回；只读 computed 走 onReorder
+      if (isReadonly(valuesOption)) onReorder?.(next)
+      else (valuesOption as Ref<T[]>).value = next
+      return
+    }
+    if (Array.isArray(valuesOption)) {
+      if (isReadonly(valuesOption)) onReorder?.(next)
+      else valuesOption.splice(0, valuesOption.length, ...next)
+      return
+    }
+    onReorder?.(next)
+  }
+
+  /**
+   * 交给拖拽库的数据（视图）。库排序/转移后通过 setter 写回，
+   * setter 将视图结果合并回完整数据源。
+   */
+  const dndValues = computed<T[]>({
+    get: () => {
+      const source = readSource()
+      return filter ? source.filter(filter) : source
+    },
+    set: (nextView) => {
+      if (!filter) {
+        writeSource(nextView)
+        return
+      }
+      const source = readSource()
+      writeSource(mergeView(source, source.filter(filter), nextView))
+    }
+  })
+
+  /** 当前生效的容器元素：`parent` 选项优先，否则用模板引用 */
+  const resolvedParent = computed<HTMLElement | undefined>(() =>
+    parentOption === undefined ? parentRef.value : toValue(parentOption)
+  )
+
+  function init(parent: HTMLElement) {
+    dragAndDrop({ parent, values: dndValues, ...currentConfig })
+  }
 
   function updateConfig(newConfig: VueParentConfig<T> = {}) {
-    dragAndDrop({ parent: parentRef, values, ...newConfig })
+    currentConfig = newConfig
+    if (resolvedParent.value) init(resolvedParent.value)
   }
 
-  updateConfig(config)
+  // 容器出现 / 替换 / 移除时自动初始化 / 重建 / 销毁；
+  // flush: 'post' 保证模板引用与 DOM 已更新
+  watch(
+    resolvedParent,
+    (parent, prev) => {
+      if (prev && prev !== parent) tearDown(prev)
+      if (parent) init(parent)
+    },
+    { flush: 'post', immediate: true }
+  )
 
   onBeforeUnmount(() => {
-    parentRef.value && tearDown(parentRef.value)
+    if (resolvedParent.value) tearDown(resolvedParent.value)
   })
 
-  return { parentRef, values, updateConfig }
+  return { parentRef, values: dndValues, updateConfig }
 }
 
 // 重导出 `@formkit/drag-and-drop`，下游项目统一从 `@veltra/compositions` 获取，

package/src/use-dnd/merge-view.ts

@@ -0,0 +1,48 @@
+/**
+ * 将“拖拽视图”的新顺序稳定合并回完整数组。
+ *
+ * 视图是完整数组中参与拖拽排序的项（`filter` 命中的项），与 DOM 中可拖拽节点一一对应。
+ * 合并规则：
+ * - 未参与拖拽的项保持相对顺序（锚定在其前驱可见项之后）
+ * - 旧视图成员按新视图顺序重排（排序）
+ * - 新视图中缺少的旧成员被移除（跨容器移出）
+ * - 新视图中多出的成员按相对位置插入（跨容器移入）
+ *
+ * @param source 完整数组
+ * @param prevView 排序前的视图
+ * @param nextView 排序/转移后的视图
+ * @returns 合并后的新数组（不修改入参）
+ */
+export function mergeView<T>(
+  source: readonly T[],
+  prevView: readonly T[],
+  nextView: readonly T[]
+): T[] {
+  const prevSet = new Set(prevView)
+  const nextSet = new Set(nextView)
+  const placed = new Set<T>()
+  const queue = [...nextView]
+  const result: T[] = []
+
+  for (const item of source) {
+    // 未参与拖拽的项原位保留
+    if (!prevSet.has(item)) {
+      result.push(item)
+      continue
+    }
+    // 已从新视图移除（跨容器移出），或已按新顺序放置过
+    if (!nextSet.has(item) || placed.has(item)) continue
+    // 先放出新视图中排在它前面的项（含跨容器移入的新成员）
+    while (queue.length > 0 && queue[0] !== item) {
+      const head = queue.shift()!
+      result.push(head)
+      if (prevSet.has(head)) placed.add(head)
+    }
+    queue.shift()
+    placed.add(item)
+    result.push(item)
+  }
+
+  // 新视图尾部多出的成员追加到末尾
+  return result.concat(queue)
+}