@oceanum/oceanumlab 4.8.0 → 4.10.0

package/lib/StoredNotebooks.js

@@ -1,28 +1,32 @@
 import * as React from 'react';
-import { SpecStoreClient } from './share/client';
+import { SpecStoreClient, SpecStoreError } from './share/client';
 import { notebooksChanged } from './share/events';
-import { parseNotebookDemo, partitionSummaries } from './share/notebook';
+import { demoItemsFromSummaries, NOTEBOOK_DEMO_TYPE, 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';
 /**
- * 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, specsUrl, id) {
-    if (!id) {
-        return { state: 'none' };
-    }
+async function loadExamples(auth, specsUrl) {
     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: error instanceof Error ? error.message : 'Could not reach Oceanum.io.'
@@ -30,18 +34,17 @@ async function loadExamples(auth, specsUrl, id) {
     }
 }
 /**
- * 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, onOpen, show, onShowChange }) {
     // 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;
+    const count = examples.state === 'ready' ? examples.items.length : null;
     if (count === 0) {
         return null;
     }
@@ -64,18 +67,15 @@ function ExampleSections({ examples, onOpen, show, onShowChange }) {
     }
     return (React.createElement("div", { className: "oceanum-notebooks-section" },
         heading,
-        examples.sections.map((section, index) => (React.createElement("div", { key: index },
-            React.createElement("div", { className: "oceanum-notebooks-subheading" }, section.title),
-            React.createElement("ul", { className: "oceanum-notebooks-list" }, section.items.map((item, position) => {
-                const attributes = {
-                    [EXAMPLE_ID_ATTRIBUTE]: item.id,
-                    title: item.summary
-                };
-                const name = (React.createElement("span", { className: "oceanum-notebooks-name" }, item.title));
-                return (
-                // A record may list the same example twice; the id alone is no key.
-                React.createElement("li", { key: `${position}:${item.id}` }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-example", onClick: () => onOpen(item), ...attributes }, name)) : (React.createElement("div", { className: "oceanum-notebooks-example oceanum-notebooks-item-static", ...attributes }, name))));
-            })))))));
+        React.createElement("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 = (React.createElement("span", { className: "oceanum-notebooks-name" }, item.title));
+            return (React.createElement("li", { key: item.id }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-example", onClick: () => onOpen(item), ...attributes }, name)) : (React.createElement("div", { className: "oceanum-notebooks-example oceanum-notebooks-item-static", ...attributes }, name))));
+        }))));
 }
 function Section({ title, items, empty, onOpen }) {
     // Each row carries its record id so the share plugin's context menu (Open, Rename,
@@ -127,17 +127,14 @@ export function StoredNotebooks({ auth, onOpen, onOpenExample, onUpload, showExa
         }
         setLoad({ state: 'loading' });
         void (async () => {
-            var _a, _b;
             try {
                 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, (_b = (_a = auth.environment) === null || _a === void 0 ? void 0 : _a.notebookDemo) !== null && _b !== void 0 ? _b : null)
+                    loadExamples(auth, specs)
                 ]);
                 if (!cancelled) {
                     setLoad({ state: 'ready', items, examples });
@@ -187,15 +184,10 @@ export function StoredNotebooks({ auth, onOpen, onOpenExample, onUpload, showExa
         return React.createElement("div", { className: "oceanum-text-error" }, load.message);
     }
     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 (React.createElement("div", { className: "oceanum-notebooks" },
         onUpload && ((_a = auth.urls) === null || _a === void 0 ? void 0 : _a.specs) ? (React.createElement("div", { className: "oceanum-notebooks-actions" },
             React.createElement("button", { type: "button", className: "oceanum-notebooks-upload", title: "Upload a notebook from this computer, to save on Oceanum.io", onClick: onUpload }, "Upload notebook\u2026"))) : null,
         React.createElement(Section, { title: "My notebooks", items: mine, empty: "You have not saved any notebooks yet.", onOpen: onOpen }),
-        React.createElement(Section, { title: "Shared with me", items: shared.filter(item => !exampleIds.has(item.id)), empty: "No notebooks have been shared with you.", onOpen: onOpen }),
+        React.createElement(Section, { title: "Shared with me", items: shared, empty: "No notebooks have been shared with you.", onOpen: onOpen }),
         React.createElement(ExampleSections, { examples: load.examples, onOpen: onOpenExample, show: showExamples, onShowChange: onShowExamplesChange })));
 }

package/lib/auth/tokens.d.ts

@@ -31,12 +31,6 @@ export interface IOceanumEnvironment {
      * absent) keeps JupyterLab's file management alongside the Oceanum commands.
      */
     readonly fileManagement?: 'local' | 'oceanum';
-    /**
-     * The spec store id of this deployment's Notebook Demo record, the curated list the
-     * Notebooks tab shows as Examples. Absent where a deployment has none, and never set
-     * by a JupyterLab server's sign-in.
-     */
-    readonly notebookDemo?: string;
 }
 /** Service base URLs for an environment, without trailing slashes. */
 export interface IOceanumServiceUrls {

package/lib/share/fromDatamesh.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Notebooks generated from a Datamesh UI workspace or query.
+ *
+ * The Datamesh UI's "Open in notebook" button opens this app with the workspace in the
+ * address fragment, `#oceanum-datamesh=<base64url JSON>`. The fragment is never sent
+ * to a server, so the queries stay out of request logs and are not bound by URL
+ * length limits on the way in.
+ *
+ * Anyone can craft such a link, so the payload is treated as data only: it is
+ * validated, every value reaches the notebook as a Python literal, and the notebook is
+ * built from fixed templates, opened untrusted and never run automatically.
+ */
+import type { INotebookContent } from '@jupyterlab/nbformat';
+/** Fragment key carrying a Datamesh workspace. */
+export declare const FRAGMENT_KEY = "oceanum-datamesh";
+/** Payload version this module reads. */
+export declare const PAYLOAD_VERSION = 1;
+/** Most queries one link may carry. */
+export declare const MAX_ITEMS = 100;
+/** Longest encoded payload accepted (characters of base64url). */
+export declare const MAX_ENCODED_LENGTH: number;
+/**
+ * Deepest nesting of arrays and objects accepted. Real queries, GeoJSON
+ * multipolygon geofilters included, nest about 8 deep.
+ */
+export declare const MAX_DEPTH = 32;
+/** One query: an OceanQL spec plus the Datamesh UI's own `label`. */
+export interface IDatameshQuery {
+    datasource: string;
+    label?: string | null;
+    description?: string | null;
+    [key: string]: unknown;
+}
+/** What the fragment carries. */
+export interface IDatameshNotebookRequest {
+    v: typeof PAYLOAD_VERSION;
+    /** Workspace name, used for the notebook name and heading. */
+    name?: string;
+    items: IDatameshQuery[];
+}
+/** UTF-8 JSON to base64url, without padding. */
+export declare function encodePayload(request: IDatameshNotebookRequest): string;
+/**
+ * Read and validate a payload. Throws an `Error` whose message can be shown to the
+ * user; it never quotes the payload.
+ */
+export declare function decodePayload(encoded: string): IDatameshNotebookRequest;
+/**
+ * The payload in a location hash (`#oceanum-datamesh=...`), or null when the hash
+ * carries none. Other parts of the hash are ignored.
+ */
+export declare function payloadFromHash(hash: string): string | null;
+/**
+ * The hash with the payload removed (`''` when nothing else is left). Every other
+ * part is kept exactly as it was.
+ */
+export declare function hashWithoutPayload(hash: string): string;
+/**
+ * A Python string literal. JSON's escaping is valid Python and escapes C0 controls;
+ * the C1 controls and U+2028/U+2029 it leaves raw are escaped too, so the generated
+ * source has no character a kernel could treat as a line break.
+ */
+export declare function pyString(text: string): string;
+/**
+ * A Python literal for a JSON value, wrapped over indented lines when it does not
+ * fit on one. Strings and keys go through `pyString`, so no value can end the
+ * literal early or break the line.
+ */
+export declare function pyLiteral(value: unknown, indent?: number): string;
+/** A Python identifier for `text`, not in `taken`; adds it to `taken`. */
+export declare function pyIdentifier(text: string, taken: Set<string>): string;
+/** The OceanQL query to send: only fields oceanum-python's `Query` accepts. */
+export declare function queryFields(item: IDatameshQuery): Record<string, unknown>;
+/** The code cell that loads one query into a variable and shows it. */
+export declare function queryCellSource(item: IDatameshQuery, variable: string): string;
+/** The notebook name for a request: the workspace name, or the single query's. */
+export declare function notebookName(request: IDatameshNotebookRequest): string;
+/**
+ * A new notebook that loads every query in `request`. It carries no `oceanum` link and
+ * no trust, so saving it creates a record of the user's own.
+ */
+export declare function notebookFromDatamesh(request: IDatameshNotebookRequest): INotebookContent;

package/lib/share/fromDatamesh.js

@@ -0,0 +1,379 @@
+/** Fragment key carrying a Datamesh workspace. */
+export const FRAGMENT_KEY = 'oceanum-datamesh';
+/** Payload version this module reads. */
+export const PAYLOAD_VERSION = 1;
+/** Most queries one link may carry. */
+export const MAX_ITEMS = 100;
+/** Longest encoded payload accepted (characters of base64url). */
+export const MAX_ENCODED_LENGTH = 4 * 1024 * 1024;
+/**
+ * Deepest nesting of arrays and objects accepted. Real queries, GeoJSON
+ * multipolygon geofilters included, nest about 8 deep.
+ */
+export const MAX_DEPTH = 32;
+/** Nesting depth of a JSON value (a scalar is 0), without recursion. */
+function depthOf(value) {
+    let max = 0;
+    const stack = [[value, 0]];
+    while (stack.length) {
+        const [v, d] = stack.pop();
+        if (v !== null && typeof v === 'object') {
+            max = Math.max(max, d + 1);
+            if (max > MAX_DEPTH) {
+                return max;
+            }
+            for (const child of Object.values(v)) {
+                stack.push([child, d + 1]);
+            }
+        }
+    }
+    return max;
+}
+/** The fields of oceanum-python's `Query`. Anything else would make it warn. */
+const QUERY_FIELDS = [
+    'datasource',
+    'parameters',
+    'description',
+    'variables',
+    'timefilter',
+    'geofilter',
+    'levelfilter',
+    'coordfilter',
+    'crs',
+    'aggregate',
+    'functions',
+    'limit'
+];
+/** Fields that make a query select something rather than the whole datasource. */
+const FILTER_FIELDS = QUERY_FIELDS.filter(f => f !== 'datasource' && f !== 'description');
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** UTF-8 JSON to base64url, without padding. */
+export function encodePayload(request) {
+    const bytes = new TextEncoder().encode(JSON.stringify(request));
+    let binary = '';
+    for (const b of bytes) {
+        binary += String.fromCharCode(b);
+    }
+    return btoa(binary)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/**
+ * Read and validate a payload. Throws an `Error` whose message can be shown to the
+ * user; it never quotes the payload.
+ */
+export function decodePayload(encoded) {
+    if (encoded.length > MAX_ENCODED_LENGTH) {
+        throw new Error('The Datamesh link is too large to open.');
+    }
+    let parsed;
+    try {
+        const b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(b64);
+        const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch (_a) {
+        throw new Error('The Datamesh link is not valid.');
+    }
+    if (!isObject(parsed) || parsed.v !== PAYLOAD_VERSION) {
+        throw new Error('The Datamesh link is not valid, or comes from a newer Datamesh UI.');
+    }
+    const { name, items } = parsed;
+    // null is accepted wherever a string is optional: the UI copies datasource
+    // properties that may be null.
+    const optionalText = (value) => value === undefined || value === null || typeof value === 'string';
+    if (!optionalText(name)) {
+        throw new Error('The Datamesh link is not valid.');
+    }
+    if (!Array.isArray(items) || items.length === 0) {
+        throw new Error('The Datamesh link holds no queries.');
+    }
+    if (items.length > MAX_ITEMS) {
+        throw new Error(`The Datamesh link holds more than ${MAX_ITEMS} queries, which is too many to open.`);
+    }
+    if (depthOf(items) > MAX_DEPTH) {
+        throw new Error('The Datamesh link holds a query that is not valid.');
+    }
+    for (const item of items) {
+        if (!isObject(item) ||
+            typeof item.datasource !== 'string' ||
+            item.datasource.trim() === '' ||
+            !optionalText(item.label) ||
+            !optionalText(item.description)) {
+            throw new Error('The Datamesh link holds a query that is not valid.');
+        }
+    }
+    return {
+        v: PAYLOAD_VERSION,
+        ...(typeof name === 'string' ? { name } : {}),
+        items: items
+    };
+}
+const PAYLOAD_PREFIX = `${FRAGMENT_KEY}=`;
+/** The hash's `&`-separated parts, without the leading `#`. */
+function hashParts(hash) {
+    const body = hash.replace(/^#/, '');
+    return body === '' ? [] : body.split('&');
+}
+/**
+ * The payload in a location hash (`#oceanum-datamesh=...`), or null when the hash
+ * carries none. Other parts of the hash are ignored.
+ */
+export function payloadFromHash(hash) {
+    const part = hashParts(hash).find(p => p.startsWith(PAYLOAD_PREFIX));
+    return part === undefined ? null : part.slice(PAYLOAD_PREFIX.length);
+}
+/**
+ * The hash with the payload removed (`''` when nothing else is left). Every other
+ * part is kept exactly as it was.
+ */
+export function hashWithoutPayload(hash) {
+    const rest = hashParts(hash).filter(p => !p.startsWith(PAYLOAD_PREFIX));
+    return rest.length ? `#${rest.join('&')}` : '';
+}
+const INLINE_WIDTH = 72;
+/** Characters JSON leaves raw that Python's `splitlines()` still breaks on. */
+const RAW_BREAKS = new RegExp(`[\\x7f-\\x9f${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+/**
+ * A Python string literal. JSON's escaping is valid Python and escapes C0 controls;
+ * the C1 controls and U+2028/U+2029 it leaves raw are escaped too, so the generated
+ * source has no character a kernel could treat as a line break.
+ */
+export function pyString(text) {
+    return JSON.stringify(text).replace(RAW_BREAKS, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/** A Python literal for a scalar, or null for an array or object. */
+function pyScalar(value) {
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'True' : 'False';
+    }
+    if (typeof value === 'number') {
+        // Parsed JSON has no NaN or Infinity; guard anyway rather than emit bad code.
+        return Number.isFinite(value) ? JSON.stringify(value) : 'None';
+    }
+    if (typeof value === 'string') {
+        return pyString(value);
+    }
+    return Array.isArray(value) || isObject(value) ? null : 'None';
+}
+function definedEntries(value) {
+    return Object.entries(value).filter(([, v]) => v !== undefined);
+}
+/** A Python literal on one line, rendering each node once. */
+function pyInline(value) {
+    const scalar = pyScalar(value);
+    if (scalar !== null) {
+        return scalar;
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(pyInline).join(', ')}]`;
+    }
+    return `{${definedEntries(value)
+        .map(([k, v]) => `${pyString(k)}: ${pyInline(v)}`)
+        .join(', ')}}`;
+}
+/**
+ * A Python literal for a JSON value, wrapped over indented lines when it does not
+ * fit on one. Strings and keys go through `pyString`, so no value can end the
+ * literal early or break the line.
+ */
+export function pyLiteral(value, indent = 0) {
+    const scalar = pyScalar(value);
+    if (scalar !== null) {
+        return scalar;
+    }
+    const pad = ' '.repeat(indent + 4);
+    const end = ' '.repeat(indent);
+    const inline = pyInline(value);
+    if (Array.isArray(value)) {
+        if (inline.length + indent <= INLINE_WIDTH || value.length === 0) {
+            return inline;
+        }
+        const lines = value.map(v => pad + pyLiteral(v, indent + 4));
+        return `[\n${lines.join(',\n')},\n${end}]`;
+    }
+    if (isObject(value)) {
+        const entries = definedEntries(value);
+        if (inline.length + indent <= INLINE_WIDTH || entries.length === 0) {
+            return inline;
+        }
+        const lines = entries.map(([k, v]) => `${pad}${pyString(k)}: ${pyLiteral(v, indent + 4)}`);
+        return `{\n${lines.join(',\n')},\n${end}}`;
+    }
+    return 'None';
+}
+const PY_KEYWORDS = new Set([
+    'False',
+    'None',
+    'True',
+    'and',
+    'as',
+    'assert',
+    'async',
+    'await',
+    'break',
+    'class',
+    'continue',
+    'def',
+    'del',
+    'elif',
+    'else',
+    'except',
+    'finally',
+    'for',
+    'from',
+    'global',
+    'if',
+    'import',
+    'in',
+    'is',
+    'lambda',
+    'nonlocal',
+    'not',
+    'or',
+    'pass',
+    'raise',
+    'return',
+    'try',
+    'while',
+    'with',
+    'yield',
+    // Names the generated code itself uses.
+    'datamesh',
+    'Connector'
+]);
+/** A Python identifier for `text`, not in `taken`; adds it to `taken`. */
+export function pyIdentifier(text, taken) {
+    let base = text
+        .replace(/[^A-Za-z0-9_]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+    if (base === '') {
+        base = 'data';
+    }
+    if (/^[0-9]/.test(base)) {
+        base = `ds_${base}`;
+    }
+    if (PY_KEYWORDS.has(base)) {
+        base = `${base}_`;
+    }
+    let name = base;
+    for (let i = 2; taken.has(name); i++) {
+        name = `${base}_${i}`;
+    }
+    taken.add(name);
+    return name;
+}
+/**
+ * Every C0 and C1 control character, plus U+2028 and U+2029. This is a superset of
+ * what Python's `str.splitlines()` breaks on (LF, CR, VT, FF, FS, GS, RS, NEL and the
+ * two separators), which IPython's input transformer uses to split a cell into lines:
+ * left in a `#` comment, any of them would end the comment and run what follows.
+ */
+const LINE_BREAKS = new RegExp(`[\\x00-\\x1f\\x7f-\\x9f${String.fromCharCode(0x2028, 0x2029)}]+`, 'g');
+/** One line of text safe to put after a `#` comment marker. */
+function commentText(text) {
+    return text.replace(LINE_BREAKS, ' ').trim();
+}
+/**
+ * Text safe to put in a Markdown heading: no HTML, no Markdown syntax, and no
+ * autolink (`:`, `/` and `.` are escaped too). `&`, `<` and `>` become entities;
+ * every other ASCII punctuation character is backslash-escaped except `;` (part
+ * of the entities) and `@`: JupyterLab's math handling keeps `@@0@@` as a
+ * placeholder, and an escaped `\@\@0\@\@` slips past it and breaks rendering.
+ */
+function markdownText(text) {
+    return commentText(text)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/([!-%'-/:=?[-`{-~])/g, '\\$1');
+}
+/** The OceanQL query to send: only fields oceanum-python's `Query` accepts. */
+export function queryFields(item) {
+    const query = {};
+    for (const field of QUERY_FIELDS) {
+        if (item[field] !== undefined && item[field] !== null) {
+            query[field] = item[field];
+        }
+    }
+    return query;
+}
+/** Whether a query selects part of its datasource (else it loads the whole one). */
+function isFiltered(query) {
+    return FILTER_FIELDS.some(f => {
+        const v = query[f];
+        return !(Array.isArray(v) && v.length === 0) && v !== undefined;
+    });
+}
+/** The code cell that loads one query into a variable and shows it. */
+export function queryCellSource(item, variable) {
+    var _a, _b;
+    const query = queryFields(item);
+    const lines = [];
+    const title = commentText((_b = (_a = item.description) !== null && _a !== void 0 ? _a : item.label) !== null && _b !== void 0 ? _b : '');
+    if (title) {
+        lines.push(`# ${title}`);
+    }
+    if (isFiltered(query)) {
+        lines.push(`${variable} = datamesh.query(${pyLiteral(query)})`);
+    }
+    else {
+        // No filter: open the datasource lazily rather than download all of it.
+        lines.push(`${variable} = datamesh.load_datasource(${pyLiteral(item.datasource)})`);
+    }
+    lines.push(variable);
+    return lines.join('\n');
+}
+function codeCell(source) {
+    return {
+        cell_type: 'code',
+        execution_count: null,
+        metadata: {},
+        outputs: [],
+        source
+    };
+}
+/** The notebook name for a request: the workspace name, or the single query's. */
+export function notebookName(request) {
+    var _a, _b;
+    const only = request.items.length === 1 ? request.items[0] : null;
+    const name = ((_a = request.name) === null || _a === void 0 ? void 0 : _a.trim()) ||
+        ((_b = only === null || only === void 0 ? void 0 : only.label) === null || _b === void 0 ? void 0 : _b.trim()) ||
+        (only === null || only === void 0 ? void 0 : only.datasource.trim()) ||
+        'Datamesh workspace';
+    return commentText(name);
+}
+/**
+ * A new notebook that loads every query in `request`. It carries no `oceanum` link and
+ * no trust, so saving it creates a record of the user's own.
+ */
+export function notebookFromDatamesh(request) {
+    const taken = new Set();
+    const cells = [
+        {
+            cell_type: 'markdown',
+            metadata: {},
+            source: `# ${markdownText(notebookName(request))}\n\n` +
+                'Opened from the Oceanum Datamesh UI. Run the cells to load the data.'
+        },
+        codeCell('from oceanum.datamesh import Connector\n\ndatamesh = Connector()'),
+        ...request.items.map(item => codeCell(queryCellSource(item, pyIdentifier(item.label || item.datasource, taken))))
+    ];
+    return {
+        nbformat: 4,
+        nbformat_minor: 5,
+        // No kernelspec: the kernel is `python` in JupyterLite and `python3` in
+        // JupyterLab, and the language alone lets either pick its Python kernel.
+        metadata: { language_info: { name: 'python' } },
+        cells
+    };
+}

package/lib/share/notebook.d.ts

@@ -141,25 +141,19 @@ export declare function partitionSummaries(items: readonly ISpecSummary[], email
     mine: ISpecSummary[];
     shared: ISpecSummary[];
 };
-/** The `kind` of a Notebook Demo record's spec. */
-export declare const NOTEBOOK_DEMO_KIND = "notebook-demo";
-/** One example in a Notebook Demo record: a notebook record and how to list it. */
+/** The spec store type of the Notebook Demo specs, which are the Examples. */
+export declare 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;
 }
-/** A titled group of examples. */
-export interface INotebookDemoSection {
-    title: string;
-    items: INotebookDemoItem[];
-}
 /**
- * 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 declare function parseNotebookDemo(spec: unknown): INotebookDemoSection[];
+export declare function demoItemsFromSummaries(summaries: readonly ISpecSummary[]): INotebookDemoItem[];
 /** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
 export declare function parseTimestamp(value: string): Date | null;
 /**