@observablehq/notebook-kit 1.0.0

package/dist/src/lib/notebook.d.ts

@@ -0,0 +1,35 @@
+export type NotebookTheme = "air" | "coffee" | "cotton" | "deep-space" | "glacier" | "ink" | "midnight" | "near-midnight" | "ocean-floor" | "parchment" | "slate" | "stark" | "sun-faded";
+export interface NotebookSpec {
+    /** the notebook’s cells, in top-to-bottom document order */
+    cells?: CellSpec[];
+    /** the notebook title, if any; extracted from the first h1 */
+    title?: string;
+    /** the notebook theme; defaults to "air" */
+    theme?: NotebookTheme;
+    /** if true, don’t allow editing */
+    readOnly?: boolean;
+}
+export interface Notebook extends NotebookSpec {
+    cells: Cell[];
+    title: NonNullable<NotebookSpec["title"]>;
+    theme: NonNullable<NotebookSpec["theme"]>;
+    readOnly: NonNullable<NotebookSpec["readOnly"]>;
+}
+export interface CellSpec {
+    /** the unique identifier for this cell */
+    id: number;
+    /** the committed cell value; defaults to empty */
+    value?: string;
+    /** the mode; affects how the value is evaluated; defaults to js */
+    mode?: "js" | "ojs" | "md" | "html" | "tex" | "dot" | "sql";
+    /** if true, the editor will stay open when not focused; defaults to false */
+    pinned?: boolean;
+}
+export interface Cell extends CellSpec {
+    value: NonNullable<CellSpec["value"]>;
+    mode: NonNullable<CellSpec["mode"]>;
+    pinned: NonNullable<CellSpec["pinned"]>;
+}
+export declare function toNotebook({ cells, title, theme, readOnly }: NotebookSpec): Notebook;
+export declare function toCell({ id, value, mode, pinned }: CellSpec): Cell;
+export declare function defaultPinned(mode: Cell["mode"]): boolean;

package/dist/src/lib/notebook.js

@@ -0,0 +1,19 @@
+export function toNotebook({ cells = [], title = "Untitled", theme = "air", readOnly = false }) {
+    return {
+        cells: cells.map(toCell),
+        title,
+        theme,
+        readOnly
+    };
+}
+export function toCell({ id, value = "", mode = "js", pinned = defaultPinned(mode) }) {
+    return {
+        id,
+        value,
+        mode,
+        pinned
+    };
+}
+export function defaultPinned(mode) {
+    return mode === "js" || mode === "ojs";
+}

package/dist/src/lib/notebook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/notebook.test.js

@@ -0,0 +1,26 @@
+import { assert, test } from "vitest";
+import { toCell, toNotebook } from "./notebook.js";
+test("converts a notebook spec to a notebook", () => {
+    assert.deepStrictEqual(toNotebook({}), {
+        title: "Untitled",
+        theme: "air",
+        cells: [],
+        readOnly: false
+    });
+});
+test("converts a cell spec to a cell", () => {
+    assert.deepStrictEqual(toCell({ id: 1 }), {
+        id: 1,
+        value: "",
+        mode: "js",
+        pinned: true
+    });
+});
+test("computes an appropriate default pinned based on the cell mode", () => {
+    assert.deepStrictEqual(toCell({ id: 1, mode: "md" }), {
+        id: 1,
+        value: "",
+        mode: "md",
+        pinned: false
+    });
+});

package/dist/src/lib/serialize.d.ts

@@ -0,0 +1,5 @@
+import type { Notebook } from "./notebook.js";
+export declare function serialize(notebook: Notebook): string;
+export declare function deserialize(data: string, { parser }?: {
+    parser?: DOMParser | undefined;
+}): Notebook;

package/dist/src/lib/serialize.js

@@ -0,0 +1,97 @@
+import { toNotebook } from "./notebook.js";
+import { isEmpty } from "./text.js";
+export function serialize(notebook) {
+    const _notebook = document.createElement("notebook");
+    _notebook.setAttribute("theme", notebook.theme);
+    if (notebook.readOnly)
+        _notebook.setAttribute("readonly", "");
+    _notebook.appendChild(document.createTextNode("\n  "));
+    const _title = document.createElement("title");
+    _title.textContent = notebook.title;
+    _notebook.appendChild(_title);
+    for (const cell of notebook.cells) {
+        _notebook.appendChild(document.createTextNode("\n  "));
+        const _cell = document.createElement("script");
+        _cell.id = String(cell.id);
+        _cell.type = serializeMode(cell.mode);
+        _cell.textContent = indent(cell.value.replace(/<(?=\\*\/script(\s|>))/gi, "<\\"));
+        if (cell.pinned)
+            _cell.setAttribute("pinned", "");
+        _notebook.appendChild(_cell);
+    }
+    _notebook.appendChild(document.createTextNode("\n"));
+    return `<!doctype html>\n${_notebook.outerHTML}\n`;
+}
+export function deserialize(data, { parser = new DOMParser() } = {}) {
+    const document = parser.parseFromString(data, "text/html");
+    const _notebook = document.querySelector("notebook");
+    const theme = deserializeTheme(_notebook?.getAttribute("theme"));
+    const readOnly = _notebook?.hasAttribute("readonly");
+    const title = document.querySelector("title")?.textContent ?? undefined;
+    let maxCellId = 0;
+    const cellIds = new Set();
+    const cells = Array.from(document.querySelectorAll("notebook script"), (cell) => {
+        let id = Math.floor(Number(cell.id));
+        if (!isFinite(id) || !(id > 0) || cellIds.has(id))
+            id = ++maxCellId;
+        else if (id > maxCellId)
+            maxCellId = id;
+        cellIds.add(id);
+        const pinned = cell.hasAttribute("pinned");
+        const value = dedent(cell.textContent?.replace(/<\\(?=\\*\/script(\s|>))/gi, "<") ?? "");
+        const mode = deserializeMode(cell.getAttribute("type"));
+        return { id, pinned, mode, value };
+    });
+    return toNotebook({ title, theme, readOnly, cells });
+}
+function serializeMode(mode) {
+    switch (mode) {
+        case "md":
+            return "text/markdown";
+        case "html":
+            return "text/html";
+        case "tex":
+            return "application/x-tex";
+        case "sql":
+            return "application/sql";
+        case "dot":
+            return "text/vnd.graphviz";
+        case "ojs":
+            return "application/vnd.observable.javascript";
+        default:
+            return "module";
+    }
+}
+function deserializeMode(mode) {
+    switch (mode) {
+        case "text/markdown":
+            return "md";
+        case "text/html":
+            return "html";
+        case "application/x-tex":
+            return "tex";
+        case "application/sql":
+            return "sql";
+        case "text/vnd.graphviz":
+            return "dot";
+        case "application/vnd.observable.javascript":
+            return "ojs";
+        default:
+            return "js";
+    }
+}
+function deserializeTheme(theme) {
+    return theme ?? "air";
+}
+function dedent(text) {
+    const lines = text.split(/\r\n?|\n/);
+    if (isEmpty(lines[lines.length - 1]))
+        lines.pop();
+    if (isEmpty(lines[0]))
+        lines.shift();
+    return lines.map((l) => l.replace(/^ {4}/, "")).join("\n");
+}
+function indent(text) {
+    const lines = text.split(/\r\n?|\n/);
+    return `\n${lines.map((l) => (l.trim() ? `    ${l}` : "")).join("\n")}\n  `;
+}

package/dist/src/lib/serialize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/serialize.test.js

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+import { assert, test } from "vitest";
+import { toNotebook } from "./notebook.js";
+import { deserialize, serialize } from "./serialize.js";
+test("serializes unpinned cells", () => {
+    const notebook1 = toNotebook({
+        cells: [
+            { id: 1, mode: "md", pinned: false, value: "# Hello, world!" },
+            { id: 2, pinned: false, value: "1 + 2" }
+        ]
+    });
+    const notebook2 = toNotebook({
+        cells: [
+            { id: 1, mode: "md", pinned: false, value: "# Hello, world!" },
+            { id: 2, mode: "js", pinned: false, value: "1 + 2" }
+        ]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});
+test("serializes pinned cells", () => {
+    const notebook1 = toNotebook({
+        cells: [
+            { id: 1, mode: "md", pinned: true, value: "# Hello, world!" },
+            { id: 2, pinned: true, value: "1 + 2" }
+        ]
+    });
+    const notebook2 = toNotebook({
+        cells: [
+            { id: 1, mode: "md", pinned: true, value: "# Hello, world!" },
+            { id: 2, mode: "js", pinned: true, value: "1 + 2" }
+        ]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});
+test("serializes notebook titles", () => {
+    const notebook1 = toNotebook({
+        title: "Hello, world!",
+        cells: [
+            { id: 1, mode: "md", pinned: false, value: "# Hello, world!" },
+            { id: 2, pinned: true, value: "1 + 2" }
+        ]
+    });
+    const notebook2 = toNotebook({
+        title: "Hello, world!",
+        cells: [
+            { id: 1, mode: "md", pinned: false, value: "# Hello, world!" },
+            { id: 2, mode: "js", pinned: true, value: "1 + 2" }
+        ]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});
+test("serialization preserves indentation", () => {
+    const notebook1 = toNotebook({
+        title: "Hello, world!",
+        cells: [{ id: 2, pinned: true, value: `{\n  1;\n  2;\n}` }]
+    });
+    const notebook2 = toNotebook({
+        title: "Hello, world!",
+        cells: [{ id: 2, mode: "js", pinned: true, value: `{\n  1;\n  2;\n}` }]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});
+test("serialization escapes </script>, in various forms", () => {
+    const notebook1 = toNotebook({
+        title: "Hello, world!",
+        cells: [
+            { id: 2, pinned: true, value: `'</script>'` },
+            { id: 3, pinned: true, value: `'</script '` },
+            { id: 4, pinned: true, value: `'</SCRIPT '` },
+            { id: 5, pinned: true, value: `'</sCrIpT '` },
+            { id: 6, pinned: true, value: `'<\\/script>'` },
+            { id: 7, pinned: true, value: `'<\\/script '` },
+            { id: 8, pinned: true, value: `'<\\\\/SCRIPT '` },
+            { id: 9, pinned: true, value: `'<\\\\/sCrIpT '` }
+        ]
+    });
+    const notebook2 = toNotebook({
+        title: "Hello, world!",
+        cells: [
+            { id: 2, mode: "js", pinned: true, value: `'</script>'` },
+            { id: 3, mode: "js", pinned: true, value: `'</script '` },
+            { id: 4, mode: "js", pinned: true, value: `'</SCRIPT '` },
+            { id: 5, mode: "js", pinned: true, value: `'</sCrIpT '` },
+            { id: 6, mode: "js", pinned: true, value: `'<\\/script>'` },
+            { id: 7, mode: "js", pinned: true, value: `'<\\/script '` },
+            { id: 8, mode: "js", pinned: true, value: `'<\\\\/SCRIPT '` },
+            { id: 9, mode: "js", pinned: true, value: `'<\\\\/sCrIpT '` },
+        ]
+    });
+    const html = serialize(notebook1);
+    assert.strictEqual(html.indexOf("'</script"), -1);
+    assert.deepStrictEqual(deserialize(html), notebook2);
+});
+test("serialization enforces unique ids", () => {
+    const notebook1 = toNotebook({
+        cells: [
+            { id: 2, value: "one" },
+            { id: 2, value: "two" }
+        ]
+    });
+    const notebook2 = toNotebook({
+        cells: [
+            { id: 2, value: "one" },
+            { id: 3, value: "two" }
+        ]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});
+test("deserialization populates missing ids", () => {
+    const notebook1 = toNotebook({
+        cells: [
+            { value: "one" }, // missing id
+            { id: 3, value: "three" },
+            { value: "four" } // missing id
+        ]
+    });
+    const notebook2 = toNotebook({
+        cells: [
+            { id: 1, value: "one" },
+            { id: 3, value: "three" },
+            { id: 4, value: "four" }
+        ]
+    });
+    assert.deepStrictEqual(deserialize(serialize(notebook1)), notebook2);
+});

package/dist/src/lib/text.d.ts

@@ -0,0 +1 @@
+export declare function isEmpty(text: string): boolean;

package/dist/src/lib/text.js

@@ -0,0 +1,3 @@
+export function isEmpty(text) {
+    return /^\s*$/.test(text);
+}

package/dist/src/runtime/define.d.ts

@@ -0,0 +1,28 @@
+import type { Variable, VariableDefinition } from "@observablehq/runtime";
+import type { DisplayState } from "./display.js";
+import { observe } from "./display.js";
+export type DefineState = DisplayState & {
+    /** the runtime variables associated with this cell */
+    variables: Variable[];
+};
+export type Definition = {
+    /** the unique cell id; a positive integer */
+    id: number;
+    /** the cell’s definition function */
+    body: VariableDefinition;
+    /** the names of this cell’s inputs (unbound references), if any */
+    inputs?: string[];
+    /** the names of this cell’s outputs (top-level declarations), if any */
+    outputs?: string[];
+    /** the singular output name of this cell, if any; an alternative to outputs */
+    output?: string;
+    /** whether to display this cell’s singular output automatically */
+    autodisplay?: boolean;
+    /** whether this cell’s singular output is a view */
+    autoview?: boolean;
+    /** whether this cell’s singular output is a mutable */
+    automutable?: boolean;
+    /** an asset mapping to apply to any autodisplayed assets (e.g., images and videos) */
+    assets?: Map<string, string>;
+};
+export declare function define(state: DefineState, definition: Definition, observer?: typeof observe): void;

package/dist/src/runtime/define.js

@@ -0,0 +1,62 @@
+import { clear, display, observe } from "./display.js";
+import { main } from "./index.js";
+import { input } from "./stdlib/generators/index.js";
+import { Mutator } from "./stdlib/mutable.js";
+export function define(state, definition, observer = observe) {
+    const { id, body, inputs = [], outputs = [], output, autodisplay, autoview, automutable } = definition;
+    const variables = state.variables;
+    const v = main.variable(observer(state, definition), { shadow: {} });
+    const vid = output ?? (outputs.length ? `cell ${id}` : null);
+    if (inputs.includes("display") || inputs.includes("view")) {
+        let displayVersion = -1; // the variable._version of currently-displayed values
+        const vd = new v.constructor(2, v._module);
+        vd.define(inputs.filter((i) => i !== "display" && i !== "view"), () => {
+            const version = v._version; // capture version on input change
+            return (value) => {
+                if (version < displayVersion)
+                    throw new Error("stale display");
+                else if (state.variables[0] !== v)
+                    throw new Error("stale display");
+                else if (version > displayVersion)
+                    clear(state);
+                displayVersion = version;
+                display(state, value);
+                return value;
+            };
+        });
+        v._shadow.set("display", vd);
+        if (inputs.includes("view")) {
+            const vv = new v.constructor(2, v._module, null, { shadow: {} });
+            vv._shadow.set("display", vd);
+            vv.define(["display"], (display) => (value) => input(display(value)));
+            v._shadow.set("view", vv);
+        }
+    }
+    else if (!autodisplay) {
+        clear(state);
+    }
+    variables.push(v.define(vid, inputs, body));
+    if (output != null) {
+        if (autoview) {
+            const o = unprefix(output, "viewof$");
+            variables.push(main.define(o, [output], input));
+        }
+        else if (automutable) {
+            const o = unprefix(output, "mutable ");
+            const x = `cell ${id}`;
+            v.define(o, [x], ([mutable]) => mutable); // observe live value
+            variables.push(main.define(output, inputs, body), // initial value
+            main.define(x, [output], Mutator), main.define(`mutable$${o}`, [x], ([, mutator]) => mutator));
+        }
+    }
+    else {
+        for (const o of outputs) {
+            variables.push(main.variable(true).define(o, [vid], (exports) => exports[o]));
+        }
+    }
+}
+function unprefix(name, prefix) {
+    if (!name.startsWith(prefix))
+        throw new Error(`expected ${prefix}: ${name}`);
+    return name.slice(prefix.length);
+}

package/dist/src/runtime/display.d.ts

@@ -0,0 +1,16 @@
+import type { Definition } from "./define.js";
+export type DisplayState = {
+    /** the HTML element in which to render this cell’s display */
+    root: HTMLDivElement;
+    /** for inspected values, any expanded paths; see getExpanded */
+    expanded: (number[][] | undefined)[];
+};
+export declare function display(state: DisplayState, value: unknown): void;
+export declare function clear(state: DisplayState): void;
+export declare function observe(state: DisplayState, { autodisplay, assets }: Definition): {
+    _error: boolean;
+    _node: HTMLDivElement;
+    pending(): void;
+    fulfilled(value: unknown): void;
+    rejected(error: unknown): void;
+};

package/dist/src/runtime/display.js

@@ -0,0 +1,60 @@
+import { inspect, inspectError, getExpanded } from "./inspect.js";
+import { mapAssets } from "./stdlib/assets.js";
+export function display(state, value) {
+    const { root, expanded } = state;
+    const node = isDisplayable(value, root) ? value : inspect(value, expanded[root.childNodes.length]); // prettier-ignore
+    displayNode(state, node);
+}
+function displayNode(state, node) {
+    if (node.nodeType === 11) {
+        let child;
+        while ((child = node.firstChild)) {
+            state.root.appendChild(child);
+        }
+    }
+    else {
+        state.root.appendChild(node);
+    }
+}
+function displayError(state, value) {
+    displayNode(state, inspectError(value));
+}
+// Note: Element.prototype is instanceof Node, but cannot be inserted! This
+// excludes DocumentFragment since appending a fragment “dissolves” (mutates)
+// the fragment, and we wish for the inspector to not have side-effects.
+function isDisplayable(value, root) {
+    return ((value instanceof Element || value instanceof Text) &&
+        value instanceof value.constructor &&
+        (!value.parentNode || root.contains(value)));
+}
+export function clear(state) {
+    state.expanded = Array.from(state.root.childNodes, getExpanded);
+    while (state.root.lastChild)
+        state.root.lastChild.remove();
+}
+export function observe(state, { autodisplay, assets }) {
+    return {
+        _error: false,
+        _node: state.root, // _node for visibility promise
+        pending() {
+            if (this._error) {
+                this._error = false;
+                clear(state);
+            }
+        },
+        fulfilled(value) {
+            if (autodisplay) {
+                clear(state);
+                if (assets && value instanceof Element)
+                    mapAssets(value, assets);
+                display(state, value);
+            }
+        },
+        rejected(error) {
+            console.error(error);
+            this._error = true;
+            clear(state);
+            displayError(state, error);
+        }
+    };
+}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,11 @@
+import type { Module } from "@observablehq/runtime";
+import { Runtime } from "@observablehq/runtime";
+import { fileAttachments } from "./stdlib/fileAttachment.js";
+export * from "./define.js";
+export * from "./display.js";
+export * from "./inspect.js";
+export * from "./stdlib/index.js";
+export declare const runtime: Runtime & {
+    fileAttachments: typeof fileAttachments;
+};
+export declare const main: Module;

package/dist/src/runtime/index.js

@@ -0,0 +1,14 @@
+import { Runtime } from "@observablehq/runtime";
+import { fileAttachments } from "./stdlib/fileAttachment.js";
+import { library } from "./stdlib/index.js";
+export * from "./define.js";
+export * from "./display.js";
+export * from "./inspect.js";
+export * from "./stdlib/index.js";
+export const runtime = Object.assign(new Runtime({ ...library, __ojs_runtime: () => runtime }), { fileAttachments });
+export const main = runtime.main = runtime.module();
+main.constructor.prototype.defines = function (name) {
+    return (this._scope.has(name) ||
+        this._builtins.has(name) ||
+        this._runtime._builtin._scope.has(name));
+};

package/dist/src/runtime/inspect.d.ts

@@ -0,0 +1,3 @@
+export declare function inspect(value: unknown, expanded?: number[][]): HTMLDivElement;
+export declare function inspectError(value: unknown): HTMLDivElement;
+export declare function getExpanded(node: Node): number[][] | undefined;

package/dist/src/runtime/inspect.js

@@ -0,0 +1,43 @@
+import { Inspector } from "@observablehq/inspector";
+export function inspect(value, expanded) {
+    const node = document.createElement("div");
+    new Inspector(node).fulfilled(value); // TODO name?
+    if (expanded) {
+        for (const path of expanded) {
+            let child = node;
+            for (const i of path)
+                child = child?.childNodes[i];
+            child?.dispatchEvent(new Event("mouseup")); // restore expanded state
+        }
+    }
+    return node;
+}
+export function inspectError(value) {
+    const node = document.createElement("div");
+    new Inspector(node).rejected(value);
+    return node;
+}
+export function getExpanded(node) {
+    if (!isInspector(node))
+        return;
+    const expanded = node.querySelectorAll(".observablehq--expanded");
+    if (expanded.length)
+        return Array.from(expanded, (e) => getNodePath(node, e));
+}
+function isElement(node) {
+    return node.nodeType === 1;
+}
+function isInspector(node) {
+    return isElement(node) && node.classList.contains("observablehq");
+}
+function getNodePath(node, descendant) {
+    const path = [];
+    while (descendant !== node) {
+        path.push(getChildIndex(descendant));
+        descendant = descendant.parentNode;
+    }
+    return path.reverse();
+}
+function getChildIndex(node) {
+    return Array.prototype.indexOf.call(node.parentNode.childNodes, node);
+}

package/dist/src/runtime/stdlib/assets.d.ts

@@ -0,0 +1,4 @@
+/** Populates the asset keys from the specified root.  */
+export declare function collectAssets(assets: Set<string>, root: Element): void;
+/** Mutates the specified root to apply the specified asset mapping. */
+export declare function mapAssets(root: Element, assets: Map<string, string>): void;