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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/notebook-extension",
-  "version": "4.6.2",
+  "version": "4.7.0-alpha.1",
   "description": "JupyterLab - Notebook Extension",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -37,43 +37,44 @@
   },
   "dependencies": {
     "@jupyter/ydoc": "^4.0.0",
-    "@jupyterlab/application": "^4.6.2",
-    "@jupyterlab/apputils": "^4.7.2",
-    "@jupyterlab/cell-toolbar": "^4.6.2",
-    "@jupyterlab/cells": "^4.6.2",
-    "@jupyterlab/codeeditor": "^4.6.2",
-    "@jupyterlab/codemirror": "^4.6.2",
-    "@jupyterlab/completer": "^4.6.2",
-    "@jupyterlab/coreutils": "^6.6.2",
-    "@jupyterlab/docmanager": "^4.6.2",
-    "@jupyterlab/docmanager-extension": "^4.6.2",
-    "@jupyterlab/docregistry": "^4.6.2",
-    "@jupyterlab/documentsearch": "^4.6.2",
-    "@jupyterlab/filebrowser": "^4.6.2",
-    "@jupyterlab/launcher": "^4.6.2",
-    "@jupyterlab/logconsole": "^4.6.2",
-    "@jupyterlab/lsp": "^4.6.2",
-    "@jupyterlab/mainmenu": "^4.6.2",
-    "@jupyterlab/metadataform": "^4.6.2",
-    "@jupyterlab/nbformat": "^4.6.2",
-    "@jupyterlab/notebook": "^4.6.2",
-    "@jupyterlab/observables": "^5.6.2",
-    "@jupyterlab/property-inspector": "^4.6.2",
-    "@jupyterlab/rendermime": "^4.6.2",
-    "@jupyterlab/services": "^7.6.2",
-    "@jupyterlab/settingregistry": "^4.6.2",
-    "@jupyterlab/statedb": "^4.6.2",
-    "@jupyterlab/statusbar": "^4.6.2",
-    "@jupyterlab/toc": "^6.6.2",
-    "@jupyterlab/translation": "^4.6.2",
-    "@jupyterlab/ui-components": "^4.6.2",
-    "@lumino/algorithm": "^2.0.4",
-    "@lumino/commands": "^2.3.3",
-    "@lumino/coreutils": "^2.2.2",
-    "@lumino/disposable": "^2.1.5",
-    "@lumino/messaging": "^2.0.4",
-    "@lumino/polling": "^2.1.5",
-    "@lumino/widgets": "^2.8.0",
+    "@jupyterlab/application": "^4.7.0-alpha.1",
+    "@jupyterlab/apputils": "^4.8.0-alpha.1",
+    "@jupyterlab/cell-toolbar": "^4.7.0-alpha.1",
+    "@jupyterlab/cells": "^4.7.0-alpha.1",
+    "@jupyterlab/codeeditor": "^4.7.0-alpha.1",
+    "@jupyterlab/codemirror": "^4.7.0-alpha.1",
+    "@jupyterlab/completer": "^4.7.0-alpha.1",
+    "@jupyterlab/coreutils": "^6.7.0-alpha.1",
+    "@jupyterlab/docmanager": "^4.7.0-alpha.1",
+    "@jupyterlab/docmanager-extension": "^4.7.0-alpha.1",
+    "@jupyterlab/docregistry": "^4.7.0-alpha.1",
+    "@jupyterlab/documentsearch": "^4.7.0-alpha.1",
+    "@jupyterlab/filebrowser": "^4.7.0-alpha.1",
+    "@jupyterlab/launcher": "^4.7.0-alpha.1",
+    "@jupyterlab/logconsole": "^4.7.0-alpha.1",
+    "@jupyterlab/lsp": "^4.7.0-alpha.1",
+    "@jupyterlab/mainmenu": "^4.7.0-alpha.1",
+    "@jupyterlab/metadataform": "^4.7.0-alpha.1",
+    "@jupyterlab/nbformat": "^4.7.0-alpha.1",
+    "@jupyterlab/notebook": "^4.7.0-alpha.1",
+    "@jupyterlab/observables": "^5.7.0-alpha.1",
+    "@jupyterlab/outputarea": "^4.7.0-alpha.1",
+    "@jupyterlab/property-inspector": "^4.7.0-alpha.1",
+    "@jupyterlab/rendermime": "^4.7.0-alpha.1",
+    "@jupyterlab/services": "^7.7.0-alpha.1",
+    "@jupyterlab/settingregistry": "^4.7.0-alpha.1",
+    "@jupyterlab/statedb": "^4.7.0-alpha.1",
+    "@jupyterlab/statusbar": "^4.7.0-alpha.1",
+    "@jupyterlab/toc": "^6.7.0-alpha.1",
+    "@jupyterlab/translation": "^4.7.0-alpha.1",
+    "@jupyterlab/ui-components": "^4.7.0-alpha.1",
+    "@lumino/algorithm": "^2.0.5",
+    "@lumino/commands": "^2.3.4",
+    "@lumino/coreutils": "^2.2.3",
+    "@lumino/disposable": "^2.1.6",
+    "@lumino/messaging": "^2.0.5",
+    "@lumino/polling": "^2.1.6",
+    "@lumino/widgets": "^2.9.0",
     "@rjsf/utils": "^5.13.4",
     "react": "^18.2.0"
   },

package/schema/tracker.json

@@ -899,6 +899,12 @@
       "description": "When enabled, pasting code cells will only paste the cell content, not the outputs.",
       "type": "boolean",
       "default": false
+    },
+    "helpInBottomPanel": {
+      "title": "Show Help in Bottom Panel",
+      "description": "Whether to display help output (e.g. pager output from 'source: page' payloads) in a bottom panel inspector instead of inlining it.",
+      "type": "boolean",
+      "default": false
     }
   },
   "additionalProperties": false,

package/src/index.ts

@@ -90,9 +90,14 @@ import {
   ToolbarItems
 } from '@jupyterlab/notebook';
 import type { IObservableList } from '@jupyterlab/observables';
+import { IPageHandler } from '@jupyterlab/outputarea';
 import { IPropertyInspectorProvider } from '@jupyterlab/property-inspector';
+import {
+  IMarkdownParser,
+  IRenderMimeRegistry,
+  MimeModel
+} from '@jupyterlab/rendermime';
 import type { IRenderMime } from '@jupyterlab/rendermime';
-import { IMarkdownParser, IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { NbConvert } from '@jupyterlab/services';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { IStateDB } from '@jupyterlab/statedb';
@@ -113,6 +118,7 @@ import {
   duplicateIcon,
   fastForwardIcon,
   IFormRendererRegistry,
+  infoIcon,
   moveDownIcon,
   moveUpIcon,
   notebookIcon,
@@ -125,10 +131,11 @@ import { ArrayExt } from '@lumino/algorithm';
 import type { CommandRegistry } from '@lumino/commands';
 import type {
   JSONObject,
+  ReadonlyJSONObject,
   ReadonlyJSONValue,
   ReadonlyPartialJSONObject
 } from '@lumino/coreutils';
-import { JSONExt, UUID } from '@lumino/coreutils';
+import { JSONExt, Token, UUID } from '@lumino/coreutils';
 import type { IDisposable } from '@lumino/disposable';
 import { DisposableSet } from '@lumino/disposable';
 import type { Message } from '@lumino/messaging';
@@ -182,6 +189,8 @@ namespace CommandIDs {
 
   export const exportToFormat = 'notebook:export-to-format';
 
+  export const showExportGuidance = 'notebook:show-export-guidance';
+
   export const run = 'notebook:run-cell';
 
   export const runAndAdvance = 'notebook:run-cell-and-select-next';
@@ -365,6 +374,30 @@ const FACTORY = 'Notebook';
  */
 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';
+
+/**
+ * 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 const INotebookExportGuidance = new Token<INotebookExportGuidance>(
+  '@jupyterlab/notebook-extension:INotebookExportGuidance',
+  'A service for showing notebook export guidance.'
+);
+
 /**
  * Setting Id storing the customized toolbar definition.
  */
@@ -641,13 +674,14 @@ export const exportPlugin: JupyterFrontEndPlugin<void> = {
   description: 'Adds the export notebook commands.',
   autoStart: true,
   requires: [ITranslator, INotebookTracker],
-  optional: [IMainMenu, ICommandPalette],
+  optional: [IMainMenu, ICommandPalette, INotebookExportGuidance],
   activate: (
     app: JupyterFrontEnd,
     translator: ITranslator,
     tracker: INotebookTracker,
     mainMenu: IMainMenu | null,
-    palette: ICommandPalette | null
+    palette: ICommandPalette | null,
+    exportGuidance: INotebookExportGuidance | null
   ) => {
     const trans = translator.load('jupyterlab');
     const { commands, shell } = app;
@@ -738,21 +772,91 @@ export const exportPlugin: JupyterFrontEndPlugin<void> = {
       }
     });
 
+    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: Menu | null | undefined;
-    if (mainMenu) {
-      exportTo = mainMenu.fileMenu.items.find(
-        item =>
-          item.type === 'submenu' &&
-          item.submenu?.id === 'jp-mainmenu-file-notebookexport'
-      )?.submenu;
-    }
+    const fileMenu = mainMenu?.fileMenu as Menu | undefined;
+
+    const getExportMenu = (): Menu | undefined => {
+      return (
+        fileMenu?.items.find(
+          item =>
+            item.type === 'submenu' &&
+            item.submenu?.id === 'jp-mainmenu-file-notebookexport'
+        )?.submenu ?? undefined
+      );
+    };
 
     let formatsInitialized = false;
+    let paletteInitialized = false;
+    let exportFormats: Array<{ format: string; label: string }> | null = 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;
       }
 
@@ -760,53 +864,96 @@ export const exportPlugin: JupyterFrontEndPlugin<void> = {
 
       formatsInitialized = true;
 
-      const response = await services.nbconvert.getExportFormats(false);
-
-      if (!response) {
-        return;
+      let response: NbConvert.IExportFormats | null = null;
+      try {
+        response = await services.nbconvert.getExportFormats(false);
+      } catch {
+        // Ignore fetch errors and fallback to export guidance.
       }
 
-      const formatLabels: any = Private.getFormatLabels(translator);
+      const formatLabels = Private.getFormatLabels(translator);
 
-      // Convert export list to palette and menu items.
-      const formatList = Object.keys(response);
-      formatList.forEach(function (key) {
-        const formattedKey = key[0].toLocaleUpperCase() + key.slice(1);
-        const capCaseKey = trans.__(formattedKey);
-        const labelStr = formatLabels[key] ? formatLabels[key] : capCaseKey;
-        let args = {
-          format: key,
-          label: labelStr,
-          isPalette: false
-        };
-        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
-            });
-          }
-        }
-      });
+      // Convert export list to menu and palette items.
+      exportFormats = Object.keys(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;
+          return {
+            format: key,
+            label: labelStr
+          };
+        });
+
+      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: JupyterFrontEndPlugin<INotebookExportGuidance> =
+  {
+    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: JupyterFrontEnd,
+      translator: ITranslator
+    ): INotebookExportGuidance => {
+      const trans = translator.load('jupyterlab');
+      const { commands } = app;
+
+      const openExportDocs = (url: string, docsLabel: string) => {
+        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')
+            );
+          }
+        }
+      };
+    }
+  };
+
 /**
  * A plugin that adds a notebook trust status item to the status bar.
  */
@@ -864,11 +1011,29 @@ const widgetFactoryPlugin: JupyterFrontEndPlugin<NotebookWidgetFactory.IFactory>
       IRenderMimeRegistry,
       IToolbarWidgetRegistry
     ],
-    optional: [ISettingRegistry, ISessionContextDialogs, ITranslator],
+    optional: [
+      ISettingRegistry,
+      ISessionContextDialogs,
+      ITranslator,
+      IPageHandler
+    ],
     activate: activateWidgetFactory,
     autoStart: true
   };
 
+/**
+ * The pager output handler provider.
+ */
+const pageHandlerPlugin: JupyterFrontEndPlugin<IPageHandler> = {
+  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.
  */
@@ -1288,7 +1453,9 @@ const plugins: JupyterFrontEndPlugin<any>[] = [
   cellExecutor,
   factory,
   trackerPlugin,
+  pageHandlerPlugin,
   executionIndicator,
+  exportGuidanceDialogPlugin,
   exportPlugin,
   tools,
   cellCounterItem,
@@ -1363,6 +1530,86 @@ function activateNotebookTools(
   return notebookTools;
 }
 
+/**
+ * Activate the pager output handler provider.
+ */
+function activatePageHandler(
+  app: JupyterFrontEnd,
+  rendermime: IRenderMimeRegistry,
+  settingRegistry: ISettingRegistry | null,
+  translator_: ITranslator | null
+): IPageHandler {
+  const translator = translator_ ?? nullTranslator;
+  const trans = translator.load('jupyterlab');
+
+  let helpInBottomPanel = false;
+  let helpWidget: MainAreaWidget<Panel> | null = null;
+
+  const fetchSettings = settingRegistry
+    ? settingRegistry.load(trackerPlugin.id)
+    : Promise.reject(new Error(`No setting registry for ${trackerPlugin.id}`));
+
+  const updateConfig = (settings: ISettingRegistry.ISettings): void => {
+    helpInBottomPanel = settings.get('helpInBottomPanel').composite as boolean;
+  };
+
+  void fetchSettings
+    .then(settings => {
+      updateConfig(settings);
+      settings.changed.connect(() => {
+        updateConfig(settings);
+      });
+    })
+    .catch((reason: Error) => {
+      console.warn(reason.message);
+    });
+
+  return {
+    handlePage: payload => {
+      if (!helpInBottomPanel) {
+        return false;
+      }
+
+      const data = payload['data'];
+      if (!data || typeof data !== 'object') {
+        return false;
+      }
+
+      const mimeData = data as nbformat.IMimeBundle;
+      const metadata = (payload['metadata'] ?? {}) as ReadonlyJSONObject;
+      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.
  */
@@ -1374,7 +1621,8 @@ function activateWidgetFactory(
   toolbarRegistry: IToolbarWidgetRegistry,
   settingRegistry: ISettingRegistry | null,
   sessionContextDialogs_: ISessionContextDialogs | null,
-  translator_: ITranslator | null
+  translator_: ITranslator | null,
+  pageHandler: IPageHandler | null
 ): NotebookWidgetFactory.IFactory {
   const translator = translator_ ?? nullTranslator;
   const sessionContextDialogs =
@@ -1455,6 +1703,7 @@ function activateWidgetFactory(
     contentFactory,
     editorConfig: StaticNotebook.defaultEditorConfig,
     notebookConfig: StaticNotebook.defaultNotebookConfig,
+    pageHandler: pageHandler ?? undefined,
     mimeTypeService: editorServices.mimeTypeService,
     toolbarFactory,
     translator
@@ -1921,6 +2170,7 @@ function activateNotebookHandler(
   fetchSettings
     .then(settings => {
       updateConfig(settings);
+
       settings.changed.connect(() => {
         updateConfig(settings);
         commands.notifyCommandChanged(CommandIDs.virtualScrollbar);

package/style/index.css

@@ -16,6 +16,7 @@
 @import url('~@jupyterlab/codemirror/style/index.css');
 @import url('~@jupyterlab/docmanager/style/index.css');
 @import url('~@jupyterlab/filebrowser/style/index.css');
+@import url('~@jupyterlab/outputarea/style/index.css');
 @import url('~@jupyterlab/toc/style/index.css');
 @import url('~@jupyterlab/cells/style/index.css');
 @import url('~@jupyterlab/lsp/style/index.css');

package/style/index.js

@@ -16,6 +16,7 @@ import '@jupyterlab/documentsearch/style/index.js';
 import '@jupyterlab/codemirror/style/index.js';
 import '@jupyterlab/docmanager/style/index.js';
 import '@jupyterlab/filebrowser/style/index.js';
+import '@jupyterlab/outputarea/style/index.js';
 import '@jupyterlab/toc/style/index.js';
 import '@jupyterlab/cells/style/index.js';
 import '@jupyterlab/lsp/style/index.js';