File Manager

When to use

FileManager is the Mac-Finder content pane: a grid / list view of the current folder with multi-select, cut / copy / paste, drag-and-drop, sort, and view-mode switching. Pair it with file-tree in the sidebar slot for the dual-pane Finder layout. Standalone use is also supported.

Data shape

Same FsNode shape as file-tree — id / name / type / parentId / children / ext / size / modifiedAt / icon / meta. Consumer owns nodes and currentFolderId; manager fires object-shape callbacks on every operation.

Shared clipboard

Wrap one or more <FileManager> instances in <FileClipboardProvider> to sync cut / copy / paste across instances. Without a provider, each manager keeps its own internal clipboard. Controlled mode: pass clipboard + onClipboardChange.

import { FileManager, FileClipboardProvider } from "@/components/file-manager"

<FileClipboardProvider>
  <FileManager nodes={nodes} sidebar={<FileTree nodes={nodes} />} />
</FileClipboardProvider>

Lazy loading

import { mergeLoadedChildren } from "@/components/file-manager"

<FileManager
  nodes={nodes}
  currentFolderId={current}
  onCurrentFolderChange={({ folderId }) => setCurrent(folderId)}
  onLoadChildren={async ({ nodeId }) => {
    const kids = await fs.list(nodeId);
    setNodes((prev) => mergeLoadedChildren(prev, nodeId, kids));
    return kids;
  }}
/>

Keyboard map

• Arrow keys move focus (2-D nav in grid mode, up/down only in list mode).
• Enter opens a file (onOpen) or navigates into a folder.
• Backspace deletes selected items (with confirm), or navigates up to parent if no selection.
• F2 renames; Delete deletes; Esc clears selection or cancels rename.
• Cmd/Ctrl+X / C / V cut / copy / paste; Cmd/Ctrl+A select all visible.
• Cmd/Ctrl+[ back; Cmd/Ctrl+] forward.
• Type-ahead: typing letters jumps focus to the first matching item name (resets after 800ms).

Drag-and-drop

• Within the manager: drag selected items onto a folder. Cycle / self-drop refused; drops on files are rejected (only folders are valid targets).
• From the desktop: drop OS files onto the manager to fire onExternalDrop. targetFolderId is the folder the user dropped on, or the current folder otherwise.
• Marquee selection: drag a rectangle on empty space to select multiple items. Shift+drag adds to existing selection.

Custom chrome

Replace the toolbar via renderToolbar (typed context), or compose the standalone parts: FileManagerToolbar,FileManagerPathBar, FileManagerViewToggle,FileManagerIconSizeControl, FileManagerSortMenu, FileManagerSearchInput, FileManagerStatusBar. They read from useFileManager().

Gotchas

• Drops on files are rejected; only folders accept drops. Drops on empty whitespace are no-ops for internal drag, upload-to-current for external drag.
• Selection clears on navigate by default. Set preserveSelectionOnNavigate={true} to keep it.
• Cut / copy / paste require onPaste wired. Without a paste handler, the manager fires onClipboardChange but paste does nothing.
• Dragging files OUT to the desktop is not supported in v0.1.0. Add a Download button via renderContextMenu or the toolbar overflow.
• List-view virtualizes at virtualizeThreshold items (default 200). Grid view does NOT virtualize at v0.1.0.