📢 Notebook API announcements

[rebornix]

We introduced a proposed API for Notebook but currently the API is majorly two managed object: NotebookDocument and NotebookCell. We create them for extensions and listen to their properties changes. However this doesn't follow the principal of TextEditor/Document where TextDocument is always readonly and TextEditor is the API for applying changes to the document.

If we try to follow TextEditor/Document, the API can be shaped as below

export interface NotebookEditor {
    readonly document: NotebookDocument;
    viewColumn?: ViewColumn;
    /**
     * Fired when the output hosting webview posts a message.
     */
    readonly onDidReceiveMessage: Event<any>;
    /**
     * Post a message to the output hosting webview.
     *
     * Messages are only delivered if the editor is live.
     *
     * @param message Body of the message. This must be a string or other json serilizable object.
     */
    postMessage(message: any): Thenable<boolean>;

    /**
     * Create a notebook cell. The cell is not inserted into current document when created. Extensions should insert the cell into the document by [TextDocument.cells](#TextDocument.cells)
     */
    createCell(content: string, language: string, type: CellKind, outputs: CellOutput[], metadata: NotebookCellMetadata): NotebookCell;

    /**
     * Insert/Delete cells from the document
     */
    spliceCells(index: number, deleteCnt: number, insertedCells: NotebookCell[]): Promise<void>;

    /**
     * Make changes to individual cells
     */
    applyCellEdits(cell: NotebookCell, changes: { language?: string, outputs?: CellOutput[], metadata?: NotebookCellMetadata }): Promise<void>;
}

export interface NotebookDocument {
    readonly uri: Uri;
    readonly fileName: string;
    readonly isDirty: boolean;
    readonly languages: string[];
    readonly cells: NotebookCell[];
    readonly displayOrder?: GlobPattern[];
    readonly metadata?: NotebookDocumentMetadata;
}

export interface NotebookCell {
    readonly uri: Uri;
    readonly handle: number;
    readonly language: string;
    readonly cellKind: CellKind;
    readonly outputs: CellOutput[];
    readonly metadata?: NotebookCellMetadata;
    getContent(): string;
}

[roblourens]

Does the edit API need to support reordering? Like could there any transient state in webview cell outputs that would not be represented in CellOutput?

[roblourens]

If I set changes.metadata to something, am I overwriting all of metadata or merging in the properties that are set?

And I think metadata should be non-optional, even if all its properties are, it makes lots of things simpler.

[rebornix]

Does the edit API need to support reordering?

Extensions already use splice to do reordering since Cell are created through NotebookEditor.createCell so Cells are managed objects. We need to make sure they are not disposed during splice.

Like could there any transient state in webview cell outputs that would not be represented in CellOutput?

This should probably be done by output in the webview sending its state through webview api to extensions.

If I set changes.metadata to something, am I overwriting all of metadata or merging in the properties that are set?

It should be override IMHO.

And I think metadata should be non-optional, even if all its properties are, it makes lots of things simpler.

I agree making metadata non-optional is clear to both us (for implementation) and extensions author (maybe) but it will make cell-default-metadata on document impossible, unless we use inherit | enable | disable enum instead of boolean.

[jrieken]

We could make this even more similar to TextEditor#edit by also having an edit-callback which in the only place to create new cell, delete cell etc. Something like this

export interface NotebookEditorCellEdit {
	insert(content: string, language: string, type: CellKind, outputs: CellOutput[], metadata: NotebookCellMetadata | undefined): void;
	delete(cell: NotebookCell): void;
	// more
}

export interface NotebookEditor {
	readonly document: NotebookDocument;
	viewColumn?: ViewColumn;

	readonly onDidReceiveMessage: Event<any>;

	postMessage(message: any): Thenable<boolean>;

	editCells(callback: (cellEdit: NotebookEditorCellEdit) => any): any
}

[roblourens]

I agree making metadata non-optional is clear to both us (for implementation) and extensions author (maybe) but it will make cell-default-metadata on document impossible, unless we use inherit | enable | disable enum instead of boolean.

Right, I mean having metadata non-optional but its properties can be optional, where undefined means "inherit"

[rebornix]

Current state of the Notebook API: we added Document Edit API and make document.cells readonly. All changes to the cells should be performed through the Edit API

export interface NotebookEditorCellEdit {
    insert(index: number, content: string, language: string, type: CellKind, outputs: CellOutput[], metadata: NotebookCellMetadata | undefined): void;
    delete(index: number): void;
}

export interface NotebookEditor {
    readonly document: NotebookDocument;
    viewColumn?: ViewColumn;
    readonly onDidReceiveMessage: Event<any>;
    postMessage(message: any): Thenable<boolean>;
    edit(callback: (editBuilder: NotebookEditorCellEdit) => void): Thenable<boolean>;
}

The renderer API is also simplified as

export interface NotebookOutputRenderer {
    render(document: NotebookDocument, output: CellOutput, mimeType: string): string;
    preloads?: Uri[];
}

Note that we didn't pass NotebookEditor to renderers, instead they can only get the NotebookDocument. This is because The same document can be opened in two editors but the document is shared. My current thinking is custom renderers don't care about which editor the transformed output (html) will be rendered in and it also doesn't talk with the output through webview api because it doesn't know which editor the document will be loaded in.

[connor4312]

When implementing it the NotebookOutputRenderer felt a little awkward. The types indicated that I need check the output kind and check that rich output had data matching the mime type I care about... and throw an error if it's not right? Or return an empty string? Hard to know. It's also a little confusing to me because it seems like render will only be called for my own mime types, not CellStreamOutput/CellStreamInput. This was my boilerplate:

render(document: vscode.NotebookDocument, output: vscode.CellOutput): string {
  if (output.outputKind !== vscode.CellOutputKind.Rich) {
    return '';
  }

  if (output.data[Constants.TableMimeType] === undefined) {
    return '';
  }

  // actually do stuff...
}

Maybe the NotebookOutputRenderer's render function could be render(document: NotebookDocument, source: string, mimeType: string): CellOutput, where vscode would only call the renderer and pass in the source when the cell mime type matches. I also like the idea proposed of returning a CellOutputKind--gives me an easy way to deal with errors and higher-order renderers might be interesting.