@theia/plugin 1.31.0-next.3 → 1.31.0-next.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.31.0-next.3+d3f635993",
+  "version": "1.31.0-next.32+7f51450b8",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "d3f6359934d025781810c467e2f3b42b55f0ff0d"
+  "gitHead": "7f51450b88967fe2f96f4f895357413bf311ad16"
 }

package/src/theia.d.ts

@@ -3009,6 +3009,11 @@ export module '@theia/plugin' {
          */
         readonly creationOptions: Readonly<TerminalOptions | ExtensionTerminalOptions>
 
+        /**
+         * The current state of the {@link Terminal}.
+         */
+        readonly state: TerminalState;
+
         /**
          * Send text to the terminal.
          * @param text - text content.
@@ -3033,6 +3038,24 @@ export module '@theia/plugin' {
         dispose(): void;
     }
 
+    export interface TerminalState {
+        /**
+         * Whether the {@link Terminal} has been interacted with. Interaction means that the
+         * terminal has sent data to the process which depending on the terminal's _mode_. By
+         * default input is sent when a key is pressed or when a command or extension sends text,
+         * but based on the terminal's mode it can also happen on:
+         *
+         * - a pointer click event
+         * - a pointer scroll event
+         * - a pointer move event
+         * - terminal focus in/out
+         *
+         * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on
+         * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+         */
+        readonly isInteractedWith: boolean;
+    }
+
     /**
      * Options to create terminal widget.
      */
@@ -3071,6 +3094,15 @@ export module '@theia/plugin' {
          */
         strictEnv?: boolean;
 
+        /**
+         * When enabled the terminal will run the process as normal but not be surfaced to the user
+         * until `Terminal.show` is called. The typical usage for this is when you need to run
+         * something that may need interactivity but only want to tell the user about it when
+         * interaction is needed. Note that the terminals will still be exposed to all extensions
+         * as normal.
+         */
+        hideFromUser?: boolean;
+
         /**
          * A message to write to the terminal on first launch. Note that this is not sent to the
          * process, but rather written directly to the terminal. This supports escape sequences such
@@ -3251,7 +3283,7 @@ export module '@theia/plugin' {
     /**
      * A link on a terminal line.
      */
-    export interface TerminalLink {
+    export class TerminalLink {
         /**
          * The start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line].
          */
@@ -3270,6 +3302,18 @@ export module '@theia/plugin' {
          * depending on OS, user settings, and localization.
          */
         tooltip?: string;
+
+        /**
+         * Creates a new terminal link.
+         * @param startIndex The start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line].
+         * @param length The length of the link on [TerminalLinkContext.line](#TerminalLinkContext.line].
+         * @param tooltip The tooltip text when you hover over this link.
+         *
+         * If a tooltip is provided, is will be displayed in a string that includes instructions on
+         * how to trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary
+         * depending on OS, user settings, and localization.
+         */
+        constructor(startIndex: number, length: number, tooltip?: string);
     }
 
     /**
@@ -4995,6 +5039,11 @@ export module '@theia/plugin' {
          */
         export const onDidOpenTerminal: Event<Terminal>;
 
+        /**
+         * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed.
+         */
+        export const onDidChangeTerminalState: Event<Terminal>;
+
         /**
          * Create new terminal with predefined options.
          * @param - terminal options.
@@ -5096,7 +5145,7 @@ export module '@theia/plugin' {
          * @param provider The provider that provides the terminal links.
          * @return Disposable that unregisters the provider.
          */
-        export function registerTerminalLinkProvider(provider: TerminalLinkProvider): void;
+        export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable;
 
         /**
          * Register a file decoration provider.
@@ -5537,6 +5586,29 @@ export module '@theia/plugin' {
          * @return Parent of `element`.
          */
         getParent?(element: T): ProviderResult<T>;
+
+        /**
+         * Called on hover to resolve the {@link TreeItem.tooltip TreeItem} property if it is undefined.
+         * Called on tree item click/open to resolve the {@link TreeItem.command TreeItem} property if it is undefined.
+         * Only properties that were undefined can be resolved in `resolveTreeItem`.
+         * Functionality may be expanded later to include being called to resolve other missing
+         * properties on selection and/or on open.
+         *
+         * Will only ever be called once per TreeItem.
+         *
+         * onDidChangeTreeData should not be triggered from within resolveTreeItem.
+         *
+         * *Note* that this function is called when tree items are already showing in the UI.
+         * Because of that, no property that changes the presentation (label, description, etc.)
+         * can be changed.
+         *
+         * @param item Undefined properties of `item` should be set then `item` should be returned.
+         * @param element The object associated with the TreeItem.
+         * @param token A cancellation token.
+         * @return The resolved tree item or a thenable that resolves to such. It is OK to return the given
+         * `item`. When no result is returned, the given `item` will be used.
+         */
+        resolveTreeItem?(item: TreeItem, element: T, token: CancellationToken): ProviderResult<TreeItem>;
     }
 
     export class TreeItem {
@@ -6812,6 +6884,18 @@ export module '@theia/plugin' {
         /**
          * A base file path to which this pattern will be matched against relatively.
          */
+        baseUri: Uri;
+
+        /**
+         * A base file path against which this pattern will be matched relatively.
+         *
+         * This matches the `fsPath` value of {@link RelativePattern.baseUri}.
+         *
+         * *Note:* updating this value will update {@link RelativePattern.baseUri} to
+         * be a uri with `file` scheme.
+         *
+         * @deprecated This property is deprecated, please use {@link RelativePattern.baseUri} instead.
+         */
         base: string;
 
         /**
@@ -6831,7 +6915,7 @@ export module '@theia/plugin' {
          * @param pattern A file glob pattern like `*.{ts,js}` that will be matched on file paths
          * relative to the base path.
          */
-        constructor(base: WorkspaceFolder | string, pattern: string)
+        constructor(base: WorkspaceFolder | Uri | string, pattern: string)
     }
 
     /**
@@ -7560,6 +7644,176 @@ export module '@theia/plugin' {
         provideColorPresentations(color: Color, context: { document: TextDocument, range: Range }, token: CancellationToken): ProviderResult<ColorPresentation[]>;
     }
 
+    /**
+     * Inlay hint kinds.
+     *
+     * The kind of an inline hint defines its appearance, e.g the corresponding foreground and background colors are being
+     * used.
+     */
+    export enum InlayHintKind {
+        /**
+         * An inlay hint that for a type annotation.
+         */
+        Type = 1,
+        /**
+         * An inlay hint that is for a parameter.
+         */
+        Parameter = 2,
+    }
+
+    /**
+     * An inlay hint label part allows for interactive and composite labels of inlay hints.
+     */
+    export class InlayHintLabelPart {
+
+        /**
+         * The value of this label part.
+         */
+        value: string;
+
+        /**
+         * The tooltip text when you hover over this label part.
+         *
+         * *Note* that this property can be set late during
+         * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
+         */
+        tooltip?: string | MarkdownString | undefined;
+
+        /**
+         * An optional {@link Location source code location} that represents this label
+         * part.
+         *
+         * The editor will use this location for the hover and for code navigation features: This
+         * part will become a clickable link that resolves to the definition of the symbol at the
+         * given location (not necessarily the location itself), it shows the hover that shows at
+         * the given location, and it shows a context menu with further code navigation commands.
+         *
+         * *Note* that this property can be set late during
+         * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
+         */
+        location?: Location | undefined;
+
+        /**
+         * An optional command for this label part.
+         *
+         * The editor renders parts with commands as clickable links. The command is added to the context menu
+         * when a label part defines {@link InlayHintLabelPart.location location} and {@link InlayHintLabelPart.command command} .
+         *
+         * *Note* that this property can be set late during
+         * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
+         */
+        command?: Command | undefined;
+
+        /**
+         * Creates a new inlay hint label part.
+         *
+         * @param value The value of the part.
+         */
+        constructor(value: string);
+    }
+
+    /**
+     * Inlay hint information.
+     */
+    export class InlayHint {
+
+        /**
+         * The position of this hint.
+         */
+        position: Position;
+
+        /**
+         * The label of this hint. A human readable string or an array of {@link InlayHintLabelPart label parts}.
+         *
+         * *Note* that neither the string nor the label part can be empty.
+         */
+        label: string | InlayHintLabelPart[];
+
+        /**
+         * The tooltip text when you hover over this item.
+         *
+         * *Note* that this property can be set late during
+         * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
+         */
+        tooltip?: string | MarkdownString | undefined;
+
+        /**
+         * The kind of this hint. The inlay hint kind defines the appearance of this inlay hint.
+         */
+        kind?: InlayHintKind;
+
+        /**
+         * Optional {@link TextEdit text edits} that are performed when accepting this inlay hint. The default
+         * gesture for accepting an inlay hint is the double click.
+         *
+         * *Note* that edits are expected to change the document so that the inlay hint (or its nearest variant) is
+         * now part of the document and the inlay hint itself is now obsolete.
+         *
+         * *Note* that this property can be set late during
+         * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
+         */
+        textEdits?: TextEdit[];
+
+        /**
+         * Render padding before the hint. Padding will use the editor's background color,
+         * not the background color of the hint itself. That means padding can be used to visually
+         * align/separate an inlay hint.
+         */
+        paddingLeft?: boolean;
+
+        /**
+         * Render padding after the hint. Padding will use the editor's background color,
+         * not the background color of the hint itself. That means padding can be used to visually
+         * align/separate an inlay hint.
+         */
+        paddingRight?: boolean;
+
+        /**
+         * Creates a new inlay hint.
+         *
+         * @param position The position of the hint.
+         * @param label The label of the hint.
+         * @param kind The {@link InlayHintKind kind} of the hint.
+         */
+        constructor(position: Position, label: string | InlayHintLabelPart[], kind?: InlayHintKind);
+    }
+
+    /**
+     * The inlay hints provider interface defines the contract between extensions and
+     * the inlay hints feature.
+     */
+    export interface InlayHintsProvider<T extends InlayHint = InlayHint> {
+
+        /**
+         * An optional event to signal that inlay hints from this provider have changed.
+         */
+        onDidChangeInlayHints?: Event<void>;
+
+        /**
+         * Provide inlay hints for the given range and document.
+         *
+         * *Note* that inlay hints that are not {@link Range.contains contained} by the given range are ignored.
+         *
+         * @param document The document in which the command was invoked.
+         * @param range The range for which inlay hints should be computed.
+         * @param token A cancellation token.
+         * @return An array of inlay hints or a thenable that resolves to such.
+         */
+        provideInlayHints(document: TextDocument, range: Range, token: CancellationToken): ProviderResult<T[]>;
+
+        /**
+         * Given an inlay hint fill in {@link InlayHint.tooltip tooltip}, {@link InlayHint.textEdits text edits},
+         * or complete label {@link InlayHintLabelPart parts}.
+         *
+         * *Note* that the editor will resolve an inlay hint at most once.
+         *
+         * @param hint An inlay hint.
+         * @param token A cancellation token.
+         * @return The resolved inlay hint or a thenable that resolves to such. It is OK to return the given `item`. When no result is returned, the given `item` will be used.
+         */
+        resolveInlayHint?(hint: T, token: CancellationToken): ProviderResult<T>;
+    }
+
     /**
      * A line based folding range. To be valid, start and end line must a zero or larger and smaller than the number of lines in the document.
      * Invalid ranges will be ignored.
@@ -9466,6 +9720,21 @@ export module '@theia/plugin' {
          */
         export function registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable;
 
+        /**
+         * Register a provider that returns data for the debugger's 'inline value' feature.
+         * Whenever the generic debugger has stopped in a source file, providers registered for the language of the file
+         * are called to return textual data that will be shown in the editor at the end of lines.
+         *
+         * Multiple providers can be registered for a language. In that case providers are asked in
+         * parallel and the results are merged. A failing provider (rejected promise or exception) will
+         * not cause a failure of the whole operation.
+         *
+         * @param selector A selector that defines the documents this provider is applicable to.
+         * @param provider An inline values provider.
+         * @return A {@link Disposable} that unregisters this provider when being disposed.
+         */
+        export function registerInlineValuesProvider(selector: DocumentSelector, provider: InlineValuesProvider): Disposable;
+
         /**
          * Register a workspace symbol provider.
          *
@@ -9622,6 +9891,19 @@ export module '@theia/plugin' {
          */
         export function registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable;
 
+        /**
+         * Register a inlay hints provider.
+         *
+         * Multiple providers can be registered for a language. In that case providers are asked in
+         * parallel and the results are merged. A failing provider (rejected promise or exception) will
+         * not cause a failure of the whole operation.
+         *
+         * @param selector A selector that defines the documents this provider is applicable to.
+         * @param provider An inlay hints provider.
+         * @return A {@link Disposable} that unregisters this provider when being disposed.
+         */
+        export function registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider): Disposable;
+
         /**
          * Register a folding range provider.
          *
@@ -9827,6 +10109,134 @@ export module '@theia/plugin' {
         provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken | undefined): ProviderResult<EvaluatableExpression>;
     }
 
+    /**
+     * Provide inline value as text.
+     */
+    export class InlineValueText {
+        /**
+         * The document range for which the inline value applies.
+         */
+        readonly range: Range;
+        /**
+         * The text of the inline value.
+         */
+        readonly text: string;
+        /**
+         * Creates a new InlineValueText object.
+         *
+         * @param range The document line where to show the inline value.
+         * @param text The value to be shown for the line.
+         */
+        constructor(range: Range, text: string);
+    }
+
+    /**
+     * Provide inline value through a variable lookup.
+     * If only a range is specified, the variable name will be extracted from the underlying document.
+     * An optional variable name can be used to override the extracted name.
+     */
+    export class InlineValueVariableLookup {
+        /**
+         * The document range for which the inline value applies.
+         * The range is used to extract the variable name from the underlying document.
+         */
+        readonly range: Range;
+        /**
+         * If specified the name of the variable to look up.
+         */
+        readonly variableName?: string | undefined;
+        /**
+         * How to perform the lookup.
+         */
+        readonly caseSensitiveLookup: boolean;
+        /**
+         * Creates a new InlineValueVariableLookup object.
+         *
+         * @param range The document line where to show the inline value.
+         * @param variableName The name of the variable to look up.
+         * @param caseSensitiveLookup How to perform the lookup. If missing lookup is case sensitive.
+         */
+        constructor(range: Range, variableName?: string, caseSensitiveLookup?: boolean);
+    }
+
+    /**
+     * Provide an inline value through an expression evaluation.
+     * If only a range is specified, the expression will be extracted from the underlying document.
+     * An optional expression can be used to override the extracted expression.
+     */
+    export class InlineValueEvaluatableExpression {
+        /**
+         * The document range for which the inline value applies.
+         * The range is used to extract the evaluatable expression from the underlying document.
+         */
+        readonly range: Range;
+        /**
+         * If specified the expression overrides the extracted expression.
+         */
+        readonly expression?: string | undefined;
+        /**
+         * Creates a new InlineValueEvaluatableExpression object.
+         *
+         * @param range The range in the underlying document from which the evaluatable expression is extracted.
+         * @param expression If specified overrides the extracted expression.
+         */
+        constructor(range: Range, expression?: string);
+    }
+
+    /**
+     * Inline value information can be provided by different means:
+     * - directly as a text value (class InlineValueText).
+     * - as a name to use for a variable lookup (class InlineValueVariableLookup)
+     * - as an evaluatable expression (class InlineValueEvaluatableExpression)
+     * The InlineValue types combines all inline value types into one type.
+     */
+    export type InlineValue = InlineValueText | InlineValueVariableLookup | InlineValueEvaluatableExpression;
+
+    /**
+     * A value-object that contains contextual information when requesting inline values from a InlineValuesProvider.
+     */
+    export interface InlineValueContext {
+
+        /**
+         * The stack frame (as a DAP Id) where the execution has stopped.
+         */
+        readonly frameId: number;
+
+        /**
+         * The document range where execution has stopped.
+         * Typically the end position of the range denotes the line where the inline values are shown.
+         */
+        readonly stoppedLocation: Range;
+    }
+
+    /**
+     * The inline values provider interface defines the contract between extensions and the editor's debugger inline values feature.
+     * In this contract the provider returns inline value information for a given document range
+     * and the editor shows this information in the editor at the end of lines.
+     */
+    export interface InlineValuesProvider {
+
+        /**
+         * An optional event to signal that inline values have changed.
+         * @see {@link EventEmitter}
+         */
+        onDidChangeInlineValues?: Event<void> | undefined;
+
+        /**
+         * Provide "inline value" information for a given document and range.
+         * The editor calls this method whenever debugging stops in the given document.
+         * The returned inline values information is rendered in the editor at the end of lines.
+         *
+         * @param document The document for which the inline values information is needed.
+         * @param viewPort The visible document range for which inline values should be computed.
+         * @param context A bag containing contextual information like the current location.
+         * @param token A cancellation token.
+         * @return An array of InlineValueDescriptors or a thenable that resolves to such. The lack of a result can be
+         * signaled by returning `undefined` or `null`.
+         */
+        provideInlineValues(document: TextDocument, viewPort: Range, context: InlineValueContext, token: CancellationToken): ProviderResult<InlineValue[]>;
+    }
+
     /**
      * A document highlight kind.
      */