xtralab 0.14.1 → 0.15.1

package/lib/fileBrowser/fileBrowser.js

@@ -1,75 +1,37 @@
 import * as React from 'react';
-import { fileIcon } from '@jupyterlab/ui-components';
-import { MimeData, PromiseDelegate } from '@lumino/coreutils';
-import { Drag } from '@lumino/dragdrop';
+import { showErrorMessage } from '@jupyterlab/apputils';
+import { renameFile } from '@jupyterlab/docmanager';
+import { nullTranslator } from '@jupyterlab/translation';
 import { Poll } from '@lumino/polling';
 import { FileTree, useFileTree } from '@pierre/trees/react';
-import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
+import { ROOT_LOAD_KEY, listDirectory, parentOf, toServerPath } from './contents';
+import { computeDropMoves, computeRootDropMoves, createTreeDragAndDropConfig, useRootDropZone } from './dragAndDrop';
 import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
 import { loadGitStatusEntries } from './gitStatus';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
- * MIME types used by the dock panel and other JupyterLab drop targets.
- * `FACTORY_MIME` is the lumino dock-panel contract: the value must be a
- * synchronous function that returns a Widget. The contents MIME types
- * mirror what the default file browser sends so other drop targets that
- * understand them (the file browser itself, custom drop zones) keep
- * working when the user drags out of xtralab.
- */
-const FACTORY_MIME = 'application/vnd.lumino.widget-factory';
-const CONTENTS_MIME = 'application/x-jupyter-icontents';
-/**
- * Threshold in pixels before a press-and-drag is treated as a drag rather
- * than a click. Matches the value used by the default JupyterLab listing.
- */
-const DRAG_THRESHOLD = 5;
-/**
- * Polling cadence for the git status decoration. Out-of-band changes (a
- * terminal `git add`, a `git pull`, a file edited outside the JupyterLab
- * editor) become visible within this interval without a manual refresh.
- * Aligned with the git panel's own polling so both views update on the
- * same rhythm.
+ * Git status poll cadence, aligned with the git panel's polling so both
+ * views update on the same rhythm.
  */
 const GIT_STATUS_POLL_INTERVAL_MS = 5000;
-/**
- * Upper bound on the git status poll's exponential backoff. Matches the
- * other polls in the plugin so behavior is consistent across views.
- */
 const GIT_STATUS_POLL_MAX_MS = 300000;
 /**
- * Auto-refresh cadence for the file listing itself. Matches the default
- * JupyterLab file browser (`DEFAULT_REFRESH_INTERVAL` in
- * `@jupyterlab/filebrowser`) so the tree picks up files created outside
- * JupyterLab (terminal commands, external editors, `git pull`, …) within
- * the same window as the stock browser.
+ * Listing auto-refresh cadence; matches the default file browser's
+ * `DEFAULT_REFRESH_INTERVAL` for picking up out-of-band file changes.
  */
 const FILE_LISTING_REFRESH_INTERVAL_MS = 10000;
-/**
- * Upper bound on the auto-refresh backoff when polls fail repeatedly.
- * Matches the default file browser's `max: 300 * 1000` — five minutes is
- * long enough that a server-side outage stops hammering the API, but
- * short enough that a transient failure heals on its own.
- */
 const FILE_LISTING_REFRESH_MAX_MS = 300000;
 /**
- * Server-relative repository path used for `/git/*` calls. Empty string
- * means "use the JupyterLab server's root and let git resolve the
- * enclosing repo" — same convention as the git panel and the launcher
- * dashboard.
+ * Repo path for `/git/*` calls; empty means the server root, letting git
+ * resolve the enclosing repo (same convention as the git panel).
  */
 const GIT_REPO_PATH = '';
-/**
- * The custom-element tag used by `@pierre/trees` for its shadow host. Kept
- * as a constant rather than imported so we don't pay the `@pierre/trees`
- * resolution cost just for one string.
- */
 const FILE_TREE_TAG = 'file-tree-container';
 /**
- * Injected into the tree's shadow root. The second rule hides the search
- * box unless the host carries the visibility marker set by the filter
- * bridge effect below — `@pierre/trees` always renders the box when
- * `search` is enabled, and its stylesheet lives in the shadow root where
- * outside CSS cannot reach.
+ * Injected into the tree's shadow root, where outside CSS cannot reach.
+ * The search box is hidden unless the host carries the filter-bridge marker
+ * (the library always renders it), and the drag-hover row gets a quiet ring
+ * — the library's selection background is illegible with xtralab's colors.
  */
 const FILE_TREE_UNSAFE_CSS = '[data-type="item"][data-item-selected="true"] ' +
     '[data-item-section="spacing-item"] {' +
@@ -78,47 +40,41 @@ const FILE_TREE_UNSAFE_CSS = '[data-type="item"][data-item-selected="true"] ' +
     ':host(:not([data-xtralab-filter-visible])) ' +
     '[data-file-tree-search-container] {' +
     'display: none;' +
+    '}' +
+    '[data-type="item"][data-item-drag-target="true"] {' +
+    'background-color: var(--trees-bg-muted);' +
+    'box-shadow: inset 0 0 0 2px var(--trees-accent);' +
     '}';
 /**
- * Renders a `@pierre/trees` file tree backed by the Jupyter contents API.
- *
- * The Jupyter contents API only returns one directory level per request, so
- * the tree is populated lazily: the root is fetched on mount, and each
- * directory is fetched the first time the user expands it. Expansion is
- * detected by subscribing to the model and diffing against an in-memory load
- * state map.
+ * A `@pierre/trees` file tree backed by the Jupyter contents API. The API
+ * returns one directory level per request, so directories load lazily on
+ * first expand, detected by diffing the model against a load-state map.
  */
 export function FileBrowserComponent(props) {
-    const { contentsManager, docManager, onOpenFile, widget } = props;
+    const { contentsManager, docManager, onOpenFile, translator, widget } = props;
+    const trans = React.useMemo(() => (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab'), [translator]);
+    const dropHandlerRef = React.useRef(null);
     const { model } = useFileTree({
         paths: [],
         initialExpansion: 'closed',
         search: true,
         icons: FILE_BROWSER_ICONS,
         itemHeight: 24,
-        unsafeCSS: FILE_TREE_UNSAFE_CSS
+        unsafeCSS: FILE_TREE_UNSAFE_CSS,
+        dragAndDrop: createTreeDragAndDropConfig(dropHandlerRef)
     });
     React.useEffect(() => {
         const knownDirs = new Map();
-        // Mirror of the canonical paths currently loaded into the tree. Kept in
-        // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
-        // re-test every loaded path against the gitignore matcher whenever
-        // either side changes — the model itself does not expose a
-        // path-iteration API.
+        // Mirror of the loaded canonical paths — the model has no path-iteration
+        // API, and the gitignore matcher must re-test every loaded path.
         const loadedPaths = new Set();
         let gitignoreMatcher = null;
         let gitStatusEntries = [];
         let cancelled = false;
         /**
-         * Recompute the combined `GitStatusEntry` list from the current
-         * gitignore matcher and the latest porcelain status, then push it into
-         * the tree. Safe to call at any time: empty inputs result in an empty
-         * payload, which clears any statuses applied previously.
-         *
-         * Ignored entries go first so the porcelain entries win in the
-         * unlikely event of overlap (a tracked path that also matches a
-         * `.gitignore` rule). `@pierre/trees` lets later entries overwrite
-         * earlier ones in its internal `statusByPath` map.
+         * Push the combined gitignore + porcelain entries into the tree.
+         * Ignored entries go first so porcelain entries win on overlap —
+         * `@pierre/trees` lets later entries overwrite earlier ones.
          */
         const syncGitStatus = () => {
             const entries = [];
@@ -132,12 +88,6 @@ export function FileBrowserComponent(props) {
             }
             model.setGitStatus(entries);
         };
-        /**
-         * Reload the workspace `.gitignore`, then re-apply the resulting
-         * ignored statuses. Called on initial mount and whenever the user
-         * triggers a refresh — the file may have been edited or created in
-         * between.
-         */
         const refreshGitignoreMatcher = async () => {
             let next = null;
             try {
@@ -152,12 +102,6 @@ export function FileBrowserComponent(props) {
             gitignoreMatcher = next;
             syncGitStatus();
         };
-        /**
-         * Refresh the porcelain-derived git status entries and re-apply them
-         * to the tree. Runs on mount, on every refresh, and on a periodic
-         * poll so out-of-band changes (terminal `git add`, file edits saved
-         * outside the editor, …) become visible without explicit user action.
-         */
         const refreshGitStatus = async () => {
             const next = await loadGitStatusEntries(GIT_REPO_PATH);
             if (cancelled) {
@@ -186,21 +130,16 @@ export function FileBrowserComponent(props) {
                     }
                 }
                 else {
-                    // Filter out paths already in the model. The path-store throws
-                    // when an explicit directory is added a second time, so any
-                    // entry created out-of-band (e.g. by the "new folder" command's
-                    // `notifyPathAdded` callback) must be skipped here.
+                    // The path-store throws when a path is added twice, and entries
+                    // can arrive out-of-band (e.g. `notifyPathAdded`), so skip those.
                     const operations = paths
                         .filter(path => model.getItem(path) === null)
                         .map(path => ({ type: 'add', path }));
                     if (operations.length > 0) {
                         model.batch(operations);
                     }
-                    // Mirror every directory child into `loadedPaths` regardless of
-                    // whether it was just added or skipped above — paths skipped by
-                    // the filter are already in the model from a prior add and so
-                    // belong in the mirror too. `Set.add` is idempotent, so the
-                    // duplicate adds are a no-op.
+                    // Paths skipped above are already in the model from a prior add,
+                    // so they belong in the mirror too.
                     for (const path of paths) {
                         loadedPaths.add(path);
                     }
@@ -219,24 +158,8 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Compute the canonical parent path for a given canonical path.
-         * Returns {@link ROOT_LOAD_KEY} for top-level entries.
-         */
-        const parentOf = (canonicalPath) => {
-            const trimmed = canonicalPath.endsWith('/')
-                ? canonicalPath.slice(0, -1)
-                : canonicalPath;
-            const idx = trimmed.lastIndexOf('/');
-            if (idx < 0) {
-                return ROOT_LOAD_KEY;
-            }
-            return `${trimmed.slice(0, idx)}/`;
-        };
-        /**
-         * Refresh every directory currently loaded into the tree. Walks down
-         * from the root through the previously-expanded subdirectories so the
-         * tree state mirrors what's on disk while preserving the user's
-         * expansion state.
+         * Re-fetch the root and every previously-expanded directory so the tree
+         * mirrors the disk while preserving the user's expansion state.
          */
         const refreshAll = async () => {
             const expandedPaths = new Set();
@@ -269,9 +192,8 @@ export function FileBrowserComponent(props) {
                 return;
             }
             const allPaths = [...rootPaths];
-            // BFS through the previously-expanded subtree, fetching only the
-            // directories the user had opened so the refresh doesn't walk the
-            // entire workspace.
+            // Fetch only the previously-expanded subtree so the refresh doesn't
+            // walk the entire workspace.
             const subdirsByParent = new Map();
             subdirsByParent.set(ROOT_LOAD_KEY, rootSubdirs);
             const queue = rootSubdirs.filter(s => expandedPaths.has(s));
@@ -295,8 +217,6 @@ export function FileBrowserComponent(props) {
                     console.error(`xtralab: refresh failed for "${dir}"`, err);
                 }
             }
-            // Reset the tree contents and restore the load-state map so future
-            // expansions know which directories still need fetching.
             model.resetPaths(allPaths);
             loadedPaths.clear();
             for (const path of allPaths) {
@@ -308,18 +228,10 @@ export function FileBrowserComponent(props) {
                     knownDirs.set(subdir, expandedPaths.has(subdir) ? 'loaded' : 'unloaded');
                 }
             });
-            // Refresh the `.gitignore` matcher in case the file was edited
-            // since the last load, then re-apply the resulting statuses to the
-            // newly-loaded paths. The reload runs in parallel with the rest of
-            // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
-            // itself when it completes. The porcelain status is also re-fetched
-            // here so a user-triggered refresh picks up out-of-band git changes
-            // immediately instead of waiting for the next poll tick.
+            // Each re-applies the statuses itself when it completes.
             void refreshGitignoreMatcher();
             void refreshGitStatus();
-            // Re-expand the directories that were expanded before the refresh.
-            // We have to do this after `resetPaths` because the reset starts
-            // every directory in its initial collapsed state.
+            // `resetPaths` starts every directory collapsed, so re-expand after it.
             for (const path of expandedPaths) {
                 const item = model.getItem(path);
                 if (item !== null && item.isDirectory()) {
@@ -328,20 +240,10 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Auto-refresh tick: walk every directory currently loaded into the
-         * tree, fetch its children, and apply the per-directory diff as a
-         * single batched mutation. Unlike {@link refreshAll} this never calls
-         * `model.resetPaths`, so the user's expansion, selection, and scroll
-         * state survive every poll. Mirrors what the default JupyterLab file
-         * browser does for its single-directory view.
-         *
-         * A failed fetch for a single directory is treated as transient and
-         * is skipped without touching that directory's children — they may
-         * still be valid even if this one fetch lost the race with a server
-         * restart. A deleted directory eventually surfaces through its
-         * parent's diff: when the parent is re-fetched and no longer lists
-         * the missing child, the child is removed recursively from the tree
-         * and from the load-state tracking maps.
+         * Auto-refresh tick: diff every loaded directory and apply batched
+         * mutations without `resetPaths`, so expansion, selection, and scroll
+         * state survive. A failed fetch is skipped as transient; a deleted
+         * directory surfaces through its parent's diff and is removed recursively.
          */
         const quietRefresh = async () => {
             if (cancelled) {
@@ -361,10 +263,8 @@ export function FileBrowserComponent(props) {
                 if (cancelled) {
                     return;
                 }
-                // Skip directories that were removed from `knownDirs` while we
-                // were processing an earlier sibling — the cascade cleanup below
-                // can prune deep subtrees, so a path captured at the start of
-                // the tick may already be gone.
+                // The cascade cleanup below can prune subtrees mid-tick, so a dir
+                // captured at the start may already be gone.
                 if (knownDirs.get(dir) !== 'loaded') {
                     continue;
                 }
@@ -391,8 +291,6 @@ export function FileBrowserComponent(props) {
                     if (newChildren.has(lp)) {
                         continue;
                     }
-                    // Disappeared since the last tick. Remove recursively so any
-                    // descendants that were also being tracked go with it.
                     ops.push({ type: 'remove', path: lp, recursive: true });
                     removals.push(lp);
                     if (lp.endsWith('/')) {
@@ -412,15 +310,12 @@ export function FileBrowserComponent(props) {
                     }
                     catch (err) {
                         console.error(`xtralab: auto-refresh batch failed for "${dir}"`, err);
-                        // Leave the bookkeeping mirrors untouched so the next tick
-                        // sees the same starting state and tries again.
+                        // Leave the mirrors untouched so the next tick retries.
                         continue;
                     }
                     mutated = true;
-                    // Apply the matching mirror updates only after the batch lands
-                    // in the model. The cascade cleanup below mirrors the
-                    // `recursive: true` removal semantics so descendants we were
-                    // tracking don't linger in `loadedPaths` or `knownDirs`.
+                    // Mirror updates only after the batch lands; the cascade below
+                    // mirrors the `recursive: true` removal semantics.
                     for (const r of removals) {
                         loadedPaths.delete(r);
                     }
@@ -449,8 +344,7 @@ export function FileBrowserComponent(props) {
                         loadedPaths.add(a);
                     }
                 }
-                // Register newly-observed subdirectories so the next user expand
-                // triggers a fetch instead of being ignored.
+                // Untracked subdirectories would ignore their first expand.
                 for (const subdir of fetched.subdirectories) {
                     if (!knownDirs.has(subdir)) {
                         knownDirs.set(subdir, 'unloaded');
@@ -462,24 +356,8 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Reveal {@link canonicalPath} in the tree: load any unloaded
-         * ancestor directories, expand them, and select the target so it is
-         * scrolled into view. Tolerant of partially-loaded state so the
-         * editor breadcrumbs can call it on any path at any time without
-         * caring about what the tree has already fetched.
-         *
-         * Each ancestor is awaited *before* it is expanded — expanding a
-         * directory triggers the model's subscribe callback, which
-         * synchronously sets the directory's load state to `loading` and
-         * kicks off its own fetch in parallel. Awaiting that in-flight
-         * fetch would return immediately on the second await, leaving the
-         * children unloaded when we move to the next iteration.
-         */
-        /**
-         * Clear the tree selection and scroll back to the top. Invoked by
-         * the file browser widget's `scrollToRoot` method when the home
-         * crumb is clicked; gives that gesture visible feedback even when
-         * the sidebar is already focused on the file browser.
+         * Clear the selection and scroll to the top; gives the home-crumb
+         * gesture visible feedback even when the sidebar is already focused.
          */
         const goToRoot = () => {
             var _a;
@@ -494,13 +372,6 @@ export function FileBrowserComponent(props) {
                 container.scrollTop = 0;
             }
         };
-        /**
-         * Collapse every currently expanded directory in the tree. Walks the
-         * `knownDirs` map (the canonical record of which directories have been
-         * observed in the tree) and calls `.collapse()` on each loaded
-         * directory whose handle reports `isExpanded()`. Unloaded directories
-         * are not expanded by definition, so they're skipped.
-         */
         const collapseAll = () => {
             if (cancelled) {
                 return;
@@ -519,6 +390,12 @@ export function FileBrowserComponent(props) {
                 }
             });
         };
+        /**
+         * Reveal `canonicalPath`: fetch and expand ancestors, then select and
+         * scroll to the target. Each ancestor is fetched *before* expanding —
+         * expansion starts the subscribe callback's own fetch, and awaiting that
+         * in-flight fetch resolves with the children still unloaded.
+         */
         const revealPath = async (canonicalPath) => {
             if (cancelled || canonicalPath.length === 0) {
                 return;
@@ -529,9 +406,7 @@ export function FileBrowserComponent(props) {
             if (segments.length === 0) {
                 return;
             }
-            // Build the ordered list of ancestor directory canonical paths.
-            // For "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
-            // For "foo/bar/"       → ["foo/"].
+            // "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
             const ancestors = [];
             let cumulative = '';
             for (let i = 0; i < segments.length - 1; i++) {
@@ -578,15 +453,13 @@ export function FileBrowserComponent(props) {
                 previous === null || previous === void 0 ? void 0 : previous.deselect();
             }
             target.select();
-            // `select` highlights the row; `scrollToPath` focuses it and scrolls it
-            // to the middle of the viewport, even when the row is virtualized out of
-            // the rendered window.
+            // `scrollToPath` focuses and scrolls even when the row is virtualized
+            // out of the rendered window.
             model.scrollToPath(canonicalPath, { focus: true, offset: 'center' });
         };
         /**
-         * Insert a newly-created path (typically from "new folder" or
-         * "duplicate") into the tree without doing a full refresh. Expands
-         * the parent so the user sees the newly created entry immediately.
+         * Insert a newly-created path without a full refresh and expand its
+         * parent so the entry is visible immediately.
          */
         const handlePathAdded = (canonicalPath) => {
             if (model.getItem(canonicalPath) === null) {
@@ -600,9 +473,8 @@ export function FileBrowserComponent(props) {
             }
             loadedPaths.add(canonicalPath);
             if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
-                // The new directory has no children yet, so mark it as already
-                // loaded — there's nothing to fetch and we don't want a stale
-                // "unloaded" entry to trigger a fetch on the next expand.
+                // A new directory has no children; mark it loaded so a stale
+                // "unloaded" entry doesn't trigger a fetch on the next expand.
                 knownDirs.set(canonicalPath, 'loaded');
             }
             syncGitStatus();
@@ -619,6 +491,132 @@ export function FileBrowserComponent(props) {
                 parentDir.expand();
             }
         };
+        /**
+         * Re-key the load-state mirrors after the tree model moved
+         * `fromPath` to `toPath`; a moved directory rewrites every entry
+         * under its old prefix.
+         */
+        const rekeyMirrors = (fromPath, toPath) => {
+            if (fromPath.endsWith('/')) {
+                for (const path of [...loadedPaths]) {
+                    if (path.startsWith(fromPath)) {
+                        loadedPaths.delete(path);
+                        loadedPaths.add(`${toPath}${path.slice(fromPath.length)}`);
+                    }
+                }
+                for (const [dir, state] of [...knownDirs.entries()]) {
+                    if (dir !== ROOT_LOAD_KEY && dir.startsWith(fromPath)) {
+                        knownDirs.delete(dir);
+                        knownDirs.set(`${toPath}${dir.slice(fromPath.length)}`, state);
+                    }
+                }
+            }
+            else if (loadedPaths.delete(fromPath)) {
+                loadedPaths.add(toPath);
+            }
+        };
+        /**
+         * Rename through the document manager, so collisions surface the
+         * standard overwrite dialog and open widgets follow their file.
+         * Resolves false when the move did not happen — a declined
+         * overwrite (upstream's 'File not renamed' sentinel) or a failure.
+         */
+        const renameOnServer = async (fromPath, toPath) => {
+            try {
+                await renameFile(docManager, toServerPath(fromPath), toServerPath(toPath));
+                return true;
+            }
+            catch (err) {
+                if (err !== 'File not renamed') {
+                    await showErrorMessage(trans.__('Move failed'), err);
+                }
+                return false;
+            }
+        };
+        /**
+         * Persist moves the tree model already applied. A move that did
+         * not reach the disk leaves the tree out of step, so a full
+         * refresh then restores server truth.
+         */
+        const persistDropMoves = async (moves) => {
+            let failed = false;
+            for (const move of moves) {
+                if (!(await renameOnServer(move.from, move.to))) {
+                    failed = true;
+                }
+                if (cancelled) {
+                    return;
+                }
+            }
+            if (failed) {
+                void refreshAll();
+            }
+        };
+        const completeDrop = (result) => {
+            if (cancelled) {
+                return;
+            }
+            const moves = computeDropMoves(result);
+            for (const move of moves) {
+                rekeyMirrors(move.from, move.to);
+            }
+            syncGitStatus();
+            void persistDropMoves(moves);
+        };
+        /**
+         * Server-side renames for moves the tree model did not apply; the
+         * `fileChanged` signals nudge the listing poll to reconcile.
+         */
+        const persistFallbackMoves = async (moves) => {
+            for (const move of moves) {
+                await renameOnServer(move.from, move.to);
+                if (cancelled) {
+                    return;
+                }
+            }
+        };
+        const failedDrop = (error, context) => {
+            if (cancelled) {
+                return;
+            }
+            const moves = computeDropMoves(context);
+            if (moves.length === 0) {
+                console.error('xtralab: drop failed', error);
+                return;
+            }
+            void persistFallbackMoves(moves);
+        };
+        /**
+         * Move the dragged paths to the workspace root: apply to the model
+         * first so the rows relocate instantly, then persist. A path the
+         * model cannot move (name collision) falls back to the server-side
+         * rename and its dialog.
+         */
+        const dropOnRoot = (draggedPaths) => {
+            if (cancelled) {
+                return;
+            }
+            const applied = [];
+            const fallback = [];
+            for (const move of computeRootDropMoves(draggedPaths)) {
+                try {
+                    model.move(move.from, move.to);
+                    rekeyMirrors(move.from, move.to);
+                    applied.push(move);
+                }
+                catch (_a) {
+                    fallback.push(move);
+                }
+            }
+            if (applied.length > 0) {
+                syncGitStatus();
+                void persistDropMoves(applied);
+            }
+            if (fallback.length > 0) {
+                void persistFallbackMoves(fallback);
+            }
+        };
+        dropHandlerRef.current = { completeDrop, failedDrop, dropOnRoot };
         knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
         void fetchDirectory(ROOT_LOAD_KEY);
         void refreshGitignoreMatcher();
@@ -632,13 +630,8 @@ export function FileBrowserComponent(props) {
             },
             standby: 'when-hidden'
         });
-        // Auto-refresh the file listing on the same cadence as the default
-        // JupyterLab file browser. Backoff on failures so a server-side
-        // outage doesn't hammer the API, and stand by when the tab is
-        // hidden so we don't run the polling loop while the user is in
-        // another tab. `auto: false` keeps the first tick from racing the
-        // initial `fetchDirectory(ROOT_LOAD_KEY)` above — the poll is
-        // started explicitly once the initial load is in flight.
+        // `auto: false` keeps the first tick from racing the initial root
+        // fetch above; the poll is started explicitly below.
         const listingPoll = new Poll({
             auto: false,
             name: '@xtralab/fileBrowser:listing',
@@ -651,26 +644,16 @@ export function FileBrowserComponent(props) {
             standby: 'when-hidden'
         });
         void listingPoll.start();
-        // Surface contents changes that happen inside JupyterLab (file save,
-        // rename, delete) without waiting for the next poll tick. The
-        // default file browser uses the same `fileChanged` signal for the
-        // same reason. We can't tell from the signal alone whether the
-        // change affects a path we're showing, so we just nudge the poll —
-        // it diffs the loaded directories and emits no batch ops when
-        // nothing relevant changed.
+        // In-app contents changes (save, rename, delete) nudge the poll; the
+        // signal doesn't say whether a shown path is affected, the diff does.
         const onContentsFileChanged = () => {
             void listingPoll.refresh();
         };
         contentsManager.fileChanged.connect(onContentsFileChanged);
         const unsubscribe = model.subscribe(() => {
-            // Search-driven expansion must not trigger fetches: the tree
-            // auto-expands every directory whose path matches the query, and
-            // treating those as user expansions would recursively fetch every
-            // matching subtree — a single common letter can walk the whole
-            // workspace, node_modules included. Closing the search restores
-            // the pre-search expansion state, and a directory clicked in the
-            // results is toggled after the session closes, so real expansions
-            // are still fetched the moment the session ends.
+            // Search auto-expands every matching directory — fetching those would
+            // walk whole subtrees (node_modules included); real expansions still
+            // fetch once the search session closes.
             if (model.isSearchOpen()) {
                 return;
             }
@@ -718,6 +701,7 @@ export function FileBrowserComponent(props) {
         }
         return () => {
             cancelled = true;
+            dropHandlerRef.current = null;
             gitStatusPoll.dispose();
             contentsManager.fileChanged.disconnect(onContentsFileChanged);
             listingPoll.dispose();
@@ -740,12 +724,9 @@ export function FileBrowserComponent(props) {
                 }
             }
         };
-    }, [model, contentsManager, widget]);
-    // Bridge the tree's selection state up to the widget so command handlers
-    // can read it without depending on React internals. The tree exposes its
-    // selection through `getSelectedPaths()` and emits a generic notification
-    // through `subscribe`, so we diff against a snapshot to avoid spamming the
-    // widget on every unrelated mutation.
+    }, [model, contentsManager, widget, docManager, trans]);
+    // Bridge the tree selection up to the widget. `subscribe` fires on every
+    // mutation, so diff against a snapshot before notifying.
     React.useEffect(() => {
         if (widget === undefined) {
             return;
@@ -766,13 +747,9 @@ export function FileBrowserComponent(props) {
             unsubscribe();
         };
     }, [model, widget]);
-    // Bridge the filter-box visibility between the widget and the tree. The
-    // widget owns the flag; applying it stamps the marker attribute the
-    // unsafeCSS rule keys on and opens or closes the model's search session
-    // (opening focuses the input, closing clears any active filter). The
-    // model subscription covers the reverse direction: typing a printable
-    // character while the tree has focus opens a session on the tree's own
-    // initiative, and the box must surface for that session to be usable.
+    // Applying the widget's filter flag stamps the marker the unsafeCSS rule
+    // keys on and syncs the search session; the subscription surfaces the box
+    // when the tree opens a session itself (typing while focused).
     React.useEffect(() => {
         if (widget === undefined) {
             return;
@@ -839,21 +816,9 @@ export function FileBrowserComponent(props) {
             wrapper.removeEventListener('dblclick', handleDoubleClick);
         };
     }, [onOpenFile]);
-    // Bridge contextmenu events out of the `<file-tree-container>` shadow DOM.
-    //
-    // `@pierre/trees` mounts the tree under an open shadow root attached to the
-    // `<file-tree-container>` custom element. When the user right-clicks a row
-    // inside the shadow tree, the event is retargeted to the host element when
-    // observed from the light DOM, and `app.contextMenu` walks via
-    // `parentElement` — it never enters the shadow tree, so the `[data-type=
-    // "item"]` selectors registered in `schema/plugin.json` never match.
-    //
-    // We listen in the capture phase (so we run before the application's
-    // document-level handler) and copy the right-clicked row's data attributes
-    // onto the host. Lumino then matches the host as if it were the row, and
-    // `app.contextMenuHitTest` from command handlers reads the same attributes
-    // back to recover the path. When the right-click misses any row we clear
-    // the attributes so empty-area clicks don't show stale per-item entries.
+    // Lumino never enters the tree's shadow DOM, so the `[data-type="item"]`
+    // selectors can't match rows; mirror the right-clicked row's data
+    // attributes onto the host (capture phase, cleared on a miss).
     React.useEffect(() => {
         const wrapper = wrapperRef.current;
         if (wrapper === null) {
@@ -896,166 +861,7 @@ export function FileBrowserComponent(props) {
             wrapper.removeEventListener('contextmenu', handleContextMenu, true);
         };
     }, []);
-    // Drag a file row out of the tree onto the JupyterLab main area. The row
-    // lives in the `@pierre/trees` shadow DOM, so we listen to mousedown on
-    // the wrapper and walk `composedPath()` to recover the row. The drag
-    // payload uses Lumino's `FACTORY_MIME` contract: the dock panel calls the
-    // factory function on drop and adds the returned widget to its layout.
-    React.useEffect(() => {
-        const wrapper = wrapperRef.current;
-        if (wrapper === null) {
-            return;
-        }
-        let press = null;
-        let activeDrag = null;
-        const findRow = (event) => {
-            for (const target of event.composedPath()) {
-                if (!(target instanceof HTMLElement)) {
-                    continue;
-                }
-                if (target.dataset.type === 'item') {
-                    return target;
-                }
-            }
-            return null;
-        };
-        const cleanup = () => {
-            press = null;
-            document.removeEventListener('mousemove', handleMouseMove, true);
-            document.removeEventListener('mouseup', handleMouseUp, true);
-        };
-        const handleMouseDown = (event) => {
-            // Only react to the primary button. Do not interfere with right-click
-            // (handled by the contextmenu bridge) or middle-click (browser default).
-            if (event.button !== 0) {
-                return;
-            }
-            if (activeDrag !== null) {
-                return;
-            }
-            const row = findRow(event);
-            if (row === null || row.dataset.itemType !== 'file') {
-                return;
-            }
-            const itemPath = row.dataset.itemPath;
-            if (itemPath === undefined || itemPath.length === 0) {
-                return;
-            }
-            press = { x: event.clientX, y: event.clientY, path: itemPath };
-            document.addEventListener('mousemove', handleMouseMove, true);
-            document.addEventListener('mouseup', handleMouseUp, true);
-        };
-        const handleMouseMove = (event) => {
-            if (press === null) {
-                return;
-            }
-            const dx = Math.abs(event.clientX - press.x);
-            const dy = Math.abs(event.clientY - press.y);
-            if (dx < DRAG_THRESHOLD && dy < DRAG_THRESHOLD) {
-                return;
-            }
-            const startedFrom = press;
-            cleanup();
-            startDrag(startedFrom.path, event.clientX, event.clientY);
-        };
-        const handleMouseUp = () => {
-            cleanup();
-        };
-        /**
-         * Build the list of file paths to drag. If the user pressed on a row
-         * that is part of the current selection, drag every selected file.
-         * Otherwise, drag just the row that was pressed. Folders never join a
-         * drag-out — they have no docmanager widget to open.
-         */
-        const collectDragPaths = (sourcePath) => {
-            const selection = model.getSelectedPaths();
-            const sourceInSelection = selection.includes(sourcePath);
-            const candidates = sourceInSelection ? selection : [sourcePath];
-            const fileServerPaths = [];
-            for (const candidate of candidates) {
-                if (candidate.endsWith('/')) {
-                    continue;
-                }
-                fileServerPaths.push(toServerPath(candidate));
-            }
-            // The source row is always a file, so the list cannot be empty.
-            if (fileServerPaths.length === 0) {
-                fileServerPaths.push(toServerPath(sourcePath));
-            }
-            return fileServerPaths;
-        };
-        const startDrag = (sourcePath, clientX, clientY) => {
-            const paths = collectDragPaths(sourcePath);
-            const sourceServerPath = toServerPath(sourcePath);
-            const dragImage = createDragImage(paths.length);
-            const drag = new Drag({
-                dragImage,
-                mimeData: new MimeData(),
-                supportedActions: 'copy-move',
-                proposedAction: 'move'
-            });
-            drag.mimeData.setData(CONTENTS_MIME, paths);
-            // The factory is called by the lumino dock panel on drop. It must
-            // return a Widget synchronously. For multi-file drags we open the
-            // remaining files asynchronously after the first one is placed,
-            // mirroring the default file browser's behavior.
-            const otherPaths = paths.filter(p => p !== sourceServerPath);
-            drag.mimeData.setData(FACTORY_MIME, () => {
-                let widget = docManager.findWidget(sourceServerPath);
-                if (widget === undefined) {
-                    widget = docManager.open(sourceServerPath);
-                }
-                if (otherPaths.length > 0) {
-                    const firstPlaced = new PromiseDelegate();
-                    void firstPlaced.promise.then(() => {
-                        let prev = widget;
-                        for (const otherPath of otherPaths) {
-                            const opened = docManager.openOrReveal(otherPath, undefined, undefined, prev !== undefined
-                                ? { ref: prev.id, mode: 'tab-after' }
-                                : undefined);
-                            if (opened !== undefined) {
-                                prev = opened;
-                            }
-                        }
-                    });
-                    firstPlaced.resolve();
-                }
-                return widget;
-            });
-            activeDrag = drag;
-            void drag.start(clientX, clientY).then(() => {
-                activeDrag = null;
-            });
-        };
-        wrapper.addEventListener('mousedown', handleMouseDown);
-        return () => {
-            wrapper.removeEventListener('mousedown', handleMouseDown);
-            cleanup();
-            activeDrag === null || activeDrag === void 0 ? void 0 : activeDrag.dispose();
-            activeDrag = null;
-        };
-    }, [model, docManager]);
+    useRootDropZone({ model, handlerRef: dropHandlerRef, wrapperRef });
     return (React.createElement("div", { ref: wrapperRef, style: { display: 'flex', flex: '1 1 auto', minHeight: 0 } },
         React.createElement(FileTree, { model: model, style: { height: '100%', width: '100%' } })));
 }
-/**
- * Build the small badge shown next to the cursor while dragging. The
- * default file browser renders a richer image with the file's icon, but
- * we don't have a per-file icon at this layer — just the count of files
- * being dragged is enough to give the user feedback.
- */
-function createDragImage(count) {
-    const node = document.createElement('div');
-    node.className = 'jp-xtralab-DragImage';
-    const iconWrapper = document.createElement('span');
-    iconWrapper.className = 'jp-xtralab-DragImage-icon';
-    fileIcon.element({ container: iconWrapper, stylesheet: 'menuItem' });
-    node.appendChild(iconWrapper);
-    if (count > 1) {
-        const badge = document.createElement('span');
-        badge.className = 'jp-xtralab-DragImage-count';
-        badge.textContent = String(count);
-        node.appendChild(badge);
-    }
-    return node;
-}