xtralab 0.15.0 → 0.15.1

package/lib/fileBrowser/widget.js

@@ -68,65 +68,116 @@ export class XtralabFileBrowser extends Widget {
         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;
@@ -134,24 +185,45 @@ 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 [];
@@ -173,6 +245,10 @@ export class XtralabFileBrowser extends Widget {
             ]
             : [];
     }
+    /**
+     * 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;
@@ -188,6 +264,9 @@ export class XtralabFileBrowser extends Widget {
         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);
@@ -228,6 +307,10 @@ export class XtralabFileBrowser extends 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;
@@ -262,14 +345,16 @@ export class XtralabFileBrowser extends Widget {
     }
 }
 /**
- * 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, 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

package/lib/git/commands.d.ts

@@ -17,15 +17,24 @@ export declare namespace CommandIDs {
  * Argument shapes used by {@link CommandIDs.openDiff}.
  */
 export declare namespace CommandArguments {
+    /**
+     * The arguments for the open-diff command.
+     */
     interface IOpenDiff {
+        /**
+         * The server-relative path of the repository containing the change.
+         */
         repoPath: string;
+        /**
+         * The file change to show.
+         */
         change: IFileChange;
+        /**
+         * Whether to open the diff as a pinned tab instead of the shared preview.
+         */
         pin?: boolean;
     }
 }
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export declare const PREVIEW_DIFF_WIDGET_ID = "xtralab:diff:preview";
 /**
  * Deterministic widget id for a pinned file/group pair.
@@ -36,18 +45,42 @@ export declare function pinnedDiffWidgetId(change: IFileChange): string;
  */
 export declare class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     constructor(options: MainAreaWidget.IOptions<XtralabDiffWidget>, change: IFileChange, pinned: boolean, trans: TranslationBundle);
+    /**
+     * The file change currently displayed.
+     */
     get change(): IFileChange;
+    /**
+     * Whether the widget is pinned rather than the shared preview.
+     */
     get pinned(): boolean;
+    /**
+     * Pin the widget; a no-op when already pinned.
+     */
     pin(): void;
+    /**
+     * A signal emitted when the widget becomes pinned.
+     */
     get pinnedChanged(): ISignal<this, boolean>;
+    /**
+     * Display a new file change and update the tab title, caption, and icon.
+     */
     setChange(repoPath: string, change: IFileChange): void;
     private _change;
     private _pinned;
     private _trans;
     private _pinnedChanged;
 }
+/**
+ * The options for {@link registerGitCommands}.
+ */
 interface IRegisterGitCommandsOptions {
+    /**
+     * The JupyterLab application, providing the commands registry and shell.
+     */
     app: JupyterFrontEnd;
+    /**
+     * Theme manager the diff views follow; may be `null`.
+     */
     themeManager: IThemeManager | null;
     /**
      * Contents manager used to write hunk-discard results.
@@ -73,11 +106,13 @@ interface IRegisterGitCommandsOptions {
      * Look up an already-open diff widget for a file change.
      */
     findDiff(change: IFileChange, pin?: boolean): DiffMainAreaWidget | undefined;
+    /**
+     * Callback invoked when a preview diff widget becomes pinned.
+     */
     onPinned(widget: DiffMainAreaWidget): void;
 }
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export declare function registerGitCommands(options: IRegisterGitCommandsOptions): void;
 export {};

package/lib/git/commands.js

@@ -11,9 +11,6 @@ export var CommandIDs;
 (function (CommandIDs) {
     CommandIDs.openDiff = 'xtralab:git:open-diff';
 })(CommandIDs || (CommandIDs = {}));
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
 /**
  * Deterministic widget id for a pinned file/group pair.
@@ -38,12 +35,21 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this._pinned = pinned;
         this._trans = trans;
     }
+    /**
+     * The file change currently displayed.
+     */
     get change() {
         return this._change;
     }
+    /**
+     * Whether the widget is pinned rather than the shared preview.
+     */
     get pinned() {
         return this._pinned;
     }
+    /**
+     * Pin the widget; a no-op when already pinned.
+     */
     pin() {
         if (this._pinned) {
             return;
@@ -51,9 +57,15 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this._pinned = true;
         this._pinnedChanged.emit(true);
     }
+    /**
+     * A signal emitted when the widget becomes pinned.
+     */
     get pinnedChanged() {
         return this._pinnedChanged;
     }
+    /**
+     * Display a new file change and update the tab title, caption, and icon.
+     */
     setChange(repoPath, change) {
         this._change = change;
         this.content.setModel(fileChangeToDiffModel(repoPath, change));
@@ -62,9 +74,6 @@ export class DiffMainAreaWidget extends MainAreaWidget {
         this.title.icon = getTreeIcon(change.path);
     }
 }
-/**
- * Build the launcher's diff tab around the shared diff widget.
- */
 function createDiffWidget(options) {
     var _a;
     const { repoPath, change, themeManager, contentsManager, rendermime, askAgent, trans } = options;
@@ -89,7 +98,6 @@ function createDiffWidget(options) {
     }
     widget.toolbar.addItem('pin', pinButton);
     addDiffToolbarItems(widget.toolbar, content);
-    // Keep chrome visible only while there is a relevant toolbar control.
     const syncToolbarVisibility = () => {
         if (widget.isDisposed) {
             return;
@@ -115,7 +123,6 @@ function createDiffWidget(options) {
         }
         syncToolbarVisibility();
     };
-    // Auto-close once a discard leaves nothing to show.
     const onEmptied = () => {
         if (!widget.isDisposed) {
             widget.close();
@@ -135,8 +142,7 @@ function createDiffWidget(options) {
     return widget;
 }
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export function registerGitCommands(options) {
     const { app, themeManager, contentsManager, rendermime, askAgent, trans, trackDiff, findDiff, onPinned } = options;

package/lib/git/diffModel.js

@@ -40,6 +40,10 @@ function referenceSource(ref) {
 class FileChangeDiffModel {
     constructor(repoPath, change) {
         var _a;
+        /**
+         * A signal emitted when the reference or challenger changes; this static
+         * model never emits it.
+         */
         this.changed = new Signal(this);
         const { oldRef, newRef } = resolveReferences(change);
         // Renames compare the new path against the old path's previous content.