@visuallyjs/browser-ui 1.0.0

package/types/ui/core/view/common-options.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Common options for edge/node/group/port definitions in a view.
+ * @group Components
+ * @category View
+ */
+export interface BaseViewObjectMapping {
+    /**
+     * Optional ID of one or more edge definitions to include in this definition. The child definition is merged on top of the parent definition(s). Circular references are not allowed and will throw an error.
+     */
+    parent?: string | Array<string>;
+    /**
+     * When merging a type description into its parent(s), values in the child for `connector`, `anchor` and `anchors` will always overwrite any such values in the parent. But other values, such as `overlays`, will be merged with their parent's entry for that key. You can force a child's type to override _every_ corresponding value in its parent by setting `mergeStrategy:'override'`.
+     */
+    mergeStrategy?: string;
+}

package/types/ui/core/view/edge-options.d.ts

@@ -0,0 +1,126 @@
+import { Edge } from "../../../core";
+import { BaseViewObjectMapping } from "./common-options";
+import { AnchorSpec, ConnectorSpec, OverlaySpec, PaintStyle } from "../../common";
+import { OverlayVisibility } from "../overlay/overlay";
+import { EdgeEventOptions } from "./events";
+import { LineStyle } from "../core";
+import { FontSpec } from "../../../browser-ui";
+/**
+ * Definition of the function you can provide as `deleteConfirm` on an edge definition. VisuallyJs gives you the edge to be possibly deleted and the pointer event that instigated the deletion. If you wish to delete the edge you must invoke the `proceed()` function.
+ */
+export type EdgeDeleteConfirmationFunction = (params: {
+    edge: Edge;
+    e: Event;
+}, proceed: () => any) => any;
+/**
+ * The mapping for the definition of an edge inside a view.
+ * @group Components
+ * @category View
+ */
+export interface EdgeMapping extends BaseViewObjectMapping, LineStyle {
+    /**
+     * Name/definition of the connector to use. If you omit this, the default connector will be used.
+     */
+    connector?: ConnectorSpec;
+    /**
+     * Spec for the anchor to use for both source and target for edges of this type.
+     */
+    anchor?: AnchorSpec;
+    /**
+     * [source, target] anchor specs edges of this type.
+     */
+    anchors?: [AnchorSpec, AnchorSpec];
+    /**
+     * Paint style to use for the edge.
+     */
+    paintStyle?: PaintStyle;
+    /**
+     * Paint style to use for the edge when the pointer is hovering over it.
+     */
+    hoverPaintStyle?: PaintStyle;
+    /**
+     * Array of overlays to add to edges of this type.
+     */
+    overlays?: Array<OverlaySpec>;
+    /**
+     * Optional overlay to place at the source of an edge of this type. Location will be set to 0 and direction will be set to -1. This is a shorthand for declaring an overlay at location 0 in the overlays array.
+     */
+    sourceMarker?: OverlaySpec;
+    /**
+     * Optional overlay to place at the target of an edge of this type. Location will be set to 1 and direction will be set to 1. This is a shorthand for declaring an overlay at location 1 in the overlays array.
+     */
+    targetMarker?: OverlaySpec;
+    /**
+     * CSS class to add to edges of the type in the UI
+     */
+    cssClass?: string;
+    /**
+     * Whether or not edges of this type should be detachable with the mouse. Defaults to true.
+     */
+    detachable?: boolean;
+    /**
+     * Optional label to use for the edge. If this is set, a label overlay will be created and the value of `label` will be used as the overlay's label. This value can be parameterised, in order to extract a value from the edge's backing data, eg. if you set `label:"{{name}}"` then VisuallyJs would attempt to extract a property with key `name` from the edge's backing data, and use that property's value as the label.
+     */
+    label?: string;
+    /**
+     * Optional css class to set on the label overlay created if `label` is set. This is a static string and does not support parameterisation like `label` does.
+     */
+    labelClass?: string;
+    /**
+     * Optional location for the label. If not provided this defaults to 0.5, but the label location can be controlled via the `labelLocationAttribute`.
+     */
+    labelLocation?: number;
+    /**
+     * This defaults to `labelLocation`, and indicates the name of a property whose value can be expected to hold the location at which the label overlay should be located. The default value for this is `labelLocation`, but the key here is that VisuallyJs looks in the edge data for `labelLocation`, so the location is dynamic, and can be changed by updating `labelLocation`. This parameter allows you to change the name of the property that VisuallyJs will look for in the edge data.
+     */
+    labelLocationAttribute?: string;
+    /**
+     * Optional spec for label font. Will use browser defaults if not specified (or CSS, but remember that CSS is not taken into account when you export an SVG from a diagram or an app using an SVG container)
+     */
+    labelFont?: FontSpec;
+    /**
+     * Optional width of the edge's outline. Defaults to 0.
+     */
+    /**
+     * Whether or not when a user detaches a edge of this type it should be automatically reattached. Defaults to false.
+     */
+    reattach?: boolean;
+    /**
+     * By default, an SVG element will be used for an edge's label overlay. This is good because the label can be exported as part of an SVG export of your canvas.  If you wish to use an HTML element instead, set this flag.
+     */
+    useHTMLLabel?: boolean;
+    /**
+     * If true, the edge will be routed to avoid any vertices. Note that if your edge has any user edits, or was loaded with a path specified, the edge will not be routed to avoid vertices.
+     */
+    avoidVertices?: boolean;
+    /**
+     * Optional delete button.
+     */
+    deleteButton?: boolean | OverlayVisibility;
+    /**
+     * Location for an edge's delete button, if applicable. Defaults to 0.1. You can supply an array of locations if you want multiple buttons.
+     */
+    deleteButtonLocation?: number | Array<number>;
+    /**
+     * An optional function to invoke if the user presses the delete button on some edge. When this is present and the user clicks an edge delete button, instead of just deleting the edge, this function is invoked. It is passed the edge that is a candidate for deletion, and a function which you must invoke if you wish to proceed.
+     * @param e
+     * @param proceed
+     */
+    deleteConfirm?: EdgeDeleteConfirmationFunction;
+    /**
+     * Optional class name to set on the delete button. Defaults to "vjs-edge-delete".
+     */
+    deleteButtonClass?: string;
+    /**
+     * Whether or not to allow this type of edge to have a source and/or target in whitespace rather than connected to a vertex. Defaults to false. When this is set to true, a user may drag a new edge of this type and drop it into whitespace, and they may also - subject to whether or not the edge is detachable - detach an edge of this type via the mouse/pointer events, and drop into whitespace. If you do not need this level of control you can also use the `allowUnattached` flag in the `edges` section of the UI render options. If you have this set on an edge type, it will override `allowUnattached` from the edges UI options.
+     */
+    allowUnattached?: boolean;
+    /**
+     * Optional map of event bindings.
+     */
+    events?: EdgeEventOptions;
+    /**
+     * Whether or not to ignore (ie. exclude from the display) edges of this type.
+     */
+    ignore?: boolean;
+}

package/types/ui/core/view/events.d.ts

@@ -0,0 +1,159 @@
+import { EVENT_GROUP_MOVE_END, EVENT_GROUP_MOVE_START, EVENT_NODE_MOVE_END, EVENT_NODE_MOVE_START, Group, Port, Node, VisuallyJsModel, Edge } from "../../../core";
+import { EVENT_CONTEXTMENU, EVENT_DBLTAP, EVENT_TAP, EVENT_VERTEX_CLICK, EVENT_MOUSEOUT, EVENT_MOUSEUP, EVENT_MOUSEOVER, EVENT_MOUSEMOVE, EVENT_VERTEX_DBLCLICK, EVENT_VERTEX_DBLTAP, EVENT_VERTEX_CONTEXTMENU, EVENT_VERTEX_MOUSEMOVE, EVENT_VERTEX_MOUSEOVER, EVENT_VERTEX_MOUSEOUT, EVENT_VERTEX_TAP, EVENT_EDGE_CLICK, EVENT_EDGE_DBLCLICK, EVENT_EDGE_TAP, EVENT_EDGE_MOUSEDOWN, EVENT_EDGE_MOUSEUP, EVENT_EDGE_DBLTAP, EVENT_EDGE_MOUSEOVER, EVENT_EDGE_MOUSEOUT, EVENT_CANVAS_CLICK, EVENT_CANVAS_DBLCLICK, EVENT_PAN, EVENT_CLICK, EVENT_DBLCLICK, EVENT_MOUSEDOWN } from "../event-constants";
+import { UICore } from "../core";
+import { Connection } from "../connector/connection-impl";
+/**
+ * Events that can be bound in UI render options.
+ * @group Events
+ */
+export type BindableRenderEvent = typeof EVENT_VERTEX_CLICK | typeof EVENT_VERTEX_DBLCLICK | typeof EVENT_VERTEX_CONTEXTMENU | typeof EVENT_VERTEX_DBLTAP | typeof EVENT_VERTEX_MOUSEMOVE | typeof EVENT_VERTEX_MOUSEOUT | typeof EVENT_VERTEX_MOUSEOVER | typeof EVENT_VERTEX_TAP | typeof EVENT_EDGE_CLICK | typeof EVENT_EDGE_DBLCLICK | typeof EVENT_EDGE_TAP | typeof EVENT_EDGE_DBLTAP | typeof EVENT_EDGE_MOUSEDOWN | typeof EVENT_EDGE_MOUSEUP | typeof EVENT_EDGE_MOUSEOVER | typeof EVENT_EDGE_MOUSEOUT | typeof EVENT_CANVAS_CLICK | typeof EVENT_CANVAS_DBLCLICK | typeof EVENT_PAN | typeof EVENT_NODE_MOVE_END | typeof EVENT_GROUP_MOVE_END | typeof EVENT_NODE_MOVE_START | typeof EVENT_GROUP_MOVE_START;
+/**
+ * Events that can be bound in a view.
+ * @group Events
+ */
+export type BindableViewEvent = typeof EVENT_CLICK | typeof EVENT_DBLCLICK | typeof EVENT_TAP | typeof EVENT_DBLTAP | typeof EVENT_CONTEXTMENU | typeof EVENT_MOUSEDOWN | typeof EVENT_MOUSEOUT | typeof EVENT_MOUSEUP | typeof EVENT_MOUSEOVER | typeof EVENT_MOUSEMOVE;
+/**
+ * The payload passed to a {@link NodeEventCallback}
+ */
+export interface NodeEventCallbackPayload<EL> {
+    /**
+     * Element that represents the vertex in the UI
+     */
+    el: EL;
+    /**
+     * The model object for the vertex
+     */
+    obj: Node;
+    /**
+     * The pointer event that caused the event handler to be invoked
+     */
+    e: MouseEvent;
+    /**
+     * The underlying VisuallyJs model
+     */
+    model: VisuallyJsModel;
+    /**
+     * The UI that rendered this vertex
+     */
+    ui: UICore<EL>;
+}
+/**
+ * The payload passed to a {@link GroupEventCallback}
+ */
+export interface GroupEventCallbackPayload<EL> {
+    /**
+     * Element that represents the vertex in the UI
+     */
+    el: EL;
+    /**
+     * The group in the model
+     */
+    obj: Group;
+    /**
+     * The pointer event that caused the event handler to be invoked
+     */
+    e: MouseEvent;
+    /**
+     * The underlying VisuallyJs model
+     */
+    model: VisuallyJsModel;
+    /**
+     * The UI that rendered this vertex
+     */
+    ui: UICore<EL>;
+}
+/**
+ * The payload passed to a {@link PortEventCallback}
+ */
+export interface PortEventCallbackPayload<EL> {
+    /**
+     * Element that represents the vertex in the UI
+     */
+    el: EL;
+    /**
+     * The group in the model
+     */
+    obj: Port;
+    /**
+     * The pointer event that caused the event handler to be invoked
+     */
+    e: MouseEvent;
+    /**
+     * The underlying VisuallyJs model
+     */
+    model: VisuallyJsModel;
+    /**
+     * The UI that rendered this vertex
+     */
+    ui: UICore<EL>;
+}
+/**
+ * The payload passed to an {@link EdgeEventCallback}
+ */
+export interface EdgeEventCallbackPayload {
+    /**
+     * The connection rendered by the UI
+     */
+    connection: Connection<any>;
+    /**
+     * The edge that the event occurred on
+     */
+    obj: Edge;
+    /**
+     * The event that invoked this callback
+     */
+    e: MouseEvent;
+    /**
+     * The underlying model
+     */
+    model: VisuallyJsModel;
+    /**
+     * The UI that drew this edge
+     */
+    ui: UICore<any>;
+}
+export default EdgeEventCallbackPayload;
+/**
+ * The definition of a callback function for an edge event mapped in a view.
+ */
+export type EdgeEventCallback = (p: EdgeEventCallbackPayload) => any;
+/**
+ * The definition of a callback function for a node event mapped in a view.
+ */
+export type NodeEventCallback<EL> = (p: NodeEventCallbackPayload<EL>) => any;
+/**
+ * The definition of a callback function for a port event mapped in a view.
+ */
+export type PortEventCallback<EL> = (p: PortEventCallbackPayload<EL>) => any;
+/**
+ * The definition of a callback function for a group event mapped in a view.
+ */
+export type GroupEventCallback<EL> = (p: GroupEventCallbackPayload<EL>) => any;
+/**
+ * Events that can be mapped in a node definition in a view.
+ * @group Events
+ */
+export type NodeEventOptions<EL> = {
+    [K in BindableViewEvent]?: NodeEventCallback<EL>;
+};
+/**
+ * Events that can be mapped in a group definition in a view.
+ * @group Events
+ */
+export type GroupEventOptions<EL> = {
+    [K in BindableViewEvent]?: GroupEventCallback<EL>;
+};
+/**
+ * Events that can be mapped in a port definition in a view.
+ * @group Events
+ */
+export type PortEventOptions<EL> = {
+    [K in BindableViewEvent]?: PortEventCallback<EL>;
+};
+/**
+ * Events that can be mapped in an edge definition in a view.
+ * @group Events
+ */
+export type EdgeEventOptions = {
+    [K in BindableViewEvent]?: EdgeEventCallback;
+};

package/types/ui/core/view/group-options.d.ts

@@ -0,0 +1,75 @@
+import { LayoutParameters, Group, Size, GroupDefinition, Node } from "../../../core";
+import { GroupEventOptions } from "./events";
+import { AnchorSpec } from "../../common";
+import { NodeOrGroupMapping } from "./node-options";
+/**
+ * The mapping for the definition of a group inside a view.
+ * @group Components
+ * @category View
+ */
+export interface GroupMapping<EL> extends NodeOrGroupMapping<Group, EL, GroupEventOptions<EL>>, GroupDefinition {
+    /**
+     * True by default - indicates that child members may be dragged around inside the group.
+     */
+    elementsDraggable?: boolean;
+    /**
+     * False by default - nodes/groups may be dragged outside of the bounds of the group.
+     */
+    constrain?: boolean;
+    /**
+     * Spec for the anchor to use for connections to children of the group when they are transferred to the group in its collapsed state.
+     */
+    anchor?: AnchorSpec;
+    /**
+     * Optional interceptor that will be invoked to test whether a given node/group may be dropped onto this group.
+     * @param v
+     */
+    canDrop?: (v: Node | Group) => boolean;
+    /**
+     * False by default. This flag switches on both `autoShrink` and `autoGrow` and also enables support for shrinking a group from its left or top edge
+     */
+    autoSize?: boolean;
+    /**
+     * False by default.  If true indicates that if a child member is dragged/added/removed and the group's size is recalculated to be smaller than the previous size, the new size should be applied. This also works if the group needs to shrink from its left and/or top edge. If you don't want that behaviour, set `allowShrinkFromOrigin` to false.
+     */
+    autoShrink?: boolean;
+    /**
+     * Defaults to false, meaning that the group will not be resized if an item addition/removal or drag causes the bounds of the child members to change and the new size is greater than the previous size.
+     */
+    autoGrow?: boolean;
+    /**
+     * Similar to autoGrow, but the UI shows a visual prompt when a group will be resized as a result of dragging a child.
+     */
+    elastic?: boolean;
+    /**
+     * Maximum size the group can grow to. If not specified the group can grow to an arbitrary size. Note that this behaviour can also be enforced via CSS.
+     */
+    maxSize?: Size;
+    /**
+     * Minimum size the group can be.
+     */
+    minSize?: Size;
+    /**
+     * Optional padding to set inside a group when computing an auto size.
+     */
+    padding?: number;
+    /**
+     * Options for the group's layout.
+     */
+    layout?: {
+        type: string;
+        options?: LayoutParameters;
+    };
+    /**
+     * When sizing the group, ensure it fits the underlying grid, if there is one.
+     */
+    fitToGrid?: boolean;
+    /**
+     * Optional map of event bindings.
+     */
+    events?: GroupEventOptions<EL>;
+    /**
+     * The size to use for this group type when it is collapsed.
+     */
+    collapsedSize?: Size;
+}

package/types/ui/core/view/index.d.ts

@@ -0,0 +1,35 @@
+import { NodeMapping } from "./node-options";
+import { EdgeMapping } from "./edge-options";
+import { GroupMapping } from "./group-options";
+import { PortMapping } from "./port-options";
+export * from './common-options';
+export * from './edge-options';
+export * from './events';
+export * from './group-options';
+export * from './node-options';
+export * from './node-or-port-options';
+export * from './port-options';
+export * from './vertex-options';
+/**
+ * Mappings of vertex/edge types to their rendering and behaviour.
+ * @group Components
+ * @category View
+ */
+export interface ViewSpec<EL> {
+    /**
+     * Node mappings for the view.
+     */
+    nodes?: Record<string, NodeMapping<EL>>;
+    /**
+     * Edge mappings for the view.
+     */
+    edges?: Record<string, EdgeMapping>;
+    /**
+     * Group mappings for the view.
+     */
+    groups?: Record<string, GroupMapping<EL>>;
+    /**
+     * Port mappings for the view.
+     */
+    ports?: Record<string, PortMapping<EL>>;
+}

package/types/ui/core/view/node-options.d.ts

@@ -0,0 +1,20 @@
+import { NodeOrPortMapping } from "./node-or-port-options";
+import { NodeEventOptions } from "./events";
+import { NodeDefinition, Size, Node } from "../../../core";
+export interface NodeOrGroupMapping<O, EL, EVT> extends NodeOrPortMapping<EL, O, EVT> {
+    /**
+     * Optional default size to use for the vertex. This is not used to set the size in the DOM for a vertex - it is used to insert `width` and `height` values into the backing data for any vertex of this type that does not have them set.
+     */
+    defaultSize?: Size;
+    /**
+     * If true, vertices of this type will be ignored by this UI and not rendered.
+     */
+    ignore?: boolean;
+}
+/**
+ * The mapping for the definition of a node inside a view.
+ * @group Components
+ * @category View
+ */
+export interface NodeMapping<EL> extends NodeOrGroupMapping<Node, EL, NodeEventOptions<EL>>, NodeDefinition {
+}

package/types/ui/core/view/node-or-port-options.d.ts

@@ -0,0 +1,28 @@
+import { VertexMapping } from "./vertex-options";
+/**
+ * Base view mapping for nodes and ports (and groups, since they extend nodes)
+ * @group Components
+ * @category View
+ */
+export interface NodeOrPortMapping<E, N, EVT> extends VertexMapping<N, EVT> {
+    /**
+     * Whether or not to allow edges from this vertex back to itself. Defaults to true. This flag will not prevent an edge from a port back to the node/group to which it belongs - for that, see `allowVertexLoopback`.
+     */
+    allowLoopback?: boolean;
+    /**
+     * ID of the template to use for a vertex of this type. This is only for 'vanilla' VisuallyJs: if you are using an integration such as React/Angular/Vue, you will not need to provide this. This parameter is distinct from `template` in that when you provide `templateId` you are expecting VisuallyJs to resolve the template for you, either from a `templates` block in a `render` call, or by looking for a script element in the DOM with the appropriate ID. If you provide this and also `template`, `template` will take precedence.
+     */
+    templateId?: string;
+    /**
+     * Template to use for a vertex of this type. This is only for 'vanilla' VisuallyJs: if you are using an integration such as React/Angular/Vue/Svelte, you will not need to provide this. If you provide this and also `templateId`, this will take precedence.
+     */
+    template?: string;
+    /**
+     * Whether or not to allow edges from a port back to the vertex it belongs to. Defaults to true.
+     */
+    allowVertexLoopback?: boolean;
+    /**
+     * A map of parameters that the template engine will merge with the backing data when rendering the vertex.
+     */
+    parameters?: Record<string, any>;
+}

package/types/ui/core/view/port-options.d.ts

@@ -0,0 +1,51 @@
+import { NodeOrPortMapping } from "./node-or-port-options";
+import { PortEventOptions } from "./events";
+import { AnchorSpec } from "../../common";
+import { Port } from "../../../core";
+/**
+ * Definition of a port inside a view.
+ * @group Components
+ * @category View
+ */
+export interface PortMapping<E> extends NodeOrPortMapping<E, Port, PortEventOptions<E>> {
+    /**
+     * Type of edges generated by this port.
+     */
+    edgeType?: string;
+    /**
+     * Whether or not the port can act as a source for dragged connections. Defaults to false.
+     */
+    isSource?: boolean;
+    /**
+     * Whether or not the port can act as a target for dragged connections. Defaults to false.
+     */
+    isTarget?: boolean;
+    /**
+     * Spec for anchors connected to this port
+     */
+    anchor?: AnchorSpec;
+    /**
+     * The x location of any anchors created for this port. Allows you to specify where, in proportional values, the anchor should be located in the x axis. For a full discussion of how to use this (and the other anchor properties in this interface), see the documentation for anchors.
+     */
+    anchorX?: number;
+    /**
+     * The y location of any anchors created for this port. Allows you to specify where, in proportional values, the anchor should be located in the y axis.
+     */
+    anchorY?: number;
+    /**
+     * The orientation in the x axis for connections attached to an anchor created for this port.
+     */
+    anchorOrientationX?: number;
+    /**
+     * The orientation in the y axis for connections attached to an anchor created for this port.
+     */
+    anchorOrientationY?: number;
+    /**
+     * Offset, in pixels, to apply to the position in the x axis after the `anchorX` value has been used to compute its default position.
+     */
+    anchorOffsetX?: number;
+    /**
+     * Offset, in pixels, to apply to the position in the y axis after the `anchorY` value has been used to compute its default position.
+     */
+    anchorOffsetY?: number;
+}

package/types/ui/core/view/vertex-options.d.ts

@@ -0,0 +1,28 @@
+import { BaseViewObjectMapping } from "./common-options";
+import { VertexDefinition, ObjectAnchorSpec } from "../../../core";
+import { AnchorPositionFinder } from "../ui-model";
+/**
+ * Base mapping for nodes, groups and ports.
+ */
+export interface VertexMapping<O, EVT> extends BaseViewObjectMapping, VertexDefinition {
+    /**
+     * Optional map of event bindings.
+     */
+    events?: EVT;
+    /**
+     * Optional array of anchor positions to use.
+     */
+    anchorPositions?: Array<ObjectAnchorSpec>;
+    /**
+     * Optional function to call on connection drop, to determine the location for the target anchor for the new connection. Returning null from this indicates no preference, and VisuallyJs will use its own computed value.
+     */
+    anchorPositionFinder?: AnchorPositionFinder<any>;
+    /**
+     * Maximum number of connections this vertex supports. Default is 1. A value of -1 means no limit.
+     */
+    maxConnections?: number;
+    /**
+     * Type to assign to edges connected to this vertex as a source.
+     */
+    edgeType?: string;
+}