Add an SPA-like route to the Files page via ILiteRouter (#217)

Co-authored-by: Michał Krassowski <[email protected]>

Author: agriyakhetarpal

package.json

@@ -34,14 +34,16 @@
         "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
         "build:labextension": "jupyter labextension build .",
         "copy:landing:template": "cp templates/index.html dist/index.html",
-        "patch:lab:index": "patch -p1 --forward < templates/customise-title-and-spinner.patch || patch -p1 -R --dry-run < templates/customise-title-and-spinner.patch",
+        "build:base:css": "esbuild style/base.css --bundle --minify --loader:.svg=dataurl --outfile=dist/base.css",
+        "build:landing:css": "esbuild style/landing.css --bundle --minify --loader:.svg=dataurl --outfile=dist/landing.css",
+        "build:landing:page": "jlpm copy:landing:template && jlpm build:base:css && jlpm build:landing:css",
+        "build:landing:all": "esbuild src/landing.tsx --bundle --outfile=dist/landing.js --minify --loader:.svg=dataurl --loader:.png=dataurl --loader:.jpeg=dataurl && jlpm build:landing:page",
+        "patch:lab:index": "patch -p1 --verbose --forward < templates/customise-title-and-spinner.patch || patch -p1 -R --dry-run --verbose < templates/customise-title-and-spinner.patch",
         "copy:je-spinner-logo": "cp style/icons/logo.svg dist/lab/logo.svg",
         "copy:favicon": "cp static/favicon.ico dist/favicon.ico && cp static/favicon.ico dist/lab/favicon.ico",
-        "build:landing:css": "esbuild style/landing.css --bundle --minify --loader:.svg=dataurl --outfile=dist/landing.css",
-        "build:base:css": "esbuild style/base.css --bundle --minify --loader:.svg=dataurl --outfile=dist/base.css",
-        "build:css": "jlpm build:landing:css && jlpm build:base:css",
-        "build:landing": "esbuild src/landing.tsx --bundle --outfile=dist/landing.js --minify --loader:.svg=dataurl --loader:.png=dataurl --loader:.jpeg=dataurl && jlpm copy:landing:template && jlpm patch:lab:index && jlpm copy:je-spinner-logo && jlpm build:css",
-        "build:jupyterlite": "cd lite && jupyter lite build --XeusAddon.environment_file=xeus-environment.yml --output-dir=../dist && cd .. && jlpm build:landing && jlpm copy:favicon",
+        "build:lab:all": "jlpm patch:lab:index && jlpm copy:je-spinner-logo && jlpm copy:favicon",
+        "build:files:all": "mkdir -p dist/lab/files && cp templates/files-redirect.html dist/lab/files/index.html",
+        "build:jupyterlite": "cd lite && jupyter lite build --XeusAddon.environment_file=xeus-environment.yml --output-dir=../dist && cd .. && jlpm build:landing:all && jlpm build:lab:all && jlpm build:files:all",
         "build:all": "jlpm build && jlpm build:jupyterlite",
         "build:labextension:dev": "jupyter labextension build --development True .",
         "build:lib": "tsc --sourceMap",
@@ -80,6 +82,7 @@
         "@jupyterlab/settingregistry": "^4.5.0-alpha.3",
         "@jupyterlab/translation": "^4.5.0-alpha.3",
         "@jupyterlab/ui-components": "^4.5.0-alpha.3",
+        "@jupyterlite/application": "^0.7.0-alpha.4",
         "@lumino/commands": "^2.3.2",
         "@lumino/coreutils": "^2.2.1",
         "@lumino/messaging": "^2.0.3",
@@ -90,6 +93,7 @@
     },
     "resolutions": {
         "@jupyterlab/application": "^4.5.0-alpha.3",
+        "@jupyterlite/application": "^0.7.0-alpha.4",
         "@jupyterlab/apputils": "^4.5.0-alpha.3",
         "@jupyterlab/cells": "^4.5.0-alpha.3",
         "@jupyterlab/codeeditor": "^4.5.0-alpha.3",

src/commands.ts

@@ -1,6 +1,7 @@
 export namespace Commands {
   export const openCompetitions = 'jupytereverywhere:open-competitions';
   export const openFiles = 'jupytereverywhere:open-files';
+  export const routeFiles = 'jupytereverywhere:files-route';
   export const openHelp = 'jupytereverywhere:open-help';
   export const downloadNotebookCommand = 'jupytereverywhere:download-notebook';
   export const downloadPDFCommand = 'jupytereverywhere:download-pdf';

src/index.ts

@@ -16,6 +16,7 @@ import fastForwardSvg from '../style/icons/fast-forward.svg';
 
 import { exportNotebookAsPDF } from './pdf';
 import { files } from './pages/files';
+import routesPlugin from './routes';
 import { Commands } from './commands';
 // import { competitions } from './pages/competitions';
 import { notebookPlugin } from './pages/notebook';
@@ -597,6 +598,7 @@ export default [
   plugin,
   notebookPlugin,
   files,
+  routesPlugin,
   // competitions,
   customSidebar,
   // helpPlugin,

src/pages/competitions.tsx

@@ -40,7 +40,8 @@ export const competitions: JupyterFrontEndPlugin<void> = {
         label: 'Competition',
         icon: EverywhereIcons.competition,
         execute: () => {
-          app.commands.execute(Commands.openCompetitions);
+          void app.commands.execute(Commands.openCompetitions);
+          return;
         }
       }),
       'left',

src/pages/files.tsx

@@ -1,4 +1,5 @@
 import { JupyterFrontEndPlugin, JupyterFrontEnd } from '@jupyterlab/application';
+import { ILiteRouter } from '@jupyterlite/application';
 import { MainAreaWidget, ReactWidget, showErrorMessage } from '@jupyterlab/apputils';
 import { Contents } from '@jupyterlab/services';
 import { IContentsManager } from '@jupyterlab/services';
@@ -365,7 +366,12 @@ export const files: JupyterFrontEndPlugin<void> = {
   id: 'jupytereverywhere:files',
   autoStart: true,
   requires: [IContentsManager],
-  activate: (app: JupyterFrontEnd, contentsManager: Contents.IManager) => {
+  optional: [ILiteRouter],
+  activate: (
+    app: JupyterFrontEnd,
+    contentsManager: Contents.IManager,
+    router: ILiteRouter | null
+  ) => {
     const createWidget = () => {
       const content = new Files(contentsManager);
       const widget = new MainAreaWidget({ content });
@@ -385,18 +391,40 @@ export const files: JupyterFrontEndPlugin<void> = {
 
     let widget = createWidget();
 
-    app.shell.add(
-      new SidebarIcon({
-        label: 'Files',
-        icon: EverywhereIcons.folderSidebar,
-        execute: () => {
-          void app.commands.execute(Commands.openFiles);
-          return undefined;
+    const base = (router?.base || '').replace(/\/$/, '');
+    const filesPath = `${base}/lab/files/`;
+
+    // Show the Files widget; return false-y so SidebarIcon does the URL swap.
+    const filesSidebar = new SidebarIcon({
+      label: 'Files',
+      icon: EverywhereIcons.folderSidebar,
+      pathName: filesPath,
+      execute: () => {
+        void app.commands.execute(Commands.openFiles);
+        return SidebarIcon.delegateNavigation;
+      }
+    });
+    app.shell.add(filesSidebar, 'left', { rank: 200 });
+
+    // If we landed with a "files" intent, highlight Files in the sidebar.
+    void app.restored.then(() => {
+      const url = new URL(window.location.href);
+      const pathIsFiles = /\/lab\/files(?:\/|$)/.test(url.pathname);
+      const tabIsFiles = url.searchParams.get('tab') === 'files';
+      if (pathIsFiles || tabIsFiles) {
+        const desired = new URL(filesPath, window.location.origin);
+        desired.hash = url.hash;
+        window.history.replaceState(null, 'Files', desired.toString());
+
+        if (widget.isDisposed) {
+          widget = createWidget();
+        }
+        if (!widget.isAttached) {
+          app.shell.add(widget, 'main');
         }
-      }),
-      'left',
-      { rank: 200 }
-    );
+        app.shell.activateById(filesSidebar.id);
+      }
+    });
 
     app.commands.addCommand(Commands.openFiles, {
       label: 'Open Files',

src/pages/help.tsx

@@ -128,7 +128,8 @@ export const helpPlugin: JupyterFrontEndPlugin<void> = {
         label: 'Help Centre',
         icon: EverywhereIcons.help,
         execute: () => {
-          app.commands.execute(Commands.openHelp);
+          void app.commands.execute(Commands.openHelp);
+          return;
         }
       }),
       'left',

src/pages/notebook.tsx

@@ -1,4 +1,5 @@
 import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { ILiteRouter } from '@jupyterlite/application';
 import { INotebookTracker, INotebookWidgetFactory } from '@jupyterlab/notebook';
 import { INotebookContent } from '@jupyterlab/nbformat';
 import { SidebarIcon } from '../ui-components/SidebarIcon';
@@ -41,16 +42,26 @@ export const notebookPlugin: JupyterFrontEndPlugin<void> = {
     IToolbarWidgetRegistry,
     INotebookWidgetFactory
   ],
+  optional: [ILiteRouter],
   activate: (
     app: JupyterFrontEnd,
     tracker: INotebookTracker,
     readonlyTracker: IViewOnlyNotebookTracker,
-    toolbarRegistry: IToolbarWidgetRegistry
+    toolbarRegistry: IToolbarWidgetRegistry,
+    router?: ILiteRouter | null
   ) => {
     const { commands, shell, serviceManager } = app;
     const { contents } = serviceManager;
 
     const params = new URLSearchParams(window.location.search);
+
+    // Are we landing on the Files tab directly? In this case, we won't
+    // auto-create a new notebook or activate the notebook sidebar.
+    const nowUrl = new URL(window.location.href);
+    const onFilesPath = /\/lab\/files(?:\/|$)/.test(nowUrl.pathname);
+    const onFilesTab = nowUrl.searchParams.get('tab') === 'files';
+    const onFilesIntent = onFilesPath || onFilesTab;
+
     let notebookId = params.get('notebook');
     const uploadedNotebookId = params.get('uploaded-notebook');
 
@@ -210,7 +221,7 @@ export const notebookPlugin: JupyterFrontEndPlugin<void> = {
       void loadSharedNotebook(notebookId);
     } else if (uploadedNotebookId) {
       void openUploadedNotebook(uploadedNotebookId);
-    } else {
+    } else if (!onFilesIntent) {
       void createNewNotebook();
     }
 
@@ -230,19 +241,35 @@ export const notebookPlugin: JupyterFrontEndPlugin<void> = {
     const sidebarItem = new SidebarIcon({
       label: 'Notebook',
       icon: EverywhereIcons.notebook,
+      pathName: `${(router?.base || '').replace(/\/$/, '')}/lab/index.html`,
       execute: () => {
         if (readonlyTracker.currentWidget) {
-          return shell.activateById(readonlyTracker.currentWidget.id);
+          const id = readonlyTracker.currentWidget.id;
+          shell.activateById(id);
+          return SidebarIcon.delegateNavigation;
         }
         if (tracker.currentWidget) {
-          return shell.activateById(tracker.currentWidget.id);
+          const id = tracker.currentWidget.id;
+          shell.activateById(id);
+          return SidebarIcon.delegateNavigation;
         }
+
+        // If we don't have a notebook yet (likely we started on /lab/files/) -> create one now.
+        void (async () => {
+          await app.commands.execute('notebook:create-new', { kernelName: 'python' });
+          if (tracker.currentWidget) {
+            shell.activateById(tracker.currentWidget.id);
+          }
+        })();
+        return SidebarIcon.delegateNavigation;
       }
     });
     shell.add(sidebarItem, 'left', { rank: 100 });
 
-    app.shell.activateById(sidebarItem.id);
-    app.restored.then(() => app.shell.activateById(sidebarItem.id));
+    if (!onFilesIntent) {
+      app.shell.activateById(sidebarItem.id);
+      app.restored.then(() => app.shell.activateById(sidebarItem.id));
+    }
 
     for (const toolbarName of ['Notebook', 'ViewOnlyNotebook']) {
       toolbarRegistry.addFactory(
@@ -293,5 +320,33 @@ export const notebookPlugin: JupyterFrontEndPlugin<void> = {
         () => new KernelSwitcherDropdownButton(commands, tracker)
       );
     }
+
+    // Canonicalise the URL if we are directly at /lab/.
+    void app.restored.then(() => {
+      const url = new URL(window.location.href);
+      if (/\/lab\/$/.test(url.pathname)) {
+        url.pathname = url.pathname.replace(/\/lab\/$/, '/lab/index.html');
+        window.history.replaceState({}, '', url.toString());
+      }
+
+      const after = new URL(window.location.href);
+      if (after.searchParams.get('tab') === 'notebook') {
+        const id = document.querySelector('.jp-NotebookPanel')?.id;
+        if (id) {
+          app.shell.activateById(id);
+          after.searchParams.delete('tab');
+          const base = (router?.base || '').replace(/\/$/, '');
+          const canonical = new URL(`${base}/lab/index.html`, window.location.origin);
+          canonical.hash = after.hash;
+          // Keep any other non-tab params off; Notebook page doesn't need them
+          if (
+            after.pathname + after.search + after.hash !==
+            canonical.pathname + canonical.search + canonical.hash
+          ) {
+            window.history.replaceState(null, 'Notebook', canonical.toString());
+          }
+        }
+      }
+    });
   }
 };

src/routes.ts

@@ -0,0 +1,87 @@
+import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { ILiteRouter } from '@jupyterlite/application';
+import { Commands } from './commands';
+import { ILabShell } from '@jupyterlab/application';
+
+const ROUTE_FILES_CMD = Commands.routeFiles;
+
+const routesPlugin: JupyterFrontEndPlugin<void> = {
+  id: 'jupytereverywhere:routes',
+  autoStart: true,
+  optional: [ILiteRouter, ILabShell],
+  activate: (app: JupyterFrontEnd, router: ILiteRouter | null, _labShell?: ILabShell | null) => {
+    if (!router) {
+      return;
+    }
+
+    app.commands.addCommand(ROUTE_FILES_CMD, {
+      label: 'Open Files (route)',
+      execute: async () => {
+        await app.restored;
+        await app.commands.execute(Commands.openFiles);
+      }
+    });
+
+    const base = router.base.replace(/\/+$/, '');
+    const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    // 1. Support direct files/ paths, as the redirect page lands there first.
+    const filesPathPatterns = [
+      /^\/files(?:\/.*)?$/,
+      new RegExp(`^${esc(base)}\\/files(?:\\/.*)?$`)
+    ];
+    filesPathPatterns.forEach(pattern => router.register({ command: ROUTE_FILES_CMD, pattern }));
+
+    // 2. Support /lab/index.html?tab=files (or ?tab=notebook). We register a
+    // router handler that just inspects the query string.
+    router.register({
+      command: ROUTE_FILES_CMD,
+      pattern: new RegExp(`^${esc(base)}\\/?(?:index\\.html)?\\?[^#]*\\btab=files\\b(?:[&#].*)?$`)
+    });
+    router.register({
+      command: ROUTE_FILES_CMD,
+      pattern: /^\/?(?:index\.html)?\?[^#]*\btab=files\b(?:[&#].*)?$/
+    });
+
+    void app.restored.then(() => {
+      const search = window.location.search || '';
+      const params = new URLSearchParams(search);
+      const tab = params.get('tab');
+
+      if (tab === 'files') {
+        void app.commands.execute(ROUTE_FILES_CMD).then(() => {
+          const filesURL = new URL(`${base.replace(/\/$/, '')}/lab/files/`, window.location.origin);
+          filesURL.hash = window.location.hash;
+          window.history.replaceState(null, 'Files', filesURL.toString());
+        });
+        return;
+      }
+
+      if (tab === 'notebook') {
+        const tryActivate = async () => {
+          const id = document.querySelector('.jp-NotebookPanel')?.id;
+          if (id) {
+            app.shell.activateById(id);
+          }
+          const nbURL = new URL(
+            `${base.replace(/\/$/, '')}/lab/index.html`,
+            window.location.origin
+          );
+          nbURL.hash = window.location.hash;
+          window.history.replaceState(null, 'Notebook', nbURL.toString());
+        };
+        tryActivate();
+      }
+    });
+
+    const here = window.location.href;
+
+    if (filesPathPatterns.some(p => p.test(here))) {
+      void app.restored.then(() => {
+        void app.commands.execute(Commands.openFiles);
+      });
+    }
+  }
+};
+
+export default routesPlugin;

src/sidebar.ts

@@ -44,7 +44,7 @@ export const customSidebar: JupyterFrontEndPlugin<void> = {
           : null;
         if (newWidget && newWidget instanceof SidebarIcon) {
           const cancel = newWidget.execute();
-          if (cancel) {
+          if (cancel === true) {
             console.log('Attempting to revert to:', oldWidget?.label);
             if (args.previousTitle) {
               const previousIndex = sidebar.titles.indexOf(oldWidget);