参与贡献

感谢你愿意改进 OrgTree。提交前请先确认改动属于 Core、Vue、Standalone 或 Docs 中的哪一层，避免把框架逻辑引入核心布局包。

准备环境

git clone https://github.com/Liugq5713/tree.git
cd tree
pnpm install

要求 Node.js >= 18、pnpm >= 8。

仓库结构

packages/
├─ core/          纯 TypeScript 布局、状态、事件
├─ vue/           Vue 3 渲染层
└─ standalone/    IIFE/UMD 构建
apps/
└─ docs/          VitePress 文档站点与在线示例

依赖方向必须保持：

standalone → vue → core
docs demos → vue → core

Core 不能导入 Vue 或浏览器 UI 框架。

开发命令

pnpm dev              # 文档与在线示例，默认 3001 端口
pnpm dev:docs         # 显式启动 docs 应用
pnpm build            # 构建所有具有 build script 的包
pnpm build:standalone # 只构建独立产物
pnpm build:docs       # 只构建文档
pnpm lint             # 全仓库 ESLint

仓库当前没有测试框架，pnpm test 是占位命令并会失败。不要把它当作有效验证。

编码约定

• TypeScript 使用严格模式。
• 单引号、无分号、2 空格缩进。
• 类型导入使用 import type。
• 跨包引用使用包名和 workspace:*，不使用跨包相对路径。
• Core 错误信息以 [OrgTree] 开头。
• 修改数据结构时先更新 packages/core/src/types.ts。
• 公共 API 使用 JSDoc；复杂原因使用中文注释说明。
• 节点实际尺寸必须与布局 nodeSize 一致。

修改流程

1. 创建聚焦单一问题的分支。
2. 阅读相关类型、实现与现有在线示例。
3. 完成最小且边界清晰的改动。
4. 为新能力增加或更新在线示例。
5. 更新对应指南、API 和 FAQ。
6. 对改动文件运行 ESLint。
7. 运行相关构建和真实交互验证。

例如修改一个 TypeScript 文件：

pnpm exec eslint --fix path/to/changed-file.ts
pnpm build

修改网页 UI 后，应启动本地服务检查桌面与窄屏，并在结束时关闭服务、确认端口不再监听。

文档贡献

文档位于 apps/docs/docs/，在线示例源码位于 apps/docs/src/。新增页面时同时更新 .vitepress/config.mts 中的导航或侧栏。

pnpm dev:docs
pnpm build:docs

文档示例必须以当前源码为准，尤其注意：

• 默认字段是 id/parentId。
• data 和 api 互斥。
• setDirection() 后需要重新布局。
• highlight/visible 由业务渲染解释。
• 未发布的包不能写成已经可从 npm 安装。

Pull Request 清单

• [ ] 改动只涉及必要文件，没有覆盖无关工作区修改
• [ ] 公开类型、实现和文档保持一致
• [ ] 受影响文件通过 ESLint
• [ ] 相关构建成功
• [ ] 新行为通过真实最小用例验证
• [ ] UI 改动完成桌面和移动端检查
• [ ] 没有提交 dist、Vite 缓存或本地依赖目录

报告问题

提交 bug 时请包含：

• 最小数据和配置
• 使用的数据模式与布局方向
• Node、Vue、浏览器版本
• 预期结果与实际结果
• 可复现步骤、截图或控制台错误

布局问题请同时提供 nodeSize 和实际卡片 CSS。