@oceanum/oceanumlab 4.7.2 → 4.8.0

package/lib/share/plugin.d.ts

@@ -1,6 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 export declare const CommandIDs: {
     readonly open: "oceanum-share:open";
+    readonly openExample: "oceanum-share:open-example";
+    readonly upload: "oceanum-share:upload";
     readonly save: "oceanum-share:save";
     readonly share: "oceanum-share:share";
     readonly rename: "oceanum-share:rename";

package/lib/share/plugin.js

@@ -9,11 +9,14 @@ import { startSignIn } from '../auth/startSignIn';
 import { IOceanumAuth } from '../auth/tokens';
 import { SpecStoreClient, SpecStoreError } from './client';
 import { notebooksChanged } from './events';
-import { buildSpecBody, isSpecId, METADATA_KEY, notebookFromRecord, notebookNamesFor, OCEANUM_DIR, partitionSummaries, QUERY_PARAM, readLink, reportForShareFailures, sanitizeName, shareLink, uniqueNotebookPath } from './notebook';
-import { hideFileBrowser, pruneBeforeEachOpen, pruneFileMenu, routeSaves } from './oceanumOnly';
+import { buildSpecBody, isSpecId, METADATA_KEY, notebookFromRecord, notebookFromUpload, notebookNamesFor, OCEANUM_DIR, partitionSummaries, QUERY_PARAM, readLink, reportForShareFailures, sanitizeName, shareLink, 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',
@@ -221,6 +224,19 @@ export const sharePlugin = {
             }
             return null;
         }
+        /** Write a notebook to `path` on the local drive and open it. */
+        async function writeAndOpen(path, content) {
+            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, record) {
             var _a;
@@ -236,14 +252,7 @@ export const sharePlugin = {
             // named "<name> (1)", and a record takes its name from the file on every save, so
             // opening the same notebook twice would quietly rename it on Oceanum.
             const path = (_a = (await pathHoldingRecord(s, record, names))) !== null && _a !== void 0 ? _a : 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) {
             if (!store ||
@@ -257,6 +266,70 @@ export const sharePlugin = {
                 await reportError('Open from Oceanum failed', error);
             }
         }
+        // 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();
+        // Examples whose copy is still being written, so a second click in that time does
+        // not write a second copy.
+        const openingExamples = new Set();
+        /**
+         * 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, title) {
+            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.client.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() {
+            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() {
             var _a, _b;
             if (!store ||
@@ -757,6 +830,23 @@ export const sharePlugin = {
                 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',
@@ -808,6 +898,7 @@ export const sharePlugin = {
         });
         const commands = [
             CommandIDs.open,
+            CommandIDs.upload,
             CommandIDs.save,
             CommandIDs.share,
             CommandIDs.rename,
@@ -865,7 +956,9 @@ export const sharePlugin = {
         });
         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 === null || mainMenu === void 0 ? void 0 : mainMenu.fileMenu;
@@ -873,6 +966,11 @@ export const sharePlugin = {
                     pruneFileMenu(fileMenu);
                     pruneBeforeEachOpen(fileMenu);
                 }
+                const newMenu = mainMenu === null || mainMenu === void 0 ? void 0 : mainMenu.fileMenu.newMenu;
+                if (newMenu instanceof Menu) {
+                    pruneFileMenu(newMenu, NON_NOTEBOOK_NEW_COMMANDS);
+                    pruneBeforeEachOpen(newMenu, NON_NOTEBOOK_NEW_COMMANDS);
+                }
                 routeSaves(tracker, pushQuietly);
             });
         }

package/lib/share/upload.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function chooseNotebookFile(): Promise<File | null>;

package/lib/share/upload.js

@@ -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() {
+    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) => {
+            input.remove();
+            resolve(file);
+        };
+        input.addEventListener('change', () => { var _a, _b; return settle((_b = (_a = input.files) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@oceanum/oceanumlab",
-    "version": "4.7.2",
+    "version": "4.8.0",
     "description": "A Jupyterlab extension to interact with the Oceanum.io platform",
     "keywords": [
         "jupyter",

package/schema/datamesh-connect.json

@@ -29,6 +29,12 @@
       "title": "Iterate",
       "description": "After running, send each cell's output back to the AI so it can fix an error or take the next step. Only takes effect with Auto-run code on.",
       "default": false
+    },
+    "showExamples": {
+      "type": "boolean",
+      "title": "Show examples",
+      "description": "List Oceanum's example notebooks in the Notebooks tab, where the site provides them. Also switched from the Examples heading.",
+      "default": true
     }
   },
   "patternProperties": {

package/src/DatameshWidget.tsx

@@ -555,6 +555,34 @@ function useAiAccess(
   return access;
 }
 
+/**
+ * The `showExamples` setting, read again whenever the settings change. True where the
+ * host passes no such setting; null while the host's setting has not loaded.
+ */
+function useShowExamples(
+  settingsChanged: ISignal<unknown, void>,
+  read: (() => boolean | null) | undefined
+): boolean | null {
+  const [show, setShow] = React.useState<boolean | null>(() =>
+    read ? read() : true
+  );
+
+  React.useEffect(() => {
+    if (!read) {
+      return;
+    }
+    const update = () => setShow(read());
+    // Anything that changed between the first render and now.
+    update();
+    settingsChanged.connect(update);
+    return () => {
+      settingsChanged.disconnect(update);
+    };
+  }, [settingsChanged, read]);
+
+  return show;
+}
+
 /**
  * Shows a message prompting the user to sign in to Oceanum.io, or to configure
  * their Datamesh token where the site has no sign-in. Only renders when there
@@ -966,6 +994,17 @@ export interface IDatameshWidgetProps {
   auth?: IOceanumAuth | null;
   /** Open a stored notebook by spec store id. */
   openStoredNotebook?: (id: string) => void;
+  /** Open a copy of an example by spec store id, named from its title. */
+  openExample?: (id: string, title: string) => void;
+  /** Upload a notebook from the user's computer. */
+  uploadNotebook?: () => void;
+  /**
+   * The `showExamples` setting: whether the Notebooks tab lists the examples; null
+   * until the settings have loaded.
+   */
+  showExamples?: () => boolean | null;
+  /** Save the `showExamples` setting, from the switch on the Examples heading. */
+  setShowExamples?: (show: boolean) => void;
 }
 
 /**
@@ -983,6 +1022,10 @@ function PanelTabs({
   settings,
   renderDatamesh,
   openStoredNotebook,
+  openExample,
+  uploadNotebook,
+  showExamples,
+  setShowExamples,
   selected,
   onSelect
 }: {
@@ -991,10 +1034,15 @@ function PanelTabs({
   settings: IAiSettings;
   renderDatamesh: () => React.ReactElement;
   openStoredNotebook?: (id: string) => void;
+  openExample?: (id: string, title: string) => void;
+  uploadNotebook?: () => void;
+  showExamples?: () => boolean | null;
+  setShowExamples?: (show: boolean) => void;
   selected: string;
   onSelect: (id: string) => void;
 }): React.ReactElement {
   const access = useAiAccess(commands, settings);
+  const examplesShown = useShowExamples(settings.settingsChanged, showExamples);
   const tabs: ITab[] = [
     {
       id: 'notebooks',
@@ -1006,6 +1054,12 @@ function PanelTabs({
           <StoredNotebooks
             auth={auth}
             onOpen={openStoredNotebook && (item => openStoredNotebook(item.id))}
+            onOpenExample={
+              openExample && (item => openExample(item.id, item.title))
+            }
+            onUpload={uploadNotebook}
+            showExamples={examplesShown}
+            onShowExamplesChange={setShowExamples}
             onSignIn={() => {
               startSignIn(commands, auth).catch(error => {
                 console.warn('Oceanum.io sign-in could not start.', error);
@@ -1147,6 +1201,10 @@ export class DatameshConnectWidget extends ReactWidget {
               settings={this.props}
               renderDatamesh={() => this.renderDatamesh()}
               openStoredNotebook={this.props.openStoredNotebook}
+              openExample={this.props.openExample}
+              uploadNotebook={this.props.uploadNotebook}
+              showExamples={this.props.showExamples}
+              setShowExamples={this.props.setShowExamples}
               selected={this.selectedTab}
               onSelect={id => this.selectTab(id)}
             />

package/src/StoredNotebooks.tsx

@@ -3,9 +3,18 @@ import * as React from 'react';
 import { IOceanumAuth } from './auth/tokens';
 import { SpecStoreClient } from './share/client';
 import { notebooksChanged } from './share/events';
-import { ISpecSummary, partitionSummaries } from './share/notebook';
+import {
+  INotebookDemoItem,
+  INotebookDemoSection,
+  ISpecSummary,
+  parseNotebookDemo,
+  partitionSummaries
+} from './share/notebook';
 import { SPEC_ID_ATTRIBUTE } from './share/plugin';
 
+/** Example rows carry their record id here, not in SPEC_ID_ATTRIBUTE: see Examples. */
+export const EXAMPLE_ID_ATTRIBUTE = 'data-example-id';
+
 export interface IStoredNotebooksProps {
   auth: IOceanumAuth;
   /**
@@ -13,6 +22,22 @@ export interface IStoredNotebooksProps {
    * the list then reads rather than offering a click that does nothing.
    */
   onOpen?: (item: ISpecSummary) => void;
+  /** Open a copy of an example, as `onOpen` does for a stored notebook. */
+  onOpenExample?: (item: INotebookDemoItem) => void;
+  /** Upload a notebook from the user's computer; no Upload button without it. */
+  onUpload?: () => void;
+  /**
+   * Whether the examples are listed, or folded under their heading. Default true. Null
+   * while the setting is still loading: the Examples wait for it, so examples a user
+   * has hidden never show for a moment first.
+   */
+  showExamples?: boolean | null;
+  /**
+   * Record the user's choice to show or hide the examples. The Examples heading offers
+   * its switch only where this is given: a switch that could not keep its setting
+   * would flip back on the next load.
+   */
+  onShowExamplesChange?: (show: boolean) => void;
   /**
    * Start signing in the way this host shows it; without it the auth's own `signIn()`
    * is used, which on a JupyterLab server shows no code dialog.
@@ -20,10 +45,158 @@ export interface IStoredNotebooksProps {
   onSignIn?: () => void;
 }
 
+/** The deployment's Notebook Demo record, which lists the Examples. */
+type Examples =
+  | { state: 'none' }
+  | { state: 'error'; message: string }
+  | { state: 'ready'; sections: INotebookDemoSection[] };
+
 type Load =
   | { state: 'loading' }
   | { state: 'error'; message: string }
-  | { state: 'ready'; items: ISpecSummary[] };
+  | { state: 'ready'; items: ISpecSummary[]; examples: Examples };
+
+/**
+ * Read the Notebook Demo record, if the deployment names one. Never rejects: a failure
+ * here is shown in the Examples section and leaves the rest of the tab alone.
+ */
+async function loadExamples(
+  auth: IOceanumAuth,
+  specsUrl: string,
+  id: string | null
+): Promise<Examples> {
+  if (!id) {
+    return { state: 'none' };
+  }
+  try {
+    const client = new SpecStoreClient({
+      specsUrl,
+      getAccessToken: () => auth.getAccessToken(),
+      specType: 'notebook-demo'
+    });
+    const record = await client.get(id);
+    return { state: 'ready', sections: parseNotebookDemo(record.spec) };
+  } catch (error) {
+    return {
+      state: 'error',
+      message:
+        error instanceof Error ? error.message : 'Could not reach Oceanum.io.'
+    };
+  }
+}
+
+/**
+ * The curated examples. Their rows deliberately leave out SPEC_ID_ATTRIBUTE and the
+ * stored-notebook row class: the share plugin's row menu (Open, Rename, Share, Delete)
+ * is bound to those, and none of it applies to Oceanum's own example records.
+ */
+function ExampleSections({
+  examples,
+  onOpen,
+  show,
+  onShowChange
+}: {
+  examples: Examples;
+  onOpen?: (item: INotebookDemoItem) => void;
+  show: boolean | null;
+  onShowChange?: (show: boolean) => void;
+}): React.ReactElement | null {
+  // Not yet known, or hidden with no switch to bring them back: nothing to show.
+  if (examples.state === 'none' || show === null || (!show && !onShowChange)) {
+    return null;
+  }
+  const count =
+    examples.state === 'ready'
+      ? examples.sections.reduce(
+          (total, section) => total + section.items.length,
+          0
+        )
+      : null;
+  if (count === 0) {
+    return null;
+  }
+  const heading = (
+    <div className="oceanum-notebooks-heading">
+      Examples
+      <span className="oceanum-notebooks-heading-end">
+        {count !== null && (
+          <span className="oceanum-notebooks-count">{count}</span>
+        )}
+        {onShowChange && (
+          <button
+            type="button"
+            role="switch"
+            aria-checked={show}
+            aria-label="Show examples"
+            title="Show examples"
+            className="oceanum-notebooks-switch"
+            onClick={() => onShowChange(!show)}
+          >
+            <span className="oceanum-notebooks-switch-thumb" />
+          </button>
+        )}
+      </span>
+    </div>
+  );
+  // Hidden: the heading stays, so the switch is there to bring them back.
+  if (!show) {
+    return <div className="oceanum-notebooks-section">{heading}</div>;
+  }
+  if (examples.state === 'error') {
+    return (
+      <div className="oceanum-notebooks-section">
+        {heading}
+        <div className="oceanum-text-error">
+          The examples could not be loaded. {examples.message}
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div className="oceanum-notebooks-section">
+      {heading}
+      {examples.sections.map((section, index) => (
+        <div key={index}>
+          {/* Titles come from the record: React escapes them, never set as HTML. */}
+          <div className="oceanum-notebooks-subheading">{section.title}</div>
+          <ul className="oceanum-notebooks-list">
+            {section.items.map((item, position) => {
+              const attributes = {
+                [EXAMPLE_ID_ATTRIBUTE]: item.id,
+                title: item.summary
+              };
+              const name = (
+                <span className="oceanum-notebooks-name">{item.title}</span>
+              );
+              return (
+                // A record may list the same example twice; the id alone is no key.
+                <li key={`${position}:${item.id}`}>
+                  {onOpen ? (
+                    <button
+                      type="button"
+                      className="oceanum-notebooks-example"
+                      onClick={() => onOpen(item)}
+                      {...attributes}
+                    >
+                      {name}
+                    </button>
+                  ) : (
+                    <div
+                      className="oceanum-notebooks-example oceanum-notebooks-item-static"
+                      {...attributes}
+                    >
+                      {name}
+                    </div>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+}
 
 function Section({
   title,
@@ -90,6 +263,10 @@ function Section({
 export function StoredNotebooks({
   auth,
   onOpen,
+  onOpenExample,
+  onUpload,
+  showExamples = true,
+  onShowExamplesChange,
   onSignIn
 }: IStoredNotebooksProps): React.ReactElement {
   const [load, setLoad] = React.useState<Load>({ state: 'loading' });
@@ -115,7 +292,7 @@ export function StoredNotebooks({
     let cancelled = false;
     const specs = auth.urls?.specs ?? null;
     if (!user || !specs) {
-      setLoad({ state: 'ready', items: [] });
+      setLoad({ state: 'ready', items: [], examples: { state: 'none' } });
       return;
     }
     setLoad({ state: 'loading' });
@@ -125,9 +302,14 @@ export function StoredNotebooks({
           specsUrl: specs,
           getAccessToken: () => auth.getAccessToken()
         });
-        const items = await client.list();
+        // Only the record the deployment names: every signed-in user can create
+        // notebook-demo records, so the examples never come from a listing.
+        const [items, examples] = await Promise.all([
+          client.list(),
+          loadExamples(auth, specs, auth.environment?.notebookDemo ?? null)
+        ]);
         if (!cancelled) {
-          setLoad({ state: 'ready', items });
+          setLoad({ state: 'ready', items, examples });
         }
       } catch (error) {
         if (!cancelled) {
@@ -187,8 +369,30 @@ export function StoredNotebooks({
   }
 
   const { mine, shared } = partitionSummaries(load.items, user.email);
+  // A public example is readable by everyone, so the listing returns it as shared with
+  // every signed-in user; it is shown under Examples instead.
+  const exampleIds = new Set(
+    load.examples.state === 'ready'
+      ? load.examples.sections.flatMap(section =>
+          section.items.map(item => item.id)
+        )
+      : []
+  );
   return (
     <div className="oceanum-notebooks">
+      {/* Without a spec store the upload command does nothing. */}
+      {onUpload && auth.urls?.specs ? (
+        <div className="oceanum-notebooks-actions">
+          <button
+            type="button"
+            className="oceanum-notebooks-upload"
+            title="Upload a notebook from this computer, to save on Oceanum.io"
+            onClick={onUpload}
+          >
+            Upload notebook…
+          </button>
+        </div>
+      ) : null}
       <Section
         title="My notebooks"
         items={mine}
@@ -197,10 +401,16 @@ export function StoredNotebooks({
       />
       <Section
         title="Shared with me"
-        items={shared}
+        items={shared.filter(item => !exampleIds.has(item.id))}
         empty="No notebooks have been shared with you."
         onOpen={onOpen}
       />
+      <ExampleSections
+        examples={load.examples}
+        onOpen={onOpenExample}
+        show={showExamples}
+        onShowChange={onShowExamplesChange}
+      />
     </div>
   );
 }