Comments API Sample (#160)

* Comment API Sample

.scripts/samples.js

@@ -176,6 +176,13 @@ const lspSamples = [
       'TextDocumentContentProvider'
     ],
     contributions: ["menus"]
+  },
+  {
+    description: 'Commenting API Sample',
+    path: 'comment-sample',
+    guide: null,
+    apis: [],
+    contributions: []
   }
 ]
 

comment-sample/.vscode/launch.json

@@ -0,0 +1,22 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Extension",
+            "type": "extensionHost",
+            "request": "launch",
+            "runtimeExecutable": "${execPath}",
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/out/**/*.js"
+            ],
+            "preLaunchTask": "npm: watch"
+        }
+    ]
+}

comment-sample/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"editor.insertSpaces": false
+}

comment-sample/.vscode/tasks.json

@@ -0,0 +1,20 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "type": "npm",
+            "script": "watch",
+            "problemMatcher": "$tsc-watch",
+            "isBackground": true,
+            "presentation": {
+                "reveal": "never"
+            },
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

comment-sample/README.md

@@ -0,0 +1,9 @@
+# Commenting API Example
+
+This sample shows
+
+- How to create a comment controller.
+- How to support comment thread creation for documents.
+- How to update comment actions dynamically.
+
+![demo](./wiki-demo.gif)

comment-sample/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "vscode-terminal-api-example",
+	"displayName": "vscode-terminal-api-example",
+	"description": "abc",
+	"version": "0.0.1",
+	"publisher": "vscode-samples",
+	"engines": {
+		"vscode": "^1.32.0"
+	},
+	"enableProposedApi": true,
+	"categories": [
+		"Other"
+	],
+	"activationEvents": [
+		"*"
+	],
+	"main": "./out/extension.js",
+	"contributes": {
+		"commands": [
+			{
+				"command": "mywiki.createNote",
+				"title": "Comment API: Create a comment thread"
+			},
+			{
+				"command": "mywiki.createComment",
+				"title": "Comment API: Reply to a comment thread"
+			},
+			{
+				"command": "mywiki.deleteNote",
+				"title": "Comment API: Delete a comment thread"
+			}
+		],
+		"menus": {
+			"commandPalette": [
+				{
+					"command": "mywiki.createNote",
+					"when": "false"
+				},
+				{
+					"command": "mywiki.createComment",
+					"when": "false"
+				},
+				{
+					"command": "mywiki.deleteNote",
+					"when": "false"
+				}
+			]
+		}
+	},
+	"scripts": {
+		"vscode:prepublish": "npm run compile",
+		"compile": "tsc -p ./",
+		"lint": "tslint ./src/*.ts",
+		"watch": "tsc -watch -p ./",
+		"postinstall": "node ./node_modules/vscode/bin/install",
+		"test": "npm run compile && node ./node_modules/vscode/bin/test"
+	},
+	"devDependencies": {
+		"@types/node": "^6.0.40",
+		"tslint": "^5.11.0",
+		"typescript": "^2.0.3",
+		"vscode": "^1.1.22"
+	}
+}

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
+}

comment-sample/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"target": "es6",
+		"outDir": "out",
+		"lib": ["es6"],
+		"sourceMap": true,
+		"rootDir": "src"
+	},
+	"exclude": ["node_modules", ".vscode-test"]
+}

comment-sample/tslint.json

@@ -0,0 +1,6 @@
+{
+	"rules": {
+		"indent": [true, "tabs"],
+		"semicolon": [true, "always"]
+	}
+}