@theia/plugin 1.33.0 → 1.34.0-next.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.33.0",
+  "version": "1.34.0-next.31+255450b22",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "d66562f95639027021574e130d20bb9459d89534"
+  "gitHead": "255450b224eae499d1b130eaf7318ac9659baaa4"
 }

package/src/theia.d.ts

@@ -3001,10 +3001,34 @@ export module '@theia/plugin' {
          */
         message?: string;
 
+        /**
+         * The {@link TerminalLocation} or {@link TerminalEditorLocationOptions} or {@link TerminalSplitLocationOptions} for the terminal.
+         */
+        location?: TerminalLocation | TerminalEditorLocationOptions | TerminalSplitLocationOptions;
+
+        /**
+         * Opt-out of the default terminal persistence on restart and reload.
+         * This will only take effect when `terminal.integrated.enablePersistentSessions` is enabled.
+         */
+        isTransient?: boolean;
+
         /**
          * Terminal attributes. Can be useful to apply some implementation specific information.
          */
         attributes?: { [key: string]: string | null };
+
+        /**
+         * The icon path or {@link ThemeIcon} for the terminal.
+         */
+        iconPath?: ThemeIcon;
+
+        /**
+         * The icon {@link ThemeColor} for the terminal.
+         * The `terminal.ansi*` theme keys are
+         * recommended for the best contrast and consistency across themes.
+         * @stubbed
+         */
+        color?: ThemeColor;
     }
 
     /**
@@ -3067,6 +3091,30 @@ export module '@theia/plugin' {
          * control it.
          */
         pty: Pseudoterminal;
+
+        /**
+         * The {@link TerminalLocation} or {@link TerminalEditorLocationOptions} or {@link TerminalSplitLocationOptions} for the terminal.
+         */
+        location?: TerminalLocation | TerminalEditorLocationOptions | TerminalSplitLocationOptions;
+
+        /**
+         * Opt-out of the default terminal persistence on restart and reload.
+         * This will only take effect when `terminal.integrated.enablePersistentSessions` is enabled.
+         */
+        isTransient?: boolean;
+
+        /**
+         * The icon path or {@link ThemeIcon} for the terminal.
+         */
+        iconPath?: ThemeIcon;
+
+        /**
+         * The icon {@link ThemeColor} for the terminal.
+         * The standard `terminal.ansi*` theme keys are
+         * recommended for the best contrast and consistency across themes.
+         * @stubbed
+         */
+        color?: ThemeColor;
     }
 
     /**
@@ -3207,6 +3255,50 @@ export module '@theia/plugin' {
         constructor(startIndex: number, length: number, tooltip?: string);
     }
 
+    /**
+     * The location of the {@link Terminal}.
+     */
+    export enum TerminalLocation {
+        /**
+         * In the terminal view
+         */
+        Panel = 1,
+        /**
+         * In the editor area
+         */
+        Editor = 2,
+    }
+
+    /**
+     * Assumes a {@link TerminalLocation} of editor and allows specifying a {@link ViewColumn} and
+     * {@link TerminalEditorLocationOptions.preserveFocus preserveFocus } property
+     */
+    export interface TerminalEditorLocationOptions {
+        /**
+         * A view column in which the {@link Terminal terminal} should be shown in the editor area.
+         * Use {@link ViewColumn.Active active} to open in the active editor group, 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.
+         */
+        viewColumn: ViewColumn;
+        /**
+         * An optional flag that when `true` will stop the {@link Terminal} from taking focus.
+         */
+        preserveFocus?: boolean;
+    }
+
+    /**
+     * Uses the parent {@link Terminal}'s location for the terminal
+     */
+    export interface TerminalSplitLocationOptions {
+        /**
+         * The parent terminal to split this terminal beside. This works whether the parent terminal
+         * is in the panel or the editor area.
+         */
+        parentTerminal: Terminal;
+    }
+
     /**
      * A file decoration represents metadata that can be rendered with a file.
      */
@@ -4554,6 +4646,11 @@ export module '@theia/plugin' {
      */
     export namespace window {
 
+        /**
+         * Represents the grid widget within the main editor area
+         */
+        export const tabGroups: TabGroups;
+
         /**
          * The currently active terminal or undefined. The active terminal is the one
          * that currently has focus or most recently had focus.
@@ -5318,6 +5415,17 @@ export module '@theia/plugin' {
          */
         password: boolean;
 
+        /**
+         * Selection range in the input value. Defined as tuple of two number where the
+         * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole
+         * pre-filled value will be selected, when empty (start equals end) only the cursor will be set,
+         * otherwise the defined range will be selected.
+         *
+         * This property does not get updated when the user types or makes a selection,
+         * but it can be updated by the extension.
+         */
+        valueSelection: readonly [number, number] | undefined;
+
         /**
          * An event signaling when the value has changed.
          */
@@ -8764,11 +8872,21 @@ export module '@theia/plugin' {
         source?: string;
 
         /**
-         * A code or identifier for this diagnostics. Will not be surfaced
-         * to the user, but should be used for later processing, e.g. when
-         * providing {@link CodeActionContext code actions}.
+         * A code or identifier for this diagnostic.
+         * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}.
          */
-        code?: string | number;
+        code?: string | number | {
+            /**
+             * A code or identifier for this diagnostic.
+             * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}.
+             */
+            value: string | number;
+
+            /**
+             * A target URI to open with more information about the diagnostic error.
+             */
+            target: Uri;
+        };
 
         /**
          * An array of related diagnostic information, e.g. when symbol-names within
@@ -9179,6 +9297,17 @@ export module '@theia/plugin' {
          */
         static readonly RefactorInline: CodeActionKind;
 
+        /**
+         * Base kind for refactoring inline actions: `refactor.move`
+         *
+         * Example move actions:
+         *
+         * - Move a function to a new file
+         * - Move a property between classes
+         * - Move method to base class
+         */
+        static readonly RefactorMove: CodeActionKind;
+
         /**
          * Base kind for refactoring rewrite actions: `refactor.rewrite`
          *
@@ -9372,7 +9501,15 @@ export module '@theia/plugin' {
          * @param uri A resource identifier.
          * @param edits An array of text edits.
          */
-        set(uri: Uri, edits: TextEdit[]): void;
+        set(uri: Uri, edits: ReadonlyArray<TextEdit | SnippetTextEdit>): void;
+
+        /**
+         * Set (and replace) text edits or snippet edits with metadata for a resource.
+         *
+         * @param uri A resource identifier.
+         * @param edits An array of edits.
+         */
+        set(uri: Uri, edits: ReadonlyArray<[TextEdit | SnippetTextEdit, WorkspaceEditEntryMetadata]>): void;
 
         /**
          * Get the text edits for a resource.
@@ -10694,6 +10831,11 @@ export module '@theia/plugin' {
          * Controls whether the input box is visible (default is true).
          */
         visible: boolean;
+
+        /**
+         * Controls whether the input box is enabled (default is `true`).
+         */
+        enabled: boolean;
     }
 
     interface QuickDiffProvider {
@@ -12415,6 +12557,11 @@ export module '@theia/plugin' {
          * Label will be rendered next to authorName if exists.
          */
         label?: string;
+
+        /**
+         * Optional timestamp.
+         */
+        timestamp?: Date;
     }
 
     /**
@@ -13114,6 +13261,335 @@ export module '@theia/plugin' {
         export function registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable;
     }
 
+    /**
+     * The tab represents a single text based resource.
+     */
+    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);
+    }
+
+    /**
+     * The tab represents two text based resources
+     * being rendered as a diff.
+     */
+    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);
+    }
+
+    /**
+     * The tab represents a custom editor.
+     */
+    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);
+    }
+
+    /**
+     * The tab represents a webview.
+     */
+    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);
+    }
+
+    /**
+     * The tab represents a notebook.
+     */
+    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);
+    }
+
+    /**
+     * The tabs represents two notebooks in a diff configuration.
+     */
+    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;
+        /**
+         * Constructs a notebook diff tab input.
+         * @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);
+    }
+
+    /**
+     * The tab represents a terminal in the editor area.
+     */
+    export class TabInputTerminal {
+        /**
+         * Constructs a terminal tab input.
+         * @stubbed
+         */
+        constructor();
+    }
+
+    /**
+     * Represents a tab within a {@link TabGroup group of tabs}.
+     * Tabs are merely the graphical representation within the editor area.
+     * A backing editor is not a guarantee.
+     */
+    export interface Tab {
+
+        /**
+         * 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;
+    }
+
+    /**
+     * An event describing change to tabs.
+     */
+    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[];
+    }
+
+    /**
+     * An event describing changes to tab groups.
+     */
+    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[];
+    }
+
+    /**
+     * Represents a group of tabs. A tab group itself consists of multiple tabs.
+     */
+    export interface TabGroup {
+        /**
+         * Whether or not the group is currently active.
+         *
+         * *Note* that only one tab group is active at a time, but that multiple tab
+         * 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;
+
+        /**
+         * The active {@link Tab tab} in the group. This is the tab whose contents are currently
+         * 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[];
+    }
+
+    /**
+     * Represents the main editor area which consists of multple groups which contain tabs.
+     */
+    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>;
+
+        /**
+         * Closes the tab. This makes the tab object invalid and the tab
+         * should no longer be used for further actions.
+         * Note: In the case of a dirty tab, a confirmation dialog will be shown which may be cancelled. If cancelled the tab is still valid
+         *
+         * @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>;
+
+        /**
+         * Closes the tab group. This makes the tab group object invalid and the tab group
+         * should no longer be used for further actions.
+         * @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>;
+    }
+
     /**
      * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}.
      */
@@ -13846,6 +14322,54 @@ export module '@theia/plugin' {
         readonly selections?: readonly NotebookRange[];
     }
 
+    /**
+     * A snippet edit represents an interactive edit that is performed by
+     * the editor.
+     *
+     * *Note* that a snippet edit can always be performed as a normal {@link TextEdit text edit}.
+     * This will happen when no matching editor is open or when a {@link WorkspaceEdit workspace edit}
+     * contains snippet edits for multiple files. In that case only those that match the active editor
+     * will be performed as snippet edits and the others as normal text edits.
+     */
+    export class SnippetTextEdit {
+
+        /**
+         * Utility to create a replace snippet edit.
+         *
+         * @param range A range.
+         * @param snippet A snippet string.
+         * @return A new snippet edit object.
+         */
+        static replace(range: Range, snippet: SnippetString): SnippetTextEdit;
+
+        /**
+         * Utility to create an insert snippet edit.
+         *
+         * @param position A position, will become an empty range.
+         * @param snippet A snippet string.
+         * @return A new snippet edit object.
+         */
+        static insert(position: Position, snippet: SnippetString): SnippetTextEdit;
+
+        /**
+         * The range this edit applies to.
+         */
+        range: Range;
+
+        /**
+         * The {@link SnippetString snippet} this edit will perform.
+         */
+        snippet: SnippetString;
+
+        /**
+         * Create a new snippet edit.
+         *
+         * @param range A range.
+         * @param snippet A snippet string.
+         */
+        constructor(range: Range, snippet: SnippetString);
+    }
+
     /**
      * A notebook edit represents edits that should be applied to the contents of a notebook.
      */