xtralab 0.14.1 → 0.15.1

package/lib/fileBrowser/widget.js

@@ -1,23 +1,28 @@
 import * as React from 'react';
-import { ReactWidget, Toolbar } from '@jupyterlab/ui-components';
+import { AccordionToolbar, PanelWithToolbar, ReactWidget, Toolbar } from '@jupyterlab/ui-components';
 import { Signal } from '@lumino/signaling';
-import { PanelLayout, Widget } from '@lumino/widgets';
+import { AccordionPanel, PanelLayout, Widget } from '@lumino/widgets';
 import { FileBrowserComponent } from './fileBrowser';
 import { xtralabFileBrowserIcon } from './icons';
 export const FILE_BROWSER_ID = 'xtralab:file-browser';
 /**
- * The CSS class added to the xtralab file browser widget. The selectors that
- * bind application context menu items hang off this class, so it must remain
- * specific enough not to clash with other browsers (such as the default
- * `jp-FileBrowser`).
+ * Persisted by the movable-sections plugin, so it must stay stable.
+ */
+const TREE_SECTION_ID = 'xtralab-file-tree-section';
+/**
+ * Context menu selectors hang off this class, so it sits on the section and
+ * keeps matching once the tree moves to another panel.
  */
 const FILE_BROWSER_CSS_CLASS = 'jp-xtralab-FileBrowser';
+const PANEL_CSS_CLASS = 'jp-xtralab-FileBrowserPanel';
 const TOOLBAR_CSS_CLASS = 'jp-xtralab-FileBrowser-toolbar';
 const CONTENT_CSS_CLASS = 'jp-xtralab-FileBrowser-content';
+const ACCORDION_CSS_CLASS = 'jp-xtralab-FileBrowser-accordion';
+const MOVABLE_SECTION_CLASS = 'jp-movable-section';
 /**
- * Lumino widget that hosts the React-based `@pierre/trees` file browser.
- * The widget is laid out with a JupyterLab `Toolbar` on top and the tree
- * filling the remaining space.
+ * Lumino widget hosting the React-based `@pierre/trees` file browser. The tree
+ * and its toolbar form one movable "Files" section, and sections from other
+ * panels can be moved in below it.
  */
 export class XtralabFileBrowser extends Widget {
     constructor(options) {
@@ -31,86 +36,148 @@ export class XtralabFileBrowser extends Widget {
         this._collapseAllRequested = new Signal(this);
         this._fileFilterVisible = false;
         this._fileFilterVisibleChanged = new Signal(this);
-        const layout = (this.layout = new PanelLayout());
+        this._accordion = null;
+        this._contentChanged = new Signal(this);
+        this._sectionAdded = new Signal(this);
+        const layout = (this._panelLayout = this.layout = new PanelLayout());
         this._contentsManager = options.contentsManager;
         this._docManager = options.docManager;
         this._onOpenFile = options.onOpenFile;
+        this._translator = options.translator;
         this.id = FILE_BROWSER_ID;
         this.title.icon = xtralabFileBrowserIcon;
         this.title.caption = 'xtralab File Browser';
-        this.addClass(FILE_BROWSER_CSS_CLASS);
+        this.addClass(PANEL_CSS_CLASS);
         this._toolbar = new Toolbar();
         this._toolbar.addClass(TOOLBAR_CSS_CLASS);
         this._toolbar.node.setAttribute('aria-label', 'file browser');
-        layout.addWidget(this._toolbar);
         this._content = new XtralabFileTreeContent({
             contentsManager: this._contentsManager,
             docManager: this._docManager,
             onOpenFile: this._onOpenFile,
+            translator: this._translator,
             browser: this
         });
         this._content.addClass(CONTENT_CSS_CLASS);
-        layout.addWidget(this._content);
+        this._section = new PanelWithToolbar({ toolbar: this._toolbar });
+        this._section.id = TREE_SECTION_ID;
+        // Only an accordion host draws this; a plain `PanelLayout` shows no title.
+        this._section.title.label = 'Files';
+        this._section.addClass(FILE_BROWSER_CSS_CLASS);
+        this._section.addWidget(this._toolbar);
+        this._section.addWidget(this._content);
+        layout.addWidget(this._section);
     }
+    /**
+     * The contents manager backing the tree.
+     */
     get contentsManager() {
         return this._contentsManager;
     }
+    /**
+     * The toolbar above the tree.
+     */
     get toolbar() {
         return this._toolbar;
     }
+    /**
+     * Canonical selected paths; folder paths carry a trailing slash.
+     */
     get selectedPaths() {
         return this._selectedPaths;
     }
+    /**
+     * A signal emitted when the tree's selection changes.
+     */
     get selectionChanged() {
         return this._selectionChanged;
     }
+    /**
+     * A signal emitted when {@link refresh} is called.
+     */
     get refreshRequested() {
         return this._refreshRequested;
     }
+    /**
+     * A signal emitting a newly-created canonical path for the tree to insert.
+     */
     get pathAdded() {
         return this._pathAdded;
     }
+    /**
+     * A signal emitting a canonical path to load, expand, select, and scroll to.
+     */
     get revealRequested() {
         return this._revealRequested;
     }
+    /**
+     * A signal emitted when the tree should return to the workspace root.
+     */
     get rootRequested() {
         return this._rootRequested;
     }
+    /**
+     * A signal emitted when every expanded folder should collapse.
+     */
     get collapseAllRequested() {
         return this._collapseAllRequested;
     }
+    /**
+     * Whether the filter box above the tree is shown.
+     */
     get fileFilterVisible() {
         return this._fileFilterVisible;
     }
+    /**
+     * A signal emitted when {@link fileFilterVisible} changes.
+     */
     get fileFilterVisibleChanged() {
         return this._fileFilterVisibleChanged;
     }
     /**
-     * Update the cached selection. Called from the React tree when the
-     * underlying `@pierre/trees` model emits a selection change.
+     * Update the cached selection from the React tree.
      */
     updateSelection(paths) {
         this._selectedPaths = paths;
         this._selectionChanged.emit(paths);
     }
+    /**
+     * Trigger a refresh of every loaded directory in the tree.
+     */
     refresh() {
         this._refreshRequested.emit();
     }
+    /**
+     * Notify the tree that a new canonical path was created.
+     */
     notifyPathAdded(canonicalPath) {
         this._pathAdded.emit(canonicalPath);
     }
+    /**
+     * Reveal a non-empty canonical path in the tree; use {@link scrollToRoot}
+     * for the workspace root, which has no tree row of its own.
+     */
     reveal(canonicalPath) {
         if (canonicalPath.length === 0) {
             throw new Error('XtralabFileBrowser.reveal requires a non-empty canonical path; use scrollToRoot for the workspace root.');
         }
         this._revealRequested.emit(canonicalPath);
     }
+    /**
+     * Return to the workspace root: clear the selection and scroll to the top.
+     */
     scrollToRoot() {
         this._rootRequested.emit();
     }
+    /**
+     * Ask the tree to collapse every currently expanded folder.
+     */
     collapseAll() {
         this._collapseAllRequested.emit();
     }
+    /**
+     * Show or hide the filter box above the tree.
+     */
     setFileFilterVisible(visible) {
         if (this._fileFilterVisible === visible) {
             return;
@@ -118,20 +185,177 @@ export class XtralabFileBrowser extends Widget {
         this._fileFilterVisible = visible;
         this._fileFilterVisibleChanged.emit(visible);
     }
+    /**
+     * Toggle the filter box above the tree.
+     */
     toggleFileFilter() {
         this.setFileFilterVisible(!this._fileFilterVisible);
     }
+    /**
+     * The DOM node of the movable "Files" section.
+     */
+    get sectionNode() {
+        return this._section.node;
+    }
+    /**
+     * Whether the panel currently holds no sections, its own tree included.
+     */
+    get isEmpty() {
+        return this._panelLayout.widgets.length === 0;
+    }
+    /**
+     * A signal emitted when a section is added to or removed from the panel.
+     */
+    get contentChanged() {
+        return this._contentChanged;
+    }
+    /**
+     * A signal emitting each section entry announced to the move plugin.
+     */
+    get sectionAdded() {
+        return this._sectionAdded;
+    }
+    /**
+     * The accordion hosting the sections, or `null` while the tree sits alone.
+     */
+    get accordionPanel() {
+        return this._accordion;
+    }
+    /**
+     * Section widgets hosted from other panels; the tree section is excluded.
+     */
+    get sections() {
+        if (!this._accordion) {
+            return [];
+        }
+        return this._accordion.widgets.filter(w => w !== this._section);
+    }
+    /**
+     * The toolbar is the section's title node: it is the tree's header row at
+     * home, and an accordion host renders it inside the section title.
+     */
+    getSections() {
+        return this._isSectionHome()
+            ? [
+                {
+                    id: TREE_SECTION_ID,
+                    titleNode: this._toolbar.node,
+                    widget: this._section
+                }
+            ]
+            : [];
+    }
+    /**
+     * Detach and return the tree section so the move plugin can re-host it;
+     * `null` for any other id or when the section is already away from home.
+     */
+    removeSectionById(sectionId) {
+        if (sectionId !== TREE_SECTION_ID || !this._isSectionHome()) {
+            return null;
+        }
+        this._section.parent = null;
+        if (this._accordion && this._accordion.widgets.length === 0) {
+            this._accordion.dispose();
+            this._accordion = null;
+        }
+        // Away from home the toolbar must not offer "Move to …" as well;
+        // `getSections` re-marks it on the way back.
+        this._toolbar.node.classList.remove(MOVABLE_SECTION_CLASS);
+        this._contentChanged.emit();
+        return this._section;
+    }
+    /**
+     * Re-attach the tree section after a move back to this panel.
+     */
+    reinsertSection(widget) {
+        if (this._accordion) {
+            this._accordion.insertWidget(0, widget);
+        }
+        else {
+            this._panelLayout.addWidget(widget);
+            this._restoreToolbar();
+        }
+        this._contentChanged.emit();
+    }
+    /**
+     * The move plugin reconciles persisted moves only against sections announced
+     * after `registerSource`, and this panel builds its section in the constructor.
+     */
+    announceSections() {
+        for (const entry of this.getSections()) {
+            this._sectionAdded.emit(entry);
+        }
+    }
+    /**
+     * The first hosted section moves the tree into an accordion.
+     */
+    addSection(widget) {
+        if (!this._accordion) {
+            const accordion = new AccordionPanel({
+                layout: AccordionToolbar.createLayout({})
+            });
+            accordion.addClass(ACCORDION_CSS_CLASS);
+            if (this._section.parent === this) {
+                accordion.addWidget(this._section);
+            }
+            accordion.addWidget(widget);
+            this._accordion = accordion;
+            this._panelLayout.addWidget(accordion);
+        }
+        else {
+            this._accordion.addWidget(widget);
+        }
+        this._contentChanged.emit();
+    }
+    /**
+     * Remove a hosted section; the accordion is torn down once only the
+     * panel's own tree section (or nothing) remains.
+     */
+    removeSectionWidget(widget) {
+        if (!this._accordion || widget.parent !== this._accordion) {
+            return;
+        }
+        widget.parent = null;
+        const remaining = this._accordion.widgets;
+        const treeOnly = remaining.length === 1 && remaining[0] === this._section;
+        if (treeOnly || remaining.length === 0) {
+            if (treeOnly) {
+                if (this._section.isHidden) {
+                    this._section.show();
+                }
+                this._panelLayout.addWidget(this._section);
+                this._restoreToolbar();
+            }
+            this._accordion.dispose();
+            this._accordion = null;
+        }
+        this._contentChanged.emit();
+    }
+    _isSectionHome() {
+        const parent = this._section.parent;
+        return parent === this || (!!this._accordion && parent === this._accordion);
+    }
+    /**
+     * An accordion host moves the toolbar node into the section title and leaves
+     * it orphaned on detach; re-parenting makes the layout attach it again.
+     */
+    _restoreToolbar() {
+        this._toolbar.parent = null;
+        this._section.insertWidget(0, this._toolbar);
+    }
 }
 /**
- * The React-rendered region of the file browser. Lives inside the host
- * widget below the toolbar and renders the actual tree.
+ * The React-rendered region below the toolbar that hosts the actual tree.
  */
 class XtralabFileTreeContent extends ReactWidget {
     constructor(options) {
         super();
         this._options = options;
     }
+    /**
+     * Render the file browser React component.
+     */
     render() {
-        return (React.createElement(FileBrowserComponent, { contentsManager: this._options.contentsManager, docManager: this._options.docManager, onOpenFile: this._options.onOpenFile, widget: this._options.browser }));
+        return (React.createElement(FileBrowserComponent, { contentsManager: this._options.contentsManager, docManager: this._options.docManager, onOpenFile: this._options.onOpenFile, translator: this._options.translator, widget: this._options.browser }));
     }
 }

package/lib/fileTypeIcons/index.js

@@ -11,12 +11,8 @@ function representativePath(fileType) {
     if (extension === undefined || extension === '') {
         return null;
     }
-    // Extensions are stored with a leading dot (e.g. `.py`, `.tar.gz`).
     return `file${extension.startsWith('.') ? extension : `.${extension}`}`;
 }
-/**
- * Point a file type's icon at the tree glyph for its extension.
- */
 function applyTreeIcon(fileType) {
     const path = representativePath(fileType);
     if (path === null) {
@@ -62,9 +58,6 @@ const EXTRA_FILE_TYPE_EXTENSIONS = [
     '.graphql',
     '.wasm'
 ];
-/**
- * Register icon-only file types for unclaimed source extensions.
- */
 function registerExtraFileTypes(docRegistry) {
     for (const extension of EXTRA_FILE_TYPE_EXTENSIONS) {
         const icon = getSpecificTreeIcon(`file${extension}`);
@@ -100,7 +93,6 @@ const plugin = {
             applyTreeIcon(fileType);
         }
         registerExtraFileTypes(docRegistry);
-        // Pick up file types registered after this plugin activates.
         docRegistry.changed.connect((_, args) => {
             if (args.type === 'fileType' &&
                 args.change === 'added' &&
@@ -120,8 +112,6 @@ const plugin = {
                     }
                 };
                 setIcon();
-                // Keep the tab icon right after a rename, and release the listener
-                // when the document closes.
                 widget.context.pathChanged.connect(setIcon);
                 widget.disposed.connect(() => {
                     widget.context.pathChanged.disconnect(setIcon);

package/lib/git/api.d.ts

@@ -1,24 +1,16 @@
 import { GitReference, IFileChange, IGitContentResult, IGitStatusFile, IGitStatusResult } from './tokens';
 /**
- * Fetch `git status --porcelain` for the repository the server resolves at
- * `repoPath`. When `repoPath` is the empty string, git resolves the repo
- * from the JupyterLab server's root directory.
+ * Fetch `git status --porcelain` for the repo at `repoPath` (empty string
+ * resolves from the server's root directory).
  */
 export declare function status(repoPath: string): Promise<IGitStatusResult>;
 /**
- * Fetch a file's contents at a particular git reference. `filename` is the
- * file's path relative to the git repository root (matching the `to` field
- * of {@link status}'s response).
+ * Fetch a file's contents at a git reference; `filename` is relative to the
+ * git repository root.
  */
 export declare function content(repoPath: string, filename: string, reference: GitReference): Promise<IGitContentResult>;
 /**
  * Expand the porcelain `files` array into one entry per logical change.
- * A single porcelain row may map to two `IFileChange` rows (a file that's
- * both staged and modified again in the worktree); callers that just want
- * a flat list of all changes — without any staged-vs-unstaged grouping —
- * can use this helper.
- *
- * Provided as a manual concat rather than `Array.prototype.flatMap` so we
- * don't pin our `tsconfig.lib` to ES2019.
+ * Manual concat rather than `flatMap` so `tsconfig.lib` need not be ES2019.
  */
 export declare function expandStatusFiles(files: IGitStatusFile[]): IFileChange[];

package/lib/git/api.js

@@ -1,24 +1,10 @@
 import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
-/**
- * Root URL segment used by the `jupyterlab_git` server extension. Every
- * endpoint hangs off this prefix; the `<repoPath>` between it and the
- * endpoint suffix is the JupyterLab server-relative path of the git
- * repository (URL-encoded). For an empty `repoPath` the URL collapses to
- * `/git/<endpoint>` — a shape git's URL routing also accepts.
- */
 const GIT_NAMESPACE = 'git';
-/**
- * Issue a `POST` against a `jupyterlab_git` endpoint that takes a `<path>`
- * prefix (e.g. `/git/<path>/status`). The response body is decoded as JSON;
- * non-2xx responses are surfaced via the JupyterLab `ServerConnection`
- * machinery so callers can show their `message` field as-is.
- */
 async function postWithPath(endpoint, repoPath, body) {
     var _a, _b;
     const settings = ServerConnection.makeSettings();
-    // `URLExt.encodeParts` encodes each path segment but preserves slashes
-    // between them — the server expects the path to look like a posix path.
+    // encodeParts keeps the slashes the server's posix-path routing expects.
     const encodedPath = repoPath.length > 0 ? URLExt.encodeParts(repoPath) : '';
     const url = URLExt.join(settings.baseUrl, GIT_NAMESPACE, encodedPath, endpoint);
     const init = {
@@ -33,7 +19,7 @@ async function postWithPath(endpoint, repoPath, body) {
             data = JSON.parse(text);
         }
         catch (_c) {
-            // Fall through into the error handling below.
+            // Non-JSON bodies still surface via the ResponseError below.
         }
     }
     if (!response.ok) {
@@ -43,17 +29,15 @@ async function postWithPath(endpoint, repoPath, body) {
     return (data !== null && data !== void 0 ? data : {});
 }
 /**
- * Fetch `git status --porcelain` for the repository the server resolves at
- * `repoPath`. When `repoPath` is the empty string, git resolves the repo
- * from the JupyterLab server's root directory.
+ * Fetch `git status --porcelain` for the repo at `repoPath` (empty string
+ * resolves from the server's root directory).
  */
 export async function status(repoPath) {
     return postWithPath('status', repoPath, {});
 }
 /**
- * Fetch a file's contents at a particular git reference. `filename` is the
- * file's path relative to the git repository root (matching the `to` field
- * of {@link status}'s response).
+ * Fetch a file's contents at a git reference; `filename` is relative to the
+ * git repository root.
  */
 export async function content(repoPath, filename, reference) {
     return postWithPath('content', repoPath, {
@@ -63,13 +47,7 @@ export async function content(repoPath, filename, reference) {
 }
 /**
  * Expand the porcelain `files` array into one entry per logical change.
- * A single porcelain row may map to two `IFileChange` rows (a file that's
- * both staged and modified again in the worktree); callers that just want
- * a flat list of all changes — without any staged-vs-unstaged grouping —
- * can use this helper.
- *
- * Provided as a manual concat rather than `Array.prototype.flatMap` so we
- * don't pin our `tsconfig.lib` to ES2019.
+ * Manual concat rather than `flatMap` so `tsconfig.lib` need not be ES2019.
  */
 export function expandStatusFiles(files) {
     const result = [];
@@ -81,16 +59,12 @@ export function expandStatusFiles(files) {
     return result;
 }
 /**
- * Translate one entry in the porcelain `files` array into the panel's
- * preferred shape. A single porcelain entry may represent up to two changes
- * (one in the index, one in the worktree); we emit one {@link IFileChange}
- * per non-empty side, so a "modified-staged-and-then-modified-again" file
- * shows up twice in the panel — once under "Staged Changes" and once under
- * "Changes" — matching the layout the user sees in VS Code.
+ * Map one porcelain entry to up to two {@link IFileChange} rows — one per
+ * non-empty index/worktree side — so a staged-then-modified-again file
+ * appears under both groups, as in VS Code.
  */
 function porcelainToFileChanges(file) {
     const result = [];
-    // Untracked files are reported with `??` and only appear under "Changes".
     if (file.x === '?' && file.y === '?') {
         return [
             {

package/lib/git/askRequest.d.ts

@@ -4,14 +4,10 @@ import type { IAskAgentRequest } from '../askAgent/tokens';
 import type { IXtralabDiffModel } from './diffWidget';
 /**
  * Build the ask-agent request for a line range selected in a git diff.
- *
- * The range's `side` decides which file version the line numbers (and the
- * embedded snippet) refer to: `deletions` reads from the reference text,
- * anything else — including the sideless context rows of a unified diff,
- * whose gutter shows new-side numbers — reads from the challenger text. A
- * gutter drag that crosses the two split columns has endpoints in different
- * line-number spaces, so it is described textually instead of as a numeric
- * range.
+ * `deletions` ranges index the reference text; other ranges — including
+ * sideless unified context rows, whose gutter shows new-side numbers —
+ * index the challenger. A drag across the two split columns mixes
+ * line-number spaces, so it is described textually instead of numerically.
  */
 export declare function buildDiffAskRequest(options: {
     model: IXtralabDiffModel;

package/lib/git/askRequest.js

@@ -1,9 +1,7 @@
 import { Git } from '@jupyterlab/git';
 /**
- * Agent-facing name of a diff content source: the special refs get plain
- * words, a git ref string is used verbatim, anything else falls back to the
- * side name. English on purpose — this ends up in the agent prompt, not in
- * the UI.
+ * Agent-facing name of a diff content source. English on purpose — this
+ * ends up in the agent prompt, not in the UI.
  */
 function describeSource(source, fallback) {
     if (source === Git.Diff.SpecialRef.WORKING) {
@@ -23,9 +21,6 @@ function describeSource(source, fallback) {
 function sideName(side) {
     return side === 'deletions' ? 'old side' : 'new side';
 }
-/**
- * Extract lines `startLine`–`endLine` (1-indexed, inclusive) from `text`.
- */
 function sliceLines(text, startLine, endLine) {
     return text
         .split('\n')
@@ -34,14 +29,10 @@ function sliceLines(text, startLine, endLine) {
 }
 /**
  * Build the ask-agent request for a line range selected in a git diff.
- *
- * The range's `side` decides which file version the line numbers (and the
- * embedded snippet) refer to: `deletions` reads from the reference text,
- * anything else — including the sideless context rows of a unified diff,
- * whose gutter shows new-side numbers — reads from the challenger text. A
- * gutter drag that crosses the two split columns has endpoints in different
- * line-number spaces, so it is described textually instead of as a numeric
- * range.
+ * `deletions` ranges index the reference text; other ranges — including
+ * sideless unified context rows, whose gutter shows new-side numbers —
+ * index the challenger. A drag across the two split columns mixes
+ * line-number spaces, so it is described textually instead of numerically.
  */
 export function buildDiffAskRequest(options) {
     var _a, _b, _c;
@@ -75,14 +66,9 @@ export function buildDiffAskRequest(options) {
             ...base,
             startLine,
             endLine,
-            // Only new-side lines of a working-tree diff index the file on disk;
-            // old-side and historical line numbers must not be used to highlight
-            // the working file.
             linesInWorkingFile: !isOld && model.challenger.source === Git.Diff.SpecialRef.WORKING,
             text: sliceLines(isOld ? oldText : newText, startLine, endLine),
             location: `the ${sideName(startSide)} (${ref}) of the current git diff`,
-            // New-side lines read as the file's current content, so only old-side
-            // ranges need a clarifying tag in the popup header.
             ...(isOld ? { note: trans.__('old version') } : {})
         },
         anchor