xtralab 0.15.0 → 0.15.2

package/lib/commandBar/index.js

@@ -5,23 +5,11 @@ import { CommandRegistry } from '@lumino/commands';
 import { Widget } from '@lumino/widgets';
 import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
 const PLUGIN_ID = 'xtralab:command-bar';
-/**
- * Factory name of JupyterLab's settings-driven top bar toolbar (`#jp-top-bar`,
- * built by `@jupyterlab/application-extension:top-bar`).
- */
 const TOPBAR_FACTORY = 'TopBar';
-/**
- * Name of the pill item within that toolbar. Its placement is declared under
- * `jupyter.lab.toolbars` in this plugin's settings schema
- * (schema/command-bar.json): the core toolbar ships a spacer at rank 50, so
- * the pill's higher rank lands it at the trailing end of the toolbar, next to
- * the right-sidebar toggle button.
- */
 const ITEM_NAME = 'omnibox';
 /**
- * A search-bar-styled launcher pill. It holds no text input of its own:
- * clicking it (or pressing Enter/Space while it is focused) runs `onActivate`,
- * which opens the omnibox.
+ * A search-bar-styled launcher pill with no input of its own: activating it
+ * runs `onActivate`, which opens the omnibox.
  */
 class CommandBar extends Widget {
     constructor(options) {
@@ -31,27 +19,35 @@ class CommandBar extends Widget {
         this.addClass('jp-xtralab-CommandBar');
         this._onActivate = options.onActivate;
     }
+    /**
+     * Handle the DOM events for the command bar.
+     */
     handleEvent(event) {
         if (event.type === 'click') {
             this._onActivate();
         }
     }
+    /**
+     * A message handler invoked on an `'after-attach'` message.
+     */
     onAfterAttach() {
-        // The click bubbles from the inner pill button up to the root node
-        // listened on here; keyboard Enter/Space on the focused button raises the
-        // same synthetic click.
+        // Keyboard Enter/Space on the focused button raises the same synthetic click.
         this.node.addEventListener('click', this);
     }
+    /**
+     * A message handler invoked on a `'before-detach'` message.
+     */
     onBeforeDetach() {
         this.node.removeEventListener('click', this);
     }
 }
 (function (CommandBar) {
+    /**
+     * Create the DOM node for a command bar.
+     */
     function createNode(label, caption, shortcut) {
-        // The root is a plain wrapper: as a toolbar item it receives the core
-        // `.jp-Toolbar > .jp-Toolbar-item` sizing (full height, centered flex),
-        // which would otherwise stretch the pill itself; the button inside keeps
-        // its own compact pill height.
+        // Plain wrapper: the core `.jp-Toolbar-item` sizing would otherwise
+        // stretch the pill itself.
         const wrapper = document.createElement('div');
         const button = document.createElement('button');
         button.type = 'button';
@@ -71,7 +67,6 @@ class CommandBar extends Widget {
             const hint = document.createElement('span');
             hint.className = 'jp-xtralab-CommandBar-shortcut';
             hint.textContent = shortcut;
-            // Decorative: the button's aria-label already names the action.
             hint.setAttribute('aria-hidden', 'true');
             button.appendChild(hint);
         }
@@ -81,19 +76,10 @@ class CommandBar extends Widget {
     CommandBar.createNode = createNode;
 })(CommandBar || (CommandBar = {}));
 /**
- * Contribute a search-bar-styled command bar to JupyterLab's top bar toolbar.
- * Clicking it opens the omnibox — a launcher overlay that fuzzy-searches files
- * and commands and routes a typed prompt to an agent.
- *
- * The pill is a regular settings-driven toolbar item: this plugin registers a
- * widget factory for it on the `IToolbarWidgetRegistry` and declares its rank
- * in schema/command-bar.json, so users can move or disable it from the Top
- * Bar settings like any other toolbar item.
- *
- * The factory is only registered when the omnibox is available — the
- * `IOmnibox` token is provided by `xtralab:omnibox` — so the pill never
- * appears with nothing to open (without a factory, the toolbar item resolves
- * to an empty command button that renders nothing).
+ * Contribute a search-bar-styled pill to the top bar toolbar that opens the
+ * omnibox. It is a settings-driven toolbar item (factory here, rank in
+ * schema/command-bar.json) registered only when `IOmnibox` is provided —
+ * without a factory the item resolves to an empty button that renders nothing.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -107,10 +93,6 @@ const plugin = {
         }
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
         toolbarRegistry.addFactory(TOPBAR_FACTORY, ITEM_NAME, () => {
-            // Show the omnibox's keyboard shortcut as a hint in the pill, derived
-            // from the live binding (registered by xtralab:omnibox, which activates
-            // first as the IOmnibox provider) so it stays correct and uses the
-            // platform's modifier symbols. Empty when no binding is registered.
             const binding = app.commands.keyBindings.find(keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND);
             const shortcut = binding
                 ? CommandRegistry.formatKeystroke(binding.keys)

package/lib/customPanel/index.js

@@ -16,19 +16,34 @@ class CustomPanel extends SidePanel {
         this.title.caption = options.trans.__('Custom Panel');
         this.addClass('jp-xtralab-CustomPanel');
     }
+    /**
+     * The accordion panel hosting the sections.
+     */
     get accordionPanel() {
         return this.content;
     }
+    /**
+     * The section widgets currently hosted by the panel.
+     */
     get sections() {
         return this.content.widgets;
     }
+    /**
+     * A signal emitted with the new count when the number of sections changes.
+     */
     get sectionCountChanged() {
         return this._sectionCountChanged;
     }
+    /**
+     * Add a section widget to the panel.
+     */
     addSection(widget) {
         this.addWidget(widget);
         this._sectionCountChanged.emit(this.content.widgets.length);
     }
+    /**
+     * Remove a section widget from the panel, if it is hosted here.
+     */
     removeSectionWidget(widget) {
         if (widget.parent !== this.content) {
             return;

package/lib/editorBreadcrumbs/index.d.ts

@@ -1,11 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
- * segment is clickable: clicking dispatches `xtralab:reveal-path` so
- * any plugin that listens (today, the file browser) can surface the
- * underlying folder or file. The breadcrumbs plugin therefore does not
- * import the file browser at all — the JupyterLab command registry is
- * the only seam between them.
+ * Adds a clickable path breadcrumb to text editor toolbars. Clicks dispatch
+ * `xtralab:reveal-path`; the command registry is the only seam with the file
+ * browser.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/editorBreadcrumbs/index.js

@@ -4,11 +4,18 @@ import { EditorBreadcrumbs } from './widget';
 const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
 const EDITOR_FACTORY = 'Editor';
 const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
+/**
+ * A widget extension that adds an `EditorBreadcrumbs` item to the toolbar of
+ * each new editor widget.
+ */
 class EditorBreadcrumbsExtension {
     constructor(commands, trans) {
         this._commands = commands;
         this._trans = trans;
     }
+    /**
+     * Create the breadcrumbs toolbar item for a new editor widget.
+     */
     createNew(widget, context) {
         const breadcrumbs = new EditorBreadcrumbs({
             context,
@@ -26,12 +33,9 @@ class EditorBreadcrumbsExtension {
     }
 }
 /**
- * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
- * segment is clickable: clicking dispatches `xtralab:reveal-path` so
- * any plugin that listens (today, the file browser) can surface the
- * underlying folder or file. The breadcrumbs plugin therefore does not
- * import the file browser at all — the JupyterLab command registry is
- * the only seam between them.
+ * Adds a clickable path breadcrumb to text editor toolbars. Clicks dispatch
+ * `xtralab:reveal-path`; the command registry is the only seam with the file
+ * browser.
  */
 const plugin = {
     id: PLUGIN_ID,

package/lib/editorBreadcrumbs/widget.d.ts

@@ -2,9 +2,21 @@ import type { DocumentRegistry } from '@jupyterlab/docregistry';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import type { CommandRegistry } from '@lumino/commands';
 import { Widget } from '@lumino/widgets';
+/**
+ * The options used to create an `EditorBreadcrumbs` widget.
+ */
 interface IEditorBreadcrumbsOptions {
+    /**
+     * The document context whose path is rendered.
+     */
     context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+    /**
+     * The command registry used to dispatch the reveal command.
+     */
     commands: CommandRegistry;
+    /**
+     * The application translation bundle.
+     */
     trans: TranslationBundle;
 }
 /**
@@ -13,15 +25,16 @@ interface IEditorBreadcrumbsOptions {
  */
 export declare class EditorBreadcrumbs extends Widget {
     constructor(options: IEditorBreadcrumbsOptions);
+    /**
+     * Dispose of the resources held by the widget.
+     */
     dispose(): void;
     private _onPathChanged;
     private _render;
     private _createRootCrumb;
     /**
-     * Bind click and keyboard activation on a crumb element to the
-     * shared reveal command. Dispatch is best-effort: a failure to
-     * resolve or execute the command is logged but never thrown into
-     * the editor's toolbar.
+     * Bind click and keyboard activation on a crumb to the reveal command;
+     * dispatch failures are logged, never thrown into the toolbar.
      */
     private _attachReveal;
     private _createSeparator;

package/lib/editorBreadcrumbs/widget.js

@@ -10,9 +10,7 @@ const ITEM_CLASS = 'jp-BreadCrumbs-item';
 const CURRENT_ITEM_CLASS = 'jp-mod-current';
 const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
 /**
- * Command dispatched when the user clicks a breadcrumb segment.
- * Registered by the file browser plugin; the breadcrumbs only know
- * the name so they stay decoupled from the file browser internals.
+ * Registered by the file browser plugin; only the name is shared here.
  */
 const REVEAL_COMMAND = 'xtralab:reveal-path';
 /**
@@ -26,9 +24,8 @@ export class EditorBreadcrumbs extends Widget {
         this._commands = options.commands;
         this._trans = options.trans;
         this.addClass(EDITOR_BREADCRUMBS_CLASS);
-        // The breadcrumbs stretch to fill the toolbar, so ReactiveToolbar's
-        // overflow math must count them as a spacer (2px) — measured at their
-        // stretched clientWidth they would evict every item into the popup.
+        // ReactiveToolbar must count the stretched breadcrumbs as a spacer (2px);
+        // measured at clientWidth they would evict every item into the popup.
         this.addClass(TOOLBAR_SPACER_CLASS);
         this.node.setAttribute('aria-label', this._trans.__('Editor file path'));
         this._container = document.createElement('span');
@@ -40,6 +37,9 @@ export class EditorBreadcrumbs extends Widget {
         this._context.pathChanged.connect(this._onPathChanged, this);
         this._render();
     }
+    /**
+     * Dispose of the resources held by the widget.
+     */
     dispose() {
         if (this.isDisposed) {
             return;
@@ -62,9 +62,7 @@ export class EditorBreadcrumbs extends Widget {
         parts.forEach((part, index) => {
             const isLast = index === parts.length - 1;
             const subPath = parts.slice(0, index + 1).join('/');
-            // Canonical `@pierre/trees` paths: directories carry a trailing
-            // slash, files do not. Every part except the last names a folder
-            // along the way to the open file.
+            // Canonical @pierre/trees paths: directories carry a trailing slash.
             const canonical = isLast ? subPath : `${subPath}/`;
             const item = document.createElement('span');
             item.className = ITEM_CLASS;
@@ -94,18 +92,14 @@ export class EditorBreadcrumbs extends Widget {
         item.dataset.path = '/';
         item.tabIndex = 0;
         item.setAttribute('role', 'button');
-        // Empty canonical path: the reveal command treats this as the
-        // workspace-root gesture — surface the file browser, clear its
-        // selection, and scroll back to the top. The tree has no row for
-        // the workspace root itself.
+        // Empty path is the workspace-root gesture; the tree has no row for
+        // the root itself.
         this._attachReveal(item, '');
         return item;
     }
     /**
-     * Bind click and keyboard activation on a crumb element to the
-     * shared reveal command. Dispatch is best-effort: a failure to
-     * resolve or execute the command is logged but never thrown into
-     * the editor's toolbar.
+     * Bind click and keyboard activation on a crumb to the reveal command;
+     * dispatch failures are logged, never thrown into the toolbar.
      */
     _attachReveal(element, canonicalPath) {
         const fire = (event) => {

package/lib/editorIndent/index.d.ts

@@ -1,17 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Sniff each opened document's leading whitespace and configure CodeMirror's
- * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
- * indent setting, which means TypeScript files written with 4-space indent and
- * Python files written with 2-space indent both look wrong in the same editor;
- * detecting from the file's own content sidesteps that without forcing every
- * project to share the same convention.
- *
- * Detection runs at editor-construction time and again on the first content
- * change — that second pass exists because JupyterLab's collaborative document
- * loader can settle the file body into the shared model after the editor view
- * already exists, in which case the factory would otherwise have only seen an
- * empty string.
+ * Sniff each document's indentation and configure CodeMirror's `indentUnit` /
+ * `tabSize` to match, since JupyterLab only has one global indent setting.
+ * Detection reruns on the first content change: the collaborative loader can
+ * settle the file body after the editor view exists, so the factory may see ''.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/editorIndent/index.js

@@ -5,10 +5,8 @@ import { ViewPlugin } from '@codemirror/view';
 import detectIndent from 'detect-indent';
 const PLUGIN_ID = 'xtralab:editor-indent';
 /**
- * Mime types whose newly-created (or too-short-to-detect) files should default
- * to a 2-space indent. Matches Prettier's defaults for web languages; mime
- * types not listed here inherit whatever the user has set in JupyterLab.
- * Covers .ts/.tsx/.jsx/.js variants registered by `@jupyterlab/codemirror`.
+ * 2-space fallback for new or undetectable files, matching Prettier's
+ * web-language defaults; unlisted mime types keep the user's setting.
  */
 const FALLBACK_INDENT_BY_MIME = {
     'application/ecmascript': 2,
@@ -28,10 +26,6 @@ const FALLBACK_INDENT_BY_MIME = {
     'text/x-yaml': 2,
     'text/yaml': 2
 };
-/**
- * Run `detect-indent` against the file's content and convert its result into
- * something we can hand to CodeMirror.
- */
 function detectFromContent(text) {
     if (text.length === 0) {
         return null;
@@ -59,27 +53,18 @@ function resolveIndent(text, mimeType) {
     return { unit: ' '.repeat(fallback), width: fallback };
 }
 function buildExtension(resolved) {
-    // `Prec.highest` keeps these values first in their respective facets so
-    // they beat both `defaultConfig` and per-editor `editorConfig.indentUnit`,
-    // both of which JupyterLab registers at default precedence.
+    // `Prec.highest` beats both `defaultConfig` and per-editor
+    // `editorConfig.indentUnit`, which JupyterLab registers at default precedence.
     return Prec.highest([
         indentUnit.of(resolved.unit),
         EditorState.tabSize.of(resolved.width)
     ]);
 }
 /**
- * Sniff each opened document's leading whitespace and configure CodeMirror's
- * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
- * indent setting, which means TypeScript files written with 4-space indent and
- * Python files written with 2-space indent both look wrong in the same editor;
- * detecting from the file's own content sidesteps that without forcing every
- * project to share the same convention.
- *
- * Detection runs at editor-construction time and again on the first content
- * change — that second pass exists because JupyterLab's collaborative document
- * loader can settle the file body into the shared model after the editor view
- * already exists, in which case the factory would otherwise have only seen an
- * empty string.
+ * Sniff each document's indentation and configure CodeMirror's `indentUnit` /
+ * `tabSize` to match, since JupyterLab only has one global indent setting.
+ * Detection reruns on the first content change: the collaborative loader can
+ * settle the file body after the editor view exists, so the factory may see ''.
  */
 const plugin = {
     id: PLUGIN_ID,

package/lib/fileBrowser/commands.d.ts

@@ -4,15 +4,14 @@ import { IDocumentManager } from '@jupyterlab/docmanager';
 import { ITranslator } from '@jupyterlab/translation';
 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.
+ * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
+ * reusing the `filebrowser:` ids: the core handlers resolve their target via
+ * `IFileBrowserFactory.tracker`, which never sees this widget.
  */
 export declare namespace CommandIDs {
     const open = "xtralab:open";
     const openBrowserTab = "xtralab:open-browser-tab";
+    const openGitDiff = "xtralab:open-git-diff";
     const rename = "xtralab:rename";
     const del = "xtralab:delete";
     const duplicate = "xtralab:duplicate";
@@ -26,27 +25,40 @@ export declare namespace CommandIDs {
     const revealPath = "xtralab:reveal-path";
     const revealInFileTree = "xtralab:reveal-in-file-tree";
 }
+/**
+ * Options for registering the xtralab file browser commands.
+ */
 interface IRegisterCommandsOptions {
+    /**
+     * The JupyterLab application the commands are registered on.
+     */
     app: JupyterFrontEnd;
+    /**
+     * The file browser widget the commands act on.
+     */
     browser: IXtralabFileBrowser;
+    /**
+     * The document manager used to resolve the current widget's file path.
+     */
     docManager: IDocumentManager;
+    /**
+     * The command palette the commands are added to, or `null` when unavailable.
+     */
     palette: ICommandPalette | null;
+    /**
+     * The translator for user-facing strings; `null` falls back to English.
+     */
     translator: ITranslator | null;
 }
 /**
- * Register every xtralab command on the application command registry, attach
- * the items to the application context menu, and wire up the dynamic
- * "Open With" submenu populator.
- *
- * @returns A function that detaches the menu items and signal listener.
- *   The commands themselves are owned by the registry for the lifetime of
- *   the plugin.
+ * Register the xtralab commands, context-menu wiring, and the dynamic
+ * "Open With" populator. Returns a detach function; the commands themselves
+ * stay owned by the registry.
  */
 export 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.
+ * Toolbar item names, distinct from {@link CommandIDs}: the toolbar API
+ * uses opaque names rather than commands.
  */
 export declare namespace ToolbarNames {
     const newLauncher = "new-launcher";
@@ -56,10 +68,8 @@ export declare namespace ToolbarNames {
     const toggleFileFilter = "toggle-file-filter";
 }
 /**
- * Populate the file browser's toolbar with the buttons that mirror the
- * default JupyterLab file browser: a "+" launcher button, a new-folder
- * button, a refresh button, a collapse-all button, and the file filter
- * toggle.
+ * Populate the toolbar with the buttons that mirror the default JupyterLab
+ * file browser.
  */
 export declare function populateToolbar(opts: {
     app: JupyterFrontEnd;