Promote webview Api to stable (#47989)

* Promote webview Api to stable

Fixes #43713
Fixes #28263

* Rename position back to viewColumn and mark viewColumn as deprecated

This allows us to more easily re-introduce a `position` property once we have gridlayout

* Move dispose methods onto webview itself

Also better hide a few 'internal' methods / properties on the panel / webview

* Revert "Move dispose methods onto webview itself"

This reverts commit 8fab6cc.

* Move title onto webview panel

* Use _ names for private setters

* Remove unused emitter and dispose onMessageEmitter

* Preview internal emitters with _

extensions/markdown-language-features/src/features/preview.ts

@@ -236,7 +236,7 @@ export class MarkdownPreview {
 	}
 
 	public get position(): vscode.ViewColumn | undefined {
-		return this.editor.position;
+		return this.editor.viewColumn;
 	}
 
 	public isWebviewOf(webview: vscode.WebviewPanel): boolean {
@@ -269,7 +269,7 @@ export class MarkdownPreview {
 
 	public toggleLock() {
 		this._locked = !this._locked;
-		this.editor.webview.title = MarkdownPreview.getPreviewTitle(this._resource, this._locked);
+		this.editor.title = MarkdownPreview.getPreviewTitle(this._resource, this._locked);
 	}
 
 	private isPreviewOf(resource: vscode.Uri): boolean {
@@ -327,7 +327,7 @@ export class MarkdownPreview {
 		this.currentVersion = { resource, version: document.version };
 		const content = await this._contentProvider.provideTextDocumentContent(document, this._previewConfigurations, this.line);
 		if (this._resource === resource) {
-			this.editor.webview.title = MarkdownPreview.getPreviewTitle(this._resource, this._locked);
+			this.editor.title = MarkdownPreview.getPreviewTitle(this._resource, this._locked);
 			this.editor.webview.html = content;
 		}
 	}

src/vs/vscode.d.ts

@@ -4820,6 +4820,173 @@ declare module 'vscode' {
 		resolveTask(task: Task, token?: CancellationToken): ProviderResult<Task>;
 	}
 
+	/**
+	 * Content settings for a webview.
+	 */
+	export interface WebviewOptions {
+		/**
+		 * Should scripts be enabled in the webview content?
+		 *
+		 * Defaults to false (scripts-disabled).
+		 */
+		readonly enableScripts?: boolean;
+
+		/**
+		 * Should command uris be enabled in webview content?
+		 *
+		 * Defaults to false.
+		 */
+		readonly enableCommandUris?: boolean;
+
+		/**
+		 * Root paths from which the webview can load local (filesystem) resources using the `vscode-resource:` scheme.
+		 *
+		 * Default to the root folders of the current workspace plus the extension's install directory.
+		 *
+		 * Pass in an empty array to disallow access to any local resources.
+		 */
+		readonly localResourceRoots?: ReadonlyArray<Uri>;
+	}
+
+	/**
+	 * A webview displays html content, like an iframe.
+	 */
+	export interface Webview {
+		/**
+		 * Content settings for the webview.
+		 */
+		readonly options: WebviewOptions;
+
+		/**
+		 * Contents of the webview.
+		 *
+		 * Should be a complete html document.
+		 */
+		html: string;
+
+		/**
+		 * Fired when the webview content posts a message.
+		 */
+		readonly onDidReceiveMessage: Event<any>;
+
+		/**
+		 * Post a message to the webview content.
+		 *
+		 * Messages are only develivered if the webview is visible.
+		 *
+		 * @param message Body of the message.
+		 */
+		postMessage(message: any): Thenable<boolean>;
+	}
+
+	/**
+	 * Content settings for a webview panel.
+	 */
+	export interface WebviewPanelOptions {
+		/**
+		 * Should the find widget be enabled in the panel?
+		 *
+		 * Defaults to false.
+		 */
+		readonly enableFindWidget?: boolean;
+
+		/**
+		 * Should the webview panel's content (iframe) be kept around even when the panel
+		 * is no longer visible?
+		 *
+		 * Normally the webview panel's html context is created when the panel becomes visible
+		 * and destroyed when it is is hidden. Extensions that have complex state
+		 * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
+		 * context around, even when the webview moves to a background tab. When
+		 * the panel becomes visible again, the context is automatically restored
+		 * in the exact same state it was in originally.
+		 *
+		 * `retainContextWhenHidden` has a high memory overhead and should only be used if
+		 * your panel's context cannot be quickly saved and restored.
+		 */
+		readonly retainContextWhenHidden?: boolean;
+	}
+
+	/**
+	 * A panel that contains a webview.
+	 */
+	interface WebviewPanel {
+		/**
+		 * Type of the webview panel, such as `'markdown.preview'`.
+		 */
+		readonly viewType: string;
+
+		/**
+		 * Title of the panel shown in UI.
+		 */
+		title: string;
+
+		/**
+		 * Webview belonging to the panel.
+		 */
+		readonly webview: Webview;
+
+		/**
+		 * Content settings for the webview panel.
+		 */
+		readonly options: WebviewPanelOptions;
+
+		/**
+		 * Editor position of the panel. This property is only set if the webview is in
+		 * one of the three editor view columns.
+		 *
+		 * @deprecated
+		 */
+		readonly viewColumn?: ViewColumn;
+
+		/**
+		 * Is the panel currently visible?
+		 */
+		readonly visible: boolean;
+
+		/**
+		 * Fired when the panel's view state changes.
+		 */
+		readonly onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent>;
+
+		/**
+		 * Fired when the panel is disposed.
+		 *
+		 * This may be because the user closed the panel or because `.dispose()` was
+		 * called on it.
+		 *
+		 * Trying to use the panel after it has been disposed throws an exception.
+		 */
+		readonly onDidDispose: Event<void>;
+
+		/**
+		 * Show the webview panel in a given column.
+		 *
+		 * A webview panel may only show in a single column at a time. If it is already showing, this
+		 * method moves it to a new column.
+		 */
+		reveal(viewColumn: ViewColumn): void;
+
+		/**
+		 * Dispose of the webview panel.
+		 *
+		 * This closes the panel if it showing and disposes of the resources owned by the webview.
+		 * Webview panels are also disposed when the user closes the webview panel. Both cases
+		 * fire the `onDispose` event.
+		 */
+		dispose(): any;
+	}
+
+	/**
+	 * Event fired when a webview panel's view state changes.
+	 */
+	export interface WebviewPanelOnDidChangeViewStateEvent {
+		/**
+		 * Webview panel whose view state changed.
+		 */
+		readonly webviewPanel: WebviewPanel;
+	}
+
 	/**
 	 * Namespace describing the environment the editor runs in.
 	 */
@@ -5302,6 +5469,18 @@ declare module 'vscode' {
 		 */
 		export function createOutputChannel(name: string): OutputChannel;
 
+		/**
+		 * Create and show a new webview panel.
+		 *
+		 * @param viewType Identifies the type of the webview panel.
+		 * @param title Title of the panel.
+		 * @param position Editor column to show the new panel in.
+		 * @param options Settings for the new panel.
+		 *
+		 * @return New webview panel.
+		 */
+		export function createWebviewPanel(viewType: string, title: string, position: ViewColumn, options: WebviewPanelOptions & WebviewOptions): WebviewPanel;
+
 		/**
 		 * Set a message to the status bar. This is a short hand for the more powerful
 		 * status bar [items](#window.createStatusBarItem).