lucid-extension-sdk 0.0.6 → 0.0.13

package/sdk/document/elementproxy.js

@@ -4,42 +4,24 @@ exports.ElementProxy = void 0;
 const referencekeydefinition_1 = require("../data/referencekeydefinition");
 const referencekeyproxy_1 = require("../data/referencekeyproxy");
 const mapproxy_1 = require("./mapproxy");
+const propertystoreproxy_1 = require("./propertystoreproxy");
 const shapedataproxy_1 = require("./shapedataproxy");
 /**
  * An element is anything on a Lucid document that can have properties and shape data:
- *  * The document itself
- *  * Pages
- *  * Blocks
- *  * Lines
- *  * Groups
+ *  * [The document itself](#classes_document_documentproxy-DocumentProxy)
+ *  * [Pages](#classes_document_pageproxy-PageProxy)
+ *  * [Blocks](#classes_document_blockproxy-BlockProxy)
+ *  * [Lines](#classes_document_lineproxy-LineProxy)
+ *  * [Groups](#classes_document_groupproxy-GroupProxy)
  */
-class ElementProxy {
+class ElementProxy extends propertystoreproxy_1.PropertyStoreProxy {
     /**
      *
-     * @param id ID of this element, or undefined for the document itself
+     * @param id ID of this element, or `undefined` for the document itself
      * @param client
      */
     constructor(id, client) {
-        this.id = id;
-        this.client = client;
-        /**
-         * All properties available on this element, organized by name.
-         * Not all properties are writeable (e.g. "ClassName" on a block).
-         * To move or resize elements, use setLocation() or setBoundingBox() or offset() instead.
-         */
-        this.properties = new mapproxy_1.WriteableMapProxy(() => this.client.sendCommand("lpr" /* ListProperties */, { 'id': this.id }), (name) => this.client.sendCommand("gp" /* GetProperty */, {
-            'id': this.id,
-            'p': name,
-        }), (name, value) => {
-            if (name === 'BoundingBox') {
-                throw new Error('Do not use properties.set() to move or resize items; use setLocation() or setBoundingBox() or offset()');
-            }
-            this.client.sendCommand("sp" /* SetProperty */, {
-                'id': this.id,
-                'p': name,
-                'v': value,
-            });
-        });
+        super(id, client);
         /**
          * The shape data set directly on this element (not including any shape data inherited from the page or a containing group).
          */
@@ -52,8 +34,19 @@ class ElementProxy {
             'id': this.id,
             'n': name,
         })));
+        /**
+         * The set of reference keys, organized by their ID, which can be either a string or number.
+         *
+         * For more information, see the [Developer Guide](/extension-api#guide-reference-keys).
+         */
         this.referenceKeys = new mapproxy_1.MapProxy(() => this.client.sendCommand("lrk" /* ListReferenceKeys */, { 'id': this.id }), (key) => new referencekeyproxy_1.ReferenceKeyProxy(this.id, key, this.client, this.client.sendCommand("grk" /* GetReferenceKey */, { 'id': this.id, 'k': key })));
     }
+    /**
+     * Set a reference key on this element, replacing any existing reference at the specified key.
+     *
+     * @param key
+     * @param settings
+     */
     setReferenceKey(key, settings) {
         this.client.sendCommand("srk" /* SetReferenceKey */, {
             'id': this.id,
@@ -61,11 +54,15 @@ class ElementProxy {
             'v': (0, referencekeydefinition_1.serializeReferenceKeyDefinition)(settings),
         });
     }
+    /**
+     * Remove the specified reference key from this element.
+     * @param key
+     */
     removeReferenceKey(key) {
         this.client.sendCommand("srk" /* SetReferenceKey */, { 'id': this.id, 'k': key });
     }
     /**
-     * @returns true if this element still exists on the document, or false otherwise
+     * @returns `true` if this element still exists on the document, or `false` otherwise
      */
     exists() {
         return this.client.sendCommand("ee" /* ElementExists */, { 'id': this.id });
@@ -73,7 +70,7 @@ class ElementProxy {
     /**
      * Execute a formula in the context of this element
      * @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.
+     * @returns The result of the formula, or an error.
      */
     executeFormula(formula) {
         return shapedataproxy_1.ShapeDataProxy.parseData(this.client.sendCommand("ef" /* ExecuteFormula */, { 'id': this.id || '', 'f': formula }));

package/sdk/document/groupproxy.d.ts

@@ -2,7 +2,7 @@ import { ItemProxy } from './itemproxy';
 import { LineProxy } from './lineproxy';
 import { MapProxy } from './mapproxy';
 /**
- * A group of items on a page
+ * A group of items on a page.
  */
 export declare class GroupProxy extends ItemProxy {
     /**

package/sdk/document/groupproxy.js

@@ -5,7 +5,7 @@ const itemproxy_1 = require("./itemproxy");
 const lineproxy_1 = require("./lineproxy");
 const mapproxy_1 = require("./mapproxy");
 /**
- * A group of items on a page
+ * A group of items on a page.
  */
 class GroupProxy extends itemproxy_1.ItemProxy {
     constructor() {

package/sdk/document/itemproxy.d.ts

@@ -18,7 +18,7 @@ export declare class ItemProxy extends ElementProxy {
      */
     readonly textAreas: WriteableMapProxy<string, string>;
     /**
-     * @returns the bounding box of this item relative to its containing page. As pages may change size
+     * @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.
      *
      * If this is a rotated block, the bounding box returned here is where the block would be if it were
@@ -37,11 +37,11 @@ export declare class ItemProxy extends ElementProxy {
      */
     setBoundingBox(bb: Box): void;
     /**
-     * @returns the page containing this item
+     * @returns The page containing this item
      */
     getPage(): import("./pageproxy").PageProxy;
     /**
-     * @returns the x/y location of this item
+     * @returns The x/y location of this item
      */
     getLocation(): {
         x: number;
@@ -49,7 +49,7 @@ export declare class ItemProxy extends ElementProxy {
     };
     /**
      * Moves this item so that its upper-left corner is positioned at the given location (prior to any rotation)
-     * @param location the target location
+     * @param location The target location
      */
     setLocation(location: Point): void;
     /**
@@ -63,7 +63,7 @@ export declare class ItemProxy extends ElementProxy {
      */
     delete(): void;
     /**
-     * @returns an array of blocks whose bounding boxes contain this item's upper-left corner
+     * @returns An array of blocks whose bounding boxes contain this item's upper-left corner
      */
     getContainers(): import("./blockproxy").BlockProxy[];
 }

package/sdk/document/itemproxy.js

@@ -28,7 +28,7 @@ class ItemProxy extends elementproxy_1.ElementProxy {
         }));
     }
     /**
-     * @returns the bounding box of this item relative to its containing page. As pages may change size
+     * @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.
      *
      * If this is a rotated block, the bounding box returned here is where the block would be if it were
@@ -60,13 +60,13 @@ class ItemProxy extends elementproxy_1.ElementProxy {
         }
     }
     /**
-     * @returns the page containing this item
+     * @returns The page containing this item
      */
     getPage() {
         return this.client.getPageProxy(this.client.sendCommand("gip" /* GetItemPageId */, this.id));
     }
     /**
-     * @returns the x/y location of this item
+     * @returns The x/y location of this item
      */
     getLocation() {
         const bb = this.getBoundingBox();
@@ -74,7 +74,7 @@ class ItemProxy extends elementproxy_1.ElementProxy {
     }
     /**
      * Moves this item so that its upper-left corner is positioned at the given location (prior to any rotation)
-     * @param location the target location
+     * @param location The target location
      */
     setLocation(location) {
         const current = this.getBoundingBox();
@@ -97,7 +97,7 @@ class ItemProxy extends elementproxy_1.ElementProxy {
         this.client.sendCommand("di" /* DeleteItem */, this.id);
     }
     /**
-     * @returns an array of blocks whose bounding boxes contain this item's upper-left corner
+     * @returns An array of blocks whose bounding boxes contain this item's upper-left corner
      */
     getContainers() {
         const containers = this.executeFormula('LABEL(CONTAINEDBY)');

package/sdk/document/lineproxy.d.ts

@@ -2,6 +2,7 @@ import { Point } from '../math';
 import { BlockProxy } from './blockproxy';
 import { ItemProxy } from './itemproxy';
 import { EndpointDefinition } from './linedefinition';
+import { LineTextAreaPositioning } from './linetextareapositioning';
 /**
  * A line on the current Lucid document
  */
@@ -12,14 +13,14 @@ export declare class LineProxy extends ItemProxy {
     private parseLineEndpointDefinition;
     private serializeLineEndpointDefinition;
     /**
-     * @returns the definition of the first endpoint of this line
+     * @returns The definition of the first endpoint of this line
      */
     getEndpoint1(): EndpointDefinition & {
         x: number;
         y: number;
     };
     /**
-     * @returns the definition of the second endpoint of this line
+     * @returns The definition of the second endpoint of this line
      */
     getEndpoint2(): EndpointDefinition & {
         x: number;
@@ -36,20 +37,45 @@ export declare class LineProxy extends ItemProxy {
      */
     setEndpoint2(endpoint: EndpointDefinition): void;
     /**
-     * @returns the block or line connected to the first endpoint of this line, or undefined if none
+     * @returns The block or line connected to the first endpoint of this line, or `undefined` if none
      */
     getUpstreamConnection(): void | BlockProxy | LineProxy | undefined;
     /**
-     * @returns the block or line connected to the second endpoint of this line, or undefined if none
+     * @returns The block or line connected to the second endpoint of this line, or `undefined` if none
      */
     getDownstreamConnection(): void | BlockProxy | LineProxy | undefined;
     /**
-     * @returns a list of lines whose endpoints are connected to this line
+     * @returns A list of lines whose endpoints are connected to this line
      */
     getConnectedLines(): LineProxy[];
     /**
      * @param relative A distance, between 0 and 1, between the first and second endpoint of this line
-     * @returns the coordinate of that relative position, relative to the containing page
+     * @returns The coordinate of that relative position, relative to the containing page
      */
     getRelativePosition(relative: number): Point;
+    /**
+     *
+     * @param name
+     * @returns The position of the given text area on this line, if it exists, or undefined if it does not exist.
+     */
+    getTextAreaPosition(name: string): LineTextAreaPositioning | undefined;
+    /**
+     * Updates the position of the given text area, if it exists. If not, an error is thrown.
+     * @param name
+     * @param position
+     */
+    setTextAreaPosition(name: string, position: LineTextAreaPositioning): void;
+    /**
+     * Adds a new text area to this line at the given location with the given initial plain text.
+     * The text will be styled with the document theme, if any.
+     * @param text
+     * @param position
+     * @returns The name of the text area added
+     */
+    addTextArea(text: string, position: LineTextAreaPositioning): string;
+    /**
+     * Deletes the given text area from the line, if it exists.
+     * @param name
+     */
+    deleteTextArea(name: string): void;
 }

package/sdk/document/lineproxy.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LineProxy = void 0;
+const checks_1 = require("../core/checks");
 const blockproxy_1 = require("./blockproxy");
 const itemproxy_1 = require("./itemproxy");
+const linetextareapositioning_1 = require("./linetextareapositioning");
 /**
  * A line on the current Lucid document
  */
@@ -85,13 +87,13 @@ class LineProxy extends itemproxy_1.ItemProxy {
         }
     }
     /**
-     * @returns the definition of the first endpoint of this line
+     * @returns The definition of the first endpoint of this line
      */
     getEndpoint1() {
         return this.parseLineEndpointDefinition(this.properties.get('Endpoint1'));
     }
     /**
-     * @returns the definition of the second endpoint of this line
+     * @returns The definition of the second endpoint of this line
      */
     getEndpoint2() {
         return this.parseLineEndpointDefinition(this.properties.get('Endpoint2'));
@@ -111,19 +113,19 @@ class LineProxy extends itemproxy_1.ItemProxy {
         this.properties.set('Endpoint2', this.serializeLineEndpointDefinition(endpoint));
     }
     /**
-     * @returns the block or line connected to the first endpoint of this line, or undefined if none
+     * @returns The block or line connected to the first endpoint of this line, or `undefined` if none
      */
     getUpstreamConnection() {
         return this.getEndpoint1().connection;
     }
     /**
-     * @returns the block or line connected to the second endpoint of this line, or undefined if none
+     * @returns The block or line connected to the second endpoint of this line, or `undefined` if none
      */
     getDownstreamConnection() {
         return this.getEndpoint2().connection;
     }
     /**
-     * @returns a list of lines whose endpoints are connected to this line
+     * @returns A list of lines whose endpoints are connected to this line
      */
     getConnectedLines() {
         const ids = this.client.sendCommand("gcl" /* GetConnectedLines */, this.id);
@@ -131,10 +133,54 @@ class LineProxy extends itemproxy_1.ItemProxy {
     }
     /**
      * @param relative A distance, between 0 and 1, between the first and second endpoint of this line
-     * @returns the coordinate of that relative position, relative to the containing page
+     * @returns The coordinate of that relative position, relative to the containing page
      */
     getRelativePosition(relative) {
         return this.client.sendCommand("grlp" /* GetRelativeLinePosition */, { 'id': this.id, 'p': relative });
     }
+    /**
+     *
+     * @param name
+     * @returns The position of the given text area on this line, if it exists, or undefined if it does not exist.
+     */
+    getTextAreaPosition(name) {
+        const serializedTextAreas = this.properties.get('TextAreas');
+        if ((0, checks_1.isObject)(serializedTextAreas)) {
+            const rawEntry = serializedTextAreas[name];
+            if ((0, linetextareapositioning_1.isSerializedLineTextAreaPositioning)(rawEntry)) {
+                return (0, linetextareapositioning_1.deserializeLineTextAreaPositioning)(rawEntry);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Updates the position of the given text area, if it exists. If not, an error is thrown.
+     * @param name
+     * @param position
+     */
+    setTextAreaPosition(name, position) {
+        this.properties.set('TextAreas', { [name]: (0, linetextareapositioning_1.serializeLineTextAreaPositioning)(position) });
+    }
+    /**
+     * Adds a new text area to this line at the given location with the given initial plain text.
+     * The text will be styled with the document theme, if any.
+     * @param text
+     * @param position
+     * @returns The name of the text area added
+     */
+    addTextArea(text, position) {
+        return this.client.sendCommand("alta" /* AddLineTextArea */, {
+            'id': this.id,
+            'p': (0, linetextareapositioning_1.serializeLineTextAreaPositioning)(position),
+            't': text,
+        });
+    }
+    /**
+     * Deletes the given text area from the line, if it exists.
+     * @param name
+     */
+    deleteTextArea(name) {
+        this.properties.set('TextAreas', { [name]: null });
+    }
 }
 exports.LineProxy = LineProxy;

package/sdk/document/linetextareapositioning.d.ts

@@ -0,0 +1,31 @@
+export interface LineTextAreaPositioning {
+    /**
+     * A number between 0 and 1 representing how far this text lies along the line, where 0 puts the text
+     * at the same location as the first endpoint, and 1 puts the text at the same location as the second
+     * endpoint.
+     */
+    location: number;
+    /**
+     * Which side of the line the text is displayed on. If zero, the text is on top of the line. If -1,
+     * the text is to the left of the line as you travel from the first to second endpoints. If 1, the
+     * text is to the right of the line as you travel from the first to second endpoints.
+     */
+    side: -1 | 0 | 1;
+    /**
+     * Normally text on a line is not allowed to overlap a block that is connected to either end of the
+     * line. If `allowOverBlock` is true, then the text is allowed to overlap an attached block.
+     */
+    allowOverBlock?: boolean;
+}
+/** @ignore */
+export declare type SerializedLineTextAreaPositioning = {
+    'Location': number;
+    'Side': -1 | 0 | 1;
+    'AllowOverBlock'?: boolean;
+};
+/** @ignore */
+export declare function isSerializedLineTextAreaPositioning(raw: unknown): raw is SerializedLineTextAreaPositioning;
+/** @ignore */
+export declare function deserializeLineTextAreaPositioning(raw: SerializedLineTextAreaPositioning): LineTextAreaPositioning;
+/** @ignore */
+export declare function serializeLineTextAreaPositioning(data: LineTextAreaPositioning): SerializedLineTextAreaPositioning;

package/sdk/document/linetextareapositioning.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeLineTextAreaPositioning = exports.deserializeLineTextAreaPositioning = exports.isSerializedLineTextAreaPositioning = void 0;
+const checks_1 = require("../core/checks");
+/** @ignore */
+function isSerializedLineTextAreaPositioning(raw) {
+    return ((0, checks_1.isObject)(raw) &&
+        (0, checks_1.isNumber)(raw['Location']) &&
+        (0, checks_1.isNumber)(raw['Side']) &&
+        ((0, checks_1.isBoolean)(raw['AllowOverBlock']) || (0, checks_1.isUndefined)(raw['AllowOverBlock'])));
+}
+exports.isSerializedLineTextAreaPositioning = isSerializedLineTextAreaPositioning;
+/** @ignore */
+function deserializeLineTextAreaPositioning(raw) {
+    return {
+        location: raw['Location'],
+        side: raw['Side'],
+        allowOverBlock: raw['AllowOverBlock'],
+    };
+}
+exports.deserializeLineTextAreaPositioning = deserializeLineTextAreaPositioning;
+/** @ignore */
+function serializeLineTextAreaPositioning(data) {
+    return {
+        'Location': data.location,
+        'Side': data.side,
+        'AllowOverBlock': data.allowOverBlock,
+    };
+}
+exports.serializeLineTextAreaPositioning = serializeLineTextAreaPositioning;

package/sdk/document/mapproxy.d.ts

@@ -1,10 +1,16 @@
+/**
+ * A data structure similar to a normal Map which accesses its data through API
+ * commands to the Lucid app. This structure is iterable with `for...of`.
+ */
 export declare class MapProxy<KEY, VALUE> {
     private readonly getKeys;
     private readonly getItem;
     constructor(getKeys: () => KEY[], getItem: (key: KEY) => VALUE);
+    /** @ignore */
     [Symbol.iterator](): Iterator<[KEY, VALUE]>;
-    values(): Iterator<VALUE>;
+    values(): Generator<VALUE, void, unknown>;
     keys(): KEY[];
+    get size(): number;
     get(key: KEY): VALUE;
     first(): VALUE | undefined;
 }

package/sdk/document/mapproxy.js

@@ -1,11 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WriteableMapProxy = exports.MapProxy = void 0;
+/**
+ * A data structure similar to a normal Map which accesses its data through API
+ * commands to the Lucid app. This structure is iterable with `for...of`.
+ */
 class MapProxy {
     constructor(getKeys, getItem) {
         this.getKeys = getKeys;
         this.getItem = getItem;
     }
+    /** @ignore */
     *[Symbol.iterator]() {
         for (const key of this.keys()) {
             const value = this.get(key);
@@ -25,6 +30,9 @@ class MapProxy {
     keys() {
         return this.getKeys();
     }
+    get size() {
+        return this.keys().length;
+    }
     get(key) {
         return this.getItem(key);
     }

package/sdk/document/propertystoreproxy.d.ts

@@ -0,0 +1,21 @@
+import { EditorClient } from '../editorclient';
+import { WriteableMapProxy } from './mapproxy';
+/**
+ * Base class for anything on a Lucid document that has an ID and properties.
+ */
+export declare class PropertyStoreProxy {
+    readonly id: string | undefined;
+    protected readonly client: EditorClient;
+    /**
+     * All properties available on this element, organized by name.
+     * 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("..").JsonSerializable>;
+    /**
+     *
+     * @param id ID of this element, or undefined for the document itself
+     * @param client
+     */
+    constructor(id: string | undefined, client: EditorClient);
+}

package/sdk/document/propertystoreproxy.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyStoreProxy = void 0;
+const mapproxy_1 = require("./mapproxy");
+/**
+ * Base class for anything on a Lucid document that has an ID and properties.
+ */
+class PropertyStoreProxy {
+    /**
+     *
+     * @param id ID of this element, or undefined for the document itself
+     * @param client
+     */
+    constructor(id, client) {
+        this.id = id;
+        this.client = client;
+        /**
+         * All properties available on this element, organized by name.
+         * Not all properties are writeable (e.g. "ClassName" on a block).
+         * To move or resize elements, use setLocation() or setBoundingBox() or offset() instead.
+         */
+        this.properties = new mapproxy_1.WriteableMapProxy(() => this.client.sendCommand("lpr" /* ListProperties */, { 'id': this.id }), (name) => this.client.sendCommand("gp" /* GetProperty */, {
+            'id': this.id,
+            'p': name,
+        }), (name, value) => {
+            if (name === 'BoundingBox') {
+                throw new Error('Do not use properties.set() to move or resize items; use setLocation() or setBoundingBox() or offset()');
+            }
+            this.client.sendCommand("sp" /* SetProperty */, {
+                'id': this.id,
+                'p': name,
+                'v': value,
+            });
+        });
+    }
+}
+exports.PropertyStoreProxy = PropertyStoreProxy;

package/sdk/document/shapedataproxy.d.ts

@@ -14,6 +14,11 @@ export declare class ShapeDataProxy extends WriteableMapProxy<string, Serialized
      * @param client
      */
     constructor(id: string | undefined, client: EditorClient);
+    /**
+     * Delete the specified shape data from this element
+     * @param key
+     */
     delete(key: string): void;
+    /** @ignore */
     static parseData(raw: SerializedFieldType | SerializedDataError): SerializedFieldType | DataError;
 }

package/sdk/document/shapedataproxy.js

@@ -36,11 +36,16 @@ class ShapeDataProxy extends mapproxy_1.WriteableMapProxy {
         this.id = id;
         this.client = client;
     }
+    /**
+     * Delete the specified shape data from this element
+     * @param key
+     */
     delete(key) {
         if (this.keys().includes(key)) {
             this.client.sendCommand("dsd" /* DeleteShapeData */, { 'id': this.id, 'n': key });
         }
     }
+    /** @ignore */
     static parseData(raw) {
         if ((0, serializeddataerror_1.isSerializedDataError)(raw)) {
             return new dataerror_1.DataError(raw['error'], raw['type']);

package/sdk/editorclient.d.ts

@@ -3,6 +3,7 @@ import { JsonSerializable } from './core/jsonserializable';
 import { BlockDefinition } from './document/blockdefinition';
 import { BlockProxy } from './document/blockproxy';
 import { ElementProxy } from './document/elementproxy';
+import { GroupProxy } from './document/groupproxy';
 import { LineProxy } from './document/lineproxy';
 import { PageProxy } from './document/pageproxy';
 export interface XHRRequest {
@@ -60,6 +61,7 @@ export declare class EditorClient {
      *   code is not 2xx, the promise will reject.
      */
     xhr(request: XHRRequest): Promise<XHRResponse>;
+    oauthXhr(providerName: string, request: XHRRequest): Promise<XHRResponse>;
     /**
      * Register a named action. These actions can be triggered from custom UI, for example as the action of a
      * custom menu item.
@@ -89,7 +91,6 @@ 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
@@ -118,7 +119,7 @@ export declare class EditorClient {
      * created.
      *
      * Example usage:
-     * ```
+     * ```inline:typescript
      * const client = new EditorClient();
      * const viewport = new Viewport(client);
      *
@@ -164,6 +165,11 @@ export declare class EditorClient {
      * @returns the given page
      */
     getPageProxy(id: string): PageProxy;
+    /**
+     * @param id ID of the item to create a proxy for
+     * @returns the given item
+     */
+    getItemProxy(id: string): BlockProxy | LineProxy | GroupProxy;
     /**
      * @param id ID of the element to create a proxy for
      * @returns the given element