xtralab 0.14.0 → 0.15.0

package/schema/menu-bar.json

@@ -0,0 +1,37 @@
+{
+  "title": "xtralab menu bar",
+  "description": "Visibility of the main menu bar.",
+  "jupyter.lab.shortcuts": [],
+  "jupyter.lab.menus": {
+    "main": [
+      {
+        "id": "jp-mainmenu-view",
+        "items": [
+          {
+            "type": "submenu",
+            "rank": 1,
+            "submenu": {
+              "id": "jp-mainmenu-view-appearance",
+              "items": [
+                {
+                  "command": "xtralab:toggle-menu-bar",
+                  "rank": 14
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "type": "object",
+  "properties": {
+    "visible": {
+      "type": "boolean",
+      "title": "Show the menu bar",
+      "description": "When false, hides the main menu bar. Its menus stay available from the menu button at the leading edge of the top bar and the bar can be restored from View → Appearance → Show Menu Bar.",
+      "default": false
+    }
+  },
+  "additionalProperties": false
+}

package/schema/sidebar.json

@@ -1,6 +1,6 @@
 {
   "title": "xtralab sidebar",
-  "description": "Visibility of selected JupyterLab sidebar tabs.",
+  "description": "Visibility of individual sidebar tabs.",
   "jupyter.lab.shortcuts": [],
   "jupyter.lab.menus": {
     "main": [
@@ -17,16 +17,32 @@
                   "type": "submenu",
                   "rank": 12.5,
                   "submenu": {
-                    "id": "jp-mainmenu-view-appearance-left-sidebar",
-                    "label": "Left Sidebar",
+                    "id": "jp-mainmenu-view-appearance-sidebars",
+                    "label": "Sidebars",
                     "items": [
                       {
-                        "command": "xtralab:toggle-default-filebrowser",
+                        "command": "xtralab:toggle-terminals",
                         "rank": 1
                       },
                       {
-                        "command": "xtralab:toggle-running-sessions",
+                        "command": "xtralab:toggle-file-browser",
                         "rank": 2
+                      },
+                      {
+                        "command": "xtralab:toggle-git-panel",
+                        "rank": 3
+                      },
+                      {
+                        "command": "xtralab:toggle-default-filebrowser",
+                        "rank": 4
+                      },
+                      {
+                        "command": "xtralab:toggle-running-sessions",
+                        "rank": 5
+                      },
+                      {
+                        "command": "xtralab:toggle-search-replace",
+                        "rank": 6
                       }
                     ]
                   }
@@ -40,16 +56,40 @@
   },
   "type": "object",
   "properties": {
+    "showTerminals": {
+      "type": "boolean",
+      "title": "Show the terminals panel",
+      "description": "When false, hides the xtralab Terminals (`xtralab-running-terminals`) tab from the sidebar.",
+      "default": true
+    },
+    "showFileBrowser": {
+      "type": "boolean",
+      "title": "Show the xtralab file browser",
+      "description": "When false, hides the xtralab file browser (`xtralab:file-browser`) tab from the sidebar. The default JupyterLab file browser is unaffected.",
+      "default": true
+    },
+    "showGitPanel": {
+      "type": "boolean",
+      "title": "Show the Git panel",
+      "description": "When false, hides the `jp-git-sessions` (Git) tab from the sidebar.",
+      "default": true
+    },
     "showDefaultFileBrowser": {
       "type": "boolean",
       "title": "Show the default JupyterLab file browser",
-      "description": "When false, hides the default `filebrowser` tab from the left sidebar. The xtralab file browser is unaffected.",
+      "description": "When false, hides the default `filebrowser` tab from the sidebar. The xtralab file browser is unaffected.",
       "default": true
     },
     "showRunningSessions": {
       "type": "boolean",
       "title": "Show running terminals and kernels",
-      "description": "When false, hides the `jp-running-sessions` (Running Terminals and Kernels) tab from the left sidebar.",
+      "description": "When false, hides the `jp-running-sessions` (Running Terminals and Kernels) tab from the sidebar.",
+      "default": true
+    },
+    "showSearchReplace": {
+      "type": "boolean",
+      "title": "Show search and replace",
+      "description": "When false, hides the `jp-search-replace` (Search and Replace) tab from the sidebar.",
       "default": true
     }
   },

package/src/customPanel/index.ts

@@ -0,0 +1,104 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import {
+  IMovableSectionDestination,
+  IMovableSectionRegistry
+} from '@jupyterlab/apputils';
+import {
+  ITranslator,
+  nullTranslator,
+  type TranslationBundle
+} from '@jupyterlab/translation';
+import { SidePanel, tableRowsIcon } from '@jupyterlab/ui-components';
+import { ISignal, Signal } from '@lumino/signaling';
+import { AccordionPanel, Widget } from '@lumino/widgets';
+
+const PLUGIN_ID = 'xtralab:custom-panel';
+
+const CUSTOM_PANEL_ID = 'xtralab-custom-panel';
+
+/**
+ * A sidebar panel holding only the sections moved in from other panels.
+ */
+class CustomPanel extends SidePanel implements IMovableSectionDestination {
+  constructor(options: { trans: TranslationBundle }) {
+    super();
+    this.id = CUSTOM_PANEL_ID;
+    this.title.icon = tableRowsIcon;
+    this.title.caption = options.trans.__('Custom Panel');
+    this.addClass('jp-xtralab-CustomPanel');
+  }
+
+  get accordionPanel(): AccordionPanel {
+    return this.content as AccordionPanel;
+  }
+
+  get sections(): ReadonlyArray<Widget> {
+    return this.content.widgets;
+  }
+
+  get sectionCountChanged(): ISignal<this, number> {
+    return this._sectionCountChanged;
+  }
+
+  addSection(widget: Widget): void {
+    this.addWidget(widget);
+    this._sectionCountChanged.emit(this.content.widgets.length);
+  }
+
+  removeSectionWidget(widget: Widget): void {
+    if (widget.parent !== this.content) {
+      return;
+    }
+    widget.parent = null;
+    this._sectionCountChanged.emit(this.content.widgets.length);
+  }
+
+  private _sectionCountChanged = new Signal<this, number>(this);
+}
+
+/**
+ * Registers "Custom Panel", which takes a sidebar tab only while it hosts a
+ * section.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'A user-assembled sidebar panel hosting sections moved in from other panels; hidden while empty.',
+  autoStart: true,
+  optional: [IMovableSectionRegistry, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    registry: IMovableSectionRegistry | null,
+    translator: ITranslator | null
+  ): void => {
+    if (!registry) {
+      return;
+    }
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const panel = new CustomPanel({ trans });
+
+    // Only a user move should switch the sidebar, not the startup restoration.
+    let restored = false;
+    void app.restored.then(() => {
+      restored = true;
+    });
+
+    panel.sectionCountChanged.connect((_, count) => {
+      if (count > 0 && !panel.parent) {
+        app.shell.add(panel, 'left', { rank: 3 });
+        if (restored) {
+          app.shell.activateById(panel.id);
+        }
+      } else if (count === 0 && panel.parent) {
+        panel.parent = null;
+      }
+    });
+
+    registry.registerTarget(PLUGIN_ID, trans.__('Custom Panel'), panel);
+  }
+};
+
+export default plugin;

package/src/fileBrowser/commands.ts

@@ -512,11 +512,24 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   // point of view. An empty path is the "workspace root" gesture —
   // there is no tree row for the root itself, so the browser is asked
   // to scroll back to the top and clear its selection instead.
+  // The tree is movable, so surface whichever sidebar widget holds it.
+  const activateTreeHost = (): void => {
+    for (const area of ['left', 'right']) {
+      for (const widget of app.shell.widgets(area)) {
+        if (widget.node.contains(browser.sectionNode)) {
+          app.shell.activateById(widget.id);
+          return;
+        }
+      }
+    }
+    app.shell.activateById(FILE_BROWSER_ID);
+  };
+
   commands.addCommand(CommandIDs.revealPath, {
     label: trans.__('Reveal in File Browser'),
     execute: (args: ReadonlyPartialJSONObject) => {
       const path = (args.path as string | undefined) ?? '';
-      app.shell.activateById(FILE_BROWSER_ID);
+      activateTreeHost();
       if (path.length === 0) {
         browser.scrollToRoot();
       } else {

package/src/fileBrowser/contents.ts

@@ -17,6 +17,36 @@ export function toCanonicalPath(child: Contents.IModel): string {
   return child.type === 'directory' ? `${child.path}${DIR_SUFFIX}` : child.path;
 }
 
+/**
+ * Compute the canonical parent path for a canonical path. Returns
+ * {@link ROOT_LOAD_KEY} for top-level entries.
+ */
+export function parentOf(canonicalPath: string): string {
+  const trimmed = canonicalPath.endsWith(DIR_SUFFIX)
+    ? canonicalPath.slice(0, -DIR_SUFFIX.length)
+    : canonicalPath;
+  const idx = trimmed.lastIndexOf(DIR_SUFFIX);
+  if (idx < 0) {
+    return ROOT_LOAD_KEY;
+  }
+  return `${trimmed.slice(0, idx)}${DIR_SUFFIX}`;
+}
+
+/**
+ * The last segment of a canonical path. Directories keep their trailing
+ * slash, so appending the result to a canonical directory path yields a
+ * canonical path again.
+ */
+export function canonicalBasename(canonicalPath: string): string {
+  const isDir = canonicalPath.endsWith(DIR_SUFFIX);
+  const trimmed = isDir
+    ? canonicalPath.slice(0, -DIR_SUFFIX.length)
+    : canonicalPath;
+  const idx = trimmed.lastIndexOf(DIR_SUFFIX);
+  const base = idx < 0 ? trimmed : trimmed.slice(idx + DIR_SUFFIX.length);
+  return isDir ? `${base}${DIR_SUFFIX}` : base;
+}
+
 /**
  * Strip the trailing slash that `@pierre/trees` uses for canonical directory
  * paths so the value can be sent to the Jupyter contents API.

package/src/fileBrowser/dragAndDrop.ts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+
+import type {
+  FileTree,
+  FileTreeDragAndDropConfig,
+  FileTreeDropContext,
+  FileTreeDropResult,
+  FileTreeDropTarget
+} from '@pierre/trees';
+
+import { ROOT_LOAD_KEY, canonicalBasename, parentOf } from './contents';
+
+/**
+ * One tree-model move a drop performs, as canonical paths.
+ */
+export interface IDropMove {
+  from: string;
+  to: string;
+}
+
+/**
+ * Receives drop outcomes from the `@pierre/trees` drag-and-drop
+ * machinery. Implemented inside the file browser's contents-sync
+ * effect, which owns the load-state and contents-API bookkeeping.
+ */
+export interface ITreeDropHandler {
+  /**
+   * The tree applied the drop to its model: persist the move and
+   * re-key the load-state mirrors.
+   */
+  completeDrop(result: FileTreeDropResult): void;
+
+  /**
+   * The tree refused the drop (typically a name collision) and left
+   * its model untouched.
+   */
+  failedDrop(error: string, context: FileTreeDropContext): void;
+
+  /**
+   * A drop on the empty space below the last row: move the dragged
+   * paths to the workspace root.
+   */
+  dropOnRoot(draggedPaths: readonly string[]): void;
+}
+
+/**
+ * The from→to moves a drop performs: each dragged path keeps its
+ * basename under the target directory. Paths already directly inside
+ * the target are skipped.
+ */
+export function computeDropMoves(context: FileTreeDropContext): IDropMove[] {
+  const dir = context.target.directoryPath ?? ROOT_LOAD_KEY;
+  return context.draggedPaths
+    .filter(path => parentOf(path) !== dir)
+    .map(path => ({ from: path, to: `${dir}${canonicalBasename(path)}` }));
+}
+
+/**
+ * The drop target the tree reports for a move to the workspace root.
+ */
+const ROOT_DROP_TARGET: FileTreeDropTarget = {
+  directoryPath: null,
+  flattenedSegmentPath: null,
+  hoveredPath: null,
+  kind: 'root'
+};
+
+/**
+ * The moves for a drop of `paths` onto the workspace root.
+ */
+export function computeRootDropMoves(paths: readonly string[]): IDropMove[] {
+  return computeDropMoves({ draggedPaths: paths, target: ROOT_DROP_TARGET });
+}
+
+/**
+ * Build the `dragAndDrop` option for `useFileTree`. The tree captures
+ * its options once, so the callbacks delegate through `handlerRef`,
+ * filled by the contents-sync effect. `canDrop` hides the drop
+ * highlight for all-no-op drops, which the library would accept.
+ */
+export function createTreeDragAndDropConfig(
+  handlerRef: React.RefObject<ITreeDropHandler | null>
+): FileTreeDragAndDropConfig {
+  return {
+    canDrop: context => computeDropMoves(context).length > 0,
+    onDropComplete: result => {
+      handlerRef.current?.completeDrop(result);
+    },
+    onDropError: (error, context) => {
+      handlerRef.current?.failedDrop(error, context);
+    }
+  };
+}
+
+interface IRootDropZoneOptions {
+  model: FileTree;
+  handlerRef: React.RefObject<ITreeDropHandler | null>;
+  /**
+   * The light-DOM wrapper around the tree host; composed drag events
+   * bubble out of the shadow root to it.
+   */
+  wrapperRef: React.RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Accept drops on the empty space below the last row as moves to the
+ * workspace root — the tree resolves a drop target only while the
+ * cursor is over a row and silently discards such drops. dragstart
+ * records the dragged paths; a drop whose composed path contains no
+ * row hands them over as a root move.
+ */
+export function useRootDropZone(options: IRootDropZoneOptions): void {
+  const { model, handlerRef, wrapperRef } = options;
+
+  React.useEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (wrapper === null) {
+      return;
+    }
+
+    let draggedPaths: readonly string[] | null = null;
+
+    const findRow = (event: DragEvent): HTMLElement | null => {
+      for (const target of event.composedPath()) {
+        if (target instanceof HTMLElement && target.dataset.type === 'item') {
+          return target;
+        }
+      }
+      return null;
+    };
+
+    const handleDragStart = (event: DragEvent): void => {
+      draggedPaths = null;
+      // The tree cancels dragstart when it refuses a session, e.g.
+      // while the filter is open.
+      if (event.defaultPrevented) {
+        return;
+      }
+      const path = findRow(event)?.dataset.itemPath;
+      if (path === undefined || path.length === 0) {
+        return;
+      }
+      // The selection is the dragged set (the tree selects the pressed
+      // row); entries nested under a dragged folder travel with it.
+      const selection = model.getSelectedPaths();
+      const candidates = selection.includes(path) ? selection : [path];
+      const folders = candidates.filter(c => c.endsWith('/'));
+      draggedPaths = candidates.filter(
+        c => !folders.some(folder => folder !== c && c.startsWith(folder))
+      );
+    };
+
+    const handleDrop = (event: DragEvent): void => {
+      const paths = draggedPaths;
+      draggedPaths = null;
+      // Drops on a row were already resolved by the tree itself.
+      if (paths === null || findRow(event) !== null) {
+        return;
+      }
+      event.preventDefault();
+      handlerRef.current?.dropOnRoot(paths);
+    };
+
+    const handleDragEnd = (): void => {
+      draggedPaths = null;
+    };
+
+    wrapper.addEventListener('dragstart', handleDragStart);
+    wrapper.addEventListener('drop', handleDrop);
+    window.addEventListener('dragend', handleDragEnd);
+    return () => {
+      wrapper.removeEventListener('dragstart', handleDragStart);
+      wrapper.removeEventListener('drop', handleDrop);
+      window.removeEventListener('dragend', handleDragEnd);
+      draggedPaths = null;
+    };
+  }, [model, handlerRef, wrapperRef]);
+}