@eclipse-glsp/graph 0.9.0-next.0193b16.17

package/src/gmodel-element.ts

@@ -0,0 +1,218 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import {
+    Args,
+    Bounds,
+    Dimension,
+    flatPush,
+    JsonPrimitive,
+    MaybeArray,
+    Point,
+    SModelElementSchema,
+    SModelRootSchema
+} from '@eclipse-glsp/protocol';
+import * as uuid from 'uuid';
+
+export type GModelElementConstructor<G extends GModelElement = GModelElement> = new () => G;
+/**
+ * Represents a `GModeElement` serialized as plain JSON object.
+ */
+export type GModelElementSchema = SModelElementSchema;
+
+export namespace GModelElementSchema {
+    /**
+     * Typeguard function to check wether the given object is an {@link GModelElementSchema}.
+     * @param object The object to check.
+     * @returns A type literal indicating wether the given object is of type {@link GModelElementSchema}.
+     */
+    export const is = SModelElementSchema.is;
+}
+
+/**
+ * Base type for all elements of the graphical model.
+ * Each model element must have a unique ID and a type that is used to look up its view.
+ */
+export abstract class GModelElement implements GModelElementSchema {
+    /**
+     * The `type` of a `GModelElement` has two main purposes. It is used by the GLSP client
+     * during the rendering phase to lookup the View that is responsible for rendering this element.
+     * In addition, it serves as the discriminator for serialization & deserialization of `GModeElements` and their corresponding
+     * `GModelElementSchema`. e.g. If the glsp server receives a `GModelElementSchema` (plain JSON object) the type is used to
+     * lookup and construct the corresponding `GModelElement` class.
+     */
+    type: string;
+    /**
+     * Each model element must have a unique ID. Duplicate ids in the graphical element will result in an error during the
+     * rendering phase.
+     */
+    id: string;
+    /**
+     * A set of css classes that should be applied to the DOM element that corresponds to this element.
+     */
+    cssClasses: string[] = [];
+    /** A `GModelElement can have an arbitrary amount of children. This parent-child relation ship is also reflected in
+     * the corresponding DOM element i.e. DOM elements that reflect children of this element are also children
+     * of the DOM element that reflects this element.
+     */
+    children: GModelElement[] = [];
+    /**
+     * Each `GModelElement` (apart from  the root element) must have an assigned parent. Orphan elements are not allowed.
+     */
+    parent: GModelElement;
+    /**
+     * Additional custom arguments. Can be used to transmit additional information between client & server without
+     * having to extend the model.
+     */
+    args?: Args;
+
+    /**
+     * Retrieve the {@link GModelRoot} element by traversing up the parent hierachy.
+     */
+    get root(): GModelRoot {
+        let current: GModelElement = this;
+        while (!(current instanceof GModelRoot)) {
+            current = current.parent;
+        }
+        return current;
+    }
+}
+
+/**
+ * A fluent builder API that simplifies the construction of complex {@link GModelElement}s.
+ * The builder API is derived from the Java GLSP server implementation where it is used to hide the complexity
+ * of creating EMF objects. However, the API is also useful in a Typescript/Node context to declare the creation of a new
+ * {@link GModelElement} in a more concise way.
+ */
+export abstract class GModelElementBuilder<G extends GModelElement> {
+    protected proxy: G;
+    protected elementConstructor: GModelElementConstructor<G>;
+
+    constructor(elementConstructor: GModelElementConstructor<G>) {
+        this.elementConstructor = elementConstructor;
+        this.proxy = new elementConstructor();
+        this.proxy.cssClasses = [];
+        this.proxy.children = [];
+        this.proxy.id = uuid.v4();
+    }
+
+    reset(): this {
+        this.proxy = new this.elementConstructor();
+        return this;
+    }
+
+    build(): G {
+        const element = new this.elementConstructor();
+        Object.assign(element, this.proxy);
+        element.children.forEach(child => (child.parent = element));
+        if (element.id === undefined) {
+            throw new Error('The `id` property of a GModelElement must not be undefined!');
+        }
+        if (element.type === undefined) {
+            throw new Error('The `type` property of a GModelElement must not be undefined!');
+        }
+        return element;
+    }
+
+    id(id: string): this {
+        this.proxy.id = id;
+        return this;
+    }
+
+    type(type: string): this {
+        this.proxy.type = type;
+        return this;
+    }
+
+    addCssClass(cssClass: string): this {
+        this.proxy.cssClasses.push(cssClass);
+        return this;
+    }
+
+    addCssClasses(cssClasses: string[]): this;
+    addCssClasses(...cssClasses: string[]): this;
+    addCssClasses(...cssClasses: MaybeArray<string>[]): this {
+        flatPush(this.proxy.cssClasses, cssClasses);
+        return this;
+    }
+
+    add(child: GModelElement): this {
+        this.proxy.children.push(child);
+        return this;
+    }
+
+    addChildren(children: GModelElement[]): this;
+    addChildren(...children: GModelElement[]): this;
+    addChildren(...children: MaybeArray<GModelElement>[]): this {
+        flatPush(this.proxy.children, children);
+        return this;
+    }
+
+    addArg(key: string, value: JsonPrimitive): this {
+        if (!this.proxy.args) {
+            this.proxy.args = {};
+        }
+        this.proxy.args[key] = value;
+        return this;
+    }
+
+    addArgs(args: Args): this;
+    addArgs(args: Map<string, JsonPrimitive>): this;
+    addArgs(args: Args | Map<string, JsonPrimitive>): this {
+        const toAssign: Args = {};
+        if (args instanceof Map) {
+            [...args.keys()].forEach(key => (toAssign[key] = args.get(key)!));
+        } else {
+            Object.keys(args).forEach(key => (toAssign[key] = args[key]));
+        }
+        if (this.proxy.args) {
+            Object.assign(this.proxy.args, toAssign);
+        } else {
+            this.proxy.args = toAssign;
+        }
+        return this;
+    }
+}
+
+export type GModelRootSchema = SModelRootSchema;
+
+export class GModelRoot extends GModelElement implements SModelRootSchema {
+    static builder(): GModelRootBuilder {
+        return new GModelRootBuilder(GModelRoot);
+    }
+
+    canvasBounds?: Bounds;
+    revision = 0;
+}
+
+export class GModelRootBuilder<G extends GModelRoot = GModelRoot> extends GModelElementBuilder<G> {
+    revision(revision: number): this {
+        this.proxy.revision = revision;
+        return this;
+    }
+
+    canvasBounds(position: Point, size: Dimension): this;
+    canvasBounds(bounds: Bounds): this;
+    canvasBounds(positionOrBounds: Point | Bounds, size?: Dimension): this {
+        let bounds: Bounds;
+        if (size) {
+            bounds = { ...positionOrBounds, ...size };
+        } else {
+            bounds = positionOrBounds as Bounds;
+        }
+        this.proxy.canvasBounds = bounds;
+        return this;
+    }
+}

package/src/gmodel-util.ts

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { GModelElement, GModelElementConstructor } from '.';
+
+export type Predicate<T> = (element: T) => boolean;
+
+/**
+ * Returns the first element matching the search predicate starting from the given
+ * element and walking up the parent hierarchy.
+ *
+ * @param element   The element to start the search from.
+ * @param searchPredicate The predicate which the element should match.
+ * @returns The first matching element or `undefined`.
+ */
+export function findParent(element: GModelElement, searchPredicate: Predicate<GModelElement>): GModelElement | undefined {
+    if (!element) {
+        return undefined;
+    }
+    if (searchPredicate(element)) {
+        return element;
+    }
+    const parent = element.parent;
+    return parent ? findParent(parent, searchPredicate) : undefined;
+}
+
+/**
+ * Returns the first parent element that is an instance of the given {@link GModelElementConstructor} starting from the given element.
+ * (recursively walking up the parent hierarchy).
+ *
+ * @param element   The element to start the search from.
+ * @param constructor The queried parent class ({@link GModelElementConstructor}).
+ * @returns The first matching parent element or `undefined`.
+ */
+export function findParentByClass<G extends GModelElement>(
+    element: GModelElement,
+    constructor: GModelElementConstructor<G>
+): G | undefined {
+    const predicate: Predicate<GModelElement> = element => element instanceof constructor;
+    const result = findParent(element, predicate);
+    if (result) {
+        return result as G;
+    }
+    return undefined;
+}

package/src/gnode.ts

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { DefaultTypes } from '@eclipse-glsp/protocol';
+import { GLayoutContainer, GLayoutContainerBuilder } from './glayout-container';
+import { GShapeElement, GShapeElementBuilder } from './gshape-element';
+
+export class GNode extends GShapeElement implements GLayoutContainer {
+    static builder(): GNodeBuilder {
+        return new GNodeBuilder(GNode).type(DefaultTypes.NODE);
+    }
+
+    override type = DefaultTypes.NODE;
+    layout?: string;
+    [GLayoutContainer] = true;
+}
+
+export class GNodeBuilder<G extends GNode = GNode> extends GShapeElementBuilder<G> {
+    layout(layout?: string): this {
+        return GLayoutContainerBuilder.layout(this, layout);
+    }
+}

package/src/gport.ts

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { DefaultTypes } from '@eclipse-glsp/protocol';
+import { GShapeElement, GShapeElementBuilder } from './gshape-element';
+
+export class GPort extends GShapeElement {
+    static builder(): GShapeElementBuilder<GPort> {
+        return new GShapeElementBuilder(GPort).type(DefaultTypes.PORT);
+    }
+
+    override type = DefaultTypes.PORT;
+}

package/src/gpre-rendered-element.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { GModelElement, GModelElementBuilder } from './gmodel-element';
+import { DefaultTypes } from '@eclipse-glsp/protocol';
+
+/**
+ * Pre-rendered elements contain HTML or SVG code to be transferred to the DOM. This can be useful to
+ * render complex figures or to compute the view on the server instead of the client code.
+ * Pre rendered elements are often used for the popup model that is created by a `PopupModelFactory`.
+ * A popup model is rendered when hovering over a element and for many common use cases e.g rendering a tooltip
+ * this model can be computed entirely on the server side.
+ */
+export class GPreRenderedElement extends GModelElement {
+    static builder(): GPreRenderedElementBuilder {
+        return new GPreRenderedElementBuilder(GPreRenderedElement).type(DefaultTypes.PRE_RENDERED);
+    }
+
+    code: string;
+}
+
+export class GPreRenderedElementBuilder<G extends GPreRenderedElement = GPreRenderedElement> extends GModelElementBuilder<G> {
+    code(code: string): this {
+        this.proxy.code = code;
+        return this;
+    }
+}

package/src/gshape-element.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { Args, Dimension, JsonPrimitive, Point } from '@eclipse-glsp/protocol';
+import { GBoundsAware, GBoundsAwareBuilder } from './gbound-aware';
+import { GLayoutable, GLayoutableBuilder } from './glayoutable';
+import { GModelElement, GModelElementBuilder } from './gmodel-element';
+
+export abstract class GShapeElement extends GModelElement implements GBoundsAware, GLayoutable {
+    layoutOptions?: Args;
+    position: Point;
+    size: Dimension;
+    [GBoundsAware] = true;
+    [GLayoutable] = true;
+}
+
+export class GShapeElementBuilder<G extends GShapeElement> extends GModelElementBuilder<G> {
+    position(x: number, y: number): this;
+    position(position: Point): this;
+    position(pointOrX: Point | number, y?: number): this {
+        return GBoundsAwareBuilder.position(this, pointOrX, y);
+    }
+
+    size(width: number, height: number): this;
+    size(size: Dimension): this;
+    size(sizeOrWidth: Dimension | number, height?: number): this {
+        return GBoundsAwareBuilder.size(this, sizeOrWidth, height);
+    }
+
+    addLayoutOption(key: string, value: JsonPrimitive): this {
+        return GLayoutableBuilder.addLayoutOption(this, key, value);
+    }
+
+    addLayoutOptions(layoutOptions: Args): this;
+    addLayoutOptions(layoutOptions: Map<string, JsonPrimitive>): this;
+    addLayoutOptions(layoutOptions: Args | Map<string, JsonPrimitive>): this {
+        return GLayoutableBuilder.addLayoutOptions(this, layoutOptions);
+    }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * Copyright (c) 2022 STMicroelectronics and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+export * from './default-types';
+export * from './galignable';
+export * from './gbound-aware';
+export * from './gbutton';
+export * from './gcompartment';
+export * from './gedge';
+export * from './gedge-layoutable';
+export * from './ggraph';
+export * from './gissue-marker';
+export * from './glabel';
+export * from './glayout-container';
+export * from './glayoutable';
+export * from './gmodel-element';
+export * from './gmodel-util';
+export * from './gnode';
+export * from './gport';
+export * from './gpre-rendered-element';
+export * from './gshape-element';