Navigating deep file hierarchies, project structures, and multi-level menus requires a component that scales from 5 to 500 nodes without reinventing expand/collapse, icon rendering, keyboard navigation, and drag-and-drop. Building these from divs and buttons forces you to wire up accessibility attributes, visual feedback, tree state management, and DOM-scraping agents — all from scratch, every project.

TreeNav is a controlled compound component with a nodes array of objects (each with id, label, type, optional children). Expand/collapse is managed via expandedIds + onExpandedChange; selection via selectedId + onSelect. Folders auto-detect from the children array or an explicit type: "folder". File icons color-code by extension (ts, php, html, etc.); folders show open/closed chevrons. Drag-and-drop reordering fires onNodeMove(sourceId, targetId, position) with drop positions of "before", "after", or "inside"; external file drops trigger onExternalDrop(event, target, position) when acceptExternalDrops is true. Disabled nodes are unreachable. Stable selectors data-react-fancy-tree-nav, data-react-fancy-tree-node, and data-react-fancy-tree-drop-indicator anchor agent mutations and observers.

Import TreeNav from @particle-academy/react-fancy, pass a nodes array shaped like [{ id: "file1", label: "app.tsx", type: "file", ext: "tsx" }, { id: "src", label: "src", type: "folder", children: [...] }], then wire selectedId, onSelect, expandedIds, onExpandedChange. For drag-and-drop, set draggable={true} and define onNodeMove; for file uploads, add acceptExternalDrops={true} and onExternalDrop. Agents read/mutate the tree via stable handles and the context hook useTreeNav().