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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/notebook-extension",
-  "version": "4.7.0-alpha.0",
+  "version": "4.7.0-alpha.1",
   "description": "JupyterLab - Notebook Extension",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -37,44 +37,44 @@
   },
   "dependencies": {
     "@jupyter/ydoc": "^4.0.0",
-    "@jupyterlab/application": "^4.7.0-alpha.0",
-    "@jupyterlab/apputils": "^4.8.0-alpha.0",
-    "@jupyterlab/cell-toolbar": "^4.7.0-alpha.0",
-    "@jupyterlab/cells": "^4.7.0-alpha.0",
-    "@jupyterlab/codeeditor": "^4.7.0-alpha.0",
-    "@jupyterlab/codemirror": "^4.7.0-alpha.0",
-    "@jupyterlab/completer": "^4.7.0-alpha.0",
-    "@jupyterlab/coreutils": "^6.7.0-alpha.0",
-    "@jupyterlab/docmanager": "^4.7.0-alpha.0",
-    "@jupyterlab/docmanager-extension": "^4.7.0-alpha.0",
-    "@jupyterlab/docregistry": "^4.7.0-alpha.0",
-    "@jupyterlab/documentsearch": "^4.7.0-alpha.0",
-    "@jupyterlab/filebrowser": "^4.7.0-alpha.0",
-    "@jupyterlab/launcher": "^4.7.0-alpha.0",
-    "@jupyterlab/logconsole": "^4.7.0-alpha.0",
-    "@jupyterlab/lsp": "^4.7.0-alpha.0",
-    "@jupyterlab/mainmenu": "^4.7.0-alpha.0",
-    "@jupyterlab/metadataform": "^4.7.0-alpha.0",
-    "@jupyterlab/nbformat": "^4.7.0-alpha.0",
-    "@jupyterlab/notebook": "^4.7.0-alpha.0",
-    "@jupyterlab/observables": "^5.7.0-alpha.0",
-    "@jupyterlab/outputarea": "^4.7.0-alpha.0",
-    "@jupyterlab/property-inspector": "^4.7.0-alpha.0",
-    "@jupyterlab/rendermime": "^4.7.0-alpha.0",
-    "@jupyterlab/services": "^7.7.0-alpha.0",
-    "@jupyterlab/settingregistry": "^4.7.0-alpha.0",
-    "@jupyterlab/statedb": "^4.7.0-alpha.0",
-    "@jupyterlab/statusbar": "^4.7.0-alpha.0",
-    "@jupyterlab/toc": "^6.7.0-alpha.0",
-    "@jupyterlab/translation": "^4.7.0-alpha.0",
-    "@jupyterlab/ui-components": "^4.7.0-alpha.0",
-    "@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

@@ -841,12 +841,14 @@
       "title": "Side-by-side left margin override",
       "description": "Side-by-side left margin override.",
       "type": "string",
+      "pattern": "^-?(?:0|(?:[0-9]+|[0-9]*\\.[0-9]+)(?:px|em|rem|%|vw|vh|vmin|vmax|ch|ex|cm|mm|in|pt|pc))$",
       "default": "10px"
     },
     "sideBySideRightMarginOverride": {
       "title": "Side-by-side right margin override",
       "description": "Side-by-side right margin override.",
       "type": "string",
+      "pattern": "^-?(?:0|(?:[0-9]+|[0-9]*\\.[0-9]+)(?:px|em|rem|%|vw|vh|vmin|vmax|ch|ex|cm|mm|in|pt|pc))$",
       "default": "10px"
     },
     "sideBySideOutputRatio": {

package/src/index.ts

@@ -135,7 +135,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';
@@ -189,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';
@@ -372,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.
  */
@@ -648,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;
@@ -745,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;
       }
 
@@ -767,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.
  */
@@ -1315,6 +1455,7 @@ const plugins: JupyterFrontEndPlugin<any>[] = [
   trackerPlugin,
   pageHandlerPlugin,
   executionIndicator,
+  exportGuidanceDialogPlugin,
   exportPlugin,
   tools,
   cellCounterItem,
@@ -2306,15 +2447,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;