@particle-academy/react-fancy 1.9.0 → 2.0.0

package/docs/TreeNav.md

@@ -48,6 +48,9 @@ const files: TreeNodeData[] = [
 | nodes | `TreeNodeData[]` | - | Tree data (required) |
 | selectedId | `string` | - | Currently selected node ID |
 | onSelect | `(id: string, node: TreeNodeData) => void` | - | Selection callback |
+| onNodeContextMenu | `(e: React.MouseEvent, node: TreeNodeData) => void` | - | Right-click callback per node |
+| draggable | `boolean` | `false` | Enable drag-and-drop reordering |
+| onNodeMove | `(sourceId: string, targetId: string, position: DropPosition) => void` | - | Callback when a node is moved via drag-and-drop |
 | expandedIds | `string[]` | - | Controlled expanded node IDs |
 | defaultExpandedIds | `string[]` | - | Initial expanded nodes (uncontrolled) |
 | onExpandedChange | `(ids: string[]) => void` | - | Callback when expanded state changes |
@@ -141,6 +144,81 @@ Override with the `icon` field on any node:
 { id: "special", label: "config", icon: <GearIcon /> }
 ```
 
+## Drag and Drop
+
+Enable drag-and-drop reordering with the `draggable` prop. The tree itself is never mutated — your `onNodeMove` callback receives the source, target, and position, and you update state accordingly.
+
+```tsx
+import { TreeNav } from "@particle-academy/react-fancy";
+import type { TreeNodeData, DropPosition } from "@particle-academy/react-fancy";
+
+const [files, setFiles] = useState<TreeNodeData[]>(initialFiles);
+
+function handleNodeMove(sourceId: string, targetId: string, position: DropPosition) {
+  // position is "before", "after", or "inside" (folders only)
+  setFiles((prev) => moveNode(prev, sourceId, targetId, position));
+}
+
+<TreeNav
+  nodes={files}
+  draggable
+  onNodeMove={handleNodeMove}
+/>
+```
+
+**Drop positions:**
+- `"before"` — insert above the target node (thin blue line indicator)
+- `"after"` — insert below the target node (thin blue line indicator)
+- `"inside"` — drop into a folder (blue highlight on the folder)
+
+**Built-in safety:**
+- Cannot drop a node onto itself
+- Cannot drop a node into its own descendants
+- Folders auto-expand after 500ms when dragging over them
+- Disabled nodes cannot be dragged
+
+## Context Menu
+
+Use `onNodeContextMenu` with the `ContextMenu` component to add right-click menus per node:
+
+```tsx
+import { TreeNav, ContextMenu } from "@particle-academy/react-fancy";
+
+const [ctxNode, setCtxNode] = useState<TreeNodeData | null>(null);
+
+<ContextMenu>
+  <ContextMenu.Trigger>
+    <TreeNav
+      nodes={files}
+      selectedId={selectedFile}
+      onSelect={handleSelect}
+      onNodeContextMenu={(e, node) => setCtxNode(node)}
+    />
+  </ContextMenu.Trigger>
+  <ContextMenu.Content>
+    {ctxNode?.type === "folder" ? (
+      <>
+        <ContextMenu.Item>New File</ContextMenu.Item>
+        <ContextMenu.Item>New Folder</ContextMenu.Item>
+      </>
+    ) : (
+      <>
+        <ContextMenu.Item onClick={() => openFile(ctxNode)}>
+          Open File
+        </ContextMenu.Item>
+        <ContextMenu.Item onClick={() => copyName(ctxNode)}>
+          Copy File Name
+        </ContextMenu.Item>
+        <ContextMenu.Separator />
+        <ContextMenu.Item danger>Delete</ContextMenu.Item>
+      </>
+    )}
+  </ContextMenu.Content>
+</ContextMenu>
+```
+
+The `onNodeContextMenu` callback fires with the mouse event and the node data. Wrap TreeNav in `ContextMenu.Trigger` to let the ContextMenu handle positioning and open/close — the callback just tracks which node was right-clicked so you can render different menu items for files vs folders.
+
 ## IDE Layout Example
 
 Pair with `@particle-academy/fancy-code` for a full IDE:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "type": "module",
   "main": "./dist/index.cjs",