[Plugin-Api] Add stub comment Plugin-Api

Signed-off-by: Igor Vinokur <[email protected]>

packages/plugin-ext/src/plugin/plugin-context.ts

@@ -106,7 +106,8 @@ import {
     ColorPresentation,
     OperatingSystem,
     WebviewPanelTargetArea,
-    FileSystemError
+    FileSystemError,
+    CommentThreadCollapsibleState
 } from './types-impl';
 import { SymbolKind } from '../api/model';
 import { EditorsAndDocumentsExtImpl } from './editors-and-documents';
@@ -696,9 +697,31 @@ export function createAPIFactory(
             }
         };
 
+        const comment: typeof theia.comment = {
+            createCommentController(id: string, label: string): theia.CommentController {
+                return {
+                    id, label, inputBox: undefined,
+                    createCommentThread(commentId: string, resource: Uri, range: Range, comments: Comment[]): theia.CommentThread {
+                        return {
+                            id: commentId,
+                            resource,
+                            range,
+                            comments,
+                            collapsibleState: 0,
+                            dispose(): void {
+                            }
+                        };
+                    },
+                    dispose(): void {
+                    }
+                };
+            }
+        };
+
         return <typeof theia>{
             version: require('../../package.json').version,
             commands,
+            comment,
             window,
             workspace,
             env,
@@ -785,7 +808,8 @@ export function createAPIFactory(
             FoldingRangeKind,
             OperatingSystem,
             WebviewPanelTargetArea,
-            FileSystemError
+            FileSystemError,
+            CommentThreadCollapsibleState
         };
     };
 }

packages/plugin-ext/src/plugin/types-impl.ts

@@ -1226,6 +1226,11 @@ export enum FileChangeType {
     Deleted = 3,
 }
 
+export enum CommentThreadCollapsibleState {
+    Collapsed = 0,
+    Expanded = 1
+}
+
 export class FileSystemError extends Error {
 
     static FileExists(messageOrUri?: string | URI): FileSystemError {

packages/plugin/src/theia.d.ts

@@ -8115,4 +8115,219 @@ declare module '@theia/plugin' {
          */
         resolveWorkspaceSymbol?(symbol: SymbolInformation, token: CancellationToken | undefined): ProviderResult<SymbolInformation>;
     }
+
+    /**
+     * Collapsible state of a [comment thread](#CommentThread)
+     */
+    export enum CommentThreadCollapsibleState {
+        /**
+         * Determines an item is collapsed
+         */
+        Collapsed = 0,
+
+        /**
+         * Determines an item is expanded
+         */
+        Expanded = 1
+    }
+
+    /**
+     * A collection of [comments](#Comment) representing a conversation at a particular range in a document.
+     */
+    export interface CommentThread {
+        /**
+         * A unique identifier of the comment thread.
+         */
+        readonly id: string;
+
+        /**
+         * The uri of the document the thread has been created on.
+         */
+        readonly resource: Uri;
+
+        /**
+         * The range the comment thread is located within the document. The thread icon will be shown
+         * at the first line of the range.
+         */
+        readonly range: Range;
+
+        /**
+         * The ordered comments of the thread.
+         */
+        comments: Comment[];
+
+        /**
+         * Whether the thread should be collapsed or expanded when opening the document.
+         * Defaults to Collapsed.
+         */
+        collapsibleState: CommentThreadCollapsibleState;
+
+        /**
+         * The optional human-readable label describing the [Comment Thread](#CommentThread)
+         */
+        label?: string;
+
+        /**
+         * Optional accept input command
+         *
+         * `acceptInputCommand` is the default action rendered on Comment Widget, which is always placed rightmost.
+         * This command will be invoked when users the user accepts the value in the comment editor.
+         * This command will disabled when the comment editor is empty.
+         */
+        acceptInputCommand?: Command;
+
+        /**
+         * Optional additonal commands.
+         *
+         * `additionalCommands` are the secondary actions rendered on Comment Widget.
+         */
+        additionalCommands?: Command[];
+
+        /**
+         * The command to be executed when users try to delete the comment thread. Currently, this is only called
+         * when the user collapses a comment thread that has no comments in it.
+         */
+        deleteCommand?: Command;
+
+        /**
+         * Dispose this comment thread.
+         *
+         * Once disposed, this comment thread will be removed from visible editors and Comment Panel when approriate.
+         */
+        dispose(): void;
+    }
+
+    /**
+     * Commenting range provider for a [comment controller](#CommentController).
+     */
+    export interface CommentingRangeProvider {
+        /**
+         * Provide a list of ranges which allow new comment threads creation or null for a given document
+         */
+        provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[]>;
+    }
+
+    /**
+     * Comment thread template for new comment thread creation.
+     */
+    export interface CommentThreadTemplate {
+        /**
+         * The human-readable label describing the [Comment Thread](#CommentThread)
+         */
+        readonly label: string;
+
+        /**
+         * Optional accept input command
+         *
+         * `acceptInputCommand` is the default action rendered on Comment Widget, which is always placed rightmost.
+         * This command will be invoked when users the user accepts the value in the comment editor.
+         * This command will disabled when the comment editor is empty.
+         */
+        readonly acceptInputCommand?: Command;
+
+        /**
+         * Optional additonal commands.
+         *
+         * `additionalCommands` are the secondary actions rendered on Comment Widget.
+         */
+        readonly additionalCommands?: Command[];
+
+        /**
+         * The command to be executed when users try to delete the comment thread. Currently, this is only called
+         * when the user collapses a comment thread that has no comments in it.
+         */
+        readonly deleteCommand?: Command;
+    }
+
+    /**
+     * The comment input box in Comment Widget.
+     */
+    export interface CommentInputBox {
+        /**
+         * Setter and getter for the contents of the comment input box
+         */
+        value: string;
+
+        /**
+         * The uri of the document comment input box has been created on
+         */
+        resource: Uri;
+
+        /**
+         * The range the comment input box is located within the document
+         */
+        range: Range;
+    }
+
+    /**
+     * A comment controller is able to provide [comments](#CommentThread) support to the editor and
+     * provide users various ways to interact with comments.
+     */
+    export interface CommentController {
+        /**
+         * The id of this comment controller.
+         */
+        readonly id: string;
+
+        /**
+         * The human-readable label of this comment controller.
+         */
+        readonly label: string;
+
+        /**
+         * The active [comment input box](#CommentInputBox) or `undefined`. The active `inputBox` is the input box of
+         * the comment thread widget that currently has focus. It's `undefined` when the focus is not in any CommentInputBox.
+         */
+        readonly inputBox: CommentInputBox | undefined;
+
+        /**
+         * Optional comment thread template information.
+         *
+         * The comment controller will use this information to create the comment widget when users attempt to create new comment thread
+         * from the gutter or command palette.
+         *
+         * When users run `CommentThreadTemplate.acceptInputCommand` or `CommentThreadTemplate.additionalCommands`, extensions should create
+         * the approriate [CommentThread](#CommentThread).
+         *
+         * If not provided, users won't be able to create new comment threads in the editor.
+         */
+        template?: CommentThreadTemplate;
+
+        /**
+         * Optional commenting range provider. Provide a list [ranges](#Range) which support commenting to any given resource uri.
+         *
+         * If not provided and `emptyCommentThreadFactory` exits, users can leave comments in any document opened in the editor.
+         */
+        commentingRangeProvider?: CommentingRangeProvider;
+
+        /**
+         * Create a [comment thread](#CommentThread). The comment thread will be displayed in visible text editors (if the resource matches)
+         * and Comments Panel once created.
+         *
+         * @param id An `id` for the comment thread.
+         * @param resource The uri of the document the thread has been created on.
+         * @param range The range the comment thread is located within the document.
+         * @param comments The ordered comments of the thread.
+         */
+        createCommentThread(id: string, resource: Uri, range: Range, comments: Comment[]): CommentThread;
+
+        /**
+         * Dispose this comment controller.
+         *
+         * Once disposed, all [comment threads](#CommentThread) created by this comment controller will also be removed from the editor
+         * and Comments Panel.
+         */
+        dispose(): void;
+    }
+
+    namespace comment {
+        /**
+         * Creates a new [comment controller](#CommentController) instance.
+         *
+         * @param id An `id` for the comment controller.
+         * @param label A human-readable string for the comment controller.
+         * @return An instance of [comment controller](#CommentController).
+         */
+        export function createCommentController(id: string, label: string): CommentController;
+    }
 }