xtralab 0.14.1 → 0.15.1

package/lib/fileBrowser/commands.js

@@ -5,11 +5,9 @@ import { addIcon, closeIcon, collapseAllIcon, CommandToolbarButton, copyIcon, do
 import { toCanonicalPath, toServerPath } from './contents';
 import { FILE_BROWSER_ID } from './widget';
 /**
- * Command identifiers exposed by the xtralab browser. We deliberately namespace
- * these under `xtralab:` rather than reusing the `filebrowser:` ids
- * because the core `filebrowser:*` commands look up a `FileBrowser` instance
- * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
- * those handlers would never see it.
+ * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
+ * reusing the `filebrowser:` ids: the core handlers resolve their target via
+ * `IFileBrowserFactory.tracker`, which never sees this widget.
  */
 export var CommandIDs;
 (function (CommandIDs) {
@@ -29,18 +27,13 @@ export var CommandIDs;
     CommandIDs.revealInFileTree = 'xtralab:reveal-in-file-tree';
 })(CommandIDs || (CommandIDs = {}));
 /**
- * Submenu id used to host the dynamically populated "Open With" entries.
- * Distinct from the core file browser's `jp-contextmenu-open-with` so the
- * core's populator does not try to fill ours with items derived from the
- * default file browser's selection.
+ * "Open With" submenu id. Distinct from the core `jp-contextmenu-open-with`
+ * so the core's populator does not fill ours from its own selection.
  */
 const OPEN_WITH_SUBMENU_ID = 'jp-contextmenu-xtralab-open-with';
 /**
- * Resolve the path of the item the user right-clicked. We prefer the
- * contextmenu event's target — that is how `app.contextMenu` resolves which
- * items match a selector — and fall back to the first item in the tree's
- * selection if the command was invoked without an active contextmenu event
- * (e.g. from the command palette).
+ * Path of the right-clicked item, from the contextmenu event's target;
+ * falls back to the tree selection when invoked without one (the palette).
  */
 function getTargetPath(app, browser) {
     const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'item');
@@ -50,25 +43,15 @@ function getTargetPath(app, browser) {
     }
     return browser.selectedPaths[0];
 }
-/**
- * Resolve the kind of the item that was right-clicked, based on the data
- * attributes emitted by `@pierre/trees` rows. Returns `undefined` if no
- * contextmenu event is active or the target is not a tree item.
- */
 function getTargetKind(app) {
     const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'item');
     const kind = node === null || node === void 0 ? void 0 : node.dataset.itemType;
     return kind === 'file' || kind === 'folder' ? kind : undefined;
 }
 /**
- * Resolve the canonical paths the "Open" command should act on. When the
- * user right-clicks a row that is part of the current selection, every
- * selected file is opened — matching the default file browser, where
- * "Open" on any file in a multi-selection opens them all. If the
- * right-clicked row is *not* in the selection, only that row is opened.
- *
- * Folders are always filtered out: there is no "current directory" in
- * this tree, so opening a folder via "Open" is a no-op.
+ * Canonical paths "Open" acts on: the whole selection when the right-clicked
+ * row is part of it (matching the default browser), else just that row.
+ * Folders are filtered out — this tree has no "current directory".
  */
 function getOpenPaths(app, browser) {
     const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'item');
@@ -83,18 +66,13 @@ function getOpenPaths(app, browser) {
     }
     return candidates.filter(path => !path.endsWith('/'));
 }
-/**
- * True iff there is an actionable target for a command on the right-click.
- */
 function hasTarget(app, browser) {
     return getTargetPath(app, browser) !== undefined;
 }
 /**
- * Resolve the directory used as the working directory for actions that
- * create a new file or folder. Folder selections become their own cwd;
- * file selections fall back to their parent. Returns the empty string
- * when the tree has no selection — that matches the contents API's
- * convention for "the root directory".
+ * Working directory for create actions: a selected folder is its own cwd, a
+ * file falls back to its parent; empty string (the contents-API root) when
+ * nothing is selected.
  */
 function getWorkingDirectory(browser) {
     const first = browser.selectedPaths[0];
@@ -108,14 +86,10 @@ function getWorkingDirectory(browser) {
     return PathExt.dirname(serverPath);
 }
 /**
- * Resolve the main-area widget whose tab is the target of the current
- * context-menu event, or `null` when that target is not a document tab. The
- * shell stamps each tab's `data-id` with its widget id, so the right-clicked
- * tab resolves even when it is not the current one.
- *
- * Valid only during a context-menu invocation: `contextMenuHitTest` reads the
- * last context-menu event, which is not cleared when the menu closes, so
- * {@link documentPathToReveal} gates this to avoid resolving a stale tab.
+ * Main-area widget whose tab is the target of the current context-menu
+ * event, or `null`. `contextMenuHitTest` reads the last context-menu event,
+ * which is not cleared when the menu closes, so callers must gate against
+ * resolving a stale tab.
  */
 function contextMenuTabWidget(app) {
     const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'document-title');
@@ -131,10 +105,9 @@ function contextMenuTabWidget(app) {
     return null;
 }
 /**
- * Resolve the document to reveal as a canonical `@pierre/trees` path: the
- * right-clicked tab when `fromContextMenu` is true (the file-tab menu),
- * otherwise the active main-area widget (the palette). A file's context
- * `path` is already canonical. Returns `undefined` when nothing resolves.
+ * Canonical path of the document to reveal: the right-clicked tab when
+ * `fromContextMenu` is true (the file-tab menu), else the active main-area
+ * widget (the palette).
  */
 function documentPathToReveal(app, docManager, fromContextMenu) {
     var _a, _b, _c;
@@ -146,14 +119,10 @@ function documentPathToReveal(app, docManager, fromContextMenu) {
     return path.length > 0 ? path : undefined;
 }
 /**
- * Refresh the "Open With" submenu's items from the document factories that
- * can open the file under the right-click. Mirrors the
- * `@jupyterlab/filebrowser-extension:open-with` pattern: the schema declares
- * an empty submenu by id, and we look it up on the open context menu and
- * fill it before the user can hover.
- *
+ * Build the populator that fills the "Open With" submenu on every
+ * context-menu open, mirroring `filebrowser-extension:open-with`.
  * `preferredWidgetFactories(path)` is path-only, so the populator stays
- * synchronous and the submenu is ready before the user can hover over it.
+ * synchronous and the submenu is ready before the user can hover.
  */
 function makeOpenWithUpdater(app, browser) {
     let items = [];
@@ -182,13 +151,9 @@ function makeOpenWithUpdater(app, browser) {
     };
 }
 /**
- * Register every xtralab command on the application command registry, attach
- * the items to the application context menu, and wire up the dynamic
- * "Open With" submenu populator.
- *
- * @returns A function that detaches the menu items and signal listener.
- *   The commands themselves are owned by the registry for the lifetime of
- *   the plugin.
+ * Register the xtralab commands, context-menu wiring, and the dynamic
+ * "Open With" populator. Returns a detach function; the commands themselves
+ * stay owned by the registry.
  */
 export function registerCommands(opts) {
     var _a;
@@ -403,27 +368,32 @@ export function registerCommands(opts) {
             browser.toggleFileFilter();
         }
     });
-    // Refresh the toggle's state however the filter is shown or hidden —
-    // the toolbar button, or the auto-show that kicks in when typing with
-    // the tree focused opens a search session.
+    // The filter can also auto-show when typing with the tree focused, so
+    // track visibility changes rather than the command's own executions.
     const onFilterVisibleChanged = () => {
         commands.notifyCommandChanged(CommandIDs.toggleFileFilter);
     };
     browser.fileFilterVisibleChanged.connect(onFilterVisibleChanged);
-    // Public reveal seam. Other plugins (editor breadcrumbs, future
-    // "reveal in tree" actions) call this command rather than depending
-    // on the file browser widget directly. Activating the sidebar is part
-    // of the contract: the tree is hidden behind a tab and a reveal that
-    // does not surface the panel would silently no-op from the user's
-    // point of view. An empty path is the "workspace root" gesture —
-    // there is no tree row for the root itself, so the browser is asked
-    // to scroll back to the top and clear its selection instead.
+    // Public reveal seam for other plugins; an empty path is the workspace-root
+    // gesture (the root has no tree row of its own). The tree is movable, so
+    // surface whichever sidebar widget holds it.
+    const activateTreeHost = () => {
+        for (const area of ['left', 'right']) {
+            for (const widget of app.shell.widgets(area)) {
+                if (widget.node.contains(browser.sectionNode)) {
+                    app.shell.activateById(widget.id);
+                    return;
+                }
+            }
+        }
+        app.shell.activateById(FILE_BROWSER_ID);
+    };
     commands.addCommand(CommandIDs.revealPath, {
         label: trans.__('Reveal in File Browser'),
         execute: (args) => {
             var _a;
             const path = (_a = args.path) !== null && _a !== void 0 ? _a : '';
-            app.shell.activateById(FILE_BROWSER_ID);
+            activateTreeHost();
             if (path.length === 0) {
                 browser.scrollToRoot();
             }
@@ -432,8 +402,6 @@ export function registerCommands(opts) {
             }
         }
     });
-    // Reveal the resolved document in the tree browser via the reveal-path
-    // command, which surfaces the sidebar and scrolls to the target.
     commands.addCommand(CommandIDs.revealInFileTree, {
         label: trans.__('Show in File Tree'),
         caption: trans.__('Show this file in the xtralab file browser'),
@@ -468,41 +436,29 @@ export function registerCommands(opts) {
     commands.addCommand(CommandIDs.newLauncher, {
         label: trans.__('New Launcher'),
         caption: trans.__('Open a new launcher'),
-        // Skip the `menuItem` bindprops the other commands use: this command
-        // lives on the toolbar, where the launcher-extension's blue button
-        // styling expects the raw `jp-icon3` paths from `addIcon` so it can
-        // recolor them against the brand background.
+        // Raw `addIcon`, no `menuItem` bindprops: the launcher-extension's blue
+        // toolbar-button styling recolors the raw `jp-icon3` paths.
         icon: addIcon,
         execute: () => {
             const cwd = getWorkingDirectory(browser);
             return commands.execute('launcher:create', { cwd });
         }
     });
-    // Re-evaluate enabled/visible state when the user changes the tree
-    // selection, in case a command's predicate depends on the selection.
     browser.selectionChanged.connect(() => {
         for (const id of Object.values(CommandIDs)) {
             commands.notifyCommandChanged(id);
         }
     });
-    // This command's enabled state tracks the active widget, not the tree
-    // selection, so re-evaluate it on current-widget changes. `currentChanged`
-    // is optional on the shell interface.
     const onCurrentChanged = () => {
         commands.notifyCommandChanged(CommandIDs.revealInFileTree);
     };
     (_a = app.shell.currentChanged) === null || _a === void 0 ? void 0 : _a.connect(onCurrentChanged);
-    // Also surface it in the palette (acts on the active editor); the file-tab
-    // context-menu entry is declared in `schema/plugin.json`.
     const paletteItem = palette === null || palette === void 0 ? void 0 : palette.addItem({
         command: CommandIDs.revealInFileTree,
         category: trans.__('File Browser')
     });
-    // The static items are declared in `schema/plugin.json` under
-    // `jupyter.lab.menus.context` so users can override or disable them. The
-    // schema also declares an empty submenu placeholder with id
-    // `OPEN_WITH_SUBMENU_ID`; we fill it on every open from the document
-    // factories that can open the right-clicked file.
+    // Static context-menu items live in `schema/plugin.json` so users can
+    // override them; the schema declares the empty "Open With" placeholder.
     const updateOpenWithMenu = makeOpenWithUpdater(app, browser);
     app.contextMenu.opened.connect(updateOpenWithMenu);
     return () => {
@@ -514,9 +470,8 @@ export function registerCommands(opts) {
     };
 }
 /**
- * The names we register with the toolbar. Kept distinct from
- * {@link CommandIDs} because the toolbar API uses opaque names rather
- * than commands.
+ * Toolbar item names, distinct from {@link CommandIDs}: the toolbar API
+ * uses opaque names rather than commands.
  */
 export var ToolbarNames;
 (function (ToolbarNames) {
@@ -527,10 +482,8 @@ export var ToolbarNames;
     ToolbarNames.toggleFileFilter = 'toggle-file-filter';
 })(ToolbarNames || (ToolbarNames = {}));
 /**
- * Populate the file browser's toolbar with the buttons that mirror the
- * default JupyterLab file browser: a "+" launcher button, a new-folder
- * button, a refresh button, a collapse-all button, and the file filter
- * toggle.
+ * Populate the toolbar with the buttons that mirror the default JupyterLab
+ * file browser.
  */
 export function populateToolbar(opts) {
     const { app, browser } = opts;

package/lib/fileBrowser/contents.d.ts

@@ -10,11 +10,25 @@ export declare const ROOT_LOAD_KEY = "";
  * still be represented in the flat path list.
  */
 export declare function toCanonicalPath(child: Contents.IModel): string;
+/**
+ * Compute the canonical parent path for a canonical path. Returns
+ * {@link ROOT_LOAD_KEY} for top-level entries.
+ */
+export declare function parentOf(canonicalPath: string): string;
+/**
+ * The last segment of a canonical path. Directories keep their trailing
+ * slash, so appending the result to a canonical directory path yields a
+ * canonical path again.
+ */
+export declare function canonicalBasename(canonicalPath: string): string;
 /**
  * Strip the trailing slash that `@pierre/trees` uses for canonical directory
  * paths so the value can be sent to the Jupyter contents API.
  */
 export declare function toServerPath(canonicalPath: string): string;
+/**
+ * The immediate children of a directory, as canonical `@pierre/trees` paths.
+ */
 interface IListedDirectory {
     /**
      * Canonical paths for every immediate child of the requested directory.

package/lib/fileBrowser/contents.js

@@ -12,6 +12,34 @@ export const ROOT_LOAD_KEY = '';
 export function toCanonicalPath(child) {
     return child.type === 'directory' ? `${child.path}${DIR_SUFFIX}` : child.path;
 }
+/**
+ * Compute the canonical parent path for a canonical path. Returns
+ * {@link ROOT_LOAD_KEY} for top-level entries.
+ */
+export function parentOf(canonicalPath) {
+    const trimmed = canonicalPath.endsWith(DIR_SUFFIX)
+        ? canonicalPath.slice(0, -DIR_SUFFIX.length)
+        : canonicalPath;
+    const idx = trimmed.lastIndexOf(DIR_SUFFIX);
+    if (idx < 0) {
+        return ROOT_LOAD_KEY;
+    }
+    return `${trimmed.slice(0, idx)}${DIR_SUFFIX}`;
+}
+/**
+ * The last segment of a canonical path. Directories keep their trailing
+ * slash, so appending the result to a canonical directory path yields a
+ * canonical path again.
+ */
+export function canonicalBasename(canonicalPath) {
+    const isDir = canonicalPath.endsWith(DIR_SUFFIX);
+    const trimmed = isDir
+        ? canonicalPath.slice(0, -DIR_SUFFIX.length)
+        : canonicalPath;
+    const idx = trimmed.lastIndexOf(DIR_SUFFIX);
+    const base = idx < 0 ? trimmed : trimmed.slice(idx + DIR_SUFFIX.length);
+    return isDir ? `${base}${DIR_SUFFIX}` : base;
+}
 /**
  * Strip the trailing slash that `@pierre/trees` uses for canonical directory
  * paths so the value can be sent to the Jupyter contents API.

package/lib/fileBrowser/dragAndDrop.d.ts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { FileTree, FileTreeDragAndDropConfig, FileTreeDropContext, FileTreeDropResult } from '@pierre/trees';
+/**
+ * One tree-model move a drop performs, as canonical paths.
+ */
+export interface IDropMove {
+    /**
+     * The canonical path of the dragged item.
+     */
+    from: string;
+    /**
+     * The canonical destination path: its basename under the target directory.
+     */
+    to: string;
+}
+/**
+ * Receives drop outcomes from the `@pierre/trees` drag-and-drop
+ * machinery. Implemented inside the file browser's contents-sync
+ * effect, which owns the load-state and contents-API bookkeeping.
+ */
+export interface ITreeDropHandler {
+    /**
+     * The tree applied the drop to its model: persist the move and
+     * re-key the load-state mirrors.
+     */
+    completeDrop(result: FileTreeDropResult): void;
+    /**
+     * The tree refused the drop (typically a name collision) and left
+     * its model untouched.
+     */
+    failedDrop(error: string, context: FileTreeDropContext): void;
+    /**
+     * A drop on the empty space below the last row: move the dragged
+     * paths to the workspace root.
+     */
+    dropOnRoot(draggedPaths: readonly string[]): void;
+}
+/**
+ * The from→to moves a drop performs: each dragged path keeps its
+ * basename under the target directory. Paths already directly inside
+ * the target are skipped.
+ */
+export declare function computeDropMoves(context: FileTreeDropContext): IDropMove[];
+/**
+ * The moves for a drop of `paths` onto the workspace root.
+ */
+export declare function computeRootDropMoves(paths: readonly string[]): IDropMove[];
+/**
+ * Build the `dragAndDrop` option for `useFileTree`. The tree captures
+ * its options once, so the callbacks delegate through `handlerRef`,
+ * filled by the contents-sync effect. `canDrop` hides the drop
+ * highlight for all-no-op drops, which the library would accept.
+ */
+export declare function createTreeDragAndDropConfig(handlerRef: React.RefObject<ITreeDropHandler | null>): FileTreeDragAndDropConfig;
+/**
+ * Options for {@link useRootDropZone}.
+ */
+interface IRootDropZoneOptions {
+    /**
+     * The tree model, queried for the selection at drag start.
+     */
+    model: FileTree;
+    /**
+     * The drop handler ref, filled by the contents-sync effect.
+     */
+    handlerRef: React.RefObject<ITreeDropHandler | null>;
+    /**
+     * The light-DOM wrapper around the tree host; composed drag events
+     * bubble out of the shadow root to it.
+     */
+    wrapperRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * Accept drops on the empty space below the last row as moves to the
+ * workspace root — the tree resolves a drop target only while the cursor
+ * is over a row and silently discards such drops.
+ */
+export declare function useRootDropZone(options: IRootDropZoneOptions): void;
+export {};

package/lib/fileBrowser/dragAndDrop.js

@@ -0,0 +1,110 @@
+import * as React from 'react';
+import { ROOT_LOAD_KEY, canonicalBasename, parentOf } from './contents';
+/**
+ * The from→to moves a drop performs: each dragged path keeps its
+ * basename under the target directory. Paths already directly inside
+ * the target are skipped.
+ */
+export function computeDropMoves(context) {
+    var _a;
+    const dir = (_a = context.target.directoryPath) !== null && _a !== void 0 ? _a : ROOT_LOAD_KEY;
+    return context.draggedPaths
+        .filter(path => parentOf(path) !== dir)
+        .map(path => ({ from: path, to: `${dir}${canonicalBasename(path)}` }));
+}
+const ROOT_DROP_TARGET = {
+    directoryPath: null,
+    flattenedSegmentPath: null,
+    hoveredPath: null,
+    kind: 'root'
+};
+/**
+ * The moves for a drop of `paths` onto the workspace root.
+ */
+export function computeRootDropMoves(paths) {
+    return computeDropMoves({ draggedPaths: paths, target: ROOT_DROP_TARGET });
+}
+/**
+ * Build the `dragAndDrop` option for `useFileTree`. The tree captures
+ * its options once, so the callbacks delegate through `handlerRef`,
+ * filled by the contents-sync effect. `canDrop` hides the drop
+ * highlight for all-no-op drops, which the library would accept.
+ */
+export function createTreeDragAndDropConfig(handlerRef) {
+    return {
+        canDrop: context => computeDropMoves(context).length > 0,
+        onDropComplete: result => {
+            var _a;
+            (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.completeDrop(result);
+        },
+        onDropError: (error, context) => {
+            var _a;
+            (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.failedDrop(error, context);
+        }
+    };
+}
+/**
+ * Accept drops on the empty space below the last row as moves to the
+ * workspace root — the tree resolves a drop target only while the cursor
+ * is over a row and silently discards such drops.
+ */
+export function useRootDropZone(options) {
+    const { model, handlerRef, wrapperRef } = options;
+    React.useEffect(() => {
+        const wrapper = wrapperRef.current;
+        if (wrapper === null) {
+            return;
+        }
+        let draggedPaths = null;
+        const findRow = (event) => {
+            for (const target of event.composedPath()) {
+                if (target instanceof HTMLElement && target.dataset.type === 'item') {
+                    return target;
+                }
+            }
+            return null;
+        };
+        const handleDragStart = (event) => {
+            var _a;
+            draggedPaths = null;
+            // The tree cancels dragstart when it refuses a session, e.g.
+            // while the filter is open.
+            if (event.defaultPrevented) {
+                return;
+            }
+            const path = (_a = findRow(event)) === null || _a === void 0 ? void 0 : _a.dataset.itemPath;
+            if (path === undefined || path.length === 0) {
+                return;
+            }
+            // The selection is the dragged set (the tree selects the pressed
+            // row); entries nested under a dragged folder travel with it.
+            const selection = model.getSelectedPaths();
+            const candidates = selection.includes(path) ? selection : [path];
+            const folders = candidates.filter(c => c.endsWith('/'));
+            draggedPaths = candidates.filter(c => !folders.some(folder => folder !== c && c.startsWith(folder)));
+        };
+        const handleDrop = (event) => {
+            var _a;
+            const paths = draggedPaths;
+            draggedPaths = null;
+            // Drops on a row were already resolved by the tree itself.
+            if (paths === null || findRow(event) !== null) {
+                return;
+            }
+            event.preventDefault();
+            (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.dropOnRoot(paths);
+        };
+        const handleDragEnd = () => {
+            draggedPaths = null;
+        };
+        wrapper.addEventListener('dragstart', handleDragStart);
+        wrapper.addEventListener('drop', handleDrop);
+        window.addEventListener('dragend', handleDragEnd);
+        return () => {
+            wrapper.removeEventListener('dragstart', handleDragStart);
+            wrapper.removeEventListener('drop', handleDrop);
+            window.removeEventListener('dragend', handleDragEnd);
+            draggedPaths = null;
+        };
+    }, [model, handlerRef, wrapperRef]);
+}

package/lib/fileBrowser/fileBrowser.d.ts

@@ -1,25 +1,37 @@
 import * as React from 'react';
 import { IDocumentManager } from '@jupyterlab/docmanager';
 import { Contents } from '@jupyterlab/services';
+import { ITranslator } from '@jupyterlab/translation';
 import type { XtralabFileBrowser } from './widget';
+/**
+ * Props for {@link FileBrowserComponent}.
+ */
 interface IFileBrowserProps {
+    /**
+     * The Jupyter contents manager backing the tree.
+     */
     contentsManager: Contents.IManager;
+    /**
+     * The document manager used to rename files on drag-and-drop moves.
+     */
     docManager: IDocumentManager;
+    /**
+     * Called with the server path of an activated file.
+     */
     onOpenFile?: (serverPath: string) => void;
     /**
-     * The host widget. Selection-change events are pushed up so context-menu
-     * commands can react to what the user has selected.
+     * The application translator; defaults to `nullTranslator`.
+     */
+    translator?: ITranslator;
+    /**
+     * The host widget; selection changes are pushed up for command handlers.
      */
     widget?: XtralabFileBrowser;
 }
 /**
- * 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 declare function FileBrowserComponent(props: IFileBrowserProps): React.ReactElement;
 export {};