lucid-extension-sdk 1.0.0

package/bin/editorclient.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const blockproxy_1 = require("./document/blockproxy");
+const documentproxy_1 = require("./document/documentproxy");
+const elementproxy_1 = require("./document/elementproxy");
+const groupproxy_1 = require("./document/groupproxy");
+const lineproxy_1 = require("./document/lineproxy");
+const pageproxy_1 = require("./document/pageproxy");
+const blockproxyregistry_1 = require("./document/blockclasses/blockproxyregistry");
+class EditorClient {
+    constructor() {
+        this.nextId = 0;
+        this.oneTimeCallbacks = new Map();
+        this.actions = new Map();
+        lucid.listen((msg) => {
+            var _a;
+            const resolver = this.oneTimeCallbacks.get(msg['id']);
+            if (resolver) {
+                resolver(msg['r']);
+                this.oneTimeCallbacks.delete(msg['id']);
+            }
+            else {
+                (_a = this.actions.get(msg['id'])) === null || _a === void 0 ? void 0 : _a(msg);
+            }
+        });
+    }
+    killExtension() {
+        this.sendCommand('k');
+    }
+    reloadExtension() {
+        this.sendCommand('r');
+    }
+    download(filename, data, mime, base64) {
+        this.sendCommand('d', {
+            'f': filename,
+            'd': data,
+            'm': mime,
+            'b64': base64,
+        });
+    }
+    showModal(title, width, height, content) {
+        this.sendCommand('sm', {
+            't': title,
+            'w': width,
+            'h': height,
+            'c': content,
+        });
+    }
+    hideModal() {
+        this.sendCommand('hm');
+    }
+    registerOneTimeAction(cb) {
+        const id = this.nextId++;
+        this.oneTimeCallbacks.set(id, cb);
+        return id;
+    }
+    registerAction(name, cb) {
+        this.actions.set(name, cb);
+    }
+    deleteAction(name) {
+        this.actions.delete(name);
+    }
+    actionExists(name) {
+        return this.actions.has(name);
+    }
+    sendCommand(name, params) {
+        return lucid.executeCommand(name, params);
+    }
+    getBlockProxy(id) {
+        const className = this.sendCommand('gp', { 'id': id, 'p': 'ClassName' });
+        const proxy = blockproxyregistry_1.findProxyClass(className);
+        if (proxy) {
+            return new proxy(id, this);
+        }
+        else {
+            return new blockproxy_1.BlockProxy(id, this);
+        }
+    }
+    loadBlockClasses(classNames) {
+        return this.sendCommand('lbc', classNames);
+    }
+    getElementProxy(id) {
+        const type = this.sendCommand('get', id);
+        switch (type) {
+            case 'block':
+                return this.getBlockProxy(id);
+            case 'line':
+                return new lineproxy_1.LineProxy(id, this);
+            case 'page':
+                return new pageproxy_1.PageProxy(id, this);
+            case 'document':
+                return new documentproxy_1.DocumentProxy(this);
+            case 'group':
+                return new groupproxy_1.GroupProxy(id, this);
+            default:
+                return new elementproxy_1.ElementProxy(id, this);
+        }
+    }
+}
+exports.EditorClient = EditorClient;

package/bin/index.d.ts

@@ -0,0 +1,4 @@
+export * from './editorclient';
+export * from './document/documentproxy';
+export * from './ui/menu';
+export * from './ui/viewport';

package/bin/index.js

@@ -0,0 +1,9 @@
+"use strict";
+function __export(m) {
+    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
+}
+Object.defineProperty(exports, "__esModule", { value: true });
+__export(require("./editorclient"));
+__export(require("./document/documentproxy"));
+__export(require("./ui/menu"));
+__export(require("./ui/viewport"));

package/bin/math.d.ts

@@ -0,0 +1,10 @@
+export declare type Point = {
+    x: number;
+    y: number;
+};
+export declare type Box = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};

package/bin/math.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/ui/menu.d.ts

@@ -0,0 +1,26 @@
+import { EditorClient } from '../editorclient';
+export declare const enum MenuType {
+    Main = 0,
+    Context = 1
+}
+export interface CustomMenuItem {
+    label: string;
+    action: string;
+    menuType: MenuType;
+    /**
+     * The standard menu item to display this item after.
+     * Examples:
+     * ['file'] -> put at the top of the File menu
+     * ['file', 'duplicate'] -> put after Duplicate in the File menu
+     * ['file', 'export'] -> put at the top of the export submenu
+     *
+     * The path is interpreted up to the first invalid entry.
+     * If the resulting valid path is empty, a new top-level menu named Add-ons appears before Help and this is added
+     */
+    path: string[];
+}
+export declare class Menu {
+    private readonly client;
+    constructor(client: EditorClient);
+    addMenuItem(item: CustomMenuItem): void;
+}

package/bin/ui/menu.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class Menu {
+    constructor(client) {
+        this.client = client;
+    }
+    addMenuItem(item) {
+        if (!this.client.actionExists(item.action)) {
+            throw new Error('Unregistered action: ' + item.action);
+        }
+        this.client.sendCommand('ami', {
+            'l': item.label,
+            'a': item.action,
+            't': item.menuType,
+            'p': item.path,
+        });
+    }
+}
+exports.Menu = Menu;

package/bin/ui/viewport.d.ts

@@ -0,0 +1,10 @@
+import { ItemProxy } from '../document/itemproxy';
+import { PageProxy } from '../document/pageproxy';
+import { EditorClient } from '../editorclient';
+export declare class Viewport {
+    private readonly client;
+    constructor(client: EditorClient);
+    getSelectedItems(): ItemProxy[];
+    getCurrentPage(): PageProxy;
+    setCurrentPage(page: PageProxy): void;
+}

package/bin/ui/viewport.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const itemproxy_1 = require("../document/itemproxy");
+const pageproxy_1 = require("../document/pageproxy");
+class Viewport {
+    constructor(client) {
+        this.client = client;
+    }
+    getSelectedItems() {
+        const ids = this.client.sendCommand('gs');
+        return ids
+            .map((id) => this.client.getElementProxy(id))
+            .filter((proxy) => proxy instanceof itemproxy_1.ItemProxy);
+    }
+    getCurrentPage() {
+        return new pageproxy_1.PageProxy(this.client.sendCommand('gcp'), this.client);
+    }
+    setCurrentPage(page) {
+        this.client.sendCommand('scp', page.id);
+    }
+}
+exports.Viewport = Viewport;

package/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "lucid-extension-sdk",
+    "version": "1.0.0",
+    "description": "Utility classes for writing Lucid Software editor extensions",
+    "main": "bin/index.js",
+    "types": "bin/index.d.ts",
+    "author": "",
+    "license": "ISC",
+    "declaration": true,
+    "devDependencies": {
+        "@types/node": "^16.11.11"
+    }
+}

package/src/constants.ts

@@ -0,0 +1,14 @@
+export const enum OffsetType {
+    NW = 0,
+    NE = 1,
+    SE = 2,
+    SW = 3,
+    MOVE = 4,
+    ROTATE = 5,
+    SCALE = 6,
+    CUSTOM = 7,
+    N = 8,
+    E = 9,
+    S = 10,
+    W = 11,
+}

package/src/document/blockclasses/blockproxyregistry.ts

@@ -0,0 +1,12 @@
+import {BlockProxy} from '../blockproxy';
+import {ERDBlockProxy} from './erdblockproxy';
+
+export type BlockProxyConstructor = typeof BlockProxy & {
+    classNameRegex: RegExp;
+};
+
+const allProxyClasses: BlockProxyConstructor[] = [ERDBlockProxy];
+
+export function findProxyClass(className: string): BlockProxyConstructor | undefined {
+    return allProxyClasses.find((proxy) => proxy.classNameRegex.test(className));
+}

package/src/document/blockclasses/erdblockproxy.ts

@@ -0,0 +1,41 @@
+import {BlockProxy} from '../blockproxy';
+
+export class ERDFieldProxy {
+    constructor(private readonly block: ERDBlockProxy, private readonly index: number) {}
+
+    public getName(): string {
+        return this.block.properties.get('Field' + this.index);
+    }
+
+    public getType(): string {
+        return this.block.properties.get('Type' + this.index) ?? '';
+    }
+
+    public getKey(): string {
+        return this.block.properties.get('Key' + this.index) ?? '';
+    }
+}
+
+export class ERDBlockProxy extends BlockProxy {
+    public static classNameRegex = /^ERDEntityBlock(2|3|4)?$/;
+
+    public getName(): string {
+        return this.properties.get('Name');
+    }
+
+    public getFieldCount(): number {
+        return this.properties.get('Fields');
+    }
+
+    public getFields() {
+        const fields: ERDFieldProxy[] = [];
+
+        const fieldCount = this.getFieldCount();
+        for (let i = 1; i <= fieldCount; i++) {
+            //These are 1-indexed in the property store
+            fields.push(new ERDFieldProxy(this, i));
+        }
+
+        return fields;
+    }
+}

package/src/document/blockdefinition.ts

@@ -0,0 +1,6 @@
+import {Box} from '../math';
+
+export type BlockDefinition = {
+    className: string;
+    boundingBox: Box;
+};

package/src/document/blockproxy.ts

@@ -0,0 +1,17 @@
+import {ItemProxy} from './itemproxy';
+import {LineProxy} from './lineproxy';
+
+export class BlockProxy extends ItemProxy {
+    public getClassName(): string {
+        return this.properties.get('ClassName');
+    }
+
+    public getRotation(): number {
+        return this.properties.get('Rotation');
+    }
+
+    public getConnectedLines() {
+        const ids: string[] = this.client.sendCommand('gcl', this.id);
+        return ids.map((id) => new LineProxy(id, this.client));
+    }
+}

package/src/document/documentproxy.ts

@@ -0,0 +1,28 @@
+import {EditorClient} from '../editorclient';
+import {ElementProxy} from './elementproxy';
+import {MapProxy} from './mapproxy';
+import {PageProxy} from './pageproxy';
+import {PageDefinition} from './pagedefinition';
+
+export class DocumentProxy extends ElementProxy {
+    public readonly pages = new MapProxy<string, PageProxy>(
+        this.client,
+        'lp',
+        undefined,
+        (pageId) => new PageProxy(pageId, this.client),
+    );
+
+    constructor(client: EditorClient) {
+        super('', client);
+    }
+
+    public addPage(def: PageDefinition) {
+        const id = this.client.sendCommand('cp', {
+            'Title': def.title,
+        });
+
+        const page = new PageProxy(id, this.client);
+        page.setTitle(def.title);
+        return page;
+    }
+}

package/src/document/elementproxy.ts

@@ -0,0 +1,41 @@
+import {EditorClient} from '../editorclient';
+import {MapProxy, WriteableMapProxy} from './mapproxy';
+
+export class ElementProxy {
+    public readonly properties = new WriteableMapProxy<string, any>(
+        this.client,
+        'lpr',
+        this.id,
+        (name) =>
+            this.client.sendCommand('gp', {
+                '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', {
+                'id': this.id,
+                'p': name,
+                'v': value,
+            });
+        },
+    );
+
+    public readonly shapeData = new MapProxy<string, any>(this.client, 'lsd', this.id, (name) =>
+        this.client.sendCommand('gsd', {
+            'id': this.id,
+            'n': name,
+        }),
+    );
+
+    constructor(public readonly id: string, protected readonly client: EditorClient) {}
+
+    public exists(): boolean {
+        return this.client.sendCommand('ee', this.id);
+    }
+}

package/src/document/groupproxy.ts

@@ -0,0 +1,25 @@
+import {ElementProxy} from './elementproxy';
+import {MapProxy} from './mapproxy';
+import {BlockProxy} from './blockproxy';
+import {LineProxy} from './lineproxy';
+import {ItemProxy} from './itemproxy';
+
+export class GroupProxy extends ItemProxy {
+    public readonly blocks = new MapProxy<string, BlockProxy>(this.client, 'lb', this.id, (id) =>
+        this.client.getBlockProxy(id),
+    );
+
+    public readonly lines = new MapProxy<string, LineProxy>(
+        this.client,
+        'll',
+        this.id,
+        (id) => new LineProxy(id, this.client),
+    );
+
+    public readonly groups = new MapProxy<string, GroupProxy>(
+        this.client,
+        'lg',
+        this.id,
+        (id) => new GroupProxy(id, this.client),
+    );
+}

package/src/document/itemproxy.ts

@@ -0,0 +1,58 @@
+import {ElementProxy} from './elementproxy';
+import {MapProxy} from './mapproxy';
+import {OffsetType} from '../constants';
+import {Box, Point} from '../math';
+
+export class ItemProxy extends ElementProxy {
+    public readonly textAreas = new MapProxy<string, string>(this.client, 'lta', this.id, (name) =>
+        this.client.sendCommand('gp', {
+            'id': this.id,
+            'p': name,
+        }),
+    );
+
+    public getBoundingBox() {
+        return this.properties.get('BoundingBox') as Box;
+    }
+
+    public setBoundingBox(bb: Box) {
+        const current = this.getBoundingBox();
+        if (current.w === bb.w && current.h === bb.h) {
+            //Move it into place
+            if (current.x !== bb.x || current.y !== bb.y) {
+                this.offset(OffsetType.MOVE, {x: bb.x - current.x, y: bb.y - current.y});
+            }
+        } else {
+            //Stretch it to size
+            if (current.x !== bb.x || current.y !== bb.y) {
+                this.offset(OffsetType.NW, {x: bb.x - current.x, y: bb.y - current.y});
+            }
+            if (current.x + current.w !== bb.x + bb.w || current.y + current.h !== bb.y + bb.h) {
+                this.offset(OffsetType.SE, {
+                    x: bb.x + bb.w - (current.x + current.w),
+                    y: bb.y + bb.h - (current.y + current.h),
+                });
+            }
+        }
+    }
+
+    public getLocation() {
+        const bb = this.getBoundingBox();
+        return {x: bb.x, y: bb.y};
+    }
+
+    public setLocation(location: Point) {
+        const current = this.getBoundingBox();
+        if (current.x !== location.x || current.y !== location.y) {
+            this.offset(OffsetType.MOVE, {x: location.x - current.x, y: location.y - current.y});
+        }
+    }
+
+    public offset(type: OffsetType, offset: Point) {
+        this.client.sendCommand('oi', {'ids': [this.id], 't': type, 'o': offset});
+    }
+
+    public delete() {
+        this.client.sendCommand('di', this.id);
+    }
+}

package/src/document/linedefinition.ts

@@ -0,0 +1,41 @@
+import {BlockProxy} from './blockproxy';
+import {LineProxy} from './lineproxy';
+
+export interface EndpointStyle {
+    style?: string; //Omit to use defaults (theme)
+}
+
+export interface BlockEndpointDefinition extends EndpointStyle {
+    connection: BlockProxy;
+    linkX: number; //0 to 1, relative X position in target block's bounding box
+    linkY: number; //0 to 1, relative Y position in target block's bounding box
+    inside?: boolean;
+    autoLink?: boolean;
+    padding?: number;
+}
+
+export interface LineEndpointDefinition extends EndpointStyle {
+    connection: LineProxy;
+    position: number; //0 to 1, distance along the target line
+}
+
+export interface PositionEndpointDefinition extends EndpointStyle {
+    connection: void;
+    x: number;
+    y: number;
+}
+
+export type EndpointDefinition = BlockEndpointDefinition | LineEndpointDefinition | PositionEndpointDefinition;
+
+export function isBlockEndpointDefinition(ep: EndpointDefinition): ep is BlockEndpointDefinition {
+    return ep.connection instanceof BlockProxy;
+}
+
+export function isLineEndpointDefinition(ep: EndpointDefinition): ep is LineEndpointDefinition {
+    return ep.connection instanceof LineProxy;
+}
+
+export type LineDefinition = {
+    endpoint1: EndpointDefinition;
+    endpoint2: EndpointDefinition;
+};

package/src/document/lineproxy.ts

@@ -0,0 +1,48 @@
+import {Point} from '../math';
+import {BlockProxy} from './blockproxy';
+import {ElementProxy} from './elementproxy';
+import {ItemProxy} from './itemproxy';
+
+export class LineProxy extends ItemProxy {
+    private async getConnection(ep: {'Block'?: string; 'Line'?: string}) {
+        let proxy: ElementProxy | undefined;
+
+        if (ep['Block']) {
+            proxy = this.client.getBlockProxy(ep['Block']);
+        }
+        if (ep['Line']) {
+            proxy = new LineProxy(ep['Line'], this.client);
+        }
+
+        if (proxy && !proxy.exists()) {
+            return undefined;
+        }
+
+        return proxy;
+    }
+
+    public async getUpstreamConnection() {
+        const ep = this.properties.get('Endpoint1');
+        if (!(typeof ep === 'object')) {
+            return undefined;
+        }
+        return this.getConnection(ep);
+    }
+
+    public async getDownstreamConnection() {
+        const ep = this.properties.get('Endpoint2');
+        if (!(typeof ep === 'object')) {
+            return undefined;
+        }
+        return this.getConnection(ep);
+    }
+
+    public getConnectedLines() {
+        const ids: string[] = this.client.sendCommand('gcl', this.id);
+        return ids.map((id) => new LineProxy(id, this.client));
+    }
+
+    public getRelativePosition(relative: number): Point {
+        return this.client.sendCommand('grlp', {'id': this.id, 'p': relative});
+    }
+}

package/src/document/mapproxy.ts

@@ -0,0 +1,43 @@
+import {EditorClient} from '../editorclient';
+
+export class MapProxy<KEY, VALUE> {
+    constructor(
+        protected readonly client: EditorClient,
+        private readonly keyCommand: string,
+        private readonly keyParams: any,
+        private readonly getter: (key: KEY) => VALUE,
+    ) {}
+
+    public *[Symbol.iterator](): Iterator<[KEY, VALUE]> {
+        for (const key of this.keys()) {
+            const value = this.get(key);
+            if (value !== undefined) {
+                yield [key, value];
+            }
+        }
+    }
+
+    public keys(): KEY[] {
+        return this.client.sendCommand(this.keyCommand, this.keyParams);
+    }
+
+    public get(key: KEY) {
+        return this.getter(key);
+    }
+}
+
+export class WriteableMapProxy<KEY, VALUE> extends MapProxy<KEY, VALUE> {
+    constructor(
+        client: EditorClient,
+        keyCommand: string,
+        keyParams: any,
+        getter: (key: KEY) => VALUE,
+        private readonly setter: (key: KEY, val: VALUE) => void,
+    ) {
+        super(client, keyCommand, keyParams, getter);
+    }
+
+    public set(key: KEY, value: VALUE) {
+        this.setter(key, value);
+    }
+}

package/src/document/pagedefinition.ts

@@ -0,0 +1,3 @@
+export type PageDefinition = {
+    title: string;
+};