@splicetree/plugin-checkable 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @splicetree/plugin-checkable
+
+## 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,55 @@
+# @splicetree/plugin-checkable
+
+[![version](https://img.shields.io/npm/v/@splicetree/plugin-checkable.svg?label=version)](https://www.npmjs.com/package/@splicetree/plugin-checkable)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/plugin-checkable.svg)](https://npmcharts.com/compare/%40splicetree%2Fplugin-checkable?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/plugin-checkable.svg)](https://www.npmjs.com/package/@splicetree/plugin-checkable)
+[![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-checkable`
+
+## 使用
+
+```ts
+import { createSpliceTree } from '@splicetree/core'
+import checkable from '@splicetree/plugin-checkable'
+
+const tree = createSpliceTree(data, {
+  plugins: [checkable],
+  defaultExpanded: ['a'],
+  defaultChecked: ['a'],
+})
+```
+
+## Api
+
+### Options
+
+| 选项             | 类型       | 默认值 | 说明         |
+| ---------------- | ---------- | ------ | ------------ |
+| `defaultChecked` | `string[]` | `[]`   | 初始勾选集合 |
+
+### Events
+
+| 事件      | 负载                 | 说明               |
+| --------- | -------------------- | ------------------ |
+| `checked` | `{ keys: string[] }` | 勾选状态变化时触发 |
+
+### 实例方法
+
+| 名称                | 参数 | 说明         |
+| ------------------- | ---- | ------------ |
+| `checkedKeys`       | `无` | 当前勾选集合 |
+| `indeterminateKeys` | `无` | 当前半选集合 |
+
+### 节点方法
+
+| 名称                    | 参数                | 说明           |
+| ----------------------- | ------------------- | -------------- |
+| `isChecked()`           | `无`                | 是否勾选       |
+| `isIndeterminate()`     | `无`                | 是否半选       |
+| `toggleCheck(checked?)` | `checked?: boolean` | 切换或显式设置 |

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { SpliceTreePlugin } from "@splicetree/core";
+
+//#region src/index.d.ts
+declare module '@splicetree/core' {
+  /**
+   * 选项扩展（Checkable）
+   * - defaultChecked：初始勾选的节点 id 列表
+   */
+  interface UseSpliceTreeOptions {
+    /**
+     * 初始勾选的节点 id 列表
+     * 在初始化时将这些节点设置为已勾选
+     */
+    defaultChecked?: string[];
+  }
+  /**
+   * 节点扩展（Checkable）
+   * - isChecked：是否已勾选
+   * - isIndeterminate：是否半选
+   * - toggleCheck：切换或显式设置勾选状态
+   */
+  interface SpliceTreeNode {
+    /**
+     * 当前节点是否已勾选
+     */
+    isChecked: () => boolean;
+    /**
+     * 当前节点是否为半选状态
+     */
+    isIndeterminate: () => boolean;
+    /**
+     * 切换或显式设置当前节点的勾选状态
+     * @param checked 不传表示切换；true/false 表示显式设置
+     */
+    toggleCheck: (checked?: boolean) => void;
+  }
+  /**
+   * 事件扩展（Checkable）
+   * - checked：勾选集合变化时派发
+   */
+  interface SpliceTreeEventPayloadMap {
+    /**
+     * 勾选集合变化事件负载
+     * @property keys 当前所有已勾选节点的 id 列表
+     */
+    checked: {
+      keys: string[];
+    };
+  }
+  /**
+   * 实例扩展（Checkable）
+   * - checkedKeys/indeterminateKeys：当前勾选/半选集合
+   * - isChecked/isIndeterminate：查询节点状态
+   * - check/uncheck/toggleCheck：操作勾选状态
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 已勾选的节点 id 集合
+     */
+    checkedKeys: Set<string>;
+    /**
+     * 半选的节点 id 集合
+     */
+    indeterminateKeys: Set<string>;
+    /**
+     * 查询指定节点是否已勾选
+     */
+    isChecked: (id: string) => boolean;
+    /**
+     * 查询指定节点是否为半选状态
+     */
+    isIndeterminate: (id: string) => boolean;
+    /**
+     * 勾选指定节点
+     */
+    check: (id: string) => void;
+    /**
+     * 取消勾选指定节点
+     */
+    uncheck: (id: string) => void;
+    /**
+     * 切换指定节点的勾选状态
+     */
+    toggleCheck: (id: string) => void;
+  }
+}
+declare const checkable: SpliceTreePlugin;
+//#endregion
+export { checkable, checkable as default };

package/dist/index.js

@@ -0,0 +1,129 @@
+//#region src/index.ts
+/**
+* 设置某节点的勾选状态并维护集合
+* @param id 节点 id
+* @param state 目标状态（checked/unchecked/indeterminate）
+* @param checked 已勾选集合
+* @param indeterminate 半选集合
+*/
+function setChecked(id, state, checked, indeterminate) {
+	if (state === "checked") {
+		checked.add(id);
+		indeterminate.delete(id);
+	} else if (state === "unchecked") {
+		checked.delete(id);
+		indeterminate.delete(id);
+	} else {
+		checked.delete(id);
+		indeterminate.add(id);
+	}
+}
+const checkable = {
+	name: "checkable",
+	setup(ctx) {
+		const { defaultChecked = [] } = ctx.options;
+		const checkedKeys = new Set(defaultChecked);
+		const indeterminateKeys = /* @__PURE__ */ new Set();
+		const isChecked = (id) => checkedKeys.has(id);
+		const isIndeterminate = (id) => indeterminateKeys.has(id);
+		/**
+		* 向下遍历所有子节点并执行回调
+		* @param id 起始父节点 id
+		* @param visit 对每个子节点执行的回调
+		*/
+		const descend = (id, visit) => {
+			const n = ctx.tree.getNode(id);
+			if (!n) return;
+			for (const c of n.getChildren()) {
+				visit(c.id);
+				descend(c.id, visit);
+			}
+		};
+		/**
+		* 自底向上更新祖先节点的勾选/半选状态
+		* - 所有子节点全勾选 → 祖先设为勾选
+		* - 所有子节点全未勾选 → 祖先设为未勾选
+		* - 否则 → 祖先设为半选
+		* 同步派发 visibility 与 checked 事件
+		* @param id 起始子节点 id
+		*/
+		const updateAncestors = (id) => {
+			let cur = ctx.tree.getNode(id)?.getParent();
+			while (cur) {
+				const children = cur.getChildren();
+				const allChecked = children.every((ch) => checkedKeys.has(ch.id));
+				const noneChecked = children.every((ch) => !checkedKeys.has(ch.id) && !indeterminateKeys.has(ch.id));
+				if (allChecked) setChecked(cur.id, "checked", checkedKeys, indeterminateKeys);
+				else if (noneChecked) setChecked(cur.id, "unchecked", checkedKeys, indeterminateKeys);
+				else setChecked(cur.id, "indeterminate", checkedKeys, indeterminateKeys);
+				cur = cur.getParent();
+			}
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+			ctx.events.emit({
+				name: "checked",
+				keys: Array.from(checkedKeys)
+			});
+		};
+		/**
+		* 勾选指定节点，并向下级联勾选所有子节点
+		* @param id 节点 id
+		*/
+		const check = (id) => {
+			setChecked(id, "checked", checkedKeys, indeterminateKeys);
+			descend(id, (nid) => setChecked(nid, "checked", checkedKeys, indeterminateKeys));
+			updateAncestors(id);
+		};
+		/**
+		* 取消勾选指定节点，并向下级联取消所有子节点
+		* @param id 节点 id
+		*/
+		const uncheck = (id) => {
+			setChecked(id, "unchecked", checkedKeys, indeterminateKeys);
+			descend(id, (nid) => setChecked(nid, "unchecked", checkedKeys, indeterminateKeys));
+			updateAncestors(id);
+		};
+		/**
+		* 切换指定节点的勾选状态
+		* @param id 节点 id
+		*/
+		const toggleCheck = (id) => {
+			if (isChecked(id)) uncheck(id);
+			else check(id);
+			updateAncestors(id);
+		};
+		for (const id of defaultChecked) check(id);
+		ctx.events.emit({
+			name: "visibility",
+			keys: ctx.tree.expandedKeys()
+		});
+		ctx.events.emit({
+			name: "checked",
+			keys: Array.from(checkedKeys)
+		});
+		return {
+			checkedKeys,
+			indeterminateKeys,
+			isChecked,
+			isIndeterminate,
+			check,
+			uncheck,
+			toggleCheck
+		};
+	},
+	extendNode(node, ctx) {
+		node.isChecked = () => ctx.tree.isChecked(node.id);
+		node.isIndeterminate = () => ctx.tree.isIndeterminate(node.id);
+		node.toggleCheck = (checked) => {
+			if (checked === void 0) ctx.tree.toggleCheck(node.id);
+			else if (checked) ctx.tree.check(node.id);
+			else ctx.tree.uncheck(node.id);
+		};
+	}
+};
+var src_default = checkable;
+
+//#endregion
+export { checkable, src_default as default };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@splicetree/plugin-checkable",
+  "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,241 @@
+import type { SpliceTreePlugin, SpliceTreePluginContext } from '@splicetree/core'
+import '@splicetree/core'
+
+declare module '@splicetree/core' {
+  /**
+   * 选项扩展（Checkable）
+   * - defaultChecked：初始勾选的节点 id 列表
+   */
+  interface UseSpliceTreeOptions {
+    /**
+     * 初始勾选的节点 id 列表
+     * 在初始化时将这些节点设置为已勾选
+     */
+    defaultChecked?: string[]
+  }
+
+  /**
+   * 节点扩展（Checkable）
+   * - isChecked：是否已勾选
+   * - isIndeterminate：是否半选
+   * - toggleCheck：切换或显式设置勾选状态
+   */
+  interface SpliceTreeNode {
+    /**
+     * 当前节点是否已勾选
+     */
+    isChecked: () => boolean
+    /**
+     * 当前节点是否为半选状态
+     */
+    isIndeterminate: () => boolean
+    /**
+     * 切换或显式设置当前节点的勾选状态
+     * @param checked 不传表示切换；true/false 表示显式设置
+     */
+    toggleCheck: (checked?: boolean) => void
+  }
+
+  /**
+   * 事件扩展（Checkable）
+   * - checked：勾选集合变化时派发
+   */
+  interface SpliceTreeEventPayloadMap {
+    /**
+     * 勾选集合变化事件负载
+     * @property keys 当前所有已勾选节点的 id 列表
+     */
+    checked: { keys: string[] }
+  }
+
+  /**
+   * 实例扩展（Checkable）
+   * - checkedKeys/indeterminateKeys：当前勾选/半选集合
+   * - isChecked/isIndeterminate：查询节点状态
+   * - check/uncheck/toggleCheck：操作勾选状态
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 已勾选的节点 id 集合
+     */
+    checkedKeys: Set<string>
+    /**
+     * 半选的节点 id 集合
+     */
+    indeterminateKeys: Set<string>
+    /**
+     * 查询指定节点是否已勾选
+     */
+    isChecked: (id: string) => boolean
+    /**
+     * 查询指定节点是否为半选状态
+     */
+    isIndeterminate: (id: string) => boolean
+    /**
+     * 勾选指定节点
+     */
+    check: (id: string) => void
+    /**
+     * 取消勾选指定节点
+     */
+    uncheck: (id: string) => void
+    /**
+     * 切换指定节点的勾选状态
+     */
+    toggleCheck: (id: string) => void
+  }
+}
+
+/**
+ * 设置某节点的勾选状态并维护集合
+ * @param id 节点 id
+ * @param state 目标状态（checked/unchecked/indeterminate）
+ * @param checked 已勾选集合
+ * @param indeterminate 半选集合
+ */
+function setChecked(
+  id: string,
+  state: 'checked' | 'unchecked' | 'indeterminate',
+  checked: Set<string>,
+  indeterminate: Set<string>,
+) {
+  if (state === 'checked') {
+    checked.add(id)
+    indeterminate.delete(id)
+  } else if (state === 'unchecked') {
+    checked.delete(id)
+    indeterminate.delete(id)
+  } else {
+    checked.delete(id)
+    indeterminate.add(id)
+  }
+}
+
+export const checkable: SpliceTreePlugin = {
+  name: 'checkable',
+
+  /**
+   * 勾选/半选插件：支持向下级联与向上计算半选
+   */
+  setup(ctx: SpliceTreePluginContext) {
+    const { defaultChecked = [] } = ctx.options
+
+    const checkedKeys = new Set<string>(defaultChecked)
+    const indeterminateKeys = new Set<string>()
+
+    const isChecked = (id: string) => checkedKeys.has(id)
+    const isIndeterminate = (id: string) => indeterminateKeys.has(id)
+
+    /**
+     * 向下遍历所有子节点并执行回调
+     * @param id 起始父节点 id
+     * @param visit 对每个子节点执行的回调
+     */
+    const descend = (id: string, visit: (nid: string) => void) => {
+      const n = ctx.tree.getNode(id)
+      if (!n) {
+        return
+      }
+      for (const c of n.getChildren()) {
+        visit(c.id)
+        descend(c.id, visit)
+      }
+    }
+
+    /**
+     * 自底向上更新祖先节点的勾选/半选状态
+     * - 所有子节点全勾选 → 祖先设为勾选
+     * - 所有子节点全未勾选 → 祖先设为未勾选
+     * - 否则 → 祖先设为半选
+     * 同步派发 visibility 与 checked 事件
+     * @param id 起始子节点 id
+     */
+    const updateAncestors = (id: string) => {
+      let cur = ctx.tree.getNode(id)?.getParent()
+      while (cur) {
+        const children = cur.getChildren()
+        const allChecked = children.every(ch => checkedKeys.has(ch.id))
+        const noneChecked = children.every(ch => !checkedKeys.has(ch.id) && !indeterminateKeys.has(ch.id))
+        if (allChecked) {
+          setChecked(cur.id, 'checked', checkedKeys, indeterminateKeys)
+        } else if (noneChecked) {
+          setChecked(cur.id, 'unchecked', checkedKeys, indeterminateKeys)
+        } else {
+          setChecked(cur.id, 'indeterminate', checkedKeys, indeterminateKeys)
+        }
+        cur = cur.getParent()
+      }
+
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+      ctx.events.emit({ name: 'checked', keys: Array.from(checkedKeys) })
+    }
+
+    /**
+     * 勾选指定节点，并向下级联勾选所有子节点
+     * @param id 节点 id
+     */
+    const check = (id: string) => {
+      setChecked(id, 'checked', checkedKeys, indeterminateKeys)
+      descend(id, nid => setChecked(nid, 'checked', checkedKeys, indeterminateKeys))
+      updateAncestors(id)
+    }
+
+    /**
+     * 取消勾选指定节点，并向下级联取消所有子节点
+     * @param id 节点 id
+     */
+    const uncheck = (id: string) => {
+      setChecked(id, 'unchecked', checkedKeys, indeterminateKeys)
+      descend(id, nid => setChecked(nid, 'unchecked', checkedKeys, indeterminateKeys))
+      updateAncestors(id)
+    }
+
+    /**
+     * 切换指定节点的勾选状态
+     * @param id 节点 id
+     */
+    const toggleCheck = (id: string) => {
+      if (isChecked(id)) {
+        uncheck(id)
+      } else {
+        check(id)
+      }
+      updateAncestors(id)
+    }
+
+    for (const id of defaultChecked) {
+      check(id)
+    }
+    ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    ctx.events.emit({ name: 'checked', keys: Array.from(checkedKeys) } as any)
+
+    return {
+      checkedKeys,
+      indeterminateKeys,
+      isChecked,
+      isIndeterminate,
+      check,
+      uncheck,
+      toggleCheck,
+    }
+  },
+
+  /**
+   * 为节点扩展勾选相关方法
+   */
+  extendNode(node, ctx) {
+    node.isChecked = () => ctx.tree.isChecked(node.id)
+    node.isIndeterminate = () => ctx.tree.isIndeterminate(node.id)
+    node.toggleCheck = (checked?: boolean) => {
+      if (checked === undefined) {
+        ctx.tree.toggleCheck(node.id)
+      } else if (checked) {
+        ctx.tree.check(node.id)
+      } else {
+        ctx.tree.uncheck(node.id)
+      }
+    }
+  },
+}
+
+export default checkable

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