lucid-extension-sdk 0.0.6 → 0.0.13

package/sdk/editorclient.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EditorClient = void 0;
-const checks_1 = require("./core/checks");
+const commandtypes_1 = require("./commandtypes");
 const blockproxyregistry_1 = require("./document/blockclasses/blockproxyregistry");
 const blockproxy_1 = require("./document/blockproxy");
 const documentproxy_1 = require("./document/documentproxy");
@@ -71,7 +71,37 @@ class EditorClient {
                 timeout: raw['to'],
             };
         })
-            .catch((raw) => {
+            .catch((error) => {
+            const raw = (0, commandtypes_1.isRawSendXHRResponse)(error) ? error : undefined;
+            throw {
+                url: raw ? raw['url'] : '',
+                responseText: raw ? raw['t'] : 'An unknown error occurred',
+                status: raw ? raw['s'] : 0,
+                headers: raw ? raw['h'] : {},
+                timeout: raw ? raw['to'] : undefined,
+            };
+        });
+    }
+    oauthXhr(providerName, request) {
+        return this.sendCommand("oauth" /* SendOAuthRequest */, {
+            'url': request.url,
+            'm': request.method,
+            'd': request.data,
+            'h': request.headers,
+            'ms': request.timeoutMs,
+            'p': providerName,
+        })
+            .then((raw) => {
+            return {
+                url: raw['url'],
+                responseText: raw['t'],
+                status: raw['s'],
+                headers: raw['h'],
+                timeout: raw['to'],
+            };
+        })
+            .catch((error) => {
+            const raw = (0, commandtypes_1.isRawSendXHRResponse)(error) ? error : error;
             throw {
                 url: raw['url'],
                 responseText: raw['t'],
@@ -123,7 +153,6 @@ class EditorClient {
      * Execute an API command. This is the low-level API that most of this SDK wraps. It is not expected that you should
      * ever need to use this directly.
      *
-     * @hidden
      * @param name name of the API command to execute
      * @param params data to pass to the API command
      * @returns the output of the given API command
@@ -165,7 +194,7 @@ class EditorClient {
      * created.
      *
      * Example usage:
-     * ```
+     * ```inline:typescript
      * const client = new EditorClient();
      * const viewport = new Viewport(client);
      *
@@ -234,6 +263,23 @@ class EditorClient {
     getPageProxy(id) {
         return new pageproxy_1.PageProxy(id, this);
     }
+    /**
+     * @param id ID of the item to create a proxy for
+     * @returns the given item
+     */
+    getItemProxy(id) {
+        const type = this.sendCommand("get" /* GetElementType */, { 'id': id });
+        switch (type) {
+            case 'block':
+                return this.getBlockProxy(id);
+            case 'line':
+                return this.getLineProxy(id);
+            case 'group':
+                return new groupproxy_1.GroupProxy(id, this);
+            default:
+                throw new Error('Element ' + id + ' is not an Item; type found is ' + type);
+        }
+    }
     /**
      * @param id ID of the element to create a proxy for
      * @returns the given element
@@ -261,11 +307,7 @@ class EditorClient {
     listenToEditor() {
         lucid.listen((msg) => {
             var _a;
-            const value = (_a = this.callbacks.get(msg['id'])) === null || _a === void 0 ? void 0 : _a(msg);
-            if ((0, checks_1.isPromise)(value)) {
-                return undefined;
-            }
-            return value;
+            return (_a = this.callbacks.get(msg['id'])) === null || _a === void 0 ? void 0 : _a(msg);
         });
     }
 }

package/sdk/index.d.ts

@@ -26,4 +26,5 @@ export * from './math';
 export * from './ui/alertmodal';
 export * from './ui/menu';
 export * from './ui/modal';
+export * from './ui/panel';
 export * from './ui/viewport';

package/sdk/index.js

@@ -38,4 +38,5 @@ __exportStar(require("./math"), exports);
 __exportStar(require("./ui/alertmodal"), exports);
 __exportStar(require("./ui/menu"), exports);
 __exportStar(require("./ui/modal"), exports);
+__exportStar(require("./ui/panel"), exports);
 __exportStar(require("./ui/viewport"), exports);

package/sdk/ui/alertmodal.d.ts

@@ -2,10 +2,9 @@ import { EditorClient } from '../editorclient';
 import { Modal } from './modal';
 /**
  * A simple example modal that displays a message to the user
+ * TODO: Replace with a dedicated command
+ * @ignore
  */
 export declare class AlertModal extends Modal {
-    protected readonly client: EditorClient;
     constructor(client: EditorClient, title: string, message: string);
-    protected messageFromFrame(message: any): void;
-    protected frameLoaded(): void;
 }

package/sdk/ui/alertmodal.js

@@ -4,6 +4,8 @@ exports.AlertModal = void 0;
 const modal_1 = require("./modal");
 /**
  * A simple example modal that displays a message to the user
+ * TODO: Replace with a dedicated command
+ * @ignore
  */
 class AlertModal extends modal_1.Modal {
     constructor(client, title, message) {
@@ -32,9 +34,6 @@ p {
 </html>
             `,
         });
-        this.client = client;
     }
-    messageFromFrame(message) { }
-    frameLoaded() { }
 }
 exports.AlertModal = AlertModal;

package/sdk/ui/iframeui.d.ts

@@ -0,0 +1,57 @@
+import { JsonSerializable } from '../core/jsonserializable';
+import { EditorClient } from '../editorclient';
+/** @ignore */
+export declare enum IncomingUIMessageType {
+    Closed = 1,
+    PostMessageFromFrame = 2,
+    FrameLoaded = 3
+}
+/** @ignore */
+export interface IncomingUIMessage {
+    'id': string;
+    't': IncomingUIMessageType;
+    'data'?: any;
+}
+/**
+ * Base class for defining and interacting with custom UI elements whose contents are displayed
+ * in an iframe.
+ */
+export declare abstract class IframeUI {
+    protected readonly client: EditorClient;
+    private static nextId;
+    private id;
+    private static uiMessageActionNamePrefix;
+    protected messageActionName: string;
+    protected loaded: boolean;
+    constructor(client: EditorClient);
+    /** @ignore */
+    static isUIMessageActionName(name: string): boolean;
+    /**
+     * Subclasses must call hookMessages some time before the UI is displayed. A Modal
+     * will call this when the open() method is called, where a Panel will need to do
+     * this in the constructor to watch for the user opening the panel.
+     */
+    protected hookMessages(): void;
+    /**
+     * Subclasses must call unhookMessages to allow them to be garbage collected.
+     */
+    protected unhookMessages(): void;
+    /**
+     * Send a message to this UI component's iframe via window.postMessage.
+     * @param data Data to send to the iframe
+     */
+    sendMessage(data: JsonSerializable): void;
+    /**
+     * Receives messages sent from the iframe via parent.postMessage(<data>, '*')
+     * @param message data sent from the iframe
+     */
+    protected messageFromFrame(message: any): void;
+    /**
+     * Called when the iframe has been constructed, its srcdoc set, and the window loaded event has fired
+     */
+    protected frameLoaded(): void;
+    /**
+     * Called when the iframe has been removed from the DOM
+     */
+    protected frameClosed(): void;
+}

package/sdk/ui/iframeui.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IframeUI = exports.IncomingUIMessageType = void 0;
+/** @ignore */
+var IncomingUIMessageType;
+(function (IncomingUIMessageType) {
+    IncomingUIMessageType[IncomingUIMessageType["Closed"] = 1] = "Closed";
+    IncomingUIMessageType[IncomingUIMessageType["PostMessageFromFrame"] = 2] = "PostMessageFromFrame";
+    IncomingUIMessageType[IncomingUIMessageType["FrameLoaded"] = 3] = "FrameLoaded";
+})(IncomingUIMessageType = exports.IncomingUIMessageType || (exports.IncomingUIMessageType = {}));
+/**
+ * Base class for defining and interacting with custom UI elements whose contents are displayed
+ * in an iframe.
+ */
+class IframeUI {
+    constructor(client) {
+        this.client = client;
+        this.id = ++IframeUI.nextId;
+        this.messageActionName = IframeUI.uiMessageActionNamePrefix + this.id;
+        this.loaded = false;
+    }
+    /** @ignore */
+    static isUIMessageActionName(name) {
+        return name.startsWith(IframeUI.uiMessageActionNamePrefix);
+    }
+    /**
+     * Subclasses must call hookMessages some time before the UI is displayed. A Modal
+     * will call this when the open() method is called, where a Panel will need to do
+     * this in the constructor to watch for the user opening the panel.
+     */
+    hookMessages() {
+        this.client.registerAction(this.messageActionName, (message) => {
+            switch (message['t']) {
+                case IncomingUIMessageType.Closed:
+                    this.loaded = false;
+                    this.frameClosed();
+                    break;
+                case IncomingUIMessageType.PostMessageFromFrame:
+                    this.messageFromFrame(message['data']);
+                    break;
+                case IncomingUIMessageType.FrameLoaded:
+                    this.loaded = true;
+                    this.frameLoaded();
+                    break;
+            }
+        });
+    }
+    /**
+     * Subclasses must call unhookMessages to allow them to be garbage collected.
+     */
+    unhookMessages() {
+        this.client.deleteAction(this.messageActionName);
+    }
+    /**
+     * Send a message to this UI component's iframe via window.postMessage.
+     * @param data Data to send to the iframe
+     */
+    sendMessage(data) {
+        if (this.loaded) {
+            this.client.sendCommand("suim" /* SendUIMessage */, {
+                'n': this.messageActionName,
+                'd': data,
+            });
+        }
+    }
+    /**
+     * Receives messages sent from the iframe via parent.postMessage(<data>, '*')
+     * @param message data sent from the iframe
+     */
+    messageFromFrame(message) { }
+    /**
+     * Called when the iframe has been constructed, its srcdoc set, and the window loaded event has fired
+     */
+    frameLoaded() { }
+    /**
+     * Called when the iframe has been removed from the DOM
+     */
+    frameClosed() { }
+}
+exports.IframeUI = IframeUI;
+IframeUI.nextId = 0;
+IframeUI.uiMessageActionNamePrefix = '__ui_message__';

package/sdk/ui/modal.d.ts

@@ -1,22 +1,18 @@
-import { JsonSerializable } from '../core/jsonserializable';
 import { EditorClient } from '../editorclient';
+import { IframeUI } from './iframeui';
+/**
+ * Configuration required to display a [Modal](#classes_ui_modal-Modal).
+ */
 export interface ModalConfig {
+    /** Title to display in the header bar of the modal. */
     title: string;
+    /** Requested width of the modal, in pixels. Depending on window size, this may not be honored exactly. */
     width: number;
+    /** Requested height of the modal, in pixels. Depending on window size, this may not be honored exactly. */
     height: number;
     /** Content to display in the modal's iframe. This is set as the srcdoc on a sandboxed iframe. */
     content: string;
 }
-export declare enum ModalIncomingMessageType {
-    ModalClosed = 1,
-    PostMessageFromFrame = 2,
-    FrameLoaded = 3
-}
-export interface ModalIncomingMessage {
-    'id': string;
-    't': ModalIncomingMessageType;
-    'data'?: any;
-}
 /**
  * Extend this class to show a custom modal to the user, whose contents are displayed in a sandboxed
  * iframe controlled by your extension.
@@ -27,32 +23,14 @@ export interface ModalIncomingMessage {
  * To pass messages back from the modal to this class, call parent.postMessage from within the iframe.
  * The data sent will be passed along to the messageFromFrame implementation on your Modal class.
  */
-export declare abstract class Modal {
-    protected readonly client: EditorClient;
+export declare abstract class Modal extends IframeUI {
     private readonly config;
-    private static nextId;
-    private id;
-    private static modalMessageActionNamePrefix;
-    private messageActionName;
     private visible;
     constructor(client: EditorClient, config: ModalConfig);
-    static isMessageActionName(name: string): boolean;
-    private hookMessages;
-    private unhookMessages;
-    /**
-     * Send a message to this modal's iframe via window.postMessage.
-     * @param data Data to send to the iframe
-     */
-    sendMessage(data: JsonSerializable): void;
-    /**
-     * Receives messages sent from the iframe via parent.postMessage(<data>, '*')
-     * @param message data sent from the iframe
-     */
-    protected abstract messageFromFrame(message: any): void;
+    protected frameClosed(): void;
+    show(): void;
     /**
-     * Called when the iframe has been constructed, its srcdoc set, and the window loaded event has fired
+     * If this modal is currently visible, close it, destroying the iframe.
      */
-    protected abstract frameLoaded(): void;
-    show(): void;
     hide(): void;
 }

package/sdk/ui/modal.js

@@ -1,12 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Modal = exports.ModalIncomingMessageType = void 0;
-var ModalIncomingMessageType;
-(function (ModalIncomingMessageType) {
-    ModalIncomingMessageType[ModalIncomingMessageType["ModalClosed"] = 1] = "ModalClosed";
-    ModalIncomingMessageType[ModalIncomingMessageType["PostMessageFromFrame"] = 2] = "PostMessageFromFrame";
-    ModalIncomingMessageType[ModalIncomingMessageType["FrameLoaded"] = 3] = "FrameLoaded";
-})(ModalIncomingMessageType = exports.ModalIncomingMessageType || (exports.ModalIncomingMessageType = {}));
+exports.Modal = void 0;
+const iframeui_1 = require("./iframeui");
 /**
  * Extend this class to show a custom modal to the user, whose contents are displayed in a sandboxed
  * iframe controlled by your extension.
@@ -17,47 +12,14 @@ var ModalIncomingMessageType;
  * To pass messages back from the modal to this class, call parent.postMessage from within the iframe.
  * The data sent will be passed along to the messageFromFrame implementation on your Modal class.
  */
-class Modal {
+class Modal extends iframeui_1.IframeUI {
     constructor(client, config) {
-        this.client = client;
+        super(client);
         this.config = config;
-        this.id = ++Modal.nextId;
-        this.messageActionName = Modal.modalMessageActionNamePrefix + this.id;
         this.visible = false;
     }
-    static isMessageActionName(name) {
-        return name.startsWith(Modal.modalMessageActionNamePrefix);
-    }
-    hookMessages() {
-        this.client.registerAction(this.messageActionName, (message) => {
-            switch (message['t']) {
-                case ModalIncomingMessageType.ModalClosed:
-                    this.unhookMessages();
-                    this.visible = false;
-                    break;
-                case ModalIncomingMessageType.PostMessageFromFrame:
-                    this.messageFromFrame(message['data']);
-                    break;
-                case ModalIncomingMessageType.FrameLoaded:
-                    this.frameLoaded();
-                    break;
-            }
-        });
-    }
-    unhookMessages() {
-        this.client.deleteAction(this.messageActionName);
-    }
-    /**
-     * Send a message to this modal's iframe via window.postMessage.
-     * @param data Data to send to the iframe
-     */
-    sendMessage(data) {
-        if (this.visible) {
-            this.client.sendCommand("suim" /* SendUIMessage */, {
-                'n': this.messageActionName,
-                'd': data,
-            });
-        }
+    frameClosed() {
+        this.unhookMessages();
     }
     show() {
         if (!this.visible) {
@@ -72,6 +34,9 @@ class Modal {
             this.visible = true;
         }
     }
+    /**
+     * If this modal is currently visible, close it, destroying the iframe.
+     */
     hide() {
         if (this.visible) {
             this.client.sendCommand("hm" /* HideModal */, { 'n': this.messageActionName });
@@ -80,5 +45,3 @@ class Modal {
     }
 }
 exports.Modal = Modal;
-Modal.nextId = 0;
-Modal.modalMessageActionNamePrefix = '__modal_message__';

package/sdk/ui/panel.d.ts

@@ -0,0 +1,43 @@
+import { EditorClient } from '../editorclient';
+import { IframeUI } from './iframeui';
+/**
+ * Semantic locations to place a new menu item.
+ */
+export declare enum PanelLocation {
+    /** In Lucidchart, create a sibling to the Contextual Panel */
+    RightDock = 1
+}
+export interface PanelConfig {
+    /** Title to display at the top of the panel */
+    title: string;
+    /** Content to display in the panel's iframe. This is set as the srcdoc on a sandboxed iframe. */
+    content: string;
+    /** Location to display the panel */
+    location: PanelLocation;
+    /** If specified, what action's return value should determine if the button to toggle this panel is visible? */
+    visibleAction?: string;
+    /** The URL for an icon to represent the panel, preferably base64-encoded. Will be displayed at 24x24 CSS pixels in size. */
+    iconUrl: string;
+}
+/**
+ * Extend this class to show a custom panel to the user, whose contents are displayed in a sandboxed
+ * iframe controlled by your extension.
+ *
+ * To pass a message to a script running in the panel, call sendMessage. The data you pass in will be
+ * sent to the iframe with window.postMessage.
+ *
+ * To pass messages back from the panel to this class, call parent.postMessage from within the iframe.
+ * The data sent will be passed along to the messageFromFrame implementation on your Panel class.
+ */
+export declare abstract class Panel extends IframeUI {
+    protected readonly config: PanelConfig;
+    constructor(client: EditorClient, config: PanelConfig);
+    /**
+     * Show this panel in its specified location, if it is not already visible.
+     */
+    show(): void;
+    /**
+     * Hide this panel if it is currently visible.
+     */
+    hide(): void;
+}

package/sdk/ui/panel.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Panel = exports.PanelLocation = void 0;
+const iframeui_1 = require("./iframeui");
+/**
+ * Semantic locations to place a new menu item.
+ */
+var PanelLocation;
+(function (PanelLocation) {
+    /** In Lucidchart, create a sibling to the Contextual Panel */
+    PanelLocation[PanelLocation["RightDock"] = 1] = "RightDock";
+})(PanelLocation = exports.PanelLocation || (exports.PanelLocation = {}));
+/**
+ * Extend this class to show a custom panel to the user, whose contents are displayed in a sandboxed
+ * iframe controlled by your extension.
+ *
+ * To pass a message to a script running in the panel, call sendMessage. The data you pass in will be
+ * sent to the iframe with window.postMessage.
+ *
+ * To pass messages back from the panel to this class, call parent.postMessage from within the iframe.
+ * The data sent will be passed along to the messageFromFrame implementation on your Panel class.
+ */
+class Panel extends iframeui_1.IframeUI {
+    constructor(client, config) {
+        super(client);
+        this.config = config;
+        this.hookMessages();
+        this.client.sendCommand("rp" /* RegisterPanel */, {
+            'n': this.messageActionName,
+            't': this.config.title,
+            'l': this.config.location,
+            'c': this.config.content,
+            'v': this.config.visibleAction,
+            'i': this.config.iconUrl,
+        });
+    }
+    /**
+     * Show this panel in its specified location, if it is not already visible.
+     */
+    show() {
+        this.client.sendCommand("spn" /* ShowPanel */, { 'n': this.messageActionName });
+    }
+    /**
+     * Hide this panel if it is currently visible.
+     */
+    hide() {
+        this.client.sendCommand("hp" /* HidePanel */, { 'n': this.messageActionName });
+    }
+}
+exports.Panel = Panel;

package/sdk/ui/viewport.d.ts

@@ -1,9 +1,20 @@
 import { ItemProxy } from '../document/itemproxy';
 import { PageProxy } from '../document/pageproxy';
 import { EditorClient } from '../editorclient';
+/**
+ * A text editing hook provided to [Viewport.hookTextEdit](/extension-sdk/#classes_ui_viewport-Viewport_hooktextedit)
+ * may return a TextEditCompletionCallback to specify what behavior should happen when the user finishes editing text.
+ *
+ * If this callback returns false, the edit is reverted.
+ *
+ * If this callback returns a string, the typed value is replaced with that string.
+ */
+export declare type TextEditCompletionCallback = (newValue: string) => boolean | string | Promise<boolean | string>;
 export declare class Viewport {
     private readonly client;
+    private static nextHookId;
     constructor(client: EditorClient);
+    private static nextHookName;
     /**
      * @param deep If true, and groups are selected, include the contents of those groups in the array
      * @returns An array of currently-selected items on the currently-visible page
@@ -24,4 +35,38 @@ export declare class Viewport {
      * @param items The items the camera should zoom to
      */
     focusCameraOnItems(items: ItemProxy[]): void;
+    /**
+     * If `callback` returns false, text editing is prevented.
+     * If `callback` returns true, text editing continues as normal.
+     *
+     * If `callback` returns a [TextEditCompletionCallback](/extension-sdk/#modules_ui_viewport_texteditcompletioncallback), then text editing
+     * is allowed, but that completion callback is called
+     * when the user finishes editing that text. That completion callback may return true or false to allow or deny the edit, or
+     * also may return a replacement string to use instead of the text the user actually typed. If replacement text is provided,
+     * it will be styled as close to the original as possible, but styles that apply to only parts of the original text will be
+     * discarded.
+     *
+     * @param callback Called just before the user starts editing text.
+     *
+     * @returns A handle representing this hook, which can be passed to unhookTextEdit to remove this hook.
+     */
+    hookTextEdit(callback: (item: ItemProxy, textAreaKey: string) => boolean | TextEditCompletionCallback | Promise<boolean | TextEditCompletionCallback>): string;
+    /**
+     * Remove a hook set by hookTextEdit.
+     *
+     * @param handle The return value of hookTextEdit.
+     */
+    unhookTextEdit(handle: string): void;
+    /**
+     * @param callback Called when the user changes their selection of items
+     *
+     * @returns A handle representing this hook, which can be passed to unhookSelection to remove this hook.
+     */
+    hookSelection(callback: (items: ItemProxy[]) => void): string;
+    /**
+     * Remove a hook set by hookSelection.
+     *
+     * @param handle The return value of hookSelection.
+     */
+    unhookSelection(handle: string): void;
 }