xtralab 0.14.1 → 0.15.1

package/lib/fileBrowser/widget.d.ts

@@ -1,13 +1,32 @@
+import { IMovableSectionDestination, IMovableSectionSource, ISectionEntry } from '@jupyterlab/apputils';
 import { IDocumentManager } from '@jupyterlab/docmanager';
 import { Contents } from '@jupyterlab/services';
+import { ITranslator } from '@jupyterlab/translation';
 import { Toolbar } from '@jupyterlab/ui-components';
 import { ISignal } from '@lumino/signaling';
-import { Widget } from '@lumino/widgets';
+import { AccordionPanel, Widget } from '@lumino/widgets';
 export declare const FILE_BROWSER_ID = "xtralab:file-browser";
+/**
+ * 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;
 }
 /**
  * Public API of the xtralab file browser used by command handlers and other
@@ -16,72 +35,52 @@ 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>;
     /**
@@ -89,22 +88,17 @@ 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;
     /**
@@ -119,40 +113,158 @@ 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 declare class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
+export declare class XtralabFileBrowser extends Widget implements IXtralabFileBrowser, IMovableSectionSource, IMovableSectionDestination {
     constructor(options: IXtralabFileBrowserOptions);
+    /**
+     * The contents manager backing the tree.
+     */
     get contentsManager(): Contents.IManager;
+    /**
+     * The toolbar above the tree.
+     */
     get toolbar(): Toolbar;
+    /**
+     * Canonical selected paths; folder paths carry a trailing slash.
+     */
     get selectedPaths(): readonly string[];
+    /**
+     * A signal emitted when the tree's selection changes.
+     */
     get selectionChanged(): ISignal<this, readonly string[]>;
+    /**
+     * A signal emitted when {@link refresh} is called.
+     */
     get refreshRequested(): ISignal<this, void>;
+    /**
+     * A signal emitting a newly-created canonical path for the tree to insert.
+     */
     get pathAdded(): ISignal<this, string>;
+    /**
+     * A signal emitting a canonical path to load, expand, select, and scroll to.
+     */
     get revealRequested(): ISignal<this, string>;
+    /**
+     * A signal emitted when the tree should return to the workspace root.
+     */
     get rootRequested(): ISignal<this, void>;
+    /**
+     * A signal emitted when every expanded folder should collapse.
+     */
     get collapseAllRequested(): ISignal<this, void>;
+    /**
+     * Whether the filter box above the tree is shown.
+     */
     get fileFilterVisible(): boolean;
+    /**
+     * A signal emitted when {@link fileFilterVisible} changes.
+     */
     get fileFilterVisibleChanged(): ISignal<this, boolean>;
     /**
-     * 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;
+    /**
+     * Trigger a refresh of every loaded directory in the tree.
+     */
     refresh(): void;
+    /**
+     * Notify the tree that a new canonical path was created.
+     */
     notifyPathAdded(canonicalPath: string): void;
+    /**
+     * 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;
+    /**
+     * Return to the workspace root: clear the selection and scroll to the top.
+     */
     scrollToRoot(): void;
+    /**
+     * Ask the tree to collapse every currently expanded folder.
+     */
     collapseAll(): void;
+    /**
+     * Show or hide the filter box above the tree.
+     */
     setFileFilterVisible(visible: boolean): void;
+    /**
+     * Toggle the filter box above the tree.
+     */
     toggleFileFilter(): void;
+    /**
+     * The DOM node of the movable "Files" section.
+     */
+    get sectionNode(): HTMLElement;
+    /**
+     * Whether the panel currently holds no sections, its own tree included.
+     */
+    get isEmpty(): boolean;
+    /**
+     * A signal emitted when a section is added to or removed from the panel.
+     */
+    get contentChanged(): ISignal<this, void>;
+    /**
+     * A signal emitting each section entry announced to the move plugin.
+     */
+    get sectionAdded(): ISignal<this, ISectionEntry>;
+    /**
+     * The accordion hosting the sections, or `null` while the tree sits alone.
+     */
+    get accordionPanel(): AccordionPanel | null;
+    /**
+     * Section widgets hosted from other panels; the tree section is excluded.
+     */
+    get sections(): ReadonlyArray<Widget>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Re-attach the tree section after a move back to this panel.
+     */
+    reinsertSection(widget: Widget): void;
+    /**
+     * The move plugin reconciles persisted moves only against sections announced
+     * after `registerSource`, and this panel builds its section in the constructor.
+     */
+    announceSections(): void;
+    /**
+     * The first hosted section moves the tree into an accordion.
+     */
+    addSection(widget: Widget): void;
+    /**
+     * Remove a hosted section; the accordion is torn down once only the
+     * panel's own tree section (or nothing) remains.
+     */
+    removeSectionWidget(widget: Widget): void;
+    private _isSectionHome;
+    /**
+     * 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;
     private _contentsManager;
     private _docManager;
     private _onOpenFile;
+    private _translator;
     private _selectedPaths;
     private _selectionChanged;
     private _refreshRequested;
@@ -164,5 +276,10 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     private _fileFilterVisibleChanged;
     private _toolbar;
     private _content;
+    private _section;
+    private _panelLayout;
+    private _accordion;
+    private _contentChanged;
+    private _sectionAdded;
 }
 export {};