diff --git a/packages/plugin-ext/src/plugin/plugin-context.ts b/packages/plugin-ext/src/plugin/plugin-context.ts index 0732766ebafb9..ed40e7f6b46ae 100644 --- a/packages/plugin-ext/src/plugin/plugin-context.ts +++ b/packages/plugin-ext/src/plugin/plugin-context.ts @@ -786,16 +786,16 @@ export function createAPIFactory( } }; - const comment: typeof theia.comment = { + const comments: typeof theia.comments = { createCommentController(id: string, label: string): theia.CommentController { + // TODO replace the dummy implementation, see https://github.com/eclipse-theia/theia/issues/8492 return { - id, label, inputBox: undefined, - createCommentThread(commentId: string, resource: Uri, range: Range, comments: theia.Comment[]): theia.CommentThread { + id, label, + createCommentThread(uri: Uri, range: Range, commentsArray: theia.Comment[]): theia.CommentThread { return { - id: commentId, - resource, + uri, range, - comments, + comments: commentsArray, collapsibleState: 0, dispose(): void { } @@ -811,7 +811,7 @@ export function createAPIFactory( version: require('../../package.json').version, authentication, commands, - comment, + comments, window, workspace, env, diff --git a/packages/plugin/src/theia.d.ts b/packages/plugin/src/theia.d.ts index c98a4ad227002..f7f32a46bb914 100644 --- a/packages/plugin/src/theia.d.ts +++ b/packages/plugin/src/theia.d.ts @@ -9230,6 +9230,8 @@ declare module '@theia/plugin' { resolveWorkspaceSymbol?(symbol: SymbolInformation, token: CancellationToken | undefined): ProviderResult; } + //#region Comments + /** * Collapsible state of a [comment thread](#CommentThread) */ @@ -9264,26 +9266,21 @@ declare module '@theia/plugin' { * 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; + readonly uri: 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; + range: Range; /** * The ordered comments of the thread. */ - comments: Comment[]; + comments: ReadonlyArray; /** * Whether the thread should be collapsed or expanded when opening the document. @@ -9292,242 +9289,221 @@ declare module '@theia/plugin' { 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. + * Context value of the comment thread. This can be used to contribute thread specific actions. + * For example, a comment thread is given a context value as `editable`. When contributing actions to `comments/commentThread/title` + * using `menus` extension point, you can specify context value for key `commentThread` in `when` expression like `commentThread == editable`. + * ``` + * "contributes": { + * "menus": { + * "comments/commentThread/title": [ + * { + * "command": "extension.deleteCommentThread", + * "when": "commentThread == editable" + * } + * ] + * } + * } + * ``` + * This will show action `extension.deleteCommentThread` only for comment threads with `contextValue` is `editable`. */ - additionalCommands?: Command[]; + contextValue?: string; /** - * 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. + * The optional human-readable label describing the [Comment Thread](#CommentThread) */ - deleteCommand?: Command; + label?: string; /** * Dispose this comment thread. * - * Once disposed, this comment thread will be removed from visible editors and Comment Panel when approriate. + * Once disposed, this comment thread will be removed from visible editors and Comment Panel when appropriate. */ dispose(): void; } /** - * Commenting range provider for a [comment controller](#CommentController). + * Author information of a [comment](#Comment) */ - export interface CommentingRangeProvider { + export interface CommentAuthorInformation { /** - * Provide a list of ranges which allow new comment threads creation or null for a given document + * The display name of the author of the comment */ - provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult; + name: string; + + /** + * The optional icon path for the author + */ + iconPath?: Uri; } /** - * Comment thread template for new comment thread creation. + * Reactions of a [comment](#Comment) */ - export interface CommentThreadTemplate { + export interface CommentReaction { /** - * The human-readable label describing the [Comment Thread](#CommentThread) + * The human-readable label for the reaction */ 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 + * Icon for the reaction shown in UI. */ - value: string; + readonly iconPath: string | Uri; /** - * The uri of the document comment input box has been created on + * The number of users who have reacted to this reaction */ - resource: Uri; + readonly count: number; /** - * The range the comment input box is located within the document + * Whether the [author](CommentAuthorInformation) of the comment has reacted to this reaction */ - range: Range; + readonly authorHasReacted: boolean; } /** - * A comment controller is able to provide [comments](#CommentThread) support to the editor and - * provide users various ways to interact with comments. + * A comment is displayed within the editor or the Comments Panel, depending on how it is provided. */ - export interface CommentController { - /** - * The id of this comment controller. - */ - readonly id: string; - + export interface Comment { /** - * The human-readable label of this comment controller. + * The human-readable comment body */ - readonly label: string; + body: string | MarkdownString; /** - * 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. + * [Comment mode](#CommentMode) of the comment */ - readonly inputBox: CommentInputBox | undefined; + mode: CommentMode; /** - * 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. + * The [author information](#CommentAuthorInformation) of the comment */ - template?: CommentThreadTemplate; + author: CommentAuthorInformation; /** - * 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. + * Context value of the comment. This can be used to contribute comment specific actions. + * For example, a comment is given a context value as `editable`. When contributing actions to `comments/comment/title` + * using `menus` extension point, you can specify context value for key `comment` in `when` expression like `comment == editable`. + * ```json + * "contributes": { + * "menus": { + * "comments/comment/title": [ + * { + * "command": "extension.deleteComment", + * "when": "comment == editable" + * } + * ] + * } + * } + * ``` + * This will show action `extension.deleteComment` only for comments with `contextValue` is `editable`. */ - commentingRangeProvider?: CommentingRangeProvider; + contextValue?: string; /** - * 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. + * Optional reactions of the [comment](#Comment) */ - createCommentThread(id: string, resource: Uri, range: Range, comments: Comment[]): CommentThread; + reactions?: CommentReaction[]; /** - * 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. + * Optional label describing the [Comment](#Comment) + * Label will be rendered next to authorName if exists. */ - dispose(): void; + label?: string; } /** - * Author information of a [comment](#Comment) + * Command argument for actions registered in `comments/commentThread/context`. */ - export interface CommentAuthorInformation { + export interface CommentReply { /** - * The display name of the author of the comment + * The active [comment thread](#CommentThread) */ - name: string; + thread: CommentThread; /** - * The optional icon path for the author + * The value in the comment editor */ - iconPath?: Uri; + text: string; } /** - * Reactions of a [comment](#Comment) + * Commenting range provider for a [comment controller](#CommentController). */ - export interface CommentReaction { - /** - * The human-readable label for the reaction - */ - readonly label: string; - + export interface CommentingRangeProvider { /** - * Icon for the reaction shown in UI. + * Provide a list of ranges which allow new comment threads creation or null for a given document */ - readonly iconPath: string | Uri; + provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult; + } + /** + * Represents a [comment controller](#CommentController)'s [options](#CommentController.options). + */ + export interface CommentOptions { /** - * The number of users who have reacted to this reaction + * An optional string to show on the comment input box when it's collapsed. */ - readonly count: number; + prompt?: string; /** - * Whether the [author](CommentAuthorInformation) of the comment has reacted to this reaction + * An optional string to show as placeholder in the comment input box when it's focused. */ - readonly authorHasReacted: boolean; + placeHolder?: string; } /** - * A comment is displayed within the editor or the Comments Panel, depending on how it is provided. + * A comment controller is able to provide [comments](#CommentThread) support to the editor and + * provide users various ways to interact with comments. */ - export interface Comment { + export interface CommentController { /** - * The human-readable comment body + * The id of this comment controller. */ - body: string | MarkdownString; + readonly id: string; /** - * [Comment mode](#CommentMode) of the comment + * The human-readable label of this comment controller. */ - mode: CommentMode; + readonly label: string; /** - * The [author information](#CommentAuthorInformation) of the comment + * Comment controller options */ - author: CommentAuthorInformation; + options?: CommentOptions; /** - * Context value of the comment. This can be used to contribute comment specific actions. - * For example, a comment is given a context value as `editable`. When contributing actions to `comments/comment/title` - * using `menus` extension point, you can specify context value for key `comment` in `when` expression like `comment == editable`. + * Optional commenting range provider. Provide a list [ranges](#Range) which support commenting to any given resource uri. + * + * If not provided, users can leave comments in any document opened in the editor. */ - contextValue?: string; + commentingRangeProvider?: CommentingRangeProvider; /** - * Optional reactions of the [comment](#Comment) + * 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 uri 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. */ - reactions?: CommentReaction[]; + createCommentThread(uri: Uri, range: Range, comments: Comment[]): CommentThread; /** - * Optional label describing the [Comment](#Comment) - * Label will be rendered next to authorName if exists. + * Optional reaction handler for creating and deleting reactions on a [comment](#Comment). */ - label?: string; + reactionHandler?: (comment: Comment, reaction: CommentReaction) => Promise; + + /** + * 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 { + namespace comments { /** * Creates a new [comment controller](#CommentController) instance. * @@ -9538,6 +9514,8 @@ declare module '@theia/plugin' { export function createCommentController(id: string, label: string): CommentController; } + //#endregion + /** * A selection range represents a part of a selection hierarchy. A selection range * may have a parent selection range that contains it.