@visuallyjs/browser-ui 1.0.0

package/types/core/datasource.d.ts

@@ -0,0 +1,87 @@
+import { BeforeConnectInterceptor, BeforeStartConnectInterceptor, ObjectFactory, BeforeMoveConnectionInterceptor, BeforeDetachInterceptor, BeforeStartDetachInterceptor, VertexUpdatedReason } from "./toolkit";
+import { Vertex, Port, Node, Group, Edge, ObjectData, Graph, Base } from "./model/graph";
+import { FilterableDataset } from "./filterable-dataset";
+import { DataModel } from "./datamodel/data-model";
+import { VisuallyJsRenderer } from './renderer';
+import { TransactionCleanupAction } from "./undo-redo/undo-redo";
+import { PointXY } from "./util";
+/**
+ * Return value from getObjectInfo - an object, its type, and id. Or null.
+ * @group Model
+ */
+export interface ObjectInfo<T> {
+    type?: string;
+    obj?: T;
+    id?: string;
+}
+/**
+ * Data source for a renderer.
+ * @group Model
+ */
+export interface DataSource extends FilterableDataset {
+    bind<T = any>(evt: string, handler: (p: T) => any, insertAtStart?: boolean): void;
+    unbind(evt: string, handler: Function): void;
+    fire(evt: string, payload: any, args3?: any): void;
+    getType(obj: Base): string;
+    getGroups(): Array<Group>;
+    getGroup(id: string): Group;
+    getGroupType(groupData: ObjectData): string;
+    getGroupId(node: ObjectData): string;
+    getGroupCount(): number;
+    getGroupAt(idx: number): Group;
+    getNodes(): Array<Node>;
+    getNode(id: string): Node;
+    getNodeType(nodeData: ObjectData): string;
+    getNodeId(node: ObjectData): string;
+    getNodeCount(): number;
+    getNodeAt(idx: number): Node;
+    getPortType(port: ObjectData): string;
+    getPortId(port: ObjectData): string;
+    getDescendants(vertex: Group): Array<Node | Group>;
+    getAncestors(vertex: Node | Group): Array<Group>;
+    isAncestor(focus: Node | Group, possibleAncestor: Group): boolean;
+    isDescendantGroup(possibleDescendant: Group, ancestor: Group): boolean;
+    getEdgeCount(): number;
+    getAllEdges(): Array<Edge>;
+    getAllEdgesFor(obj: Vertex, filter?: Function): Array<Edge>;
+    getEdge(edgeId: string): Edge;
+    edgeFactory: ObjectFactory;
+    getEdgeType(edgeData: ObjectData): string;
+    getGroup(id: string): Group;
+    getGroupCount(): number;
+    getGroupAt(idx: number): Group;
+    getVertex(id: string): Vertex;
+    eachVertex(fn: (idx: number, vertex: Vertex) => void): void;
+    resolveFullId(b: Base): string;
+    getObjectInfo<T>(obj: any): ObjectInfo<T>;
+    beforeConnect: BeforeConnectInterceptor;
+    beforeMoveConnection: BeforeMoveConnectionInterceptor;
+    beforeStartConnect: BeforeStartConnectInterceptor;
+    beforeDetach: BeforeDetachInterceptor;
+    beforeStartDetach: BeforeStartDetachInterceptor;
+    debugEnabled: boolean;
+    getModel(): DataModel;
+    getGraph(): Graph;
+    reload?(): void;
+}
+/**
+ * Extension of DataSource with methods to write to the model.
+ * @group Model
+ */
+export interface WriteableDatasource extends DataSource {
+    $addToGroup(vertex: Node | Group | string, group: Group | string, sourceGroup?: Group, originalPosition?: PointXY, newPosition?: PointXY, source?: VisuallyJsRenderer<any>): boolean;
+    $removeFromGroup(node: Node | Group | string, targetGroup?: Group, originalPosition?: PointXY, newPosition?: PointXY, source?: VisuallyJsRenderer<any>): Group;
+    updateVertex(vertex: string | Node | Group | Port | ObjectData, updates?: ObjectData, reason?: VertexUpdatedReason | string): void;
+    updateVertices(updates: Array<{
+        id: string;
+        updates?: ObjectData;
+    }>, reason?: string, cleanupAction?: TransactionCleanupAction): void;
+    openTransaction(cleanupAction?: TransactionCleanupAction): void;
+    rollbackTransaction(): void;
+    commitTransaction(commitAll?: boolean): void;
+    batch(fn: Function): void;
+    addEdge(params: any, source?: any): Edge;
+    removeEdge(edge: Edge, source?: any): void;
+    setEdgeGeometry(edge: Edge, geometry: any, originalGeometry: any, renderer: VisuallyJsRenderer<any>): void;
+    addPort(node: string | Node, data: ObjectData): Port;
+}

package/types/core/event-constants.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Fired when a group has been added to the model.
+ * @group Events
+ * @category Model
+ * @payload GroupAddedParams
+ */
+export declare const EVENT_GROUP_ADDED = "group:added";
+/**
+ * Fired when a new child vertex has been added to a group
+ * @group Events
+ * @category Model
+ * @payload GroupMemberAddedParams
+ */
+export declare const EVENT_GROUP_MEMBER_ADDED = "group:member:added";
+/**
+ * Fired when a child vertex has been removed from a group
+ * @group Events
+ * @category Model
+ * @payload GroupMemberRemovedParams
+ */
+export declare const EVENT_GROUP_MEMBER_REMOVED = "group:member:removed";
+/**
+ * Fired when a group has been removed from the model.
+ * @group Events
+ * @category Model
+ * @payload GroupRemovedParams
+ */
+export declare const EVENT_GROUP_REMOVED = "group:removed";
+/**
+ * Fired at the start of a data load.
+ * @group Events
+ * @category Model
+ */
+export declare const EVENT_DATA_LOAD_START = "dataLoadStart";
+/**
+ * Fired at the start of a data append operation
+ * @group Events
+ * @category Model
+ */
+export declare const EVENT_DATA_APPEND_START = "dataAppendStart";
+/**
+ * Fired at the end of a data load, after all the data has been loaded.
+ * @group Events
+ * @category Model
+ */
+export declare const EVENT_DATA_LOAD_END = "dataLoadEnd";
+/**
+ * Fired at the end of a data append operation, after the new data has been loaded.
+ * @group Events
+ * @category Model
+ */
+export declare const EVENT_DATA_APPEND_END = "dataAppendEnd";
+/**
+ * Event fired alongside any other operation that results in the data being updated. This event is
+ * fired often and is used by various internal classes.
+ * @event
+ */
+export declare const EVENT_DATA_UPDATED = "dataUpdated";
+/**
+ * Fired immediately prior to the graph being cleared.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_GRAPH_CLEAR_START = "graphClearStart";
+/**
+ * Fired immediately after the graph has been cleared.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_GRAPH_CLEARED = "graphCleared";
+/**
+ * Fired when the graph has changed.
+ * @internal
+ */
+export declare const EVENT_GRAPH_CHANGED = "graphChanged";
+/**
+ * Fired when a group has been updated in the model.
+ * @event
+ * @category Model
+ * @payload GroupUpdatedParams
+ */
+export declare const EVENT_GROUP_UPDATED = "group:updated";
+/**
+ * Fired when a node has been updated in the model.
+ * @event
+ * @category Model
+ * @payload NodeUpdatedParams
+ */
+export declare const EVENT_NODE_UPDATED = "node:updated";
+/**
+ * Fired when a port has been updated in the model.
+ * @event
+ * @category Model
+ * @payload PortUpdatedParams
+ */
+export declare const EVENT_PORT_UPDATED = "port:updated";
+/**
+ * Fired when an edge has been updated in the model.
+ * @event
+ * @category Model
+ * @payload EdgeUpdatedParams
+ */
+export declare const EVENT_EDGE_UPDATED = "edge:updated";
+/**
+ * Fired when an edge has been added to the model.
+ * @event
+ * @category Model
+ * @payload EdgeAddedParams
+ */
+export declare const EVENT_EDGE_ADDED = "edge:added";
+/**
+ * Fired when a node has been added to the model.
+ * @event
+ * @category Model
+ * @payload NodeAddedParams
+ */
+export declare const EVENT_NODE_ADDED = "node:added";
+/**
+ * Fired when an edge has been removed from the model.
+ * @event
+ * @category Model
+ * @payload EdgeRemovedParams
+ */
+export declare const EVENT_EDGE_REMOVED = "edge:removed";
+/**
+ * Fired when a node has been removed from the model.
+ * @event
+ * @category Model
+ * @payload NodeRemovedParams
+ */
+export declare const EVENT_NODE_REMOVED = "node:removed";
+/**
+ * Fired when a port has been added to the model.
+ * @event
+ * @category Model
+ * @payload PortAddedParams
+ */
+export declare const EVENT_PORT_ADDED = "port:added";
+/**
+ * Fired when a port has been removed from the model.
+ * @event
+ * @category Model
+ * @payload PortRemovedParams
+ */
+export declare const EVENT_PORT_REMOVED = "port:removed";
+/**
+ * Fired when the target of some edge has changed
+ * @event
+ * @category Model
+ * @payload EdgeTargetChangedParams
+ */
+export declare const EVENT_EDGE_TARGET_CHANGED = "edge:target";
+/**
+ * Fired when the source of some edge has changed
+ * @event
+ * @category Model
+ * @payload EdgeSourceChangedParams
+ */
+export declare const EVENT_EDGE_SOURCE_CHANGED = "edge:source";
+/**
+ * Fired when an object is added to a selection
+ * @event
+ * @category Model
+ * @payload SelectionParams
+ */
+export declare const EVENT_SELECT = "select";
+/**
+ * Fired when an object is removed from a selection
+ * @event
+ * @category Model
+ * @payload SelectionParams
+ */
+export declare const EVENT_DESELECT = "deselect";
+/**
+ * Fired when a selection is cleared.
+ * @event
+ * @category Model
+ * @payload SelectionClearedParams
+ */
+export declare const EVENT_SELECTION_CLEARED = "selection:cleared";
+/**
+ * Fired by the model when the geometry for an edge has changed
+ * @event
+ * @category Model
+ */
+export declare const EVENT_EDGE_GEOMETRY = "edge:geometry";
+/**
+ * Fired by the UI when the user has made some edits to an edge path
+ * @event
+ * @category UI
+ */
+export declare const EVENT_EDGE_PATH_EDITED = "edge:pathEdited";
+/**
+ * Fired by the model when the type of a node has changed.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_EDGE_TYPE_CHANGED = "edge:typeChanged";
+/**
+ * Fired by the model when the type of a node has changed.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_NODE_TYPE_CHANGED = "node:typeChanged";
+/**
+ * Fired by the model when the type of a port has changed.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_PORT_TYPE_CHANGED = "port:typeChanged";
+/**
+ * Fired by the model when the type of a group has changed.
+ * @event
+ * @category Model
+ */
+export declare const EVENT_GROUP_TYPE_CHANGED = "group:typeChanged";
+/**
+ * Fired as the user starts to drag a group
+ * @category UI
+ * @payload VertexMoveStartParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_GROUP_MOVE_START = "group:move:start";
+/**
+ * Fired each time the mouse/pointer moves while a group is being dragged.
+ * @category UI
+ * @payload VertexMoveParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_GROUP_MOVE = "group:move";
+/**
+ * Fired at the end of a group drag
+ * @category UI
+ * @payload VertexMoveEndParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_GROUP_MOVE_END = "group:move:end";
+/**
+ * @internal
+ */
+export declare const EVENT_INTERNAL_GROUP_SIZE_CHANGED = "internal:group:sizeChanged";
+/**
+ * @internal
+ */
+export declare const EVENT_INTERNAL_GROUP_SIZE_CHANGED_REDO = "internal:group:sizeChangedRedo";
+/**
+ * @internal
+ */
+export declare const EVENT_INTERNAL_GROUP_SIZE_CHANGED_UNDO = "internal:group:sizeChangedUndo";
+/**
+ * @internal
+ * @payload RendererAddedParams
+ */
+export declare const EVENT_RENDERER_ADDED = "renderer:added";
+/**
+ * Fired as the user starts to drag a node
+ * @category UI
+ * @payload VertexMoveStartParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_NODE_MOVE_START = "node:move:start";
+/**
+ * Fired each time the mouse/pointer moves while a node is being dragged.
+ * @category UI
+ * @payload VertexMoveParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_NODE_MOVE = "node:move";
+/**
+ * Fired at the end of a node drag
+ * @category UI
+ * @payload VertexMoveEndParams
+ * @event
+ * @context element-dragging
+ */
+export declare const EVENT_NODE_MOVE_END = "node:move:end";
+/**
+ * Fired when the undo/redo manager has performed an undo or a redo.
+ * @event
+ * @category Model
+ * @context undo-redo
+ */
+export declare const EVENT_UNDOREDO_UPDATE = "undoredo:update";
+/**
+ * Fired when the `undo` operation has occurred in the model
+ * @group Constants
+ * @category Model
+ * @context undo-redo
+ */
+export declare const EVENT_UNDO = "undo";
+/**
+ * Fired when the `redo` operation has occurred in the model
+ * @group Constants
+ * @category Model
+ * @context undo-redo
+ */
+export declare const EVENT_REDO = "redo";
+/**
+ * Fired when a renderer is destroyed.
+ * @event
+ * @category UI
+ */
+export declare const EVENT_DESTROY = "destroy";

package/types/core/event-generator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Base class for classes that wish to support binding and firing of events.
+ *
+ * @remarks You need to implement the `shouldFireEvent` method in your concrete subclasses of this class, or you can instead extend from `OptimisticEventGenerator`, which has a default implementation of `shouldFireEvent` that returns true.
+ *
+ * @internal
+ */
+export declare abstract class EventGenerator<EVT = any> {
+    private _listeners;
+    private _eventsSuspended;
+    private _tick;
+    private _eventsToDieOn;
+    private _queue;
+    protected abstract shouldFireEvent(event: string, value: any, originalEvent?: Event): boolean;
+    constructor();
+    /**
+     * Fire the named event.
+     * @param event Event to fire
+     * @param value Value to pass to event handlers
+     * @param originalEvent Optional original event that caused this event to be fired.
+     *
+     * @internal
+     */
+    fire<T>(event: EVT, value?: T, originalEvent?: Event): any;
+    /**
+     * Fire the named event.
+     * @param event Event to fire
+     * @param value Value to pass to event handlers
+     * @param originalEvent Optional original event that caused this event to be fired.
+     *
+     * @internal
+     *
+     * @deprecated Try to avoid using this method. The goal in the medium term is to not support firing events that cannot be checked at compile time.
+     */
+    fireUnchecked<T>(event: string, value?: T, originalEvent?: Event): any;
+    /**
+     * Drain the queue of pending event notifications
+     * @internal
+     */
+    private _drain;
+    /**
+     * Unbind the given event listener, or all listeners. If you call this method with no arguments then all event listeners are unbound.
+     * @param eventOrListener Either an event name, or an event handler function
+     * @param listener If `eventOrListener` is defined, this is the event handler to unbind.
+     *
+     */
+    unbind(eventOrListener?: string | Function, listener?: Function): EventGenerator;
+    /**
+     * Gets all listeners for the given named event.
+     * @param forEvent
+     * @internal
+     */
+    getListener(forEvent: string): Array<any>;
+    /**
+     * Returns whether not event firing is currently suspended
+     * @internal
+     */
+    isSuspendEvents(): boolean;
+    /**
+     * Sets whether not event firing is currently suspended
+     * @internal
+     */
+    setSuspendEvents(val: boolean): void;
+    /**
+     * Bind a listener to the named event, optionally inserting the listener at the head of the queue for the given event.
+     * @param event Name of the event to bind
+     * @param listener Function to bind to the event
+     * @param insertAtStart Defaults to false. If true, this handler is inserted at the head of the list of listeners for the given event.
+     * @typeParam T The type of the payload you expect to be passed to your callback. Using this is helpful to ensure your callbacks are typed correctly.
+     */
+    bind<T = any>(event: EVT, listener: (payload: T, evt?: any) => any, insertAtStart?: boolean): EventGenerator;
+    /**
+     * Bind a listener to all of the named events, optionally inserting each one at the head of the queue for the given event.
+     * @param events
+     * @param listener
+     * @param insertAtStart
+     * @typeParam T The type of the payload you expect to be passed to your callback. Using this is helpful to ensure your callbacks are typed correctly.
+     */
+    bindAll<T = any>(events: Array<EVT>, listener: (payload: T, evt?: any) => any, insertAtStart?: boolean): EventGenerator;
+    /**
+     * Bind an event listener. This method can be used with a type parameter by call sites; although it's not necessary it can be helpful to use this to ensure you've thought about what the payload to your event handler is going to be.
+     * @param event Name of the event(s) to bind to.
+     * @param listener Function to bind to the given event(s)
+     * @param insertAtStart Whether or not to insert this listener at the head of the listener queue. Defaults to false.
+     * @typeParam T The type of the payload you expect to be passed to your callback. Using this is helpful to ensure your callbacks are typed correctly.
+     *
+     */
+    bindUnchecked<T = any>(event: string, listener: (a: T, e?: any) => any, insertAtStart?: boolean): EventGenerator;
+    /**
+     * Run the given function without firing any events.
+     * @param fn
+     * @internal
+     */
+    silently(fn: Function): void;
+}
+/**
+ * Subclass of EventGenerator with a default implementation of `shouldFireEvent`, which returns true always.
+ * @internal
+ */
+export declare class OptimisticEventGenerator<EVT = any> extends EventGenerator<EVT> {
+    shouldFireEvent(event: string, value: any, originalEvent?: Event): boolean;
+}

package/types/core/filterable-dataset.d.ts

@@ -0,0 +1,38 @@
+import { Node, Edge, Group, Vertex } from "./model/graph";
+/**
+ * Offers methods to invoke operations on dataset contents, and to filter the contents.
+ * @group Model
+ */
+export interface FilterableDataset {
+    /**
+     * Invoke the given function on each node in the dataset
+     * @param fn
+     */
+    eachNode(fn: (i: number, n: Node) => void): void;
+    /**
+     * Invoke the given function on each edge in the dataset
+     * @param fn
+     */
+    eachEdge(fn: (i: number, e: Edge) => void): void;
+    /**
+     * Invoke the given function on each group in the dataset
+     * @param fn
+     */
+    eachGroup(fn: (i: number, e: Group) => void): void;
+    /**
+     * Invoke the given function on each vertex (node or group) in the dataset
+     * @param fn
+     */
+    eachVertex(fn: (i: number, e: Vertex) => void): void;
+    /**
+     * Filter the dataset and return a filtered copy.
+     * @param spec
+     * @param includePartials
+     */
+    filter(spec: any, includePartials?: boolean): any;
+}
+/**
+ * @internal
+ * @param obj
+ */
+export declare function isFilterableDataset(obj: any): obj is FilterableDataset;