Initial Commit
This commit is contained in:
87
openspec/changes/enterprise-react-tree-view/proposal.md
Normal file
87
openspec/changes/enterprise-react-tree-view/proposal.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# OpenSpec Change: enterprise-react-tree-view
|
||||
|
||||
- **Change ID**: enterprise-react-tree-view
|
||||
- **Package**: `@suaveplan/react-tree-view`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/ui/react-tree-view`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-tree-view.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-tree-view` on genesis from scratch at enterprise quality. A hierarchical tree-view React component with controlled/uncontrolled expand/collapse, text-based filter, keyboard navigation, `renderNode` slot, and pure utility functions (`flattenTree`, `filterTree`, `collectAllIds`). The `useTreeState` hook centralises expanded-id state. Genesis adds `@suaveplan/error`-backed errors, `@suaveplan/react-virtual` integration for large trees, stories for every component, Playwright keyboard-nav E2E, and 100% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `TreeViewError` |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n for search placeholder, aria-labels |
|
||||
| `@suaveplan/react-virtual` (`workspace:^`) | Virtualized nodes for large trees |
|
||||
| `zod` (`catalog:forms`) | Config schemas |
|
||||
|
||||
External: `tslib catalog:build`. React 18 peer.
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
TreeView<T> — top-level controlled/uncontrolled tree
|
||||
TreeNodeComponent<T> — single node renderer (arrow, indent, renderNode slot)
|
||||
useTreeState — expanded-ids Set, toggle/expand/collapse/expandAll/collapseAll/isExpanded
|
||||
|
||||
// Utils
|
||||
flattenTree<T>(root: TreeNode<T>): TreeNode<T>[]
|
||||
filterTree<T>(root: TreeNode<T>, predicate): TreeNode<T> | null
|
||||
collectAllIds<T>(root: TreeNode<T>): string[]
|
||||
|
||||
// Types
|
||||
TreeNode<T>, TreeViewProps<T>, UseTreeStateOptions, UseTreeStateReturn
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Virtualized large trees** — `useTreeState` + `@suaveplan/react-virtual` when flattened node count > 100.
|
||||
2. **`TreeViewError`** — code: `TREE_VIEW_CONTEXT_MISSING`.
|
||||
3. **Full keyboard navigation** — `ArrowDown`/`ArrowUp` moves focus, `ArrowRight` expands, `ArrowLeft` collapses or moves to parent, `Enter`/`Space` selects.
|
||||
4. **Stories** — `TreeView` and `TreeNodeComponent` each with `default`, `large-tree`, `with-search`, `keyboard-nav`, `playground`.
|
||||
5. **Playwright E2E** — keyboard navigation and search filter.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/ui/react-tree-view/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
components/
|
||||
tree-view/ (tsx + types + md + test + stories + index)
|
||||
tree-node/ (tsx + types + md + test + stories + index)
|
||||
hooks/
|
||||
use-tree-state/ (ts + types + md + test + index)
|
||||
types/
|
||||
tree.types.ts
|
||||
utils/
|
||||
tree-utils/ (ts + md + test + index)
|
||||
cn.ts
|
||||
e2e/
|
||||
tree-view.spec.ts
|
||||
```
|
||||
86
openspec/changes/enterprise-react-tree-view/tasks.md
Normal file
86
openspec/changes/enterprise-react-tree-view/tasks.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Tasks: enterprise-react-tree-view
|
||||
|
||||
**Change ID**: enterprise-react-tree-view
|
||||
**Package**: `@suaveplan/react-tree-view`
|
||||
**Target path**: `react/ui/react-tree-view`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/react-translate`, `@suaveplan/react-virtual`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree per proposal layout.
|
||||
- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map.
|
||||
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/react-translate workspace:^`, `@suaveplan/react-virtual workspace:^`, `zod catalog:forms`, `tslib catalog:build`.
|
||||
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types and errors
|
||||
|
||||
- [ ] Define `TreeViewError` extending `SuaveplanError`; code: `TREE_VIEW_CONTEXT_MISSING`.
|
||||
- [ ] Define `TreeNode<T>`: `{ id: string; label: string; children?: TreeNode<T>[]; data?: T; disabled?: boolean }`.
|
||||
- [ ] Define `TreeViewProps<T>`, `UseTreeStateOptions`, `UseTreeStateReturn`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utils (`src/utils/tree-utils/`)
|
||||
|
||||
- [ ] Implement `flattenTree<T>(root)` — DFS traversal, returns flat array.
|
||||
- [ ] Implement `filterTree<T>(root, predicate)` — returns subtree containing matching nodes; `null` if no match.
|
||||
- [ ] Implement `collectAllIds<T>(root)` — returns all `id` values.
|
||||
- [ ] Write `tree-utils.test.ts` (≤500 lines): flat tree, nested tree, filter no-match, filter partial-match, collectAllIds deep. `{ timeout: 5000 }`.
|
||||
- [ ] Write `tree-utils.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Hook — `useTreeState`
|
||||
|
||||
- [ ] Manages `expandedIds: Set<string>` in `useState`.
|
||||
- [ ] Exposes `toggle(id)`, `expand(id)`, `collapse(id)`, `expandAll(tree)`, `collapseAll()`, `isExpanded(id)`.
|
||||
- [ ] Controlled mode: accepts `expandedIds` + `onExpandedChange` props; uncontrolled: manages internally.
|
||||
- [ ] Activates `@suaveplan/react-virtual` `useVirtualList` when `flattenTree(root).length > 100`.
|
||||
- [ ] Write `use-tree-state.test.ts`: toggle, expand, collapse, expandAll, collapseAll, controlled mode, uncontrolled mode. `{ timeout: 5000 }`.
|
||||
- [ ] Write `use-tree-state.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Components
|
||||
|
||||
### TreeNodeComponent
|
||||
|
||||
- [ ] Renders arrow indicator (collapsed/expanded), indent per `depth`, optional `showLines`, `renderNode` slot for custom node markup.
|
||||
- [ ] Keyboard: `ArrowRight` expands, `ArrowLeft` collapses (or moves to parent when already collapsed), `ArrowDown`/`ArrowUp` moves focus to next/prev visible node.
|
||||
- [ ] `aria-expanded`, `aria-selected`, `role="treeitem"`, `tabIndex` management.
|
||||
- [ ] Write test, stories (default, with-custom-render, playground), md.
|
||||
|
||||
### TreeView
|
||||
|
||||
- [ ] Top-level controlled/uncontrolled tree: optional search input (`showSearch` prop) using `useTranslation` for placeholder; filters via `filterTree` on input change.
|
||||
- [ ] Renders `TreeNodeComponent` for each visible node; uses virtual list when node count > 100.
|
||||
- [ ] `role="tree"`, `aria-label` from i18n.
|
||||
- [ ] Write test, stories (default, large-tree 500 nodes, with-search, keyboard-nav, playground), md.
|
||||
|
||||
---
|
||||
|
||||
## 6. E2E
|
||||
|
||||
- [ ] `e2e/tree-view.spec.ts` — Playwright:
|
||||
- Render tree, click expand arrow, verify children visible.
|
||||
- Keyboard: Tab into tree, `ArrowRight` to expand, `ArrowDown` to move focus, `ArrowLeft` to collapse.
|
||||
- Type in search box, verify filtered nodes only.
|
||||
|
||||
---
|
||||
|
||||
## 7. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-tree-view` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-tree-view` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-tree-view`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user