@splicetree/plugin-keyboard 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @splicetree/plugin-keyboard
+
+## 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,51 @@
+# @splicetree/plugin-keyboard
+
+[![version](https://img.shields.io/npm/v/@splicetree/plugin-keyboard.svg?label=version)](https://www.npmjs.com/package/@splicetree/plugin-keyboard)
+[![downloads](https://img.shields.io/npm/dm/@splicetree/plugin-keyboard.svg)](https://npmcharts.com/compare/%40splicetree%2Fplugin-keyboard?minimal=true)
+[![license](https://img.shields.io/npm/l/@splicetree/plugin-keyboard.svg)](https://www.npmjs.com/package/@splicetree/plugin-keyboard)
+[![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-keyboard`
+
+## 使用
+
+```ts
+import { createSpliceTree } from '@splicetree/core'
+import keyboardNavigation from '@splicetree/plugin-keyboard'
+
+const tree = createSpliceTree(data, {
+  plugins: [keyboardNavigation],
+  defaultActive: 'a',
+  autoListenKeyboard: true,
+  keymap: { expand: 'ArrowRight', collapse: 'ArrowLeft', next: 'ArrowDown', prev: 'ArrowUp' },
+})
+```
+
+## Api
+
+### Options
+
+| 选项                 | 类型                                                                   | 默认值          | 说明                             |
+| -------------------- | ---------------------------------------------------------------------- | --------------- | -------------------------------- |
+| `defaultActive`      | `string`                                                               | `undefined`     | 默认激活节点                     |
+| `autoListenKeyboard` | `boolean`                                                              | `true`          | 是否自动监听键盘事件             |
+| `keymap`             | `{ expand?: string; collapse?: string; next?: string; prev?: string }` | `见下`          | 快捷键映射（默认：左右上下箭头） |
+| `keyboardTarget`     | `HTMLElement`                                                          | `document.body` | 键盘监听目标                     |
+
+### 实例方法
+
+| 名称                    | 参数                       | 说明                   |
+| ----------------------- | -------------------------- | ---------------------- |
+| `activeId`              | `无`                       | 当前激活的节点         |
+| `toggleActive(id, on?)` | `id: string; on?: boolean` | 切换或显式设置激活状态 |
+
+### 节点方法
+
+| 名称                | 参数           | 说明                 |
+| ------------------- | -------------- | -------------------- |
+| `toggleActive(on?)` | `on?: boolean` | 切换或显式设置激活态 |

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { SpliceTreePlugin } from "@splicetree/core";
+
+//#region src/index.d.ts
+type KeyboardTargetType = HTMLElement | string | null | undefined;
+type KeyboardTarget = KeyboardTargetType | (() => KeyboardTargetType);
+declare module '@splicetree/core' {
+  interface UseSpliceTreeOptions {
+    /**
+     * 默认激活节点 ID
+     * @default undefined
+     */
+    defaultActive?: string;
+    /**
+     * 是否自动监听键盘事件
+     * 开启后，插件会自动监听键盘事件
+     * 关闭后，需要手动调用 `listenKeyboard` 方法监听键盘事件
+     * @default true
+     */
+    autoListenKeyboard?: boolean;
+    /**
+     * 键盘导航快捷键
+     * @default { expand: 'ArrowRight', collapse: 'ArrowLeft', next: 'ArrowDown', prev: 'ArrowUp' }
+     */
+    keymap?: {
+      expand?: string;
+      collapse?: string;
+      next?: string;
+      prev?: string;
+    };
+    /**
+     * 键盘导航目标元素
+     * @default document.body
+     */
+    keyboardTarget?: KeyboardTarget;
+  }
+  /**
+   * 实例扩展（Keyboard）
+   * - activeId：当前激活的节点 id
+   * - toggleActive：切换或显式设置某节点的激活态
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 当前激活的节点 id（未激活时为 undefined）
+     */
+    activeId?: string;
+    /**
+     * 切换或显式设置某节点的激活态
+     * @param id 节点 id
+     * @param active 不传表示切换；true/false 表示显式设置
+     */
+    toggleActive: (id: string, active?: boolean) => void;
+  }
+  /**
+   * 节点扩展（Keyboard）
+   * - isActive：当前节点是否激活
+   * - toggleActive：切换当前节点的激活态
+   */
+  interface SpliceTreeNode {
+    /**
+     * 当前节点是否为激活态
+     */
+    isActive: () => boolean;
+    /**
+     * 切换当前节点的激活态
+     * @param active 不传表示切换；true/false 表示显式设置
+     */
+    toggleActive: (active?: boolean) => void;
+  }
+}
+declare const keyboardNavigation: SpliceTreePlugin;
+//#endregion
+export { keyboardNavigation as default, keyboardNavigation };

package/dist/index.js

@@ -0,0 +1,147 @@
+//#region src/index.ts
+/**
+* 解析键盘监听目标元素
+* 支持传入选择器、元素实例或函数
+*/
+function resolveKeyboardTarget(targe) {
+	if (typeof targe === "string") return document.querySelector(targe);
+	if (targe instanceof HTMLElement) return targe;
+	if (typeof targe === "function") return resolveKeyboardTarget(targe?.());
+	return null;
+}
+const keyboardNavigation = {
+	name: "keyboard",
+	setup(ctx) {
+		const { defaultActive, autoListenKeyboard = true, keyboardTarget, keymap } = ctx.options;
+		let activeId = defaultActive;
+		Object.defineProperty(ctx.tree, "activeId", {
+			get() {
+				return activeId;
+			},
+			configurable: true,
+			enumerable: true
+		});
+		/**
+		* 切换或设置激活节点
+		* 更新后派发 visibility 事件以刷新视图
+		* @param id 节点 id
+		* @param active 不传表示切换；true/false 表示显式设置
+		*/
+		const toggleActive = (id, active) => {
+			if (active === void 0) activeId = activeId === id ? void 0 : id;
+			else if (active) activeId = id;
+			else if (activeId === id) activeId = void 0;
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 按可见序列移动激活项
+		* @param delta 移动步长（-1 上一个，1 下一个）
+		*/
+		const moveActive = (delta) => {
+			const items = ctx.tree.items();
+			if (!items.length) return;
+			const idx = activeId ? items.findIndex((n) => n.id === activeId) : -1;
+			activeId = items[Math.max(0, Math.min(items.length - 1, idx < 0 ? 0 : idx + delta))]?.id;
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 激活上一个可见节点
+		*/
+		const keyUp = () => moveActive(-1);
+		/**
+		* 激活下一个可见节点
+		*/
+		const keyDown = () => moveActive(1);
+		/**
+		* 左方向键：优先收起；否则激活父节点
+		*/
+		const keyLeft = () => {
+			if (!activeId) return;
+			const node = ctx.tree.getNode(activeId);
+			if (!node) return;
+			if (ctx.tree.isExpanded(node.id)) ctx.tree.collapse(node.id);
+			else if (node.getParent()?.id) activeId = node.getParent().id;
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 右方向键：优先展开；已展开则进入第一个子节点
+		*/
+		const keyRight = () => {
+			if (!activeId) return;
+			const node = ctx.tree.getNode(activeId);
+			if (!node) return;
+			if (!ctx.tree.isExpanded(node.id)) ctx.tree.expand(node.id);
+			else {
+				const first = node.getChildren()[0];
+				if (first) activeId = first.id;
+			}
+			ctx.events.emit({
+				name: "visibility",
+				keys: ctx.tree.expandedKeys()
+			});
+		};
+		/**
+		* 键盘按下事件处理
+		* - 根据 keymap 映射调用对应处理函数
+		* - 自动阻止默认行为以避免滚动
+		*/
+		const onKeydown = (e) => {
+			const kExpand = keymap?.expand ?? "ArrowRight";
+			const kCollapse = keymap?.collapse ?? "ArrowLeft";
+			const kNext = keymap?.next ?? "ArrowDown";
+			const kPrev = keymap?.prev ?? "ArrowUp";
+			const key = e.key;
+			if (key === kPrev) {
+				e.preventDefault();
+				keyUp();
+				return;
+			}
+			if (key === kNext) {
+				e.preventDefault();
+				keyDown();
+				return;
+			}
+			if (key === kCollapse) {
+				e.preventDefault();
+				keyLeft();
+				return;
+			}
+			if (key === kExpand) {
+				e.preventDefault();
+				keyRight();
+			}
+		};
+		if (autoListenKeyboard && typeof document !== "undefined") setTimeout(() => {
+			const root = resolveKeyboardTarget(keyboardTarget);
+			if (root) {
+				root.setAttribute("tabindex", "0");
+				root?.focus?.();
+			}
+			const handler = (e) => {
+				const active = document.activeElement;
+				if (!root || root.contains(active)) onKeydown(e);
+			};
+			document.addEventListener("keydown", handler);
+		});
+		return { toggleActive };
+	},
+	extendNode(node, ctx) {
+		node.isActive = () => ctx.tree?.activeId === node.id;
+		node.toggleActive = (active) => {
+			ctx.tree.toggleActive(node.id, active);
+		};
+	}
+};
+var src_default = keyboardNavigation;
+
+//#endregion
+export { src_default as default, keyboardNavigation };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@splicetree/plugin-keyboard",
+  "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,252 @@
+import type { SpliceTreePlugin, SpliceTreePluginContext } from '@splicetree/core'
+import '@splicetree/core'
+
+type KeyboardTargetType = HTMLElement | string | null | undefined
+type KeyboardTarget = KeyboardTargetType | (() => KeyboardTargetType)
+declare module '@splicetree/core' {
+  export interface UseSpliceTreeOptions {
+    /**
+     * 默认激活节点 ID
+     * @default undefined
+     */
+    defaultActive?: string
+    /**
+     * 是否自动监听键盘事件
+     * 开启后，插件会自动监听键盘事件
+     * 关闭后，需要手动调用 `listenKeyboard` 方法监听键盘事件
+     * @default true
+     */
+    autoListenKeyboard?: boolean
+    /**
+     * 键盘导航快捷键
+     * @default { expand: 'ArrowRight', collapse: 'ArrowLeft', next: 'ArrowDown', prev: 'ArrowUp' }
+     */
+    keymap?: {
+      expand?: string
+      collapse?: string
+      next?: string
+      prev?: string
+    }
+    /**
+     * 键盘导航目标元素
+     * @default document.body
+     */
+    keyboardTarget?: KeyboardTarget
+  }
+
+  /**
+   * 实例扩展（Keyboard）
+   * - activeId：当前激活的节点 id
+   * - toggleActive：切换或显式设置某节点的激活态
+   */
+  interface SpliceTreeInstance {
+    /**
+     * 当前激活的节点 id（未激活时为 undefined）
+     */
+    activeId?: string
+    /**
+     * 切换或显式设置某节点的激活态
+     * @param id 节点 id
+     * @param active 不传表示切换；true/false 表示显式设置
+     */
+    toggleActive: (id: string, active?: boolean) => void
+  }
+
+  /**
+   * 节点扩展（Keyboard）
+   * - isActive：当前节点是否激活
+   * - toggleActive：切换当前节点的激活态
+   */
+  interface SpliceTreeNode {
+    /**
+     * 当前节点是否为激活态
+     */
+    isActive: () => boolean
+    /**
+     * 切换当前节点的激活态
+     * @param active 不传表示切换；true/false 表示显式设置
+     */
+    toggleActive: (active?: boolean) => void
+  }
+}
+
+/**
+ * 解析键盘监听目标元素
+ * 支持传入选择器、元素实例或函数
+ */
+function resolveKeyboardTarget(targe?: KeyboardTarget): HTMLElement | null {
+  if (typeof targe === 'string') {
+    return document.querySelector(targe)
+  }
+  if (targe instanceof HTMLElement) {
+    return targe
+  }
+  if (typeof targe === 'function') {
+    return resolveKeyboardTarget(targe?.())
+  }
+  return null
+}
+export const keyboardNavigation: SpliceTreePlugin = {
+  name: 'keyboard',
+  /**
+   * 键盘导航插件
+   * - 提供 activeId 概念与切换 API
+   * - 支持上下移动、展开/收起与进入子级
+   * - 自动或自定义监听目标元素的键盘事件
+   */
+  setup(ctx: SpliceTreePluginContext) {
+    const { defaultActive, autoListenKeyboard = true, keyboardTarget, keymap } = ctx.options
+    let activeId: string | undefined = defaultActive
+
+    Object.defineProperty(ctx.tree, 'activeId', {
+      get() {
+        return activeId
+      },
+      configurable: true,
+      enumerable: true,
+    })
+
+    /**
+     * 切换或设置激活节点
+     * 更新后派发 visibility 事件以刷新视图
+     * @param id 节点 id
+     * @param active 不传表示切换；true/false 表示显式设置
+     */
+    const toggleActive = (id: string, active?: boolean) => {
+      if (active === undefined) {
+        activeId = activeId === id ? undefined : id
+      } else {
+        if (active)
+          activeId = id
+        else if (activeId === id)
+          activeId = undefined
+      }
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 按可见序列移动激活项
+     * @param delta 移动步长（-1 上一个，1 下一个）
+     */
+    const moveActive = (delta: number) => {
+      const items = ctx.tree.items()
+      if (!items.length) {
+        return
+      }
+      const idx = activeId ? items.findIndex(n => n.id === activeId) : -1
+      const next = Math.max(0, Math.min(items.length - 1, (idx < 0 ? 0 : idx + delta)))
+      activeId = items[next]?.id
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+
+    /**
+     * 激活上一个可见节点
+     */
+    const keyUp = () => moveActive(-1)
+    /**
+     * 激活下一个可见节点
+     */
+    const keyDown = () => moveActive(1)
+    /**
+     * 左方向键：优先收起；否则激活父节点
+     */
+    const keyLeft = () => {
+      if (!activeId) {
+        return
+      }
+      const node = ctx.tree.getNode(activeId)
+      if (!node) {
+        return
+      }
+      if (ctx.tree.isExpanded(node.id)) {
+        ctx.tree.collapse(node.id)
+      } else if (node.getParent()?.id) {
+        activeId = node.getParent()!.id
+      }
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+    /**
+     * 右方向键：优先展开；已展开则进入第一个子节点
+     */
+    const keyRight = () => {
+      if (!activeId) {
+        return
+      }
+      const node = ctx.tree.getNode(activeId)
+      if (!node) {
+        return
+      }
+      if (!ctx.tree.isExpanded(node.id)) {
+        ctx.tree.expand(node.id)
+      } else {
+        const first = node.getChildren()[0]
+        if (first) {
+          activeId = first.id
+        }
+      }
+      ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+    }
+    /**
+     * 键盘按下事件处理
+     * - 根据 keymap 映射调用对应处理函数
+     * - 自动阻止默认行为以避免滚动
+     */
+    const onKeydown = (e: KeyboardEvent) => {
+      const kExpand = keymap?.expand ?? 'ArrowRight'
+      const kCollapse = keymap?.collapse ?? 'ArrowLeft'
+      const kNext = keymap?.next ?? 'ArrowDown'
+      const kPrev = keymap?.prev ?? 'ArrowUp'
+      const key = e.key
+      if (key === kPrev) {
+        e.preventDefault()
+        keyUp()
+        return
+      }
+      if (key === kNext) {
+        e.preventDefault()
+        keyDown()
+        return
+      }
+      if (key === kCollapse) {
+        e.preventDefault()
+        keyLeft()
+        return
+      }
+      if (key === kExpand) {
+        e.preventDefault()
+        keyRight()
+      }
+    }
+    if (autoListenKeyboard && typeof document !== 'undefined') {
+      setTimeout(() => {
+        const root = resolveKeyboardTarget(keyboardTarget)
+        if (root) {
+          root.setAttribute('tabindex', '0')
+          root?.focus?.()
+        }
+        const handler = (e: KeyboardEvent) => {
+          const active = document.activeElement
+          // 仅当 activeElement 在树容器内时触发
+          if (!root || root.contains(active)) {
+            onKeydown(e)
+          }
+        }
+        document.addEventListener('keydown', handler)
+      })
+    }
+    return { toggleActive }
+  },
+  /**
+   * 为节点扩展激活态判断方法
+   * - isActive：是否为当前激活项
+   * - toggleActive：切换当前节点的激活态
+   */
+  extendNode(node, ctx) {
+    node.isActive = () => ctx.tree?.activeId === node.id
+    node.toggleActive = (active?: boolean) => {
+      ctx.tree.toggleActive(node.id, active)
+    }
+  },
+}
+
+export default keyboardNavigation

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