@theia/plugin 1.34.0 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.34.0"
+    "@theia/ext-scripts": "1.35.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "a8c403b103829a1b8b092ce741ef3826804f773b"
+  "gitHead": "5b1e4f9b913cf1b0d27acd4bc435cb2570f164d8"
 }

package/src/theia.d.ts

@@ -5653,6 +5653,103 @@ export module '@theia/plugin' {
         report(value: T): void;
     }
 
+    /**
+     * A file associated with a {@linkcode DataTransferItem}.
+     */
+    export interface DataTransferFile {
+        /**
+         * The name of the file.
+         */
+        readonly name: string;
+
+        /**
+         * The full file path of the file.
+         *
+         * May be `undefined` on web.
+         */
+        readonly uri?: Uri;
+
+        /**
+         * The full file contents of the file.
+         */
+        data(): Thenable<Uint8Array>;
+    }
+
+    /**
+     * Encapsulates data transferred during drag and drop operations.
+     */
+    export class DataTransferItem {
+        /**
+         * Get a string representation of this item.
+         *
+         * If {@linkcode DataTransferItem.value} is an object, this returns the result of json stringifying {@linkcode DataTransferItem.value} value.
+         */
+        asString(): Thenable<string>;
+
+        /**
+         * Try getting the {@link DataTransferFile file} associated with this data transfer item.
+         *
+         * Note that the file object is only valid for the scope of the drag and drop operation.
+         *
+         * @returns The file for the data transfer or `undefined` if the item is either not a file or the
+         * file data cannot be accessed.
+         */
+        asFile(): DataTransferFile | undefined;
+
+        /**
+         * Custom data stored on this item.
+         *
+         * You can use `value` to share data across operations. The original object can be retrieved so long as the extension that
+         * created the `DataTransferItem` runs in the same extension host.
+         */
+        readonly value: any;
+
+        /**
+         * @param value Custom data stored on this item. Can be retrieved using {@linkcode DataTransferItem.value}.
+         */
+        constructor(value: any);
+    }
+
+    /**
+     * A map containing a mapping of the mime type of the corresponding transferred data.
+     *
+     * Drag and drop controllers that implement {@link TreeDragAndDropController.handleDrag `handleDrag`} can add additional mime types to the
+     * data transfer. These additional mime types will only be included in the `handleDrop` when the the drag was initiated from
+     * an element in the same drag and drop controller.
+     */
+    export class DataTransfer implements Iterable<[mimeType: string, item: DataTransferItem]> {
+        /**
+         * Retrieves the data transfer item for a given mime type.
+         *
+         * @param mimeType The mime type to get the data transfer item for, such as `text/plain` or `image/png`.
+         *
+         * Special mime types:
+         * - `text/uri-list` — A string with `toString()`ed Uris separated by `\r\n`. To specify a cursor position in the file,
+         * set the Uri's fragment to `L3,5`, where 3 is the line number and 5 is the column number.
+         */
+        get(mimeType: string): DataTransferItem | undefined;
+
+        /**
+         * Sets a mime type to data transfer item mapping.
+         * @param mimeType The mime type to set the data for.
+         * @param value The data transfer item for the given mime type.
+         */
+        set(mimeType: string, value: DataTransferItem): void;
+
+        /**
+         * Allows iteration through the data transfer items.
+         *
+         * @param callbackfn Callback for iteration through the data transfer items.
+         * @param thisArg The `this` context used when invoking the handler function.
+         */
+        forEach(callbackfn: (item: DataTransferItem, mimeType: string, dataTransfer: DataTransfer) => void, thisArg?: any): void;
+
+        /**
+         * Get a new iterator with the `[mime, item]` pairs for each element in this data transfer.
+         */
+        [Symbol.iterator](): IterableIterator<[mimeType: string, item: DataTransferItem]>;
+    }
+
     /**
      * Options for creating a {@link TreeView TreeView}
      */
@@ -7108,9 +7205,10 @@ export module '@theia/plugin' {
          * not be attempted, when a single edit fails.
          *
          * @param edit A workspace edit.
+         * @param metadata Optional {@link WorkspaceEditMetadata metadata} for the edit.
          * @return A thenable that resolves when the edit could be applied.
          */
-        export function applyEdit(edit: WorkspaceEdit): Thenable<boolean>;
+        export function applyEdit(edit: WorkspaceEdit, metadata?: WorkspaceEditMetadata): Thenable<boolean>;
 
         /**
          * Register a filesystem provider for a given scheme, e.g. `ftp`.
@@ -9652,6 +9750,16 @@ export module '@theia/plugin' {
         iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
     }
 
+    /**
+     * Additional data about a workspace edit.
+     */
+    export interface WorkspaceEditMetadata {
+        /**
+         * Signal to the editor that this edit is a refactoring.
+         */
+        isRefactoring?: boolean;
+    }
+
     /**
      * A workspace edit is a collection of textual and files changes for
      * multiple resources and documents.
@@ -10347,6 +10455,16 @@ export module '@theia/plugin' {
          */
         export function registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable;
 
+        /**
+         * Registers a new {@link DocumentDropEditProvider}.
+         *
+         * @param selector A selector that defines the documents this provider applies to.
+         * @param provider A drop provider.
+         *
+         * @return A {@link Disposable} that unregisters this provider when disposed of.
+         */
+        export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider): Disposable;
+
         /**
          * Register a declaration provider.
          *
@@ -13208,6 +13326,48 @@ export module '@theia/plugin' {
         provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<LinkedEditingRanges>;
     }
 
+    /**
+     * An edit operation applied {@link DocumentDropEditProvider on drop}.
+     */
+    export class DocumentDropEdit {
+        /**
+         * The text or snippet to insert at the drop location.
+         */
+        insertText: string | SnippetString;
+
+        /**
+         * An optional additional edit to apply on drop.
+         */
+        additionalEdit?: WorkspaceEdit;
+
+        /**
+         * @param insertText The text or snippet to insert at the drop location.
+         */
+        constructor(insertText: string | SnippetString);
+    }
+
+    /**
+     * Provider which handles dropping of resources into a text editor.
+     *
+     * This allows users to drag and drop resources (including resources from external apps) into the editor. While dragging
+     * 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 {
+        /**
+         * Provide edits which inserts the content being dragged and dropped into the document.
+         *
+         * @param document The document in which the drop occurred.
+         * @param position The position in the document where the drop occurred.
+         * @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
+         * signaled by returning `undefined` or `null`.
+         */
+        provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<DocumentDropEdit>;
+    }
+
     /**
      * Represents a session of a currently logged in user.
      */
@@ -13474,13 +13634,11 @@ export module '@theia/plugin' {
     export class TabInputText {
         /**
          * The uri represented by the tab.
-         * @stubbed
          */
         readonly uri: Uri;
         /**
          * Constructs a text tab input with the given URI.
          * @param uri The URI of the tab.
-         * @stubbed
          */
         constructor(uri: Uri);
     }
@@ -13492,19 +13650,16 @@ export module '@theia/plugin' {
     export class TabInputTextDiff {
         /**
          * The uri of the original text resource.
-         * @stubbed
          */
         readonly original: Uri;
         /**
          * The uri of the modified text resource.
-         * @stubbed
          */
         readonly modified: Uri;
         /**
          * Constructs a new text diff tab input with the given URIs.
          * @param original The uri of the original text resource.
          * @param modified The uri of the modified text resource.
-         * @stubbed
          */
         constructor(original: Uri, modified: Uri);
     }
@@ -13515,19 +13670,16 @@ export module '@theia/plugin' {
     export class TabInputCustom {
         /**
          * The uri that the tab is representing.
-         * @stubbed
          */
         readonly uri: Uri;
         /**
          * The type of custom editor.
-         * @stubbed
          */
         readonly viewType: string;
         /**
          * Constructs a custom editor tab input.
          * @param uri The uri of the tab.
          * @param viewType The viewtype of the custom editor.
-         * @stubbed
          */
         constructor(uri: Uri, viewType: string);
     }
@@ -13538,13 +13690,11 @@ export module '@theia/plugin' {
     export class TabInputWebview {
         /**
          * The type of webview. Maps to WebviewPanel's viewType
-         * @stubbed
          */
         readonly viewType: string;
         /**
          * Constructs a webview tab input with the given view type.
          * @param viewType The type of webview. Maps to WebviewPanel's viewType
-         * @stubbed
          */
         constructor(viewType: string);
     }
@@ -13555,19 +13705,16 @@ export module '@theia/plugin' {
     export class TabInputNotebook {
         /**
          * The uri that the tab is representing.
-         * @stubbed
          */
         readonly uri: Uri;
         /**
          * The type of notebook. Maps to NotebookDocuments's notebookType
-         * @stubbed
          */
         readonly notebookType: string;
         /**
          * Constructs a new tab input for a notebook.
          * @param uri The uri of the notebook.
          * @param notebookType The type of notebook. Maps to NotebookDocuments's notebookType
-         * @stubbed
          */
         constructor(uri: Uri, notebookType: string);
     }
@@ -13578,17 +13725,14 @@ export module '@theia/plugin' {
     export class TabInputNotebookDiff {
         /**
          * The uri of the original notebook.
-         * @stubbed
          */
         readonly original: Uri;
         /**
          * The uri of the modified notebook.
-         * @stubbed
          */
         readonly modified: Uri;
         /**
          * The type of notebook. Maps to NotebookDocuments's notebookType
-         * @stubbed
          */
         readonly notebookType: string;
         /**
@@ -13596,7 +13740,6 @@ export module '@theia/plugin' {
          * @param original The uri of the original unmodified notebook.
          * @param modified The uri of the modified notebook.
          * @param notebookType The type of notebook. Maps to NotebookDocuments's notebookType
-         * @stubbed
          */
         constructor(original: Uri, modified: Uri, notebookType: string);
     }
@@ -13607,7 +13750,6 @@ export module '@theia/plugin' {
     export class TabInputTerminal {
         /**
          * Constructs a terminal tab input.
-         * @stubbed
          */
         constructor();
     }
@@ -13621,45 +13763,38 @@ export module '@theia/plugin' {
 
         /**
          * The text displayed on the tab.
-         * @stubbed
          */
         readonly label: string;
 
         /**
          * The group which the tab belongs to.
-         * @stubbed
          */
         readonly group: TabGroup;
 
         /**
          * Defines the structure of the tab i.e. text, notebook, custom, etc.
          * Resource and other useful properties are defined on the tab kind.
-         * @stubbed
          */
         readonly input: TabInputText | TabInputTextDiff | TabInputCustom | TabInputWebview | TabInputNotebook | TabInputNotebookDiff | TabInputTerminal | unknown;
 
         /**
          * Whether or not the tab is currently active.
          * This is dictated by being the selected tab in the group.
-         * @stubbed
          */
         readonly isActive: boolean;
 
         /**
          * Whether or not the dirty indicator is present on the tab.
-         * @stubbed
          */
         readonly isDirty: boolean;
 
         /**
          * Whether or not the tab is pinned (pin icon is present).
-         * @stubbed
          */
         readonly isPinned: boolean;
 
         /**
          * Whether or not the tab is in preview mode.
-         * @stubbed
          */
         readonly isPreview: boolean;
     }
@@ -13670,18 +13805,15 @@ export module '@theia/plugin' {
     export interface TabChangeEvent {
         /**
          * The tabs that have been opened.
-         * @stubbed
          */
         readonly opened: readonly Tab[];
         /**
          * The tabs that have been closed.
-         * @stubbed
          */
         readonly closed: readonly Tab[];
         /**
          * Tabs that have changed, e.g have changed
          * their {@link Tab.isActive active} state.
-         * @stubbed
          */
         readonly changed: readonly Tab[];
     }
@@ -13692,18 +13824,15 @@ export module '@theia/plugin' {
     export interface TabGroupChangeEvent {
         /**
          * Tab groups that have been opened.
-         * @stubbed
          */
         readonly opened: readonly TabGroup[];
         /**
          * Tab groups that have been closed.
-         * @stubbed
          */
         readonly closed: readonly TabGroup[];
         /**
          * Tab groups that have changed, e.g have changed
          * their {@link TabGroup.isActive active} state.
-         * @stubbed
          */
         readonly changed: readonly TabGroup[];
     }
@@ -13719,13 +13848,11 @@ export module '@theia/plugin' {
          * groups can have an {@link TabGroup.aciveTab active tab}.
          *
          * @see {@link Tab.isActive}
-         * @stubbed
          */
         readonly isActive: boolean;
 
         /**
          * The view column of the group.
-         * @stubbed
          */
         readonly viewColumn: ViewColumn;
 
@@ -13734,14 +13861,12 @@ export module '@theia/plugin' {
          * being rendered.
          *
          * *Note* that there can be one active tab per group but there can only be one {@link TabGroups.activeTabGroup active group}.
-         * @stubbed
          */
         readonly activeTab: Tab | undefined;
 
         /**
          * The list of tabs contained within the group.
          * This can be empty if the group has no tabs open.
-         * @stubbed
          */
         readonly tabs: readonly Tab[];
     }
@@ -13752,25 +13877,21 @@ export module '@theia/plugin' {
     export interface TabGroups {
         /**
          * All the groups within the group container.
-         * @stubbed
          */
         readonly all: readonly TabGroup[];
 
         /**
          * The currently active group.
-         * @stubbed
          */
         readonly activeTabGroup: TabGroup;
 
         /**
          * An {@link Event event} which fires when {@link TabGroup tab groups} have changed.
-         * @stubbed
          */
         readonly onDidChangeTabGroups: Event<TabGroupChangeEvent>;
 
         /**
          * An {@link Event event} which fires when {@link Tab tabs} have changed.
-         * @stubbed
          */
         readonly onDidChangeTabs: Event<TabChangeEvent>;
 
@@ -13782,7 +13903,6 @@ export module '@theia/plugin' {
          * @param tab The tab to close.
          * @param preserveFocus When `true` focus will remain in its current position. If `false` it will jump to the next tab.
          * @returns A promise that resolves to `true` when all tabs have been closed.
-         * @stubbed
          */
         close(tab: Tab | readonly Tab[], preserveFocus?: boolean): Thenable<boolean>;
 
@@ -13792,7 +13912,6 @@ export module '@theia/plugin' {
          * @param tabGroup The tab group to close.
          * @param preserveFocus When `true` focus will remain in its current position.
          * @returns A promise that resolves to `true` when all tab groups have been closed.
-         * @stubbed
          */
         close(tabGroup: TabGroup | readonly TabGroup[], preserveFocus?: boolean): Thenable<boolean>;
     }
@@ -13933,7 +14052,6 @@ export module '@theia/plugin' {
 
         /**
          * The {@link NotebookDocument notebook} that contains this cell.
-         * @stubbed
          */
         readonly notebook: NotebookDocument;
 
@@ -13994,26 +14112,22 @@ export module '@theia/plugin' {
         /**
          * The version number of this notebook (it will strictly increase after each
          * change, including undo/redo).
-         * @stubbed
          */
         readonly version: number;
 
         /**
          * `true` if there are unpersisted changes.
-         * @stubbed
          */
         readonly isDirty: boolean;
 
         /**
          * Is this notebook representing an untitled file which has not been saved yet.
-         * @stubbed
          */
         readonly isUntitled: boolean;
 
         /**
          * `true` if the notebook has been closed. A closed notebook isn't synchronized anymore
          * and won't be re-used when the same resource is opened again.
-         * @stubbed
          */
         readonly isClosed: boolean;