@jupyterlab/application 3.4.1 → 4.0.0-alpha.10

package/lib/shell.js

@@ -4,7 +4,7 @@ import { DocumentWidget } from '@jupyterlab/docregistry';
 import { nullTranslator } from '@jupyterlab/translation';
 import { classes, DockPanelSvg, LabIcon, TabPanelSvg } from '@jupyterlab/ui-components';
 import { ArrayExt, find, iter, toArray } from '@lumino/algorithm';
-import { PromiseDelegate, Token } from '@lumino/coreutils';
+import { JSONExt, PromiseDelegate, Token } from '@lumino/coreutils';
 import { MessageLoop } from '@lumino/messaging';
 import { Debouncer } from '@lumino/polling';
 import { Signal } from '@lumino/signaling';
@@ -74,11 +74,24 @@ export class LabShell extends Widget {
         }, 0);
         this._restored = new PromiseDelegate();
         this._tracker = new FocusTracker();
+        this._topHandlerHiddenByUser = false;
+        this._idTypeMap = new Map();
         this._mainOptionsCache = new Map();
         this._sideOptionsCache = new Map();
+        this._delayedWidget = new Array();
         this.addClass(APPLICATION_SHELL_CLASS);
         this.id = 'main';
+        if ((options === null || options === void 0 ? void 0 : options.waitForRestore) === false) {
+            this._userLayout = { 'multiple-document': {}, 'single-document': {} };
+        }
         const trans = ((options && options.translator) || nullTranslator).load('jupyterlab');
+        // Skip Links
+        const skipLinkWidget = (this._skipLinkWidget = new Private.SkipLinkWidget(this));
+        this._skipLinkWidget.show();
+        //  Wrap the skip widget to customize its position and size
+        const skipLinkWrapper = new Panel();
+        skipLinkWrapper.addClass('jp-skiplink-wrapper');
+        skipLinkWrapper.addWidget(skipLinkWidget);
         const headerPanel = (this._headerPanel = new BoxPanel());
         const menuHandler = (this._menuHandler = new Private.PanelHandler());
         menuHandler.panel.node.setAttribute('role', 'navigation');
@@ -88,13 +101,15 @@ export class LabShell extends Widget {
         const bottomPanel = (this._bottomPanel = new BoxPanel());
         bottomPanel.node.setAttribute('role', 'contentinfo');
         const hboxPanel = new BoxPanel();
-        const vsplitPanel = (this._vsplitPanel = new Private.RestorableSplitPanel());
+        const vsplitPanel = (this._vsplitPanel =
+            new Private.RestorableSplitPanel());
         const dockPanel = (this._dockPanel = new DockPanelSvg({
             hiddenMode: Widget.HiddenMode.Scale,
             translator: options === null || options === void 0 ? void 0 : options.translator
         }));
         MessageLoop.installMessageHook(dockPanel, this._dockChildHook);
-        const hsplitPanel = (this._hsplitPanel = new Private.RestorableSplitPanel());
+        const hsplitPanel = (this._hsplitPanel =
+            new Private.RestorableSplitPanel());
         const downPanel = (this._downPanel = new TabPanelSvg({
             tabsMovable: true
         }));
@@ -160,6 +175,7 @@ export class LabShell extends Widget {
         BoxLayout.setStretch(topHandler.panel, 0);
         BoxLayout.setStretch(hboxPanel, 1);
         BoxLayout.setStretch(bottomPanel, 0);
+        rootLayout.addWidget(skipLinkWrapper);
         rootLayout.addWidget(headerPanel);
         rootLayout.addWidget(topHandler.panel);
         rootLayout.addWidget(hboxPanel);
@@ -181,8 +197,8 @@ export class LabShell extends Widget {
         this._downPanel.tabBar.tabMoved.connect(this._onTabPanelChanged, this);
         this._downPanel.stackedPanel.widgetRemoved.connect(this._onTabPanelChanged, this);
         // Catch current changed events on the side handlers.
-        this._leftHandler.sideBar.currentChanged.connect(this._onLayoutModified, this);
-        this._rightHandler.sideBar.currentChanged.connect(this._onLayoutModified, this);
+        this._leftHandler.updated.connect(this._onLayoutModified, this);
+        this._rightHandler.updated.connect(this._onLayoutModified, this);
         // Catch update events on the horizontal split panel
         this._hsplitPanel.updated.connect(this._onLayoutModified, this);
         // Setup single-document-mode title bar
@@ -193,12 +209,8 @@ export class LabShell extends Widget {
             titleHandler.hide();
         }
         else {
-            rootLayout.insertWidget(2, this._menuHandler.panel);
+            rootLayout.insertWidget(3, this._menuHandler.panel);
         }
-        // Skip Links
-        const skipLinkWidget = (this._skipLinkWidget = new Private.SkipLinkWidget(this));
-        this.add(skipLinkWidget, 'top', { rank: 0 });
-        this._skipLinkWidget.show();
         // Wire up signals to update the title panel of the simple interface mode to
         // follow the title of this.currentWidget
         this.currentChanged.connect((sender, args) => {
@@ -232,16 +244,25 @@ export class LabShell extends Widget {
         return this._tracker.activeWidget;
     }
     /**
-     * A signal emitted when main area's current focus changes.
+     * Whether the add buttons for each main area tab bar are enabled.
      */
-    get currentChanged() {
-        return this._currentChanged;
+    get addButtonEnabled() {
+        return this._dockPanel.addButtonEnabled;
+    }
+    set addButtonEnabled(value) {
+        this._dockPanel.addButtonEnabled = value;
     }
     /**
-     * A signal emitted when the shell/dock panel change modes (single/multiple document).
+     * A signal emitted when the add button on a main area tab bar is clicked.
      */
-    get modeChanged() {
-        return this._modeChanged;
+    get addRequested() {
+        return this._dockPanel.addRequested;
+    }
+    /**
+     * A signal emitted when main area's current focus changes.
+     */
+    get currentChanged() {
+        return this._currentChanged;
     }
     /**
      * A signal emitted when the path of the current document changes.
@@ -282,10 +303,6 @@ export class LabShell extends Widget {
     get presentationMode() {
         return this.hasClass('jp-mod-presentationMode');
     }
-    /**
-     * Enable/disable presentation mode (`jp-mod-presentationMode` CSS class) with
-     * a boolean.
-     */
     set presentationMode(value) {
         this.toggleClass('jp-mod-presentationMode', value);
     }
@@ -311,9 +328,12 @@ export class LabShell extends Widget {
                 dock.activateWidget(this.currentWidget);
             }
             // Adjust menu and title
-            this.layout.insertWidget(2, this._menuHandler.panel);
+            this.layout.insertWidget(3, this._menuHandler.panel);
             this._titleHandler.show();
             this._updateTitlePanelTitle();
+            if (this._topHandlerHiddenByUser) {
+                this._topHandler.panel.hide();
+            }
         }
         else {
             // Cache a reference to every widget currently in the dock panel before
@@ -345,7 +365,6 @@ export class LabShell extends Widget {
             }
             // Adjust menu and title
             this.add(this._menuHandler.panel, 'top', { rank: 100 });
-            // this._topHandler.addWidget(this._menuHandler.panel, 100)
             this._titleHandler.hide();
         }
         // Set the mode data attribute on the applications shell node.
@@ -354,6 +373,12 @@ export class LabShell extends Widget {
         // Emit the mode changed signal
         this._modeChanged.emit(mode);
     }
+    /**
+     * A signal emitted when the shell/dock panel change modes (single/multiple document).
+     */
+    get modeChanged() {
+        return this._modeChanged;
+    }
     /**
      * Promise that resolves when state is first restored, returning layout
      * description.
@@ -361,6 +386,12 @@ export class LabShell extends Widget {
     get restored() {
         return this._restored.promise;
     }
+    /**
+     * User customized shell layout.
+     */
+    get userLayout() {
+        return JSONExt.deepCopy(this._userLayout);
+    }
     /**
      * Activate a widget in its area.
      */
@@ -384,7 +415,7 @@ export class LabShell extends Widget {
             dock.activateWidget(widget);
         }
     }
-    /*
+    /**
      * Activate the next Tab in the active TabBar.
      */
     activateNextTab() {
@@ -413,22 +444,7 @@ export class LabShell extends Widget {
             }
         }
     }
-    /*
-     * Whether the add buttons for each main area tab bar are enabled.
-     */
-    get addButtonEnabled() {
-        return this._dockPanel.addButtonEnabled;
-    }
-    set addButtonEnabled(value) {
-        this._dockPanel.addButtonEnabled = value;
-    }
-    /*
-     * A signal emitted when the add button on a main area tab bar is clicked.
-     */
-    get addRequested() {
-        return this._dockPanel.addRequested;
-    }
-    /*
+    /**
      * Activate the previous Tab in the active TabBar.
      */
     activatePreviousTab() {
@@ -458,7 +474,7 @@ export class LabShell extends Widget {
             }
         }
     }
-    /*
+    /**
      * Activate the next TabBar.
      */
     activateNextTabBar() {
@@ -469,7 +485,7 @@ export class LabShell extends Widget {
             }
         }
     }
-    /*
+    /**
      * Activate the next TabBar.
      */
     activatePreviousTabBar() {
@@ -480,7 +496,34 @@ export class LabShell extends Widget {
             }
         }
     }
+    /**
+     * Add a widget to the JupyterLab shell
+     *
+     * @param widget Widget
+     * @param area Area
+     * @param options Options
+     */
     add(widget, area = 'main', options) {
+        var _a;
+        if (!this._userLayout) {
+            this._delayedWidget.push({ widget, area, options });
+            return;
+        }
+        let userPosition;
+        if ((options === null || options === void 0 ? void 0 : options.type) && this._userLayout[this.mode][options.type]) {
+            userPosition = this._userLayout[this.mode][options.type];
+            this._idTypeMap.set(widget.id, options.type);
+        }
+        else {
+            userPosition = this._userLayout[this.mode][widget.id];
+        }
+        if (options === null || options === void 0 ? void 0 : options.type) {
+            this._idTypeMap.set(widget.id, options.type);
+        }
+        area = (_a = userPosition === null || userPosition === void 0 ? void 0 : userPosition.area) !== null && _a !== void 0 ? _a : area;
+        options =
+            options || (userPosition === null || userPosition === void 0 ? void 0 : userPosition.options)
+                ? Object.assign(Object.assign({}, options), userPosition === null || userPosition === void 0 ? void 0 : userPosition.options) : undefined;
         switch (area || 'main') {
             case 'bottom':
                 return this._addToBottomArea(widget, options);
@@ -502,6 +545,29 @@ export class LabShell extends Widget {
                 throw new Error(`Invalid area: ${area}`);
         }
     }
+    /**
+     * Move a widget type to a new area.
+     *
+     * The type is determined from the `widget.id` and fallback to `widget.id`.
+     *
+     * #### Notes
+     * If `mode` is undefined, both mode are updated.
+     * The new layout is now persisted.
+     *
+     * @param widget Widget to move
+     * @param area New area
+     * @param mode Mode to change
+     * @returns The new user layout
+     */
+    move(widget, area, mode) {
+        var _a;
+        const type = (_a = this._idTypeMap.get(widget.id)) !== null && _a !== void 0 ? _a : widget.id;
+        for (const m of ['single-document', 'multiple-document'].filter(c => !mode || c === mode)) {
+            this._userLayout[m][type] = Object.assign(Object.assign({}, this._userLayout[m][type]), { area });
+        }
+        this.add(widget, area);
+        return this._userLayout;
+    }
     /**
      * Collapse the left area.
      */
@@ -558,6 +624,28 @@ export class LabShell extends Widget {
         toArray(this._dockPanel.widgets()).forEach(widget => widget.close());
         this._downPanel.stackedPanel.widgets.forEach(widget => widget.close());
     }
+    /**
+     * Whether an side tab bar is visible or not.
+     *
+     * @param side Sidebar of interest
+     * @returns Side tab bar visibility
+     */
+    isSideTabBarVisible(side) {
+        switch (side) {
+            case 'left':
+                return this._leftHandler.isVisible;
+            case 'right':
+                return this._rightHandler.isVisible;
+        }
+    }
+    /**
+     * Whether the top bar in simple mode is visible or not.
+     *
+     * @returns Top bar visibility
+     */
+    isTopInSimpleModeVisible() {
+        return !this._topHandlerHiddenByUser;
+    }
     /**
      * True if the given area is empty.
      */
@@ -584,11 +672,24 @@ export class LabShell extends Widget {
         }
     }
     /**
-     * Restore the layout state for the application shell.
+     * Restore the layout state and configuration for the application shell.
+     *
+     * #### Notes
+     * This should only be called once.
      */
-    restoreLayout(mode, layout) {
-        var _a, _b;
-        const { mainArea, downArea, leftArea, rightArea, relativeSizes } = layout;
+    restoreLayout(mode, layout, configuration = {}) {
+        var _a, _b, _c, _d;
+        // Set the configuration
+        this._userLayout = {
+            'single-document': (_a = configuration['single-document']) !== null && _a !== void 0 ? _a : {},
+            'multiple-document': (_b = configuration['multiple-document']) !== null && _b !== void 0 ? _b : {}
+        };
+        this._delayedWidget.forEach(({ widget, area, options }) => {
+            this.add(widget, area, options);
+        });
+        this._delayedWidget.length = 0;
+        // Reset the layout
+        const { mainArea, downArea, leftArea, rightArea, topArea, relativeSizes } = layout;
         // Rehydrate the main area.
         if (mainArea) {
             const { currentWidget, dock } = mainArea;
@@ -608,10 +709,16 @@ export class LabShell extends Widget {
                 this.mode = mode;
             }
         }
+        if ((topArea === null || topArea === void 0 ? void 0 : topArea.simpleVisibility) !== undefined) {
+            this._topHandlerHiddenByUser = !topArea.simpleVisibility;
+            if (this.mode === 'single-document') {
+                this._topHandler.panel.setHidden(this._topHandlerHiddenByUser);
+            }
+        }
         // Rehydrate the down area
         if (downArea) {
             const { currentWidget, widgets, size } = downArea;
-            const widgetIds = (_a = widgets === null || widgets === void 0 ? void 0 : widgets.map(widget => widget.id)) !== null && _a !== void 0 ? _a : [];
+            const widgetIds = (_c = widgets === null || widgets === void 0 ? void 0 : widgets.map(widget => widget.id)) !== null && _c !== void 0 ? _c : [];
             // Remove absent widgets
             this._downPanel.tabBar.titles
                 .filter(title => !widgetIds.includes(title.owner.id))
@@ -632,7 +739,7 @@ export class LabShell extends Widget {
                 const index = this._downPanel.stackedPanel.widgets.findIndex(widget => widget.id === currentWidget.id);
                 if (index) {
                     this._downPanel.currentIndex = index;
-                    (_b = this._downPanel.currentWidget) === null || _b === void 0 ? void 0 : _b.activate();
+                    (_d = this._downPanel.currentWidget) === null || _d === void 0 ? void 0 : _d.activate();
                 }
             }
             if (size && size > 0.0) {
@@ -694,10 +801,53 @@ export class LabShell extends Widget {
             },
             leftArea: this._leftHandler.dehydrate(),
             rightArea: this._rightHandler.dehydrate(),
+            topArea: { simpleVisibility: !this._topHandlerHiddenByUser },
             relativeSizes: this._hsplitPanel.relativeSizes()
         };
         return layout;
     }
+    /**
+     * Toggle top header visibility in simple mode
+     *
+     * Note: Does nothing in multi-document mode
+     */
+    toggleTopInSimpleModeVisibility() {
+        if (this.mode === 'single-document') {
+            if (this._topHandler.panel.isVisible) {
+                this._topHandlerHiddenByUser = true;
+                this._topHandler.panel.hide();
+            }
+            else {
+                this._topHandlerHiddenByUser = false;
+                this._topHandler.panel.show();
+                this._updateTitlePanelTitle();
+            }
+            this._onLayoutModified();
+        }
+    }
+    /**
+     * Toggle side tab bar visibility
+     *
+     * @param side Sidebar of interest
+     */
+    toggleSideTabBarVisibility(side) {
+        if (side === 'right') {
+            if (this._rightHandler.isVisible) {
+                this._rightHandler.hide();
+            }
+            else {
+                this._rightHandler.show();
+            }
+        }
+        else {
+            if (this._leftHandler.isVisible) {
+                this._leftHandler.hide();
+            }
+            else {
+                this._leftHandler.show();
+            }
+        }
+    }
     /**
      * Update the shell configuration.
      *
@@ -1113,7 +1263,9 @@ var Private;
          * Construct a new side bar handler.
          */
         constructor() {
+            this._isHiddenByUser = false;
             this._items = new Array();
+            this._updated = new Signal(this);
             this._sideBar = new TabBar({
                 insertBehavior: 'none',
                 removeBehavior: 'none',
@@ -1128,6 +1280,12 @@ var Private;
             this._sideBar.tabActivateRequested.connect(this._onTabActivateRequested, this);
             this._stackedPanel.widgetRemoved.connect(this._onWidgetRemoved, this);
         }
+        /**
+         * Whether the side bar is visible
+         */
+        get isVisible() {
+            return this._sideBar.isVisible;
+        }
         /**
          * Get the tab bar managed by the handler.
          */
@@ -1140,6 +1298,12 @@ var Private;
         get stackedPanel() {
             return this._stackedPanel;
         }
+        /**
+         * Signal fires when the stack panel or the sidebar changes
+         */
+        get updated() {
+            return this._updated;
+        }
         /**
          * Expand the sidebar.
          *
@@ -1212,7 +1376,12 @@ var Private;
             const collapsed = this._sideBar.currentTitle === null;
             const widgets = toArray(this._stackedPanel.widgets);
             const currentWidget = widgets[this._sideBar.currentIndex];
-            return { collapsed, currentWidget, widgets };
+            return {
+                collapsed,
+                currentWidget,
+                visible: !this._isHiddenByUser,
+                widgets
+            };
         }
         /**
          * Rehydrate the side bar.
@@ -1224,6 +1393,23 @@ var Private;
             if (data.collapsed) {
                 this.collapse();
             }
+            if (!data.visible) {
+                this.hide();
+            }
+        }
+        /**
+         * Hide the side bar even if it contains widgets
+         */
+        hide() {
+            this._isHiddenByUser = true;
+            this._refreshVisibility();
+        }
+        /**
+         * Show the side bar if it contains widgets
+         */
+        show() {
+            this._isHiddenByUser = false;
+            this._refreshVisibility();
         }
         /**
          * Find the insertion index for a rank item.
@@ -1255,8 +1441,9 @@ var Private;
          * Refresh the visibility of the side bar and stacked panel.
          */
         _refreshVisibility() {
-            this._sideBar.setHidden(this._sideBar.titles.length === 0);
             this._stackedPanel.setHidden(this._sideBar.currentTitle === null);
+            this._sideBar.setHidden(this._isHiddenByUser || this._sideBar.titles.length === 0);
+            this._updated.emit();
         }
         /**
          * Handle the `currentChanged` signal from the sidebar.