Merge pull request #322 from fcollonval/ft/58-add-command-description

Add `describedBy` to command

Author: afshin

packages/commands/src/index.ts

@@ -151,6 +151,18 @@ export class CommandRegistry {
     this._commandChanged.emit({ id, type: id ? 'changed' : 'many-changed' });
   }
 
+  /**
+   * Get the description for a specific command.
+   *
+   * @param id - The id of the command of interest.
+   *
+   * @returns The description for the command.
+   */
+  describedBy(id: string): { args: ReadonlyJSONObject | null } {
+    let cmd = this._commands[id];
+    return cmd?.describedBy ?? { args: null };
+  }
+
   /**
    * Get the display label for a specific command.
    *
@@ -685,6 +697,15 @@ export namespace CommandRegistry {
      */
     execute: CommandFunc<any | Promise<any>>;
 
+    /**
+     * JSON Schemas describing the command.
+     *
+     * #### Notes
+     * For now, the command arguments are the only one that can be
+     * described.
+     */
+    describedBy?: { args?: ReadonlyJSONObject };
+
     /**
      * The label for the command.
      *
@@ -1242,6 +1263,7 @@ namespace Private {
    */
   export interface ICommand {
     readonly execute: CommandFunc<any>;
+    readonly describedBy: { args: ReadonlyJSONObject | null };
     readonly label: CommandFunc<string>;
     readonly mnemonic: CommandFunc<number>;
     readonly icon: CommandFunc<VirtualElement.IRenderer | undefined>;
@@ -1265,6 +1287,7 @@ namespace Private {
   ): ICommand {
     return {
       execute: options.execute,
+      describedBy: { args: null, ...options.describedBy },
       label: asFunc(options.label, emptyStringFunc),
       mnemonic: asFunc(options.mnemonic, negativeOneFunc),
       icon: asFunc(options.icon, undefinedFunc),

packages/commands/tests/src/index.spec.ts

@@ -328,6 +328,35 @@ describe('@lumino/commands', () => {
       });
     });
 
+    describe('#describedBy()', () => {
+      it('should get the description for a specific command', () => {
+        const description = {
+          args: {
+            properties: {},
+            additionalProperties: false,
+            type: 'object'
+          }
+        };
+        let cmd = {
+          execute: (args: JSONObject) => {
+            return args;
+          },
+          describedBy: description
+        };
+        registry.addCommand('test', cmd);
+        expect(registry.describedBy('test')).to.deep.equal(description);
+      });
+
+      it('should return an empty description if the command is not registered', () => {
+        expect(registry.describedBy('foo')).to.deep.equal({ args: null });
+      });
+
+      it('should default to an empty description for a command', () => {
+        registry.addCommand('test', NULL_COMMAND);
+        expect(registry.describedBy('test')).to.deep.equal({ args: null });
+      });
+    });
+
     describe('#usage()', () => {
       it('should get the usage text for a specific command', () => {
         let cmd = {