Comments API Sample (#160)

* Comment API Sample

comment-sample/src/extension.ts

@@ -0,0 +1,93 @@
+'use strict';
+
+import * as vscode from 'vscode';
+
+let threadId = 0;
+let commentId = 0;
+
+export function activate(context: vscode.ExtensionContext) {
+	// A `CommentController` is able to provide comments for documents.
+	const commentController = vscode.comment.createCommentController('comment-sample', 'Comment API Sample');
+	context.subscriptions.push(commentController);
+
+	// commenting range provider
+	commentController.commentingRangeProvider = {
+		provideCommentingRanges: (document: vscode.TextDocument, token: vscode.CancellationToken) => {
+			let lineCount = document.lineCount;
+			return [new vscode.Range(0, 0, lineCount - 1, 0)];
+		}
+	};
+
+	// callback when users click `+` button on Gutter or run Create Comment command from Command Palette
+	commentController.emptyCommentThreadFactory = {
+		createEmptyCommentThread: (document: vscode.TextDocument, range: vscode.Range) => {
+		// create a empty thread
+			let thread = commentController.createCommentThread(`${++threadId}`, document.uri, range, []);
+			// by default, a comment thread is collapsed, for newly created empty comment thread, we want to expand it and users can start commenting immediately
+			thread.collapsibleState = vscode.CommentThreadCollapsibleState.Expanded;
+
+			// In this example, we call it `Create New Note` while for GH PR case, we can call it `Start Review` or `Start New Converstation`
+			thread.label = 'Create New Note';
+
+			// We will render all `acceptInputCommands` as Actions on the bottom of Comment Widget in the editor.
+			thread.acceptInputCommand = {
+				title: 'Create Note',
+				command: 'mywiki.createNote',
+				// Command is responsible for arguments
+				arguments: [
+					commentController,
+					thread
+				]
+			};
+
+			thread.deleteCommand = {
+				title: 'Delete Note',
+				command: 'mywiki.deleteNote',
+				arguments: [
+					thread
+				]
+			};
+		}
+	};
+
+	// register `mywiki.createNote` command
+	context.subscriptions.push(vscode.commands.registerCommand('mywiki.createNote', (commentController: vscode.CommentController, thread: vscode.CommentThread) => {
+		if (commentController.inputBox) {
+			// Read text from the focused textarea in the Comment Widget.
+			let text = commentController.inputBox.value;
+			let markedString = new vscode.MarkdownString(text);
+			let newComment: vscode.Comment = { commentId: `${++commentId}`, body: markedString, userName: 'vscode' };
+
+			thread.comments = [newComment];
+			thread.label = 'Participants: vscode';
+
+			// After we create the new comment thread, we may want to update the actions on the Comment Widget.
+			thread.acceptInputCommand = {
+				title: 'Create Comment',
+				command: 'mywiki.createComment',
+				arguments: [
+					commentController,
+					thread
+				]
+			};
+
+			// Lastly, we want to clear the textarea in Comment Widget.
+			commentController.inputBox.value = '';
+		}
+	}));
+
+	context.subscriptions.push(vscode.commands.registerCommand('mywiki.createComment', (commentController: vscode.CommentController, thread: vscode.CommentThread) => {
+		if (commentController.inputBox) {
+			let text = commentController.inputBox.value;
+			let markedString = new vscode.MarkdownString(text);
+			let newComment: vscode.Comment = { commentId: `${++commentId}`, body: markedString, userName: 'vscode' };
+
+			thread.comments = [...thread.comments, newComment];
+			commentController.inputBox.value = '';
+		}
+	}));
+
+	context.subscriptions.push(vscode.commands.registerCommand('mywiki.deleteNote', (thread: vscode.CommentThread) => {
+		thread.dispose();
+	}));
+}

comment-sample/src/typings/vscode.proposed.d.ts

@@ -0,0 +1,211 @@
+import { Range } from "vscode";
+
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * This is the place for API experiments and proposals.
+ * These API are NOT stable and subject to change. They are only available in the Insiders
+ * distribution and CANNOT be used in published extensions.
+ *
+ * To test these API in local environment:
+ * - Use Insiders release of VS Code.
+ * - Add `"enableProposedApi": true` to your package.json.
+ * - Copy this file to your project.
+ */
+
+declare module 'vscode' {
+	export enum CommentThreadCollapsibleState {
+		/**
+		 * Determines an item is collapsed
+		 */
+		Collapsed = 0,
+		/**
+		 * Determines an item is expanded
+		 */
+		Expanded = 1
+	}
+
+	/**
+	 * A collection of comments representing a conversation at a particular range in a document.
+	 */
+	export interface CommentThread {
+		/**
+		 * A unique identifier of the comment thread.
+		 */
+		threadId: string;
+
+		/**
+		 * The uri of the document the thread has been created on.
+		 */
+		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.
+		 */
+		range: Range;
+
+		/**
+		 * The human-readable label describing the [Comment Thread](#CommentThread)
+		 */
+		label?: string;
+
+		/**
+		 * The ordered comments of the thread.
+		 */
+		comments: Comment[];
+
+		/**
+		 * 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[];
+
+		/**
+		 * Whether the thread should be collapsed or expanded when opening the document.
+		 * Defaults to Collapsed.
+		 */
+		collapsibleState?: CommentThreadCollapsibleState;
+
+		/**
+		 * 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, the comment thread will be removed from visible text editors and Comments Panel.
+		 */
+		dispose?(): void;
+	}
+
+	/**
+	 * A comment is displayed within the editor or the Comments Panel, depending on how it is provided.
+	 */
+	export interface Comment {
+		/**
+		 * The id of the comment
+		 */
+		commentId: string;
+
+		/**
+		 * The text of the comment
+		 */
+		body: MarkdownString;
+
+		/**
+		 * Optional label describing the [Comment](#Comment)
+		 * Label will be rendered next to userName if exists.
+		 */
+		label?: string;
+
+		/**
+		 * The display name of the user who created the comment
+		 */
+		userName: string;
+
+		/**
+		 * The icon path for the user who created the comment
+		 */
+		userIconPath?: Uri;
+
+		/**
+		 * The command to be executed if the comment is selected in the Comments Panel
+		 */
+		selectCommand?: Command;
+
+		/**
+		 * The command to be executed when users try to save the edits to the comment
+		 */
+		editCommand?: Command;
+
+		/**
+		 * The command to be executed when users try to delete the comment
+		 */
+		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;
+	}
+
+	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[]>;
+	}
+
+	export interface EmptyCommentThreadFactory {
+		/**
+		 * The method `createEmptyCommentThread` is called when users attempt to create new comment thread from the gutter or command palette.
+		 * Extensions still need to call `createCommentThread` inside this call when appropriate.
+		 */
+		createEmptyCommentThread(document: TextDocument, range: Range): ProviderResult<void>;
+	}
+
+	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 (focused) [comment input box](#CommentInputBox).
+		 */
+		readonly inputBox?: CommentInputBox;
+
+		/**
+		 * Create a [CommentThread](#CommentThread)
+		 */
+		createCommentThread(id: string, resource: Uri, range: Range, comments: Comment[]): CommentThread;
+
+		/**
+		 * Optional commenting range provider.
+		 * Provide a list [ranges](#Range) which support commenting to any given resource uri.
+		 */
+		commentingRangeProvider?: CommentingRangeProvider;
+
+		/**
+		 * Optional new comment thread factory.
+		 */
+		emptyCommentThreadFactory?: EmptyCommentThreadFactory;
+
+		/**
+		 * Dispose this comment controller.
+		 */
+		dispose(): void;
+	}
+
+	namespace comment {
+		export function createCommentController(id: string, label: string): CommentController;
+	}
+
+	//#endregion
+}