@alwith/module-file-tree

A standalone file tree. It depends on @alwith/module-fs and does not import the editor package.

import { createFileTreeController, FileTree } from "@alwith/module-file-tree"
import "@alwith/module-file-tree/styles.css"
const tree = createFileTreeController({ fs, root: "/project", reportError })
await tree.refresh()
<FileTree controller={tree} onOpenFile={openFile} requestName={requestName}
  confirmDelete={confirmDelete} onError={reportError} />
// On workspace disposal:
tree.dispose()

/core exports the React-free controller, snapshots, rows and PartialOperationError. The root entry exports React UI and all core types. Import CSS once in the host.

Included behavior

Directory-first sorting, lazy expansion, virtual rows, filtering loaded entries (including collapsed descendants), hidden-file toggle, multi/range selection, keyboard navigation, create/rename/delete, copy/cut/paste and internal drag-to-directory. The native adapter applies gitignore filtering. Filter is explicitly limited to loaded entries; it is not a recursive search index.

requestName and confirmDelete are asynchronous host dialogs. Return null/false to cancel. onOpenFile can open a preview, editor, external application or any host action. renderDecoration adds per-row metadata. All strings are replaceable using FileTreeLabels; CSS consumes semantic host theme tokens.

expanded and onExpandedChange let a host persist view state. The host owns workspace/session selection. The controller never loads global settings or subscribes to a global app store.

Mutations use the shared FS instance and therefore its guards. Passing one FS instance to tree and editor is the standard composition; the tree remains unaware of editor internals. A batch stops on the first failure and reports completed paths plus the failed path. Copying uses Desktop-style incremented copy names. Moving preflights all destination conflicts before touching sources. Cut-paste replacement requires the host confirmReplace callback and rechecks target versions after confirmation; removing the target uses FS mutation guards. A batch is not an OS transaction: later I/O failures report completed items; replacements remove an approved target before moving its source. Filesystem notifications are coalesced before refreshing the loaded tree.

See examples/files/tree-only.tsx for a consumer that imports no editor package.

Explorer UI and host adapters

The toolbar exposes search, creation, refresh, collapse and view preferences. Rows use 22px height, file-type icons, inline rename, range selection, keyboard navigation and context menus. Cmd/Ctrl+F filters names and relative path fragments; Enter/Shift+Enter moves between matches and Escape closes search. Cmd/Ctrl+A, C/X/V operate on the focused tree. Rename and delete use the row context menu, as in Desktop.

activePath reveals an editor selection through lazy ancestor expansion. onReveal, onCopyPath, onImport, and requestMoveDestination are host capabilities. onPinFile, renderIcon, renderDecoration, and renderActions integrate richer editor, icon, Git and application behavior without importing the host. explorerLabels supplements the original labels without breaking existing consumers. OS drag-drop registration, native consent, file pickers and persistence stay in the host. Cloud authorization, synchronization, sharing and sidebar pinning are application features and are not bundled into the local file tree.

Desktop implementation provenance

The visual resolver, icon associations, pointer-drag hook and floating drag preview are extracted from Desktop's file-visual.ts, use-tree-drag.ts and drag-preview.tsx. Icons are bundled locally; the default vscode-icons collection is pinned to Desktop's 1.2.86 version. isDark selects light/dark mappings and iconTheme selects vscode-icons, catppuccin-latte, catppuccin-mocha or material-icon-theme. The host supplies its theme setting; no global settings store is imported. Codicons provide the toolbar and expand/collapse symbols.

TanStack Virtual renders 22px rows with Desktop's 8px nesting increment. The project root is an expandable row. Collapse All keeps the project root expanded. Pointer drag uses Desktop's 5px threshold and floating preview, avoiding HTML5 drag events that are unreliable in WKWebView. Drops are limited to the tree's viewport and reject moves into the source or its descendants.

The build validates emitted icon mappings to detect accidental rewriting of ordinary strings by the ESM module-path transformer.

explorerControl replaces the toolbar title with host content. collapsed keeps that control visible while hiding the tree and its remaining toolbar actions. The host controls the collapsed container width and the toggle state.

Source alignment

desktop-provenance.json records the Desktop source hashes at extraction. filter-tree.ts, copy-name.ts and move-plan.ts preserve their original algorithms; their Desktop test suites are copied with only runner/import changes. use-tree-keyboard.ts preserves Desktop navigation and injects store access. The UI click handler follows Explorer.handleItemClick; the local context menu follows TreeItem root exclusions, single-row deletion and multi-row copying.

Host adapters replace global stores, native calls and notifications. The keyboard hook additionally handles an empty list without indexing a missing node. Existing FS guards still protect dirty documents and workspace boundaries. The requested right-side layout, Explorer icon toggle and subtle scrollbars are intentional UI differences. Cloud actions require the cloud host; they are not simulated locally.