lucid-extension-sdk 0.0.0 → 0.0.1

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.0",
+    "version": "0.0.1",
     "description": "Utility classes for writing Lucid Software editor extensions",
-    "main": "out/index.js",
-    "types": "out/index.d.ts",
+    "main": "sdk/index.js",
+    "types": "sdk/index.d.ts",
     "author": "Lucid Software",
     "license": "Apache-2.0",
     "declaration": true,

package/sdk/core/dataerrortype.d.ts

@@ -0,0 +1,34 @@
+export declare const enum DataErrorType {
+    /**
+     * A formula syntax error occurred
+     */
+    Parse = 1,
+    /**
+     * The formula directly or indirectly references itself. For example, if you have shape data
+     *   a = @b
+     *   b = @c
+     *   c = @a
+     *
+     * when trying to evaluate any of those values, they eventually reference themselves, and thus
+     * cannot be evaluated.
+     */
+    Loop = 2,
+    /**
+     * The formula contains a reference to an entity that does not exist, e.g. an incorrect shape
+     * data name, field name, or object ID.
+     */
+    ReferenceNotFound = 3,
+    /**
+     * An error occurred specific to a particular formula feature, e.g. adding together values of
+     * two different currencies.
+     */
+    Evaluation = 4,
+    /**
+     * The formula attempts to call a function that does not exist.
+     */
+    InvalidFunction = 5,
+    /**
+     * The formula passes an invalid parameter to a function.
+     */
+    InvalidParameter = 6
+}

package/{out → sdk}/core/jsonserializable.d.ts

@@ -5,4 +5,7 @@ export interface JsonObject {
 export interface JsonObjectConvertible {
     toJsonObject(): JsonObject;
 }
+/**
+ * Any type that can be natively converted to a string with JSON.stringify.
+ */
 export declare type JsonSerializable = undefined | null | string | number | boolean | JsonArray | JsonObject;

package/sdk/core/offsettype.d.ts

@@ -0,0 +1,46 @@
+/**
+ * When adjusting the size or location of items on a page, these are the specific operations that are available.
+ */
+export declare enum OffsetType {
+    /**
+     * Resize from the northwest (upper-left) corner of the selection, anchoring the lower-right corner in place.
+     */
+    NW = 0,
+    /**
+     * Resize from the northeast (upper-right) corner of the selection, anchoring the lower-left corner in place.
+     */
+    NE = 1,
+    /**
+     * Resize from the southeast (lower-right) corner of the selection, anchoring the upper-left corner in place.
+     */
+    SE = 2,
+    /**
+     * Resize from the southwest (lower-left) corner of the selection, anchoring the upper-right corner in place.
+     */
+    SW = 3,
+    /**
+     * Move the selection without resizing.
+     */
+    MOVE = 4,
+    ROTATE = 5,
+    SCALE = 6,
+    CUSTOM = 7,
+    /**
+     * Resize from the north (upper) side of the selection, stretching vertically.
+     */
+    N = 8,
+    /**
+     * Resize from the east (right) side of the selection, stretching horizontally.
+     */
+    E = 9,
+    /**
+     * Resize from the south (lower) side of the selection, stretching vertically.
+     */
+    S = 10,
+    /**
+     * Resize from the west (left) side of the selection, stretching horizontally.
+     */
+    W = 11
+}
+export declare type LinearOffsetType = OffsetType.NW | OffsetType.NE | OffsetType.SE | OffsetType.SW | OffsetType.MOVE | OffsetType.N | OffsetType.E | OffsetType.S | OffsetType.W;
+export declare function isLinearOffsetType(offsetType: unknown): offsetType is LinearOffsetType;

package/{out → sdk}/core/offsettype.js

@@ -1,19 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLinearOffsetType = exports.OffsetType = void 0;
+/**
+ * When adjusting the size or location of items on a page, these are the specific operations that are available.
+ */
 var OffsetType;
 (function (OffsetType) {
+    /**
+     * Resize from the northwest (upper-left) corner of the selection, anchoring the lower-right corner in place.
+     */
     OffsetType[OffsetType["NW"] = 0] = "NW";
+    /**
+     * Resize from the northeast (upper-right) corner of the selection, anchoring the lower-left corner in place.
+     */
     OffsetType[OffsetType["NE"] = 1] = "NE";
+    /**
+     * Resize from the southeast (lower-right) corner of the selection, anchoring the upper-left corner in place.
+     */
     OffsetType[OffsetType["SE"] = 2] = "SE";
+    /**
+     * Resize from the southwest (lower-left) corner of the selection, anchoring the upper-right corner in place.
+     */
     OffsetType[OffsetType["SW"] = 3] = "SW";
+    /**
+     * Move the selection without resizing.
+     */
     OffsetType[OffsetType["MOVE"] = 4] = "MOVE";
     OffsetType[OffsetType["ROTATE"] = 5] = "ROTATE";
     OffsetType[OffsetType["SCALE"] = 6] = "SCALE";
     OffsetType[OffsetType["CUSTOM"] = 7] = "CUSTOM";
+    /**
+     * Resize from the north (upper) side of the selection, stretching vertically.
+     */
     OffsetType[OffsetType["N"] = 8] = "N";
+    /**
+     * Resize from the east (right) side of the selection, stretching horizontally.
+     */
     OffsetType[OffsetType["E"] = 9] = "E";
+    /**
+     * Resize from the south (lower) side of the selection, stretching vertically.
+     */
     OffsetType[OffsetType["S"] = 10] = "S";
+    /**
+     * Resize from the west (left) side of the selection, stretching horizontally.
+     */
     OffsetType[OffsetType["W"] = 11] = "W";
 })(OffsetType = exports.OffsetType || (exports.OffsetType = {}));
 function isLinearOffsetType(offsetType) {

package/sdk/data/collectionproxy.d.ts

@@ -0,0 +1,40 @@
+import { ElementProxy } from '../document/elementproxy';
+import { MapProxy } from '../document/mapproxy';
+import { EditorClient } from '../editorclient';
+import { DataItemProxy } from './dataitemproxy';
+/**
+ * A collection is a set of data items, each with the same set of fields (though some data items may not have all
+ * fields defined).
+ */
+export declare class CollectionProxy extends ElementProxy {
+    readonly id: string;
+    /**
+     *
+     * @param id ID of this collection on the current document
+     * @param client
+     */
+    constructor(id: string, client: EditorClient);
+    /**
+     * @returns a human-readable name for this collection
+     */
+    getName(): string;
+    /**
+     * Some data collections may have local branches on the document, to store the set of changes that have been
+     * made by the user since the time the data was last refreshed from its source. For those collections, you
+     * can use this method to get the original data collection as it was last imported or refreshed.
+     *
+     * @returns the original collection from which this collection was branched, or undefined if this collection
+     * is not a branch
+     */
+    getBranchedFrom(): CollectionProxy | undefined;
+    /**
+     * The data items in this collection, organized by their primary key. The primary key is usually calculated
+     * from the content of the data item, but may differ from the expected value in some circumstances, e.g. if
+     * there are two data items that would have the same primary key.
+     */
+    readonly items: MapProxy<string, DataItemProxy>;
+    /**
+     * @returns an array of field names that are accessible on the items in this collection
+     */
+    getFields(): import("../commandtypes").ListCollectionFieldsResult;
+}

package/sdk/data/collectionproxy.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectionProxy = void 0;
+const elementproxy_1 = require("../document/elementproxy");
+const mapproxy_1 = require("../document/mapproxy");
+const dataitemproxy_1 = require("./dataitemproxy");
+/**
+ * A collection is a set of data items, each with the same set of fields (though some data items may not have all
+ * fields defined).
+ */
+class CollectionProxy extends elementproxy_1.ElementProxy {
+    /**
+     *
+     * @param id ID of this collection on the current document
+     * @param client
+     */
+    constructor(id, client) {
+        super(id, client);
+        this.id = id;
+        /**
+         * The data items in this collection, organized by their primary key. The primary key is usually calculated
+         * from the content of the data item, but may differ from the expected value in some circumstances, e.g. if
+         * there are two data items that would have the same primary key.
+         */
+        this.items = new mapproxy_1.MapProxy(() => this.client.sendCommand("ldi" /* ListDataItems */, { 'id': this.id }), (primaryKey) => new dataitemproxy_1.DataItemProxy(primaryKey, this, this.client));
+    }
+    /**
+     * @returns a human-readable name for this collection
+     */
+    getName() {
+        return this.properties.get('Name');
+    }
+    /**
+     * Some data collections may have local branches on the document, to store the set of changes that have been
+     * made by the user since the time the data was last refreshed from its source. For those collections, you
+     * can use this method to get the original data collection as it was last imported or refreshed.
+     *
+     * @returns the original collection from which this collection was branched, or undefined if this collection
+     * is not a branch
+     */
+    getBranchedFrom() {
+        const id = this.properties.get('BranchedFrom');
+        return id ? new CollectionProxy(id, this.client) : undefined;
+    }
+    /**
+     * @returns an array of field names that are accessible on the items in this collection
+     */
+    getFields() {
+        return this.client.sendCommand("lcf" /* ListCollectionFields */, { 'id': this.id });
+    }
+}
+exports.CollectionProxy = CollectionProxy;

package/sdk/data/dataerror.d.ts

@@ -0,0 +1,13 @@
+import { DataErrorType } from '../core/dataerrortype';
+/**
+ * The requested data or formula result couldn't be calculated.
+ */
+export declare class DataError {
+    readonly error: string;
+    readonly type: DataErrorType;
+    /**
+     * @param error A human-readable description of the reason why the error occurred
+     * @param type The kind of error that occurred
+     */
+    constructor(error: string, type: DataErrorType);
+}

package/{out → sdk}/data/dataerror.js

@@ -1,7 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataError = void 0;
+/**
+ * The requested data or formula result couldn't be calculated.
+ */
 class DataError {
+    /**
+     * @param error A human-readable description of the reason why the error occurred
+     * @param type The kind of error that occurred
+     */
     constructor(error, type) {
         this.error = error;
         this.type = type;

package/{out → sdk}/data/dataitemproxy.d.ts

@@ -1,10 +1,21 @@
 import { MapProxy } from '../document/mapproxy';
 import { EditorClient } from '../editorclient';
 import { CollectionProxy } from './collectionproxy';
+/**
+ * One data item in a collection, consisting of key-value pairs
+ */
 export declare class DataItemProxy {
     readonly primaryKey: string;
     readonly collection: CollectionProxy;
     private readonly client;
+    /**
+     * @param primaryKey The current primary key of the data item. This may change if the fields on the data item change, rendering this proxy inoperable.
+     * @param collection The collection that contains this data item.
+     * @param client
+     */
     constructor(primaryKey: string, collection: CollectionProxy, client: EditorClient);
+    /**
+     * The fields on this data item, organized by their name.
+     */
     readonly fields: MapProxy<string, import("../core/serializedfields").SerializedFieldType>;
 }

package/{out → sdk}/data/dataitemproxy.js

@@ -2,11 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataItemProxy = void 0;
 const mapproxy_1 = require("../document/mapproxy");
+/**
+ * One data item in a collection, consisting of key-value pairs
+ */
 class DataItemProxy {
+    /**
+     * @param primaryKey The current primary key of the data item. This may change if the fields on the data item change, rendering this proxy inoperable.
+     * @param collection The collection that contains this data item.
+     * @param client
+     */
     constructor(primaryKey, collection, client) {
         this.primaryKey = primaryKey;
         this.collection = collection;
         this.client = client;
+        /**
+         * The fields on this data item, organized by their name.
+         */
         this.fields = new mapproxy_1.MapProxy(() => this.client.sendCommand("lcf" /* ListCollectionFields */, { 'id': this.collection.id }), (name) => this.client.sendCommand("gdif" /* GetDataItemField */, {
             'c': this.collection.id,
             'pk': this.primaryKey,

package/sdk/data/dataproxy.d.ts

@@ -0,0 +1,19 @@
+import { MapProxy } from '../document/mapproxy';
+import { EditorClient } from '../editorclient';
+import { DataSourceProxy } from './datasourceproxy';
+/**
+ * The DataProxy class gives access to the tabular and graph data on the current Lucid document.
+ *
+ * Data collections are organized into data sources. One data sources is typically produced for
+ * each data import, and may contain multiple collections.
+ */
+export declare class DataProxy {
+    private readonly client;
+    /**
+     * Data sources on the current document, organized by their ID on this document. The ID will
+     * remain stable for as long as the data source exists on this document, but will vary from
+     * the data source ID on other documents if the same data is imported there.
+     */
+    readonly dataSources: MapProxy<string, DataSourceProxy>;
+    constructor(client: EditorClient);
+}

package/sdk/data/dataproxy.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataProxy = void 0;
+const mapproxy_1 = require("../document/mapproxy");
+const datasourceproxy_1 = require("./datasourceproxy");
+/**
+ * The DataProxy class gives access to the tabular and graph data on the current Lucid document.
+ *
+ * Data collections are organized into data sources. One data sources is typically produced for
+ * each data import, and may contain multiple collections.
+ */
+class DataProxy {
+    constructor(client) {
+        this.client = client;
+        /**
+         * Data sources on the current document, organized by their ID on this document. The ID will
+         * remain stable for as long as the data source exists on this document, but will vary from
+         * the data source ID on other documents if the same data is imported there.
+         */
+        this.dataSources = new mapproxy_1.MapProxy(() => this.client.sendCommand("lds" /* ListDataSources */, undefined), (dataSourceId) => new datasourceproxy_1.DataSourceProxy(dataSourceId, this.client));
+    }
+}
+exports.DataProxy = DataProxy;

package/sdk/data/datasourceproxy.d.ts

@@ -0,0 +1,26 @@
+import { ElementProxy } from '../document/elementproxy';
+import { MapProxy } from '../document/mapproxy';
+import { EditorClient } from '../editorclient';
+import { CollectionProxy } from './collectionproxy';
+/**
+ * A data source represents a set of related data collections on a document. Typically one data source
+ * is produced for each data import.
+ */
+export declare class DataSourceProxy extends ElementProxy {
+    readonly id: string;
+    /**
+     * @param id ID of the collection on the current document
+     * @param client
+     */
+    constructor(id: string, client: EditorClient);
+    /**
+     * The set of data collections in this data source, organized by ID on this document. The IDs will
+     * remain stable for as long as the collection exists on this document, but will vary from
+     * the collection ID on other documents if the same data is imported there.
+     */
+    readonly collections: MapProxy<string, CollectionProxy>;
+    /**
+     * @returns a human-readable name for this data source
+     */
+    getName(): string;
+}

package/{out → sdk}/data/datasourceproxy.js

@@ -4,12 +4,28 @@ exports.DataSourceProxy = void 0;
 const elementproxy_1 = require("../document/elementproxy");
 const mapproxy_1 = require("../document/mapproxy");
 const collectionproxy_1 = require("./collectionproxy");
+/**
+ * A data source represents a set of related data collections on a document. Typically one data source
+ * is produced for each data import.
+ */
 class DataSourceProxy extends elementproxy_1.ElementProxy {
+    /**
+     * @param id ID of the collection on the current document
+     * @param client
+     */
     constructor(id, client) {
         super(id, client);
         this.id = id;
+        /**
+         * The set of data collections in this data source, organized by ID on this document. The IDs will
+         * remain stable for as long as the collection exists on this document, but will vary from
+         * the collection ID on other documents if the same data is imported there.
+         */
         this.collections = new mapproxy_1.MapProxy(() => this.client.sendCommand("lc" /* ListCollections */, { 'id': this.id }), (id) => new collectionproxy_1.CollectionProxy(id, this.client));
     }
+    /**
+     * @returns a human-readable name for this data source
+     */
     getName() {
         return this.properties.get('Name');
     }

package/sdk/document/blockdefinition.d.ts

@@ -0,0 +1,14 @@
+import { Box } from '../math';
+/**
+ * The information required to create a new block on the current document
+ */
+export interface BlockDefinition {
+    /**
+     * The type of block to create, e.g. "ProcessBlock".
+     */
+    className: string;
+    /**
+     * The initial location and size of the block on the page.
+     */
+    boundingBox: Box;
+}

package/sdk/document/blockproxy.d.ts

@@ -0,0 +1,18 @@
+import { ItemProxy } from './itemproxy';
+/**
+ * A block is a single shape on the document.
+ */
+export declare class BlockProxy extends ItemProxy {
+    /**
+     * @returns the type of block this is
+     */
+    getClassName(): string;
+    /**
+     * @returns The amount this block is rotated around its own center, in radians
+     */
+    getRotation(): number;
+    /**
+     * @returns an array of lines that have one or both endpoints connected to this block
+     */
+    getConnectedLines(): import("./lineproxy").LineProxy[];
+}

package/{out → sdk}/document/blockproxy.js

@@ -2,13 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlockProxy = void 0;
 const itemproxy_1 = require("./itemproxy");
+/**
+ * A block is a single shape on the document.
+ */
 class BlockProxy extends itemproxy_1.ItemProxy {
+    /**
+     * @returns the type of block this is
+     */
     getClassName() {
         return this.properties.get('ClassName');
     }
+    /**
+     * @returns The amount this block is rotated around its own center, in radians
+     */
     getRotation() {
         return this.properties.get('Rotation');
     }
+    /**
+     * @returns an array of lines that have one or both endpoints connected to this block
+     */
     getConnectedLines() {
         const ids = this.client.sendCommand("gcl" /* GetConnectedLines */, this.id);
         return ids.map((id) => this.client.getLineProxy(id));

package/{out → sdk}/document/documentproxy.d.ts

@@ -3,8 +3,19 @@ import { ElementProxy } from './elementproxy';
 import { MapProxy } from './mapproxy';
 import { PageDefinition } from './pagedefinition';
 import { PageProxy } from './pageproxy';
+/**
+ * The currently-open Lucid document
+ */
 export declare class DocumentProxy extends ElementProxy {
+    /**
+     * The set of pages on this document, organized by ID
+     */
     readonly pages: MapProxy<string, PageProxy>;
     constructor(client: EditorClient);
+    /**
+     * Add a new page to the current document
+     * @param def Definition of the page to add
+     * @returns the created page
+     */
     addPage(def: PageDefinition): PageProxy;
 }

package/{out → sdk}/document/documentproxy.js

@@ -4,11 +4,22 @@ exports.DocumentProxy = void 0;
 const elementproxy_1 = require("./elementproxy");
 const mapproxy_1 = require("./mapproxy");
 const pageproxy_1 = require("./pageproxy");
+/**
+ * The currently-open Lucid document
+ */
 class DocumentProxy extends elementproxy_1.ElementProxy {
     constructor(client) {
-        super('', client);
+        super(undefined, client);
+        /**
+         * The set of pages on this document, organized by ID
+         */
         this.pages = new mapproxy_1.MapProxy(() => this.client.sendCommand("lp" /* ListPages */, undefined), (pageId) => new pageproxy_1.PageProxy(pageId, this.client));
     }
+    /**
+     * Add a new page to the current document
+     * @param def Definition of the page to add
+     * @returns the created page
+     */
     addPage(def) {
         const id = this.client.sendCommand("cp" /* CreatePage */, undefined);
         const page = new pageproxy_1.PageProxy(id, this.client);

package/sdk/document/elementproxy.d.ts

@@ -0,0 +1,46 @@
+import { EditorClient } from '../editorclient';
+import { MapProxy, WriteableMapProxy } from './mapproxy';
+import { ShapeDataProxy } from './shapedataproxy';
+/**
+ * An element is anything on a Lucid document that can have properties and shape data:
+ *  * The document itself
+ *  * Pages
+ *  * Blocks
+ *  * Lines
+ *  * Groups
+ */
+export declare class ElementProxy {
+    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("../core/jsonserializable").JsonSerializable>;
+    /**
+     * The shape data set directly on this element (not including any shape data inherited from the page or a containing group).
+     */
+    readonly shapeData: ShapeDataProxy;
+    /**
+     * 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>;
+    /**
+     *
+     * @param id ID of this element, or undefined for the document itself
+     * @param client
+     */
+    constructor(id: string | undefined, client: EditorClient);
+    /**
+     * @returns true if this element still exists on the document, or false otherwise
+     */
+    exists(): boolean;
+    /**
+     * 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.
+     */
+    executeFormula(formula: string): import("../core/serializedfields").SerializedFieldType | import("../data/dataerror").DataError;
+}