[commands] add contribution types

modules/extensions/src/api/experimental/commands.ts

@@ -1,19 +1,5 @@
 import { extensionPort } from "../../util/comlink";
-import { CreateCommand, CommandProxy, Command } from "../../commands";
-
-export function register(command: CommandProxy): void {
-  extensionPort.experimental.commands.registerCommand(command);
-}
-
-export function registerCreate(
-  data: { commandId: string; contributions: Array<string> },
-  createCommand: CreateCommand
-): void {
-  extensionPort.experimental.commands.registerCreateCommand(
-    data,
-    createCommand
-  );
-}
+import { CreateCommand, CommandProxy, ContributionType } from "../../commands";
 
 export interface AddCommandArgs {
   /**
@@ -24,20 +10,53 @@ export interface AddCommandArgs {
   /**
    * The surfaces that this command should appear in. This is an array of strings
    */
-  contributions: Array<string>;
+  contributions: Array<ContributionType>;
 
   /**
    * A Command, or, a function that returns a Command.
    */
   command: CommandProxy | CreateCommand;
 }
 
+/**
+ * Adds a command to the command system.
+ *
+ * @param id The command's unique identifier. This is used to identify the command in Replit's command system
+ * @param contributions The surfaces that this command should appear in. This is an array of strings
+ * @param command A Command, or, a function that returns a Command.
+ */
 export function add({ id, contributions, command }: AddCommandArgs) {
   if (typeof command === "function") {
-    registerCreate({ commandId: id, contributions }, command);
+    extensionPort.experimental.commands.registerCreateCommand(
+      { commandId: id, contributions },
+      command
+    );
   } else {
-    registerCreate({ commandId: id, contributions }, async () => ({
-      ...command,
-    }));
+    extensionPort.experimental.commands.registerCreateCommand(
+      { commandId: id, contributions },
+      async () => ({
+        ...command,
+      })
+    );
   }
 }
+
+/**
+ * @deprecated Use `add` instead
+ */
+export function register(command: CommandProxy): void {
+  extensionPort.experimental.commands.registerCommand(command);
+}
+
+/**
+ * @deprecated Use `add` instead
+ */
+export function registerCreate(
+  data: { commandId: string; contributions: Array<string> },
+  createCommand: CreateCommand
+): void {
+  extensionPort.experimental.commands.registerCreateCommand(
+    data,
+    createCommand
+  );
+}

modules/extensions/src/commands/index.ts

@@ -1,5 +1,15 @@
 import { proxy } from "../util/comlink";
 
+/**
+ * Surfaces that a command can appear in.
+ */
+export enum ContributionType {
+  CommandBar = "commandbar",
+  FiletreeContextMenu = "filetree-context-menu",
+  SidebarSearch = "sidebar-search",
+  EditorContextMenu = "editor-context-menu",
+}
+
 export type CommandFnArgs = {
   /**
    * Whether the command is currently active. That is, the user has selected this command in the command bar.
@@ -16,7 +26,7 @@ export type CommandFnArgs = {
   /**
    * The current path. This is the path of commands that the user has selected in the command bar.
    *
-   * The first element of the array is the "root" which contains contextual information about the command. It varies depending on the contribution point.
+   * The first element of the array is the "root" which contains contextual information about the command. It varies depending on the surface.
    */
   path: SerializableValue[];
 };