@splicetree/core 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,74 @@
+# @splicetree/core
+
+[![version](https://img.shields.io/npm/v/@splicetree/core.svg?label=version)](https://www.npmjs.com/package/@splicetree/core)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/core.svg)](https://npmcharts.com/compare/%40splicetree%2Fcore?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/core.svg)](https://www.npmjs.com/package/@splicetree/core)
+[![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)
+
+为扁平数据提供轻量、可扩展的树运行时。支持插件扩展事件与能力。
+
+## 简介
+
+SpliceTree 是一个 Headless 树运行时，面向扁平数据构建可操作的树结构，提供精简 API，并通过插件扩展搜索、拖拽、懒加载、键盘导航等能力。
+
+## 官方文档
+
+文档与示例位于 [https://www.splicetree.dev](https://www.splicetree.dev)
+
+## 安装
+
+```sh
+pnpm add @splicetree/core
+```
+
+## 使用
+
+```ts
+import { createSpliceTree } from '@splicetree/core'
+
+const data = [
+  { id: 'a' },
+  { id: 'b', parent: 'a' },
+]
+
+const { items } = createSpliceTree(data, {
+  keyField: 'id',
+  parentField: 'parent',
+  defaultExpanded: ['a'],
+})
+
+// 渲染可见节点
+for (const node of items()) {
+  console.log(node.id, node.level)
+}
+```
+
+## 选项
+
+| 名称              | 类型                 | 默认值     | 说明                         |
+| ----------------- | -------------------- | ---------- | ---------------------------- |
+| `keyField`        | `string`             | `'id'`     | 主键字段名                   |
+| `parentField`     | `string`             | `'parent'` | 父级字段名                   |
+| `plugins`         | `SpliceTreePlugin[]` | `[]`       | 插件列表（可扩展实例与节点） |
+| `defaultExpanded` | `string[]`           | `[]`       | 初始展开的节点 id 集合       |
+
+## 实例 API
+
+- `items()` 返回当前可见节点序列
+- `getNode(id)` 通过 id 获取节点
+- `events` 事件总线（`on/emit`）
+- `expand/collapse/toggleExpand(id)` 展开/收起/切换
+- `appendChildren(parentId, children)` 追加子节点（支持追加到根）
+- `moveNode(id, newParentId, beforeId?)` 移动到新父级，并指定插入位置
+
+## 节点 API
+
+- `id/original/level`
+- `isExpanded()` 当前是否展开
+- `hasChildren()` 是否存在子节点（懒加载插件可覆盖）
+- `getParent()/getChildren()` 父子节点查询
+
+## 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,283 @@
+//#region src/types.d.ts
+/**
+ * 抽象的函数类型
+ * - 若不传泛型参数 `D`，表示无参函数
+ * - 若传入 `D`，表示函数可选择性接收该参数类型
+ */
+type Fn<T, D = undefined> = [D] extends [undefined] ? () => T : (data?: D) => T;
+/**
+ * 输入数据的通用结构
+ * - 表示原始树数据的任意键值对对象
+ */
+interface SpliceTreeData {
+  [key: string]: any;
+}
+/**
+ * 树节点的运行时结构
+ * - `id`：节点唯一标识（来自原始数据的主键）
+ * - `original`：原始数据引用
+ * - `level`：层级（根为 0）
+ * - `isExpanded()`：当前是否展开
+ * - `hasChildren()`：是否存在子节点（懒加载插件可覆盖）
+ * - `getParent()`：获取父节点
+ * - `getChildren()`：获取子节点列表
+ * - `toggleExpand(expand?)`：切换或显式设置展开状态
+ */
+interface SpliceTreeNode<T = SpliceTreeData> {
+  /**
+   * 节点唯一标识
+   */
+  id: string;
+  /**
+   * 原始数据引用
+   */
+  original: T;
+  /**
+   * 节点层级（根为 0）
+   */
+  level: number;
+  /**
+   * 当前是否处于展开状态
+   */
+  isExpanded: Fn<boolean>;
+  /**
+   * 是否存在子节点
+   * 懒加载插件可能在未加载时返回 true 以保持交互一致性
+   */
+  hasChildren: Fn<boolean>;
+  /**
+   * 获取父节点（根节点时返回 undefined）
+   */
+  getParent: Fn<SpliceTreeNode<T> | undefined>;
+  /**
+   * 获取子节点列表（无子节点时返回空数组）
+   */
+  getChildren: Fn<SpliceTreeNode<T>[]>;
+  /**
+   * 切换或显式设置展开状态
+   * @param expand 不传表示切换；true/false 表示显式设置
+   */
+  toggleExpand: Fn<void, boolean | undefined>;
+}
+/**
+ * 事件负载映射（可被插件扩展）
+ * - `visibility`：视图可见性相关事件（携带当前展开的节点 id 集合）
+ */
+interface SpliceTreeEventPayloadMap {
+  /**
+   * 视图可见性事件负载
+   * @property keys 当前展开的节点 id 集合
+   */
+  visibility: {
+    keys: string[];
+  };
+}
+type SpliceTreeEventName = keyof SpliceTreeEventPayloadMap;
+type SpliceTreeEventPayload = { [K in keyof SpliceTreeEventPayloadMap]: {
+  name: K;
+} & SpliceTreeEventPayloadMap[K] }[keyof SpliceTreeEventPayloadMap];
+/**
+ * 事件总线接口
+ * - `on(name, handler)`：订阅事件，返回取消订阅函数
+ * - `emit(payload)`：派发事件
+ */
+interface SpliceTreeEvents {
+  /**
+   * 订阅指定事件
+   * @param name 事件名称
+   * @param handler 事件处理函数，接收事件负载
+   * @returns 取消订阅函数（返回 true 表示取消成功）
+   */
+  on: (name: keyof SpliceTreeEventPayloadMap, handler: (payload: SpliceTreeEventPayload) => void) => () => boolean;
+  /**
+   * 派发事件
+   * @param payload 事件负载，包含名称与数据
+   */
+  emit: (payload: SpliceTreeEventPayload) => void;
+}
+/**
+ * `createSpliceTree` 的选项
+ * - `keyField`：主键字段名，默认 `'id'`
+ * - `parentField`：父级字段名，默认 `'parent'`
+ * - `plugins`：插件列表
+ * - `defaultExpanded`：默认展开的节点 id 列表（或设为 true 表示全部展开）
+ * - `defaultExpandedLevel`：默认展开的层级（或 `'deepest'` 表示展开到最深层）
+ * - 其余键允许被插件进行选项扩展
+ */
+interface UseSpliceTreeOptions<T = SpliceTreeData> {
+  /**
+   * 主键字段名
+   * @default 'id'
+   */
+  keyField?: string;
+  /**
+   * 父级字段名
+   * @default 'parent'
+   */
+  parentField?: string;
+  /**
+   * 插件列表
+   */
+  plugins?: SpliceTreePlugin<T>[];
+  /**
+   * 默认展开的节点 ID 列表
+   * 设为 true 表示默认展开所有节点
+   */
+  defaultExpanded?: true | string[];
+  /**
+   * 默认展开的层级
+   * 设为 'deepest' 表示默认展开所有层级
+   */
+  defaultExpandedLevel?: number | 'deepest';
+  /**
+   * 其余选项键，供插件扩展使用
+   */
+  [key: string]: any;
+}
+/**
+ * 核心实例结构（可被插件扩展）
+ * - 数据与选项：`data`、`options`
+ * - 查询与遍历：`items()`、`getNode(id)`
+ * - 展开控制：`expand/collapse/toggleExpand` 及其全量版本
+ * - 结构操作：`appendChildren` 追加子节点、`moveNode` 移动节点
+ * - 事件：`events` 事件总线（`on/emit`）
+ */
+interface SpliceTreeInstance<T = SpliceTreeData> {
+  /**
+   * 原始数据列表
+   */
+  data: T[];
+  /**
+   * 实例选项
+   */
+  options: UseSpliceTreeOptions<T>;
+  /**
+   * 返回当前可见节点序列（按展开状态计算）
+   */
+  items: () => SpliceTreeNode<T>[];
+  /**
+   * 通过 id 获取节点（不存在时返回 undefined）
+   * @param id 节点 id
+   */
+  getNode: (id: string) => SpliceTreeNode<T> | undefined;
+  /**
+   * 事件总线
+   */
+  events: SpliceTreeEvents;
+  /**
+   * 返回当前展开的节点 id 集合
+   */
+  expandedKeys: () => string[];
+  /**
+   * 查询指定节点是否展开
+   * @param id 节点 id
+   */
+  isExpanded: (id: string) => boolean;
+  /**
+   * 展开指定节点或节点列表
+   * @param id 单个 id 或 id 数组
+   */
+  expand: (id: string | string[]) => void;
+  /**
+   * 收起指定节点或节点列表
+   * @param id 单个 id 或 id 数组
+   */
+  collapse: (id: string | string[]) => void;
+  /**
+   * 切换指定节点或节点列表的展开状态
+   * @param id 单个 id 或 id 数组
+   */
+  toggleExpand: (id: string | string[]) => void;
+  /**
+   * 展开所有节点
+   */
+  expandAll: () => void;
+  /**
+   * 收起所有节点
+   */
+  collapseAll: () => void;
+  /**
+   * 切换所有节点的展开状态
+   */
+  toggleExpandAll: () => void;
+  /**
+   * 追加子节点
+   * @param parentId 父节点 id（传 undefined 表示追加到根）
+   * @param children 子节点数据列表
+   */
+  appendChildren: (parentId: string | undefined, children: T[]) => void;
+  /**
+   * 移动节点到新父级并指定插入位置
+   * @param id 要移动的节点 id
+   * @param newParentId 新父级节点 id（传 undefined 移动到根）
+   * @param beforeId 插入到指定兄弟节点之前（不传表示末尾）
+   */
+  moveNode: (id: string, newParentId: string | undefined, beforeId?: string) => void;
+}
+/**
+ * 插件上下文
+ * - `tree`：核心实例引用
+ * - `options`：插件自身选项
+ * - `events`：事件总线
+ */
+interface SpliceTreePluginContext<T = SpliceTreeData> {
+  /**
+   * 核心实例
+   */
+  tree: SpliceTreeInstance<T>;
+  /**
+   * 插件选项（来自用户传入的 `options` 合并）
+   */
+  options: Record<string, any>;
+  /**
+   * 事件总线
+   */
+  events: SpliceTreeEvents;
+}
+/**
+ * 插件定义接口
+ * - `name`：插件名称
+ * - `options`：插件选项（可用于配置行为）
+ * - `setup(ctx)`：实例级扩展，返回扩展的字段与方法
+ * - `extendNode(node, ctx)`：节点级扩展，直接为节点追加方法/属性
+ */
+interface SpliceTreePlugin<T = SpliceTreeData, TExt = Record<string, any>> {
+  /**
+   * 插件名称
+   */
+  name: string;
+  /**
+   * 插件选项
+   */
+  options?: Record<string, any>;
+  /**
+   * 设置实例扩展
+   * @param ctx 插件上下文
+   * @returns 扩展的字段与方法，将合并到实例上
+   */
+  setup?: (ctx: SpliceTreePluginContext<T>) => TExt;
+  /**
+   * 扩展节点
+   * @param node 当前节点
+   * @param ctx 插件上下文
+   */
+  extendNode?: (node: SpliceTreeNode<T>, ctx: SpliceTreePluginContext<T>) => void;
+}
+/**
+ * 工厂函数类型：创建 SpliceTree 实例
+ * @param data 原始树数据列表
+ * @param options 实例选项（支持插件扩展）
+ * @returns SpliceTree 实例
+ */
+type CreateSpliceTree = <T = SpliceTreeData>(data: T[], options?: UseSpliceTreeOptions<T>) => SpliceTreeInstance<T>;
+//#endregion
+//#region src/use.d.ts
+/**
+ * 创建 SpliceTree 树实例
+ * - 构建缓存结构
+ * - 暴露操作方法（展开/收起/追加/移动）
+ * - 提供插件扩展点（setup/extendNode）
+ */
+declare function createSpliceTree<T extends SpliceTreeData = SpliceTreeData>(data: T[], options?: UseSpliceTreeOptions<T>): SpliceTreeInstance<T>;
+//#endregion
+export { CreateSpliceTree, Fn, SpliceTreeData, SpliceTreeEventName, SpliceTreeEventPayload, SpliceTreeEventPayloadMap, SpliceTreeEvents, SpliceTreeInstance, SpliceTreeNode, SpliceTreePlugin, SpliceTreePluginContext, UseSpliceTreeOptions, createSpliceTree };

package/dist/index.js

@@ -0,0 +1,433 @@
+//#region src/emitter.ts
+/**
+* 轻量事件总线：支持订阅与派发，供核心与插件通信
+*/
+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
+	};
+}
+
+//#endregion
+//#region src/impl.ts
+/**
+* 创建运行时树节点，并注入必要的 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
+	};
+}
+
+//#endregion
+//#region src/utils/expand.ts
+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);
+}
+
+//#endregion
+//#region src/utils/reactive.ts
+/**
+* 为 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;
+		}
+	});
+}
+
+//#endregion
+//#region src/utils/node.ts
+/**
+* 以 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();
+}
+
+//#endregion
+//#region src/use.ts
+/**
+* 创建 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
+export { createSpliceTree };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@splicetree/core",
+  "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"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {},
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown"
+  }
+}