@djangocfg/ui-tools 2.1.415 → 2.1.416

package/src/tools/data/Tree/TreeDndProvider.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+  type DragMoveEvent,
+  type DragStartEvent,
+} from '@dnd-kit/core';
+import { useCallback, useRef } from 'react';
+
+import { useTreeContext } from './context/TreeContext';
+import { resolveDropZone, TREE_ROOT_DROP_ID } from './data/dnd';
+import type { TreeItemId } from './types';
+
+interface TreeDndProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Wrap Tree's body in a `<DndContext>` when DnD is enabled.
+ *
+ * One central drag handler decides the drop zone (`before` / `inside` /
+ * `after`) from the cursor position vs. the hovered row's bounding box.
+ * Rows themselves only register `useDraggable` + `useDroppable` — no
+ * per-row `onPointerMove`, so dragging across 1000 rows stays cheap.
+ *
+ * Sensors: pointer (with a small activation distance so a plain click
+ * doesn't initiate a drag) + keyboard (drag with Space/Enter, arrows,
+ * Space drops — built-in accessibility).
+ */
+export function TreeDndProvider({ children }: TreeDndProviderProps) {
+  const ctx = useTreeContext();
+  const { dnd } = ctx;
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(KeyboardSensor),
+  );
+
+  // Latest cursor position — @dnd-kit gives us the active rectangle but
+  // not the raw pointer Y. We grab it from pointermove ourselves and
+  // use it inside `onDragMove` to compute the drop zone.
+  const cursorYRef = useRef(0);
+
+  const handleDragStart = useCallback(
+    (e: DragStartEvent) => {
+      dnd.beginDrag(e.active.id as TreeItemId);
+    },
+    [dnd],
+  );
+
+  const handleDragMove = useCallback(
+    (e: DragMoveEvent) => {
+      const overId = e.over?.id;
+      // Root drop target — TreeEmptyArea registers under this id.
+      if (overId === TREE_ROOT_DROP_ID) {
+        const current = dnd.dropTarget;
+        if (current?.id !== null || current?.position !== 'inside') {
+          dnd.setDropTarget({ id: null, position: 'inside' });
+        }
+        return;
+      }
+      if (typeof overId !== 'string') {
+        if (dnd.dropTarget !== null) dnd.setDropTarget(null);
+        return;
+      }
+
+      // The dnd-kit `over.rect` is the droppable's bounding box. Combined
+      // with the latest cursor Y we recover the same before/inside/after
+      // split Finder uses.
+      const rect = e.over?.rect;
+      if (!rect) return;
+
+      // `data-folder` on the dom row tells us if `inside` is allowed.
+      const el = document.querySelector<HTMLElement>(
+        `[data-tree-row][data-id="${CSS.escape(overId)}"]`,
+      );
+      const isFolder = el?.dataset.folder === 'true';
+
+      const position = resolveDropZone({
+        pointerY: cursorYRef.current,
+        rowRect: { top: rect.top, bottom: rect.top + rect.height, height: rect.height },
+        isFolder,
+      });
+
+      const current = dnd.dropTarget;
+      if (current?.id !== overId || current.position !== position) {
+        dnd.setDropTarget({ id: overId, position });
+      }
+    },
+    [dnd],
+  );
+
+  const handleDragEnd = useCallback(
+    async (_e: DragEndEvent) => {
+      await dnd.commitDrop();
+    },
+    [dnd],
+  );
+
+  const handleDragCancel = useCallback(() => {
+    dnd.cancelDrag();
+  }, [dnd]);
+
+  // Track the latest cursor Y position globally while a drag is in flight.
+  // Used by `handleDragMove` to figure out which third of the row we're
+  // over. Cheap — one passive listener, no re-renders.
+  const handlePointerMove = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    cursorYRef.current = e.clientY;
+  }, []);
+
+  if (!dnd.active) {
+    return <>{children}</>;
+  }
+
+  return (
+    <DndContext
+      sensors={sensors}
+      onDragStart={handleDragStart}
+      onDragMove={handleDragMove}
+      onDragEnd={handleDragEnd}
+      onDragCancel={handleDragCancel}
+    >
+      <div
+        onPointerMove={handlePointerMove}
+        className="contents"
+        data-tree-dnd-surface=""
+      >
+        {children}
+      </div>
+    </DndContext>
+  );
+}

package/src/tools/data/Tree/TreeRoot.tsx

@@ -11,58 +11,80 @@ import {
   ContextMenuTrigger,
 } from '@djangocfg/ui-core/components';
 
-import { TreeProvider, useTreeContext } from './context/TreeContext';
+import { TreeContext, TreeProvider, useTreeContext } from './context/TreeContext';
+import { TreeDndProvider } from './TreeDndProvider';
 import { TreeContent, treeRowDomId } from './components/TreeContent';
+import { TreeEmptyArea } from './components/TreeEmptyArea';
 import { TreeSearchInput } from './components/TreeSearchInput';
 import { appearanceToStyle } from './data/appearance';
-import { useTreeKeyboard } from './hooks/useTreeKeyboard';
-import { useTreeTypeAhead } from './hooks/useTreeTypeAhead';
+import {
+  useTreeKeyboard,
+  useTreeTypeAhead,
+  useTreeFinderHotkeys,
+} from './hooks';
 import type {
-  TreeContextMenuActionsResolver,
+  TreeContextMenuItem,
   TreeContextMenuSlot,
   TreeRootProps,
   TreeRowRenderProps,
 } from './types';
 
 /**
- * Build a `renderContextMenu` slot from a declarative `actions` resolver.
- * Used internally by `TreeRoot` when consumers pass `contextMenuActions`
- * instead of the lower-level `renderContextMenu`.
+ * Render an array of declarative menu items as a themed `<ContextMenu>`
+ * wrapped around the supplied trigger element. Pure presentational layer
+ * — the caller resolves and merges items.
  */
-function actionsToRenderContextMenu<T>(
-  resolve: TreeContextMenuActionsResolver<T>,
-): TreeContextMenuSlot<T> {
-  return (rowProps: TreeRowRenderProps<T>, trigger) => {
-    const items = resolve(rowProps);
-    if (!items || items.length === 0) return trigger;
-    return (
-      <ContextMenu>
-        <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
-        <ContextMenuContent>
-          {items.map((item, idx) => {
-            if (item === 'separator') {
-              return <ContextMenuSeparator key={`sep-${idx}`} />;
-            }
-            const Icon = item.icon;
-            return (
-              <ContextMenuItem
-                key={item.id}
-                disabled={item.disabled}
-                variant={item.destructive ? 'destructive' : undefined}
-                onSelect={() => item.onSelect(rowProps)}
-              >
-                {Icon ? <Icon /> : null}
-                {item.label}
-                {item.shortcut ? (
-                  <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
-                ) : null}
-              </ContextMenuItem>
-            );
-          })}
-        </ContextMenuContent>
-      </ContextMenu>
-    );
-  };
+function renderItemsAsContextMenu<T>(
+  rowProps: TreeRowRenderProps<T>,
+  items: TreeContextMenuItem<T>[],
+  trigger: React.ReactNode,
+): React.ReactNode {
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
+      <ContextMenuContent>
+        {items.map((item, idx) => {
+          if (item === 'separator') {
+            return <ContextMenuSeparator key={`sep-${idx}`} />;
+          }
+          const Icon = item.icon;
+          return (
+            <ContextMenuItem
+              key={item.id}
+              disabled={item.disabled}
+              variant={item.destructive ? 'destructive' : undefined}
+              onSelect={() => item.onSelect(rowProps)}
+            >
+              {Icon ? <Icon /> : null}
+              {item.label}
+              {item.shortcut ? (
+                <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+              ) : null}
+            </ContextMenuItem>
+          );
+        })}
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}
+
+/**
+ * Drop trailing / leading / duplicate separators so a merged menu never
+ * shows a separator next to a section header or another separator.
+ */
+function tidyMenuItems<T>(items: TreeContextMenuItem<T>[]): TreeContextMenuItem<T>[] {
+  const out: TreeContextMenuItem<T>[] = [];
+  for (const it of items) {
+    if (it === 'separator') {
+      if (out.length === 0) continue;
+      if (out[out.length - 1] === 'separator') continue;
+      out.push(it);
+    } else {
+      out.push(it);
+    }
+  }
+  while (out.length > 0 && out[out.length - 1] === 'separator') out.pop();
+  return out;
 }
 
 /**
@@ -89,6 +111,10 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     enableSearch = false,
     enableTypeAhead = true,
     showIndentGuides = false,
+    enableInlineRename = false,
+    enableFinderHotkeys = false,
+    enableDnD = false,
+    canDrop,
     renderRow,
     renderIcon,
     renderLabel,
@@ -98,18 +124,12 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     labels,
     persistKey,
     persistSelection = false,
+    adapter,
+    defaultMenuItems,
     className,
     style,
   } = props;
 
-  // Short-form actions resolver is auto-converted into a renderContextMenu
-  // slot. The lower-level slot wins if both are provided.
-  const resolvedRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(() => {
-    if (renderContextMenu) return renderContextMenu;
-    if (contextMenuActions) return actionsToRenderContextMenu(contextMenuActions);
-    return undefined;
-  }, [renderContextMenu, contextMenuActions]);
-
   return (
     <TreeProvider<T>
       data={data}
@@ -130,7 +150,16 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
       renderIcon={renderIcon}
       renderLabel={renderLabel}
       renderActions={renderActions}
-      renderContextMenu={resolvedRenderContextMenu}
+      // The provider builds the *declarative* merged resolver. Slot
+      // conversion happens inside <TreeRootShell /> via the inner ctx,
+      // so built-in actions can read live selection state.
+      renderContextMenu={renderContextMenu}
+      contextMenuActions={contextMenuActions}
+      adapter={adapter}
+      defaultMenuItems={defaultMenuItems}
+      enableInlineRename={enableInlineRename}
+      enableDnD={enableDnD}
+      canDrop={canDrop}
       labels={labels}
       persistKey={persistKey}
       persistSelection={persistSelection}
@@ -140,6 +169,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
         style={style}
         enableSearch={enableSearch}
         enableTypeAhead={enableTypeAhead}
+        enableFinderHotkeys={enableFinderHotkeys}
         renderRow={renderRow}
       />
     </TreeProvider>
@@ -151,6 +181,7 @@ interface TreeRootShellProps<T> {
   style?: React.CSSProperties;
   enableSearch: boolean;
   enableTypeAhead: boolean;
+  enableFinderHotkeys: boolean;
   renderRow?: TreeRootProps<T>['renderRow'];
 }
 
@@ -159,16 +190,30 @@ function TreeRootShell<T>({
   style,
   enableSearch,
   enableTypeAhead,
+  enableFinderHotkeys,
   renderRow,
 }: TreeRootShellProps<T>) {
   const containerRef = useRef<HTMLDivElement>(null);
   const ctx = useTreeContext<T>();
 
-  // Keyboard navigation (↑↓ ←→ Home/End Enter Esc) — scoped via callback ref.
+  // Keyboard navigation (↑↓ ←→ Home/End Enter Esc Cmd+A, Shift-extend) —
+  // scoped via callback ref.
+  const isMulti = ctx.selectionMode === 'multiple';
   const { ref: keyboardRef } = useTreeKeyboard<T>({
     rows: ctx.flatRows,
     focusedId: ctx.focused,
-    onFocus: ctx.setFocus,
+    multiSelect: isMulti,
+    // Pause container hotkeys while inline rename is active so the
+    // user can type freely (TreeRenameInput stops bubbling already, but
+    // gating here is the cleaner second line of defence).
+    enabled: ctx.renamingId === null,
+    onFocus: (id, { extend }) => {
+      if (extend && isMulti) {
+        ctx.moveSelect(id, { extend: true });
+      } else {
+        ctx.setFocus(id);
+      }
+    },
     onSelect: ctx.select,
     onActivate: (id) => {
       // Keyboard Enter / Space is always an explicit action — pin (no preview).
@@ -178,14 +223,41 @@ function TreeRootShell<T>({
     onExpand: ctx.expand,
     onCollapse: ctx.collapse,
     onClearSelection: ctx.clearSelection,
+    onSelectAll: ctx.selectAll,
+  });
+
+  // Finder hotkeys (P4) — ⌘⌫, F2, ⌘D, ⌘N, ⌘⇧N, ⌘C/X/V. Bound only when
+  // `enableFinderHotkeys` is true; individual shortcuts further gated
+  // by adapter method availability inside the hook.
+  const { ref: finderHotkeysRef } = useTreeFinderHotkeys<T>({
+    enabled: enableFinderHotkeys,
+    paused: ctx.renamingId !== null,
+    adapter: ctx.adapter,
+    labels: ctx.labels,
+    selected: ctx.selected,
+    focused: ctx.focused,
+    getNodeById: ctx.getNodeById,
+    getItemName: ctx.getItemName,
+    startInlineRename: ctx.inlineRenameEnabled ? ctx.startRename : undefined,
+    clipboard: {
+      hasItems: !!ctx.clipboard && ctx.clipboard.ids.length > 0,
+      cut: ctx.cutToClipboard,
+      copy: ctx.copyToClipboard,
+      // Hotkey paste targets the currently focused row (or null = root).
+      paste: () => {
+        const target = ctx.focused ? ctx.getNodeById(ctx.focused) ?? null : null;
+        return ctx.pasteFromClipboard(target, 'inside');
+      },
+    },
   });
 
   const setContainerRef = useCallback(
     (instance: HTMLDivElement | null) => {
       containerRef.current = instance;
       keyboardRef(instance);
+      finderHotkeysRef(instance);
     },
-    [keyboardRef],
+    [keyboardRef, finderHotkeysRef],
   );
 
   // Keep the focused row scrolled into view whenever focus moves (keyboard
@@ -216,7 +288,28 @@ function TreeRootShell<T>({
     enabled: enableTypeAhead,
   });
 
-  return (
+  // Build the final renderContextMenu slot from the merged declarative
+  // resolver. `renderContextMenu` (escape-hatch slot) wins if both are
+  // provided. We replace `ctx.renderContextMenu` on the child context
+  // here so TreeRow keeps reading a single source of truth.
+  const finalRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(() => {
+    if (ctx.renderContextMenu) return ctx.renderContextMenu;
+    const resolve = ctx.resolvedContextMenuActions;
+    if (!resolve) return undefined;
+    return (rowProps, trigger) => {
+      const items = resolve(rowProps);
+      const cleaned = items ? tidyMenuItems(items) : null;
+      if (!cleaned || cleaned.length === 0) return trigger;
+      return renderItemsAsContextMenu(rowProps, cleaned, trigger);
+    };
+  }, [ctx.renderContextMenu, ctx.resolvedContextMenuActions]);
+
+  const childCtx = useMemo(
+    () => ({ ...ctx, renderContextMenu: finalRenderContextMenu }),
+    [ctx, finalRenderContextMenu],
+  );
+
+  const treeBody = (
     <div
       ref={setContainerRef}
       tabIndex={0}
@@ -233,11 +326,33 @@ function TreeRootShell<T>({
       data-tree-root=""
     >
       {enableSearch ? <TreeSearchInput className="mx-2 mt-2" /> : null}
-      <div className="min-h-0 flex-1 overflow-auto px-1">
+      <div className="flex min-h-0 flex-1 flex-col overflow-auto px-1">
         <TreeContent<T> role="group">{renderRow}</TreeContent>
+        {/* Empty-area: catches right-clicks on whitespace below the
+            last row + acts as the root drop target for DnD. Always
+            rendered — it self-disables when there's nothing to do. */}
+        <TreeEmptyArea />
       </div>
     </div>
   );
+
+  // If we computed a different renderContextMenu slot than the one in
+  // the parent provider, override it via a thin nested provider so
+  // <TreeRow> reads the merged slot. Otherwise skip the wrapper to keep
+  // the render cheap.
+  const body =
+    finalRenderContextMenu === ctx.renderContextMenu ? (
+      treeBody
+    ) : (
+      <TreeContext.Provider value={childCtx as never}>
+        {treeBody}
+      </TreeContext.Provider>
+    );
+
+  // Wrap in @dnd-kit context only when DnD is active — `TreeDndProvider`
+  // short-circuits to a fragment otherwise, so we don't pay the
+  // sensor-registration cost.
+  return <TreeDndProvider>{body}</TreeDndProvider>;
 }
 
 export default TreeRoot;

package/src/tools/data/Tree/__tests__/dnd.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultCanDrop, resolveDropZone } from '../data/dnd';
+import type { TreeNode } from '../types';
+
+const rowRect = { top: 0, bottom: 30, height: 30 };
+
+describe('resolveDropZone (folder targets)', () => {
+  it('returns `before` in the top third', () => {
+    expect(
+      resolveDropZone({ pointerY: 5, rowRect, isFolder: true }),
+    ).toBe('before');
+  });
+
+  it('returns `inside` in the middle third', () => {
+    expect(
+      resolveDropZone({ pointerY: 15, rowRect, isFolder: true }),
+    ).toBe('inside');
+  });
+
+  it('returns `after` in the bottom third', () => {
+    expect(
+      resolveDropZone({ pointerY: 25, rowRect, isFolder: true }),
+    ).toBe('after');
+  });
+});
+
+describe('resolveDropZone (leaf targets)', () => {
+  it('splits leaves in half: before / after', () => {
+    expect(
+      resolveDropZone({ pointerY: 10, rowRect, isFolder: false }),
+    ).toBe('before');
+    expect(
+      resolveDropZone({ pointerY: 20, rowRect, isFolder: false }),
+    ).toBe('after');
+  });
+
+  it('never returns `inside` for a leaf', () => {
+    // Sweep the row — none of these should report `inside`.
+    for (let y = 0; y <= 30; y++) {
+      expect(
+        resolveDropZone({ pointerY: y, rowRect, isFolder: false }),
+      ).not.toBe('inside');
+    }
+  });
+});
+
+describe('resolveDropZone (degenerate row)', () => {
+  it('falls back to a sensible default when height is zero', () => {
+    expect(
+      resolveDropZone({
+        pointerY: 5,
+        rowRect: { top: 0, bottom: 0, height: 0 },
+        isFolder: false,
+      }),
+    ).toBe('after');
+  });
+});
+
+// ----------------------------------------------------------------------
+// defaultCanDrop
+// ----------------------------------------------------------------------
+
+interface FsItem {
+  name: string;
+}
+
+const folder: TreeNode<FsItem> = {
+  id: 'folder',
+  data: { name: 'folder' },
+  isFolder: true,
+  children: [
+    { id: 'child', data: { name: 'child' } },
+    {
+      id: 'nested-folder',
+      data: { name: 'nested' },
+      isFolder: true,
+      children: [{ id: 'grandchild', data: { name: 'gc' } }],
+    },
+  ],
+};
+
+const leaf: TreeNode<FsItem> = { id: 'leaf', data: { name: 'leaf' } };
+
+const lookup = new Map<string, TreeNode<FsItem>>();
+function indexNodes(node: TreeNode<FsItem>) {
+  lookup.set(node.id, node);
+  if (Array.isArray(node.children)) node.children.forEach(indexNodes);
+}
+indexNodes(folder);
+indexNodes(leaf);
+
+describe('defaultCanDrop', () => {
+  it('allows a drop on the root (null target)', () => {
+    expect(
+      defaultCanDrop({
+        source: [leaf],
+        target: null,
+        position: 'inside',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(true);
+  });
+
+  it('rejects dropping a node onto itself', () => {
+    expect(
+      defaultCanDrop({
+        source: [folder],
+        target: folder,
+        position: 'inside',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(false);
+  });
+
+  it('rejects `inside` drop on a leaf', () => {
+    expect(
+      defaultCanDrop({
+        source: [folder],
+        target: leaf,
+        position: 'inside',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(false);
+  });
+
+  it('allows `before`/`after` drop on a leaf', () => {
+    expect(
+      defaultCanDrop({
+        source: [folder],
+        target: leaf,
+        position: 'before',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(true);
+  });
+
+  it('rejects dropping a folder into its own descendant', () => {
+    const nested = lookup.get('nested-folder')!;
+    expect(
+      defaultCanDrop({
+        source: [folder],
+        target: nested,
+        position: 'inside',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(false);
+  });
+
+  it('rejects an empty source list', () => {
+    expect(
+      defaultCanDrop({
+        source: [],
+        target: null,
+        position: 'inside',
+        getNodeById: (id) => lookup.get(id),
+      }),
+    ).toBe(false);
+  });
+});