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

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

Virtualized large trees — useTreeState + @suaveplan/react-virtual when flattened node count > 100.
TreeViewError — code: TREE_VIEW_CONTEXT_MISSING.
Full keyboard navigation — ArrowDown/ArrowUp moves focus, ArrowRight expands, ArrowLeft collapses or moves to parent, Enter/Space selects.
Stories — TreeView and TreeNodeComponent each with default, large-tree, with-search, keyboard-nav, playground.
Playwright E2E — keyboard navigation and search filter.

File layout

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

2.9 KiB Raw Blame History