@visuallyjs/browser-ui 1.0.0

package/types/browser-ui/surface-renderer/diagrams/diagram-link.d.ts

@@ -0,0 +1,116 @@
+import { Edge, ObjectData, PointXY } from "../../../core";
+import { Diagram } from "./diagram";
+import { DiagramCell } from "./diagram-cell";
+/**
+ * A link in a diagram.
+ */
+export declare class DiagramLink {
+    private diagram;
+    edge: Edge;
+    /**
+     * This is set when the link has been destroyed, ie. the underlying
+     * edge cell was removed from the data model.
+     */
+    $destroyed: boolean;
+    get id(): string;
+    constructor(diagram: Diagram, edge: Edge);
+    /**
+     * Update the link's backing data.
+     * @param updates
+     */
+    update(updates: ObjectData): void;
+    /**
+     * Removes the link from the diagram.
+     */
+    remove(): void;
+    /**
+     * Sets the link's label.
+     * @param label
+     */
+    setLabel(label: string): void;
+    /**
+     * Gets the link's label.
+     */
+    get label(): string;
+    /**
+     * Sets the link's stroke color.
+     * @param color
+     */
+    setColor(color: string): void;
+    /**
+     * Gets the link's stroke color.
+     */
+    get color(): string;
+    /**
+     * Sets the link's stroke width.
+     * @param lineWidth
+     */
+    setLineWidth(lineWidth: number): void;
+    /**
+     * Gets the link's stroke width.
+     */
+    get lineWidth(): number;
+    /**
+     * Sets the link's outline color.
+     * @param outlineColor
+     */
+    setOutlineColor(outlineColor: string): void;
+    /**
+     * Gets the link's outline color.
+     */
+    get outlineColor(): string;
+    /**
+     * Sets the link's outline width.
+     * @param outlineWidth
+     */
+    setOutlineWidth(outlineWidth: number): void;
+    /**
+     * Gets the link's outline width.
+     */
+    get outlineWidth(): number;
+    /**
+     * Sets the link's dash array.
+     * @param dashArray
+     */
+    setDashArray(dashArray: string): void;
+    /**
+     * Gets the link's dash array.
+     */
+    get dashArray(): string;
+    /**
+     * Sets the link's label location (0 to 1).
+     * @param labelLocation
+     */
+    setLabelLocation(labelLocation: number): void;
+    /**
+     * Gets the link's label location.
+     */
+    get labelLocation(): number;
+    /**
+     * Sets the link's source.
+     * @param source
+     */
+    setSource(source: string | DiagramCell | PointXY): void;
+    /**
+     * Gets the link's source.
+     */
+    get source(): any;
+    /**
+     * Sets the link's target.
+     * @param target
+     */
+    setTarget(target: string | DiagramCell | PointXY): void;
+    /**
+     * Gets the link's target.
+     */
+    get target(): any;
+    /**
+     * Bring this link to the front.
+     */
+    toFront(): void;
+    /**
+     * Send this link to the back.
+     */
+    toBack(): void;
+    destroy(): void;
+}

package/types/browser-ui/surface-renderer/diagrams/diagram-palette.d.ts

@@ -0,0 +1,11 @@
+import { ShapePalette } from "../shape-palette";
+import { BrowserElement } from "../../util";
+import { DiagramPaletteOptions } from "./definitions";
+import { Diagram } from "./diagram";
+/**
+ * A palette for a diagram - a thin wrapper around ShapePalette offering a couple of diagram specific methods.
+ * @group Diagrams
+ */
+export declare class DiagramPalette extends ShapePalette<BrowserElement> {
+    constructor(container: HTMLElement, diagram: Diagram, options?: DiagramPaletteOptions);
+}

package/types/browser-ui/surface-renderer/diagrams/diagram-tools.d.ts

@@ -0,0 +1,112 @@
+import { Group, Vertex } from "../../../core";
+import { ViewportElement } from "../../../ui";
+import { BrowserElement } from "../../util";
+import { ResizingToolsPlugin, ResizingToolsPluginOptions } from "../plugins";
+import { Surface } from "../surface";
+/**
+ * The default size for a button in the diagram tools.
+ */
+export declare const DEFAULT_DIAGRAM_TOOLS_BUTTON_SIZE = 15;
+/**
+ * Options for the diagram tools plugin
+ */
+export interface DiagramToolsPluginOptions extends ResizingToolsPluginOptions {
+    /**
+     * width/height of buttons. Defaults to 15 pixels.
+     */
+    buttonSize?: number;
+    /**
+     * Whether or not to allow clone of vertices. Defaults to true; is overriden by any `canClone` function passed in.
+     */
+    allowClone?: boolean;
+    /**
+     * Whether or not to allow delete of vertices. Defaults to true; is overriden by any `canDelete` function passed in.
+     */
+    allowDelete?: boolean;
+    /**
+     * Whether or not to show a handle from which a user can drag a link to other vertices. Defaults to true; is overriden by any `canShowLinkButton` function passed in.
+     */
+    allowLink?: boolean;
+    /**
+     * A function that you can provide to instruct the plugin whether or not to show a link handle. The return value of this function overrides the setting of `allowLink`.
+     * @param v
+     * @param el
+     */
+    canShowLinkButton?: (v: Vertex, el: BrowserElement) => boolean;
+    /**
+     * A function that you can provide to instruct the plugin whether or not to show a delete button. The return value of this function overrides the setting of `allowDelete`.
+     * @param v
+     * @param el
+     */
+    canDelete?: (v: Vertex, el: BrowserElement) => boolean;
+    /**
+     * A function that you can provide to instruct the plugin whether or not to show a clone button. The return value of this function overrides the setting of `allowClone`.
+     * @param v
+     * @param el
+     */
+    canClone?: (v: Vertex, el: BrowserElement) => boolean;
+    /**
+     * A function that you can provide to instruct the plugin whether or not, when removing a group, to also remove its child members. You need to return boolean true from this method in order for group members to be deleted.
+     * @param v
+     * @param el
+     */
+    shouldDeleteGroupMembers?: (g: Group, el: BrowserElement) => boolean;
+}
+/**
+ * CSS class set on all diagram tool buttons
+ * @group Diagrams
+ * @category CSS Classes
+ * @cssClass
+ * @context diagramTools
+ */
+export declare const CLASS_DIAGRAM_CELL_TOOL = "vjs-cell-tool";
+/**
+ * CSS class set on the clone tool button
+ * @group Diagrams
+ * @category CSS Classes
+ * @cssClass
+ * @context diagramTools
+ */
+export declare const CLASS_DIAGRAM_CLONE_CELL = "vjs-clone-cell";
+/**
+ * CSS class set on the delete cell button
+ * @group Diagrams
+ * @category CSS Classes
+ * @cssClass
+ * @context diagramTools
+ */
+export declare const CLASS_DIAGRAM_DELETE_CELL = "vjs-delete-cell";
+/**
+ * CSS class set on the link cell handle
+ * @group Diagrams
+ * @category CSS Classes
+ * @cssClass
+ * @context diagramTools
+ */
+export declare const CLASS_DIAGRAM_LINK_CELL = "vjs-link-cell";
+/**
+ * Vertex tools for a diagram - resizing, rotating, clone and delete.
+ * @group Diagrams
+ */
+export declare class DiagramToolsPlugin extends ResizingToolsPlugin {
+    static type: string;
+    id: string;
+    $buttonSize: number;
+    $allowClone: boolean;
+    $allowDelete: boolean;
+    $allowLink: boolean;
+    $canShowLinkButton: (v: Vertex, el: BrowserElement) => boolean;
+    $canDelete: (v: Vertex, el: BrowserElement) => boolean;
+    $canClone: (v: Vertex, el: BrowserElement) => boolean;
+    $shouldDeleteGroupMembers: (g: Group, el: BrowserElement) => boolean;
+    $buttonY: number;
+    initialise(surface: Surface, options: DiagramToolsPluginOptions): boolean;
+    protected _attachSvg(mel: ViewportElement<BrowserElement>, obj: any, resizeX: boolean, resizeY: boolean): BrowserElement;
+    private $getCloneButtonX;
+    private $getCloneButtonY;
+    private $getDeleteButtonX;
+    private $getDeleteButtonY;
+    private $getLinkButtonX;
+    private $getLinkButtonY;
+    protected $_setSkeletonPositionById(id: string): boolean;
+}

package/types/browser-ui/surface-renderer/diagrams/diagram.d.ts

@@ -0,0 +1,221 @@
+import { ObjectData, PriorityQueue, SaveOptions, ModelOptions, Edge } from "../../../core";
+import { PropertyTracker, ZoomToFitOptions, ZoomToFitIfNecessaryOptions } from "../../../ui";
+import { BrowserElement } from "../../util";
+import { BrowserUIModel } from "../../browser-ui";
+import { ShapeLibraryImpl } from "../../shape-library";
+import { AddLinkOptions, DiagramOptions, DiagramPaletteOptions, DiagramSaveData, DiagramSaveOptions } from "./definitions";
+import { DiagramCell } from "./diagram-cell";
+import { DiagramLink } from "./diagram-link";
+import { BrowserUI } from "../../browser-visuallyjs-instance";
+import { MiniviewPluginOptions } from "../plugins";
+import { DiagramPalette } from "./diagram-palette";
+import { DiagramActionMediator } from "./mediator";
+import { ImageExportOptions, ImageReadyFunction, SvgExportOptions } from "../../svg-export";
+/**
+ * A Diagram draws nodes, edges and group as SVG elements into an SVG container element, and provides a programmatic API for manipulating the various elements.
+ * @group Diagrams
+ */
+export declare class Diagram {
+    model: BrowserUIModel;
+    $shapeLibrary: ShapeLibraryImpl<BrowserElement>;
+    $ui: BrowserUI;
+    readonly defaultCellWidth: number;
+    readonly defaultCellHeight: number;
+    get cellWidthAttribute(): string;
+    get cellHeightAttribute(): string;
+    get cellLeftAttribute(): string;
+    get cellTopAttribute(): string;
+    labelAttribute: string;
+    $_cellMap: Map<string, DiagramCell>;
+    $editable: boolean;
+    $_cellList: PriorityQueue<DiagramCell>;
+    $propertyTracker: PropertyTracker;
+    _mediator: DiagramActionMediator;
+    constructor(model: BrowserUIModel, container: BrowserElement, options: DiagramOptions);
+    private _createView;
+    /**
+     * @internal
+     * @param v
+     */
+    private _addVertex;
+    /**
+     * @internal
+     * @param v
+     */
+    private _removeVertex;
+    private _canRotate;
+    private _canLink;
+    private _canClone;
+    private _canResize;
+    private _canDelete;
+    /**
+     * gets the shape type definition corresponding to the given vertex.
+     * @param v
+     * @internal
+     */
+    private _getShapeDefinition;
+    $destroy(): void;
+    private _resolveId;
+    private _resolveCell;
+    /**
+     * Gets the cell with the given ID. May return null if no matching cell found.
+     * @param id
+     * @public
+     */
+    getCell(id: string): DiagramCell;
+    /**
+     * Adds a cell to the diagram.
+     * @param o
+     */
+    addCell(o: ObjectData): DiagramCell;
+    /**
+     * Gets the link with the given id.
+     * @param id
+     */
+    getLink(id: string): DiagramLink;
+    /**
+     * Add a link to the diagram, which may be connected to a cell at one or both ends, or placed in whitespace.
+     * @param o
+     */
+    addLink(o: AddLinkOptions): DiagramLink;
+    /**
+     * Loads data either as an object or from a url into the diagram, first clearing it. Invokes the
+     * given onload function after load is complete.
+     * @param options
+     */
+    load(options: {
+        data?: any;
+        url?: string;
+        onload?: () => any;
+    }): void;
+    /**
+     * Exports the dataset - only the dataset. If you want the dataset plus the current state, use {@link save}
+     */
+    exportData(): any;
+    /**
+     * Exports an SVG representation of the diagram.
+     * @returns An SVG element representing the diagram.
+     */
+    /**
+     * Exports an SVG representation of the diagram
+     * @returns An string representing the diagram in SVG.
+     */
+    exportSvg(options?: SvgExportOptions): string;
+    /**
+     * Exports an image representation of the diagram.
+     * @returns An image representing the diagram.
+     */
+    exportImage(options: ImageExportOptions, onImageReady: ImageReadyFunction): void;
+    /**
+     * Exports the dataset and current state as JSON.
+     * @param options
+     */
+    save(options?: DiagramSaveOptions): DiagramSaveData;
+    /**
+     * Posts the Diagram data and state via ajax to a given URL.
+     * @param options Save options
+     */
+    saveToUrl(options: SaveOptions): void;
+    /**
+     * Gets the number of cells in the diagram
+     */
+    getCellCount(): number;
+    /**
+     * Gets the number of links in the diagram.
+     */
+    getLinkCount(): number;
+    /**
+     * Clears the diagram.
+     */
+    clear(): void;
+    /**
+     * Removes a cell from the diagram.
+     * @param cell Either the cell to remove, or the ID of the cell to remove.
+     */
+    removeCell(cell: string | DiagramCell): void;
+    /**
+     * Bring the given cell or link to the front.
+     * @param c Cell or link, or its id.
+     */
+    toFront(c: string | DiagramCell | DiagramLink): void;
+    /**
+     * Send the given cell or link to the back.
+     * @param c Cell or link, or its id.
+     */
+    toBack(c: string | DiagramCell | DiagramLink): void;
+    /**
+     * Sets the given cell as the selected cell in the model
+     * @param c Cell to select.
+     */
+    selectCell(c: string | DiagramCell): void;
+    /**
+     * Sets the given link as the selected link in the model
+     * @param l Link to select.
+     */
+    selectLink(l: string | DiagramLink | Edge): void;
+    /**
+     * Alias for selectLink
+     * @param l Link to select.
+     */
+    selectEdge(l: string | DiagramLink | Edge): void;
+    /**
+     * Start editing the given edge/link
+     */
+    startEditingPath(edgeOrLink: Edge | DiagramLink, params: any): void;
+    /**
+     * Stop editing a link path. If a path is not being edited this is ignored.
+     */
+    stopEditingPath(): void;
+    /**
+     * Clear the edits for the given edge/link.
+     */
+    clearPathEdits(edgeOrLink: Edge | DiagramLink): void;
+    /**
+     * Gets the current visible zoom.
+     */
+    getZoom(): number;
+    /**
+     * Attach a miniview to this diagram.
+     * @param options Options for the miniview.
+     */
+    attachMiniview(options: MiniviewPluginOptions): void;
+    /**
+     * Create a new DiagramPalette in the given container element, and attach it to this Diagram.
+     * @param container HTMLElement that will host the palette
+     * @param options Options for the palette.
+     */
+    attachPalette(container: HTMLElement, options?: DiagramPaletteOptions): DiagramPalette;
+    /**
+     * Sets the current zoom. If this value is outside the zoom range it will be ignored.
+     * @param z
+     * @public
+     */
+    setZoom(z: number): void;
+    /**
+     * Zooms the display so that all the tracked elements fit inside the viewport. This method will also, by default, increase the zoom if necessary - meaning the default behaviour is to adjust the zoom so that the content fills the viewport. You can suppress zoom increase by setting `doNotZoomIfVisible:true` on the parameters to this method.
+     * @tags zoom
+     */
+    zoomToFit(params?: ZoomToFitOptions): void;
+    /**
+     * Zooms the display so that all the tracked elements fit inside the viewport, but does not make any adjustments to zoom if all the elements are currently visible (it still does center the content though).
+     * @tags zoom
+     */
+    zoomToFitIfNecessary(params?: ZoomToFitIfNecessaryOptions): void;
+}
+/**
+ * Create a new DiagramPalette in the given container element, and attach it to the given Diagram.
+ * @param diagram
+ * @param container
+ * @param options
+ * @group Factory Methods
+ */
+export declare function attachDiagramPalette(diagram: Diagram, container: HTMLElement, options?: DiagramPaletteOptions): DiagramPalette;
+/**
+ * Create a new Diagram in the given container element.
+ * @param container
+ * @param options
+ * @param modelOptions
+ * @param data
+ * @group Factory Methods
+ */
+export declare function createDiagram(container: BrowserElement, options?: DiagramOptions, modelOptions?: ModelOptions, data?: any): Diagram;

package/types/browser-ui/surface-renderer/diagrams/index.d.ts

@@ -0,0 +1,25 @@
+import { SvgExportComponent, SvgExportComponentOptions } from "../../components";
+import { BrowserElement } from "../../util";
+import { Diagram } from "./diagram";
+export * from './constants';
+export * from './definitions';
+export * from './diagram';
+export * from './diagram-tools';
+export * from './diagram-palette';
+export * from './diagram-cell';
+export * from './diagram-link';
+export * from './util';
+export * from './mediator';
+/**
+ * Options for a diagram export component.
+ */
+export interface DiagramExportComponentOptions extends SvgExportComponentOptions {
+}
+/**
+ * Simple component offering buttons for export of SVG, PNG or JPG from a UI that has an SVG container
+ * @group Components
+ * @category Export Controls
+ */
+export declare class DiagramExportComponent extends SvgExportComponent {
+    constructor(container: BrowserElement, diagram: Diagram, options?: DiagramExportComponentOptions);
+}

package/types/browser-ui/surface-renderer/diagrams/mediator.d.ts

@@ -0,0 +1,59 @@
+import { Group, Vertex, Node, ObjectData, Size } from "../../../core";
+import { ShapeType } from "../../shape-library";
+import { BrowserElement } from "../../util";
+/**
+ * Defines an object that can decide at runtime whether a given shape should offer various actions in its shape editing tools. Each method in this interface is optional, and does not override any diagram-wide settings for the specific operation.  Also, the mediator will not be invoked if a diagram is not editable.
+ */
+export interface DiagramActionMediator {
+    /**
+     * Returns whether or not the given vertex should be clonable in the UI. Defaults to true, meaning the clone icon will be present in the diagram tools.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canClone?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be deletable in the UI. Defaults to true, meaning the delete icon will be present in the diagram tools when the vertex is selected.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canDelete?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be linkable via edge drag in the UI. Defaults to true, meaning the link icon will be present in the diagram tools when the vertex is selected.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canLink?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be resizable in the UI. Defaults to true, meaning the resize handles will be present in the diagram tools when the vertex is selected.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canResize?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be resizable in the UI. Defaults to true, meaning the rotate handle and leader will be present in the diagram tools when the vertex is selected.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canRotate?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be draggable in the UI. Defaults to true.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canDrag?: (v: Vertex, shape: ShapeType, el: BrowserElement) => boolean;
+    /**
+     * Returns whether or not the given vertex should be droppable on the given target, which may either be another vertex (if `targetVertex` is set), or the diagram canvas (if `isOnCanvas` is set). This method will never be called with both `targetVertex` set an `isOnCanvas` true - it's one or the other.
+     * @param v
+     * @param shape
+     * @param el
+     */
+    canDrop?: (vertex: Node | Group, targetVertex?: Node | Group, isOnCanvas?: boolean) => boolean;
+    canCollapse?: (group: Group, currentSize: Size) => boolean | ObjectData;
+    canExpand?: (group: Group, currentSize: Size) => boolean | ObjectData;
+}

package/types/browser-ui/surface-renderer/diagrams/util.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @internal
+ */
+export declare function gridBackgroundOptions(): {
+    dragOnGrid: boolean;
+    showGrid: boolean;
+    showBorder: boolean;
+    autoShrink: boolean;
+    minWidth: number;
+    maxWidth: number;
+    minHeight: number;
+    maxHeight: number;
+    showTickMarks: boolean;
+    type: string;
+};

package/types/browser-ui/surface-renderer/elastic-group-manager.d.ts

@@ -0,0 +1,102 @@
+import { Group, Node, AbstractLayout, PointXY, RectangleXY, Size, Extents } from "../../core";
+import { ViewportElement, ViewportGroupElement, UICore, GroupResizeResult, GroupMapping } from "../../ui";
+import { BrowserElement } from "../util";
+/**
+ * Class set on the SVG element we use to track an elastic group resize.
+ * @group Nodes and Groups
+ * @category CSS Classes
+ * @cssClass
+ * @context groups
+ */
+export declare const CLASS_ELASTIC_GROUP_RESIZE = "vjs-surface-elastic-group-resize";
+/**
+ * Event fired when the elastic group resizes. For internal use.
+ * @internal
+ */
+export declare const EVENT_ELASTIC_GROUP_FRAME_RESIZE = "elasticGroupFrame:resize";
+/**
+ * Event fired when the elastic group frame is removed. For internal use.
+ * @internal
+ */
+export declare const EVENT_ELASTIC_GROUP_FRAME_REMOVE = "elasticGroupFrame:remove";
+/**
+ * @internal
+ */
+export declare class ElasticGroupManager {
+    private surface;
+    focusVertex: Node | Group;
+    group: Group;
+    private groupDef;
+    groupEntry: RectangleXY;
+    focusPosition: RectangleXY;
+    siblingEntries: Array<ViewportElement<BrowserElement>>;
+    xMinEntries: Array<RectangleXY>;
+    xMaxEntries: Array<RectangleXY>;
+    yMinEntries: Array<RectangleXY>;
+    yMaxEntries: Array<RectangleXY>;
+    managedElement: ViewportGroupElement<BrowserElement>;
+    uiGroup: ViewportGroupElement<BrowserElement>;
+    frame: SVGElement;
+    layout: AbstractLayout<any>;
+    uiGroupContentArea: BrowserElement;
+    _initialExtents: Extents;
+    layoutShiftX: number;
+    layoutShiftY: number;
+    width: number;
+    height: number;
+    minSize: Size;
+    x: number;
+    y: number;
+    parent: ElasticGroupManager;
+    constructor(surface: UICore<BrowserElement>, focusVertex: Node | Group, group: Group, groupDef: GroupMapping<BrowserElement>);
+    /**
+     * Sort the child entries in each of the four directions. The head of each array is then the furthest point in the
+     * given direction.
+     * @internal
+     * @private
+     */
+    _sortEntries(): void;
+    /**
+     * Sets the position of the current focus, and optionally changes its size, and then recomputes.
+     * NOTE: this method expects `pos` to be relative to the focus element's offset parent (whose x/y location
+     * is stored in the `groupEntry` member of this class), unless you set `adjustForParent:true`, which is what this
+     * class does when it calls a parent instance
+     * @internal
+     * @param p
+     * @param wh
+     */
+    setFocusPosition(p: PointXY, allowOriginShrink: boolean, event?: MouseEvent, wh?: Size, adjustForParent?: boolean): void;
+    private _$_recompute;
+    getCurrentExtents(): Extents;
+    /**
+     * @internal
+     */
+    cleanup(): void;
+    /**
+     * Get computed values for some group. If the given group is not managed by this manager and there is a parent manager, delegate to the parent. Otherwise return null.
+     * @param groupId
+     * @internal
+     */
+    getValues(groupId: string): {
+        layoutShiftX: number;
+        layoutShiftY: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Persists the current state of the elastic group to the UI ONLY, NOT to the model. This means it resizes the group content area and repositions the group, if necessary, plus relocates any child elements that have been moved as a result of the group's origin moving.  But nothing is written to the model.  All of the changes are returned by this method though, and the call site is expected to handle them (for now; this might change in the future. But we need to ensure that any updates this makes to the model are in a transaction, probably one that already is in progress)
+     * @param movedElements
+     * @param resizedGroups
+     * @internal
+     */
+    _persistToUI(movedElements?: Record<string, {
+        original: PointXY;
+        current: PointXY;
+    }>, resizedGroups?: Record<string, GroupResizeResult<any>>): {
+        movedElements: Record<string, {
+            original: PointXY;
+            current: PointXY;
+        }>;
+        resizedGroups: Record<string, GroupResizeResult<any>>;
+    };
+}