@theia/plugin 1.22.1 → 1.23.0-next.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.22.1",
+  "version": "1.23.0-next.26+0aa2621d3fd",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "49910aeaecf520a54b253db0215b28c2268bb2f3"
+  "gitHead": "0aa2621d3fd7ce5f1dff771506f5473200104fea"
 }

package/src/theia-proposed.d.ts

@@ -81,12 +81,6 @@ export module '@theia/plugin' {
          */
         readonly supportsMultipleAccounts: boolean;
 
-        /**
-         * An [event](#Event) which fires when the array of sessions has changed, or data
-         * within a session has changed.
-         */
-        readonly onDidChangeSessions: Event<AuthenticationProviderAuthenticationSessionsChangeEvent>;
-
         /**
          * Returns an array of current sessions.
          */

package/src/theia.d.ts

@@ -2745,6 +2745,7 @@ export module '@theia/plugin' {
 
     /**
      * Options a virtual process terminal.
+     * @deprecated since 1.23.0 - Use [ExtensionTerminalOptions](#ExtensionTerminalOptions) instead.
      */
     export interface PseudoTerminalOptions {
         /**
@@ -2759,6 +2760,22 @@ export module '@theia/plugin' {
         pty: Pseudoterminal;
     }
 
+    /**
+     * Options a virtual process terminal.
+     */
+    export interface ExtensionTerminalOptions {
+        /**
+         * The name of the terminal.
+         */
+        name: string;
+
+        /**
+         * An implementation of [Pseudoterminal](#Pseudoterminal) where an extension can
+         * control it.
+         */
+        pty: Pseudoterminal;
+    }
+
     /**
      * Defines the interface of a terminal pty, enabling extensions to control a terminal.
      */
@@ -3971,6 +3988,87 @@ export module '@theia/plugin' {
 
     }
 
+    export interface WebviewView {
+        /**
+         * Identifies the type of the webview view, such as `'hexEditor.dataView'`.
+         */
+        readonly viewType: string;
+
+        /**
+         * The underlying webview for the view.
+         */
+        readonly webview: Webview;
+
+        /**
+         * View title displayed in the UI.
+         *
+         * The view title is initially taken from the extension `package.json` contribution.
+         */
+        title?: string;
+
+        /**
+         * Human-readable string which is rendered less prominently in the title.
+         */
+        description?: string;
+
+        /**
+         * Event fired when the view is disposed.
+         *
+         * Views are disposed when they are explicitly hidden by a user (this happens when a user
+         * right clicks in a view and unchecks the webview view).
+         *
+         * Trying to use the view after it has been disposed throws an exception.
+         */
+        readonly onDidDispose: Event<void>;
+
+        /**
+         * Tracks if the webview is currently visible.
+         *
+         * Views are visible when they are on the screen and expanded.
+         */
+        readonly visible: boolean;
+
+        /**
+         * Event fired when the visibility of the view changes.
+         *
+         * Actions that trigger a visibility change:
+         *
+         * - The view is collapsed or expanded.
+         * - The user switches to a different view group in the sidebar or panel.
+         *
+         * Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`.
+         */
+        readonly onDidChangeVisibility: Event<boolean>;
+
+        /**
+         * Reveal the view in the UI.
+         *
+         * If the view is collapsed, this will expand it.
+         *
+         * @param preserveFocus When `true` the view will not take focus.
+         */
+        show(preserveFocus?: boolean): void;
+    }
+    /**
+     * Provider for creating `WebviewView` elements.
+     */
+    export interface WebviewViewProvider {
+        /**
+         * Revolves a webview view.
+         *
+         * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is
+         * first loaded or when the user hides and then shows a view again.
+         *
+         * @param webviewView Webview view to restore. The provider should take ownership of this view. The
+         *    provider must set the webview's `.html` and hook up all webview events it is interested in.
+         * @param context Additional metadata about the view being resolved.
+         * @param token Cancellation token indicating that the view being provided is no longer needed.
+         *
+         * @return Optional thenable indicating that the view has been fully resolved.
+         */
+        resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void;
+    }
+
     /**
      * Common namespace for dealing with window and editor, showing messages and user input.
      */
@@ -4304,6 +4402,70 @@ export module '@theia/plugin' {
          * @param viewType Type of the webview panel that can be serialized.
          * @param serializer Webview serializer.
          */
+
+        /**
+         * Additional information the webview view being resolved.
+         *
+         * @param T Type of the webview's state.
+         */
+        interface WebviewViewResolveContext<T = unknown> {
+            /**
+             * Persisted state from the webview content.
+             *
+             * To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible.
+             * For example, when the user collapse a view or switches to another top level activity in the sidebar, the
+             * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
+             * the view becomes visible again.
+             *
+             * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
+             * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
+             * save off a webview's state so that it can be quickly recreated as needed.
+             *
+             * To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
+             * any json serializable object. To restore the state again, call `getState()`. For example:
+             *
+             * ```js
+             * // Within the webview
+             * const vscode = acquireVsCodeApi();
+             *
+             * // Get existing state
+             * const oldState = vscode.getState() || { value: 0 };
+             *
+             * // Update state
+             * setState({ value: oldState.value + 1 })
+             * ```
+             *
+             * VS Code ensures that the persisted state is saved correctly when a webview is hidden and across
+             * editor restarts.
+             */
+            readonly state: T | undefined;
+        }
+
+        export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
+            /**
+             * Content settings for the webview created for this view.
+             */
+            readonly webviewOptions?: {
+                /**
+                 * Controls if the webview element itself (iframe) is kept around even when the view
+                 * is no longer visible.
+                 *
+                 * Normally the webview's html context is created when the view becomes visible
+                 * and destroyed when it is hidden. Extensions that have complex state
+                 * or UI can set the `retainContextWhenHidden` to make the editor keep the webview
+                 * context around, even when the webview moves to a background tab. When a webview using
+                 * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
+                 * When the view becomes visible again, the context is automatically restored
+                 * in the exact same state it was in originally. You cannot send messages to a
+                 * hidden webview, even with `retainContextWhenHidden` enabled.
+                 *
+                 * `retainContextWhenHidden` has a high memory overhead and should only be used if
+                 * your view's context cannot be quickly saved and restored.
+                 */
+                readonly retainContextWhenHidden?: boolean;
+            };
+        }): Disposable;
+
         export function registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable;
 
         /**
@@ -4439,6 +4601,14 @@ export module '@theia/plugin' {
          */
         export function createTerminal(options: PseudoTerminalOptions): Terminal;
 
+        /**
+         * Creates a pseudo where an extension controls its input and output.
+         *
+         * @param options ExtensionTerminalOptions.
+         * @return A new Terminal.
+         */
+        export function createTerminal(options: ExtensionTerminalOptions): Terminal;
+
         /**
          * Register a [TreeDataProvider](#TreeDataProvider) for the view contributed using the extension point `views`.
          * This will allow you to contribute data to the [TreeView](#TreeView) and update if the data changes.
@@ -6024,6 +6194,28 @@ export module '@theia/plugin' {
          * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
          */
         export function registerTaskProvider(type: string, provider: TaskProvider): Disposable;
+
+        /**
+         * When true, the user has explicitly trusted the contents of the workspace.
+         */
+        export const isTrusted: boolean;
+
+        export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Promise<boolean | undefined>;
+
+        /**
+         * Event that fires when the current workspace has been trusted.
+         */
+        export const onDidGrantWorkspaceTrust: Event<void>;
+    }
+
+    export interface WorkspaceTrustRequestButton {
+        readonly label: string;
+        readonly type: 'ContinueWithTrust' | 'ContinueWithoutTrust' | 'Manage' | 'Cancel'
+    }
+
+    export interface WorkspaceTrustRequestOptions {
+        readonly buttons?: WorkspaceTrustRequestButton[];
+        readonly message?: string;
     }
 
     export namespace env {
@@ -10992,6 +11184,28 @@ export module '@theia/plugin' {
          * Defaults to false.
          */
         clearSessionPreference?: boolean;
+
+        /**
+         * Whether we should attempt to reauthenticate even if there is already a session available.
+         *
+         * If true, a modal dialog will be shown asking the user to sign in again. This is mostly used for scenarios
+         * where the token needs to be re minted because it has lost some authorization.
+         *
+         * Defaults to false.
+         */
+        forceNewSession?: boolean | { detail: string };
+
+        /**
+         * Whether we should show the indication to sign in in the Accounts menu.
+         *
+         * If false, the user will be shown a badge on the Accounts menu with an option to sign in for the extension.
+         * If true, no indication will be shown.
+         *
+         * Defaults to false.
+         *
+         * Note: you cannot use this option with any other options that prompt the user like {@link createIfNone}.
+         */
+        silent?: boolean;
     }
 
     /**
@@ -11019,6 +11233,83 @@ export module '@theia/plugin' {
         readonly provider: AuthenticationProviderInformation;
     }
 
+    /**
+     * Options for creating an {@link AuthenticationProvider}.
+     */
+    export interface AuthenticationProviderOptions {
+        /**
+         * Whether it is possible to be signed into multiple accounts at once with this provider.
+         * If not specified, will default to false.
+         */
+        readonly supportsMultipleAccounts?: boolean;
+    }
+
+    /**
+     * An {@link Event} which fires when an {@link AuthenticationSession} is added, removed, or changed.
+     */
+    export interface AuthenticationProviderAuthenticationSessionsChangeEvent {
+        /**
+         * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been added.
+         */
+        readonly added: readonly AuthenticationSession[] | undefined;
+
+        /**
+         * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been removed.
+         */
+        readonly removed: readonly AuthenticationSession[] | undefined;
+
+        /**
+         * The {@link AuthenticationSession AuthenticationSessions} of the {@link AuthenticationProvider} that have been changed.
+         * A session changes when its data excluding the id are updated. An example of this is a session refresh that results in a new
+         * access token being set for the session.
+         */
+        readonly changed: readonly AuthenticationSession[] | undefined;
+    }
+
+    /**
+     * A provider for performing authentication to a service.
+     */
+    export interface AuthenticationProvider {
+        /**
+         * An {@link Event} which fires when the array of sessions has changed, or data
+         * within a session has changed.
+         */
+        readonly onDidChangeSessions: Event<AuthenticationProviderAuthenticationSessionsChangeEvent>;
+
+        /**
+         * Get a list of sessions.
+         * @param scopes An optional list of scopes. If provided, the sessions returned should match
+         * these permissions, otherwise all sessions should be returned.
+         * @returns A promise that resolves to an array of authentication sessions.
+         */
+        getSessions(scopes?: readonly string[]): Thenable<readonly AuthenticationSession[]>;
+
+        /**
+         * Prompts a user to login.
+         *
+         * If login is successful, the onDidChangeSessions event should be fired.
+         *
+         * If login fails, a rejected promise should be returned.
+         *
+         * If the provider has specified that it does not support multiple accounts,
+         * then this should never be called if there is already an existing session matching these
+         * scopes.
+         * @param scopes A list of scopes, permissions, that the new session should be created with.
+         * @returns A promise that resolves to an authentication session.
+         */
+        createSession(scopes: readonly string[]): Thenable<AuthenticationSession>;
+
+        /**
+         * Removes the session corresponding to session id.
+         *
+         * If the removal is successful, the onDidChangeSessions event should be fired.
+         *
+         * If a session cannot be removed, the provider should reject with an error message.
+         * @param sessionId The id of the session to remove.
+         */
+        removeSession(sessionId: string): Thenable<void>;
+    }
+
     /**
      * Namespace for authentication.
      */
@@ -11038,6 +11329,21 @@ export module '@theia/plugin' {
          */
         export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable<AuthenticationSession>;
 
+        /**
+         * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
+         * registered, or if the user does not consent to sharing authentication information with
+         * the extension. If there are multiple sessions with the same scopes, the user will be shown a
+         * quickpick to select which account they would like to use.
+         *
+         * Currently, there are only two authentication providers that are contributed from built in extensions
+         * to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
+         * @param providerId The id of the provider to use
+         * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
+         * @param options The {@link AuthenticationGetSessionOptions} to use
+         * @returns A thenable that resolves to an authentication session
+         */
+        export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { forceNewSession: true | { detail: string } }): Thenable<AuthenticationSession>;
+
         /**
          * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
          * registered, or if the user does not consent to sharing authentication information with
@@ -11056,5 +11362,25 @@ export module '@theia/plugin' {
          * been added, removed, or changed.
          */
         export const onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>;
+
+        /**
+         * Register an authentication provider.
+         *
+         * There can only be one provider per id and an error is being thrown when an id
+         * has already been used by another provider. Ids are case-sensitive.
+         *
+         * @param id The unique identifier of the provider.
+         * @param label The human-readable name of the provider.
+         * @param provider The authentication provider provider.
+         * @params options Additional options for the provider.
+         * @return A {@link Disposable} that unregisters this provider when being disposed.
+         */
+        export function registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable;
+
+        /**
+         * @deprecated Use {@link getSession()} {@link AuthenticationGetSessionOptions.silent} instead.
+         */
+        export function hasSession(providerId: string, scopes: readonly string[]): Thenable<boolean>;
+
     }
 }