@particle-academy/react-fancy 2.8.1 → 2.9.0

package/dist/index.d.cts

@@ -2231,7 +2231,12 @@ interface CanvasContextValue {
     nodeRects: Map<string, NodeRect>;
     registryVersion: number;
     containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Grid spacing in canvas-space pixels (unaffected by zoom). */
+    gridSize: number;
+    /** When true, dragged nodes snap their top-left corner to the grid. */
+    snapToGrid: boolean;
 }
+type GridStyle = "dots" | "lines" | "none";
 interface CanvasProps {
     children: ReactNode;
     viewport?: ViewportState;
@@ -2241,8 +2246,17 @@ interface CanvasProps {
     maxZoom?: number;
     pannable?: boolean;
     zoomable?: boolean;
+    /** Grid spacing in canvas-space pixels. Defaults to 20. */
     gridSize?: number;
+    /** Show/hide the canvas grid. Defaults to false. */
     showGrid?: boolean;
+    /** Grid pattern when shown — dots (default), lines, or none. Setting this
+     *  to "none" hides the grid even when `showGrid` is true. */
+    gridStyle?: GridStyle;
+    /** Grid color (any CSS color). Defaults to a faint zinc. */
+    gridColor?: string;
+    /** Snap dragged nodes to the grid. Defaults to false. */
+    snapToGrid?: boolean;
     /** Automatically fit all nodes into view on initial mount */
     fitOnMount?: boolean;
     className?: string;
@@ -2308,7 +2322,7 @@ declare namespace CanvasControls {
     var displayName: string;
 }
 
-declare function CanvasRoot({ children, viewport: controlledViewport, defaultViewport, onViewportChange, minZoom, maxZoom, pannable, zoomable, showGrid, fitOnMount, className, style, }: CanvasProps): react_jsx_runtime.JSX.Element;
+declare function CanvasRoot({ children, viewport: controlledViewport, defaultViewport, onViewportChange, minZoom, maxZoom, pannable, zoomable, showGrid, gridStyle, gridSize, gridColor, snapToGrid, fitOnMount, className, style, }: CanvasProps): react_jsx_runtime.JSX.Element;
 declare const Canvas: typeof CanvasRoot & {
     Node: typeof CanvasNode;
     Edge: typeof CanvasEdge;
@@ -2474,6 +2488,15 @@ interface TreeNavProps {
     draggable?: boolean;
     /** Callback when a node is moved via drag and drop */
     onNodeMove?: (sourceId: string, targetId: string, position: DropPosition) => void;
+    /** Accept drops from outside the tree — OS files, items from other
+     *  components, etc. When true, drag-over is allowed for any data source
+     *  and `onExternalDrop` fires on drop. (default: false) */
+    acceptExternalDrops?: boolean;
+    /** Called when an external drag (file or cross-component) is dropped on
+     *  a node. The raw event lets you read `event.dataTransfer.files` for OS
+     *  file drops or `event.dataTransfer.getData(type)` for custom MIME
+     *  payloads from other components. */
+    onExternalDrop?: (event: React.DragEvent, target: TreeNodeData, position: DropPosition) => void;
     /** Controlled expanded node IDs */
     expandedIds?: string[];
     /** Default expanded node IDs (uncontrolled) */
@@ -2501,6 +2524,8 @@ interface TreeNavContextValue {
     dragState: DragState;
     setDragState: (state: DragState) => void;
     onNodeMove?: (sourceId: string, targetId: string, position: DropPosition) => void;
+    acceptExternalDrops: boolean;
+    onExternalDrop?: (event: React.DragEvent, target: TreeNodeData, position: DropPosition) => void;
     nodes: TreeNodeData[];
     expandNode: (id: string) => void;
 }
@@ -2515,7 +2540,7 @@ declare namespace TreeNode {
     var displayName: string;
 }
 
-declare function TreeNavRoot({ nodes, selectedId, onSelect, onNodeContextMenu, draggable, onNodeMove, expandedIds: controlledExpanded, defaultExpandedIds, onExpandedChange, defaultExpandAll, indentSize, showIcons, className, }: TreeNavProps): react_jsx_runtime.JSX.Element;
+declare function TreeNavRoot({ nodes, selectedId, onSelect, onNodeContextMenu, draggable, onNodeMove, acceptExternalDrops, onExternalDrop, expandedIds: controlledExpanded, defaultExpandedIds, onExpandedChange, defaultExpandAll, indentSize, showIcons, className, }: TreeNavProps): react_jsx_runtime.JSX.Element;
 declare namespace TreeNavRoot {
     var displayName: string;
 }

package/dist/index.d.ts

@@ -2231,7 +2231,12 @@ interface CanvasContextValue {
     nodeRects: Map<string, NodeRect>;
     registryVersion: number;
     containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Grid spacing in canvas-space pixels (unaffected by zoom). */
+    gridSize: number;
+    /** When true, dragged nodes snap their top-left corner to the grid. */
+    snapToGrid: boolean;
 }
+type GridStyle = "dots" | "lines" | "none";
 interface CanvasProps {
     children: ReactNode;
     viewport?: ViewportState;
@@ -2241,8 +2246,17 @@ interface CanvasProps {
     maxZoom?: number;
     pannable?: boolean;
     zoomable?: boolean;
+    /** Grid spacing in canvas-space pixels. Defaults to 20. */
     gridSize?: number;
+    /** Show/hide the canvas grid. Defaults to false. */
     showGrid?: boolean;
+    /** Grid pattern when shown — dots (default), lines, or none. Setting this
+     *  to "none" hides the grid even when `showGrid` is true. */
+    gridStyle?: GridStyle;
+    /** Grid color (any CSS color). Defaults to a faint zinc. */
+    gridColor?: string;
+    /** Snap dragged nodes to the grid. Defaults to false. */
+    snapToGrid?: boolean;
     /** Automatically fit all nodes into view on initial mount */
     fitOnMount?: boolean;
     className?: string;
@@ -2308,7 +2322,7 @@ declare namespace CanvasControls {
     var displayName: string;
 }
 
-declare function CanvasRoot({ children, viewport: controlledViewport, defaultViewport, onViewportChange, minZoom, maxZoom, pannable, zoomable, showGrid, fitOnMount, className, style, }: CanvasProps): react_jsx_runtime.JSX.Element;
+declare function CanvasRoot({ children, viewport: controlledViewport, defaultViewport, onViewportChange, minZoom, maxZoom, pannable, zoomable, showGrid, gridStyle, gridSize, gridColor, snapToGrid, fitOnMount, className, style, }: CanvasProps): react_jsx_runtime.JSX.Element;
 declare const Canvas: typeof CanvasRoot & {
     Node: typeof CanvasNode;
     Edge: typeof CanvasEdge;
@@ -2474,6 +2488,15 @@ interface TreeNavProps {
     draggable?: boolean;
     /** Callback when a node is moved via drag and drop */
     onNodeMove?: (sourceId: string, targetId: string, position: DropPosition) => void;
+    /** Accept drops from outside the tree — OS files, items from other
+     *  components, etc. When true, drag-over is allowed for any data source
+     *  and `onExternalDrop` fires on drop. (default: false) */
+    acceptExternalDrops?: boolean;
+    /** Called when an external drag (file or cross-component) is dropped on
+     *  a node. The raw event lets you read `event.dataTransfer.files` for OS
+     *  file drops or `event.dataTransfer.getData(type)` for custom MIME
+     *  payloads from other components. */
+    onExternalDrop?: (event: React.DragEvent, target: TreeNodeData, position: DropPosition) => void;
     /** Controlled expanded node IDs */
     expandedIds?: string[];
     /** Default expanded node IDs (uncontrolled) */
@@ -2501,6 +2524,8 @@ interface TreeNavContextValue {
     dragState: DragState;
     setDragState: (state: DragState) => void;
     onNodeMove?: (sourceId: string, targetId: string, position: DropPosition) => void;
+    acceptExternalDrops: boolean;
+    onExternalDrop?: (event: React.DragEvent, target: TreeNodeData, position: DropPosition) => void;
     nodes: TreeNodeData[];
     expandNode: (id: string) => void;
 }
@@ -2515,7 +2540,7 @@ declare namespace TreeNode {
     var displayName: string;
 }
 
-declare function TreeNavRoot({ nodes, selectedId, onSelect, onNodeContextMenu, draggable, onNodeMove, expandedIds: controlledExpanded, defaultExpandedIds, onExpandedChange, defaultExpandAll, indentSize, showIcons, className, }: TreeNavProps): react_jsx_runtime.JSX.Element;
+declare function TreeNavRoot({ nodes, selectedId, onSelect, onNodeContextMenu, draggable, onNodeMove, acceptExternalDrops, onExternalDrop, expandedIds: controlledExpanded, defaultExpandedIds, onExpandedChange, defaultExpandAll, indentSize, showIcons, className, }: TreeNavProps): react_jsx_runtime.JSX.Element;
 declare namespace TreeNavRoot {
     var displayName: string;
 }

package/dist/index.js

@@ -11461,7 +11461,7 @@ function useCanvas() {
   return ctx;
 }
 function CanvasNode({ children, id, x, y, draggable, onPositionChange, className, style }) {
-  const { registerNode, unregisterNode, viewport } = useCanvas();
+  const { registerNode, unregisterNode, viewport, gridSize, snapToGrid } = useCanvas();
   const nodeRef = useRef(null);
   const isDragging = useRef(false);
   const dragStart = useRef({ mouseX: 0, mouseY: 0, nodeX: 0, nodeY: 0 });
@@ -11494,9 +11494,15 @@ function CanvasNode({ children, id, x, y, draggable, onPositionChange, className
       if (!isDragging.current) return;
       const dx = (e.clientX - dragStart.current.mouseX) / viewport.zoom;
       const dy = (e.clientY - dragStart.current.mouseY) / viewport.zoom;
-      onPositionChange?.(dragStart.current.nodeX + dx, dragStart.current.nodeY + dy);
+      let nx = dragStart.current.nodeX + dx;
+      let ny = dragStart.current.nodeY + dy;
+      if (snapToGrid && gridSize > 0) {
+        nx = Math.round(nx / gridSize) * gridSize;
+        ny = Math.round(ny / gridSize) * gridSize;
+      }
+      onPositionChange?.(nx, ny);
     },
-    [viewport.zoom, onPositionChange]
+    [viewport.zoom, onPositionChange, snapToGrid, gridSize]
   );
   const handlePointerUp = useCallback(() => {
     isDragging.current = false;
@@ -11744,6 +11750,10 @@ function CanvasRoot({
   pannable = true,
   zoomable = true,
   showGrid = false,
+  gridStyle = "dots",
+  gridSize = 20,
+  gridColor = "rgb(161 161 170 / 0.3)",
+  snapToGrid = false,
   fitOnMount = false,
   className,
   style
@@ -11761,8 +11771,8 @@ function CanvasRoot({
     containerRef
   });
   const ctx = useMemo(
-    () => ({ viewport, setViewport, registerNode, unregisterNode, nodeRects, registryVersion, containerRef }),
-    [viewport, setViewport, registerNode, unregisterNode, nodeRects, registryVersion]
+    () => ({ viewport, setViewport, registerNode, unregisterNode, nodeRects, registryVersion, containerRef, gridSize, snapToGrid }),
+    [viewport, setViewport, registerNode, unregisterNode, nodeRects, registryVersion, gridSize, snapToGrid]
   );
   const hasFitted = useRef(false);
   useEffect(() => {
@@ -11818,9 +11828,13 @@ function CanvasRoot({
           {
             "data-canvas-bg": "",
             className: "absolute inset-0",
-            style: showGrid ? {
-              backgroundImage: `radial-gradient(circle, rgb(161 161 170 / 0.3) 1px, transparent 1px)`,
-              backgroundSize: `${20 * viewport.zoom}px ${20 * viewport.zoom}px`,
+            style: showGrid && gridStyle !== "none" ? gridStyle === "lines" ? {
+              backgroundImage: `linear-gradient(to right, ${gridColor} 1px, transparent 1px), linear-gradient(to bottom, ${gridColor} 1px, transparent 1px)`,
+              backgroundSize: `${gridSize * viewport.zoom}px ${gridSize * viewport.zoom}px`,
+              backgroundPosition: `${viewport.panX}px ${viewport.panY}px`
+            } : {
+              backgroundImage: `radial-gradient(circle, ${gridColor} 1px, transparent 1px)`,
+              backgroundSize: `${gridSize * viewport.zoom}px ${gridSize * viewport.zoom}px`,
               backgroundPosition: `${viewport.panX}px ${viewport.panY}px`
             } : void 0
           }
@@ -12537,6 +12551,8 @@ function TreeNode({ node, depth }) {
     dragState,
     setDragState,
     onNodeMove,
+    acceptExternalDrops,
+    onExternalDrop,
     nodes,
     expandNode
   } = useTreeNav();
@@ -12579,14 +12595,18 @@ function TreeNode({ node, depth }) {
     clearAutoExpand();
     setDragState({ draggedNodeId: null, dropTargetId: null, dropPosition: null });
   }, [clearAutoExpand, setDragState]);
+  const isExternalDrag = !dragState.draggedNodeId;
   const handleDragOver = useCallback((e) => {
-    if (!dragState.draggedNodeId) return;
-    const sourceId = dragState.draggedNodeId;
-    if (sourceId === node.id) return;
-    if (isDescendantOf(nodes, sourceId, node.id)) return;
+    if (isExternalDrag) {
+      if (!acceptExternalDrops) return;
+    } else {
+      const sourceId = dragState.draggedNodeId;
+      if (sourceId === node.id) return;
+      if (isDescendantOf(nodes, sourceId, node.id)) return;
+    }
     e.preventDefault();
     e.stopPropagation();
-    e.dataTransfer.dropEffect = "move";
+    e.dataTransfer.dropEffect = isExternalDrag ? "copy" : "move";
     const position = computeDropPosition(e, !!isFolder);
     if (isFolder && !isExpanded && position === "inside") {
       if (!autoExpandTimer.current) {
@@ -12599,9 +12619,9 @@ function TreeNode({ node, depth }) {
       clearAutoExpand();
     }
     if (dragState.dropTargetId !== node.id || dragState.dropPosition !== position) {
-      setDragState({ draggedNodeId: sourceId, dropTargetId: node.id, dropPosition: position });
+      setDragState({ draggedNodeId: dragState.draggedNodeId, dropTargetId: node.id, dropPosition: position });
     }
-  }, [dragState, node.id, isFolder, isExpanded, nodes, setDragState, expandNode, clearAutoExpand]);
+  }, [dragState, isExternalDrag, acceptExternalDrops, node.id, isFolder, isExpanded, nodes, setDragState, expandNode, clearAutoExpand]);
   const handleDragLeave = useCallback((e) => {
     if (!e.currentTarget.contains(e.relatedTarget)) {
       clearAutoExpand();
@@ -12615,21 +12635,25 @@ function TreeNode({ node, depth }) {
     e.stopPropagation();
     clearAutoExpand();
     const sourceId = dragState.draggedNodeId;
-    const position = dragState.dropPosition;
-    if (!sourceId || !position) return;
-    if (sourceId === node.id) return;
-    if (isDescendantOf(nodes, sourceId, node.id)) return;
-    onNodeMove?.(sourceId, node.id, position);
+    const position = dragState.dropPosition ?? computeDropPosition(e, !!isFolder);
+    if (sourceId) {
+      if (sourceId === node.id) return;
+      if (isDescendantOf(nodes, sourceId, node.id)) return;
+      onNodeMove?.(sourceId, node.id, position);
+    } else if (acceptExternalDrops) {
+      onExternalDrop?.(e, node, position);
+    }
     setDragState({ draggedNodeId: null, dropTargetId: null, dropPosition: null });
-  }, [dragState, node.id, nodes, onNodeMove, setDragState, clearAutoExpand]);
+  }, [dragState, node, isFolder, nodes, onNodeMove, acceptExternalDrops, onExternalDrop, setDragState, clearAutoExpand]);
   const canDrag = draggable && !node.disabled;
+  const dropEnabled = draggable || acceptExternalDrops;
   return /* @__PURE__ */ jsxs(
     "div",
     {
       "data-react-fancy-tree-node": "",
-      onDragOver: draggable ? handleDragOver : void 0,
-      onDragLeave: draggable ? handleDragLeave : void 0,
-      onDrop: draggable ? handleDrop : void 0,
+      onDragOver: dropEnabled ? handleDragOver : void 0,
+      onDragLeave: dropEnabled ? handleDragLeave : void 0,
+      onDrop: dropEnabled ? handleDrop : void 0,
       children: [
         isDropTarget && dropPosition === "before" && /* @__PURE__ */ jsx(
           "div",
@@ -12702,6 +12726,8 @@ function TreeNavRoot({
   onNodeContextMenu,
   draggable = false,
   onNodeMove,
+  acceptExternalDrops = false,
+  onExternalDrop,
   expandedIds: controlledExpanded,
   defaultExpandedIds,
   onExpandedChange,
@@ -12755,6 +12781,8 @@ function TreeNavRoot({
       dragState,
       setDragState,
       onNodeMove,
+      acceptExternalDrops,
+      onExternalDrop,
       nodes,
       expandNode
     }),
@@ -12769,16 +12797,19 @@ function TreeNavRoot({
       draggable,
       dragState,
       onNodeMove,
+      acceptExternalDrops,
+      onExternalDrop,
       nodes,
       expandNode
     ]
   );
+  const dropEnabled = draggable || acceptExternalDrops;
   return /* @__PURE__ */ jsx(TreeNavContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(
     "nav",
     {
       "data-react-fancy-tree-nav": "",
       className: cn("flex flex-col gap-0.5 py-1 text-sm", className),
-      onDragEnd: draggable ? handleDragEnd : void 0,
+      onDragEnd: dropEnabled ? handleDragEnd : void 0,
       children: nodes.map((node) => /* @__PURE__ */ jsx(TreeNode, { node, depth: 0 }, node.id))
     }
   ) });