Add strict notebook document edit api #105283
Description
Today, notebook document cells can be removed and added via the NotebookEditorCellEdit-api. The reason for having the edit-builder approach is that notebooks can change from the UX- and API-side and that it provides a consistent way to apply multiple edits for a given state. However, cell metadata, cell output, and document metadata can be changed directly via setters which conflicts with the approach outlined above. Modifying these properties should only be possible via an explicit edit API, direct modification shouldn't be possible.
In addition to this extended edit API we also need a way to modify a notebook without it showing in an editor. This will help with LS scenarios but will be generally useful. The same edit primitives are required outside of an notebook editor, maybe as part of the workspace edit API.
An extended/updated version of the edit-API looks so:
// edit with vscode.workspace.applyEdit(...)
export interface WorkspaceEdit {
replaceCells(uri: Uri, start: number, end: number, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void;
replaceCellOutput(uri: Uri, index: number, outputs: CellOutput[], metadata?: WorkspaceEditEntryMetadata): void;
replaceCellMetadata(uri: Uri, index: number, cellMetadata: NotebookCellMetadata, metadata?: WorkspaceEditEntryMetadata): void;
}
// edit with NotebookEditor
export interface NotebookEditorCellEdit {
replaceCells(start: number, end: number, cells: NotebookCellData[]): void;
replaceOutput(index: number, outputs: CellOutput[]): void;
replaceMetadata(index: number, metadata: NotebookCellMetadata): void;
}with an samples being
// via editor
const success = await vscode.notebook.activeNotebookEditor.edit(edit => {
edit.replaceOutputs(0, [{ outputKind: vscode.CellOutputKind.Rich, data: { 'text/markdown': '_Hello_' } }])
})
console.log(success);
// via workspace edit
const edit = new vscode.WorkspaceEdit();
edit.replaceCells(
someNotebookUri,
0, 0, [{ cellKind: vscode.CellKind.Markdown, language: 'markdown', outputs: [], source: '_Hello_', metadata: undefined }]
)
const success = await vscode.workspace.applyEdit(edit);
console.log(success);