@jupyterlab/fileeditor-extension 4.5.0-alpha.0 → 4.5.0-alpha.2

package/src/commands.ts

@@ -53,6 +53,7 @@ import {
   ReadonlyJSONObject,
   ReadonlyPartialJSONObject
 } from '@lumino/coreutils';
+import { DisposableSet, IDisposable } from '@lumino/disposable';
 
 const autoClosingBracketsNotebook = 'notebook:toggle-autoclosing-brackets';
 const autoClosingBracketsConsole = 'console:toggle-autoclosing-brackets';
@@ -288,6 +289,26 @@ export namespace Commands {
             ? trans.__('Decrease Text Editor Font Size')
             : trans.__('Decrease Font Size');
         }
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            delta: {
+              type: 'number',
+              description: trans.__(
+                'The font size change delta (positive to increase, negative to decrease)'
+              )
+            },
+            isMenu: {
+              type: 'boolean',
+              description: trans.__(
+                'Whether the command is called from a menu context'
+              )
+            }
+          },
+          required: ['delta']
+        }
       }
     });
 
@@ -308,7 +329,13 @@ export namespace Commands {
       isEnabled,
       isToggled: () =>
         config.lineNumbers ?? extensions.baseConfiguration.lineNumbers,
-      label: trans.__('Show Line Numbers')
+      label: trans.__('Show Line Numbers'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.currentLineNumbers, {
@@ -330,6 +357,12 @@ export namespace Commands {
             | boolean
             | undefined) ?? false
         );
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
       }
     });
 
@@ -353,7 +386,18 @@ export namespace Commands {
           (config.lineWrap ?? extensions.baseConfiguration.lineWrap)
         );
       },
-      label: trans.__('Word Wrap')
+      label: trans.__('Word Wrap'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            mode: {
+              type: 'boolean',
+              description: trans.__('Whether to enable word wrap')
+            }
+          }
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.currentLineWrap, {
@@ -373,6 +417,12 @@ export namespace Commands {
         return (
           (widget?.content.editor.getOption('lineWrap') as boolean) ?? false
         );
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
       }
     });
 
@@ -406,6 +456,19 @@ export namespace Commands {
         return args['size']
           ? args['size'] === currentIndentUnit
           : 'Tab' == currentIndentUnit;
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            size: {
+              type: 'string',
+              description: trans.__(
+                'The number of spaces for indentation (or Tab for tab indentation)'
+              )
+            }
+          }
+        }
       }
     });
 
@@ -426,7 +489,13 @@ export namespace Commands {
       label: trans.__('Match Brackets'),
       isEnabled,
       isToggled: () =>
-        config.matchBrackets ?? extensions.baseConfiguration.matchBrackets
+        config.matchBrackets ?? extensions.baseConfiguration.matchBrackets,
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.currentMatchBrackets, {
@@ -448,6 +517,12 @@ export namespace Commands {
             | boolean
             | undefined) ?? false
         );
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
       }
     });
 
@@ -472,7 +547,20 @@ export namespace Commands {
       label: trans.__('Auto Close Brackets in Text Editor'),
       isToggled: () =>
         config.autoClosingBrackets ??
-        extensions.baseConfiguration.autoClosingBrackets
+        extensions.baseConfiguration.autoClosingBrackets,
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            force: {
+              type: 'boolean',
+              description: trans.__(
+                'Force enable/disable auto closing brackets'
+              )
+            }
+          }
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.autoClosingBracketsUniversal, {
@@ -501,7 +589,13 @@ export namespace Commands {
       isToggled: () =>
         commands.isToggled(CommandIDs.autoClosingBrackets) ||
         commands.isToggled(autoClosingBracketsNotebook) ||
-        commands.isToggled(autoClosingBracketsConsole)
+        commands.isToggled(autoClosingBracketsConsole),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -523,7 +617,22 @@ export namespace Commands {
         }
       },
       isToggled: args =>
-        args['theme'] === (config.theme ?? extensions.baseConfiguration.theme)
+        args['theme'] === (config.theme ?? extensions.baseConfiguration.theme),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            theme: {
+              type: 'string',
+              description: trans.__('The theme name to change to')
+            },
+            displayName: {
+              type: 'string',
+              description: trans.__('The display name of the theme')
+            }
+          }
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.find, {
@@ -536,7 +645,13 @@ export namespace Commands {
         const editor = widget.content.editor as CodeMirrorEditor;
         editor.execCommand(findNext);
       },
-      isEnabled
+      isEnabled,
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.goToLine, {
@@ -559,7 +674,22 @@ export namespace Commands {
           editor.execCommand(gotoLine);
         }
       },
-      isEnabled
+      isEnabled,
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            line: {
+              type: 'number',
+              description: trans.__('The line number to go to (1-indexed)')
+            },
+            column: {
+              type: 'number',
+              description: trans.__('The column number to go to (1-indexed)')
+            }
+          }
+        }
+      }
     });
 
     commands.addCommand(CommandIDs.changeLanguage, {
@@ -592,6 +722,21 @@ export namespace Commands {
         const spec = languages.findByMIME(mime);
         const name = spec && spec.name;
         return args['name'] === name;
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: trans.__('The language name to change to')
+            },
+            displayName: {
+              type: 'string',
+              description: trans.__('The display name of the language')
+            }
+          }
+        }
       }
     });
 
@@ -609,7 +754,20 @@ export namespace Commands {
         widget.content.editor.replaceSelection?.(text);
       },
       isEnabled,
-      label: trans.__('Replace Selection in Editor')
+      label: trans.__('Replace Selection in Editor'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            text: {
+              type: 'string',
+              description: trans.__(
+                'The text to replace the current selection with'
+              )
+            }
+          }
+        }
+      }
     });
 
     /**
@@ -627,7 +785,13 @@ export namespace Commands {
       },
       isEnabled,
       icon: consoleIcon,
-      label: trans.__('Create Console for Editor')
+      label: trans.__('Create Console for Editor'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -649,7 +813,13 @@ export namespace Commands {
         }
       },
       label: trans.__('Restart Kernel'),
-      isEnabled: () => consoleTracker !== null && isEnabled()
+      isEnabled: () => consoleTracker !== null && isEnabled(),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -713,7 +883,13 @@ export namespace Commands {
         }
       },
       isEnabled,
-      label: trans.__('Run Selected Code')
+      label: trans.__('Run Selected Code'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -751,7 +927,13 @@ export namespace Commands {
         }
       },
       isEnabled,
-      label: trans.__('Run All Code')
+      label: trans.__('Run All Code'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -778,7 +960,13 @@ export namespace Commands {
         );
       },
       icon: markdownIcon,
-      label: trans.__('Show Markdown Preview')
+      label: trans.__('Show Markdown Preview'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -808,6 +996,42 @@ export namespace Commands {
           cwd as string,
           (args.fileExt as string) ?? 'txt'
         );
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            cwd: {
+              type: 'string',
+              description: trans.__('The current working directory path')
+            },
+            fileExt: {
+              type: 'string',
+              description: trans.__('The file extension for the new file')
+            },
+            isPalette: {
+              type: 'boolean',
+              description:
+                'Whether the command is being called from the command palette'
+            },
+            paletteLabel: {
+              type: 'string',
+              description: trans.__('The label to show in the command palette')
+            },
+            launcherLabel: {
+              type: 'string',
+              description: trans.__('The label to show in the launcher')
+            },
+            caption: {
+              type: 'string',
+              description: trans.__('The caption for the command')
+            },
+            iconName: {
+              type: 'string',
+              description: trans.__('The name of the icon to use')
+            }
+          }
+        }
       }
     });
 
@@ -824,6 +1048,22 @@ export namespace Commands {
       execute: args => {
         const cwd = args['cwd'] || defaultBrowser.model.path;
         return createNew(commands, cwd as string, 'md');
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            cwd: {
+              type: 'string',
+              description: trans.__('The current working directory path')
+            },
+            isPalette: {
+              type: 'boolean',
+              description:
+                'Whether the command is being called from the command palette'
+            }
+          }
+        }
       }
     });
 
@@ -854,7 +1094,13 @@ export namespace Commands {
         return widget.editor.model.sharedModel.canUndo();
       },
       icon: undoIcon.bindprops({ stylesheet: 'menuItem' }),
-      label: trans.__('Undo')
+      label: trans.__('Undo'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -884,7 +1130,13 @@ export namespace Commands {
         return widget.editor.model.sharedModel.canRedo();
       },
       icon: redoIcon.bindprops({ stylesheet: 'menuItem' }),
-      label: trans.__('Redo')
+      label: trans.__('Redo'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -919,7 +1171,13 @@ export namespace Commands {
         return isSelected(widget.editor as CodeMirrorEditor);
       },
       icon: cutIcon.bindprops({ stylesheet: 'menuItem' }),
-      label: trans.__('Cut')
+      label: trans.__('Cut'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -953,7 +1211,13 @@ export namespace Commands {
         return isSelected(widget.editor as CodeMirrorEditor);
       },
       icon: copyIcon.bindprops({ stylesheet: 'menuItem' }),
-      label: trans.__('Copy')
+      label: trans.__('Copy'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -980,7 +1244,13 @@ export namespace Commands {
       },
       isEnabled: () => Boolean(isEnabled() && tracker.currentWidget?.content),
       icon: pasteIcon.bindprops({ stylesheet: 'menuItem' }),
-      label: trans.__('Paste')
+      label: trans.__('Paste'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     /**
@@ -998,7 +1268,13 @@ export namespace Commands {
         editor.execCommand(selectAll);
       },
       isEnabled: () => Boolean(isEnabled() && tracker.currentWidget?.content),
-      label: trans.__('Select All')
+      label: trans.__('Select All'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      }
     });
 
     // All commands with isEnabled defined directly or in a semantic commands
@@ -1048,6 +1324,12 @@ export namespace Commands {
         if (id) {
           return manager.invoke(id);
         }
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
       }
     });
 
@@ -1059,6 +1341,12 @@ export namespace Commands {
         if (id) {
           return manager.select(id);
         }
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
       }
     });
 
@@ -1157,20 +1445,27 @@ export namespace Commands {
 
   /**
    * Add ___ File items to the Launcher for common file types associated with available kernels
+   * Returns a DisposableSet containing all added items
    */
   export function addKernelLanguageLauncherItems(
     launcher: ILauncher,
     trans: TranslationBundle,
     availableKernelFileTypes: Iterable<IFileTypeData>
-  ): void {
-    for (let ext of availableKernelFileTypes) {
-      launcher.add({
-        command: CommandIDs.createNew,
-        category: trans.__('Other'),
-        rank: 3,
-        args: ext
-      });
+  ): IDisposable {
+    const disposables = new DisposableSet();
+
+    for (const ext of availableKernelFileTypes) {
+      disposables.add(
+        launcher.add({
+          command: CommandIDs.createNew,
+          category: trans.__('Other'),
+          rank: 3,
+          args: ext
+        })
+      );
     }
+
+    return disposables;
   }
 
   /**
@@ -1260,20 +1555,27 @@ export namespace Commands {
 
   /**
    * Add New ___ File commands to the File Editor palette for common file types associated with available kernels
+   * Returns a DisposableSet containing all added items
    */
   export function addKernelLanguagePaletteItems(
     palette: ICommandPalette,
     trans: TranslationBundle,
     availableKernelFileTypes: Iterable<IFileTypeData>
-  ): void {
+  ): IDisposable {
+    const disposables = new DisposableSet();
     const paletteCategory = trans.__('Text Editor');
-    for (let ext of availableKernelFileTypes) {
-      palette.addItem({
-        command: CommandIDs.createNew,
-        args: { ...ext, isPalette: true },
-        category: paletteCategory
-      });
+
+    for (const ext of availableKernelFileTypes) {
+      disposables.add(
+        palette.addItem({
+          command: CommandIDs.createNew,
+          args: { ...ext, isPalette: true },
+          category: paletteCategory
+        })
+      );
     }
+
+    return disposables;
   }
 
   /**
@@ -1323,18 +1625,25 @@ export namespace Commands {
 
   /**
    * Add Create New ___ File commands to the File menu for common file types associated with available kernels
+   * Returns a DisposableSet containing all added items
    */
   export function addKernelLanguageMenuItems(
     menu: IMainMenu,
     availableKernelFileTypes: Iterable<IFileTypeData>
-  ): void {
-    for (let ext of availableKernelFileTypes) {
-      menu.fileMenu.newMenu.addItem({
-        command: CommandIDs.createNew,
-        args: ext,
-        rank: 31
-      });
+  ): IDisposable {
+    const disposables = new DisposableSet();
+
+    for (const ext of availableKernelFileTypes) {
+      disposables.add(
+        menu.fileMenu.newMenu.addItem({
+          command: CommandIDs.createNew,
+          args: ext,
+          rank: 31
+        })
+      );
     }
+
+    return disposables;
   }
 
   /**
@@ -1418,6 +1727,36 @@ export namespace Commands {
       label: trans.__('Open Code Viewer'),
       execute: (args: any) => {
         return openCodeViewer(args);
+      },
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {
+            content: {
+              type: 'string',
+              description: trans.__('The content to display in the code viewer')
+            },
+            label: {
+              type: 'string',
+              description: trans.__('The label for the code viewer')
+            },
+            mimeType: {
+              type: 'string',
+              description: trans.__('The MIME type of the content')
+            },
+            extension: {
+              type: 'string',
+              description: trans.__(
+                'The file extension to derive MIME type from'
+              )
+            },
+            widgetId: {
+              type: 'string',
+              description: trans.__('The ID to assign to the widget')
+            }
+          },
+          required: ['content']
+        }
       }
     });
   }