@splicetree/plugin-lazy-load 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @splicetree/plugin-lazy-load
+
+## 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,48 @@
+# @splicetree/plugin-lazy-load
+
+[![version](https://img.shields.io/npm/v/@splicetree/plugin-lazy-load.svg?label=version)](https://www.npmjs.com/package/@splicetree/plugin-lazy-load)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/plugin-lazy-load.svg)](https://npmcharts.com/compare/%40splicetree%2Fplugin-lazy-load?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/plugin-lazy-load.svg)](https://www.npmjs.com/package/@splicetree/plugin-lazy-load)
+[![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-lazy-load`
+
+## 使用
+
+```ts
+import { createSpliceTree } from '@splicetree/core'
+import lazyLoad from '@splicetree/plugin-lazy-load'
+
+const tree = createSpliceTree(data, {
+  plugins: [lazyLoad],
+  loadChildren: async (node) => {
+    const resp = await fetch(`/api/children?parent=${node.id}`)
+    const children = await resp.json()
+    return children
+  },
+})
+```
+
+## Api
+
+### 实例方法
+
+| 名称                | 参数                      | 说明                       |
+| ------------------- | ------------------------- | -------------------------- |
+| `loadedKeys`        | `无`                      | 已加载集合                 |
+| `isLoaded(id)`      | `id: string`              | 是否已加载                 |
+| `load(id)`          | `id: string`              | 手动加载                   |
+| `expand(ids)`       | `ids: string \| string[]` | 覆盖：未加载时先加载再展开 |
+| `toggleExpand(ids)` | `ids: string \| string[]` | 覆盖：未加载时先加载再切换 |
+
+### 节点方法
+
+| 名称            | 参数 | 说明                                          |
+| --------------- | ---- | --------------------------------------------- |
+| `isLoaded()`    | `无` | 当前节点是否已加载                            |
+| `hasChildren()` | `无` | 重写：未加载返回 `true`，加载后根据子节点判断 |

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { SpliceTreePlugin } from "@splicetree/core";
+
+//#region src/index.d.ts
+declare module '@splicetree/core' {
+  /**
+   * 选项扩展（Lazy-Load）
+   * - loadChildren：按需加载指定节点的子节点
+   */
+  interface UseSpliceTreeOptions {
+    /**
+     * 加载指定节点的子节点
+     * 返回子节点数据数组，加载完成后将自动追加到树中
+     * @param node 要加载子节点的目标节点
+     */
+    loadChildren?: (node: SpliceTreeNode<any>) => Promise<any[]>;
+  }
+  /**
+   * 事件扩展（Lazy-Load）
+   * - lazyload：派发已加载节点集合
+   */
+  interface SpliceTreeEventPayloadMap {
+    lazyload: {
+      keys: string[];
+    };
+  }
+  /**
+   * 实例扩展（Lazy-Load）
+   * - loadedKeys：已加载集合
+   * - isLoaded：查询是否已加载
+   * - load：加载指定节点的子节点
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 已完成加载的节点 id 集合
+     */
+    loadedKeys: Set<string>;
+    /**
+     * 查询指定节点是否已完成子节点加载
+     */
+    isLoaded: (id: string) => boolean;
+    /**
+     * 加载指定节点的子节点并追加到树中
+     * @param id 目标节点 id
+     */
+    load: (id: string) => Promise<void>;
+  }
+  /**
+   * 节点扩展（Lazy-Load）
+   * - isLoaded：当前节点是否已加载
+   */
+  interface SpliceTreeNode {
+    isLoaded: () => boolean;
+  }
+}
+declare const lazyLoad: SpliceTreePlugin;
+//#endregion
+export { lazyLoad as default, lazyLoad };

package/dist/index.js

@@ -0,0 +1,90 @@
+//#region src/index.ts
+const lazyLoad = {
+	name: "lazy-load",
+	setup(ctx) {
+		const { loadChildren } = ctx.options;
+		const loadedKeys = /* @__PURE__ */ new Set();
+		const isLoaded = (id) => loadedKeys.has(id);
+		/**
+		* 为节点应用懒加载相关的覆盖方法
+		* - isLoaded：读取实例的已加载状态
+		* - hasChildren：未加载时返回 true，避免展开箭头消失
+		*/
+		const applyLazyOverrides = (node) => {
+			node.isLoaded = () => ctx.tree.isLoaded?.(node.id);
+			node.hasChildren = () => {
+				if (!ctx.tree.isLoaded?.(node.id)) return true;
+				return !!node.getChildren()?.length;
+			};
+		};
+		/**
+		* 加载指定节点的子节点，并将其追加到树结构
+		* - 若已加载或未提供加载器则跳过
+		* - 追加后为新增节点应用覆盖方法
+		* - 完成后记录 loadedKeys 并派发 lazyload 事件
+		* @param id 目标节点 id
+		*/
+		const load = async (id) => {
+			if (!loadChildren) return;
+			if (loadedKeys.has(id)) return;
+			const node = ctx.tree.getNode(id);
+			if (!node) return;
+			const children = await loadChildren(node);
+			if (children?.length) {
+				ctx.tree.appendChildren(id, children);
+				for (const c of children) {
+					const childId = String(Reflect.get(c, ctx.tree.options?.keyField ?? "id"));
+					const childNode = ctx.tree.getNode(childId);
+					if (childNode) applyLazyOverrides(childNode);
+				}
+			}
+			loadedKeys.add(id);
+			ctx.events.emit({
+				name: "lazyload",
+				keys: Array.from(loadedKeys)
+			});
+		};
+		const origExpand = ctx.tree.expand.bind(ctx.tree);
+		const origToggle = ctx.tree.toggleExpand.bind(ctx.tree);
+		/**
+		* 覆盖 expand：在展开前确保子节点已加载
+		* @param ids 要展开的节点 id 或 id 数组
+		*/
+		const expand = async (ids) => {
+			const list = Array.isArray(ids) ? ids : [ids];
+			if (loadChildren) {
+				for (const id of list) if (!isLoaded(id)) await load(id);
+			}
+			origExpand(ids);
+		};
+		/**
+		* 覆盖 toggleExpand：在切换前确保子节点已加载
+		* @param ids 要切换的节点 id 或 id 数组
+		*/
+		const toggleExpand = async (ids) => {
+			const list = Array.isArray(ids) ? ids : [ids];
+			if (loadChildren) {
+				for (const id of list) if (!isLoaded(id)) await load(id);
+			}
+			origToggle(ids);
+		};
+		return {
+			loadedKeys,
+			isLoaded,
+			load,
+			expand,
+			toggleExpand
+		};
+	},
+	extendNode(node, ctx) {
+		node.isLoaded = () => ctx.tree.isLoaded?.(node.id);
+		node.hasChildren = () => {
+			if (!ctx.tree.isLoaded?.(node.id)) return true;
+			return !!node.getChildren()?.length;
+		};
+	}
+};
+var src_default = lazyLoad;
+
+//#endregion
+export { src_default as default, lazyLoad };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@splicetree/plugin-lazy-load",
+  "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,177 @@
+import type { SpliceTreePlugin, SpliceTreePluginContext } from '@splicetree/core'
+import '@splicetree/core'
+
+declare module '@splicetree/core' {
+  /**
+   * 选项扩展（Lazy-Load）
+   * - loadChildren：按需加载指定节点的子节点
+   */
+  interface UseSpliceTreeOptions {
+    /**
+     * 加载指定节点的子节点
+     * 返回子节点数据数组，加载完成后将自动追加到树中
+     * @param node 要加载子节点的目标节点
+     */
+    loadChildren?: (node: SpliceTreeNode<any>) => Promise<any[]>
+  }
+
+  /**
+   * 事件扩展（Lazy-Load）
+   * - lazyload：派发已加载节点集合
+   */
+  interface SpliceTreeEventPayloadMap {
+    lazyload: { keys: string[] }
+  }
+
+  /**
+   * 实例扩展（Lazy-Load）
+   * - loadedKeys：已加载集合
+   * - isLoaded：查询是否已加载
+   * - load：加载指定节点的子节点
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 已完成加载的节点 id 集合
+     */
+    loadedKeys: Set<string>
+    /**
+     * 查询指定节点是否已完成子节点加载
+     */
+    isLoaded: (id: string) => boolean
+    /**
+     * 加载指定节点的子节点并追加到树中
+     * @param id 目标节点 id
+     */
+    load: (id: string) => Promise<void>
+  }
+
+  /**
+   * 节点扩展（Lazy-Load）
+   * - isLoaded：当前节点是否已加载
+   */
+  interface SpliceTreeNode {
+    isLoaded: () => boolean
+  }
+}
+
+export const lazyLoad: SpliceTreePlugin = {
+  name: 'lazy-load',
+  /**
+   * 懒加载插件
+   * - 首次展开时按需加载子节点
+   * - 覆盖 hasChildren/expand/toggleExpand 以接入加载流程
+   * - 通过 loadedKeys 标记已加载节点
+   */
+  setup(ctx: SpliceTreePluginContext) {
+    const { loadChildren } = ctx.options
+    const loadedKeys = new Set<string>()
+    const isLoaded = (id: string) => loadedKeys.has(id)
+
+    /**
+     * 为节点应用懒加载相关的覆盖方法
+     * - isLoaded：读取实例的已加载状态
+     * - hasChildren：未加载时返回 true，避免展开箭头消失
+     */
+    const applyLazyOverrides = (node: any) => {
+      node.isLoaded = () => ctx.tree.isLoaded?.(node.id)
+      node.hasChildren = () => {
+        const loaded = ctx.tree.isLoaded?.(node.id)
+        if (!loaded) {
+          return true
+        }
+        return !!node.getChildren()?.length
+      }
+    }
+
+    /**
+     * 加载指定节点的子节点，并将其追加到树结构
+     * - 若已加载或未提供加载器则跳过
+     * - 追加后为新增节点应用覆盖方法
+     * - 完成后记录 loadedKeys 并派发 lazyload 事件
+     * @param id 目标节点 id
+     */
+    const load = async (id: string) => {
+      if (!loadChildren) {
+        return
+      }
+      if (loadedKeys.has(id)) {
+        return
+      }
+      const node = ctx.tree.getNode(id)
+      if (!node) {
+        return
+      }
+      const children = await loadChildren(node)
+      if (children?.length) {
+        ctx.tree.appendChildren(id, children)
+        for (const c of children) {
+          const childId = String(Reflect.get(c as any, ctx.tree.options?.keyField ?? 'id'))
+          const childNode = ctx.tree.getNode(childId)
+          if (childNode) {
+            applyLazyOverrides(childNode)
+          }
+        }
+      }
+      loadedKeys.add(id)
+      ctx.events.emit({ name: 'lazyload', keys: Array.from(loadedKeys) } as any)
+    }
+
+    const origExpand = ctx.tree.expand.bind(ctx.tree)
+    const origToggle = ctx.tree.toggleExpand.bind(ctx.tree)
+
+    /**
+     * 覆盖 expand：在展开前确保子节点已加载
+     * @param ids 要展开的节点 id 或 id 数组
+     */
+    const expand = async (ids: string | string[]) => {
+      const list = Array.isArray(ids) ? ids : [ids]
+      if (loadChildren) {
+        for (const id of list) {
+          if (!isLoaded(id))
+            await load(id)
+        }
+      }
+      origExpand(ids as any)
+    }
+    /**
+     * 覆盖 toggleExpand：在切换前确保子节点已加载
+     * @param ids 要切换的节点 id 或 id 数组
+     */
+    const toggleExpand = async (ids: string | string[]) => {
+      const list = Array.isArray(ids) ? ids : [ids]
+      if (loadChildren) {
+        for (const id of list) {
+          if (!isLoaded(id))
+            await load(id)
+        }
+      }
+      origToggle(ids as any)
+    }
+
+    return {
+      loadedKeys,
+      isLoaded,
+      load,
+      // 覆盖核心方法以接入懒加载
+      expand: expand as any,
+      toggleExpand: toggleExpand as any,
+    }
+  },
+  /**
+   * 为节点扩展懒加载相关方法与行为覆盖
+   * - isLoaded：查询当前节点是否已加载
+   * - hasChildren：未加载时返回 true，已加载后按实际子节点判断
+   */
+  extendNode(node, ctx) {
+    ;(node as any).isLoaded = () => ctx.tree.isLoaded?.(node.id)
+    node.hasChildren = () => {
+      const loaded = ctx.tree.isLoaded?.(node.id)
+      if (!loaded) {
+        return true
+      }
+      return !!node.getChildren()?.length
+    }
+  },
+}
+
+export default lazyLoad

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'],
+})