@oceanum/oceanumlab 4.7.1 → 4.8.0

package/src/StoredNotebooks.tsx

@@ -1,22 +1,202 @@
 import * as React from 'react';
 
 import { IOceanumAuth } from './auth/tokens';
-import { ISpecSummary, listNotebooks, partitionNotebooks } from './specStore';
+import { SpecStoreClient } from './share/client';
+import { notebooksChanged } from './share/events';
+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;
   /**
-   * Open a stored notebook, when this host can. Undefined where nothing has registered
-   * a way to open one — today that is native JupyterLab, which has no spec store drive
-   * until OCE-182. The list then reads rather than offering an action that does nothing.
+   * Open a stored notebook. Undefined where nothing has registered a way to open one;
+   * 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.
+   */
+  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,
@@ -29,6 +209,12 @@ function Section({
   empty: string;
   onOpen?: (item: ISpecSummary) => void;
 }): React.ReactElement {
+  // Each row carries its record id so the share plugin's context menu (Open, Rename,
+  // Share, Delete) can tell which one was clicked.
+  const rowAttributes = (item: ISpecSummary) => ({
+    [SPEC_ID_ATTRIBUTE]: item.id,
+    title: item.description ?? undefined
+  });
   return (
     <div className="oceanum-notebooks-section">
       <div className="oceanum-notebooks-heading">
@@ -47,7 +233,7 @@ function Section({
                   type="button"
                   className="oceanum-notebooks-item"
                   onClick={() => onOpen(item)}
-                  title={item.description ?? undefined}
+                  {...rowAttributes(item)}
                 >
                   <span className="oceanum-notebooks-name">
                     {item.name || 'Untitled'}
@@ -56,7 +242,7 @@ function Section({
               ) : (
                 <div
                   className="oceanum-notebooks-item oceanum-notebooks-item-static"
-                  title={item.description ?? undefined}
+                  {...rowAttributes(item)}
                 >
                   <span className="oceanum-notebooks-name">
                     {item.name || 'Untitled'}
@@ -76,18 +262,29 @@ function Section({
  */
 export function StoredNotebooks({
   auth,
-  onOpen
+  onOpen,
+  onOpenExample,
+  onUpload,
+  showExamples = true,
+  onShowExamplesChange,
+  onSignIn
 }: IStoredNotebooksProps): React.ReactElement {
   const [load, setLoad] = React.useState<Load>({ state: 'loading' });
   const [user, setUser] = React.useState(auth.user);
+  // Bumped whenever the store changes, so the list is fetched again.
+  const [version, setVersion] = React.useState(0);
 
   // Reload whenever the signed-in user changes, so signing in or out does not leave a
-  // stale list from the previous session on screen.
+  // stale list from the previous session on screen; and whenever this extension has
+  // created, renamed or deleted a record.
   React.useEffect(() => {
     const onUser = (): void => setUser(auth.user);
+    const onChanged = (): void => setVersion(v => v + 1);
     auth.userChanged.connect(onUser);
+    notebooksChanged.connect(onChanged);
     return () => {
       auth.userChanged.disconnect(onUser);
+      notebooksChanged.disconnect(onChanged);
     };
   }, [auth]);
 
@@ -95,23 +292,24 @@ 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' });
     void (async () => {
       try {
-        const token = await auth.getAccessToken();
-        if (cancelled) {
-          return;
-        }
-        if (!token) {
-          setLoad({ state: 'ready', items: [] });
-          return;
-        }
-        const items = await listNotebooks(specs, token);
+        const client = new SpecStoreClient({
+          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)
+        ]);
         if (!cancelled) {
-          setLoad({ state: 'ready', items });
+          setLoad({ state: 'ready', items, examples });
         }
       } catch (error) {
         if (!cancelled) {
@@ -128,12 +326,36 @@ export function StoredNotebooks({
     return () => {
       cancelled = true;
     };
-  }, [auth, user]);
+  }, [auth, user, version]);
 
   if (!user) {
+    const signIn = (): void => {
+      if (onSignIn) {
+        onSignIn();
+        return;
+      }
+      auth.signIn().catch(error => {
+        console.warn('Oceanum.io sign-in could not start.', error);
+      });
+    };
     return (
       <div className="oceanum-text-empty">
-        Sign in to Oceanum.io to see your notebooks.
+        {/* A link rather than a button to match the panel's other actions, so it
+            carries the role and the keys a button would have. */}
+        <a
+          role="button"
+          tabIndex={0}
+          onClick={signIn}
+          onKeyDown={event => {
+            if (event.key === 'Enter' || event.key === ' ') {
+              event.preventDefault();
+              signIn();
+            }
+          }}
+        >
+          Sign in
+        </a>{' '}
+        to Oceanum.io to see your notebooks.
       </div>
     );
   }
@@ -146,9 +368,31 @@ export function StoredNotebooks({
     return <div className="oceanum-text-error">{load.message}</div>;
   }
 
-  const { mine, shared } = partitionNotebooks(load.items, user.email);
+  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}
@@ -157,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>
   );
 }

package/src/__tests__/OceanumPanel.spec.tsx

@@ -11,8 +11,29 @@ const icon = new LabIcon({
   svgstr: '<svg xmlns="http://www.w3.org/2000/svg"></svg>'
 });
 
-function panel(): DatameshConnectWidget {
+interface IPanelOptions {
+  /** The `datameshToken` setting value. */
+  token?: string;
+  /** Register the host's sign-in commands, and say whether someone is signed in. */
+  signedIn?: boolean;
+  /** Widget props to use instead of the defaults below. */
+  props?: Record<string, unknown>;
+}
+
+function panel(options: IPanelOptions = {}): DatameshConnectWidget {
   const commands = new CommandRegistry();
+  if (options.signedIn !== undefined) {
+    // What the host provides: sign-out is visible only while signed in, which is how
+    // the sidebar reads the state without running anything.
+    commands.addCommand('oceanum-auth:sign-out', {
+      execute: () => undefined,
+      isVisible: () => options.signedIn === true
+    });
+    commands.addCommand('oceanum-auth:access-token', {
+      execute: () => null,
+      isVisible: () => false
+    });
+  }
   const app = {
     shell: { currentWidget: null },
     commands
@@ -24,17 +45,20 @@ function panel(): DatameshConnectWidget {
     openDatameshUI: (): void => undefined,
     datameshUiUrl: () => 'https://ui.datamesh.example.com',
     datameshUiFrame: (): Window | null => null,
-    datameshToken: () => '',
+    datameshToken: () => options.token ?? '',
     aiBackendUrl: () => 'https://ai.example.com',
     settingsChanged: new Signal<unknown, void>({}),
     commands,
     getCurrentWidget: () => new Widget(),
-    auth: null
+    auth: null,
+    ...options.props
   } as unknown as ConstructorParameters<typeof DatameshConnectWidget>[0]);
 }
 
-async function mount(): Promise<DatameshConnectWidget> {
-  const widget = panel();
+async function mount(
+  options: IPanelOptions = {}
+): Promise<DatameshConnectWidget> {
+  const widget = panel(options);
   Widget.attach(widget, document.body);
   await new Promise(resolve => setTimeout(resolve, 100));
   return widget;
@@ -46,6 +70,19 @@ async function mount(): Promise<DatameshConnectWidget> {
  * touches the Datamesh surface, so nothing else here would notice if rearranging the
  * two lost one of them.
  */
+beforeAll(() => {
+  // The AI chat scrolls to its last message, and every pane renders whether or not it
+  // is the selected one. jsdom has no scrollIntoView, and the error would come back as
+  // React unmounting the whole sidebar.
+  (Element.prototype as unknown as Record<string, unknown>).scrollIntoView =
+    (): void => undefined;
+});
+
+const tabLabels = (widget: DatameshConnectWidget): (string | null)[] =>
+  Array.from(widget.node.querySelectorAll('[role="tab"]')).map(
+    node => node.textContent
+  );
+
 describe('the Oceanum panel', () => {
   it('offers no Oceanum AI tab when the chat has no credential', async () => {
     // AIChatPanel renders nothing without one, so a labelled tab would open on the
@@ -61,6 +98,28 @@ describe('the Oceanum panel', () => {
     widget.dispose();
   });
 
+  it('offers no Oceanum AI tab for a pasted token alone, until someone signs in', async () => {
+    // The token would reach the backend, but the tab waits for a sign-in.
+    const withToken = await mount({ token: 'a-datamesh-token' });
+    expect(tabLabels(withToken)).toEqual(['Notebooks', 'Datamesh']);
+    withToken.dispose();
+
+    const signedOut = await mount({
+      token: 'a-datamesh-token',
+      signedIn: false
+    });
+    expect(tabLabels(signedOut)).toEqual(['Notebooks', 'Datamesh']);
+    signedOut.dispose();
+  });
+
+  it('offers the Oceanum AI tab once the host says the user is signed in', async () => {
+    const widget = await mount({ signedIn: true });
+
+    expect(tabLabels(widget)).toEqual(['Notebooks', 'Datamesh', 'Oceanum AI']);
+
+    widget.dispose();
+  });
+
   it('still renders the Datamesh workspace section', async () => {
     const widget = await mount();
 
@@ -99,3 +158,98 @@ describe('the Oceanum panel', () => {
     widget.dispose();
   });
 });
+
+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(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const until = async (test: () => boolean): Promise<void> => {
+    const deadline = Date.now() + 4000;
+    while (!test()) {
+      if (Date.now() > deadline) {
+        throw new Error('timed out');
+      }
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  };
+
+  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' }] }
+              ]
+            }
+          }
+        : [];
+      return { ok: true, status: 200, json: async () => data } as Response;
+    }) as typeof fetch;
+    const auth = {
+      environment: { notebookDemo: DEMO_ID },
+      urls: { specs: 'https://specs.example.com' },
+      ready: Promise.resolve(),
+      user: {
+        sub: 'auth0|1',
+        email: 'me@example.com',
+        name: null as string | null,
+        activeOrg: null as string | null,
+        colorScheme: null as string | null
+      },
+      userChanged: new Signal<unknown, unknown>({}),
+      tokenChanged: new Signal<unknown, unknown>({}),
+      signIn: async (): Promise<void> => undefined,
+      signOut: async (): Promise<void> => undefined,
+      getAccessToken: async (): Promise<string> => 'tok'
+    };
+    // What the host keeps: the setting, and the signal it emits when it changes.
+    // Null until the host's settings load.
+    let shown: boolean | null = null;
+    const saved: boolean[] = [];
+    const settingsChanged = new Signal<unknown, void>({});
+    const widget = await mount({
+      props: {
+        auth,
+        settingsChanged,
+        showExamples: () => shown,
+        setShowExamples: (show: boolean) => saved.push(show)
+      }
+    });
+    const toggle = (): HTMLButtonElement | null =>
+      widget.node.querySelector<HTMLButtonElement>('[role="switch"]');
+    // The tab has loaded, but the examples wait for the setting.
+    await until(() => widget.node.querySelector('.oceanum-notebooks') !== null);
+    expect(toggle()).toBeNull();
+    expect(widget.node.querySelector('[data-example-id]')).toBeNull();
+
+    shown = true;
+    settingsChanged.emit();
+    await until(() => toggle() !== null);
+    expect(toggle()!.getAttribute('aria-checked')).toBe('true');
+    expect(widget.node.querySelector('[data-example-id]')).not.toBeNull();
+
+    toggle()!.click();
+    expect(saved).toEqual([false]);
+
+    // The host saves the setting and says so; the panel reads it again.
+    shown = false;
+    settingsChanged.emit();
+    await until(() => toggle()?.getAttribute('aria-checked') === 'false');
+    expect(widget.node.querySelector('[data-example-id]')).toBeNull();
+
+    widget.dispose();
+  });
+});