@oceanum/oceanumlab 4.8.0 → 4.10.0

package/lib/share/notebook.js

@@ -237,45 +237,25 @@ export function partitionSummaries(items, email) {
         shared: sorted.filter(item => !isMine(item))
     };
 }
-/** The `kind` of a Notebook Demo record's spec. */
-export const NOTEBOOK_DEMO_KIND = 'notebook-demo';
-function nonBlank(value) {
-    return typeof value === 'string' && value.trim() !== '';
-}
+/** The spec store type of the Notebook Demo specs, which are the Examples. */
+export const NOTEBOOK_DEMO_TYPE = 'notebook-demo';
 /**
- * The sections of a Notebook Demo record's spec, keeping only what can be listed: items
- * with a record id and a title, in sections with a title and at least one such item.
- * A spec of another kind or version gives no sections, with a warning.
+ * The examples in a listing of Notebook Demo specs, ordered by name as people number
+ * them ("2 …" before "10 …").
  */
-export function parseNotebookDemo(spec) {
-    if (!isObject(spec) ||
-        spec.kind !== NOTEBOOK_DEMO_KIND ||
-        spec.version !== 1 ||
-        !Array.isArray(spec.sections)) {
-        console.warn('Oceanum: ignoring a Notebook Demo record this version cannot read.');
-        return [];
-    }
-    const sections = [];
-    for (const section of spec.sections) {
-        if (!isObject(section) ||
-            !nonBlank(section.title) ||
-            !Array.isArray(section.items)) {
-            continue;
-        }
-        const items = [];
-        for (const item of section.items) {
-            if (!isObject(item) || !isSpecId(item.id) || !nonBlank(item.title)) {
-                continue;
-            }
-            items.push(typeof item.summary === 'string'
-                ? { id: item.id, title: item.title, summary: item.summary }
-                : { id: item.id, title: item.title });
-        }
-        if (items.length > 0) {
-            sections.push({ title: section.title, items });
-        }
-    }
-    return sections;
+export function demoItemsFromSummaries(summaries) {
+    // 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) {

package/lib/share/plugin.js

@@ -9,7 +9,8 @@ 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, notebookFromUpload, notebookNamesFor, OCEANUM_DIR, partitionSummaries, QUERY_PARAM, readLink, reportForShareFailures, sanitizeName, shareLink, uniqueNotebookPath, unlinkedNotebookFromRecord } from './notebook';
+import { decodePayload, hashWithoutPayload, notebookFromDatamesh, notebookName, payloadFromHash } from './fromDatamesh';
+import { buildSpecBody, isSpecId, METADATA_KEY, notebookFromRecord, notebookFromUpload, notebookNamesFor, NOTEBOOK_DEMO_TYPE, 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';
@@ -51,6 +52,11 @@ export const sharePlugin = {
                 client: new SpecStoreClient({
                     specsUrl,
                     getAccessToken: () => auth.getAccessToken()
+                }),
+                demos: new SpecStoreClient({
+                    specsUrl,
+                    getAccessToken: () => auth.getAccessToken(),
+                    specType: NOTEBOOK_DEMO_TYPE
                 })
             };
         const oceanumOnly = store !== null && ((_c = auth.environment) === null || _c === void 0 ? void 0 : _c.fileManagement) === 'oceanum';
@@ -64,6 +70,22 @@ export const sharePlugin = {
         let signInGeneration = 0;
         let warnedSignedOut = false;
         const signedIn = () => store !== null && auth.user !== null;
+        // A workspace sent by the Datamesh UI's "Open in notebook". Read it now, before
+        // anything can rewrite the address. It stays in the address until the notebook
+        // is written (see openFromDatamesh), so nothing is lost if the page is left
+        // before then. Not handled: a full-page sign-in redirect (signInRedirect) puts
+        // the hash back only after this plugin has activated, so the workspace opens
+        // on the next load rather than this one.
+        const datameshPayload = payloadFromHash(window.location.hash);
+        /** Remove the payload from the address, so a reload does not open a copy. */
+        const clearDatameshPayload = () => {
+            const url = new URL(window.location.href);
+            const hash = hashWithoutPayload(url.hash);
+            if (hash !== url.hash) {
+                url.hash = hash;
+                window.history.replaceState(window.history.state, '', url.toString());
+            }
+        };
         const label = (text) => () => store ? text : `${text}${UNAVAILABLE}`;
         // --- what a command acts on ---------------------------------------------------
         /**
@@ -293,7 +315,7 @@ export const sharePlugin = {
             }
             openingExamples.add(id);
             try {
-                const record = await store.client.get(id);
+                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));
@@ -798,6 +820,37 @@ export const sharePlugin = {
             }
             clearQuery();
         }
+        /**
+         * Open a new notebook that loads a Datamesh UI workspace or query. It is written to
+         * the Oceanum folder unlinked, like an example, so the first save creates a record
+         * of the user's own. Nothing runs until the user runs it.
+         */
+        async function openFromDatamesh(encoded) {
+            let content;
+            let name;
+            try {
+                const request = decodePayload(encoded);
+                content = notebookFromDatamesh(request);
+                name = notebookName(request);
+            }
+            catch (error) {
+                clearDatameshPayload();
+                Notification.warning(error instanceof Error
+                    ? error.message
+                    : 'The Datamesh link is not valid.', { autoClose: 5000 });
+                return;
+            }
+            try {
+                const path = uniqueNotebookPath(name, await oceanumFolderNames());
+                await writeAndOpen(path, content);
+            }
+            catch (error) {
+                await reportError('Opening the Datamesh workspace failed', error);
+            }
+            finally {
+                clearDatameshPayload();
+            }
+        }
         // --- commands -----------------------------------------------------------------
         /** Whether the command can act on the pointer's row, the target notebook, or both. */
         const enabledFor = (wants, args) => {
@@ -977,5 +1030,8 @@ export const sharePlugin = {
         Promise.all([app.restored, auth.ready])
             .then(() => openFromQuery())
             .catch(error => console.error('Failed to open the Oceanum notebook link', error));
+        if (datameshPayload !== null) {
+            void app.restored.then(() => openFromDatamesh(datameshPayload));
+        }
     }
 };

package/package.json

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

package/schema/datamesh-connect.json

@@ -33,7 +33,7 @@
     "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.",
+      "description": "List Oceanum's example notebooks (its Notebook Demo specs) in the Notebooks tab. Also switched from the Examples heading.",
       "default": true
     }
   },

package/src/StoredNotebooks.tsx

@@ -1,13 +1,13 @@
 import * as React from 'react';
 
 import { IOceanumAuth } from './auth/tokens';
-import { SpecStoreClient } from './share/client';
+import { SpecStoreClient, SpecStoreError } from './share/client';
 import { notebooksChanged } from './share/events';
 import {
+  demoItemsFromSummaries,
   INotebookDemoItem,
-  INotebookDemoSection,
   ISpecSummary,
-  parseNotebookDemo,
+  NOTEBOOK_DEMO_TYPE,
   partitionSummaries
 } from './share/notebook';
 import { SPEC_ID_ATTRIBUTE } from './share/plugin';
@@ -45,11 +45,11 @@ export interface IStoredNotebooksProps {
   onSignIn?: () => void;
 }
 
-/** The deployment's Notebook Demo record, which lists the Examples. */
+/** The Notebook Demo specs the user can read, which are the Examples. */
 type Examples =
   | { state: 'none' }
   | { state: 'error'; message: string }
-  | { state: 'ready'; sections: INotebookDemoSection[] };
+  | { state: 'ready'; items: INotebookDemoItem[] };
 
 type Load =
   | { state: 'loading' }
@@ -57,26 +57,29 @@ type Load =
   | { 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.
+ * List the Notebook Demo specs, each one an example notebook. Only org oceanum may
+ * create them (spec store 0.6.2), so every one listed is Oceanum's. 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
+  specsUrl: string
 ): Promise<Examples> {
-  if (!id) {
-    return { state: 'none' };
-  }
   try {
     const client = new SpecStoreClient({
       specsUrl,
       getAccessToken: () => auth.getAccessToken(),
-      specType: 'notebook-demo'
+      specType: NOTEBOOK_DEMO_TYPE
     });
-    const record = await client.get(id);
-    return { state: 'ready', sections: parseNotebookDemo(record.spec) };
+    return {
+      state: 'ready',
+      items: demoItemsFromSummaries(await client.list())
+    };
   } catch (error) {
+    // A store with no Notebook Demo type has no examples, which is not an error.
+    if (error instanceof SpecStoreError && error.kind === 'not-found') {
+      return { state: 'none' };
+    }
     return {
       state: 'error',
       message:
@@ -86,9 +89,10 @@ async function loadExamples(
 }
 
 /**
- * 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.
+ * The examples: Oceanum's Notebook Demo specs. 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,
@@ -105,13 +109,7 @@ function ExampleSections({
   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;
+  const count = examples.state === 'ready' ? examples.items.length : null;
   if (count === 0) {
     return null;
   }
@@ -155,45 +153,39 @@ function ExampleSections({
   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>
-      ))}
+      <ul className="oceanum-notebooks-list">
+        {examples.items.map(item => {
+          const attributes = {
+            [EXAMPLE_ID_ATTRIBUTE]: item.id,
+            title: item.summary
+          };
+          // Names come from the spec store: React escapes them, never set as HTML.
+          const name = (
+            <span className="oceanum-notebooks-name">{item.title}</span>
+          );
+          return (
+            <li key={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>
   );
 }
@@ -302,11 +294,9 @@ export function StoredNotebooks({
           specsUrl: specs,
           getAccessToken: () => auth.getAccessToken()
         });
-        // 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)
+          loadExamples(auth, specs)
         ]);
         if (!cancelled) {
           setLoad({ state: 'ready', items, examples });
@@ -369,15 +359,6 @@ 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. */}
@@ -401,7 +382,7 @@ export function StoredNotebooks({
       />
       <Section
         title="Shared with me"
-        items={shared.filter(item => !exampleIds.has(item.id))}
+        items={shared}
         empty="No notebooks have been shared with you."
         onOpen={onOpen}
       />

package/src/__tests__/OceanumPanel.spec.tsx

@@ -160,7 +160,6 @@ describe('the Oceanum panel', () => {
 });
 
 describe('the Examples switch in the Oceanum panel', () => {
-  const DEMO_ID = '3e4f5a6b-4444-4a2b-8c3d-9e8f7a6b5c4d';
   const EXAMPLE = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
   const originalFetch = globalThis.fetch;
   afterEach(() => {
@@ -179,27 +178,23 @@ describe('the Examples switch in the Oceanum panel', () => {
 
   it('saves the choice, and follows the setting once it has changed', async () => {
     globalThis.fetch = (async (input: RequestInfo | URL) => {
-      const demo = String(input).includes('/specs/notebook-demo/');
-      const data: unknown = demo
-        ? {
-            id: DEMO_ID,
-            name: 'Notebook Demo',
-            description: null as string | null,
-            modified: '2026-09-22T10:00:00',
-            creator: null as string | null,
-            spec: {
-              kind: 'notebook-demo',
-              version: 1,
-              sections: [
-                { title: 'Start', items: [{ id: EXAMPLE, title: 'Query' }] }
-              ]
+      // The Notebook Demo listing has one example; the user has no notebooks.
+      const demos = String(input).endsWith('/specs/notebook-demo');
+      const data: unknown = demos
+        ? [
+            {
+              id: EXAMPLE,
+              name: 'Query',
+              description: null as string | null,
+              modified: '2026-09-22T10:00:00',
+              creator: null as string | null
             }
-          }
+          ]
         : [];
       return { ok: true, status: 200, json: async () => data } as Response;
     }) as typeof fetch;
     const auth = {
-      environment: { notebookDemo: DEMO_ID },
+      environment: {},
       urls: { specs: 'https://specs.example.com' },
       ready: Promise.resolve(),
       user: {