feat: initial open-source release of react-cascading-input

Co-Authored-By: Claude <noreply@anthropic.com>

Author: chenJJ-88

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+    push:
+        branches: [main, master]
+    pull_request:
+
+# 同一分支只保留最新一次运行，节省 CI 资源
+concurrency:
+    group: ci-${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    verify:
+        name: Lint & Test (Node ${{ matrix.node }})
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+            matrix:
+                node: [18, 20, 22]
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+
+            - name: Setup Node.js ${{ matrix.node }}
+              uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node }}
+                  cache: pnpm
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Lint
+              run: pnpm lint
+
+            - name: Typecheck
+              run: pnpm typecheck
+
+            - name: Test
+              run: pnpm test
+
+            - name: Build
+              run: pnpm build

.gitignore

@@ -0,0 +1,31 @@
+# dependencies
+node_modules
+
+# build output
+dist
+
+# test coverage
+coverage
+
+# logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment / secrets
+*.local
+
+# editor / IDE
+.idea/
+.vscode/*
+!.vscode/extensions.json
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+
+# OS
+.DS_Store
+Thumbs.db

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

.npmrc

@@ -0,0 +1 @@
+auto-install-peers=true

CLAUDE.md

@@ -0,0 +1,37 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+pnpm dev            # start demo dev server
+pnpm build          # typecheck (src only) + vite library build → dist/
+pnpm test           # vitest run (all tests once)
+pnpm test:watch     # vitest watch mode
+pnpm typecheck      # tsc --noEmit for src + demo + node configs
+pnpm lint           # biome check
+pnpm lint:fix       # biome check --write (auto-fix)
+```
+
+Run a single test file:
+```bash
+pnpm vitest run __tests__/useTreeData.test.ts
+```
+
+## Architecture
+
+This is a **library** project. `src/index.ts` is the published entry point; `demo/` and `__tests__/` are dev-only and excluded from the build.
+
+**Data model:** `TreeNode[]` — a recursive tree where each node carries dynamic fields keyed by `ColumnConfig.dataIndex`, plus `id` and `children`. The tree is fully controlled: callers own state, pass `value` + `onChange`.
+
+**Core split:**
+- `src/CascadingInput.tsx` — renders the tree recursively via `renderLevel()`, wires up hooks, provides `DefaultCellRenderer` (native HTML). Each cell gets `id="cell-${node.id}"` for Canvas targeting.
+- `src/hooks/useTreeData.ts` — pure tree mutation helpers (`createChain`, `updateTreeValue`, `addSiblingNode`, `deleteNodeCascade`) plus `useTreeData` hook and `ensureInitialData`. All helpers are exported and unit-tested directly.
+- `src/hooks/useCanvasLines.ts` — reads DOM positions via `getBoundingClientRect()` on `#cell-${id}` elements and draws lines on a `<canvas>` overlay. Uses `useLayoutEffect` to draw before paint; `ResizeObserver` for container resizes.
+
+**Headless pattern:** Every column can supply `ColumnConfig.render` to fully replace the cell UI. Without it, `DefaultCellRenderer` is used. This is how antd/any-UI-library integration works — no hard dependency.
+
+**tsconfig setup:** Project references split: `tsconfig.src.json` (lib), `tsconfig.demo.json` (demo + tests), `tsconfig.node.json` (vite configs). `tsconfig.base.json` holds shared `compilerOptions`.
+
+**Build output:** `dist/index.js` (ESM), `dist/index.cjs` (CJS), `dist/index.d.ts` (types), `dist/style.css`. CSS export is `"./styles": "./dist/style.css"` — `cssFileName: 'style'` in `vite.config.ts` controls this.

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# 贡献指南 (Contributing)
+
+感谢你对 `react-cascading-input` 的关注！欢迎提 Issue、PR 或参与讨论。
+
+## 环境要求
+
+- Node.js `>= 18`
+- pnpm（项目锁定版本见 `package.json` 的 `packageManager` 字段，首次可 `corepack enable` 自动启用）
+
+## 本地开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动 demo 开发服务器（Vite）
+pnpm dev
+
+# 类型检查
+pnpm typecheck
+
+# 运行单元测试
+pnpm test
+
+# 构建（先类型检查再打包到 dist/）
+pnpm build
+```
+
+## 代码规范
+
+- 提交前会自动通过 husky + lint-staged 运行 Biome（见 `.husky/pre-commit`）。
+- 手动检查：
+
+```bash
+pnpm lint          # Biome lint + 格式检查
+pnpm lint:fix      # 自动修复 lint 问题和格式
+pnpm format:check  # 仅格式检查
+pnpm format        # 自动格式化
+```
+
+- 代码风格：4 空格缩进、单引号、尾随逗号、语句分号（由 Biome 强制，配置见 `biome.json`）。
+- 请保持已有注释密度与命名风格，新增逻辑尽量复用 `src/hooks` 中已有工具。
+
+## 项目结构
+
+```
+src/
+├── index.ts              # 库入口
+├── types.ts              # 类型定义
+├── CascadingInput.tsx    # 主组件（Headless 逻辑 + 默认渲染器）
+├── hooks/
+│   ├── useTreeData.ts    # 树数据增删改
+│   └── useCanvasLines.ts # Canvas 关系线绘制
+└── styles/
+    └── index.css         # 默认渲染器样式
+demo/                     # 本地 demo（不发布）
+__tests__/                # 单元测试（Vitest + Testing Library）
+```
+
+## 提交与 PR 流程
+
+1. Fork 仓库并新建分支：`feat/xxx`、`fix/xxx` 或 `docs/xxx`。
+2. 保证 `pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build` 全部通过。
+3. 如果新增/修改了对外 API，请同步更新 `README.md` 与测试用例。
+4. 提交 PR，描述清楚动机与改动点。CI（GitHub Actions）会自动跑 lint / typecheck / test / build。
+
+## 行为准则
+
+请保持友善、尊重，致力于建设包容的开源社区。

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenJJ-88
+
+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.