@jupyterlab/notebook-extension 4.7.0-alpha.0 → 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

@@ -31,7 +31,7 @@ import { ITableOfContentsRegistry } from '@jupyterlab/toc';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 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';
@@ -62,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';
@@ -156,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.
  */
@@ -378,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;
@@ -455,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'));
+                }
+            }
+        };
     }
 };
 /**
@@ -902,6 +1000,7 @@ const plugins = [
     trackerPlugin,
     pageHandlerPlugin,
     executionIndicator,
+    exportGuidanceDialogPlugin,
     exportPlugin,
     tools,
     cellCounterItem,
@@ -1643,13 +1742,17 @@ function activateNotebookHandler(app, factory, extensions, executor, palette, de
         setSideBySideOutputRatio(factory.notebookConfig.sideBySideOutputRatio);
         const sideBySideMarginStyle = `.jp-mod-sideBySide.jp-Notebook .jp-Notebook-cell {
       margin-left: ${factory.notebookConfig.sideBySideLeftMarginOverride} !important;
-      margin-right: ${factory.notebookConfig.sideBySideRightMarginOverride} !important;`;
+      margin-right: ${factory.notebookConfig.sideBySideRightMarginOverride} !important;
+    }`;
         const sideBySideMarginTag = document.getElementById(SIDE_BY_SIDE_STYLE_ID);
         if (sideBySideMarginTag) {
-            sideBySideMarginTag.innerText = sideBySideMarginStyle;
+            sideBySideMarginTag.textContent = sideBySideMarginStyle;
         }
         else {
-            document.head.insertAdjacentHTML('beforeend', `<style id="${SIDE_BY_SIDE_STYLE_ID}">${sideBySideMarginStyle}}</style>`);
+            const style = document.createElement('style');
+            style.id = SIDE_BY_SIDE_STYLE_ID;
+            style.textContent = sideBySideMarginStyle;
+            document.head.appendChild(style);
         }
         factory.autoStartDefault = settings.get('autoStartDefaultKernel')
             .composite;