@jupyterlab/notebook-extension 4.6.2 → 4.7.0-alpha.1

package/lib/index.d.ts

@@ -3,6 +3,20 @@
  * @module notebook-extension
  */
 import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { Token } from '@lumino/coreutils';
+/**
+ * An interface describing how export guidance is presented to users.
+ */
+export interface INotebookExportGuidance {
+    /**
+     * Show guidance for enabling notebook exports.
+     */
+    showExportHelp(): Promise<void>;
+}
+/**
+ * A token describing a service for showing notebook export guidance.
+ */
+export declare const INotebookExportGuidance: Token<INotebookExportGuidance>;
 /**
  * A plugin providing a CommandEdit status item.
  */
@@ -19,6 +33,10 @@ export declare const executionIndicator: JupyterFrontEndPlugin<void>;
  * A plugin providing export commands in the main menu and command palette
  */
 export declare const exportPlugin: JupyterFrontEndPlugin<void>;
+/**
+ * A plugin providing the default notebook export guidance service.
+ */
+export declare const exportGuidanceDialogPlugin: JupyterFrontEndPlugin<INotebookExportGuidance>;
 /**
  * A plugin that adds a notebook trust status item to the status bar.
  */

package/lib/index.js

@@ -21,16 +21,17 @@ import { ILSPCodeExtractorsManager, ILSPDocumentConnectionManager, ILSPFeatureMa
 import { IMainMenu } from '@jupyterlab/mainmenu';
 import { IMetadataFormProvider } from '@jupyterlab/metadataform';
 import { CellCounterStatus, CommandEditStatus, ExecutionIndicator, INotebookCellExecutor, INotebookTools, INotebookTracker, INotebookWidgetFactory, NotebookActions, NotebookAdapter, NotebookModelFactory, NotebookPanel, NotebookSearchProvider, NotebookToCFactory, NotebookTools, NotebookTracker, NotebookTrustStatus, NotebookWidgetFactory, setCellExecutor, StaticNotebook, ToolbarItems } from '@jupyterlab/notebook';
+import { IPageHandler } from '@jupyterlab/outputarea';
 import { IPropertyInspectorProvider } from '@jupyterlab/property-inspector';
-import { IMarkdownParser, IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { IMarkdownParser, IRenderMimeRegistry, MimeModel } from '@jupyterlab/rendermime';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { IStateDB } from '@jupyterlab/statedb';
 import { IStatusBar } from '@jupyterlab/statusbar';
 import { ITableOfContentsRegistry } from '@jupyterlab/toc';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
-import { addAboveIcon, addBelowIcon, buildIcon, copyIcon, cutIcon, duplicateIcon, fastForwardIcon, IFormRendererRegistry, moveDownIcon, moveUpIcon, notebookIcon, pasteIcon, refreshIcon, runIcon, stopIcon } from '@jupyterlab/ui-components';
+import { addAboveIcon, addBelowIcon, buildIcon, copyIcon, cutIcon, duplicateIcon, fastForwardIcon, IFormRendererRegistry, infoIcon, moveDownIcon, moveUpIcon, notebookIcon, pasteIcon, refreshIcon, runIcon, stopIcon } from '@jupyterlab/ui-components';
 import { ArrayExt } from '@lumino/algorithm';
-import { JSONExt, UUID } from '@lumino/coreutils';
+import { JSONExt, Token, UUID } from '@lumino/coreutils';
 import { DisposableSet } from '@lumino/disposable';
 import { MessageLoop } from '@lumino/messaging';
 import { Panel } from '@lumino/widgets';
@@ -61,6 +62,7 @@ var CommandIDs;
     CommandIDs.closeAndShutdown = 'notebook:close-and-shutdown';
     CommandIDs.trust = 'notebook:trust';
     CommandIDs.exportToFormat = 'notebook:export-to-format';
+    CommandIDs.showExportGuidance = 'notebook:show-export-guidance';
     CommandIDs.run = 'notebook:run-cell';
     CommandIDs.runAndAdvance = 'notebook:run-cell-and-select-next';
     CommandIDs.runAndInsert = 'notebook:run-cell-and-insert-below';
@@ -155,6 +157,14 @@ const FACTORY = 'Notebook';
  * (returned from nbconvert's export list)
  */
 const FORMAT_EXCLUDE = ['notebook', 'python', 'custom'];
+/**
+ * Documentation page describing notebook export support.
+ */
+const NOTEBOOK_EXPORT_DOCS_URL = 'https://jupyterlab.readthedocs.io/en/stable/user/export.html';
+/**
+ * A token describing a service for showing notebook export guidance.
+ */
+export const INotebookExportGuidance = new Token('@jupyterlab/notebook-extension:INotebookExportGuidance', 'A service for showing notebook export guidance.');
 /**
  * Setting Id storing the customized toolbar definition.
  */
@@ -377,9 +387,8 @@ export const exportPlugin = {
     description: 'Adds the export notebook commands.',
     autoStart: true,
     requires: [ITranslator, INotebookTracker],
-    optional: [IMainMenu, ICommandPalette],
-    activate: (app, translator, tracker, mainMenu, palette) => {
-        var _a;
+    optional: [IMainMenu, ICommandPalette, INotebookExportGuidance],
+    activate: (app, translator, tracker, mainMenu, palette, exportGuidance) => {
         const trans = translator.load('jupyterlab');
         const { commands, shell } = app;
         const services = app.serviceManager;
@@ -454,63 +463,153 @@ export const exportPlugin = {
                 }
             }
         });
+        commands.addCommand(CommandIDs.showExportGuidance, {
+            label: trans.__('Enable notebook exports'),
+            execute: () => {
+                if (exportGuidance) {
+                    return exportGuidance.showExportHelp();
+                }
+                window.open(NOTEBOOK_EXPORT_DOCS_URL, '_blank', 'noopener,noreferrer');
+                return undefined;
+            },
+            describedBy: {
+                args: {
+                    type: 'object',
+                    properties: {}
+                }
+            }
+        });
         // Add a notebook group to the File menu.
-        let exportTo;
-        if (mainMenu) {
-            exportTo = (_a = mainMenu.fileMenu.items.find(item => {
+        const fileMenu = mainMenu === null || mainMenu === void 0 ? void 0 : mainMenu.fileMenu;
+        const getExportMenu = () => {
+            var _a, _b;
+            return ((_b = (_a = fileMenu === null || fileMenu === void 0 ? void 0 : fileMenu.items.find(item => {
                 var _a;
                 return item.type === 'submenu' &&
                     ((_a = item.submenu) === null || _a === void 0 ? void 0 : _a.id) === 'jp-mainmenu-file-notebookexport';
-            })) === null || _a === void 0 ? void 0 : _a.submenu;
-        }
+            })) === null || _a === void 0 ? void 0 : _a.submenu) !== null && _b !== void 0 ? _b : undefined);
+        };
         let formatsInitialized = false;
+        let paletteInitialized = false;
+        let exportFormats = null;
+        const updateExportMenu = () => {
+            const exportTo = getExportMenu();
+            if (!exportTo || !exportFormats) {
+                return;
+            }
+            exportTo.clearItems();
+            if (exportFormats.length === 0) {
+                exportTo.addItem({
+                    command: CommandIDs.showExportGuidance
+                });
+                return;
+            }
+            exportFormats.forEach(({ format, label }) => {
+                exportTo.addItem({
+                    command: CommandIDs.exportToFormat,
+                    args: {
+                        format,
+                        label,
+                        isPalette: false
+                    }
+                });
+            });
+            if (palette && !paletteInitialized) {
+                const category = trans.__('Notebook Operations');
+                exportFormats.forEach(({ format, label }) => {
+                    palette.addItem({
+                        command: CommandIDs.exportToFormat,
+                        category,
+                        args: {
+                            format,
+                            label,
+                            isPalette: true
+                        }
+                    });
+                });
+                paletteInitialized = true;
+            }
+        };
         /** Request formats only when a notebook might use them. */
         const maybeInitializeFormats = async () => {
             if (formatsInitialized) {
+                updateExportMenu();
+                return;
+            }
+            if (tracker.size === 0) {
                 return;
             }
             tracker.widgetAdded.disconnect(maybeInitializeFormats);
             formatsInitialized = true;
-            const response = await services.nbconvert.getExportFormats(false);
-            if (!response) {
-                return;
+            let response = null;
+            try {
+                response = await services.nbconvert.getExportFormats(false);
+            }
+            catch (_a) {
+                // Ignore fetch errors and fallback to export guidance.
             }
             const formatLabels = Private.getFormatLabels(translator);
-            // Convert export list to palette and menu items.
-            const formatList = Object.keys(response);
-            formatList.forEach(function (key) {
+            // Convert export list to menu and palette items.
+            exportFormats = Object.keys(response !== null && response !== void 0 ? response : {})
+                .filter(key => !FORMAT_EXCLUDE.includes(key))
+                .map(key => {
                 const formattedKey = key[0].toLocaleUpperCase() + key.slice(1);
                 const capCaseKey = trans.__(formattedKey);
                 const labelStr = formatLabels[key] ? formatLabels[key] : capCaseKey;
-                let args = {
+                return {
                     format: key,
-                    label: labelStr,
-                    isPalette: false
+                    label: labelStr
                 };
-                if (FORMAT_EXCLUDE.indexOf(key) === -1) {
-                    if (exportTo) {
-                        exportTo.addItem({
-                            command: CommandIDs.exportToFormat,
-                            args: args
-                        });
-                    }
-                    if (palette) {
-                        args = {
-                            format: key,
-                            label: labelStr,
-                            isPalette: true
-                        };
-                        const category = trans.__('Notebook Operations');
-                        palette.addItem({
-                            command: CommandIDs.exportToFormat,
-                            category,
-                            args
-                        });
-                    }
-                }
             });
+            updateExportMenu();
         };
         tracker.widgetAdded.connect(maybeInitializeFormats);
+        if (tracker.size > 0) {
+            void maybeInitializeFormats();
+        }
+        void app.restored.then(() => {
+            void maybeInitializeFormats();
+        });
+    }
+};
+/**
+ * A plugin providing the default notebook export guidance service.
+ */
+export const exportGuidanceDialogPlugin = {
+    id: '@jupyterlab/notebook-extension:export-guidance-dialog',
+    description: 'Provides the default notebook export guidance shown when no exporters are available.',
+    provides: INotebookExportGuidance,
+    autoStart: true,
+    requires: [ITranslator],
+    activate: (app, translator) => {
+        const trans = translator.load('jupyterlab');
+        const { commands } = app;
+        const openExportDocs = (url, docsLabel) => {
+            if (commands.hasCommand('help:open')) {
+                return commands.execute('help:open', {
+                    url,
+                    text: docsLabel,
+                    newBrowserTab: true
+                });
+            }
+            window.open(url, '_blank', 'noopener,noreferrer');
+            return undefined;
+        };
+        return {
+            showExportHelp: async () => {
+                const result = await showDialog({
+                    title: trans.__('Notebook exports are unavailable'),
+                    body: trans.__('No notebook export formats are currently available. To enable exports, install nbconvert in the server environment or use another exporter supported by your deployment.'),
+                    buttons: [
+                        Dialog.cancelButton({ label: trans.__('Close') }),
+                        Dialog.okButton({ label: trans.__('Open Documentation') })
+                    ]
+                });
+                if (result.button.accept) {
+                    void openExportDocs(NOTEBOOK_EXPORT_DOCS_URL, trans.__('Notebook Export Documentation'));
+                }
+            }
+        };
     }
 };
 /**
@@ -557,10 +656,27 @@ const widgetFactoryPlugin = {
         IRenderMimeRegistry,
         IToolbarWidgetRegistry
     ],
-    optional: [ISettingRegistry, ISessionContextDialogs, ITranslator],
+    optional: [
+        ISettingRegistry,
+        ISessionContextDialogs,
+        ITranslator,
+        IPageHandler
+    ],
     activate: activateWidgetFactory,
     autoStart: true
 };
+/**
+ * The pager output handler provider.
+ */
+const pageHandlerPlugin = {
+    id: '@jupyterlab/notebook-extension:page-handler',
+    description: 'Provides a handler for pager output payloads.',
+    autoStart: true,
+    provides: IPageHandler,
+    requires: [IRenderMimeRegistry],
+    optional: [ISettingRegistry, ITranslator],
+    activate: activatePageHandler
+};
 /**
  * The cloned output provider.
  */
@@ -882,7 +998,9 @@ const plugins = [
     cellExecutor,
     factory,
     trackerPlugin,
+    pageHandlerPlugin,
     executionIndicator,
+    exportGuidanceDialogPlugin,
     exportPlugin,
     tools,
     cellCounterItem,
@@ -943,10 +1061,72 @@ function activateNotebookTools(app, tracker, editorServices, languages, state, t
     }
     return notebookTools;
 }
+/**
+ * Activate the pager output handler provider.
+ */
+function activatePageHandler(app, rendermime, settingRegistry, translator_) {
+    const translator = translator_ !== null && translator_ !== void 0 ? translator_ : nullTranslator;
+    const trans = translator.load('jupyterlab');
+    let helpInBottomPanel = false;
+    let helpWidget = null;
+    const fetchSettings = settingRegistry
+        ? settingRegistry.load(trackerPlugin.id)
+        : Promise.reject(new Error(`No setting registry for ${trackerPlugin.id}`));
+    const updateConfig = (settings) => {
+        helpInBottomPanel = settings.get('helpInBottomPanel').composite;
+    };
+    void fetchSettings
+        .then(settings => {
+        updateConfig(settings);
+        settings.changed.connect(() => {
+            updateConfig(settings);
+        });
+    })
+        .catch((reason) => {
+        console.warn(reason.message);
+    });
+    return {
+        handlePage: payload => {
+            var _a;
+            if (!helpInBottomPanel) {
+                return false;
+            }
+            const data = payload['data'];
+            if (!data || typeof data !== 'object') {
+                return false;
+            }
+            const mimeData = data;
+            const metadata = ((_a = payload['metadata']) !== null && _a !== void 0 ? _a : {});
+            const mimeType = rendermime.preferredMimeType(mimeData, 'any');
+            if (!mimeType) {
+                return false;
+            }
+            if (!helpWidget || helpWidget.isDisposed) {
+                const content = new Panel();
+                content.addClass('jp-HelpPanel');
+                helpWidget = new MainAreaWidget({ content });
+                helpWidget.id = 'jp-help-panel';
+                helpWidget.title.label = trans.__('Help');
+                helpWidget.title.icon = infoIcon;
+                helpWidget.title.closable = true;
+            }
+            const content = helpWidget.content;
+            content.widgets.forEach(widget => widget.dispose());
+            const renderer = rendermime.createRenderer(mimeType);
+            void renderer.renderModel(new MimeModel({ data: mimeData, metadata, trusted: true }));
+            content.addWidget(renderer);
+            if (!helpWidget.isAttached) {
+                app.shell.add(helpWidget, 'down');
+            }
+            app.shell.activateById(helpWidget.id);
+            return true;
+        }
+    };
+}
 /**
  * Activate the notebook widget factory.
  */
-function activateWidgetFactory(app, contentFactory, editorServices, rendermime, toolbarRegistry, settingRegistry, sessionContextDialogs_, translator_) {
+function activateWidgetFactory(app, contentFactory, editorServices, rendermime, toolbarRegistry, settingRegistry, sessionContextDialogs_, translator_, pageHandler) {
     const translator = translator_ !== null && translator_ !== void 0 ? translator_ : nullTranslator;
     const sessionContextDialogs = sessionContextDialogs_ !== null && sessionContextDialogs_ !== void 0 ? sessionContextDialogs_ : new SessionContextDialogs({ translator });
     const preferKernelOption = PageConfig.getOption('notebookStartsKernel');
@@ -985,6 +1165,7 @@ function activateWidgetFactory(app, contentFactory, editorServices, rendermime,
         contentFactory,
         editorConfig: StaticNotebook.defaultEditorConfig,
         notebookConfig: StaticNotebook.defaultNotebookConfig,
+        pageHandler: pageHandler !== null && pageHandler !== void 0 ? pageHandler : undefined,
         mimeTypeService: editorServices.mimeTypeService,
         toolbarFactory,
         translator