@splicetree/adapter-vue 0.0.1

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,56 @@
+# @splicetree/adapter-vue
+
+[![version](https://img.shields.io/npm/v/@splicetree/adapter-vue.svg?label=version)](https://www.npmjs.com/package/@splicetree/adapter-vue)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/adapter-vue.svg)](https://npmcharts.com/compare/%40splicetree%2Fadapter-vue?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/adapter-vue.svg)](https://www.npmjs.com/package/@splicetree/adapter-vue)
+[![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)
+
+提供响应式 `items` 与操作方法，自动监听核心事件刷新视图。
+
+## 简介
+
+SpliceTree Vue 适配层，将核心 `items()` 适配为 `shallowRef` 响应式数据，并复用核心 API。
+
+## 官方文档
+
+文档与示例位于 [https://www.splicetree.dev](https://www.splicetree.dev)
+
+## 安装
+
+```sh
+pnpm add @splicetree/adapter-vue
+```
+
+## 使用
+
+```ts
+import { useSpliceTree } from '@splicetree/adapter-vue'
+
+const { items, expand, collapse, toggleExpand } = useSpliceTree(data, {
+  defaultExpanded: ['a'],
+})
+
+// 在组件中渲染
+// <template>
+//   <div v-for="n in items" :key="n.id">{{ n.original.title }}</div>
+// </template>
+```
+
+## 返回值
+
+- `items: ShallowRef<SpliceTreeNode[]>` 响应式可见节点列表
+- 其余方法属性与核心一致（除 `items()`）
+
+## 选项（继承 Core）
+
+| 名称              | 类型                 | 默认值     | 说明         |
+| ----------------- | -------------------- | ---------- | ------------ |
+| `keyField`        | `string`             | `'id'`     | 主键字段名   |
+| `parentField`     | `string`             | `'parent'` | 父级字段名   |
+| `plugins`         | `SpliceTreePlugin[]` | `[]`       | 插件列表     |
+| `defaultExpanded` | `string[]`           | `[]`       | 初始展开集合 |
+
+## License
+
+[MIT](https://github.com/michaelcocova/splicetree/blob/main/LICENSE)，仓库地址 [https://github.com/michaelcocova/splicetree](https://github.com/michaelcocova/splicetree)

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Ref, ShallowRef, WritableComputedRef } from "vue";
+import { SpliceTreeData, SpliceTreeData as SpliceTreeData$1, SpliceTreeInstance, SpliceTreeInstance as SpliceTreeInstance$1, SpliceTreeNode, SpliceTreeNode as SpliceTreeNode$1, UseSpliceTreeOptions, UseSpliceTreeOptions as UseSpliceTreeOptions$1 } from "@splicetree/core";
+
+//#region src/index.d.ts
+interface UseSpliceTreeReturn<T extends SpliceTreeData$1 = SpliceTreeData$1> extends ShallowRef<Omit<SpliceTreeInstance$1<T>, 'items'>> {
+  items: ShallowRef<SpliceTreeNode$1<T>[]>;
+}
+/**
+ * Vue 3 适配器
+ * - 以 shallowRef 暴露 items，使其在核心派发 visibility 事件时刷新
+ * - 保留核心 API 的完整返回（展开/收起/移动等方法）
+ * - 适用于任意自定义渲染逻辑与组件绑定
+ */
+declare function useSpliceTree<T extends SpliceTreeData$1 = SpliceTreeData$1>(data: Ref<T[]> | T[] | WritableComputedRef<T[]>, options?: UseSpliceTreeOptions$1<T>): UseSpliceTreeReturn<T>;
+//#endregion
+export { type SpliceTreeData, type SpliceTreeInstance, type SpliceTreeNode, type UseSpliceTreeOptions, UseSpliceTreeReturn, useSpliceTree };

package/dist/index.js

@@ -0,0 +1,450 @@
+import { shallowRef, toValue, watch } from "vue";
+
+//#region ../../core/dist/index.js
+/**
+* 轻量事件总线：支持订阅与派发，供核心与插件通信
+*/
+function createEmitter() {
+	const listeners = /* @__PURE__ */ new Map();
+	const on = (name, handler) => {
+		if (!listeners.has(name)) listeners.set(name, /* @__PURE__ */ new Set());
+		const set = listeners.get(name);
+		set.add(handler);
+		return () => set.delete(handler);
+	};
+	const emit = (payload) => {
+		const set = listeners.get(payload.name);
+		if (!set) return;
+		for (const h of set) h(payload);
+	};
+	return {
+		on,
+		emit
+	};
+}
+/**
+* 创建运行时树节点，并注入必要的 API
+*/
+function createSpliceTreeNode(id, original, api) {
+	return {
+		id,
+		original,
+		level: 0,
+		isExpanded: api.isExpanded,
+		hasChildren: api.hasChildren,
+		getParent: api.getParent,
+		getChildren: api.getChildren,
+		toggleExpand: api.toggleExpand
+	};
+}
+/**
+* 基于扁平数据构建树结构缓存
+* - by id 的节点 map
+* - parent/children 缓存
+* - 根节点列表
+* 并计算每个节点的 level
+*/
+function buildTree(data, keyField, parentField, expandedKeys = /* @__PURE__ */ new Set()) {
+	const map = /* @__PURE__ */ new Map();
+	const roots = [];
+	const parentCache = /* @__PURE__ */ new Map();
+	const childrenCache = /* @__PURE__ */ new Map();
+	data.forEach((item) => {
+		const id = String(Reflect.get(item, keyField || "id"));
+		const node = createSpliceTreeNode(id, item, {
+			hasChildren: () => !!childrenCache.get(id)?.length,
+			getParent: () => parentCache.get(id),
+			getChildren: () => childrenCache.get(id) ?? [],
+			isExpanded: () => expandedKeys.has(id),
+			toggleExpand: () => {
+				if (expandedKeys.has(id)) expandedKeys.delete(id);
+				else expandedKeys.add(id);
+			}
+		});
+		map.set(id, node);
+	});
+	for (const id of map.keys()) childrenCache.set(id, []);
+	for (const node of map.values()) {
+		const parentId = Reflect.get(node.original, parentField || "parentId");
+		if (!parentId) {
+			parentCache.set(node.id, void 0);
+			roots.push(node);
+			continue;
+		}
+		const parentNode = map.get(String(parentId));
+		parentCache.set(node.id, parentNode ?? void 0);
+		if (parentNode) childrenCache.get(parentNode.id).push(node);
+		else roots.push(node);
+	}
+	const dfs = (node, level) => {
+		node.level = level;
+		for (const child of childrenCache.get(node.id) ?? []) dfs(child, level + 1);
+	};
+	for (const r of roots) dfs(r, 0);
+	return {
+		roots,
+		map,
+		parentCache,
+		childrenCache
+	};
+}
+function initDefaultExpansion(map, expanded, def, lvl) {
+	const expandAll = () => {
+		for (const id of map.keys()) expanded.add(id);
+	};
+	const expandByLevel = (lv) => {
+		for (const n of map.values()) if (n.level < lv) expanded.add(n.id);
+	};
+	if (def === true) {
+		expandAll();
+		return;
+	}
+	if (Array.isArray(def)) {
+		for (const id of def) expanded.add(id);
+		if (lvl === "deepest") {
+			expandAll();
+			return;
+		}
+		if (typeof lvl === "number" && Number.isFinite(lvl) && lvl > 0) expandByLevel(lvl);
+		return;
+	}
+	if (lvl === "deepest") {
+		expandAll();
+		return;
+	}
+	if (typeof lvl === "number" && Number.isFinite(lvl) && lvl > 0) expandByLevel(lvl);
+}
+/**
+* 为 Set/Map/Object 创建响应式代理
+* 在集合或对象发生更改时，触发回调以便同步状态（如可见性）
+*/
+function createReactive(target, callback) {
+	const isSet = target instanceof Set;
+	const isMap = target instanceof Map;
+	return new Proxy(target, {
+		get(obj, prop, receiver) {
+			if (isSet) {
+				if (prop === "size") return Reflect.get(obj, prop, obj);
+				const value = Reflect.get(obj, prop, obj);
+				if (prop === "add") return (v) => {
+					const existed = obj.has(v);
+					const r = obj.add(v);
+					if (!existed) callback({
+						type: "ADD",
+						target: obj,
+						newValue: v
+					});
+					return r;
+				};
+				if (prop === "delete") return (v) => {
+					const existed = obj.has(v);
+					const old = v;
+					const r = obj.delete(v);
+					if (existed) callback({
+						type: "DELETE",
+						target: obj,
+						oldValue: old
+					});
+					return r;
+				};
+				if (prop === "clear") return () => {
+					if (obj.size > 0) callback({
+						type: "CLEAR",
+						target: obj
+					});
+					return obj.clear();
+				};
+				return typeof value === "function" ? value.bind(obj) : value;
+			}
+			if (isMap) {
+				if (prop === "size") return Reflect.get(obj, prop, obj);
+				const value = Reflect.get(obj, prop, obj);
+				if (prop === "set") return (k, v) => {
+					const old = obj.get(k);
+					const r = obj.set(k, v);
+					callback({
+						type: "MAP_SET",
+						target: obj,
+						property: k,
+						oldValue: old,
+						newValue: v
+					});
+					return r;
+				};
+				if (prop === "delete") return (k) => {
+					const existed = obj.has(k);
+					const old = obj.get(k);
+					const r = obj.delete(k);
+					if (existed) callback({
+						type: "DELETE",
+						target: obj,
+						property: k,
+						oldValue: old
+					});
+					return r;
+				};
+				if (prop === "clear") return () => {
+					if (obj.size > 0) callback({
+						type: "CLEAR",
+						target: obj
+					});
+					return obj.clear();
+				};
+				return typeof value === "function" ? value.bind(obj) : value;
+			}
+			return Reflect.get(obj, prop, receiver);
+		},
+		set(obj, prop, value, receiver) {
+			const oldValue = Reflect.get(obj, prop, receiver);
+			const r = Reflect.set(obj, prop, value);
+			callback({
+				type: "SET",
+				target: obj,
+				property: prop,
+				oldValue,
+				newValue: value
+			});
+			return r;
+		},
+		deleteProperty(obj, prop) {
+			const oldValue = Reflect.get(obj, prop);
+			const r = Reflect.deleteProperty(obj, prop);
+			callback({
+				type: "DELETE",
+				target: obj,
+				property: prop,
+				oldValue
+			});
+			return r;
+		}
+	});
+}
+/**
+* 以 DFS 方式计算当前可见节点序列
+* 仅在父节点展开时展开其子节点
+*/
+function computeVisibleItems(roots) {
+	const result = [];
+	const walk = (node) => {
+		result.push(node);
+		if (node.isExpanded() && node.hasChildren()) for (const child of node.getChildren()) walk(child);
+	};
+	for (const root of roots) walk(root);
+	return result;
+}
+/**
+* 递归设置节点层级
+*/
+function setLevelRecursively(node, childrenCache, startLevel) {
+	node.level = startLevel ?? node.level;
+	for (const c of childrenCache.get(node.id) ?? []) setLevelRecursively(c, childrenCache, (node.level ?? 0) + 1);
+}
+/**
+* 追加子节点到指定父节点（或根）
+* 自动维护缓存与层级，并触发通知
+*/
+function appendChildren(ctx, parentId, children) {
+	const parent = parentId ? ctx.map.get(parentId) : void 0;
+	for (const item of children) {
+		const id = String(Reflect.get(item, ctx.keyField || "id"));
+		if (ctx.map.has(id)) continue;
+		const node = {
+			id,
+			original: item,
+			level: parent ? parent.level + 1 : 0,
+			hasChildren: () => !!ctx.childrenCache.get(id)?.length,
+			getParent: () => ctx.parentCache.get(id),
+			getChildren: () => ctx.childrenCache.get(id) ?? [],
+			isExpanded: () => ctx.expandedKeys.has(id),
+			toggleExpand: (expand) => {
+				if (expand === void 0) ctx.tree.toggleExpand(id);
+				else if (expand) ctx.tree.expand(id);
+				else ctx.tree.collapse(id);
+			}
+		};
+		ctx.map.set(id, node);
+		ctx.childrenCache.set(id, []);
+		ctx.parentCache.set(id, parent);
+		if (parent) ctx.childrenCache.get(parent.id).push(node);
+		else ctx.roots.push(node);
+	}
+	if (parent) setLevelRecursively(parent, ctx.childrenCache, parent.level);
+	else ctx.roots.forEach((r) => setLevelRecursively(r, ctx.childrenCache, 0));
+	ctx.notify();
+}
+/**
+* 移动节点到新父级，并支持在某个兄弟节点之前插入
+* 自动维护缓存与层级，并触发通知
+*/
+function moveNode(ctx, id, newParentId, beforeId) {
+	const node = ctx.map.get(id);
+	if (!node) return;
+	const oldParent = ctx.parentCache.get(id);
+	const newParent = newParentId ? ctx.map.get(newParentId) : void 0;
+	if (oldParent) {
+		const arr = ctx.childrenCache.get(oldParent.id) ?? [];
+		const idx = arr.findIndex((n) => n.id === id);
+		if (idx >= 0) arr.splice(idx, 1);
+	} else {
+		const idx = ctx.roots.findIndex((n) => n.id === id);
+		if (idx >= 0) ctx.roots.splice(idx, 1);
+	}
+	ctx.parentCache.set(id, newParent);
+	node.level = newParent ? newParent.level + 1 : 0;
+	if (newParent) {
+		const arr = ctx.childrenCache.get(newParent.id) ?? [];
+		if (!ctx.childrenCache.has(newParent.id)) ctx.childrenCache.set(newParent.id, arr);
+		if (beforeId) {
+			const idx = arr.findIndex((n) => n.id === beforeId);
+			if (idx >= 0) arr.splice(idx, 0, node);
+			else arr.push(node);
+		} else arr.push(node);
+	} else if (beforeId) {
+		const idx = ctx.roots.findIndex((n) => n.id === beforeId);
+		if (idx >= 0) ctx.roots.splice(idx, 0, node);
+		else ctx.roots.push(node);
+	} else ctx.roots.push(node);
+	setLevelRecursively(node, ctx.childrenCache, node.level);
+	ctx.notify();
+}
+/**
+* 创建 SpliceTree 树实例
+* - 构建缓存结构
+* - 暴露操作方法（展开/收起/追加/移动）
+* - 提供插件扩展点（setup/extendNode）
+*/
+function createSpliceTree(data, options = {}) {
+	const keyField = options.keyField ?? "id";
+	const parentField = options.parentField ?? "parent";
+	const events = createEmitter();
+	const expandedKeys = createReactive(/* @__PURE__ */ new Set(), (payload) => {
+		events.emit({
+			name: "visibility",
+			keys: Array.from(payload.target)
+		});
+	});
+	const { roots, map, parentCache, childrenCache } = buildTree(data, keyField, parentField, expandedKeys);
+	initDefaultExpansion(map, expandedKeys, options.defaultExpanded, options.defaultExpandedLevel);
+	const emitVisibility = () => {
+		events.emit({
+			name: "visibility",
+			keys: Array.from(expandedKeys)
+		});
+	};
+	const tree = {
+		data,
+		options,
+		items: () => computeVisibleItems(roots),
+		getNode: (id) => map.get(id),
+		events,
+		expandedKeys: () => Array.from(expandedKeys),
+		isExpanded: (id) => expandedKeys.has(id),
+		expand(ids) {
+			const list = Array.isArray(ids) ? ids : [ids];
+			for (const id of list) if (!expandedKeys.has(id)) expandedKeys.add(id);
+			emitVisibility();
+		},
+		collapse(ids) {
+			const list = Array.isArray(ids) ? ids : [ids];
+			for (const id of list) if (expandedKeys.has(id)) expandedKeys.delete(id);
+			emitVisibility();
+		},
+		toggleExpand(ids) {
+			const list = Array.isArray(ids) ? ids : [ids];
+			const toExpand = [];
+			const toCollapse = [];
+			for (const id of list) if (tree.isExpanded(id)) toCollapse.push(id);
+			else toExpand.push(id);
+			if (toExpand.length) tree.expand(toExpand);
+			if (toCollapse.length) tree.collapse(toCollapse);
+		},
+		expandAll() {
+			for (const id of map.keys()) expandedKeys.add(id);
+			emitVisibility();
+		},
+		collapseAll() {
+			expandedKeys.clear();
+			emitVisibility();
+		},
+		toggleExpandAll() {
+			if (expandedKeys.size > 0) tree.collapseAll();
+			else tree.expandAll();
+		},
+		appendChildren(parentId, children) {
+			appendChildren({
+				map,
+				tree,
+				roots,
+				keyField,
+				parentCache,
+				childrenCache,
+				expandedKeys,
+				notify: emitVisibility
+			}, parentId, children);
+		},
+		moveNode(id, newParentId, beforeId) {
+			moveNode({
+				map,
+				tree,
+				roots,
+				keyField,
+				parentCache,
+				childrenCache,
+				expandedKeys,
+				notify: emitVisibility
+			}, id, newParentId, beforeId);
+		}
+	};
+	const pluginCtx = {
+		tree,
+		options,
+		events
+	};
+	options?.plugins?.forEach((plugin) => {
+		const api = plugin.setup?.(pluginCtx);
+		Object.assign(tree, api);
+	});
+	if (options?.plugins?.length) for (const n of map.values()) for (const plugin of options.plugins) plugin.extendNode?.(n, pluginCtx);
+	for (const node of map.values()) {
+		node.isExpanded = () => tree.isExpanded(node.id);
+		node.toggleExpand = (expand) => {
+			if (expand === void 0) tree.toggleExpand(node.id);
+			else if (expand) tree.expand(node.id);
+			else tree.collapse(node.id);
+		};
+	}
+	return tree;
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Vue 3 适配器
+* - 以 shallowRef 暴露 items，使其在核心派发 visibility 事件时刷新
+* - 保留核心 API 的完整返回（展开/收起/移动等方法）
+* - 适用于任意自定义渲染逻辑与组件绑定
+*/
+function useSpliceTree(data, options = {}) {
+	const api = shallowRef();
+	const items = shallowRef(api.value?.items?.() ?? []);
+	const createTree = () => {
+		api.value = createSpliceTree(toValue(data), options);
+		api.value.events.on("visibility", () => {
+			items.value = api.value.items();
+		});
+		items.value = api.value.items();
+	};
+	watch(() => toValue(data), () => {
+		createTree();
+	}, {
+		deep: true,
+		immediate: true
+	});
+	return {
+		...api,
+		items
+	};
+}
+
+//#endregion
+export { useSpliceTree };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@splicetree/adapter-vue",
+  "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",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "dependencies": {
+    "unplugin-vue": "^7.1.0",
+    "vue-tsc": "^3.1.5"
+  },
+  "devDependencies": {
+    "vue": "^3.0.0",
+    "@splicetree/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown"
+  }
+}