Finalize NotebookEditor api proposal

Fixes microsoft#149271

This finalizes most parts of the NotebookEditor api proposal. I haven't removed the proposal entirely as there are still a few parts being left behind:

- The deprecated properties/functions
- A few contribution points such as `notebook/cell/executePrimary`

extensions/ipynb/package.json

@@ -9,7 +9,6 @@
 		"vscode": "^1.57.0"
 	},
 	"enabledApiProposals": [
-		"notebookEditor",
 		"notebookEditorEdit"
 	],
 	"activationEvents": [

extensions/ipynb/tsconfig.json

@@ -9,7 +9,6 @@
 	"include": [
 		"src/**/*",
 		"../../src/vscode-dts/vscode.d.ts",
-		"../../src/vscode-dts/vscode.proposed.notebookEditor.d.ts",
 		"../../src/vscode-dts/vscode.proposed.notebookEditorEdit.d.ts"
 	]
 }

extensions/notebook-renderers/tsconfig.json

@@ -9,7 +9,6 @@
 	"include": [
 		"src/**/*",
 		"../../src/vscode-dts/vscode.d.ts",
-		"../../src/vscode-dts/vscode.proposed.notebookEditor.d.ts",
 		"../../src/vscode-dts/vscode.proposed.notebookEditorEdit.d.ts",
 	]
 }

extensions/vscode-api-tests/package.json

@@ -24,7 +24,6 @@
     "notebookControllerKind",
     "notebookDebugOptions",
     "notebookDeprecated",
-    "notebookEditor",
     "notebookEditorDecorationType",
     "notebookEditorEdit",
     "notebookLiveShare",

extensions/vscode-notebook-tests/package.json

@@ -15,7 +15,6 @@
     "notebookControllerKind",
     "notebookDebugOptions",
     "notebookDeprecated",
-    "notebookEditor",
     "notebookEditorDecorationType",
     "notebookEditorEdit",
     "notebookLiveShare",

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

@@ -759,31 +759,28 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
 				return extHostWebviewViews.registerWebviewViewProvider(extension, viewId, provider, options?.webviewOptions);
 			},
 			get activeNotebookEditor(): vscode.NotebookEditor | undefined {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebook.activeNotebookEditor;
 			},
 			onDidChangeActiveNotebookEditor(listener, thisArgs?, disposables?) {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebook.onDidChangeActiveNotebookEditor(listener, thisArgs, disposables);
 			},
 			get visibleNotebookEditors() {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebook.visibleNotebookEditors;
 			},
 			get onDidChangeVisibleNotebookEditors() {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebook.onDidChangeVisibleNotebookEditors;
 			},
 			onDidChangeNotebookEditorSelection(listener, thisArgs?, disposables?) {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebookEditors.onDidChangeNotebookEditorSelection(listener, thisArgs, disposables);
 			},
 			onDidChangeNotebookEditorVisibleRanges(listener, thisArgs?, disposables?) {
-				checkProposedApiEnabled(extension, 'notebookEditor');
 				return extHostNotebookEditors.onDidChangeNotebookEditorVisibleRanges(listener, thisArgs, disposables);
 			},
 			showNotebookDocument(uriOrDocument, options?) {
-				checkProposedApiEnabled(extension, 'notebookEditor');
+				if (URI.isUri(uriOrDocument)) {
+					extHostApiDeprecation.report('window.showNotebookDocument(uri)', extension,
+						`Please use 'window.openNotebookDocument' and ''window.showTextDocument'`);
+				}
 				return extHostNotebook.showNotebookDocument(uriOrDocument, options);
 			},
 			registerExternalUriOpener(id: string, opener: vscode.ExternalUriOpener, metadata: vscode.ExternalUriOpenerMetadata) {

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

@@ -8,7 +8,6 @@ import { IExtensionDescription } from 'vs/platform/extensions/common/extensions'
 import { ExtHostNotebookRenderersShape, IMainContext, MainContext, MainThreadNotebookRenderersShape } from 'vs/workbench/api/common/extHost.protocol';
 import { ExtHostNotebookController } from 'vs/workbench/api/common/extHostNotebook';
 import { ExtHostNotebookEditor } from 'vs/workbench/api/common/extHostNotebookEditor';
-import { isProposedApiEnabled } from 'vs/workbench/services/extensions/common/extensions';
 import * as vscode from 'vscode';
 
 
@@ -30,29 +29,16 @@ export class ExtHostNotebookRenderers implements ExtHostNotebookRenderersShape {
 			throw new Error(`Extensions may only call createRendererMessaging() for renderers they contribute (got ${rendererId})`);
 		}
 
-		// In the stable API, the editor is given as an empty object, and this map
-		// is used to maintain references. This can be removed after editor finalization.
-		const notebookEditorVisible = isProposedApiEnabled(manifest, 'notebookEditor');
-		const notebookEditorAliases = new WeakMap<{}, vscode.NotebookEditor>();
-
 		const messaging: vscode.NotebookRendererMessaging = {
 			onDidReceiveMessage: (listener, thisArg, disposables) => {
-				const wrappedListener = notebookEditorVisible ? listener : (evt: { editor: vscode.NotebookEditor; message: any }) => {
-					const obj = {};
-					notebookEditorAliases.set(obj, evt.editor);
-					listener({ editor: obj as vscode.NotebookEditor, message: evt.message });
-				};
-
-				return this.getOrCreateEmitterFor(rendererId).event(wrappedListener, thisArg, disposables);
+				return this.getOrCreateEmitterFor(rendererId).event(listener, thisArg, disposables);
 			},
 			postMessage: (message, editorOrAlias) => {
 				if (ExtHostNotebookEditor.apiEditorsToExtHost.has(message)) { // back compat for swapped args
 					[message, editorOrAlias] = [editorOrAlias, message];
 				}
 
-
-				const editor = notebookEditorVisible ? editorOrAlias : notebookEditorAliases.get(editorOrAlias!);
-				const extHostEditor = editor && ExtHostNotebookEditor.apiEditorsToExtHost.get(editor);
+				const extHostEditor = editorOrAlias && ExtHostNotebookEditor.apiEditorsToExtHost.get(editorOrAlias);
 				return this.proxy.$postMessage(extHostEditor?.id, rendererId, message);
 			},
 		};

src/vscode-dts/vscode.d.ts

@@ -777,6 +777,67 @@ declare module 'vscode' {
 		selection?: Range;
 	}
 
+	/**
+	 * Represents an event describing the change in a {@link NotebookEditor.selections notebook editor's selections}.
+	 */
+	export interface NotebookEditorSelectionChangeEvent {
+		/**
+		 * The {@link NotebookEditor notebook editor} for which the selections have changed.
+		 */
+		readonly notebookEditor: NotebookEditor;
+
+		/**
+		 * The new value for the {@link NotebookEditor.selections notebook editor's selections}.
+		 */
+		readonly selections: readonly NotebookRange[];
+	}
+
+	/**
+	 * Represents an event describing the change in a {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}.
+	 */
+	export interface NotebookEditorVisibleRangesChangeEvent {
+		/**
+		 * The {@link NotebookEditor notebook editor} for which the visible ranges have changed.
+		 */
+		readonly notebookEditor: NotebookEditor;
+
+		/**
+		 * The new value for the {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}.
+		 */
+		readonly visibleRanges: readonly NotebookRange[];
+	}
+
+	/**
+	 * Represents options to configure the behavior of showing a {@link NotebookDocument notebook document} in an {@link NotebookEditor notebook editor}.
+	 */
+	export interface NotebookDocumentShowOptions {
+		/**
+		 * An optional view column in which the {@link NotebookEditor notebook editor} should be shown.
+		 * The default is the {@link ViewColumn.Active active}, other values are adjusted to
+		 * be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is
+		 * not adjusted. Use {@linkcode ViewColumn.Beside} to open the
+		 * editor to the side of the currently active one.
+		 */
+		readonly viewColumn?: ViewColumn;
+
+		/**
+		 * An optional flag that when `true` will stop the {@link NotebookEditor notebook editor} from taking focus.
+		 */
+		readonly preserveFocus?: boolean;
+
+		/**
+		 * An optional flag that controls if an {@link NotebookEditor notebook editor}-tab shows as preview. Preview tabs will
+		 * be replaced and reused until set to stay - either explicitly or through editing. The default behaviour depends
+		 * on the `workbench.editor.enablePreview`-setting.
+		 */
+		readonly preview?: boolean;
+
+		/**
+		 * An optional selection to apply for the document in the {@link NotebookEditor notebook editor}.
+		 */
+		readonly selections?: readonly NotebookRange[];
+	}
+
 	/**
 	 * A reference to one of the workbench colors as defined in https://code.visualstudio.com/docs/getstarted/theme-color-reference.
 	 * Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.
@@ -9121,6 +9182,43 @@ declare module 'vscode' {
 		 */
 		export const onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>;
 
+		/**
+		 * The currently visible {@link NotebookEditor notebook editors} or an empty array.
+		 */
+		export const visibleNotebookEditors: readonly NotebookEditor[];
+
+		/**
+		 * An {@link Event} which fires when the {@link window.visibleNotebookEditors visible notebook editors}
+		 * has changed.
+		 */
+		export const onDidChangeVisibleNotebookEditors: Event<readonly NotebookEditor[]>;
+
+		/**
+		 * The currently active {@link NotebookEditor notebook editor} or `undefined`. The active editor is the one
+		 * that currently has focus or, when none has focus, the one that has changed
+		 * input most recently.
+		 */
+		export const activeNotebookEditor: NotebookEditor | undefined;
+
+		/**
+		 * An {@link Event} which fires when the {@link window.activeNotebookEditor active notebook editor}
+		 * has changed. *Note* that the event also fires when the active editor changes
+		 * to `undefined`.
+		 */
+		export const onDidChangeActiveNotebookEditor: Event<NotebookEditor | undefined>;
+
+		/**
+		 * An {@link Event} which fires when the {@link NotebookEditor.selections notebook editor selections}
+		 * have changed.
+		 */
+		export const onDidChangeNotebookEditorSelection: Event<NotebookEditorSelectionChangeEvent>;
+
+		/**
+		 * An {@link Event} which fires when the {@link NotebookEditor.visibleRanges notebook editor visible ranges}
+		 * have changed.
+		 */
+		export const onDidChangeNotebookEditorVisibleRanges: Event<NotebookEditorVisibleRangesChangeEvent>;
+
 		/**
 		 * The currently opened terminals or an empty array.
 		 */
@@ -9200,6 +9298,16 @@ declare module 'vscode' {
 		 */
 		export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor>;
 
+		/**
+		 * Show the given {@link NotebookDocument} in a {@link NotebookEditor notebook editor}.
+		 *
+		 * @param document A text document to be shown.
+		 * @param options {@link NotebookDocumentShowOptions Editor options} to configure the behavior of showing the {@link NotebookEditor notebook editor}.
+		 *
+		 * @return A promise that resolves to an {@link NotebookEditor notebook editor}.
+		 */
+		export function showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable<NotebookEditor>;
+
 		/**
 		 * Create a TextEditorDecorationType that can be used to add decorations to text editors.
 		 *
@@ -12482,13 +12590,73 @@ declare module 'vscode' {
 
 	}
 
+	/**
+	 * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}.
+	 */
+	export enum NotebookEditorRevealType {
+		/**
+		 * The range will be revealed with as little scrolling as possible.
+		 */
+		Default = 0,
+
+		/**
+		 * The range will always be revealed in the center of the viewport.
+		 */
+		InCenter = 1,
+
+		/**
+		 * If the range is outside the viewport, it will be revealed in the center of the viewport.
+		 * Otherwise, it will be revealed with as little scrolling as possible.
+		 */
+		InCenterIfOutsideViewport = 2,
+
+		/**
+		 * The range will always be revealed at the top of the viewport.
+		 */
+		AtTop = 3
+	}
+
 	/**
 	 * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}.
 	 * Additional properties of the NotebookEditor are available in the proposed
 	 * API, which will be finalized later.
 	 */
 	export interface NotebookEditor {
 
+		/**
+		 * The {@link NotebookDocument notebook document} associated with this notebook editor.
+		 */
+		readonly notebook: NotebookDocument;
+
+		/**
+		 * The primary selection in this notebook editor.
+		 */
+		selection: NotebookRange;
+
+		/**
+		 * All selections in this notebook editor.
+		 *
+		 * The primary selection (or focused range) is `selections[0]`. When the document has no cells, the primary selection is empty `{ start: 0, end: 0 }`;
+		 */
+		selections: readonly NotebookRange[];
+
+		/**
+		 * The current visible ranges in the editor (vertically).
+		 */
+		readonly visibleRanges: readonly NotebookRange[];
+
+		/**
+		 * The column in which this editor shows.
+		 */
+		readonly viewColumn?: ViewColumn;
+
+		/**
+		 * Scroll as indicated by `revealType` in order to reveal the given range.
+		 *
+		 * @param range A range.
+		 * @param revealType The scrolling strategy for revealing `range`.
+		 */
+		revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void;
 	}
 
 	/**