lucid-extension-sdk 0.0.207 → 0.0.210

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/commandtypes.d.ts

@@ -122,6 +122,7 @@ export declare const enum CommandName {
     SetPackageSettings = "sps",
     SetProperty = "sp",
     SetReferenceKey = "srk",
+    SetSelection = "ss",
     SetShapeData = "ssd",
     SetText = "st",
     SetTextStyle = "sts",
@@ -548,6 +549,10 @@ export type CommandArgs = {
         query: SetReferenceKeyQuery;
         result: SetReferenceKeyResult;
     };
+    [CommandName.SetSelection]: {
+        query: SetSelectionQuery;
+        result: SetSelectionResult;
+    };
     [CommandName.SetShapeData]: {
         query: SetShapeDataQuery;
         result: SetShapeDataResult;
@@ -1034,11 +1039,17 @@ export type GetLLMContextFromItemsQuery = {
     /** List of item IDs to return LLM-readable context for */
     'i': string[];
 };
-/**
- * A string in a format that LLMs like ChatGPT can easily understand, representing the content
- * of the items specified as well as their immediate context if necessary
- */
-export type GetLLMContextFromItemsResult = string;
+export type GetLLMContextFromItemsResult = {
+    /**
+     * A string in a format that LLMs like ChatGPT can easily understand, representing the content
+     * of the items specified as well as their immediate context if necessary
+     */
+    'p': string;
+    /**
+     * A map from IDs specified in the prompt string to actual Lucid item IDs
+     */
+    'id': Record<string, string>;
+};
 export type GetReferenceKeyQuery = {
     /** ID of the LucidElement to read a reference key from, or undefined to read from the LucidDocument */
     'id'?: string | undefined;
@@ -1370,6 +1381,11 @@ export type SetReferenceKeyQuery = {
     'v'?: SerializedReferenceKeyType | undefined;
 };
 export type SetReferenceKeyResult = undefined;
+export type SetSelectionQuery = {
+    /** IDs of the elements to select */
+    'i': string[];
+};
+export type SetSelectionResult = undefined;
 export type SetShapeDataQuery = {
     /** ID of the element to set this shape data on */
     'id'?: string | undefined;

package/commandtypes.js

@@ -99,6 +99,7 @@ exports.commandTitles = new Map([
     ["sps" /* CommandName.SetPackageSettings */, 'SetPackageSettings'],
     ["sp" /* CommandName.SetProperty */, 'SetProperty'],
     ["srk" /* CommandName.SetReferenceKey */, 'SetReferenceKey'],
+    ["ss" /* CommandName.SetSelection */, 'SetSelection'],
     ["ssd" /* CommandName.SetShapeData */, 'SetShapeData'],
     ["sts" /* CommandName.SetTextStyle */, 'SetTextStyle'],
     ["sm" /* CommandName.ShowModal */, 'ShowModal'],

package/document/pageproxy.d.ts

@@ -111,7 +111,11 @@ export declare class PageProxy extends ElementProxy {
     /**
      * @param items
      * @returns A string representing the content of the items provided, including immediate surrounding context if
-     * necessary, in a format that is easily understandable by LLMs like ChatGPT.
+     * necessary, in a format that is easily understandable by LLMs like ChatGPT. Also a map of IDs, from the shortened
+     * IDs provided for the items in the context to the actual Lucid item IDs.
      */
-    getLLMContextForItems(items: ItemProxy[]): string;
+    getLLMContextForItems(items: ItemProxy[]): {
+        prompt: string;
+        idToLucidId: Map<string, string>;
+    };
 }

package/document/pageproxy.js

@@ -177,15 +177,20 @@ class PageProxy extends elementproxy_1.ElementProxy {
     /**
      * @param items
      * @returns A string representing the content of the items provided, including immediate surrounding context if
-     * necessary, in a format that is easily understandable by LLMs like ChatGPT.
+     * necessary, in a format that is easily understandable by LLMs like ChatGPT. Also a map of IDs, from the shortened
+     * IDs provided for the items in the context to the actual Lucid item IDs.
      */
     getLLMContextForItems(items) {
         //We don't check that the items are on this page here; that is done in the implementation
         //of the API command. It would be a lot of extra API calls for no benefit.
-        return this.client.sendCommand("llm" /* CommandName.GetLLMContextFromItems */, {
+        const result = this.client.sendCommand("llm" /* CommandName.GetLLMContextFromItems */, {
             'p': this.id,
             'i': items.map((item) => item.id),
         });
+        return {
+            prompt: result['p'],
+            idToLucidId: new Map(Object.entries(result['id'])),
+        };
     }
 }
 exports.PageProxy = PageProxy;

package/editorclient.d.ts

@@ -317,6 +317,11 @@ export declare class EditorClient {
      * @returns the given item
      */
     getItemProxy(id: string): BlockProxy | LineProxy | GroupProxy;
+    /**
+     * @param id ID of the item to create a proxy for
+     * @returns the given item, or undefined if the item does not exist or an error occurs
+     */
+    tryGetItemProxy(id: string): BlockProxy | LineProxy | GroupProxy | undefined;
     /**
      * @param id ID of the element to create a proxy for
      * @returns the given element

package/editorclient.js

@@ -516,6 +516,20 @@ class EditorClient {
                 throw new Error('Element ' + id + ' is not an Item; type found is ' + type);
         }
     }
+    /**
+     * @param id ID of the item to create a proxy for
+     * @returns the given item, or undefined if the item does not exist or an error occurs
+     */
+    tryGetItemProxy(id) {
+        try {
+            const item = this.getItemProxy(id);
+            if (item.exists()) {
+                return item;
+            }
+        }
+        catch (_a) { }
+        return undefined;
+    }
     /**
      * @param id ID of the element to create a proxy for
      * @returns the given element

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.207",
+    "version": "0.0.210",
     "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;

package/ui/viewport.d.ts

@@ -21,6 +21,12 @@ export declare class Viewport {
      * @returns An array of currently-selected items on the currently-visible page
      */
     getSelectedItems(deep?: boolean): ItemProxy[];
+    /**
+     * Unselect all currently-selected items, and select the subset of the given items that exist on
+     * the currently-visible page.
+     * @param items
+     */
+    setSelectedItems(items: ItemProxy[]): void;
     /**
      * Find available space on the current page for adding new content.
      * @param width

package/ui/viewport.js

@@ -23,6 +23,14 @@ class Viewport {
             .map((id) => this.client.getElementProxy(id))
             .filter((proxy) => proxy instanceof itemproxy_1.ItemProxy);
     }
+    /**
+     * Unselect all currently-selected items, and select the subset of the given items that exist on
+     * the currently-visible page.
+     * @param items
+     */
+    setSelectedItems(items) {
+        this.client.sendCommand("ss" /* CommandName.SetSelection */, { 'i': items.map((i) => i.id) });
+    }
     /**
      * Find available space on the current page for adding new content.
      * @param width