@theia/plugin 1.59.0-next.72 → 1.60.0-next.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.59.0-next.72+f41d8efcd",
+  "version": "1.60.0-next.43+2a13720d2",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.58.0"
+    "@theia/ext-scripts": "1.59.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "f41d8efcd4abb79167b74bf476eafc7857e97306"
+  "gitHead": "2a13720d2d41d8ae6ee4e34cd2dee1c656a18018"
 }

package/src/theia.d.ts

@@ -27,7 +27,6 @@ import './theia.proposed.createFileSystemWatcher';
 import './theia.proposed.customEditorMove';
 import './theia.proposed.debugVisualization';
 import './theia.proposed.diffCommand';
-import './theia.proposed.documentPaste';
 import './theia.proposed.editSessionIdentityProvider';
 import './theia.proposed.extensionsAny';
 import './theia.proposed.externalUriOpener';
@@ -358,19 +357,21 @@ export module '@theia/plugin' {
     export class Selection extends Range {
 
         /**
-         * Position where selection starts.
+         * The position at which the selection starts.
+         * This position might be before or after {@link Selection.active active}.
          */
-        anchor: Position;
+        readonly anchor: Position;
 
         /**
-         * Position of the cursor
+         * The position of the cursor.
+         * This position might be before or after {@link Selection.anchor anchor}.
          */
-        active: Position;
+        readonly active: Position;
 
         /**
-         * A selection is reversed if `active.isBefore(anchor)`
+         * A selection is reversed if its {@link Selection.anchor anchor} is the {@link Selection.end end} position.
          */
-        isReversed: boolean;
+        readonly isReversed: boolean;
 
         /**
          * Create a selection from two positions.
@@ -3436,10 +3437,17 @@ export module '@theia/plugin' {
         /**
          * The exit code reported by the shell.
          *
-         * Note that `undefined` means the shell either did not report an exit  code (ie. the shell
-         * integration script is misbehaving) or the shell reported a command started before the command
-         * finished (eg. a sub-shell was opened). Generally this should not happen, depending on the use
-         * case, it may be best to treat this as a failure.
+         * When this is `undefined` it can mean several things:
+         *
+         * - The shell either did not report an exit  code (ie. the shell integration script is
+         *   misbehaving)
+         * - The shell reported a command started before the command finished (eg. a sub-shell was
+         *   opened).
+         * - The user canceled the command via ctrl+c.
+         * - The user pressed enter when there was no input.
+         *
+         * Generally this should not happen. Depending on the use case, it may be best to treat this
+         * as a failure.
          *
          * @example
          * const execution = shellIntegration.executeCommand({
@@ -3449,15 +3457,14 @@ export module '@theia/plugin' {
          * window.onDidEndTerminalShellExecution(event => {
          *   if (event.execution === execution) {
          *     if (event.exitCode === undefined) {
-         *      console.log('Command finished but exit code is unknown');
+         *       console.log('Command finished but exit code is unknown');
          *     } else if (event.exitCode === 0) {
-         *      console.log('Command succeeded');
+         *       console.log('Command succeeded');
          *     } else {
-         *      console.log('Command failed');
+         *       console.log('Command failed');
          *     }
          *   }
          * });
-         * @stubbed
          */
         readonly exitCode: number | undefined;
     }
@@ -11375,12 +11382,44 @@ export module '@theia/plugin' {
         /**
          * Registers a new {@link DocumentDropEditProvider}.
          *
+         * Multiple drop providers can be registered for a language. When dropping content into an editor, all
+         * registered providers for the editor's language will be invoked based on the mimetypes they handle
+         * as specified by their {@linkcode DocumentDropEditProviderMetadata}.
+         *
+         * Each provider can return one or more {@linkcode DocumentDropEdit DocumentDropEdits}. The edits are sorted
+         * using the {@linkcode DocumentDropEdit.yieldTo} property. By default the first edit will be applied. If there
+         * are any additional edits, these will be shown to the user as selectable drop options in the drop widget.
+         *
          * @param selector A selector that defines the documents this provider applies to.
          * @param provider A drop provider.
+         * @param metadata Additional metadata about the provider.
+         *
+         * @returns A {@linkcode Disposable} that unregisters this provider when disposed of.
+         */
+        export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider, metadata?: DocumentDropEditProviderMetadata): Disposable;
+
+        /**
+         * Registers a new {@linkcode DocumentPasteEditProvider}.
+         *
+         * Multiple providers can be registered for a language. All registered providers for a language will be invoked
+         * for copy and paste operations based on their handled mimetypes as specified by the {@linkcode DocumentPasteProviderMetadata}.
+         *
+         * For {@link DocumentPasteEditProvider.prepareDocumentPaste copy operations}, changes to the {@linkcode DataTransfer}
+         * made by each provider will be merged into a single {@linkcode DataTransfer} that is used to populate the clipboard.
+         *
+         * For {@link DocumentPasteEditProvider.providerDocumentPasteEdits paste operations}, each provider will be invoked
+         * and can return one or more {@linkcode DocumentPasteEdit DocumentPasteEdits}. The edits are sorted using
+         * the {@linkcode DocumentPasteEdit.yieldTo} property. By default the first edit will be applied
+         * and the rest of the edits will be shown to the user as selectable paste options in the paste widget.
          *
-         * @return A {@link Disposable} that unregisters this provider when disposed of.
+         * @param selector A selector that defines the documents this provider applies to.
+         * @param provider A paste editor provider.
+         * @param metadata Additional metadata about the provider.
+         *
+         * @returns A {@linkcode Disposable} that unregisters this provider when disposed of.
+         * @stubbed
          */
-        export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider): Disposable;
+        export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable;
 
         /**
          * Register a declaration provider.
@@ -13186,7 +13225,7 @@ export module '@theia/plugin' {
         /**
          * The shell command line. Is `undefined` if created with a command and arguments.
          */
-        commandLine?: string;
+        commandLine: string | undefined;
 
         /**
          * The shell options used when the command line is executed in a shell.
@@ -13197,12 +13236,12 @@ export module '@theia/plugin' {
         /**
          * The shell command. Is `undefined` if created with a full command line.
          */
-        command?: string | ShellQuotedString;
+        command: string | ShellQuotedString | undefined;
 
         /**
          * The shell args. Is `undefined` if created with a full command line.
          */
-        args?: (string | ShellQuotedString)[];
+        args: Array<string | ShellQuotedString> | undefined;
     }
 
     export interface ProcessExecutionOptions {
@@ -13744,9 +13783,10 @@ export module '@theia/plugin' {
 
         /**
          * The range the comment thread is located within the document. The thread icon will be shown
-         * at the first line of the range.
+         * at the last line of the range. When set to undefined, the comment will be associated with the
+         * file, and not a specific range.
          */
-        range: Range;
+        range: Range | undefined;
 
         /**
          * The ordered comments of the thread.
@@ -13921,6 +13961,21 @@ export module '@theia/plugin' {
         text: string;
     }
 
+    /**
+     * The ranges a CommentingRangeProvider enables commenting on.
+     */
+    export interface CommentingRanges {
+        /**
+         * Enables comments to be added to a file without a specific range.
+         */
+        enableFileComments: boolean;
+
+        /**
+         * The ranges which allow new comment threads creation.
+         */
+        ranges?: Range[];
+    }
+
     /**
      * Commenting range provider for a {@link CommentController comment controller}.
      */
@@ -13928,7 +13983,7 @@ export module '@theia/plugin' {
         /**
          * Provide a list of ranges which allow new comment threads creation or null for a given document
          */
-        provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[]>;
+        provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[] | CommentingRanges>;
     }
 
     /**
@@ -14343,10 +14398,88 @@ export module '@theia/plugin' {
         provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<LinkedEditingRanges>;
     }
 
+    /**
+     * Identifies a {@linkcode DocumentDropEdit} or {@linkcode DocumentPasteEdit}
+     */
+    export class DocumentDropOrPasteEditKind {
+        static readonly Empty: DocumentDropOrPasteEditKind;
+
+        /**
+         * The root kind for basic text edits.
+         *
+         * This kind should be used for edits that insert basic text into the document. A good example of this is
+         * an edit that pastes the clipboard text while also updating imports in the file based on the pasted text.
+         * For this we could use a kind such as `text.updateImports.someLanguageId`.
+         *
+         * Even though most drop/paste edits ultimately insert text, you should not use {@linkcode Text} as the base kind
+         * for every edit as this is redundant. Instead a more specific kind that describes the type of content being
+         * inserted should be used instead. For example, if the edit adds a Markdown link, use `markdown.link` since even
+         * though the content being inserted is text, it's more important to know that the edit inserts Markdown syntax.
+         */
+        static readonly Text: DocumentDropOrPasteEditKind;
+
+        /**
+         * Root kind for edits that update imports in a document in addition to inserting text.
+         */
+        static readonly TextUpdateImports: DocumentDropOrPasteEditKind;
+
+        /**
+         * Use {@linkcode DocumentDropOrPasteEditKind.Empty} instead.
+         */
+        private constructor(value: string);
+
+        /**
+         * The raw string value of the kind.
+         */
+        readonly value: string;
+
+        /**
+         * Create a new kind by appending additional scopes to the current kind.
+         *
+         * Does not modify the current kind.
+         */
+        append(...parts: string[]): DocumentDropOrPasteEditKind;
+
+        /**
+         * Checks if this kind intersects `other`.
+         *
+         * The kind `"text.plain"` for example intersects `text`, `"text.plain"` and `"text.plain.list"`,
+         * but not `"unicorn"`, or `"textUnicorn.plain"`.
+         *
+         * @param other Kind to check.
+         */
+        intersects(other: DocumentDropOrPasteEditKind): boolean;
+
+        /**
+         * Checks if `other` is a sub-kind of this `DocumentDropOrPasteEditKind`.
+         *
+         * The kind `"text.plain"` for example contains `"text.plain"` and `"text.plain.list"`,
+         * but not `"text"` or `"unicorn.text.plain"`.
+         *
+         * @param other Kind to check.
+         */
+        contains(other: DocumentDropOrPasteEditKind): boolean;
+    }
+
     /**
      * An edit operation applied {@link DocumentDropEditProvider on drop}.
      */
     export class DocumentDropEdit {
+        /**
+         * Human readable label that describes the edit.
+         */
+        title?: string;
+
+        /**
+         * {@link DocumentDropOrPasteEditKind Kind} of the edit.
+         */
+        kind?: DocumentDropOrPasteEditKind;
+
+        /**
+         * Controls the ordering or multiple edits. If this provider yield to edits, it will be shown lower in the list.
+         */
+        yieldTo?: readonly DocumentDropOrPasteEditKind[];
+
         /**
          * The text or snippet to insert at the drop location.
          */
@@ -14359,8 +14492,10 @@ export module '@theia/plugin' {
 
         /**
          * @param insertText The text or snippet to insert at the drop location.
+         * @param title Human readable label that describes the edit.
+         * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit.
          */
-        constructor(insertText: string | SnippetString);
+        constructor(insertText: string | SnippetString, title?: string, kind?: DocumentDropOrPasteEditKind);
     }
 
     /**
@@ -14370,7 +14505,7 @@ export module '@theia/plugin' {
      * and dropping files, users can hold down `shift` to drop the file into the editor instead of opening it.
      * Requires `editor.dropIntoEditor.enabled` to be on.
      */
-    export interface DocumentDropEditProvider {
+    export interface DocumentDropEditProvider<T extends DocumentDropEdit = DocumentDropEdit> {
         /**
          * Provide edits which inserts the content being dragged and dropped into the document.
          *
@@ -14379,12 +14514,223 @@ export module '@theia/plugin' {
          * @param dataTransfer A {@link DataTransfer} object that holds data about what is being dragged and dropped.
          * @param token A cancellation token.
          *
-         * @return A {@link DocumentDropEdit} or a thenable that resolves to such. The lack of a result can be
+         * @returns A {@link DocumentDropEdit} or a thenable that resolves to such. The lack of a result can be
          * signaled by returning `undefined` or `null`.
          */
-        provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<DocumentDropEdit>;
+        provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<T | T[]>;
+
+        /**
+         * Optional method which fills in the {@linkcode DocumentDropEdit.additionalEdit} before the edit is applied.
+         *
+         * This is called once per edit and should be used if generating the complete edit may take a long time.
+         * Resolve can only be used to change {@link DocumentDropEdit.additionalEdit}.
+         *
+         * @param edit The {@linkcode DocumentDropEdit} to resolve.
+         * @param token A cancellation token.
+         *
+         * @returns The resolved edit or a thenable that resolves to such. It is OK to return the given
+         * `edit`. If no result is returned, the given `edit` is used.
+         * @stubbed
+         */
+        resolveDocumentDropEdit?(edit: T, token: CancellationToken): ProviderResult<T>;
+    }
+
+    /**
+     * Provides additional metadata about how a {@linkcode DocumentDropEditProvider} works.
+     */
+    export interface DocumentDropEditProviderMetadata {
+        /**
+         * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentDropEditProvider.provideDocumentDropEdits provideDocumentDropEdits}.
+         *
+         * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested.
+         */
+        readonly providedDropEditKinds?: readonly DocumentDropOrPasteEditKind[];
+
+        /**
+         * List of {@link DataTransfer} mime types that the provider can handle.
+         *
+         * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`.
+         *
+         * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench.
+         *
+         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@link DataTransfer}.
+         * Note that {@link DataTransferFile} entries are only created when dropping content from outside the editor, such as
+         * from the operating system.
+         */
+        readonly dropMimeTypes: readonly string[];
     }
 
+    /**
+     * The reason why paste edits were requested.
+     */
+    export enum DocumentPasteTriggerKind {
+        /**
+         * Pasting was requested as part of a normal paste operation.
+         */
+        Automatic = 0,
+
+        /**
+         * Pasting was requested by the user with the `paste as` command.
+         */
+        PasteAs = 1,
+    }
+
+    /**
+     * Additional information about the paste operation.
+     */
+    export interface DocumentPasteEditContext {
+
+        /**
+         * Requested kind of paste edits to return.
+         *
+         * When a explicit kind if requested by {@linkcode DocumentPasteTriggerKind.PasteAs PasteAs}, providers are
+         * encourage to be more flexible when generating an edit of the requested kind.
+         */
+        readonly only: DocumentDropOrPasteEditKind | undefined;
+
+        /**
+         * The reason why paste edits were requested.
+         */
+        readonly triggerKind: DocumentPasteTriggerKind;
+    }
+
+    /**
+     * Provider invoked when the user copies or pastes in a {@linkcode TextDocument}.
+     */
+    export interface DocumentPasteEditProvider<T extends DocumentPasteEdit = DocumentPasteEdit> {
+
+        /**
+         * Optional method invoked after the user copies from a {@link TextEditor text editor}.
+         *
+         * This allows the provider to attach metadata about the copied text to the {@link DataTransfer}. This data
+         * transfer is then passed back to providers in {@linkcode provideDocumentPasteEdits}.
+         *
+         * Note that currently any changes to the {@linkcode DataTransfer} are isolated to the current editor window.
+         * This means that any added metadata cannot be seen by other editor windows or by other applications.
+         *
+         * @param document Text document where the copy took place.
+         * @param ranges Ranges being copied in {@linkcode document}.
+         * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for
+         * later use in {@linkcode provideDocumentPasteEdits}. This object is only valid for the duration of this method.
+         * @param token A cancellation token.
+         *
+         * @return Optional thenable that resolves when all changes to the `dataTransfer` are complete.
+         */
+        prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>;
+
+        /**
+         * Invoked before the user pastes into a {@link TextEditor text editor}.
+         *
+         * Returned edits can replace the standard pasting behavior.
+         *
+         * @param document Document being pasted into
+         * @param ranges Range in the {@linkcode document} to paste into.
+         * @param dataTransfer The {@link DataTransfer data transfer} associated with the paste. This object is only
+         * valid for the duration of the paste operation.
+         * @param context Additional context for the paste.
+         * @param token A cancellation token.
+         *
+         * @return Set of potential {@link DocumentPasteEdit edits} that can apply the paste. Only a single returned
+         * {@linkcode DocumentPasteEdit} is applied at a time. If multiple edits are returned from all providers, then
+         * the first is automatically applied and a widget is shown that lets the user switch to the other edits.
+         */
+        provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext, token: CancellationToken): ProviderResult<T[]>;
+
+        /**
+         * Optional method which fills in the {@linkcode DocumentPasteEdit.additionalEdit} before the edit is applied.
+         *
+         * This is called once per edit and should be used if generating the complete edit may take a long time.
+         * Resolve can only be used to change {@linkcode DocumentPasteEdit.insertText} or {@linkcode DocumentPasteEdit.additionalEdit}.
+         *
+         * @param pasteEdit The {@linkcode DocumentPasteEdit} to resolve.
+         * @param token A cancellation token.
+         *
+         * @returns The resolved paste edit or a thenable that resolves to such. It is OK to return the given
+         * `pasteEdit`. If no result is returned, the given `pasteEdit` is used.
+         */
+        resolveDocumentPasteEdit?(pasteEdit: T, token: CancellationToken): ProviderResult<T>;
+    }
+
+    /**
+     * An edit the applies a paste operation.
+     */
+    export class DocumentPasteEdit {
+
+        /**
+         * Human readable label that describes the edit.
+         */
+        title: string;
+
+        /**
+         * {@link DocumentDropOrPasteEditKind Kind} of the edit.
+         */
+        kind: DocumentDropOrPasteEditKind;
+
+        /**
+         * The text or snippet to insert at the pasted locations.
+         *
+         * If your edit requires more advanced insertion logic, set this to an empty string and provide an {@link DocumentPasteEdit.additionalEdit additional edit} instead.
+         */
+        insertText: string | SnippetString;
+
+        /**
+         * An optional additional edit to apply on paste.
+         */
+        additionalEdit?: WorkspaceEdit;
+
+        /**
+         * Controls ordering when multiple paste edits can potentially be applied.
+         *
+         * If this edit yields to another, it will be shown lower in the list of possible paste edits shown to the user.
+         */
+        yieldTo?: readonly DocumentDropOrPasteEditKind[];
+
+        /**
+         * Create a new paste edit.
+         *
+         * @param insertText The text or snippet to insert at the pasted locations.
+         * @param title Human readable label that describes the edit.
+         * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit.
+         */
+        constructor(insertText: string | SnippetString, title: string, kind: DocumentDropOrPasteEditKind);
+    }
+
+    /**
+     * Provides additional metadata about how a {@linkcode DocumentPasteEditProvider} works.
+     */
+    export interface DocumentPasteProviderMetadata {
+        /**
+         * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits}.
+         *
+         * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested.
+         */
+        readonly providedPasteEditKinds: readonly DocumentDropOrPasteEditKind[];
+
+        /**
+         * Mime types that {@linkcode DocumentPasteEditProvider.prepareDocumentPaste prepareDocumentPaste} may add on copy.
+         */
+        readonly copyMimeTypes?: readonly string[];
+
+        /**
+         * Mime types that {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for.
+         *
+         * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`.
+         *
+         * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench.
+         *
+         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@linkcode DataTransfer}.
+         * Note that {@linkcode DataTransferFile} entries are only created when pasting content from outside the editor, such as
+         * from the operating system.
+         */
+        readonly pasteMimeTypes?: readonly string[];
+    }
+
+    /**
+     * A tuple of two characters, like a pair of
+     * opening and closing brackets.
+     */
+    export type CharacterPair = [string, string];
+
     /**
      * Represents a session of a currently logged in user.
      */

package/src/theia.proposed.documentPaste.d.ts

@@ -1,330 +0,0 @@
-// *****************************************************************************
-// Copyright (C) 2023 Ericsson and others.
-//
-// This program and the accompanying materials are made available under the
-// terms of the Eclipse Public License v. 2.0 which is available at
-// http://www.eclipse.org/legal/epl-2.0.
-//
-// This Source Code may also be made available under the following Secondary
-// Licenses when the conditions for such availability set forth in the Eclipse
-// Public License v. 2.0 are satisfied: GNU General Public License, version 2
-// with the GNU Classpath Exception which is available at
-// https://www.gnu.org/software/classpath/license.html.
-//
-// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
-// *****************************************************************************
-
-/*---------------------------------------------------------------------------------------------
- *  Copyright (c) Microsoft Corporation. All rights reserved.
- *  Licensed under the MIT License. See License.txt in the project root for license information.
- *--------------------------------------------------------------------------------------------*/
-// code copied and modified from https://github.com/microsoft/vscode/blob/1.79.0/src/vscode-dts/vscode.proposed.documentPaste.d.ts
-
-export module '@theia/plugin' {
-
-    /**
-     * Identifies a {@linkcode DocumentDropEdit} or {@linkcode DocumentPasteEdit}
-     */
-    class DocumentDropOrPasteEditKind {
-        static readonly Empty: DocumentDropOrPasteEditKind;
-
-        /**
-         * The root kind for basic text edits.
-         *
-         * This kind should be used for edits that insert basic text into the document. A good example of this is
-         * an edit that pastes the clipboard text while also updating imports in the file based on the pasted text.
-         * For this we could use a kind such as `text.updateImports.someLanguageId`.
-         *
-         * Even though most drop/paste edits ultimately insert text, you should not use {@linkcode Text} as the base kind
-         * for every edit as this is redundant. Instead a more specific kind that describes the type of content being
-         * inserted should be used instead For example, if the edit adds a Markdown link, use `markdown.link` since even
-         * though the content being inserted is text, it's more important to know that the edit inserts Markdown syntax.
-         */
-        static readonly Text: DocumentDropOrPasteEditKind;
-
-        private constructor(value: string);
-
-        /**
-         * The raw string value of the kind.
-         */
-        readonly value: string;
-
-        /**
-         * Create a new kind by appending additional scopes to the current kind.
-         *
-         * Does not modify the current kind.
-         */
-        append(...parts: string[]): DocumentDropOrPasteEditKind;
-
-        /**
-         * Checks if this kind intersects `other`.
-         *
-         * The kind `"text.plain"` for example intersects `text`, `"text.plain"` and `"text.plain.list"`,
-         * but not `"unicorn"`, or `"textUnicorn.plain"`.
-         *
-         * @param other Kind to check.
-         */
-        intersects(other: DocumentDropOrPasteEditKind): boolean;
-
-        /**
-         * Checks if `other` is a sub-kind of this `DocumentDropOrPasteEditKind`.
-         *
-         * The kind `"text.plain"` for example contains `"text.plain"` and `"text.plain.list"`,
-         * but not `"text"` or `"unicorn.text.plain"`.
-         *
-         * @param other Kind to check.
-         */
-        contains(other: DocumentDropOrPasteEditKind): boolean;
-    }
-
-    /**
-     * The reason why paste edits were requested.
-     */
-    export enum DocumentPasteTriggerKind {
-        /**
-         * Pasting was requested as part of a normal paste operation.
-         */
-        Automatic = 0,
-
-        /**
-         * Pasting was requested by the user with the `paste as` command.
-         */
-        PasteAs = 1,
-    }
-
-    /**
-     * Additional information about the paste operation.
-     */
-
-    export interface DocumentPasteEditContext {
-        /**
-         * Requested kind of paste edits to return.
-         */
-        readonly only: DocumentDropOrPasteEditKind | undefined;
-
-        /**
-         * The reason why paste edits were requested.
-         */
-        readonly triggerKind: DocumentPasteTriggerKind;
-    }
-
-    /**
-     * Provider invoked when the user copies or pastes in a {@linkcode TextDocument}.
-     */
-    interface DocumentPasteEditProvider<T extends DocumentPasteEdit = DocumentPasteEdit> {
-
-        /**
-         * Optional method invoked after the user copies from a {@link TextEditor text editor}.
-         *
-         * This allows the provider to attach metadata about the copied text to the {@link DataTransfer}. This data
-         * transfer is then passed back to providers in {@linkcode provideDocumentPasteEdits}.
-         *
-         * Note that currently any changes to the {@linkcode DataTransfer} are isolated to the current editor window.
-         * This means that any added metadata cannot be seen by other editor windows or by other applications.
-         *
-         * @param document Text document where the copy took place.
-         * @param ranges Ranges being copied in {@linkcode document}.
-         * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for
-         * later use in  {@linkcode provideDocumentPasteEdits}. This object is only valid for the duration of this method.
-         * @param token A cancellation token.
-         *
-         * @return Optional thenable that resolves when all changes to the `dataTransfer` are complete.
-         */
-        prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>;
-
-        /**
-         * Invoked before the user pastes into a {@link TextEditor text editor}.
-         *
-         * Returned edits can replace the standard pasting behavior.
-         *
-         * @param document Document being pasted into
-         * @param ranges Range in the {@linkcode document} to paste into.
-         * @param dataTransfer The {@link DataTransfer data transfer} associated with the paste. This object is only
-         * valid for the duration of the paste operation.
-         * @param context Additional context for the paste.
-         * @param token A cancellation token.
-         *
-         * @return Set of potential {@link DocumentPasteEdit edits} that can apply the paste. Only a single returned
-         * {@linkcode DocumentPasteEdit} is applied at a time. If multiple edits are returned from all providers, then
-         * the first is automatically applied and a widget is shown that lets the user switch to the other edits.
-         */
-        provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext, token: CancellationToken):
-            ProviderResult<T[]>;
-
-        /**
-         * Optional method which fills in the {@linkcode DocumentPasteEdit.additionalEdit} before the edit is applied.
-         *
-         * This is called once per edit and should be used if generating the complete edit may take a long time.
-         * Resolve can only be used to change {@linkcode DocumentPasteEdit.additionalEdit}.
-         *
-         * @param pasteEdit The {@linkcode DocumentPasteEdit} to resolve.
-         * @param token A cancellation token.
-         *
-         * @returns The resolved paste edit or a thenable that resolves to such. It is OK to return the given
-         * `pasteEdit`. If no result is returned, the given `pasteEdit` is used.
-         */
-        resolveDocumentPasteEdit?(pasteEdit: T, token: CancellationToken): ProviderResult<T>;
-    }
-
-    /**
-     * An edit the applies a paste operation.
-     */
-    class DocumentPasteEdit {
-
-        /**
-         * Human readable label that describes the edit.
-         */
-        title: string;
-
-        /**
-         * {@link DocumentDropOrPasteEditKind Kind} of the edit.
-         */
-        kind: DocumentDropOrPasteEditKind;
-
-        /**
-         * The text or snippet to insert at the pasted locations.
-         *
-         * If your edit requires more advanced insertion logic, set this to an empty string and provide an {@link DocumentPasteEdit.additionalEdit additional edit} instead.
-         */
-        insertText: string | SnippetString;
-
-        /**
-         * An optional additional edit to apply on paste.
-         */
-        additionalEdit?: WorkspaceEdit;
-
-        /**
-         * Controls ordering when multiple paste edits can potentially be applied.
-         *
-         * If this edit yields to another, it will be shown lower in the list of possible paste edits shown to the user.
-         */
-        yieldTo?: readonly DocumentDropOrPasteEditKind[];
-
-        /**
-         * Create a new paste edit.
-         *
-         * @param insertText The text or snippet to insert at the pasted locations.
-         * @param title Human readable label that describes the edit.
-         * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit.
-         */
-        constructor(insertText: string | SnippetString, title: string, kind: DocumentDropOrPasteEditKind);
-    }
-
-    /**
-     * Provides additional metadata about how a {@linkcode DocumentPasteEditProvider} works.
-     */
-    interface DocumentPasteProviderMetadata {
-        /**
-         * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in
-         * {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits}.
-         *
-         * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested.
-         */
-        readonly providedPasteEditKinds: readonly DocumentDropOrPasteEditKind[];
-
-        /**
-         * Mime types that {@linkcode DocumentPasteEditProvider.prepareDocumentPaste prepareDocumentPaste} may add on copy.
-         */
-        readonly copyMimeTypes?: readonly string[];
-
-        /**
-         * Mime types that {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for.
-         *
-         * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`.
-         *
-         * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench.
-         *
-         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@linkcode DataTransfer}.
-         * Note that {@linkcode DataTransferFile} entries are only created when pasting content from outside the editor, such as
-         * from the operating system.
-         */
-        readonly pasteMimeTypes?: readonly string[];
-    }
-
-    /**
-     * TODO on finalization:
-     * - Add ctor(insertText: string | SnippetString, title?: string, kind?: DocumentDropOrPasteEditKind); Can't be done as this is an extension to an existing class
-     */
-
-    export interface DocumentDropEdit {
-        /**
-         * Human readable label that describes the edit.
-         */
-        title?: string;
-
-        /**
-         * {@link DocumentDropOrPasteEditKind Kind} of the edit.
-         */
-        kind: DocumentDropOrPasteEditKind;
-
-        /**
-         * Controls the ordering or multiple edits. If this provider yield to edits, it will be shown lower in the list.
-         */
-        yieldTo?: readonly DocumentDropOrPasteEditKind[];
-    }
-
-    export interface DocumentDropEditProvider<T extends DocumentDropEdit = DocumentDropEdit> {
-        // Overload that allows returning multiple edits
-        // Will be merged in on finalization
-        provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken):
-            ProviderResult<DocumentDropEdit | DocumentDropEdit[]>;
-
-        /**
-         * Optional method which fills in the {@linkcode DocumentDropEdit.additionalEdit} before the edit is applied.
-         *
-         * This is called once per edit and should be used if generating the complete edit may take a long time.
-         * Resolve can only be used to change {@link DocumentDropEdit.additionalEdit}.
-         *
-         * @param pasteEdit The {@linkcode DocumentDropEdit} to resolve.
-         * @param token A cancellation token.
-         *
-         * @returns The resolved edit or a thenable that resolves to such. It is OK to return the given
-         * `edit`. If no result is returned, the given `edit` is used.
-         */
-        resolveDocumentDropEdit?(edit: T, token: CancellationToken): ProviderResult<T>;
-    }
-
-    /**
-     * Provides additional metadata about how a {@linkcode DocumentDropEditProvider} works.
-     */
-    export interface DocumentDropEditProviderMetadata {
-        /**
-         * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentDropEditProvider.provideDocumentDropEdits provideDocumentDropEdits}.
-         *
-         * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested.
-         */
-        readonly providedDropEditKinds?: readonly DocumentDropOrPasteEditKind[];
-
-        /**
-         * List of {@link DataTransfer} mime types that the provider can handle.
-         *
-         * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`.
-         *
-         * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench.
-         *
-         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@link DataTransfer}.
-         * Note that {@link DataTransferFile} entries are only created when dropping content from outside the editor, such as
-         * from the operating system.
-         */
-        readonly dropMimeTypes: readonly string[];
-    }
-
-    namespace languages {
-        /**
-         * Registers a new {@linkcode DocumentPasteEditProvider}.
-         *
-         * @param selector A selector that defines the documents this provider applies to.
-         * @param provider A paste editor provider.
-         * @param metadata Additional metadata about the provider.
-         *
-         * @returns A {@link Disposable} that unregisters this provider when disposed of.
-         * @stubbed
-         */
-        export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable;
-
-        /**
-         * Overload which adds extra metadata. Will be removed on finalization.
-         */
-        export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider, metadata?: DocumentDropEditProviderMetadata): Disposable;
-    }
-}