xtralab 0.14.1 → 0.15.1

package/src/fileBrowser/widget.tsx

@@ -1,10 +1,21 @@
 import * as React from 'react';
 
+import {
+  IMovableSectionDestination,
+  IMovableSectionSource,
+  ISectionEntry
+} from '@jupyterlab/apputils';
 import { IDocumentManager } from '@jupyterlab/docmanager';
 import { Contents } from '@jupyterlab/services';
-import { ReactWidget, Toolbar } from '@jupyterlab/ui-components';
+import { ITranslator } from '@jupyterlab/translation';
+import {
+  AccordionToolbar,
+  PanelWithToolbar,
+  ReactWidget,
+  Toolbar
+} from '@jupyterlab/ui-components';
 import { Signal, ISignal } from '@lumino/signaling';
-import { PanelLayout, Widget } from '@lumino/widgets';
+import { AccordionPanel, PanelLayout, Widget } from '@lumino/widgets';
 
 import { FileBrowserComponent } from './fileBrowser';
 import { xtralabFileBrowserIcon } from './icons';
@@ -12,20 +23,46 @@ 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';
+
+/**
+ * The options used to create an {@link XtralabFileBrowser}.
+ */
 interface IXtralabFileBrowserOptions {
+  /**
+   * The contents manager backing the tree.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The document manager used to open files from the tree.
+   */
   docManager: IDocumentManager;
+  /**
+   * Callback invoked with a file's server path when its row is
+   * double-clicked. No double-click handler is installed when absent.
+   */
   onOpenFile?: (serverPath: string) => void;
+  /**
+   * The application language translator.
+   */
+  translator?: ITranslator;
 }
 
 /**
@@ -35,82 +72,62 @@ interface IXtralabFileBrowserOptions {
  */
 export interface IXtralabFileBrowser {
   /**
-   * The contents manager backing the tree. Exposed so command handlers can
-   * issue contents operations (rename, delete, copy, …) against the same
-   * drive the tree was loaded from.
+   * The contents manager backing the tree; command handlers issue rename,
+   * delete, copy, … against the same drive.
    */
   readonly contentsManager: Contents.IManager;
 
   /**
-   * The toolbar shown above the tree. Plugin code populates it with command
-   * buttons after the widget is constructed.
+   * The toolbar above the tree, populated by plugin code after construction.
    */
   readonly toolbar: Toolbar;
 
   /**
-   * Canonical paths of the items currently selected in the tree. Folder
-   * paths carry a trailing slash; file paths do not.
+   * Canonical selected paths; folder paths carry a trailing slash.
    */
   readonly selectedPaths: readonly string[];
 
   /**
-   * Emits when the tree's selection changes. Commands that have an
-   * `isVisible` / `isEnabled` predicate should listen so they re-evaluate.
+   * Emits when the tree's selection changes.
    */
   readonly selectionChanged: ISignal<IXtralabFileBrowser, readonly string[]>;
 
   /**
-   * Emits when {@link refresh} is called. The React component listens and
-   * re-fetches the directories that were previously loaded so the tree
-   * matches the contents on disk again.
+   * Emits when {@link refresh} is called.
    */
   readonly refreshRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Emits when the widget is asked to surface a newly-created path
-   * (for example, after the toolbar's "new folder" command). The React
-   * component listens and inserts the path into the model so the user
-   * sees the new item without a full refresh.
+   * Emits a newly-created canonical path so the tree inserts it without a
+   * full refresh.
    */
   readonly pathAdded: ISignal<IXtralabFileBrowser, string>;
 
   /**
-   * Emits when an external caller asks the tree to scroll to and select
-   * the given canonical path. The React component listens, lazily loads
-   * any unloaded ancestor directories, expands them, and selects the
-   * target. Used by the editor breadcrumbs to jump back to a file or
-   * folder shown in the breadcrumb trail.
+   * Emits a canonical path to load, expand, select, and scroll to. Used by
+   * the editor breadcrumbs.
    */
   readonly revealRequested: ISignal<IXtralabFileBrowser, string>;
 
   /**
-   * Emits when an external caller asks the tree to return to the
-   * workspace root: clear any current selection and scroll back to the
-   * first row. Distinct from {@link revealRequested} because the
-   * workspace root has no tree row of its own — it cannot be reached
-   * by passing a path.
+   * Emits when the tree should return to the workspace root — the root has
+   * no tree row of its own, so it cannot be revealed by path.
    */
   readonly rootRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Emits when an external caller asks the tree to collapse every
-   * expanded folder. The React component listens and walks the loaded
-   * directories, calling `.collapse()` on each expanded one.
+   * Emits when every expanded folder should collapse.
    */
   readonly collapseAllRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Whether the filter box above the tree is shown. Mirrors the default
-   * file browser's `showFileFilter`: hidden on startup and flipped by the
-   * toolbar toggle. Also forced to `true` when the tree opens a search
-   * session on its own — typing a letter while the tree has focus.
+   * Whether the filter box above the tree is shown; also forced `true` when
+   * the tree opens a search session itself (typing while it has focus).
    */
   readonly fileFilterVisible: boolean;
 
   /**
-   * Emits when {@link fileFilterVisible} changes. The React component
-   * listens to show or hide the filter box; the toggle command listens
-   * to refresh its toggled state.
+   * Emits when {@link fileFilterVisible} changes.
    */
   readonly fileFilterVisibleChanged: ISignal<IXtralabFileBrowser, boolean>;
 
@@ -120,24 +137,19 @@ export interface IXtralabFileBrowser {
   refresh(): void;
 
   /**
-   * Notify the React component that a new path was created and should
-   * appear in the tree. `canonicalPath` follows the `@pierre/trees`
-   * convention: directories carry a trailing slash, files do not.
+   * Notify the React component that a new canonical path was created and
+   * should appear in the tree.
    */
   notifyPathAdded(canonicalPath: string): void;
 
   /**
-   * Ask the tree to reveal {@link canonicalPath}: load and expand any
-   * unloaded ancestor directories, then select and scroll the target
-   * into view. `canonicalPath` follows the `@pierre/trees` convention
-   * (directories carry a trailing slash, files do not). Must be a
-   * non-empty path — use {@link scrollToRoot} for the root gesture.
+   * Reveal a non-empty canonical path: load and expand ancestors, then
+   * select and scroll to it. Use {@link scrollToRoot} for the root gesture.
    */
   reveal(canonicalPath: string): void;
 
   /**
-   * Ask the tree to return to the workspace root: clear any current
-   * selection and scroll back to the top of the tree.
+   * Return to the workspace root: clear the selection and scroll to the top.
    */
   scrollToRoot(): void;
 
@@ -155,102 +167,165 @@ export interface IXtralabFileBrowser {
    * Toggle the filter box above the tree.
    */
   toggleFileFilter(): void;
+
+  /**
+   * The DOM node of the movable "Files" section, used to locate the panel
+   * currently hosting the tree.
+   */
+  readonly sectionNode: HTMLElement;
 }
 
 /**
- * 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 implements IXtralabFileBrowser {
+export class XtralabFileBrowser
+  extends Widget
+  implements
+    IXtralabFileBrowser,
+    IMovableSectionSource,
+    IMovableSectionDestination
+{
   constructor(options: IXtralabFileBrowserOptions) {
     super();
-    const layout = (this.layout = new PanelLayout());
+    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(): Contents.IManager {
     return this._contentsManager;
   }
 
+  /**
+   * The toolbar above the tree.
+   */
   get toolbar(): Toolbar {
     return this._toolbar;
   }
 
+  /**
+   * Canonical selected paths; folder paths carry a trailing slash.
+   */
   get selectedPaths(): readonly string[] {
     return this._selectedPaths;
   }
 
+  /**
+   * A signal emitted when the tree's selection changes.
+   */
   get selectionChanged(): ISignal<this, readonly string[]> {
     return this._selectionChanged;
   }
 
+  /**
+   * A signal emitted when {@link refresh} is called.
+   */
   get refreshRequested(): ISignal<this, void> {
     return this._refreshRequested;
   }
 
+  /**
+   * A signal emitting a newly-created canonical path for the tree to insert.
+   */
   get pathAdded(): ISignal<this, string> {
     return this._pathAdded;
   }
 
+  /**
+   * A signal emitting a canonical path to load, expand, select, and scroll to.
+   */
   get revealRequested(): ISignal<this, string> {
     return this._revealRequested;
   }
 
+  /**
+   * A signal emitted when the tree should return to the workspace root.
+   */
   get rootRequested(): ISignal<this, void> {
     return this._rootRequested;
   }
 
+  /**
+   * A signal emitted when every expanded folder should collapse.
+   */
   get collapseAllRequested(): ISignal<this, void> {
     return this._collapseAllRequested;
   }
 
+  /**
+   * Whether the filter box above the tree is shown.
+   */
   get fileFilterVisible(): boolean {
     return this._fileFilterVisible;
   }
 
+  /**
+   * A signal emitted when {@link fileFilterVisible} changes.
+   */
   get fileFilterVisibleChanged(): ISignal<this, boolean> {
     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: readonly string[]): void {
     this._selectedPaths = paths;
     this._selectionChanged.emit(paths);
   }
 
+  /**
+   * Trigger a refresh of every loaded directory in the tree.
+   */
   refresh(): void {
     this._refreshRequested.emit();
   }
 
+  /**
+   * Notify the tree that a new canonical path was created.
+   */
   notifyPathAdded(canonicalPath: string): void {
     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: string): void {
     if (canonicalPath.length === 0) {
       throw new Error(
@@ -260,14 +335,23 @@ export class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
     this._revealRequested.emit(canonicalPath);
   }
 
+  /**
+   * Return to the workspace root: clear the selection and scroll to the top.
+   */
   scrollToRoot(): void {
     this._rootRequested.emit();
   }
 
+  /**
+   * Ask the tree to collapse every currently expanded folder.
+   */
   collapseAll(): void {
     this._collapseAllRequested.emit();
   }
 
+  /**
+   * Show or hide the filter box above the tree.
+   */
   setFileFilterVisible(visible: boolean): void {
     if (this._fileFilterVisible === visible) {
       return;
@@ -276,13 +360,181 @@ export class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
     this._fileFilterVisibleChanged.emit(visible);
   }
 
+  /**
+   * Toggle the filter box above the tree.
+   */
   toggleFileFilter(): void {
     this.setFileFilterVisible(!this._fileFilterVisible);
   }
 
+  /**
+   * The DOM node of the movable "Files" section.
+   */
+  get sectionNode(): HTMLElement {
+    return this._section.node;
+  }
+
+  /**
+   * Whether the panel currently holds no sections, its own tree included.
+   */
+  get isEmpty(): boolean {
+    return this._panelLayout.widgets.length === 0;
+  }
+
+  /**
+   * A signal emitted when a section is added to or removed from the panel.
+   */
+  get contentChanged(): ISignal<this, void> {
+    return this._contentChanged;
+  }
+
+  /**
+   * A signal emitting each section entry announced to the move plugin.
+   */
+  get sectionAdded(): ISignal<this, ISectionEntry> {
+    return this._sectionAdded;
+  }
+
+  /**
+   * The accordion hosting the sections, or `null` while the tree sits alone.
+   */
+  get accordionPanel(): AccordionPanel | null {
+    return this._accordion;
+  }
+
+  /**
+   * Section widgets hosted from other panels; the tree section is excluded.
+   */
+  get sections(): ReadonlyArray<Widget> {
+    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(): ReadonlyArray<ISectionEntry> {
+    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: string): Widget | null {
+    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: Widget): void {
+    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(): void {
+    for (const entry of this.getSections()) {
+      this._sectionAdded.emit(entry);
+    }
+  }
+
+  /**
+   * The first hosted section moves the tree into an accordion.
+   */
+  addSection(widget: Widget): void {
+    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: Widget): void {
+    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();
+  }
+
+  private _isSectionHome(): boolean {
+    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.
+   */
+  private _restoreToolbar(): void {
+    this._toolbar.parent = null;
+    this._section.insertWidget(0, this._toolbar);
+  }
+
   private _contentsManager: Contents.IManager;
   private _docManager: IDocumentManager;
   private _onOpenFile: ((serverPath: string) => void) | undefined;
+  private _translator: ITranslator | undefined;
   private _selectedPaths: readonly string[] = [];
   private _selectionChanged = new Signal<this, readonly string[]>(this);
   private _refreshRequested = new Signal<this, void>(this);
@@ -294,18 +546,42 @@ export class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
   private _fileFilterVisibleChanged = new Signal<this, boolean>(this);
   private _toolbar: Toolbar;
   private _content: XtralabFileTreeContent;
+  private _section: PanelWithToolbar;
+  private _panelLayout: PanelLayout;
+  private _accordion: AccordionPanel | null = null;
+  private _contentChanged = new Signal<this, void>(this);
+  private _sectionAdded = new Signal<this, ISectionEntry>(this);
 }
 
+/**
+ * The options used to create an {@link XtralabFileTreeContent}.
+ */
 interface IFileTreeContentOptions {
+  /**
+   * The contents manager backing the tree.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The document manager used to open files from the tree.
+   */
   docManager: IDocumentManager;
+  /**
+   * Callback invoked with a file's server path when its row is
+   * double-clicked. No double-click handler is installed when absent.
+   */
   onOpenFile?: (serverPath: string) => void;
+  /**
+   * The application language translator.
+   */
+  translator?: ITranslator;
+  /**
+   * The host widget the React tree reports selection and state changes to.
+   */
   browser: XtralabFileBrowser;
 }
 
 /**
- * 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: IFileTreeContentOptions) {
@@ -313,12 +589,16 @@ class XtralabFileTreeContent extends ReactWidget {
     this._options = options;
   }
 
+  /**
+   * Render the file browser React component.
+   */
   protected render(): React.ReactElement {
     return (
       <FileBrowserComponent
         contentsManager={this._options.contentsManager}
         docManager={this._options.docManager}
         onOpenFile={this._options.onOpenFile}
+        translator={this._options.translator}
         widget={this._options.browser}
       />
     );

package/src/fileTypeIcons/index.ts

@@ -25,13 +25,9 @@ function representativePath(
   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: DocumentRegistry.IFileType): void {
   const path = representativePath(fileType);
   if (path === null) {
@@ -79,9 +75,6 @@ const EXTRA_FILE_TYPE_EXTENSIONS = [
   '.wasm'
 ];
 
-/**
- * Register icon-only file types for unclaimed source extensions.
- */
 function registerExtraFileTypes(docRegistry: DocumentRegistry): void {
   for (const extension of EXTRA_FILE_TYPE_EXTENSIONS) {
     const icon = getSpecificTreeIcon(`file${extension}`);
@@ -125,7 +118,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
       applyTreeIcon(fileType);
     }
     registerExtraFileTypes(docRegistry);
-    // Pick up file types registered after this plugin activates.
     docRegistry.changed.connect((_, args) => {
       if (
         args.type === 'fileType' &&
@@ -148,8 +140,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
           }
         };
         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);