@oceanum/oceanumlab 4.7.2 → 4.9.0

package/src/share/notebook.ts

@@ -189,6 +189,49 @@ export function buildSpecBody(
   return { ok: false, bytes: strippedBytes };
 }
 
+/**
+ * The notebook stored in a record, untrusted. Throws if the record does not hold an
+ * nbformat 4 notebook.
+ */
+function recordNotebook(record: ISpecRecord): INotebookContent {
+  const spec = record.spec;
+  if (!isNotebook(spec)) {
+    throw new Error('This Oceanum.io record is not a valid notebook.');
+  }
+  return withoutTrust(spec);
+}
+
+function isNotebook(value: unknown): value is INotebookContent {
+  return (
+    isObject(value) &&
+    value.nbformat === 4 &&
+    Array.isArray(value.cells) &&
+    value.cells.every(
+      cell => isObject(cell) && typeof cell.cell_type === 'string'
+    ) &&
+    isObject(value.metadata)
+  );
+}
+
+/**
+ * A notebook uploaded from the user's computer, untrusted and linked to nothing: a file
+ * someone else downloaded from a record must not save over that record, and its outputs
+ * must not run scripts on the origin that holds the Oceanum.io session. Throws if the
+ * text is not an nbformat 4 notebook; the message never quotes the file.
+ */
+export function notebookFromUpload(text: string): INotebookContent {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('The file is not a Jupyter notebook: it is not JSON.');
+  }
+  if (!isNotebook(parsed)) {
+    throw new Error('The file is not a Jupyter notebook in nbformat 4.');
+  }
+  return withoutLink(withoutTrust(parsed));
+}
+
 /**
  * The notebook stored in a record, with its `oceanum` link set. Throws if the record
  * does not hold an nbformat 4 notebook.
@@ -197,26 +240,28 @@ export function notebookFromRecord(
   record: ISpecRecord,
   specsUrl: string
 ): INotebookContent {
-  const spec = record.spec;
-  if (
-    !isObject(spec) ||
-    spec.nbformat !== 4 ||
-    !Array.isArray(spec.cells) ||
-    !isObject(spec.metadata)
-  ) {
-    throw new Error('This Oceanum.io record is not a valid notebook.');
-  }
   const link: IOceanumLink = { spec_id: record.id, specs_url: specsUrl };
   if (record.description) {
     link.description = record.description;
   }
-  const content = withoutTrust(spec as unknown as INotebookContent);
+  const content = recordNotebook(record);
   return {
     ...content,
     metadata: { ...content.metadata, [METADATA_KEY]: { ...link } }
   };
 }
 
+/**
+ * A copy of the notebook stored in a record, linked to nothing: untrusted, and without
+ * any `oceanum` link, so saving it creates a record of the user's own instead of
+ * writing to this one. Throws if the record does not hold an nbformat 4 notebook.
+ */
+export function unlinkedNotebookFromRecord(
+  record: ISpecRecord
+): INotebookContent {
+  return withoutLink(recordNotebook(record));
+}
+
 /** Make a record name safe to use as a single path segment. */
 export function sanitizeName(name: string): string {
   const clean = name
@@ -307,6 +352,39 @@ export function partitionSummaries(
   };
 }
 
+/** The spec store type of the Notebook Demo specs, which are the Examples. */
+export const NOTEBOOK_DEMO_TYPE = 'notebook-demo';
+
+/** One example: a Notebook Demo spec, whose body is the example notebook. */
+export interface INotebookDemoItem {
+  id: string;
+  title: string;
+  summary?: string;
+}
+
+/**
+ * The examples in a listing of Notebook Demo specs, ordered by name as people number
+ * them ("2 …" before "10 …").
+ */
+export function demoItemsFromSummaries(
+  summaries: readonly ISpecSummary[]
+): INotebookDemoItem[] {
+  // No id check: the client's listing already rejects any summary without a spec id.
+  return summaries
+    .map(summary => {
+      const title = summary.name.trim() || 'Untitled';
+      return summary.description
+        ? { id: summary.id, title, summary: summary.description }
+        : { id: summary.id, title };
+    })
+    .sort((a, b) =>
+      a.title.localeCompare(b.title, undefined, {
+        numeric: true,
+        sensitivity: 'base'
+      })
+    );
+}
+
 /** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
 export function parseTimestamp(value: string): Date | null {
   const zoned = /(Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`;

package/src/share/oceanumOnly.ts

@@ -14,6 +14,9 @@ import type { Menu, Widget } from '@lumino/widgets';
 /** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
 export const FILE_BROWSER_ID = 'filebrowser';
 
+/** The widget id of this extension's Oceanum.io panel, which takes the browser's place. */
+export const OCEANUM_PANEL_ID = 'datamesh-connect';
+
 /**
  * File menu entries that manage local files. Save, Save All and Rename stay: saving is
  * routed to Oceanum, and renaming the local file is how a notebook gets its name.
@@ -28,23 +31,71 @@ export const LOCAL_FILE_COMMANDS: readonly string[] = [
   'docmanager:download'
 ];
 
+/**
+ * File > New entries for files that are not notebooks. The spec store holds notebooks
+ * only, so such a file could never be saved anywhere the user can see.
+ */
+export const NON_NOTEBOOK_NEW_COMMANDS: readonly string[] = [
+  'fileeditor:create-new',
+  'fileeditor:create-new-markdown-file'
+];
+
 /**
  * Take the file browser out of the sidebar; true if it was there. It is closed, not
  * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
- * open paths.
+ * open paths. If it was the open panel, `instead` is opened in its place; a sidebar the
+ * user had collapsed stays collapsed.
  */
-export function hideFileBrowser(shell: {
-  widgets(area: 'left'): Iterable<Widget>;
-}): boolean {
+export function hideFileBrowser(
+  shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+    activateById(id: string): void;
+  },
+  instead?: string
+): boolean {
   for (const widget of shell.widgets('left')) {
     if (widget.id === FILE_BROWSER_ID) {
+      const wasOpen = widget.isVisible;
       widget.close();
+      if (wasOpen && instead) {
+        shell.activateById(instead);
+      }
       return true;
     }
   }
   return false;
 }
 
+/**
+ * Put a left-sidebar widget first, and keep it open if it was. True if it moved.
+ *
+ * A rank alone is not enough: the layout restorer replays the sidebar order each user
+ * last had, so a returning user would keep the panel wherever it used to be. Adding it
+ * again after the restore re-inserts it by rank, and the shell saves the new order.
+ */
+export function moveToTop(
+  shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+    add(widget: Widget, area: 'left', options: { rank: number }): void;
+    activateById(id: string): void;
+  },
+  id: string
+): boolean {
+  const widgets = Array.from(shell.widgets('left'));
+  const index = widgets.findIndex(widget => widget.id === id);
+  if (index <= 0) {
+    return false;
+  }
+  const widget = widgets[index];
+  // Adding hides the widget, so an open panel has to be opened again.
+  const wasOpen = widget.isVisible;
+  shell.add(widget, 'left', { rank: 0 });
+  if (wasOpen) {
+    shell.activateById(id);
+  }
+  return true;
+}
+
 /**
  * Submenus of local files. "Open Recent" is built by the document manager rather than
  * declared in a schema, and its menu has no id, so it is known by the commands it holds.

package/src/share/plugin.ts

@@ -16,7 +16,7 @@ import { IMainMenu } from '@jupyterlab/mainmenu';
 import type { INotebookContent } from '@jupyterlab/nbformat';
 import { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
 import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
-import { Menu } from '@lumino/widgets';
+import { Menu, type Widget } from '@lumino/widgets';
 
 import { startSignIn } from '../auth/startSignIn';
 import { IOceanumAuth } from '../auth/tokens';
@@ -29,7 +29,9 @@ import {
   ISpecRecord,
   METADATA_KEY,
   notebookFromRecord,
+  notebookFromUpload,
   notebookNamesFor,
+  NOTEBOOK_DEMO_TYPE,
   OCEANUM_DIR,
   partitionSummaries,
   QUERY_PARAM,
@@ -37,18 +39,25 @@ import {
   reportForShareFailures,
   sanitizeName,
   shareLink,
-  uniqueNotebookPath
+  uniqueNotebookPath,
+  unlinkedNotebookFromRecord
 } from './notebook';
 import {
   hideFileBrowser,
+  moveToTop,
+  NON_NOTEBOOK_NEW_COMMANDS,
+  OCEANUM_PANEL_ID,
   pruneBeforeEachOpen,
   pruneFileMenu,
   routeSaves
 } from './oceanumOnly';
+import { chooseNotebookFile } from './upload';
 import { NotebookListBody, ShareBody } from './widgets';
 
 export const CommandIDs = {
   open: 'oceanum-share:open',
+  openExample: 'oceanum-share:open-example',
+  upload: 'oceanum-share:upload',
   save: 'oceanum-share:save',
   share: 'oceanum-share:share',
   rename: 'oceanum-share:rename',
@@ -67,6 +76,8 @@ const UNAVAILABLE =
 interface IStore {
   specsUrl: string;
   client: SpecStoreClient;
+  /** The Notebook Demo specs, which are the Examples. */
+  demos: SpecStoreClient;
 }
 
 /**
@@ -102,6 +113,11 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
             client: new SpecStoreClient({
               specsUrl,
               getAccessToken: () => auth.getAccessToken()
+            }),
+            demos: new SpecStoreClient({
+              specsUrl,
+              getAccessToken: () => auth.getAccessToken(),
+              specType: NOTEBOOK_DEMO_TYPE
             })
           };
     const oceanumOnly =
@@ -317,6 +333,23 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
       return null;
     }
 
+    /** Write a notebook to `path` on the local drive and open it. */
+    async function writeAndOpen(
+      path: string,
+      content: INotebookContent
+    ): Promise<Widget> {
+      await docManager.services.contents.save(path, {
+        type: 'notebook',
+        format: 'json',
+        content
+      });
+      const widget = docManager.openOrReveal(path);
+      if (!widget) {
+        throw new Error(`Could not open ${path}.`);
+      }
+      return widget;
+    }
+
     /** Write a record to the local drive as `Oceanum/<name>.ipynb` and open it. */
     async function openRecord(s: IStore, record: ISpecRecord): Promise<void> {
       // Already open: bring it forward rather than writing a second copy.
@@ -333,14 +366,7 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
       const path =
         (await pathHoldingRecord(s, record, names)) ??
         uniqueNotebookPath(record.name, names);
-      await docManager.services.contents.save(path, {
-        type: 'notebook',
-        format: 'json',
-        content
-      });
-      if (!docManager.openOrReveal(path)) {
-        throw new Error(`Could not open ${path}.`);
-      }
+      await writeAndOpen(path, content);
     }
 
     async function openById(id: string): Promise<void> {
@@ -359,6 +385,84 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
       }
     }
 
+    // The copy each example was last opened into, so opening it again while that copy
+    // is still open brings it forward rather than writing another.
+    const exampleCopies = new Map<string, Widget>();
+    // Examples whose copy is still being written, so a second click in that time does
+    // not write a second copy.
+    const openingExamples = new Set<string>();
+
+    /**
+     * Open a copy of an example as a new file in the Oceanum folder, untrusted and
+     * linked to nothing. Not `openRecord`: that links the file to the example's record,
+     * which is Oceanum's and read-only to everyone else, so the first save would be
+     * refused. Unlinked, the first save creates a record of the user's own.
+     */
+    async function openExample(id: string, title: string): Promise<void> {
+      if (
+        !store ||
+        !(await ensureSignedIn(
+          'Opening notebooks needs an Oceanum.io account.'
+        ))
+      ) {
+        return;
+      }
+      const copy = exampleCopies.get(id);
+      if (copy && !copy.isDisposed) {
+        app.shell.activateById(copy.id);
+        return;
+      }
+      if (openingExamples.has(id)) {
+        return;
+      }
+      openingExamples.add(id);
+      try {
+        const record = await store.demos.get(id);
+        const content = unlinkedNotebookFromRecord(record);
+        const path = uniqueNotebookPath(
+          title || record.name,
+          await oceanumFolderNames()
+        );
+        exampleCopies.set(id, await writeAndOpen(path, content));
+      } catch (error) {
+        await reportError('Open from Oceanum failed', error);
+      } finally {
+        openingExamples.delete(id);
+      }
+    }
+
+    /**
+     * Bring a notebook from the user's computer into the Oceanum folder and open it,
+     * untrusted and linked to nothing. It reaches Oceanum on its first save, like any
+     * new notebook; nothing is sent on upload.
+     */
+    async function uploadNotebook(): Promise<void> {
+      if (
+        !store ||
+        !(await ensureSignedIn(
+          'Uploading notebooks needs an Oceanum.io account.'
+        ))
+      ) {
+        return;
+      }
+      try {
+        const file = await chooseNotebookFile();
+        if (!file) {
+          return;
+        }
+        const content = notebookFromUpload(await file.text());
+        const path = uniqueNotebookPath(file.name, await oceanumFolderNames());
+        await writeAndOpen(path, content);
+        // Outside Oceanum-only mode a plain Save stays local.
+        Notification.info(
+          `Uploaded "${file.name}". ${oceanumOnly ? 'Save it' : 'Use Save to Oceanum'} to store it on Oceanum.io.`,
+          { autoClose: 5000 }
+        );
+      } catch (error) {
+        await reportError('Upload failed', error);
+      }
+    }
+
     async function openFromOceanum(): Promise<void> {
       if (
         !store ||
@@ -959,6 +1063,26 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
         await (id ? openById(id) : openFromOceanum());
       }
     });
+    // Run by the Notebooks tab's Examples; not offered in menus or the palette.
+    app.commands.addCommand(CommandIDs.openExample, {
+      label: 'Open a copy',
+      caption: 'Open a copy of an Oceanum example notebook',
+      isEnabled: () => signedIn(),
+      execute: async args => {
+        if (isSpecId(args.id)) {
+          await openExample(
+            args.id,
+            typeof args.title === 'string' ? args.title : ''
+          );
+        }
+      }
+    });
+    app.commands.addCommand(CommandIDs.upload, {
+      label: label('Upload Notebook…'),
+      caption: 'Upload a notebook from this computer, to save on Oceanum.io',
+      isEnabled: () => signedIn(),
+      execute: () => uploadNotebook()
+    });
     app.commands.addCommand(CommandIDs.save, {
       label: label('Save to Oceanum'),
       caption: 'Save the notebook to Oceanum.io',
@@ -1013,6 +1137,7 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
 
     const commands = [
       CommandIDs.open,
+      CommandIDs.upload,
       CommandIDs.save,
       CommandIDs.share,
       CommandIDs.rename,
@@ -1075,7 +1200,9 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
 
     if (oceanumOnly) {
       void app.restored.then(() => {
-        hideFileBrowser(app.shell);
+        hideFileBrowser(app.shell, OCEANUM_PANEL_ID);
+        // Oceanum is where notebooks live now, so its panel leads the sidebar.
+        moveToTop(app.shell, OCEANUM_PANEL_ID);
         // IFileMenu is the narrow interface; the menu itself is a Lumino Menu, which
         // is what can drop items.
         const fileMenu = mainMenu?.fileMenu;
@@ -1083,6 +1210,11 @@ export const sharePlugin: JupyterFrontEndPlugin<void> = {
           pruneFileMenu(fileMenu);
           pruneBeforeEachOpen(fileMenu);
         }
+        const newMenu = mainMenu?.fileMenu.newMenu;
+        if (newMenu instanceof Menu) {
+          pruneFileMenu(newMenu, NON_NOTEBOOK_NEW_COMMANDS);
+          pruneBeforeEachOpen(newMenu, NON_NOTEBOOK_NEW_COMMANDS);
+        }
         routeSaves(tracker, pushQuietly);
       });
     }

package/src/share/upload.ts

@@ -0,0 +1,27 @@
+/**
+ * Ask the user for a notebook file on their computer; null if they cancel.
+ *
+ * Kept apart from the plugin because it is browser-only: the tests replace it.
+ */
+export function chooseNotebookFile(): Promise<File | null> {
+  return new Promise(resolve => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = '.ipynb,application/x-ipynb+json';
+    input.hidden = true;
+    // Attached while the picker is open: some browsers (Safari) drop the `change`
+    // event of a detached input, or collect the input before it fires.
+    document.body.appendChild(input);
+    const settle = (file: File | null): void => {
+      input.remove();
+      resolve(file);
+    };
+    input.addEventListener('change', () => settle(input.files?.[0] ?? null), {
+      once: true
+    });
+    // Browsers fire `cancel` when the picker is dismissed; without it the promise
+    // would simply never settle, which is harmless.
+    input.addEventListener('cancel', () => settle(null), { once: true });
+    input.click();
+  });
+}

package/style/index.css

@@ -600,7 +600,8 @@
   list-style: none;
 }
 
-.oceanum-notebooks-item {
+.oceanum-notebooks-item,
+.oceanum-notebooks-example {
   display: block;
   width: 100%;
   padding: 4px 8px;
@@ -613,7 +614,8 @@
   cursor: pointer;
 }
 
-.oceanum-notebooks-item:hover {
+.oceanum-notebooks-item:hover,
+.oceanum-notebooks-example:hover {
   background: var(--jp-layout-color2);
 }
 
@@ -621,10 +623,100 @@
   cursor: default;
 }
 
+.oceanum-notebooks-actions {
+  padding: 6px 8px 2px;
+}
+
+.oceanum-notebooks-upload {
+  padding: 3px 8px;
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: var(--jp-border-radius);
+  background: var(--jp-layout-color1);
+  color: var(--jp-ui-font-color1);
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size1);
+  cursor: pointer;
+}
+
+.oceanum-notebooks-upload:hover {
+  background: var(--jp-layout-color2);
+}
+
 .oceanum-notebooks-item-static:hover {
   background: transparent;
 }
 
+/* The Examples heading's count and show/hide switch, kept together on the right. */
+.oceanum-notebooks-heading-end {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+/* The Examples show/hide switch (a button with role="switch"). */
+.oceanum-notebooks-switch {
+  position: relative;
+  flex: none;
+  width: 24px;
+  height: 14px;
+  padding: 0;
+  border: none;
+  border-radius: 7px;
+  background: var(--jp-layout-color3);
+  cursor: pointer;
+}
+
+.oceanum-notebooks-switch[aria-checked='true'] {
+  background: var(--jp-brand-color1);
+}
+
+.oceanum-notebooks-switch:focus-visible {
+  outline: 1px solid var(--jp-brand-color1);
+  outline-offset: 1px;
+}
+
+.oceanum-notebooks-switch-thumb {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--jp-layout-color0);
+  transition: left 0.1s ease;
+}
+
+.oceanum-notebooks-switch[aria-checked='true'] .oceanum-notebooks-switch-thumb {
+  left: 12px;
+}
+
+/* Forced colours replace backgrounds, which would leave a switch drawn only with them
+   invisible: draw it with system colours instead. */
+@media (forced-colors: active) {
+  .oceanum-notebooks-switch {
+    forced-color-adjust: none;
+    box-sizing: border-box;
+    border: 1px solid ButtonText;
+    background: Canvas;
+  }
+
+  .oceanum-notebooks-switch[aria-checked='true'] {
+    background: Highlight;
+  }
+
+  .oceanum-notebooks-switch-thumb {
+    top: 1px;
+    left: 1px;
+    background: ButtonText;
+  }
+
+  .oceanum-notebooks-switch[aria-checked='true']
+    .oceanum-notebooks-switch-thumb {
+    left: 11px;
+    background: HighlightText;
+  }
+}
+
 .oceanum-notebooks-name {
   overflow: hidden;
   text-overflow: ellipsis;