@visuallyjs/browser-ui 1.0.0

package/types/core/model/path.d.ts

@@ -0,0 +1,227 @@
+import { VisuallyJsModel } from "../toolkit";
+import { Edge, Group, Node, Vertex } from "./graph";
+import { ShortestPathComponent, ShortestPathResult } from "./djikstra";
+import { FilterableDataset } from "../filterable-dataset";
+/**
+ * Options for a Path.
+ * @group Data Model
+ * @category Graph Objects
+ */
+export interface PathOptions {
+    /**
+     * Path source. Either a vertex (node/group/port) or a vertex id.
+     */
+    source: string | Vertex;
+    /**
+     * Path target. Either a vertex (node/group/port) or a vertex id.
+     */
+    target: string | Vertex;
+    /**
+     * Sets whether or not paths are searched strictly by the given source/target. If you supply a node as the source, but there are only edges connected to ports on that node, by default these edges will be ignored. Switching `strict` to false will mean these edges are considered.
+     */
+    strict?: boolean;
+    /**
+     * This function is given each Node/Group's backing data and asked to return true or false - true means include the Node/Group, false means exclude it.
+     * @param n
+     */
+    nodeFilter?: (n: Node) => boolean;
+    /**
+     * This function is given each Edge's backing data and asked to return true or false - true means include the Edge, false means exclude it.
+     * @param n
+     */
+    edgeFilter?: (n: Edge) => boolean;
+}
+/**
+ * Models the path between two vertices, which consists of a series of vertices connected by edges.
+ * @group Data Model
+ * @category Graph Objects
+ */
+export interface Path extends FilterableDataset {
+    /**
+     * Deletes, from the underlying model, all of the edges in this path.
+     */
+    deleteEdges(): void;
+    /**
+     * Deletes, from the underlying model, all the nodes/groups in this path. As with the `contains` method, there is a special consideration here: if a path passes through ports on a node/group, then that node/group will be, for the purposes of this method, considered to be part of the path and it will be deleted.  If you instead wish to delete only the ports in a path, use `deletePorts`.  Note that this method will, of course, have the effect of also deleting all the edges, since the nodes/groups for those edges will no longer exist.
+     */
+    deleteVertices(): void;
+    /**
+     * Returns true if the path contains the given object (a node, group, port or edge), false otherwise.
+     * @param obj Node/Port/Edge, or object id, of the element to test for.
+     * @param doNotFuzzyMatchNodes By default, if you pass a node/group in to this method and the path passes through a port on that node/group, this method returns true. But if you set `doNotFuzzyMatchNodes` to true, then this method will return true only if the node/group itself is on the path.
+     * @returns True if Path contains the object, false otherwise.
+     */
+    contains(obj: Edge | Vertex, doNotFuzzyMatchNodes?: boolean): boolean;
+    /**
+     * Get all the vertices in the path.
+     */
+    getVertices(): Array<Vertex>;
+    /**
+     * Retrieve the specified vertex from the path
+     * @param obj Either a vertex ID or a node/group/port.
+     * @returns A Vertex, if the given vertex is in the path, otherwise null.
+     */
+    getVertex(obj: string | Vertex): Vertex;
+    /**
+     * Gets all the edges in the path that are connected to the given vertex.
+     * @param v Vertex to get edges for.
+     */
+    getAllEdgesFor(v: Vertex): Array<Edge>;
+    /**
+     * Iterates through the path one step at a time. Each step consists of an object containing a `vertex`, and, for all entries except the first, an `edge` member, which supplies the Edge that links to the Vertex (which is why it is null for the first entry).
+     * @param fn Function to call for each step.
+     */
+    each(fn: (i: number, p: ShortestPathComponent) => any): void;
+    /**
+     * Counts the number of vertices in the Path (including the start and end nodes/groups).  Note that for the purposes of this calculation, a Port is considered a vertex, as is a Group.
+     */
+    getVertexCount(): number;
+    /**
+     * Gets the Vertex at the given index in the path.
+     * @param idx Index of the vertex to retrieve.
+     * @returns vertex at the given index, or null if no vertex exists at the given index.
+     */
+    getNodeAt(idx: number): Vertex;
+    /**
+     * Counts the number of edges in the path.  This may be zero, if the given path spec did not select a valid path in the model.
+     */
+    getEdgeCount(): number;
+    /**
+     * Gets the Edge at the given index in the Path.
+     * @param idx Index of the Edge to retrieve. You can use negative numbers here: an index of -1 means get the last edge. An index of -2 means get the last but one. etc.
+     */
+    getEdgeAt(idx: number): Edge;
+    /**
+     * Removes all vertices and edges in this path from the underlying Toolkit. This is an alias for `deleteVertices`, since deleting a vertex causes its edges to also be deleted.
+     */
+    deleteAll(): void;
+    /**
+     * Returns whether or not a given path is empty
+     * @returns True if path is empty, false otherwise.
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the cost of the given path.  Edges in VisuallyJs can have a cost associated with them (the default is 1), and so the cost of any given path is the sum of the cost of all of the edges in the path.
+     * @returns Total cost of the Path. Null if path does not exist.
+     */
+    getCost(): number;
+    /**
+     * Returns whether or not a given path exists.
+     * @returns True if path exists, false otherwise.
+     */
+    exists(): boolean;
+    /**
+     * @internal
+     */
+    result: ShortestPathResult;
+}
+/**
+ * Implementation of the Path interface
+ * @internal
+ */
+export declare class PathImpl implements Path {
+    instance: VisuallyJsModel;
+    result: ShortestPathResult;
+    private _vertices;
+    private _vertexMap;
+    /**
+     * @param instance model instance from which to get the path info.
+     * @param params Path specification
+     */
+    constructor(instance: VisuallyJsModel, params?: PathOptions);
+    /**
+     * Deletes, from the underlying model, all of the edges in this path.
+     */
+    deleteEdges(): this;
+    /**
+     * Deletes, from the underlying model, all the nodes/groups in this path. As with the `contains` method, there is a special consideration here: if a path passes through ports on a node/group, then that node/group will be, for the purposes of this method, considered to be part of the path and it will be deleted.  If you instead wish to delete only the ports in a path, use `deletePorts`.  Note that this method will, of course, have the effect of also deleting all the edges, since the nodes/groups for those edges will no longer exist.
+     */
+    deleteVertices(): this;
+    /**
+     * Returns true if the path contains the given object (a node, group, port or edge), false otherwise.
+     * @param obj Node/Port/Edge, or object id, of the element to test for.
+     * @param doNotFuzzyMatchNodes By default, if you pass a node/group in to this method and the path passes through a port on that node/group, this method returns true. But if you set `doNotFuzzyMatchNodes` to true, then this method will return true only if the node/group itself is on the path.
+     * @returns True if Path contains the object, false otherwise.
+     */
+    contains(obj: Edge | Vertex, doNotFuzzyMatchNodes?: boolean): boolean;
+    /**
+     * Get all the vertices in the path.
+     */
+    getVertices(): Array<Vertex>;
+    /**
+     * Retrieve the specified vertex from the path
+     * @param obj Either a vertex ID or a node/group/port.
+     * @returns A Vertex, if the given vertex is in the path, otherwise null.
+     */
+    getVertex(obj: string | Vertex): Vertex;
+    /**
+     * Gets all the edges in the path that are connected to the given vertex.
+     * @param v Vertex to get edges for.
+     */
+    getAllEdgesFor(v: Vertex): Array<Edge>;
+    filter(spec: any, includePartials?: boolean): void;
+    private _each;
+    /**
+     * Iterates through the path one step at a time. Each step consists of an object containing a `vertex`, and, for all entries except the first, an `edge` member, which supplies the Edge that links to the Vertex (which is why it is null for the first entry).
+     * @param fn Function to call for each step.
+     */
+    each(fn: (i: number, p: ShortestPathComponent) => any): void;
+    /**
+     * Iterates through the Nodes/Groups/Ports in the path one step at a time.
+     * @param fn Function to call for each step.
+     */
+    eachVertex(fn: (idx: number, v: Vertex) => any): void;
+    /**
+     * Iterates through the Edges in the path one step at a time. There is always one fewer Edges than Nodes/Ports.
+     * @param fn Function to call for each step.
+     */
+    eachEdge(fn: (i: number, e: Edge) => any): void;
+    /**
+     * Iterates through the Nodes in the path one step at a time.
+     * @param fn Function to call for each step.
+     */
+    eachNode(fn: (i: number, n: Node) => void): void;
+    /**
+     * Iterates through the Groups in the path one step at a time.
+     * @param fn Function to call for each step.
+     */
+    eachGroup(fn: (i: number, g: Group) => void): void;
+    /**
+     * Counts the number of vertices in the Path (including the start and end nodes/groups).  Note that for the purposes of this calculation, a Port is considered a vertex, as is a Group.
+     */
+    getVertexCount(): number;
+    /**
+     * Gets the Vertex at the given index in the path.
+     * @param idx Index of the vertex to retrieve.
+     * @returns vertex at the given index, or null if no vertex exists at the given index.
+     */
+    getNodeAt(idx: number): Vertex;
+    /**
+     * Counts the number of edges in the path.  This may be zero, if the given path spec did not select a valid path in the Toolkit instance.
+     */
+    getEdgeCount(): number;
+    /**
+     * Gets the Edge at the given index in the Path.
+     * @param idx Index of the Edge to retrieve. You can use negative numbers here: an index of -1 means get the last edge. An index of -2 means get the last but one. etc.
+     */
+    getEdgeAt(idx: number): Edge;
+    /**
+     * Removes all vertices and edges in this path from the underlying Toolkit. This is an alias for `deleteVertices`, since deleting a vertex causes its edges to also be deleted.
+     */
+    deleteAll(): void;
+    /**
+     * Returns whether or not a given path is empty
+     * @returns True if path is empty, false otherwise.
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the cost of the given path.  Edges in the Toolkit can have a cost associated with them (the default is 1), and so the cost of any given path is the sum of the cost of all of the edges in the path.
+     * @returns Total cost of the Path. Null if path does not exist.
+     */
+    getCost(): number;
+    /**
+     * Returns whether or not a given path exists.
+     * @returns True if path exists, false otherwise.
+     */
+    exists(): boolean;
+}

package/types/core/params.d.ts

@@ -0,0 +1,476 @@
+import { Group, Node, ObjectData, Port, Edge, Vertex, Base } from "./model/graph";
+import { VisuallyJsRenderer } from "./renderer";
+import { PointXY } from "./util";
+import { EdgeUpdatedReason, VertexUpdatedReason } from "./toolkit";
+import { VisuallyJsSelection } from "./selection";
+import { ObjectAnchorSpec } from "./model/anchor";
+/**
+ * Defines the payload for a node added event.
+ * @group Events
+ * @category Payloads
+ */
+export interface NodeAddedParams {
+    node: Node;
+    eventInfo?: any;
+    parentGroup?: Group;
+}
+/**
+ * Defines the payload for a port added event.
+ * @group Events
+ * @category Payloads
+ */
+export interface PortAddedParams {
+    vertex: Node | Group;
+    data: ObjectData;
+    port: Port;
+}
+/**
+ * Defines the payload for a selection cleared event.
+ * @group Events
+ * @category Payloads
+ */
+export interface SelectionClearedParams {
+    selection: VisuallyJsSelection;
+}
+/**
+ * Defines the payload for a selection event.
+ * @group Events
+ * @category Payloads
+ */
+export interface SelectionParams {
+    /**
+     * Selection this event pertains to
+     */
+    selection: VisuallyJsSelection;
+    /**
+     * The subject of the selection event
+     */
+    obj: Base;
+    /**
+     * Optional reason for the selection event, which can be passed to the model when selecting some object.
+     */
+    reason?: string;
+}
+/**
+ * Payload for a group member added event in the model.
+ * @group Events
+ * @category Payloads
+ */
+export interface GroupMemberAddedParams {
+    /**
+     * Vertex that was added to the group
+     */
+    vertex: Node | Group;
+    /**
+     * Group the vertex was added to
+     */
+    group: Group;
+    /**
+     * Optional original location for the vertex that was added
+     */
+    originalPosition?: PointXY;
+    /**
+     * Optional new location for the vertex that was added
+     */
+    pos?: PointXY;
+    /**
+     * If a vertex being added to some group is currently a member of some other group, that group is provided here.
+     */
+    sourceGroup?: Group;
+    /**
+     * @internal
+     */
+    source?: VisuallyJsRenderer<any>;
+    /**
+     * Set to true if the vertex is also brand new, not copied from elsewhere in the dataset.
+     */
+    vertexIsNew?: boolean;
+    /**
+     * @internal
+     */
+    payload?: Record<string, any>;
+    positionInGroup?: PointXY;
+}
+/**
+ * Payload for a group member removed event in the model
+ * @group Events
+ * @category Payloads
+ */
+export interface GroupMemberRemovedParams {
+    /**
+     * Vertex that was removed from the group
+     */
+    vertex: Node | Group;
+    /**
+     * Group the vertex was removed from
+     */
+    group: Group;
+    /**
+     * @internal
+     */
+    source?: VisuallyJsRenderer<any>;
+    /**
+     * If the vertex is being moved to some other group, that group is provided here.
+     */
+    targetGroup?: Group;
+    /**
+     * Optional new position for the vertex.
+     */
+    newPosition?: PointXY;
+    /**
+     * Optional original position for the vertex.
+     */
+    originalPosition?: PointXY;
+}
+/**
+ * Payload for a group added event in the model
+ * @group Events
+ * @category Payloads
+ */
+export interface GroupAddedParams {
+    /**
+     * Group that was added
+     */
+    group: Group;
+    /** @internal */
+    eventInfo?: any;
+    /**
+     * If the group is a child of some other group, that group is provided here.
+     */
+    parentGroup?: Group;
+}
+/**
+ * Payload for a group added event in the model
+ * @group Events
+ * @category Payloads
+ */
+export interface GroupRemovedParams {
+    /**
+     * Group that was removed
+     */
+    group: Group;
+    /**
+     * If true, indicates the group's children were also removed
+     */
+    removeChildren?: boolean;
+    /**
+     * If children were removed, this is the list of them
+     */
+    children: Array<Node | Group>;
+    /**
+     * If the group was a member of some other group, that group is provided here
+     */
+    parentGroup?: Group;
+    /**
+     * Indicates that the group is being removed because some parent group is being removed and is forcing removal of its children.
+     */
+    parentGroupIsBeingRemoved: boolean;
+}
+/**
+ * Payload for a node removed event in the model
+ * @group Events
+ * @category Payloads
+ */
+export interface NodeRemovedParams {
+    /**
+     * Node that was removed
+     */
+    node: Node;
+    /**
+     * List of edges that are being removed as a result of this node's removal.
+     */
+    edges: Array<Edge>;
+    /**
+     * If the node was a member of some other group, that group is provided here
+     */
+    parentGroup?: Group;
+    /**
+     * Indicates that the node is being removed because some parent group is being removed and is forcing removal of its children.
+     */
+    parentGroupIsBeingRemoved: boolean;
+}
+/**
+ * Payload for a vertex updated event.
+ * @group Events
+ * @category Payloads
+ */
+export interface VertexUpdatedParams {
+    vertex: Node | Group;
+    updates: ObjectData;
+    originalData: ObjectData;
+    originalId?: string;
+    originalPortId?: string;
+    reason: VertexUpdatedReason;
+    port?: Port;
+}
+/**
+ * Payload for a port removed event.
+ * @group Events
+ * @category Payloads
+ */
+export interface PortRemovedParams {
+    vertex: Node | Group;
+    port: Port;
+    edges: Array<Edge>;
+}
+/**
+ * Payload for a port updated event.
+ * @group Events
+ * @category Payloads
+ */
+export interface PortUpdatedParams {
+    vertex: Node | Group;
+    port: Port;
+    updates: ObjectData;
+    originalData: ObjectData;
+    originalId: string;
+    originalPortId?: string;
+}
+/**
+ * Payload for an edge added event
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeAddedParams {
+    edge: Edge;
+    source?: VisuallyJsRenderer<any>;
+    geometry: any;
+    addedByMouse?: boolean;
+    transient?: boolean;
+    reason: ConnectReason;
+}
+/**
+ * Payload for a vertex moved event
+ * @group Events
+ * @category Payloads
+ */
+export interface VertexMovedParams<T> {
+    ui: VisuallyJsRenderer<any>;
+    dragGroup: Array<{
+        el: T;
+        pos: PointXY;
+        originalPosition: PointXY;
+        vertex: Node | Group;
+    }>;
+}
+/**
+ * Payload for an edge updated event
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeUpdatedParams {
+    edge: Edge;
+    updates: ObjectData;
+    originalData: ObjectData;
+    reason?: EdgeUpdatedReason;
+}
+/**
+ * @internal
+ */
+export interface RendererAddedParams {
+    renderer: VisuallyJsRenderer<any>;
+    id: string;
+}
+/**
+ * Payload for an event from the undo/redo manager
+ * @group Events
+ * @category Payloads
+ */
+export interface UndoRedoUpdateParams {
+    /**
+     * Current size of the undo stack
+     */
+    undoCount: number;
+    /**
+     * Current size of the redo stack
+     */
+    redoCount: number;
+}
+/**
+ * Payload for an edge path edited event.
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgePathEditedParams {
+    /**
+     * The UI the user is editing the path on
+     */
+    ui: VisuallyJsRenderer<any>;
+    /**
+     * The edge that was edited
+     */
+    edge: Edge;
+    /**
+     * The edge's new geometry
+     */
+    geometry: any;
+    /**
+     * The edge's original geometry
+     */
+    originalGeometry: any;
+}
+/**
+ * Payload for an edge remove event
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeRemovedParams {
+    edge: Edge;
+    source?: any;
+}
+/**
+ * Superclass for edge target changed/edge source changed payloads.
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeVertexChangedParams {
+    /**
+     * Previous source/target/position
+     */
+    old?: Vertex | PointXY;
+    /**
+     * Current source/target
+     */
+    new?: Vertex | PointXY;
+    /**
+     * Edge that was updated
+     */
+    edge: Edge;
+    /**
+     * Whether or not the operation was successful
+     */
+    success: boolean;
+    /**
+     * The UI in which this operation occurred. Not set if the operation was as a result of a programmatic call to the model.
+     */
+    source?: VisuallyJsRenderer<any>;
+}
+/**
+ * Payload for the event fired when an edge target is changed.
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeTargetChangedParams extends EdgeVertexChangedParams {
+}
+/**
+ * Payload for the event fired when an edge source is changed.
+ * @group Events
+ * @category Payloads
+ */
+export interface EdgeSourceChangedParams extends EdgeVertexChangedParams {
+}
+/**
+ * Options for the select edges method.
+ * @group Edges
+ */
+export interface EdgeSelectionParams {
+    source?: string | Vertex;
+    target?: string | Vertex;
+    element?: string | Vertex;
+    filter?: (e: Edge) => boolean;
+}
+/**
+ * @internal
+ */
+export interface EdgeGeometryParams {
+    edge: Edge;
+    geometry: any;
+    originalGeometry: any;
+}
+export declare const CONNECT_REASON_UNDO_REDO = "undoRedo";
+export declare const CONNECT_REASON_USER_ACTIVITY = "userActivity";
+export declare const CONNECT_REASON_API = "api";
+export declare const CONNECT_REASON_DATA_LOAD = "dataLoad";
+export declare const CONNECT_REASON_TRANSIENT = "transient";
+export declare const CONNECT_REASON_COPY_PASTE = "copyPaste";
+export type ConnectReason = typeof CONNECT_REASON_API | typeof CONNECT_REASON_UNDO_REDO | typeof CONNECT_REASON_USER_ACTIVITY | typeof CONNECT_REASON_DATA_LOAD | typeof CONNECT_REASON_TRANSIENT | typeof CONNECT_REASON_COPY_PASTE;
+/**
+ * Options for loading data.
+ * @group Model
+ * @category Input and Output
+ */
+export interface LoadOptions {
+    /**
+     * Specifies the data type of the data to load. Defaults to `json`. This must match the name of a loader registered with the given instance of VisuallyJs.
+     */
+    type?: string;
+    /**
+     * Optional. JSON data to load directly.
+     */
+    data?: any;
+    /**
+     * URL to retrieve data from. Optional, but you need to supply either this or `data`.
+     */
+    url?: string;
+    /**
+     * Optional, defaults to false. Tells VisuallyJs that the data is coming via JSON-P.
+     */
+    jsonp?: boolean;
+    /**
+     * Optional callback to execute once the data has loaded. Most often used when you are retrieving remote data (using `url`)
+     */
+    onload?: Function;
+    /**
+     * Optional parameters to pass to the loader.
+     */
+    parameters?: Record<string, any>;
+    /**
+     * Optional function to call on load error.
+     * @param e
+     * @param status
+     */
+    error?: (e: any, status?: any) => any;
+    /**
+     * Optional map of HTTP header values, if loading via URL.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional dataType to pass in the request
+     */
+    dataType?: string;
+    /**
+     * By default the model's load method is incremental, meaning it does not clear itself when loading new data. Set this flag to `false` if you want the model to call `clear()` after parsing the data (either passed in directly or having been retrieved from a url) and before loading it.
+     */
+    incremental?: boolean;
+}
+/**
+ * Options for the `addEdge` method in the {@link VisuallyJsModel} class.
+ * @group Edges
+ */
+export interface AddEdgeOptions {
+    /**
+     * Source for the edge - a vertex, vertex id, or canvas location.
+     */
+    source: Vertex | string | PointXY;
+    /**
+     * Target for the edge - a vertex, vertex id, or canvas location.
+     */
+    target: Vertex | string | PointXY;
+    /**
+     * Optional edge geometry.
+     */
+    geometry?: any;
+    /**
+     * Optional backing data for the edge.
+     */
+    data?: any;
+    /**
+     * Optional edge cost. Defaults to 1.
+     */
+    cost?: number;
+    /**
+     * By default edges are not directed. This is used only when computing paths between vertices.
+     */
+    directed?: boolean;
+    /**
+     * @internal
+     */
+    transient?: boolean;
+    /**
+     * Optional anchors for the edge.
+     */
+    anchors?: {
+        source?: ObjectAnchorSpec;
+        target?: ObjectAnchorSpec;
+    };
+}