@particle-academy/react-fancy 2.8.0 → 2.9.0

package/docs/Canvas.md

@@ -37,8 +37,11 @@ import { Canvas } from "@particle-academy/react-fancy";
 | maxZoom | `number` | `3` | Maximum zoom level |
 | pannable | `boolean` | `true` | Enable panning (click+drag on background) |
 | zoomable | `boolean` | `true` | Enable zoom (Ctrl+scroll) |
-| gridSize | `number` | - | Grid cell size in px |
-| showGrid | `boolean` | `false` | Display dot grid background |
+| gridSize | `number` | `20` | Grid cell size in canvas-space pixels |
+| showGrid | `boolean` | `false` | Display the canvas grid background |
+| gridStyle | `'dots' \| 'lines' \| 'none'` | `'dots'` | Grid pattern when shown. `'none'` hides the grid even when `showGrid` is true |
+| gridColor | `string` | `'rgb(161 161 170 / 0.3)'` | Any CSS color for grid dots/lines |
+| snapToGrid | `boolean` | `false` | Snap dragged nodes to the grid |
 | fitOnMount | `boolean` | `false` | Auto-fit all nodes into view on mount |
 | className | `string` | - | Additional CSS classes |
 | style | `CSSProperties` | - | Inline styles |

package/docs/TreeNav.md

@@ -49,8 +49,10 @@ const files: TreeNodeData[] = [
 | 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 |
+| draggable | `boolean` | `false` | Enable drag-and-drop reordering of tree nodes |
+| onNodeMove | `(sourceId: string, targetId: string, position: DropPosition) => void` | - | Callback when a node is moved via drag-and-drop within the tree |
+| acceptExternalDrops | `boolean` | `false` | Accept drops from outside the tree — OS files, items dragged from other components, etc. |
+| onExternalDrop | `(event: React.DragEvent, target: TreeNodeData, position: DropPosition) => void` | - | Fires on external drop. Read `event.dataTransfer.files` for OS file drops or `event.dataTransfer.getData(type)` for custom MIME payloads. |
 | expandedIds | `string[]` | - | Controlled expanded node IDs |
 | defaultExpandedIds | `string[]` | - | Initial expanded nodes (uncontrolled) |
 | onExpandedChange | `(ids: string[]) => void` | - | Callback when expanded state changes |
@@ -177,6 +179,29 @@ function handleNodeMove(sourceId: string, targetId: string, position: DropPositi
 - Folders auto-expand after 500ms when dragging over them
 - Disabled nodes cannot be dragged
 
+## External Drops (files, cross-component)
+
+Set `acceptExternalDrops` and supply `onExternalDrop` to accept payloads from outside the tree — OS files dragged from the desktop, items dragged from a Kanban card, anything that ships a `dataTransfer`. The same `before` / `after` / `inside` indicators apply, and folders still auto-expand.
+
+```tsx
+<TreeNav
+  nodes={files}
+  acceptExternalDrops
+  onExternalDrop={(event, target, position) => {
+    // OS file drop?
+    if (event.dataTransfer.files.length > 0) {
+      uploadFiles(event.dataTransfer.files, target.id);
+      return;
+    }
+    // Custom payload from another component?
+    const payload = event.dataTransfer.getData("application/x-card-id");
+    if (payload) attachCardToNode(payload, target.id, position);
+  }}
+/>
+```
+
+`acceptExternalDrops` and `draggable` are independent — enable either, both, or neither. With both on, internal drag-reorder and external drops coexist; the handler distinguishes via the absence of an internal drag source.
+
 ## Context Menu
 
 Use `onNodeContextMenu` with the `ContextMenu` component to add right-click menus per node:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "repository": {
     "type": "git",