xtralab 0.1.0

package/lib/fileBrowser/fileBrowser.js

@@ -0,0 +1,535 @@
+import * as React from 'react';
+import { fileIcon } from '@jupyterlab/ui-components';
+import { MimeData, PromiseDelegate } from '@lumino/coreutils';
+import { Drag } from '@lumino/dragdrop';
+import { FileTree, useFileTree } from '@pierre/trees/react';
+import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
+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;
+/**
+ * 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';
+/**
+ * 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.
+ */
+export function FileBrowserComponent(props) {
+    const { contentsManager, docManager, onOpenFile, widget } = props;
+    const { model } = useFileTree({
+        paths: [],
+        initialExpansion: 'closed',
+        search: true,
+        icons: FILE_BROWSER_ICONS
+    });
+    React.useEffect(() => {
+        const knownDirs = new Map();
+        let cancelled = false;
+        const fetchDirectory = async (canonicalPath) => {
+            const current = knownDirs.get(canonicalPath);
+            if (current === 'loading' || current === 'loaded') {
+                return;
+            }
+            knownDirs.set(canonicalPath, 'loading');
+            try {
+                const serverPath = toServerPath(canonicalPath);
+                const { paths, subdirectories } = await listDirectory(contentsManager, serverPath);
+                if (cancelled) {
+                    return;
+                }
+                if (canonicalPath === ROOT_LOAD_KEY) {
+                    model.resetPaths(paths);
+                }
+                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.
+                    const operations = paths
+                        .filter(path => model.getItem(path) === null)
+                        .map(path => ({ type: 'add', path }));
+                    if (operations.length > 0) {
+                        model.batch(operations);
+                    }
+                }
+                for (const subdir of subdirectories) {
+                    if (!knownDirs.has(subdir)) {
+                        knownDirs.set(subdir, 'unloaded');
+                    }
+                }
+                knownDirs.set(canonicalPath, 'loaded');
+            }
+            catch (err) {
+                console.error(`xtralab: failed to load directory "${canonicalPath}"`, err);
+                knownDirs.set(canonicalPath, 'unloaded');
+            }
+        };
+        /**
+         * 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.
+         */
+        const refreshAll = async () => {
+            const expandedPaths = new Set();
+            knownDirs.forEach((state, path) => {
+                if (path === ROOT_LOAD_KEY || state !== 'loaded') {
+                    return;
+                }
+                const item = model.getItem(path);
+                if (item !== null &&
+                    item.isDirectory() &&
+                    item.isExpanded()) {
+                    expandedPaths.add(path);
+                }
+            });
+            knownDirs.clear();
+            knownDirs.set(ROOT_LOAD_KEY, 'loading');
+            let rootPaths;
+            let rootSubdirs;
+            try {
+                const result = await listDirectory(contentsManager, '');
+                rootPaths = result.paths;
+                rootSubdirs = result.subdirectories;
+            }
+            catch (err) {
+                console.error('xtralab: refresh failed at the root', err);
+                knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
+                return;
+            }
+            if (cancelled) {
+                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.
+            const subdirsByParent = new Map();
+            subdirsByParent.set(ROOT_LOAD_KEY, rootSubdirs);
+            const queue = rootSubdirs.filter(s => expandedPaths.has(s));
+            while (queue.length > 0) {
+                const dir = queue.shift();
+                try {
+                    const serverPath = toServerPath(dir);
+                    const { paths, subdirectories } = await listDirectory(contentsManager, serverPath);
+                    if (cancelled) {
+                        return;
+                    }
+                    allPaths.push(...paths);
+                    subdirsByParent.set(dir, subdirectories);
+                    for (const subdir of subdirectories) {
+                        if (expandedPaths.has(subdir)) {
+                            queue.push(subdir);
+                        }
+                    }
+                }
+                catch (err) {
+                    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);
+            knownDirs.set(ROOT_LOAD_KEY, 'loaded');
+            subdirsByParent.forEach(subdirs => {
+                for (const subdir of subdirs) {
+                    knownDirs.set(subdir, expandedPaths.has(subdir) ? 'loaded' : 'unloaded');
+                }
+            });
+            // 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.
+            for (const path of expandedPaths) {
+                const item = model.getItem(path);
+                if (item !== null && item.isDirectory()) {
+                    item.expand();
+                }
+            }
+        };
+        /**
+         * 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.
+         */
+        const handlePathAdded = (canonicalPath) => {
+            if (model.getItem(canonicalPath) === null) {
+                try {
+                    model.add(canonicalPath);
+                }
+                catch (err) {
+                    console.error(`xtralab: failed to add path "${canonicalPath}"`, err);
+                    return;
+                }
+            }
+            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.
+                knownDirs.set(canonicalPath, 'loaded');
+            }
+            const parent = parentOf(canonicalPath);
+            if (parent === ROOT_LOAD_KEY) {
+                return;
+            }
+            const parentItem = model.getItem(parent);
+            if (parentItem === null || !parentItem.isDirectory()) {
+                return;
+            }
+            const parentDir = parentItem;
+            if (!parentDir.isExpanded()) {
+                parentDir.expand();
+            }
+        };
+        knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
+        void fetchDirectory(ROOT_LOAD_KEY);
+        const unsubscribe = model.subscribe(() => {
+            knownDirs.forEach((state, canonicalPath) => {
+                if (state !== 'unloaded') {
+                    return;
+                }
+                if (canonicalPath === ROOT_LOAD_KEY) {
+                    return;
+                }
+                const item = model.getItem(canonicalPath);
+                if (item !== null &&
+                    item.isDirectory() &&
+                    item.isExpanded()) {
+                    void fetchDirectory(canonicalPath);
+                }
+            });
+        });
+        let refreshSlot;
+        let pathAddedSlot;
+        if (widget !== undefined) {
+            refreshSlot = () => {
+                void refreshAll();
+            };
+            pathAddedSlot = (_sender, path) => {
+                handlePathAdded(path);
+            };
+            widget.refreshRequested.connect(refreshSlot);
+            widget.pathAdded.connect(pathAddedSlot);
+        }
+        return () => {
+            cancelled = true;
+            unsubscribe();
+            if (widget !== undefined) {
+                if (refreshSlot !== undefined) {
+                    widget.refreshRequested.disconnect(refreshSlot);
+                }
+                if (pathAddedSlot !== undefined) {
+                    widget.pathAdded.disconnect(pathAddedSlot);
+                }
+            }
+        };
+    }, [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.
+    React.useEffect(() => {
+        if (widget === undefined) {
+            return;
+        }
+        let lastSnapshot = [];
+        const sync = () => {
+            const next = model.getSelectedPaths();
+            if (next.length === lastSnapshot.length &&
+                next.every((path, index) => path === lastSnapshot[index])) {
+                return;
+            }
+            lastSnapshot = next;
+            widget.updateSelection(next);
+        };
+        sync();
+        const unsubscribe = model.subscribe(sync);
+        return () => {
+            unsubscribe();
+        };
+    }, [model, widget]);
+    const wrapperRef = React.useRef(null);
+    React.useEffect(() => {
+        const wrapper = wrapperRef.current;
+        if (wrapper === null || onOpenFile === undefined) {
+            return;
+        }
+        const handleDoubleClick = (event) => {
+            for (const target of event.composedPath()) {
+                if (!(target instanceof HTMLElement)) {
+                    continue;
+                }
+                if (target.dataset.type !== 'item') {
+                    continue;
+                }
+                if (target.dataset.itemType !== 'file') {
+                    return;
+                }
+                const itemPath = target.dataset.itemPath;
+                if (itemPath !== undefined && itemPath.length > 0) {
+                    event.preventDefault();
+                    onOpenFile(toServerPath(itemPath));
+                }
+                return;
+            }
+        };
+        wrapper.addEventListener('dblclick', handleDoubleClick);
+        return () => {
+            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.
+    React.useEffect(() => {
+        const wrapper = wrapperRef.current;
+        if (wrapper === null) {
+            return;
+        }
+        const handleContextMenu = (event) => {
+            var _a, _b;
+            let host = null;
+            let rowItem = null;
+            for (const target of event.composedPath()) {
+                if (!(target instanceof HTMLElement)) {
+                    continue;
+                }
+                if (host === null && target.tagName.toLowerCase() === FILE_TREE_TAG) {
+                    host = target;
+                }
+                if (rowItem === null && target.dataset.type === 'item') {
+                    rowItem = target;
+                }
+                if (host !== null && rowItem !== null) {
+                    break;
+                }
+            }
+            if (host === null) {
+                return;
+            }
+            if (rowItem !== null) {
+                host.dataset.type = 'item';
+                host.dataset.itemType = (_a = rowItem.dataset.itemType) !== null && _a !== void 0 ? _a : '';
+                host.dataset.itemPath = (_b = rowItem.dataset.itemPath) !== null && _b !== void 0 ? _b : '';
+            }
+            else {
+                delete host.dataset.type;
+                delete host.dataset.itemType;
+                delete host.dataset.itemPath;
+            }
+        };
+        wrapper.addEventListener('contextmenu', handleContextMenu, true);
+        return () => {
+            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]);
+    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;
+}

package/lib/fileBrowser/icons.d.ts

@@ -0,0 +1,37 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+import type { FileTreeIconConfig } from '@pierre/trees';
+/**
+ * The glyph used as the Xtralab file browser's sidebar tab icon. Defined as a
+ * `LabIcon` (rather than the default `folderIcon` from
+ * `@jupyterlab/ui-components`) so the Xtralab browser is visually distinguishable
+ * from JupyterLab's built-in file browser, which also lives in the left
+ * sidebar.
+ *
+ * Source: `file-tree` from SVG Repo (https://www.svgrepo.com/svg/371275/file-tree).
+ * The original `fill="#444"` is replaced with `fill="currentColor"` and the
+ * root element is given the `jp-icon3` class so the icon picks up JupyterLab's
+ * theme color and the sidebar's inverse-color painting automatically.
+ */
+export declare const xtralabFileBrowserIcon: LabIcon;
+/**
+ * Icon configuration for the Xtralab file browser. Keeps the default `complete`
+ * built-in icon set (the colored language icons) and layers a Jupyter notebook
+ * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
+ *
+ * `set` must be set explicitly: when a config object includes any custom
+ * overrides without `set`, `@pierre/trees` defaults `set` to `'none'`, which
+ * disables the built-in icons entirely.
+ */
+export declare const FILE_BROWSER_ICONS: FileTreeIconConfig;
+/**
+ * Return a JupyterLab `LabIcon` matching the icon the Xtralab file tree would
+ * render for the given file path. Used by other plugins (e.g. the git diff
+ * viewer) that want their main-area widget tabs to display the same per-file
+ * glyph the tree shows in the sidebar.
+ *
+ * Resolves the symbol via the same `@pierre/trees` resolver the tree itself
+ * uses, then inlines the symbol's body into a self-contained SVG so the icon
+ * works outside the tree's shadow DOM. Falls back to JupyterLab's default
+ * `fileIcon` when the sprite cannot be located in either sheet.
+ */
+export declare function getTreeIcon(filePath: string): LabIcon;