xtralab 0.14.1 → 0.15.1

package/src/omnibox/widget.tsx

@@ -11,21 +11,15 @@ import { computeSections, IOmniboxItem } from './model';
 import { loadWorkspaceFiles } from './files';
 import type { OmniboxRecents } from './recents';
 
-/**
- * DOM id of the results listbox, referenced by the input's `aria-controls`.
- */
 const LIST_ID = 'jp-xtralab-Omnibox-list';
 
-/**
- * Stable DOM id for the result row at `index`, for `aria-activedescendant`.
- */
 function optionId(index: number): string {
   return `jp-xtralab-Omnibox-option-${index}`;
 }
 
 /**
  * Render `text` with the fuzzy-matched characters at `indices` wrapped in a
- * highlight span, leaving the rest as plain text.
+ * highlight span.
  */
 function renderHighlight(
   text: string,
@@ -125,13 +119,10 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
   );
   const hasResults = flat.length > 0;
 
-  // Reset the highlighted row whenever the result set changes, and keep the
-  // index in range when results shrink.
   React.useEffect(() => {
     setActive(current => (current < flat.length ? current : 0));
   }, [flat]);
 
-  // Keep the highlighted row scrolled into view as it moves.
   React.useEffect(() => {
     listRef.current
       ?.querySelector('.jp-mod-active')
@@ -139,8 +130,8 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
   }, [active, flat]);
 
   const dismiss = React.useCallback(() => {
-    // Defer so unmounting this React root (via onClose) never happens
-    // synchronously inside the event handler that triggered it.
+    // Defer so unmounting this React root never happens synchronously inside
+    // the event handler that triggered it.
     window.setTimeout(onClose, 0);
   }, [onClose]);
 
@@ -307,10 +298,8 @@ function OmniboxComponent(props: OmniboxWidget.IOptions): JSX.Element {
 }
 
 /**
- * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
- * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
- * theme CSS variables resolve outside the shell, and its own `jp-xtralab-Omnibox`
- * class for the overlay/panel styling (style/omnibox.css).
+ * The omnibox overlay widget, attached to `document.body`; `jp-ThemedContainer`
+ * makes JupyterLab's theme CSS variables resolve outside the shell.
  */
 export class OmniboxWidget extends ReactWidget {
   constructor(options: OmniboxWidget.IOptions) {
@@ -321,6 +310,9 @@ export class OmniboxWidget extends ReactWidget {
     this.addClass('jp-ThemedContainer');
   }
 
+  /**
+   * Render the omnibox overlay content.
+   */
   render(): JSX.Element {
     return <OmniboxComponent {...this._options} />;
   }
@@ -328,20 +320,23 @@ export class OmniboxWidget extends ReactWidget {
   private _options: OmniboxWidget.IOptions;
 }
 
-/**
- * A namespace for `OmniboxWidget` statics.
- */
 export namespace OmniboxWidget {
   /**
    * Construction options for {@link OmniboxWidget}.
    */
   export interface IOptions {
+    /**
+     * The command registry used to look up and execute commands.
+     */
     commands: CommandRegistry;
     /**
      * Snapshot of the command palette's items, read once when the overlay
      * opens; empty when the palette isn't available.
      */
     paletteItems: ReadonlyArray<CommandPalette.IItem>;
+    /**
+     * The document registry used to pick file icons.
+     */
     docRegistry: DocumentRegistry;
     /**
      * Snapshot of the available agents, read once when the overlay opens.

package/src/searchReplace/index.ts

@@ -11,34 +11,16 @@ const PLUGIN_ID = 'xtralab:search-replace';
 const COMMAND_ID = 'xtralab:activate-search-replace';
 
 /**
- * Widget id of the panel contributed by `jupyterlab-search-replace`. The
- * extension adds it to the left sidebar but registers no command of its own,
- * so there is nothing to bind a shortcut to out of the box — this plugin adds
- * the missing command.
+ * Widget id of the `jupyterlab-search-replace` left-sidebar panel; the
+ * extension registers no command of its own to bind a shortcut to.
  */
 const SEARCH_REPLACE_WIDGET_ID = 'jp-search-replace';
 
 /**
- * Bind Accel+Shift+F (Cmd+Shift+F on macOS, Ctrl+Shift+F elsewhere) to the
- * project-wide Search and Replace panel, matching the equivalent shortcut in
- * editors like VS Code.
- *
- * Two pieces are needed because that chord is already taken: JupyterLab core
- * binds Accel+Shift+F to `filebrowser:toggle-main`.
- *
- * 1. The chord is freed declaratively. `SettingRegistry.reconcileShortcuts`
- *    keys collisions and disables on (keys, selector) — not on command — so the
- *    `@jupyterlab/shortcuts-extension:shortcuts` override in
- *    `default_setting_overrides.d/00-xtralab.json` disables the file-browser
- *    binding. The file browser stays reachable from its sidebar tab and the
- *    View menu; only the keyboard shortcut moves.
- *
- * 2. The new binding is added imperatively below rather than as another shipped
- *    default. A `disabled` default and a re-binding default land on the same
- *    (keys, selector) slot, and the disable suppresses every default on that
- *    slot — including the re-binding. `commands.addKeyBinding` runs outside the
- *    reconcile pass, so it is unaffected and wins cleanly once the file-browser
- *    binding is gone.
+ * Bind Accel+Shift+F to the Search and Replace panel (VS Code parity). Core
+ * binds the chord to `filebrowser:toggle-main`; a `default_setting_overrides.d`
+ * override disables it. The re-binding is imperative: `reconcileShortcuts` keys
+ * on (keys, selector), so the disable would suppress a shipped default too.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -60,9 +42,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
       label: trans.__('Search and Replace'),
       caption: trans.__('Show the Search and Replace panel'),
       execute: () => {
-        // `activateById` expands the left sidebar when collapsed, selects the
-        // tab, and the widget focuses its search input from `onAfterShow`, so
-        // the user can start typing a query immediately. It no-ops if
+        // The widget focuses its search input from `onAfterShow`; no-ops if
         // `jupyterlab-search-replace` is unavailable.
         labShell.activateById(SEARCH_REPLACE_WIDGET_ID);
       }

package/src/showOutput/index.ts

@@ -12,24 +12,12 @@ import { coerceData } from '../mimeData';
 
 const PLUGIN_ID = 'xtralab:show-output';
 
-/**
- * Render arbitrary rich content into a panel, with no notebook and no kernel.
- */
 const SHOW_COMMAND = 'xtralab:show';
 
 /**
- * Contribute `xtralab:show`: render a single MIME bundle into a main-area
- * panel using the application's render-mime registry.
- *
- * This is the kernel-free counterpart to running a notebook. A coding agent
- * generates the content itself (a Vega-Lite spec, a Markdown explainer, an
- * HTML fragment, an SVG, a base64 image) and hands it to this command, which
- * renders it with the same renderers JupyterLab uses for cell output and docks
- * the result beside the code. Nothing is written to disk and no kernel is
- * required, so it works even where the kernel has no plotting libraries.
- *
- * Repeated calls with the same `id` reuse one panel, so a walkthrough can
- * refresh the view in place instead of piling up tabs.
+ * Contributes `xtralab:show`: render a single MIME bundle into a panel with
+ * the same renderers JupyterLab uses for cell output — no kernel, no file on
+ * disk. Repeated calls with the same `id` reuse one panel.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -48,7 +36,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const { commands } = app;
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
-    // One reusable panel per `id`, so repeated shows refresh in place.
     const panels = new Map<string, Panel>();
 
     commands.addCommand(SHOW_COMMAND, {
@@ -120,9 +107,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
 
         const model = rendermime.createModel({ data: bundle, trusted: true });
         const renderer = rendermime.createRenderer(chosen);
-        // A scrollable Panel, not a MainAreaWidget: MainAreaWidget does not lay
-        // out its content in the side area, and the panel needs to scroll when
-        // the content is taller than it (style/showOutput.css).
+        // Not a MainAreaWidget: it does not lay out its content in the side
+        // area; the panel scrolls via style/showOutput.css.
         const widget = new Panel();
         widget.addClass('jp-xtralab-ShowPanel');
         widget.id = `xtralab-show-${id}`;
@@ -130,7 +116,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
         widget.title.closable = true;
         widget.addWidget(renderer);
 
-        // Replace any existing panel with this id so shows refresh in place.
         const existing = panels.get(id);
         if (existing && !existing.isDisposed) {
           existing.dispose();
@@ -143,8 +128,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
         });
 
         // Attach before rendering so renderers that need layout (Vega) size
-        // correctly. Default to the side area so the editor keeps full width;
-        // only split the document area when `area` is "main".
+        // correctly.
         if (area === 'main') {
           labShell.add(widget, 'main', {
             mode,

package/src/sidebar/index.ts

@@ -10,21 +10,61 @@ import type { Widget } from '@lumino/widgets';
 const PLUGIN_ID = 'xtralab:sidebar';
 
 /**
- * Each entry pairs an upstream sidebar widget id with the rank it was
- * originally added at. The ranks come from the upstream extensions —
- * `filebrowser-extension` adds the default browser at rank 100 and
- * `running-extension` adds the running panel at rank 200 — and we reuse
- * them when re-adding so the tab lands back in its usual position.
+ * `rank` is the fallback used when re-adding a hidden tab; the shipped
+ * `layout` setting normally wins because `LabShell.add` merges its
+ * per-widget options over the ones passed in.
  */
 interface ITarget {
+  /**
+   * The shell widget id of the sidebar tab.
+   */
   id: string;
+  /**
+   * The sidebar rank used when re-adding the hidden tab.
+   */
   rank: number;
-  settingKey: 'showDefaultFileBrowser' | 'showRunningSessions';
+  /**
+   * The boolean plugin setting controlling the tab's visibility.
+   */
+  settingKey:
+    | 'showTerminals'
+    | 'showFileBrowser'
+    | 'showGitPanel'
+    | 'showDefaultFileBrowser'
+    | 'showRunningSessions'
+    | 'showSearchReplace';
+  /**
+   * The id of the toggle command registered for the tab.
+   */
   command: string;
+  /**
+   * The localized label of the toggle command.
+   */
   label: (trans: ReturnType<ITranslator['load']>) => string;
 }
 
 const TARGETS: ITarget[] = [
+  {
+    id: 'xtralab-running-terminals',
+    rank: 1,
+    settingKey: 'showTerminals',
+    command: 'xtralab:toggle-terminals',
+    label: trans => trans.__('Terminals')
+  },
+  {
+    id: 'xtralab:file-browser',
+    rank: 2,
+    settingKey: 'showFileBrowser',
+    command: 'xtralab:toggle-file-browser',
+    label: trans => trans.__('File Browser')
+  },
+  {
+    id: 'jp-git-sessions',
+    rank: 200,
+    settingKey: 'showGitPanel',
+    command: 'xtralab:toggle-git-panel',
+    label: trans => trans.__('Git')
+  },
   {
     id: 'filebrowser',
     rank: 100,
@@ -38,28 +78,26 @@ const TARGETS: ITarget[] = [
     settingKey: 'showRunningSessions',
     command: 'xtralab:toggle-running-sessions',
     label: trans => trans.__('Running Terminals and Kernels')
+  },
+  {
+    id: 'jp-search-replace',
+    rank: 900,
+    settingKey: 'showSearchReplace',
+    command: 'xtralab:toggle-search-replace',
+    label: trans => trans.__('Search and Replace')
   }
 ];
 
 /**
- * Lets the user toggle individual left-sidebar tabs from
- * View > Appearance > Left Sidebar. Removing a widget from a `LabShell`
- * side area is done by setting `widget.parent = null`: the StackedPanel
- * emits `widgetRemoved`, which the SideBarHandler responds to by removing
- * the matching tab. The widget instance is preserved, so we can re-add it
- * later via `labShell.add` with its original rank.
- *
- * The menu placement is contributed declaratively in
- * `schema/sidebar.json`, so this plugin only registers commands and
- * applies state — it does not touch `IMainMenu` directly.
- *
- * The preference is persisted to `xtralab:sidebar` settings so the choice
- * survives reloads.
+ * Toggles individual sidebar tabs from View > Appearance > Sidebars. Hiding
+ * detaches the widget while keeping the instance for a later re-add; which
+ * side it came from is only tracked in-memory, so after a reload a re-shown
+ * tab lands on the left. Menu placement is declared in schema/sidebar.json.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
   description:
-    'Toggle visibility of selected sidebar tabs (default file browser, running sessions) from the View menu.',
+    'Toggle visibility of individual sidebar tabs from the View menu.',
   autoStart: true,
   requires: [ILabShell],
   optional: [ISettingRegistry, ITranslator],
@@ -72,31 +110,38 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
     const { commands } = app;
 
-    // Cache widget instances so we can re-add them after `widget.parent =
-    // null` has detached them from the sidebar. The widget is no longer
-    // reachable through `labShell.widgets('left')` once removed, so a
-    // missing cache entry would leave us unable to bring the tab back.
+    // Detached widgets are unreachable via `labShell.widgets(...)`; keep
+    // instances here so hidden tabs can be re-added.
     const widgetCache = new Map<string, Widget>();
 
-    const findInSidebar = (id: string): Widget | null => {
-      for (const w of labShell.widgets('left')) {
-        if (w.id === id) {
-          return w;
+    const hiddenFrom = new Map<string, 'left' | 'right'>();
+
+    const findInSidebars = (
+      id: string
+    ): { widget: Widget; area: 'left' | 'right' } | null => {
+      for (const area of ['left', 'right'] as const) {
+        for (const widget of labShell.widgets(area)) {
+          if (widget.id === id) {
+            return { widget, area };
+          }
         }
       }
       return null;
     };
 
+    const locate = (id: string): 'left' | 'right' | null =>
+      findInSidebars(id)?.area ?? null;
+
     const captureWidget = (id: string): Widget | null => {
       const cached = widgetCache.get(id);
       if (cached && !cached.isDisposed) {
         return cached;
       }
-      const found = findInSidebar(id);
+      const found = findInSidebars(id);
       if (found) {
-        widgetCache.set(id, found);
+        widgetCache.set(id, found.widget);
       }
-      return found;
+      return found?.widget ?? null;
     };
 
     let settings: ISettingRegistry.ISettings | null = null;
@@ -112,19 +157,23 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const apply = (target: ITarget): void => {
       const widget = captureWidget(target.id);
       if (!widget) {
-        // The upstream widget hasn't been added yet (or the extension is
-        // disabled). Nothing to do — the next time `apply` runs and finds
-        // it, the preference will take effect.
         return;
       }
-      const present = findInSidebar(target.id) !== null;
+      const area = locate(target.id);
+      if (!area && widget.parent !== null) {
+        // Attached outside the sidebars — leave it alone.
+        return;
+      }
       const wantPresent = readPreference(target);
-      if (wantPresent && !present) {
-        labShell.add(widget, 'left', { rank: target.rank });
-      } else if (!wantPresent && present) {
-        // Setting `parent = null` triggers SideBarHandler's
-        // `_onWidgetRemoved`, which strips the tab while leaving the
-        // widget instance alive for a later re-add.
+      if (wantPresent && !area) {
+        labShell.add(widget, hiddenFrom.get(target.id) ?? 'left', {
+          rank: target.rank
+        });
+        hiddenFrom.delete(target.id);
+      } else if (!wantPresent && area) {
+        hiddenFrom.set(target.id, area);
+        // Detaching makes the SideBarHandler remove the tab while the
+        // widget instance stays alive for a later re-add.
         widget.parent = null;
       }
     };
@@ -139,14 +188,21 @@ const plugin: JupyterFrontEndPlugin<void> = {
       commands.addCommand(target.command, {
         label: target.label(trans),
         isToggled: () => readPreference(target),
+        isVisible: () => {
+          // List only tabs this plugin can manage: in a sidebar, or
+          // hidden by this plugin (`parent === null`).
+          const widget = captureWidget(target.id);
+          return (
+            widget !== null &&
+            (widget.parent === null || locate(target.id) !== null)
+          );
+        },
         execute: async () => {
           const next = !readPreference(target);
           if (settings) {
             try {
               await settings.set(target.settingKey, next);
-              // `settings.changed` will fire and drive `apply` + the
-              // command-state refresh. Returning here keeps the toggle's
-              // single source of truth in the settings registry.
+              // `settings.changed` drives `apply` and the state refresh.
               return;
             } catch (reason) {
               console.error(
@@ -155,9 +211,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
               );
             }
           }
-          // No settings registry available (or the write failed): fall
-          // back to applying the change in-memory so the toggle still
-          // works for the current session.
+          // No settings (or the write failed): apply in-memory for this session.
           apply(target);
           commands.notifyCommandChanged(target.command);
         }
@@ -179,11 +233,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
     }
 
     void app.restored.then(() => {
-      // Capture references first so a hidden-on-startup widget is still
-      // recoverable later. `apply` would also do the lookup, but only on
-      // the targets that need to stay visible — by capturing every target
-      // here we keep the cache populated for both directions of the
-      // toggle.
+      // Capture every widget before applying, so tabs hidden on startup
+      // stay recoverable.
       for (const target of TARGETS) {
         captureWidget(target.id);
       }

package/src/terminalNotifications/index.ts

@@ -22,16 +22,28 @@ const OSC_RXVT_NOTIFY = 777;
 
 const MAX_TEXT_LENGTH = 256;
 
-// The bits of an xterm.js `Terminal` we reach into. JupyterLab's terminal
-// widget keeps its xterm in a private `_term` field and does not expose these
-// hooks, so a structural type uses them without depending on `@xterm/xterm`. If
-// the field is ever renamed, `_term` is `undefined` and notifications stop, with
-// a console warning per terminal.
+// JupyterLab's terminal keeps its xterm in a private `_term` field; structural
+// types use its hooks without `@xterm/xterm`, going inert (warning) if renamed.
+/**
+ * A handle returned by an xterm listener registration.
+ */
 interface IXtermDisposable {
+  /**
+   * Unregister the listener.
+   */
   dispose(): void;
 }
+/**
+ * The subset of the xterm.js API used to observe bells and OSC sequences.
+ */
 interface IXtermTerminal {
+  /**
+   * Register a handler invoked when the terminal bell rings.
+   */
   onBell(handler: () => void): IXtermDisposable;
+  /**
+   * The escape-sequence parser used to register OSC handlers.
+   */
   parser: {
     registerOscHandler(
       ident: number,
@@ -39,8 +51,17 @@ interface IXtermTerminal {
     ): IXtermDisposable;
   };
 }
+/**
+ * A JupyterLab terminal widget content with its private xterm exposed.
+ */
 interface ITerminalContentInternals extends ITerminal.ITerminal {
+  /**
+   * A promise resolving once the underlying xterm exists.
+   */
   ready: Promise<void>;
+  /**
+   * The private xterm instance; `undefined` if upstream renames the field.
+   */
   _term?: IXtermTerminal;
 }
 
@@ -48,26 +69,30 @@ type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
 
 // The renderer→main bridge the desktop shell injects on the lab window. Absent
 // for pip-install users in a browser, who fall back to web Notifications.
+/**
+ * The desktop notification API exposed on `window.xtralab`.
+ */
 interface IDesktopBridge {
+  /**
+   * Show a native notification, tagged with the emitting terminal session.
+   */
   notify?: (
     title: string,
     body: string,
     session?: string
   ) => Promise<void> | void;
+  /**
+   * Register a callback invoked with the tagged terminal session name when
+   * the user clicks a notification.
+   */
   onFocusTerminal?: (callback: (session: string) => void) => void;
 }
 
 /**
- * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
- * into desktop notifications. JupyterLab's xterm renders these sequences but
- * never forwards them to the OS, so this plugin hooks each terminal and bridges
- * them through `window.xtralab.notify` (desktop) or the web Notifications API.
- *
- * A notification is suppressed while its terminal is the focused, active tab,
- * and throttled per terminal. The desktop shell advertises
- * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
- * session name is forwarded so clicking a notification focuses the terminal
- * that fired it.
+ * Turns the OSC 9 / OSC 777 / bell sequences agents emit into desktop
+ * notifications via `window.xtralab.notify` (desktop) or the web Notifications
+ * API — JupyterLab's xterm renders them but never forwards them to the OS.
+ * The desktop shell advertises `TERM_PROGRAM=iTerm.app` so agents emit OSC 9.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -87,13 +112,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
     let enabled = true;
     let notifyOnBell = true;
 
-    // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
-    // widgets be collected; hooks are torn down when a tab closes.
     const lastNotified = new WeakMap<TerminalWidget, number>();
     const hooks = new WeakMap<TerminalWidget, IXtermDisposable[]>();
 
-    // True when the user is already looking at this terminal, so a banner would
-    // just be noise.
     const isActivelyViewing = (widget: TerminalWidget): boolean =>
       document.hasFocus() && app.shell.currentWidget === widget;
 
@@ -107,7 +128,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
         );
         return;
       }
-      // Plain-browser fallback (pip install): the Web Notifications API.
       if (typeof Notification === 'undefined') {
         return;
       }
@@ -146,9 +166,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
       widget.title.label || trans.__('Terminal');
 
     const onOsc9 = (widget: TerminalWidget, data: string): boolean => {
-      // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
-      // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
-      // payload and leave it unconsumed rather than treat it as a notification.
+      // OSC 9 is overloaded: ConEmu/Windows Terminal use numeric subcommands
+      // (e.g. `9 ; 4` progress); leave those unconsumed.
       if (/^\d+(;|$)/.test(data)) {
         return false;
       }
@@ -197,8 +216,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
             );
             return;
           }
-          // Handlers are wrapped so a parse slip cannot break xterm's parser; an
-          // OSC handler returns whether it consumed the sequence.
           const disposables: IXtermDisposable[] = [
             term.onBell(() => guard(() => onBell(widget))),
             term.parser.registerOscHandler(OSC_ITERM2_GROWL, data =>