xtralab 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jeremy Tuloup
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,69 @@
+# xtralab
+
+An opinionated JupyterLab meta-package.
+
+`xtralab` bundles a curated set of JupyterLab extensions, ships its own
+JupyterLab extension with a path-first file browser and a VS Code-style git
+changes panel, and applies a quieter default workspace configuration. The
+defaults are shipped under `etc/jupyter/labconfig` and the bundled
+labextension is shipped under `share/jupyter/labextensions/xtralab`.
+
+The goal is to keep the package easy to inspect: most behavior comes from the
+upstream Jupyter packages, while `xtralab` defines the default environment we
+want out of the box.
+
+## Approach
+
+The package brings together:
+
+- The `ajlab` meta-package (agent-ready JupyterLab — collaboration plumbing, MCP support, command tooling, and its own quieter defaults)
+- JupyterLab 4.6+
+- Git server integration (`jupyterlab-git` — backs the bundled changes panel)
+- Quick file opening (`jupyterlab-quickopen`)
+- Cursor styling helpers (`jupyterlab-cursor-light`, `jupyterlab-cursor-theme`)
+- Day and night themes (`jupyterlab-day`, `jupyterlab-night`)
+
+These are installed as normal Python dependencies, so deployments can still
+override versions and Jupyter configuration in the usual ways.
+
+## Bundled labextension
+
+`xtralab` ships its own prebuilt labextension that contributes:
+
+- A path-first file browser in the left sidebar, built on `@pierre/trees`.
+- A VS Code-style "Source Control" panel in the left sidebar, powered by the
+  `jupyterlab-git` server REST API and `@pierre/diffs`. The bundled
+  `@jupyterlab/git` frontend is disabled automatically so the two panels do
+  not coexist.
+
+## Default settings
+
+`xtralab` ships the following JupyterLab defaults:
+
+- The announcements plugin is disabled, so JupyterLab does not prompt to fetch
+  news from the Jupyter news feed and does not check for application updates.
+- The Table of Contents, Debugger, and Notebook Tools panels are disabled so
+  they do not show up in the right sidebar by default.
+
+The JupyterLab frontend defaults are shipped as `labconfig/*.d/00-xtralab.json`
+fragments so downstream meta-packages can add their own Lab configuration
+fragments without replacing `xtralab`'s files.
+
+## Install
+
+```bash
+pip install xtralab
+```
+
+## Development
+
+```bash
+# Install dependencies and the package in editable mode
+uv pip install -e ".[dev]"
+jlpm
+jlpm build
+```
+
+## License
+
+BSD-3-Clause

package/lib/fileBrowser/commands.d.ts

@@ -0,0 +1,62 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { IXtralabFileBrowser } 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.
+ */
+export declare namespace CommandIDs {
+    const open = "xtralab:open";
+    const openBrowserTab = "xtralab:open-browser-tab";
+    const rename = "xtralab:rename";
+    const del = "xtralab:delete";
+    const duplicate = "xtralab:duplicate";
+    const copyPath = "xtralab:copy-path";
+    const download = "xtralab:download";
+    const refresh = "xtralab:refresh";
+    const createNewDirectory = "xtralab:create-new-directory";
+    const newLauncher = "xtralab:new-launcher";
+}
+/**
+ * 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.
+ */
+export declare const OPEN_WITH_SUBMENU_ID = "jp-contextmenu-xtralab-open-with";
+export interface IRegisterCommandsOptions {
+    app: JupyterFrontEnd;
+    browser: IXtralabFileBrowser;
+}
+/**
+ * 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.
+ */
+export declare function registerCommands(opts: IRegisterCommandsOptions): () => void;
+/**
+ * The names we register with the toolbar. Kept distinct from
+ * {@link CommandIDs} because the toolbar API uses opaque names rather
+ * than commands.
+ */
+export declare namespace ToolbarNames {
+    const newLauncher = "new-launcher";
+    const newDirectory = "new-directory";
+    const refresh = "refresh";
+}
+/**
+ * Populate the file browser's toolbar with the buttons that mirror the
+ * default JupyterLab file browser: a "+" launcher button, a new-folder
+ * button, and a refresh button. Returns a list of button names so callers
+ * can extend it or remove items if they need to.
+ */
+export declare function populateToolbar(opts: {
+    app: JupyterFrontEnd;
+    browser: IXtralabFileBrowser;
+}): void;

package/lib/fileBrowser/commands.js

@@ -0,0 +1,418 @@
+import { Clipboard, Dialog, InputDialog, showDialog, showErrorMessage } from '@jupyterlab/apputils';
+import { PageConfig, PathExt } from '@jupyterlab/coreutils';
+import { addIcon, closeIcon, CommandToolbarButton, copyIcon, downloadIcon, editIcon, fileIcon, newFolderIcon, refreshIcon } from '@jupyterlab/ui-components';
+import { toCanonicalPath, toServerPath } from './contents';
+/**
+ * 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.
+ */
+export var CommandIDs;
+(function (CommandIDs) {
+    CommandIDs.open = 'xtralab:open';
+    CommandIDs.openBrowserTab = 'xtralab:open-browser-tab';
+    CommandIDs.rename = 'xtralab:rename';
+    CommandIDs.del = 'xtralab:delete';
+    CommandIDs.duplicate = 'xtralab:duplicate';
+    CommandIDs.copyPath = 'xtralab:copy-path';
+    CommandIDs.download = 'xtralab:download';
+    CommandIDs.refresh = 'xtralab:refresh';
+    CommandIDs.createNewDirectory = 'xtralab:create-new-directory';
+    CommandIDs.newLauncher = 'xtralab:new-launcher';
+})(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.
+ */
+export 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).
+ */
+function getTargetPath(app, browser) {
+    const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'item');
+    const fromContext = node === null || node === void 0 ? void 0 : node.dataset.itemPath;
+    if (fromContext !== undefined && fromContext.length > 0) {
+        return fromContext;
+    }
+    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.
+ */
+function getOpenPaths(app, browser) {
+    const node = app.contextMenuHitTest(n => n.dataset !== undefined && n.dataset.type === 'item');
+    const fromContext = node === null || node === void 0 ? void 0 : node.dataset.itemPath;
+    const selection = browser.selectedPaths;
+    let candidates;
+    if (fromContext !== undefined && fromContext.length > 0) {
+        candidates = selection.includes(fromContext) ? selection : [fromContext];
+    }
+    else {
+        candidates = selection;
+    }
+    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".
+ */
+function getWorkingDirectory(browser) {
+    const first = browser.selectedPaths[0];
+    if (first === undefined || first.length === 0) {
+        return '';
+    }
+    const serverPath = toServerPath(first);
+    if (first.endsWith('/')) {
+        return serverPath;
+    }
+    return PathExt.dirname(serverPath);
+}
+/**
+ * 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.
+ *
+ * `preferredWidgetFactories(path)` is path-only, so the populator stays
+ * synchronous and the submenu is ready before the user can hover over it.
+ */
+function makeOpenWithUpdater(app, browser) {
+    let items = [];
+    return (contextMenu) => {
+        var _a, _b;
+        items.forEach(item => item.dispose());
+        items = [];
+        const submenu = (_b = (_a = contextMenu.menu.items.find(item => { var _a; return item.type === 'submenu' && ((_a = item.submenu) === null || _a === void 0 ? void 0 : _a.id) === OPEN_WITH_SUBMENU_ID; })) === null || _a === void 0 ? void 0 : _a.submenu) !== null && _b !== void 0 ? _b : null;
+        if (submenu === null) {
+            return;
+        }
+        submenu.clearItems();
+        if (getTargetKind(app) !== 'file') {
+            return;
+        }
+        const targetPath = getTargetPath(app, browser);
+        if (targetPath === undefined) {
+            return;
+        }
+        const serverPath = toServerPath(targetPath);
+        const factories = app.docRegistry.preferredWidgetFactories(serverPath);
+        items = factories.map(factory => submenu.addItem({
+            args: { factory: factory.name, label: factory.label || factory.name },
+            command: CommandIDs.open
+        }));
+    };
+}
+/**
+ * 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.
+ */
+export function registerCommands(opts) {
+    const { app, browser } = opts;
+    const { commands } = app;
+    commands.addCommand(CommandIDs.open, {
+        label: args => { var _a, _b; return ((_b = (_a = args.label) !== null && _a !== void 0 ? _a : args.factory) !== null && _b !== void 0 ? _b : 'Open'); },
+        icon: args => {
+            var _a;
+            const factoryName = args.factory;
+            if (factoryName !== undefined) {
+                const fileType = app.docRegistry.getFileType(factoryName);
+                return (_a = fileType === null || fileType === void 0 ? void 0 : fileType.icon) === null || _a === void 0 ? void 0 : _a.bindprops({ stylesheet: 'menuItem' });
+            }
+            return fileIcon.bindprops({ stylesheet: 'menuItem' });
+        },
+        mnemonic: 0,
+        isEnabled: () => getOpenPaths(app, browser).length > 0,
+        execute: async (args) => {
+            var _a;
+            const targets = getOpenPaths(app, browser);
+            if (targets.length === 0) {
+                return;
+            }
+            const factory = (_a = args.factory) !== null && _a !== void 0 ? _a : undefined;
+            await Promise.all(targets.map(target => commands.execute('docmanager:open', {
+                path: toServerPath(target),
+                factory
+            })));
+        }
+    });
+    commands.addCommand(CommandIDs.openBrowserTab, {
+        label: 'Open in New Browser Tab',
+        icon: fileIcon.bindprops({ stylesheet: 'menuItem' }),
+        isEnabled: () => getTargetKind(app) === 'file',
+        isVisible: () => getTargetKind(app) === 'file',
+        execute: async () => {
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            return commands.execute('docmanager:open-browser-tab', {
+                path: toServerPath(targetPath)
+            });
+        }
+    });
+    commands.addCommand(CommandIDs.rename, {
+        label: 'Rename…',
+        icon: editIcon.bindprops({ stylesheet: 'menuItem' }),
+        mnemonic: 0,
+        isEnabled: () => hasTarget(app, browser),
+        execute: async () => {
+            var _a;
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            const serverPath = toServerPath(targetPath);
+            const oldName = PathExt.basename(serverPath);
+            const result = await InputDialog.getText({
+                title: 'Rename',
+                label: 'Enter a new name',
+                text: oldName,
+                okLabel: 'Rename'
+            });
+            const newName = (_a = result.value) === null || _a === void 0 ? void 0 : _a.trim();
+            if (result.button.accept !== true ||
+                newName === undefined ||
+                newName.length === 0 ||
+                newName === oldName) {
+                return;
+            }
+            const newPath = PathExt.join(PathExt.dirname(serverPath), newName);
+            try {
+                await browser.contentsManager.rename(serverPath, newPath);
+                browser.refresh();
+            }
+            catch (err) {
+                await showErrorMessage('Rename failed', err);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.del, {
+        label: () => PageConfig.getOption('delete_to_trash') === 'true'
+            ? 'Move to Trash'
+            : 'Delete',
+        icon: closeIcon.bindprops({ stylesheet: 'menuItem' }),
+        mnemonic: 0,
+        isEnabled: () => hasTarget(app, browser),
+        execute: async () => {
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            const serverPath = toServerPath(targetPath);
+            const trashing = PageConfig.getOption('delete_to_trash') === 'true';
+            const result = await showDialog({
+                title: trashing ? 'Move to Trash' : 'Delete',
+                body: `Are you sure you want to permanently delete: ${serverPath}?`,
+                buttons: [
+                    Dialog.cancelButton(),
+                    Dialog.warnButton({ label: trashing ? 'Move to Trash' : 'Delete' })
+                ]
+            });
+            if (result.button.accept !== true) {
+                return;
+            }
+            try {
+                await browser.contentsManager.delete(serverPath);
+                browser.refresh();
+            }
+            catch (err) {
+                await showErrorMessage('Delete failed', err);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.duplicate, {
+        label: 'Duplicate',
+        icon: copyIcon.bindprops({ stylesheet: 'menuItem' }),
+        isEnabled: () => getTargetKind(app) === 'file',
+        isVisible: () => getTargetKind(app) === 'file',
+        execute: async () => {
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            const serverPath = toServerPath(targetPath);
+            const dir = PathExt.dirname(serverPath);
+            try {
+                const created = await browser.contentsManager.copy(serverPath, dir);
+                browser.notifyPathAdded(toCanonicalPath(created));
+            }
+            catch (err) {
+                await showErrorMessage('Duplicate failed', err);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.copyPath, {
+        label: 'Copy Path',
+        icon: fileIcon.bindprops({ stylesheet: 'menuItem' }),
+        isEnabled: () => hasTarget(app, browser),
+        execute: async () => {
+            var _a;
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            const serverPath = toServerPath(targetPath);
+            if (PageConfig.getOption('copyAbsolutePath') === 'true') {
+                Clipboard.copyToSystem(PathExt.joinWithLeadingSlash((_a = PageConfig.getOption('serverRoot')) !== null && _a !== void 0 ? _a : '', serverPath));
+            }
+            else {
+                Clipboard.copyToSystem(serverPath);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.download, {
+        label: 'Download',
+        icon: downloadIcon.bindprops({ stylesheet: 'menuItem' }),
+        isEnabled: () => getTargetKind(app) === 'file',
+        isVisible: () => getTargetKind(app) === 'file',
+        execute: async () => {
+            const targetPath = getTargetPath(app, browser);
+            if (targetPath === undefined) {
+                return;
+            }
+            const serverPath = toServerPath(targetPath);
+            try {
+                const url = await browser.contentsManager.getDownloadUrl(serverPath);
+                const anchor = document.createElement('a');
+                anchor.href = url;
+                anchor.download = '';
+                document.body.appendChild(anchor);
+                anchor.click();
+                document.body.removeChild(anchor);
+            }
+            catch (err) {
+                await showErrorMessage('Download failed', err);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.refresh, {
+        label: 'Refresh File List',
+        caption: 'Refresh the file browser',
+        icon: refreshIcon.bindprops({ stylesheet: 'menuItem' }),
+        execute: () => {
+            browser.refresh();
+        }
+    });
+    commands.addCommand(CommandIDs.createNewDirectory, {
+        label: 'New Folder',
+        caption: 'Create a new folder',
+        icon: newFolderIcon.bindprops({ stylesheet: 'menuItem' }),
+        execute: async () => {
+            const cwd = getWorkingDirectory(browser);
+            try {
+                const created = await browser.contentsManager.newUntitled({
+                    path: cwd,
+                    type: 'directory'
+                });
+                browser.notifyPathAdded(toCanonicalPath(created));
+            }
+            catch (err) {
+                await showErrorMessage('Could not create folder', err);
+            }
+        }
+    });
+    commands.addCommand(CommandIDs.newLauncher, {
+        label: 'New Launcher',
+        caption: '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.
+        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);
+        }
+    });
+    // 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.
+    const updateOpenWithMenu = makeOpenWithUpdater(app, browser);
+    app.contextMenu.opened.connect(updateOpenWithMenu);
+    return () => {
+        app.contextMenu.opened.disconnect(updateOpenWithMenu);
+    };
+}
+/**
+ * The names we register with the toolbar. Kept distinct from
+ * {@link CommandIDs} because the toolbar API uses opaque names rather
+ * than commands.
+ */
+export var ToolbarNames;
+(function (ToolbarNames) {
+    ToolbarNames.newLauncher = 'new-launcher';
+    ToolbarNames.newDirectory = 'new-directory';
+    ToolbarNames.refresh = 'refresh';
+})(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, and a refresh button. Returns a list of button names so callers
+ * can extend it or remove items if they need to.
+ */
+export function populateToolbar(opts) {
+    const { app, browser } = opts;
+    const { commands } = app;
+    browser.toolbar.addItem(ToolbarNames.newLauncher, new CommandToolbarButton({
+        commands,
+        id: CommandIDs.newLauncher,
+        label: ''
+    }));
+    browser.toolbar.addItem(ToolbarNames.newDirectory, new CommandToolbarButton({
+        commands,
+        id: CommandIDs.createNewDirectory,
+        label: ''
+    }));
+    browser.toolbar.addItem(ToolbarNames.refresh, new CommandToolbarButton({
+        commands,
+        id: CommandIDs.refresh,
+        label: ''
+    }));
+}

package/lib/fileBrowser/contents.d.ts

@@ -0,0 +1,28 @@
+import { Contents } from '@jupyterlab/services';
+/**
+ * The canonical path used by the root of the in-memory load-state map.
+ * The tree itself does not surface a path for its root.
+ */
+export declare const ROOT_LOAD_KEY = "";
+/**
+ * Convert a {@link Contents.IModel} into the canonical path expected by
+ * `@pierre/trees`. Directories carry a trailing slash so empty directories can
+ * still be represented in the flat path list.
+ */
+export declare function toCanonicalPath(child: Contents.IModel): 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;
+export interface IListedDirectory {
+    /** Canonical paths for every immediate child of the requested directory. */
+    paths: string[];
+    /** Subset of {@link IListedDirectory.paths} that are directories. */
+    subdirectories: string[];
+}
+/**
+ * Fetch the immediate children of a directory through the Jupyter contents API
+ * and return them as canonical `@pierre/trees` paths.
+ */
+export declare function listDirectory(manager: Contents.IManager, serverPath: string): Promise<IListedDirectory>;

package/lib/fileBrowser/contents.js

@@ -0,0 +1,48 @@
+const DIR_SUFFIX = '/';
+/**
+ * The canonical path used by the root of the in-memory load-state map.
+ * The tree itself does not surface a path for its root.
+ */
+export const ROOT_LOAD_KEY = '';
+/**
+ * Convert a {@link Contents.IModel} into the canonical path expected by
+ * `@pierre/trees`. Directories carry a trailing slash so empty directories can
+ * still be represented in the flat path list.
+ */
+export function toCanonicalPath(child) {
+    return child.type === 'directory' ? `${child.path}${DIR_SUFFIX}` : child.path;
+}
+/**
+ * Strip the trailing slash that `@pierre/trees` uses for canonical directory
+ * paths so the value can be sent to the Jupyter contents API.
+ */
+export function toServerPath(canonicalPath) {
+    if (canonicalPath === ROOT_LOAD_KEY) {
+        return '';
+    }
+    return canonicalPath.endsWith(DIR_SUFFIX)
+        ? canonicalPath.slice(0, -DIR_SUFFIX.length)
+        : canonicalPath;
+}
+/**
+ * Fetch the immediate children of a directory through the Jupyter contents API
+ * and return them as canonical `@pierre/trees` paths.
+ */
+export async function listDirectory(manager, serverPath) {
+    var _a;
+    const model = await manager.get(serverPath, { content: true });
+    if (model.type !== 'directory') {
+        throw new Error(`Expected a directory at "${serverPath}", got "${model.type}"`);
+    }
+    const children = (_a = model.content) !== null && _a !== void 0 ? _a : [];
+    const paths = [];
+    const subdirectories = [];
+    for (const child of children) {
+        const canonical = toCanonicalPath(child);
+        paths.push(canonical);
+        if (child.type === 'directory') {
+            subdirectories.push(canonical);
+        }
+    }
+    return { paths, subdirectories };
+}

package/lib/fileBrowser/fileBrowser.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { Contents } from '@jupyterlab/services';
+import type { XtralabFileBrowser } from './widget';
+export interface IFileBrowserProps {
+    contentsManager: Contents.IManager;
+    docManager: IDocumentManager;
+    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.
+     */
+    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.
+ */
+export declare function FileBrowserComponent(props: IFileBrowserProps): React.ReactElement;