Add a set of functions to handle user interactions

Author: cyanzhong

README.md

@@ -18,7 +18,7 @@ Add `markedit-api` to your (TypeScript) project's devDependencies:
 ```json
 {
   "devDependencies": {
-    "markedit-api": "https://github.com/MarkEdit-app/MarkEdit-api#v0.5.0"
+    "markedit-api": "https://github.com/MarkEdit-app/MarkEdit-api#v0.6.0"
   }
 }
 ```
@@ -42,13 +42,21 @@ interface MarkEdit {
   // Lezer modules used by MarkEdit.
   lezer: { common, highlight, markdown, lr };
   // Get notified when the editor is initialized.
-  onEditorReady: (listener: (editorView: EditorView) => void) => void;
+  onEditorReady(listener: (editorView: EditorView) => void): void;
   // Add an extension to MarkEdit.
-  addExtension: (extension: Extension) => void;
+  addExtension(extension: Extension): void;
   // Add a Markdown config to MarkEdit.
-  addMarkdownConfig: (config: MarkdownConfig) => void;
+  addMarkdownConfig(config: MarkdownConfig): void;
   // Add a language to be highlighted (in code blocks) to MarkEdit.
-  addCodeLanguage: (language: LanguageDescription) => void;
+  addCodeLanguage(language: LanguageDescription): void;
+  // Add a menu item to the status bar.
+  addMainMenuItem(item: MenuItem | MenuItem[]): void;
+  // Present a contextual menu to receive user input.
+  showContextMenu(items: MenuItem[], location?: Point): void;
+  // Present an alert to receive user input.
+  showAlert(alert: Alert): Promise<number>;
+  // Present a text box to receive user input.
+  showTextBox(textBox?: TextBox): Promise<string | undefined>;
 }
 ```
 
@@ -81,6 +89,14 @@ MarkEdit.addCodeLanguage(language);
 
 > While extensions and configs can theoretically be added at any time, it is recommended that they be added immediately after loading the script.
 
+## Handling User Input
+
+While you can certainly build user interfaces with JavaScript and CSS, leveraging native UI components might be a better option.
+
+To create UI entries for your features, you can use the [addMainMenuItem](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+addMainMenuItem&type=code) function, which adds an item to the "Extensions" submenu of the main menu, with keyboard shortcuts support.
+
+To request user input, try using [showContextMenu](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showContextMenu&type=code), [showAlert](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showAlert&type=code), and [showTextBox](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showTextBox&type=code).
+
 ## Building
 
 In your build configuration, mark used MarkEdit and CodeMirror dependencies as `external`.
@@ -147,3 +163,5 @@ const editorAPI = MarkEdit.editorAPI;
 ----
 
 For complete examples, refer to [Example: Markdown Table Editor](https://github.com/MarkEdit-app/MarkEdit-mte), [Example: Text Highlight](https://github.com/MarkEdit-app/MarkEdit-highlight) and [Example: Vue Language Package](https://github.com/MarkEdit-app/MarkEdit-lang-vue).
+
+Also, [markedit.d.ts](./markedit.d.ts) is fully typed and documented, use it as the API reference.

markedit.d.ts

@@ -95,25 +95,52 @@ export interface MarkEdit {
    * Get notified when the editor is initialized.
    * @param listener The callback function with the initialized editor instance.
    */
-  onEditorReady: (listener: (editorView: EditorView) => void) => void;
+  onEditorReady(listener: (editorView: EditorView) => void): void;
 
   /**
    * Add an extension to MarkEdit.
    * @param extension CodeMirror extension.
    */
-  addExtension: (extension: Extension) => void;
+  addExtension(extension: Extension): void;
 
   /**
    * Add a Markdown config to MarkEdit.
    * @param config Markdown config.
    */
-  addMarkdownConfig: (config: MarkdownConfig) => void;
+  addMarkdownConfig(config: MarkdownConfig): void;
 
   /**
    * Add a language to be highlighted (in code blocks) to MarkEdit.
    * @param language The language description.
    */
-  addCodeLanguage: (language: LanguageDescription) => void;
+  addCodeLanguage(language: LanguageDescription): void;
+
+  /**
+   * Add a menu item to the status bar.
+   * @param item The menu item to add, which will be placed under the "Extensions" submenu. It can either perform an action or contain a submenu.
+   */
+  addMainMenuItem(item: MenuItem | MenuItem[]): void;
+
+  /**
+   * Present a contextual menu to receive user input.
+   * @param items The items in the menu.
+   * @param location The location to show the menu, with the default value set to the caret position.
+   */
+  showContextMenu(items: MenuItem[], location?: Point): void;
+
+  /**
+   * Present an alert to receive user input.
+   * @param alert The alert to present.
+   * @returns The index of the chosen button, 0-indexed.
+   */
+  showAlert(alert: Alert): Promise<number>;
+
+  /**
+   * Present a text box to receive user input.
+   * @param textBox The text box to present.
+   * @returns The input string, or undefined if no value is provided.
+   */
+  showTextBox(textBox?: TextBox): Promise<string | undefined>;
 }
 
 /**
@@ -183,7 +210,83 @@ export interface TextEditable {
   redo(): void;
 }
 
+/**
+ * Represents a portion of text.
+ */
 export type TextRange = {
   from: number;
   to: number;
-}
+};
+
+/**
+ * Represents a menu item in native menus.
+ */
+export type MenuItem = {
+  title?: string;
+  action?: () => void;
+
+  /**
+   * Whether an item is a separator used to logically group other items.
+   */
+  separator?: boolean;
+
+  /**
+   * Key equivalent of the action.
+   */
+  key?: string;
+
+  /**
+   * Key modifiers of the action. Valid values are `Shift`, `Control`, `Command`, and `Option`.
+   *
+   * The order does not matter but they are case sensitive.
+   *
+   * When `key` is uppercase, `Shift` is automatically enabled.
+   */
+  modifiers?: ('Shift' | 'Control' | 'Command' | 'Option')[];
+
+  /**
+   * Child items to build a submenu.
+   */
+  children?: MenuItem[];
+};
+
+/**
+ * Represents a location on the screen.
+ */
+export type Point = {
+  x: number;
+  y: number;
+};
+
+/**
+ * Represents a native alert to present.
+ *
+ * If it's a string, it will be used as the title.
+ */
+export type Alert = {
+  /**
+   * The title that is displayed prominently in the alert.
+   */
+  title?: string;
+
+  /**
+   * The informative message for more details.
+   */
+  message?: string;
+
+  /**
+   * The button titles.
+   */
+  buttons?: string[];
+} | string;
+
+/**
+ * Represents a text box to receive input.
+ *
+ * If it's a string, it will be used as the title.
+ */
+export type TextBox = {
+  title?: string;
+  placeholder?: string;
+  defaultValue?: string;
+} | string;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "markedit-api",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Type definitions for the latest MakrEdit API.",
   "main": "main.ts",
   "types": "markedit.d.ts",