lucid-extension-sdk 0.0.207 → 0.0.209

package/README.md

@@ -23,10 +23,9 @@ client.registerAction('my-new-action', () => {
     console.log('Hello world');
 });
 
-menu.addMenuItem({
+menu.addDropdownMenuItem({
     label: 'Hello world',
     action: 'my-new-action',
-    menuType: MenuType.Main,
 });
 ```
 
@@ -67,10 +66,9 @@ client.registerAction('create-content', async () => {
     }
 });
 
-menu.addMenuItem({
+menu.addDropdownMenuItem({
     label: 'Hello world',
     action: 'create-content',
-    menuType: MenuType.Main,
 });
 ```
 
@@ -103,10 +101,9 @@ client.registerAction('download', async () => {
     client.download('data.csv', csv.map((line) => line.join(',')).join('\n'), 'text/plain', false);
 });
 
-menu.addMenuItem({
+menu.addDropdownMenuItem({
     label: 'Download CSV',
     action: 'download',
-    menuType: MenuType.Main,
     location: MenuLocation.Export, //Near File -> Export
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.207",
+    "version": "0.0.209",
     "description": "Utility classes for writing Lucid Software editor extensions",
     "main": "index.js",
     "types": "index.d.ts",

package/ui/menu.d.ts

@@ -1,8 +1,14 @@
 import { EditorClient } from '../editorclient';
+/**
+ * Type of menu you're adding.
+ * Consider using addDropdownMenuItem, addContextMenuItem, or addContentDockMenuItem for easier to use entrypoints and clearer requirements.
+ */
 export declare enum MenuType {
+    /** The main drop down menus. */
     Main = 1,
     /** The context menu that appears when the user right-clicks the canvas. */
     Context = 2,
+    /** The side dock in Lucidspark and Teamspaces */
     ContentDock = 3
 }
 /**
@@ -17,6 +23,56 @@ export declare enum MenuLocation {
     Export = 5,
     Import = 6
 }
+/**
+ * Data to create a menu
+ */
+export interface CustomMenuConfig {
+    /** The text to display on the menu item */
+    label: string;
+    /** The registered action to run when the menu item is clicked. */
+    action?: string;
+    /** If specified, what action's return value should determine if this menu item is visible? */
+    visibleAction?: string;
+    /** If specified, what action's return value should determine if this menu item is disabled? */
+    disabledAction?: string;
+    /** If specified, this menu item should launch a file picker */
+    file?: {
+        /** An action registered with EditorClient.registerFileUploadAction */
+        action: string;
+        /** An [accept string](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) as specified for HTML file inputs */
+        accept: string;
+        /** If true, only allow a single file to be selected for upload */
+        singleFileOnly?: boolean;
+        /** If true, send the file contents to the callback action as a Uint8Array as well as a plain text string */
+        binary?: boolean;
+    };
+}
+/**
+ * Data to create a dropdown menu in the main top menus.
+ */
+export interface CustomDropdownMenu extends CustomMenuConfig {
+    /** Where in that menu to display this item in Lucidchart.
+     * Defaults to the extension menu.
+     * In Lucidspark the only valid menu is Extension, it will not appear otherwise.
+     */
+    location?: MenuLocation;
+}
+/**
+ * Data to create a content dock icon in Spark + Teamspaces
+ */
+export interface CustomContentDockMenu extends CustomMenuConfig {
+    /** The icon to display on the menu item.
+     * A URL (a data URI is fine) pointing to an icon representing the integration.
+     * This will be displayed at up to 32x32 CSS pixels in size.
+     */
+    iconUrl: string;
+    /** The registered action to run when the menu item is clicked */
+    action: string;
+}
+/**
+ * A generic object to contain any information creating a menu might need.
+ * It is a little easier to use CustomMenuConfig, CustomDropdownMenu, or CustomContentDockMenu.
+ */
 export interface CustomMenuItem {
     /** The text to display on the menu item */
     label: string;
@@ -58,11 +114,45 @@ export declare class Menu {
     private readonly client;
     constructor(client: EditorClient);
     /**
-     * Add a new menu item to execute custom code. The action must be registered with
+     * Generic function to create a new menu item to trigger custom code.
+     * You can use addDropdownMenuItem, addContextMenuItem, or addContentDockMenuItem for easier to use entrypoints.
+     *
+     * The action must be registered with
      * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
      * prior to using it in the menu.
      *
      * @param item The definition of the new menu item
      */
     addMenuItem(item: CustomMenuItem): void;
+    /**
+     * Create a menu in the basic drop down top menus. In Lucidspark this will just be under the generic menu.
+     * In Lucidchart you can configure this to be in any of the other drop down menus.
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addDropdownMenuItem(item: CustomDropdownMenu): void;
+    /**
+     * Create a menu in the right click context menu. Appears in both Lucidspark and Lucidchart.
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addContextMenuItem(item: CustomMenuConfig): void;
+    /**
+     * Create an icon tied to an action (required) that appears in the left toolbar in Lucidspark and Teamspaces (not in Lucidchart).
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addContentDockMenuItem(item: CustomContentDockMenu): void;
 }

package/ui/menu.js

@@ -1,11 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Menu = exports.MenuLocation = exports.MenuType = void 0;
+/**
+ * Type of menu you're adding.
+ * Consider using addDropdownMenuItem, addContextMenuItem, or addContentDockMenuItem for easier to use entrypoints and clearer requirements.
+ */
 var MenuType;
 (function (MenuType) {
+    /** The main drop down menus. */
     MenuType[MenuType["Main"] = 1] = "Main";
     /** The context menu that appears when the user right-clicks the canvas. */
     MenuType[MenuType["Context"] = 2] = "Context";
+    /** The side dock in Lucidspark and Teamspaces */
     MenuType[MenuType["ContentDock"] = 3] = "ContentDock";
 })(MenuType = exports.MenuType || (exports.MenuType = {}));
 /**
@@ -26,7 +32,10 @@ class Menu {
         this.client = client;
     }
     /**
-     * Add a new menu item to execute custom code. The action must be registered with
+     * Generic function to create a new menu item to trigger custom code.
+     * You can use addDropdownMenuItem, addContextMenuItem, or addContentDockMenuItem for easier to use entrypoints.
+     *
+     * The action must be registered with
      * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
      * prior to using it in the menu.
      *
@@ -66,5 +75,68 @@ class Menu {
                 : undefined,
         });
     }
+    /**
+     * Create a menu in the basic drop down top menus. In Lucidspark this will just be under the generic menu.
+     * In Lucidchart you can configure this to be in any of the other drop down menus.
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addDropdownMenuItem(item) {
+        var _a;
+        this.addMenuItem({
+            label: item.label,
+            action: item.action,
+            visibleAction: item.visibleAction,
+            disabledAction: item.disabledAction,
+            menuType: MenuType.Main,
+            location: (_a = item.location) !== null && _a !== void 0 ? _a : MenuLocation.Extension,
+            file: item.file,
+        });
+    }
+    /**
+     * Create a menu in the right click context menu. Appears in both Lucidspark and Lucidchart.
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addContextMenuItem(item) {
+        this.addMenuItem({
+            label: item.label,
+            action: item.action,
+            visibleAction: item.visibleAction,
+            disabledAction: item.disabledAction,
+            menuType: MenuType.Context,
+            location: MenuLocation.Extension,
+            file: item.file,
+        });
+    }
+    /**
+     * Create an icon tied to an action (required) that appears in the left toolbar in Lucidspark and Teamspaces (not in Lucidchart).
+     *
+     * The action must be registered with
+     * [EditorClient.registerAction](/extension-sdk/#classes_editorclient-EditorClient_registeraction)
+     * prior to using it in the menu.
+     *
+     * @param item The definition of the new menu item
+     */
+    addContentDockMenuItem(item) {
+        this.addMenuItem({
+            label: item.label,
+            iconUrl: item.iconUrl,
+            action: item.action,
+            visibleAction: item.visibleAction,
+            disabledAction: item.disabledAction,
+            menuType: MenuType.ContentDock,
+            location: MenuLocation.Extension,
+            file: item.file,
+        });
+    }
 }
 exports.Menu = Menu;