@jupyterlab/notebook-extension 4.7.0-alpha.0 → 4.7.0-alpha.2

package/src/index.ts

@@ -16,6 +16,7 @@ import { ILabShell, ILayoutRestorer, IRouter } from '@jupyterlab/application';
 import type { ISessionContext } from '@jupyterlab/apputils';
 import {
   Clipboard,
+  CommandLinker,
   createToolbarFactory,
   Dialog,
   ICommandPalette,
@@ -135,7 +136,7 @@ import type {
   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';
@@ -145,7 +146,10 @@ import { Panel } from '@lumino/widgets';
 import { CellBarExtension } from '@jupyterlab/cell-toolbar';
 import { cellExecutor } from './cellexecutor';
 import { logNotebookOutput } from './nboutput';
-import { ActiveCellTool } from './tool-widgets/activeCellToolWidget';
+import {
+  ActiveCellTool,
+  CellIdField
+} from './tool-widgets/activeCellToolWidget';
 import {
   CellMetadataField,
   NotebookMetadataField
@@ -189,6 +193,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';
@@ -372,6 +378,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.
  */
@@ -648,13 +678,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;
@@ -745,21 +776,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;
       }
 
@@ -767,53 +868,99 @@ 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);
+          // Fallback for export formats the server offers but `formatLabels`
+          // does not know about, so there is no literal to extract.
+          // eslint-disable-next-line jupyter/no-dynamic-translation
+          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.
  */
@@ -1139,6 +1286,9 @@ const updateRawMimetype: JupyterFrontEndPlugin<void> = {
           ).length > 0;
         if (!mimetypeExists) {
           const formattedKey = key[0].toLocaleUpperCase() + key.slice(1);
+          // Fallback for export formats the server offers but `formatLabels`
+          // does not know about, so there is no literal to extract.
+          // eslint-disable-next-line jupyter/no-dynamic-translation
           const altOption = trans.__(formattedKey);
           const option = formatLabels[key] ? formatLabels[key] : altOption;
           const mimeTypeValue = response[key].output_mimetype;
@@ -1176,15 +1326,20 @@ const customMetadataEditorFields: JupyterFrontEndPlugin<void> = {
   ) => {
     const editorFactory: CodeEditor.Factory = options =>
       editorServices.factoryService.newInlineEditor(options);
-    // Register the custom fields.
+    // Register the custom fields. As with the active cell tool below, the
+    // field renderers are used by rjsf as React components, so they run on
+    // every rebuild of the metadata form. Each field is created once and
+    // reused: constructing one per render abandons an editor, its host node
+    // and its listeners on every keystroke that rebuilds the form.
+    const cellMetadataField = new CellMetadataField({
+      editorFactory,
+      tracker,
+      label: 'Cell metadata',
+      translator: translator
+    });
     const cellComponent: IFormRenderer = {
       fieldRenderer: (props: FieldProps) => {
-        return new CellMetadataField({
-          editorFactory,
-          tracker,
-          label: 'Cell metadata',
-          translator: translator
-        }).render(props);
+        return cellMetadataField.render(props);
       }
     };
     formRegistry.addRenderer(
@@ -1192,14 +1347,15 @@ const customMetadataEditorFields: JupyterFrontEndPlugin<void> = {
       cellComponent
     );
 
+    const notebookMetadataField = new NotebookMetadataField({
+      editorFactory,
+      tracker,
+      label: 'Notebook metadata',
+      translator: translator
+    });
     const notebookComponent: IFormRenderer = {
       fieldRenderer: (props: FieldProps) => {
-        return new NotebookMetadataField({
-          editorFactory,
-          tracker,
-          label: 'Notebook metadata',
-          translator: translator
-        }).render(props);
+        return notebookMetadataField.render(props);
       }
     };
     formRegistry.addRenderer(
@@ -1214,28 +1370,50 @@ const customMetadataEditorFields: JupyterFrontEndPlugin<void> = {
  */
 const activeCellTool: JupyterFrontEndPlugin<void> = {
   id: '@jupyterlab/notebook-extension:active-cell-tool',
-  description: 'Adds active cell field in the metadata editor tab.',
+  description: 'Adds active cell fields in the metadata editor tab.',
   autoStart: true,
   requires: [INotebookTracker, IFormRendererRegistry, IEditorLanguageRegistry],
+  optional: [ITranslator],
   activate: (
     // Register the custom field.
     app: JupyterFrontEnd,
     tracker: INotebookTracker,
     formRegistry: IFormRendererRegistry,
-    languages: IEditorLanguageRegistry
+    languages: IEditorLanguageRegistry,
+    translator?: ITranslator
   ) => {
+    // The field renderer is used by rjsf as a React component, so it runs on
+    // every rebuild of the metadata form. The tool is created once and reused:
+    // constructing one per render would rebuild the prompt and the preview from
+    // scratch (showing them empty until the next update) and would leave a
+    // connection to the cell model behind for every abandoned instance.
+    const tool = new ActiveCellTool({
+      tracker,
+      languages
+    });
     const component: IFormRenderer = {
       fieldRenderer: (props: FieldProps) => {
-        return new ActiveCellTool({
-          tracker,
-          languages
-        }).render(props);
+        return tool.render(props);
       }
     };
     formRegistry.addRenderer(
       '@jupyterlab/notebook-extension:active-cell-tool.renderer',
       component
     );
+
+    const cellIdComponent: IFormRenderer = {
+      fieldRenderer: (props: FieldProps) => {
+        return CellIdField({
+          ...props,
+          tracker,
+          translator
+        });
+      }
+    };
+    formRegistry.addRenderer(
+      '@jupyterlab/notebook-extension:active-cell-tool.cell-id',
+      cellIdComponent
+    );
   }
 };
 
@@ -1315,6 +1493,7 @@ const plugins: JupyterFrontEndPlugin<any>[] = [
   trackerPlugin,
   pageHandlerPlugin,
   executionIndicator,
+  exportGuidanceDialogPlugin,
   exportPlugin,
   tools,
   cellCounterItem,
@@ -1436,7 +1615,8 @@ function activatePageHandler(
 
       const mimeData = data as nbformat.IMimeBundle;
       const metadata = (payload['metadata'] ?? {}) as ReadonlyJSONObject;
-      const mimeType = rendermime.preferredMimeType(mimeData, 'any');
+      const trusted = false;
+      const mimeType = rendermime.preferredMimeType(mimeData, 'ensure');
       if (!mimeType) {
         return false;
       }
@@ -1456,7 +1636,7 @@ function activatePageHandler(
 
       const renderer = rendermime.createRenderer(mimeType);
       void renderer.renderModel(
-        new MimeModel({ data: mimeData, metadata, trusted: true })
+        new MimeModel({ data: mimeData, metadata, trusted })
       );
       content.addWidget(renderer);
 
@@ -2132,8 +2312,12 @@ function activateNotebookHandler(
             value: settings.get('sideBySideOutputRatio').composite as number
           })
             .then(result => {
-              setSideBySideOutputRatio(result.value!);
-              if (result.value) {
+              if (
+                result.value !== null &&
+                Number.isFinite(result.value) &&
+                result.value >= 0
+              ) {
+                setSideBySideOutputRatio(result.value);
                 void settings.set('sideBySideOutputRatio', result.value);
               }
             })
@@ -2224,10 +2408,13 @@ function activateNotebookHandler(
     widget.title.iconLabel = ft?.iconLabel ?? '';
     widget.content.scrollbar = factory.notebookConfig.showMinimap ?? false;
 
-    // Notify the widget tracker if restore data needs to update.
+    // Notify the widget tracker if restore data needs to update. The context
+    // outlives this panel when other views of the document stay open, so the
+    // connection is made with the panel as receiver: `Widget.dispose()` calls
+    // `Signal.clearData(this)`, which removes it when the panel is closed.
     widget.context.pathChanged.connect(() => {
       void tracker.save(widget);
-    });
+    }, widget);
     // Add the notebook panel to the tracker.
     void tracker.add(widget);
   });
@@ -2306,15 +2493,16 @@ function activateNotebookHandler(
     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 as boolean;
@@ -2532,6 +2720,7 @@ function activateNotebookCompleterService(
     keys: ['Enter'],
     selector: '.jp-Notebook .jp-mod-completer-active'
   });
+  const completerConnected = new WeakSet<NotebookPanel>();
   const updateCompleter = async (
     _: INotebookTracker | undefined,
     notebook: NotebookPanel
@@ -2543,6 +2732,15 @@ function activateNotebookCompleterService(
       sanitizer: sanitizer
     };
     await manager.updateCompleter(completerContext);
+    // `updateCompleter` also runs for every panel on `activeProvidersChanged`
+    // below; connect the listeners only on the first call for a panel so
+    // they do not accumulate per settings change. The disposal check covers
+    // a panel closed while `updateCompleter` was pending: connections made
+    // then would outlive the disposal cleanup that has already run.
+    if (notebook.isDisposed || completerConnected.has(notebook)) {
+      return;
+    }
+    completerConnected.add(notebook);
     notebook.content.activeCellChanged.connect((_, cell) => {
       // Ensure the editor will exist on the cell before adding the completer
       cell?.ready
@@ -2557,6 +2755,10 @@ function activateNotebookCompleterService(
         })
         .catch(console.error);
     });
+    // The session context outlives this panel when other views of the
+    // document stay open, so the connection is made with the panel as
+    // receiver: `Widget.dispose()` calls `Signal.clearData(this)`, which
+    // removes it when the panel is closed.
     notebook.sessionContext.sessionChanged.connect(() => {
       // Ensure the editor will exist on the cell before adding the completer
       notebook.content.activeCell?.ready
@@ -2569,7 +2771,7 @@ function activateNotebookCompleterService(
           return manager.updateCompleter(newCompleterContext);
         })
         .catch(console.error);
-    });
+    }, notebook);
   };
   notebooks.widgetAdded.connect(updateCompleter);
   manager.activeProvidersChanged.connect(() => {
@@ -2709,18 +2911,28 @@ function addCommands(
     }
   };
 
-  // Set up signal handler to keep the collapse state consistent
+  // Set up signal handler to keep the collapse state consistent. The
+  // connections are made once per panel: `currentChanged` fires repeatedly
+  // for the same panel, and reconnecting each time would pile up duplicate
+  // handlers for as long as the panel lives.
+  const collapseSynchronized = new WeakSet<NotebookPanel>();
   tracker.currentChanged.connect(
     (sender: INotebookTracker, panel: NotebookPanel) => {
-      if (!panel?.content?.model?.cells) {
+      if (!panel?.content?.model?.cells || collapseSynchronized.has(panel)) {
         return;
       }
+      collapseSynchronized.add(panel);
+      // The cell list belongs to the model, which outlives this view when
+      // other views of the document stay open, so the connection is made
+      // with the notebook as receiver: `Widget.dispose()` calls
+      // `Signal.clearData(this)`, which removes it when the view is closed.
       panel.content.model.cells.changed.connect(
         (list: any, args: IObservableList.IChangedArgs<ICellModel>) => {
           // Might be overkill to refresh this every time, but
           // it helps to keep the collapse state consistent.
           refreshCellCollapsed(panel.content);
-        }
+        },
+        panel.content
       );
       panel.content.activeCellChanged.connect(
         (notebook: Notebook, cell: Cell) => {
@@ -3077,8 +3289,14 @@ function addCommands(
   commands.addCommand(CommandIDs.trust, {
     label: () => trans.__('Trust Notebook'),
     execute: async args => {
-      const current = getCurrent(tracker, shell, args);
-      if (current) {
+      const trustBoundaryId = args[CommandLinker.TRUST_BOUNDARY_ID_ARG];
+      const current =
+        typeof trustBoundaryId === 'string'
+          ? (tracker.find(
+              widget => widget.content.node.id === trustBoundaryId
+            ) ?? null)
+          : getCurrent(tracker, shell, args);
+      if (current && !current.isDisposed) {
         const { context, content } = current;
         const trustResult = await NotebookActions.trust(content);
         if (trustResult.trusted) {
@@ -3092,7 +3310,12 @@ function addCommands(
     describedBy: {
       args: {
         type: 'object',
-        properties: {}
+        properties: {
+          [CommandLinker.TRUST_BOUNDARY_ID_ARG]: {
+            type: 'string',
+            description: trans.__('The notebook trust boundary ID')
+          }
+        }
       }
     }
   });

package/src/nboutput.ts

@@ -65,12 +65,19 @@ function activateNBOutput(
     // There is overlap here since unhandled messages are also emitted in the
     // iopubMessage signal. However, unhandled messages warrant a higher log
     // severity, so we'll accept that they are logged twice.
+    //
+    // The session context outlives this panel when other views of the
+    // document stay open, so the connections are made with the panel as
+    // receiver: `Widget.dispose()` calls `Signal.clearData(this)`, which
+    // removes them when the panel is closed.
     nb.context.sessionContext.iopubMessage.connect(
-      (_, msg: KernelMessage.IIOPubMessage) => logOutput(msg, 'info', 'info')
+      (_, msg: KernelMessage.IIOPubMessage) => logOutput(msg, 'info', 'info'),
+      nb
     );
     nb.context.sessionContext.unhandledMessage.connect(
       (_, msg: KernelMessage.IIOPubMessage) =>
-        logOutput(msg, 'warning', 'error')
+        logOutput(msg, 'warning', 'error'),
+      nb
     );
   }
   nbtracker.forEach(nb => registerNB(nb));