Add notebookWorkspaceEdit api proposal (#149128)

* Add notebookWorkspaceEdit api proposal

Splits a new `notebookWorkspaceEdit` out of the existing `notebookEditorEdit` proposal.

The notebookWorkspaceEdit reflects the api that we believe should be finalized instead of `notebookEditorEdit`. It lets extensions use workspaceedits to change cells in a notebook or replace the metadata for a notebook document

As part of this change, I've also marked all of the `notebookEditorEdit` apis as deprecated (except for `replaceNotebookMetadata` which exists in the new proposal too)

* Export type from extHost

src/vs/workbench/api/common/extHost.api.impl.ts

@@ -1321,6 +1321,7 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
 			NotebookCellOutputItem: extHostTypes.NotebookCellOutputItem,
 			NotebookCellStatusBarItem: extHostTypes.NotebookCellStatusBarItem,
 			NotebookControllerAffinity: extHostTypes.NotebookControllerAffinity,
+			NotebookEdit: extHostTypes.NotebookEdit,
 			PortAttributes: extHostTypes.PortAttributes,
 			LinkedEditingRanges: extHostTypes.LinkedEditingRanges,
 			TestResultState: extHostTypes.TestResultState,

src/vs/workbench/api/common/extHostTypes.ts

@@ -598,6 +598,43 @@ export class TextEdit {
 	}
 }
 
+@es5ClassCompat
+export class NotebookEdit implements vscode.NotebookEdit {
+
+	static isNotebookCellEdit(thing: any): thing is NotebookEdit {
+		if (thing instanceof NotebookEdit) {
+			return true;
+		}
+		if (!thing) {
+			return false;
+		}
+		return NotebookRange.isNotebookRange((<NotebookEdit>thing))
+			&& Array.isArray((<NotebookEdit>thing).newCells);
+	}
+
+	static replaceCells(range: NotebookRange, newCells: NotebookCellData[]): NotebookEdit {
+		return new NotebookEdit(range, newCells);
+	}
+
+	static deleteCells(range: NotebookRange): NotebookEdit {
+		return new NotebookEdit(range, []);
+	}
+
+	static updateCellMetadata(index: number, newMetadata: { [key: string]: any }): NotebookEdit {
+		return new NotebookEdit(new NotebookRange(index, index), [], newMetadata);
+	}
+
+	readonly range: NotebookRange;
+	readonly newCells: NotebookCellData[];
+	readonly newCellMetadata?: { [key: string]: any };
+
+	constructor(range: NotebookRange, newCells: NotebookCellData[], newCellMetadata?: { [key: string]: any }) {
+		this.range = range;
+		this.newCells = newCells;
+		this.newCellMetadata = newCellMetadata;
+	}
+}
+
 export class SnippetTextEdit implements vscode.SnippetTextEdit {
 
 	range: vscode.Range;
@@ -741,7 +778,7 @@ export class WorkspaceEdit implements vscode.WorkspaceEdit {
 		return this._edits.some(edit => edit._type === FileEditType.Text && edit.uri.toString() === uri.toString());
 	}
 
-	set(uri: URI, edits: TextEdit[]): void {
+	set(uri: URI, edits: TextEdit[] | unknown): void {
 		if (!edits) {
 			// remove all text edits for `uri`
 			for (let i = 0; i < this._edits.length; i++) {
@@ -753,9 +790,17 @@ export class WorkspaceEdit implements vscode.WorkspaceEdit {
 			coalesceInPlace(this._edits);
 		} else {
 			// append edit to the end
-			for (const edit of edits) {
+			for (const edit of edits as TextEdit[] | NotebookEdit[]) {
 				if (edit) {
-					this._edits.push({ _type: FileEditType.Text, uri, edit });
+					if (NotebookEdit.isNotebookCellEdit(edit)) {
+						if (edit.newCellMetadata) {
+							this.replaceNotebookCellMetadata(uri, edit.range.start, edit.newCellMetadata);
+						} else {
+							this.replaceNotebookCells(uri, edit.range, edit.newCells);
+						}
+					} else {
+						this._edits.push({ _type: FileEditType.Text, uri, edit });
+					}
 				}
 			}
 		}

src/vs/workbench/services/extensions/common/extensionsApiProposals.ts

@@ -42,6 +42,7 @@ export const allApiProposals = Object.freeze({
 	notebookMessaging: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.notebookMessaging.d.ts',
 	notebookMime: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.notebookMime.d.ts',
 	notebookProxyController: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.notebookProxyController.d.ts',
+	notebookWorkspaceEdit: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.notebookWorkspaceEdit.d.ts',
 	portsAttributes: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.portsAttributes.d.ts',
 	quickPickSortByLabel: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts',
 	resolvers: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.resolvers.d.ts',

src/vscode-dts/vscode.proposed.notebookEditorEdit.d.ts

@@ -7,32 +7,34 @@ declare module 'vscode' {
 
 	// https://github.com/microsoft/vscode/issues/106744
 
-	// todo@API add NotebookEdit-type which handles all these cases?
-	// export class NotebookEdit {
-	// 	range: NotebookRange;
-	// 	newCells: NotebookCellData[];
-	// 	newMetadata?: NotebookDocumentMetadata;
-	// 	constructor(range: NotebookRange, newCells: NotebookCellData)
-	// }
-
-	// export class NotebookCellEdit {
-	// 	newMetadata?: NotebookCellMetadata;
-	// }
-
-	// export interface WorkspaceEdit {
-	// 	set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void
-	// }
-
 	export interface WorkspaceEdit {
-		// todo@API add NotebookEdit-type which handles all these cases?
 		replaceNotebookMetadata(uri: Uri, value: { [key: string]: any }): void;
+
+		/**
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 */
 		replaceNotebookCells(uri: Uri, range: NotebookRange, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void;
+
+		/**
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 */
 		replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: { [key: string]: any }, metadata?: WorkspaceEditEntryMetadata): void;
 	}
 
 	export interface NotebookEditorEdit {
+		/**
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 */
 		replaceMetadata(value: { [key: string]: any }): void;
+
+		/**
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 */
 		replaceCells(start: number, end: number, cells: NotebookCellData[]): void;
+
+		/**
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 */
 		replaceCellMetadata(index: number, metadata: { [key: string]: any }): void;
 	}
 
@@ -44,10 +46,11 @@ declare module 'vscode' {
 		 * be used to make edits. Note that the edit-builder is only valid while the
 		 * callback executes.
 		 *
+		 * @deprecated Please migrate to the new `notebookWorkspaceEdit` proposed API.
+		 *
 		 * @param callback A function which can create edits using an {@link NotebookEditorEdit edit-builder}.
 		 * @return A promise that resolves with a value indicating if the edits could be applied.
 		 */
-		// @jrieken REMOVE maybe
 		edit(callback: (editBuilder: NotebookEditorEdit) => void): Thenable<boolean>;
 	}
 }

src/vscode-dts/vscode.proposed.notebookWorkspaceEdit.d.ts

@@ -0,0 +1,70 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+declare module 'vscode' {
+
+	// https://github.com/microsoft/vscode/issues/106744
+
+	/**
+	 * A notebook edit represents edits that should be applied to the contents of a notebook.
+	 */
+	export class NotebookEdit {
+
+		/**
+		 * Utility to create a edit that replaces cells in a notebook.
+		 *
+		 * @param range The range of cells to replace
+		 * @param newCells The new notebook cells.
+		 */
+		static replaceCells(range: NotebookRange, newCells: NotebookCellData[]): NotebookEdit;
+
+		/**
+		 * Utility to create a edit that deletes cells in a notebook.
+		 *
+		 * @param range The range of cells to delete.
+		 */
+		static deleteCells(range: NotebookRange): NotebookEdit;
+
+		/**
+		 * Utility to update a cells metadata.
+		 *
+		 * @param index The index of the cell to update.
+		 * @param newMetadata The new metadata for the cell.
+		 */
+		static updateCellMetadata(index: number, newMetadata: { [key: string]: any }): NotebookEdit;
+
+		/**
+		 * Range of the cells being edited
+		 */
+		readonly range: NotebookRange;
+
+		/**
+		 * New cells being inserted. May be empty.
+		 */
+		readonly newCells: NotebookCellData[];
+
+		/**
+		 * Optional new metadata for the cells.
+		 */
+		readonly newCellMetadata?: { [key: string]: any };
+
+		constructor(range: NotebookRange, newCells: NotebookCellData[], newCellMetadata?: { [key: string]: any });
+	}
+
+	export interface WorkspaceEdit {
+		/**
+		 * Replaces the metadata for a notebook document.
+		 */
+		replaceNotebookMetadata(uri: Uri, value: { [key: string]: any }): void;
+
+		/**
+		 * Set (and replace) edits for a resource.
+		 *
+		 * @param uri A resource identifier.
+		 * @param edits An array of text or notebook edits.
+		 */
+		set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void;
+	}
+}