lucid-extension-sdk 0.0.1 → 0.0.2

package/README.md

@@ -4,6 +4,113 @@
 
 TypeScript SDK for building in-editor extensions for the products of Lucid Software.
 
+## Getting started
+
+To get started building an extension for Lucid products, follow the instructions in
+the [`lucid-package` CLI](https://www.npmjs.com/package/lucid-package).
+
+## Simple examples
+
+### Add a new entry in the main menu
+
+```
+import {EditorClient, Menu, MenuType} from 'lucid-extension-sdk';
+
+const client = new EditorClient();
+const menu = new Menu(client);
+
+client.registerAction('my-new-action', () => {
+    console.log('Hello world');
+});
+
+menu.addMenuItem({
+    label: 'Hello world',
+    action: 'my-new-action',
+    menuType: MenuType.Main,
+});
+```
+
+### Create a new page and add some shapes to it
+
+```
+import {DocumentProxy, EditorClient, Menu, MenuType, Viewport} from 'lucid-extension-sdk';
+
+const client = new EditorClient();
+const menu = new Menu(client);
+const viewport = new Viewport(client);
+const document = new DocumentProxy(client);
+
+client.registerAction('create-content', async () => {
+    const page = document.addPage({title: 'Hello world'});
+    viewport.setCurrentPage(page);
+
+    //Before creating any blocks, you must make sure the code
+    //for that kind of block is loaded.
+    await client.loadBlockClasses(['ProcessBlock']);
+
+    let y = 0;
+    for (const char of 'Hello world') {
+        const block = page.addBlock({
+            className: 'ProcessBlock',
+            boundingBox: {
+                x: 0,
+                y,
+                w: 60,
+                h: 60,
+            },
+        });
+
+        const textAreaName = block.textAreas.keys()[0];
+        block.textAreas.set(textAreaName, char);
+
+        y += 80;
+    }
+});
+
+menu.addMenuItem({
+    label: 'Hello world',
+    action: 'create-content',
+    menuType: MenuType.Main,
+});
+```
+
+### Create and download a CSV with shape data from the current page
+
+```
+import {EditorClient, Menu, MenuLocation, MenuType, Viewport} from 'lucid-extension-sdk';
+
+const client = new EditorClient();
+const menu = new Menu(client);
+const viewport = new Viewport(client);
+
+client.registerAction('download', async () => {
+    const page = viewport.getCurrentPage();
+    if (!page) {
+        return;
+    }
+
+    const csv: string[][] = [['Type', 'ID', 'Text', 'DataValue']];
+
+    for (const [id, block] of page?.allBlocks) {
+        csv.push([
+            block.getClassName(),
+            block.id,
+            block.textAreas.first() ?? '',
+            JSON.stringify(block.allShapeData.get('DataValue')),
+        ]);
+    }
+
+    client.download('data.csv', csv.map((line) => line.join(',')).join('\n'), 'text/plain', false);
+});
+
+menu.addMenuItem({
+    label: 'Download CSV',
+    action: 'download',
+    menuType: MenuType.Main,
+    location: MenuLocation.Export, //Near File -> Export
+});
+```
+
 ## License
 
 This project is distributed under the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "description": "Utility classes for writing Lucid Software editor extensions",
     "main": "sdk/index.js",
     "types": "sdk/index.d.ts",
@@ -8,8 +8,9 @@
     "license": "Apache-2.0",
     "declaration": true,
     "devDependencies": {
-        "@types/node": "^16.11.11",
         "@bazel/typescript": "2.0.1",
+        "@types/node": "^16.11.11",
+        "typedoc": "^0.22.11",
         "typescript": "4.3.5"
     }
 }

package/sdk/core/serializedfields.d.ts

@@ -1,7 +1,3 @@
-/**
- * Once we have full server support for complex field types,
- * we should be able to support object/array data here
- */
 export declare type SerializedFieldType = number | boolean | string | null | SerializedLucidDateObject | SerializedColorObjectFieldType | SerializedLucidDictionary | SerializedLucidCurrency | undefined | Array<SerializedFieldType>;
 export declare type SerializedLucidDictionary = {
     'dict': {

package/sdk/data/collectionproxy.d.ts

@@ -36,5 +36,5 @@ export declare class CollectionProxy extends ElementProxy {
     /**
      * @returns an array of field names that are accessible on the items in this collection
      */
-    getFields(): import("../commandtypes").ListCollectionFieldsResult;
+    getFields(): string[];
 }

package/sdk/data/dataitemproxy.d.ts

@@ -17,5 +17,5 @@ export declare class DataItemProxy {
     /**
      * The fields on this data item, organized by their name.
      */
-    readonly fields: MapProxy<string, import("../core/serializedfields").SerializedFieldType>;
+    readonly fields: MapProxy<string, import("..").SerializedFieldType>;
 }

package/sdk/document/blockclasses/erdblockproxy.d.ts

@@ -4,8 +4,8 @@ export declare class ERDFieldProxy {
     private readonly index;
     constructor(block: ERDBlockProxy, index: number);
     getName(): string;
-    getType(): string | number | boolean | import("../../core/jsonserializable").JsonArray | import("../../core/jsonserializable").JsonObject;
-    getKey(): string | number | boolean | import("../../core/jsonserializable").JsonArray | import("../../core/jsonserializable").JsonObject;
+    getType(): string | number | boolean | import("../..").JsonArray | import("../..").JsonObject;
+    getKey(): string | number | boolean | import("../..").JsonArray | import("../..").JsonObject;
 }
 export declare class ERDBlockProxy extends BlockProxy {
     static classNameRegex: RegExp;

package/sdk/document/elementproxy.d.ts

@@ -17,7 +17,7 @@ export declare class ElementProxy {
      * Not all properties are writeable (e.g. "ClassName" on a block).
      * To move or resize elements, use setLocation() or setBoundingBox() or offset() instead.
      */
-    readonly properties: WriteableMapProxy<string, import("../core/jsonserializable").JsonSerializable>;
+    readonly properties: WriteableMapProxy<string, import("..").JsonSerializable>;
     /**
      * The shape data set directly on this element (not including any shape data inherited from the page or a containing group).
      */
@@ -26,7 +26,7 @@ export declare class ElementProxy {
      * All shape data accessible on this element, including shape data inherited from the page or a containing group.
      * This collection is read-only.
      */
-    readonly allShapeData: MapProxy<string, import("../core/serializedfields").SerializedFieldType | import("../data/dataerror").DataError>;
+    readonly allShapeData: MapProxy<string, import("..").SerializedFieldType | import("..").DataError>;
     /**
      *
      * @param id ID of this element, or undefined for the document itself
@@ -42,5 +42,5 @@ export declare class ElementProxy {
      * @param formula The formula text, e.g. "@a + @b" to add together the shape data values a and b.
      * @returns the result of the formula, or an error.
      */
-    executeFormula(formula: string): import("../core/serializedfields").SerializedFieldType | import("../data/dataerror").DataError;
+    executeFormula(formula: string): import("..").SerializedFieldType | import("..").DataError;
 }

package/sdk/document/itemproxy.d.ts

@@ -2,7 +2,7 @@ import { LinearOffsetType } from '../core/offsettype';
 import { EditorClient } from '../editorclient';
 import { Box, Point } from '../math';
 import { ElementProxy } from './elementproxy';
-import { MapProxy } from './mapproxy';
+import { WriteableMapProxy } from './mapproxy';
 /**
  * A block, line, or group on a page of the current document.
  */
@@ -16,7 +16,7 @@ export declare class ItemProxy extends ElementProxy {
     /**
      * The plain text in each of the text areas on this item, organized by text area name.
      */
-    readonly textAreas: MapProxy<string, string>;
+    readonly textAreas: WriteableMapProxy<string, string>;
     /**
      * @returns the bounding box of this item relative to its containing page. As pages may change size
      * to fit the content on them, note that these coordinates may be negative or very large.

package/sdk/document/itemproxy.js

@@ -18,9 +18,13 @@ class ItemProxy extends elementproxy_1.ElementProxy {
         /**
          * The plain text in each of the text areas on this item, organized by text area name.
          */
-        this.textAreas = new mapproxy_1.MapProxy(() => this.client.sendCommand("lta" /* ListTextAreas */, this.id), (name) => this.client.sendCommand("gp" /* GetProperty */, {
+        this.textAreas = new mapproxy_1.WriteableMapProxy(() => this.client.sendCommand("lta" /* ListTextAreas */, this.id), (name) => this.client.sendCommand("gp" /* GetProperty */, {
             'id': this.id,
             'p': name,
+        }), (name, plainText) => this.client.sendCommand("sp" /* SetProperty */, {
+            'id': this.id,
+            'p': name,
+            'v': plainText,
         }));
     }
     /**

package/sdk/editorclient.d.ts

@@ -62,12 +62,17 @@ export declare class EditorClient {
      * Register a named action. These actions can be triggered from custom UI, for example as the action of a
      * custom menu item.
      *
-     * Throws an error if the same action is registered multiple times.
+     * Some actions may return a value that is used by the core application, e.g. a `visibleAction` for a menu
+     * item. However, if you return a `Promise` from your callback, that value will be discarded and your
+     * action will return `undefined` instead. The ability to provide a callback that returns a Promise is only
+     * a convenience so that you can register actions with `async` callbacks for easy async/await.
+     *
+     * Throws an error if the same action name is registered multiple times.
      *
      * @param name name of the action
      * @param callback function to execute when this action is invoked
      */
-    registerAction(name: string, callback: (value: any) => JsonSerializable | void): void;
+    registerAction(name: string, callback: (value: any) => JsonSerializable | void | Promise<any>): void;
     /**
      * Remove the callback for a given action. If the action is later invoked, nothing will happen.
      * @param name name of the action to unregister
@@ -82,6 +87,7 @@ export declare 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
@@ -120,6 +126,9 @@ export declare class EditorClient {
      * @returns the given element
      */
     getElementProxy(id: string): ElementProxy;
+    /**
+     * @hidden
+     */
     protected listenToEditor(): void;
     constructor();
 }

package/sdk/editorclient.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EditorClient = void 0;
+const checks_1 = require("./core/checks");
 const blockproxyregistry_1 = require("./document/blockclasses/blockproxyregistry");
 const blockproxy_1 = require("./document/blockproxy");
 const documentproxy_1 = require("./document/documentproxy");
@@ -78,7 +79,12 @@ class EditorClient {
      * Register a named action. These actions can be triggered from custom UI, for example as the action of a
      * custom menu item.
      *
-     * Throws an error if the same action is registered multiple times.
+     * Some actions may return a value that is used by the core application, e.g. a `visibleAction` for a menu
+     * item. However, if you return a `Promise` from your callback, that value will be discarded and your
+     * action will return `undefined` instead. The ability to provide a callback that returns a Promise is only
+     * a convenience so that you can register actions with `async` callbacks for easy async/await.
+     *
+     * Throws an error if the same action name is registered multiple times.
      *
      * @param name name of the action
      * @param callback function to execute when this action is invoked
@@ -111,6 +117,7 @@ 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
@@ -182,10 +189,17 @@ class EditorClient {
                 return new elementproxy_1.ElementProxy(id, this);
         }
     }
+    /**
+     * @hidden
+     */
     listenToEditor() {
         lucid.listen((msg) => {
             var _a;
-            return (_a = this.callbacks.get(msg['id'])) === null || _a === void 0 ? void 0 : _a(msg);
+            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;
         });
     }
 }

package/sdk/index.d.ts

@@ -1,7 +1,29 @@
-export { DataProxy } from './data/dataproxy';
-export { DocumentProxy } from './document/documentproxy';
-export { EditorClient } from './editorclient';
-export { AlertModal } from './ui/alertmodal';
-export { CustomMenuItem, Menu, MenuLocation, MenuType } from './ui/menu';
-export { Modal } from './ui/modal';
-export { Viewport } from './ui/viewport';
+export * from './core/dataerrortype';
+export * from './core/jsonserializable';
+export * from './core/offsettype';
+export * from './core/serializeddataerror';
+export * from './core/serializedfields';
+export * from './core/shapedatainheritance';
+export * from './data/collectionproxy';
+export * from './data/dataerror';
+export * from './data/dataitemproxy';
+export * from './data/dataproxy';
+export * from './data/datasourceproxy';
+export * from './document/blockdefinition';
+export * from './document/blockproxy';
+export * from './document/documentproxy';
+export * from './document/elementproxy';
+export * from './document/groupproxy';
+export * from './document/itemproxy';
+export * from './document/linedefinition';
+export * from './document/lineproxy';
+export * from './document/mapproxy';
+export * from './document/pagedefinition';
+export * from './document/pageproxy';
+export * from './document/shapedataproxy';
+export * from './editorclient';
+export * from './math';
+export * from './ui/alertmodal';
+export * from './ui/menu';
+export * from './ui/modal';
+export * from './ui/viewport';

package/sdk/index.js

@@ -1,19 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Viewport = exports.Modal = exports.MenuType = exports.MenuLocation = exports.Menu = exports.AlertModal = exports.EditorClient = exports.DocumentProxy = exports.DataProxy = void 0;
-var dataproxy_1 = require("./data/dataproxy");
-Object.defineProperty(exports, "DataProxy", { enumerable: true, get: function () { return dataproxy_1.DataProxy; } });
-var documentproxy_1 = require("./document/documentproxy");
-Object.defineProperty(exports, "DocumentProxy", { enumerable: true, get: function () { return documentproxy_1.DocumentProxy; } });
-var editorclient_1 = require("./editorclient");
-Object.defineProperty(exports, "EditorClient", { enumerable: true, get: function () { return editorclient_1.EditorClient; } });
-var alertmodal_1 = require("./ui/alertmodal");
-Object.defineProperty(exports, "AlertModal", { enumerable: true, get: function () { return alertmodal_1.AlertModal; } });
-var menu_1 = require("./ui/menu");
-Object.defineProperty(exports, "Menu", { enumerable: true, get: function () { return menu_1.Menu; } });
-Object.defineProperty(exports, "MenuLocation", { enumerable: true, get: function () { return menu_1.MenuLocation; } });
-Object.defineProperty(exports, "MenuType", { enumerable: true, get: function () { return menu_1.MenuType; } });
-var modal_1 = require("./ui/modal");
-Object.defineProperty(exports, "Modal", { enumerable: true, get: function () { return modal_1.Modal; } });
-var viewport_1 = require("./ui/viewport");
-Object.defineProperty(exports, "Viewport", { enumerable: true, get: function () { return viewport_1.Viewport; } });
+__exportStar(require("./core/dataerrortype"), exports);
+__exportStar(require("./core/jsonserializable"), exports);
+__exportStar(require("./core/offsettype"), exports);
+__exportStar(require("./core/serializeddataerror"), exports);
+__exportStar(require("./core/serializedfields"), exports);
+__exportStar(require("./core/shapedatainheritance"), exports);
+__exportStar(require("./data/collectionproxy"), exports);
+__exportStar(require("./data/dataerror"), exports);
+__exportStar(require("./data/dataitemproxy"), exports);
+__exportStar(require("./data/dataproxy"), exports);
+__exportStar(require("./data/datasourceproxy"), exports);
+__exportStar(require("./document/blockdefinition"), exports);
+__exportStar(require("./document/blockproxy"), exports);
+__exportStar(require("./document/documentproxy"), exports);
+__exportStar(require("./document/elementproxy"), exports);
+__exportStar(require("./document/groupproxy"), exports);
+__exportStar(require("./document/itemproxy"), exports);
+__exportStar(require("./document/linedefinition"), exports);
+__exportStar(require("./document/lineproxy"), exports);
+__exportStar(require("./document/mapproxy"), exports);
+__exportStar(require("./document/pagedefinition"), exports);
+__exportStar(require("./document/pageproxy"), exports);
+__exportStar(require("./document/shapedataproxy"), exports);
+__exportStar(require("./editorclient"), exports);
+__exportStar(require("./math"), exports);
+__exportStar(require("./ui/alertmodal"), exports);
+__exportStar(require("./ui/menu"), exports);
+__exportStar(require("./ui/modal"), exports);
+__exportStar(require("./ui/viewport"), exports);