@visuallyjs/browser-ui 1.0.0

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

@@ -0,0 +1,528 @@
+import { LabelPosition, ShapeSet } from "../../shape-library";
+import { Group, ObjectData, PointXY, Size, Vertex, Node, BeforeConnectInterceptor } from "../../../core";
+import { DiagramCell } from "./diagram-cell";
+import { GridOptions, UIExportOptions, UICoreDefaults, EdgeEventOptions, OverlaySpec, ConnectorSpec, NodeEventOptions, GroupMapping, NodeMapping, AnchorSpec, EdgePropertyMappings, MagnetizeOptions, PaintStyle, OverlayVisibility, EdgeDeleteConfirmationFunction } from "../../../ui";
+import { SurfaceSaveData } from "../definitions";
+import { BrowserElement } from "../../util";
+import { PaletteMode } from "../../components/palette/palette-options";
+import { PanOptions, WheelOptions, ZoomOptions } from "../../pan-zoom-options";
+import { MiniviewPluginOptions, LassoPluginOptions, ResizingToolsModelUpdater, ResizingToolsHandlerFactory, DragGroupsPluginOptions, ResizingToolsResizeMethod, SnaplinesPluginOptions, PanButtonsPluginOptions } from "../plugins";
+import { EdgeSnapOptions } from "../../edge-handler-base";
+import { DiagramActionMediator } from "./mediator";
+import { OnVertexAddedCallback, FontSpec } from "../../definitions";
+import { EdgeInputMethod } from "../../edge-input-handler";
+import { PreparedShape } from "../shape-palette-options";
+/**
+ * Options for the {@link Diagram.addLink method}
+ * @group Diagrams
+ * @category Options
+ */
+export interface AddLinkOptions {
+    /**
+     * Source cell, cell id or canvas location.
+     */
+    source: PointXY | string | DiagramCell;
+    /**
+     * Source cell, cell id or canvas location.
+     */
+    target: PointXY | string | DiagramCell;
+    /**
+     * Optional backing data for the link. You can control the link appearance with values in this object, and also store any arbitrary data you wish to.
+     */
+    data?: ObjectData;
+}
+/**
+ * Options for a Diagram grid
+ * @group Diagrams
+ * @category Options
+ */
+export interface DiagramGridOptions extends GridOptions {
+    /**
+     * Whether or not to show the grid. Defaults to true.
+     */
+    visible?: boolean;
+}
+/**
+ * Defines a function that can generate the backing data for a new edge.
+ */
+export type EdgeDataGenerator = (v: Vertex, type: string) => ObjectData;
+/**
+ * Options for a diagram.
+ * @group Diagrams
+ * @category Options
+ */
+export interface DiagramOptions {
+    /**
+     * Defaults to true - whether or not to allow multiple objects to be selected at the same time via shift+click.
+     */
+    allowMultipleSelections?: boolean;
+    /**
+     * Defaults to true, meaning the canvas will pan automatically to track elements that have been dragged out of the visible area.
+     */
+    autoPan?: boolean;
+    /**
+     * Defaults to true, meaning the user can edit the diagram.
+     */
+    editable?: boolean;
+    edges?: {
+        /**
+         * Default anchor to use for both source and target of edges.
+         */
+        anchor?: AnchorSpec;
+        /**
+         * Anchors to use as source, target of edges. This will take precedence over `anchor`.
+         */
+        anchors?: [AnchorSpec, AnchorSpec];
+        /**
+         * Defaults to true - edges are editable when the user taps on them.
+         */
+        editable?: boolean;
+        /**
+         * Input method for edges. Defaults to drag.
+         */
+        inputMethod?: EdgeInputMethod;
+        /**
+         * Defaults to false. If true, edges will attempt to avoid vertices wherever possible.
+         */
+        avoidVertices?: boolean;
+        /**
+         * Mappings from property values to overlays, edge style etc.
+         */
+        propertyMappings?: EdgePropertyMappings;
+        /**
+         * Defaults to true - edges which are unattached at either or both of the source/target are allowed.
+         */
+        allowUnattached?: 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;
+        /**
+         * Optional overlay to place at the source of every edge. 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 every edge. 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;
+        /**
+         * Optional list of overlays to draw on every edge.
+         */
+        overlays?: Array<OverlaySpec>;
+        /**
+         * Optional connector spec to use as default for edges. Internally this is mapped to `defaults.connector`; we've exposed it here for convenience.
+         */
+        connector?: ConnectorSpec;
+        /**
+         * Whether or not to display labels on edges. Defaults to false. The value for an edge's label is sourced from the `label` field of the edge's data. You can change this via the `labelProperty` setting. The label is placed at location 0.5 by default. You can change that with either the `labelLocation` setting (to change every label), or the `labelLocationProperty` (to set location on a per-edge basis).
+         */
+        showLabels?: boolean;
+        /**
+         * Whether or not to reattach this connection automatically should it be detached via user intervention and then dropped onto whitespace.
+         */
+        reattach?: boolean;
+        /**
+         * Whether or not edges should be detachable via pointer/touch events by default. The default value for this is true.
+         */
+        detachable?: boolean;
+        /**
+         * The name of the property in an edge's data that provides the label for the edge. Defaults to `"label"`.
+         */
+        labelProperty?: string;
+        /**
+         * The location to place edge labels at. Defaults to 0.5; it is defined as a proportion of the length of the edge's path. This applies to all edges. You can set location on a per-edge basis via the `labelLocationProperty` setting.
+         */
+        labelLocation?: number;
+        /**
+         * The name of the property that indicates where some edge's label should be placed. Defaults to `"labelLocation"`. You can use this to set label location on a per-edge basis. If your edge does not have a property with this key then the `labelLocation` setting will be used.
+         */
+        labelLocationProperty?: string;
+        /**
+         * Optional font for edge labels.
+         */
+        labelFont?: FontSpec;
+        /**
+         * Optional map of event handlers for edges.
+         */
+        events?: EdgeEventOptions;
+        /**
+         * Options for edge snapping.
+         */
+        snap?: EdgeSnapOptions;
+        /**
+         * By default, edges are drawn in a layer that appears in the DOM after the vertex layer, meaning edges will show above vertices. If you set this to 0, you can force the edge layer to the back.
+         */
+        layerIndex?: number;
+        /**
+         * Defaults to true - when an edge is selected, it's bounding box will be highlighted.
+         */
+        highlightSelected?: boolean;
+        /**
+         * Styles for the edge highlight box.
+         */
+        highlightStyle?: PaintStyle;
+    };
+    /**
+     * Defaults to #FFFFFF
+     */
+    defaultFillColor?: string;
+    /**
+     * Defaults to #000000
+     */
+    defaultOutlineColor?: string;
+    /**
+     * Defaults to 2px
+     */
+    defaultOutlineWidth?: number;
+    /**
+     * Defaults to #000000
+     */
+    defaultColor?: string;
+    /**
+     * This method is invoked when a user begins to drag a new edge. It is given the vertex the drag is starting from, and any derived type for the edge being dragged. This method can be used for two purposes: firstly, if you return false, the drag will be aborted. Secondly, if you return a data object from this method, that object will be used as the edge's backing data. So a common usage is to use this method to set properties that will define an edge's initial appearance.
+     */
+    beforeStartConnect?: EdgeDataGenerator;
+    /**
+     * Definition of a function to use as a beforeConnect interceptor.
+     * @param source - The source vertex for the new edge
+     * @param target - The target vertex for the new edge
+     * @param userInstigated - If true, the new edge came from user activity, with a pointer device or touch input. This will be false whenever the edge is added programmatically, either during a data load or via the `addEdge` method of VisuallyJsModel.
+     */
+    beforeConnect?: BeforeConnectInterceptor;
+    /**
+     * Options for cells.
+     */
+    cells?: {
+        /**
+         * True by default. Set this to false to stop all forms of edit for cells - delete, rotate, resize, clone
+         */
+        editable?: boolean;
+        /**
+         * True by default - cells may be dragged.
+         */
+        draggable?: boolean;
+        /**
+         * True by default - cells may be deleted when selected.
+         */
+        deletable?: boolean;
+        /**
+         * True by default - cells may be cloned when selected.
+         */
+        clonable?: boolean;
+        /**
+         * True by default - cells may be linked to other cells via edge drag
+         */
+        linkable?: boolean;
+        /**
+         * The default width of a cell in this diagram. Defaults to 100 pixels.
+         */
+        defaultWidth?: number;
+        /**
+         * The default height of a cell in this diagram. Defaults to 80 pixels.
+         */
+        defaultHeight?: number;
+        /**
+         * Whether or not to show labels. Defaults to true.
+         */
+        showLabels?: boolean;
+        /**
+         * Stroke width to use for outline of svg shapes.
+         */
+        outlineWidth?: number;
+        /**
+         * Options for the magnetize functionality of the UI.
+         */
+        magnetizer?: MagnetizeOptions;
+        /**
+         * The property containing each cell's label. Defaults to 'label'
+         */
+        labelProperty?: string;
+        /**
+         * The property containing each cell's width. Defaults to 'width'
+         */
+        widthProperty?: string;
+        /**
+         * The property containing each cell's height. Defaults to 'height'
+         */
+        heightProperty?: string;
+        /**
+         * The property containing each cell's left position. Defaults to 'x'.
+         */
+        leftProperty?: string;
+        /**
+         * The property containing each cell's top position. Defaults to 'y'.
+         */
+        topProperty?: string;
+        /**
+         * The property containing each cell's rotation. Defaults to `rotation`
+         */
+        rotationProperty?: string;
+        /**
+         * Whether or not the user should be able to rotate cells in the diagram. Defaults to true. Ignored if editable is false.
+         */
+        rotatable?: boolean;
+        /**
+         * Optional number of stops to use when rotating cells. If not provided vertices can be rotated to any angle. If provided, the value is divided into 360 and the result is the angle between each stop. For example, a value of 12 means each stop is 30 degrees.
+         */
+        rotationStops?: number;
+        /**
+         * Whether or not the user should be able to resize cells in the diagram using mouse/pointer. Defaults to true. Ignored if editable is false.
+         */
+        resizable?: boolean;
+        /**
+         * Defaults to true - labels are split across multiple lines to fit inside their shape. Set this to false if you want labels to always be a single line.
+         */
+        multilineLabels?: boolean;
+        /**
+         * How much of the width of a shape a multiline label will take up before wrapping. Defaults to 0.8. You can set this to a number greater than 1, if you like, but that will allow the label to overflow.
+         */
+        labelFillRatio?: number;
+        /**
+         * Default position for labels (will be overridden by a shape that defines its own position. Defaults to "center"
+         */
+        labelPosition?: LabelPosition;
+        /**
+         * Optional event mappings for all cells.
+         */
+        events?: NodeEventOptions<any>;
+        /**
+         * Optional behaviour mapping for groups in the diagram. For many setups, you won't need to use this, as the other options in the `cells` config are quite extensive and can be used to configure many things. For some setups you may need to provide config for group behaviour, such as whether or not vertices can be dragged in/out, whether the group should be resizable, etc. You can also provide group-specific event mappings here. Any `events` you provide here will be merged with the internal event registrations made by the diagram, but if you provide a `template` it will be ignored.
+         */
+        groups?: DiagramGroupMapping;
+        /**
+         * Optional function that can return the desired size for some group that is about to be collapsed. In certain diagrams it is useful to be able to decide what this should be at runtime.
+         * @param g
+         */
+        getCollapsedGroupSize?: (g: Group, currentSize: Size) => Size;
+        /**
+         * Optional mapping for nodes in the diagram. For many setups, you won't need to use this, as the other options in the `cells` config are quite extensive and can be used to configure many things. Any `events` you provide here will be merged with the internal event registrations made by the diagram, but if you provide a `template` it will be ignored.
+         */
+        nodes?: DiagramNodeMapping;
+        resize?: {
+            /**
+             * Width/height to use for resize handles. Defaults to 20 pixels.
+             */
+            handleSize?: number;
+            /**
+             * Shape of resize handles. Defaults to circle.
+             */
+            handleShape?: "rectangle" | "circle";
+            /**
+             * Method to use for resize - handles on the corners, or borders. Defaults to handles.
+             */
+            method?: ResizingToolsResizeMethod;
+            /**
+             * When method is "borders", set this to make the borders visible. Internally this just sets a CSS class on the draw skeleton's parent DOM element, and the appearance of the borders is then controlled via CSS.
+             */
+            bordersVisible?: boolean;
+            /**
+             * Optional function that can attach extra model updates when a resize occurs
+             */
+            modelUpdater?: ResizingToolsModelUpdater;
+            /**
+             * Optional factory that can return a resize handler for some given vertex. You can use this to override the default behaviour for any vertex you choose
+             */
+            handlerFactory?: ResizingToolsHandlerFactory;
+            /**
+             * Defaults to false, meaning size changes conform to an underlying grid, if present
+             */
+            ignoreGrid?: boolean;
+            /**
+             * Whether or not to support resize in the X axis. Defaults to true.
+             */
+            resizeX?: boolean;
+            /**
+             * Whether or not to support resize in the Y axis. Defaults to true.
+             */
+            resizeY?: boolean;
+        };
+        /**
+         * A function that you can provide to instruct the diagram whether or not, when removing a group via the diagram tools, 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;
+        /**
+         * Optional spec for font size/style to apply to all shapes. Shapes that have their own font spec will override this.
+         */
+        font?: FontSpec;
+    };
+    /**
+     * Which shape sets to make available to this diagram.
+     */
+    shapes?: ShapeSet | Array<ShapeSet>;
+    /**
+     * Options for the behaviour of the mousewheel (which also covers two finger scrolling on a mac trackpad)
+     */
+    wheel?: WheelOptions;
+    /**
+     * Options to control how a user manages zoom on the canvas.
+     */
+    zoom?: ZoomOptions;
+    /**
+     * Options to control how a user pans the canvas.
+     */
+    pan?: PanOptions;
+    /**
+     * If true, zoom the display so that the dataset is entirely visible after initialisation.
+     */
+    zoomToFit?: boolean;
+    /**
+     * If true, zoom the display so that the dataset is entirely visible after initialisation, but only adjust the zoom level if the dataset is not already visible at the default zoom level.
+     */
+    zoomToFitIfNecessary?: boolean;
+    /**
+     * Options for a grid for the diagram.
+     */
+    grid?: DiagramGridOptions;
+    /**
+     * Defaults for connector/anchors etc
+     */
+    defaults?: UICoreDefaults<BrowserElement>;
+    /**
+     * Options for lasso, or just a boolean instructing the diagram to attach a lasso with default options, if true. If no value is set for this, the diagram will not have a lasso attached.
+     */
+    lasso?: boolean | LassoPluginOptions;
+    /**
+     * Defaults to true - select a shape/edge if the user taps on it. This is valid also when the diagram is read only.
+     */
+    selectShapeOnTap?: boolean;
+    /**
+     * Defaults to true - deselect any currently selected shapes when the user taps on canvas whitespace.
+     */
+    deselectOnCanvasTap?: boolean;
+    /**
+     * Options for a miniview
+     */
+    miniview?: MiniviewPluginOptions;
+    /**
+     * Defines an object that can decide at runtime whether a given shape should offer various actions in its shape editing tools. Defaults to null.
+     */
+    mediator?: DiagramActionMediator;
+    /**
+     * Options for drag groups.
+     */
+    dragGroups?: DragGroupsPluginOptions;
+    /**
+     * Controls whether snaplines are displayed, defaults to false. You can either supply a boolean and have the snaplines plugin initialize with its default settings, or supply your own settings.
+     */
+    snapLines?: boolean | SnaplinesPluginOptions;
+    /**
+     * Controls whether pan buttons are displayed at the edges of the canvas, defaults to false. You can either supply a boolean and have the panbuttons plugin initialize with its default settings, or supply your own settings.
+     */
+    panButtons?: boolean | PanButtonsPluginOptions;
+}
+/**
+ * Options for a palette for a diagram.
+ * @group Diagrams
+ * @category Options
+ */
+export interface DiagramPaletteOptions {
+    /**
+     * Optional fill color to use for dragged elements. This should be in RGB format, _not_ a color like 'white' or 'cyan' etc.
+     */
+    fill?: string;
+    /**
+     * Optional color to use for outline of dragged elements. Should be in RGB format.
+     */
+    outline?: string;
+    /**
+     * Optional size to use for dragged elements.
+     */
+    dragSize?: Size;
+    /**
+     * Indicates that when one or more vertices are selected, clicking on an entry in the palette will change the type of the selected vertices to that type. Defaults to true.
+     */
+    inspector?: boolean;
+    /**
+     * Optional size to use for icons. Defaults to 150x100 pixels. If you provide this but not `dragSize` this size will also be used for an icon that is being dragged.
+     */
+    iconSize?: Size;
+    /**
+     * Optionally show each shape icon's label underneath it
+     */
+    showLabels?: boolean;
+    /**
+     * Stroke width to use for shapes in palette. Defaults to 1.
+     */
+    paletteStrokeWidth?: number;
+    /**
+     * Message to use for the 'show all' option in the shape set drop down when there is more than one set of shapes. Defaults to `Show all`.
+     */
+    showAllMessage?: string;
+    /**
+     * Callback to invoke when a new diagram cell has been added.
+     * @param dc
+     */
+    onCellAdded?: (dc: DiagramCell) => any;
+    /**
+     * Mode to operate in - 'drag' or 'tap'. Defaults to 'drag' (PALETTE_MODE_DRAG).
+     */
+    mode?: PaletteMode;
+    /**
+     * When in tap mode, allow addition of new vertices simply by clicking, instead of requiring a shape be drawn. (When this is true, the drawing method also still works)
+     */
+    allowClickToAdd?: boolean;
+    /**
+     * Defaults to true: when in 'tap' mode and a new group/node has been drawn on the canvas, the UI is set back to pan mode.
+     */
+    autoExitDrawMode?: boolean;
+    /**
+     * When true (which is the default), a newly dropped shape will be set as the underlying model's selection.
+     */
+    selectAfterAdd?: boolean;
+    /**
+     * Optional function that is invoked at the start of a drag, and which identifies allowed drop targets. Each target - the canvas, nodes and groups - is passed in turn to this method; returning false indicates that the given target is not valid for that drag.
+     * @param candidate
+     * @param target
+     * @param onCanvas
+     */
+    canDrop?: (candidate: Node | Group, target?: Node | Group, onCanvas?: boolean) => boolean;
+    /**
+     * Optional callback that will be invoked after a new vertex has been dropped and added to the dataset.
+     * @param v
+     */
+    onVertexAdded?: OnVertexAddedCallback;
+    /**
+     * Optional set of prepared shapes to show in the palette. When this is provided, the palette will only render these shapes, and not the contents of the shape library.
+     */
+    preparedShapes?: Array<PreparedShape>;
+}
+/**
+ * Save options for a Diagram
+ * @group Diagrams
+ * @category Options
+ */
+export interface DiagramSaveOptions extends UIExportOptions {
+}
+/**
+ * Defines the format of the data returned from a Diagram save
+ * @group Diagrams
+ * @category IO
+ */
+export interface DiagramSaveData extends SurfaceSaveData {
+}
+/**
+ * A group mapping in a Diagram. Intended for advanced use cases where you need fine-grained controls over groups, and the config options available in `cells` are not granular enough.
+ */
+export interface DiagramGroupMapping extends Omit<GroupMapping<BrowserElement>, "template" | "ignore" | "templateId"> {
+}
+/**
+ * A node mapping in a Diagram. Intended for advanced use cases where you need fine-grained controls over nodes, and the config options available in `cells` are not granular enough.
+ */
+export interface DiagramNodeMapping extends Omit<NodeMapping<BrowserElement>, "template" | "ignore" | "templateId"> {
+}

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

@@ -0,0 +1,123 @@
+import { Size, PointXY, Vertex, ObjectData } from "../../../core";
+import { Diagram } from "./diagram";
+import { BrowserElement } from "../../util";
+/**
+ * A cell in a diagram, offering methods to set/get its position and size, and to update its backing data.
+ * @group Diagrams
+ */
+export declare class DiagramCell {
+    private diagram;
+    vertex: Vertex;
+    /**
+     * The DOM element pertaining to the cell. Will be null until rendering
+     * has completed.
+     */
+    el: BrowserElement;
+    /**
+     * This is set when the cell has been destroyed, ie. the underlying
+     * cell was removed from the data model.
+     * @internal
+     */
+    $destroyed: boolean;
+    constructor(diagram: Diagram, vertex: Vertex);
+    /**
+     * Gets the cell's ID.
+     */
+    get id(): string;
+    /**
+     * Gets the cell's current z index.
+     */
+    get zIndex(): any;
+    /**
+     * Update the cell's backing data. If you want to change the position or size of the cell, use `setSize` or `setPosition` in preference to this.
+     * @param updates
+     */
+    update(updates: ObjectData): void;
+    /**
+     * Sets the size of the cell
+     * @param s The new size to set.
+     */
+    setSize(s: Size): void;
+    /**
+     * Sets the position of the cell
+     * @param p The new position to set.
+     */
+    setPosition(p: PointXY): void;
+    /**
+     * Sets the cell's label.
+     * @param label
+     */
+    setLabel(label: string): void;
+    /**
+     * Sets the cell's fill color.
+     * @param fill Color to set. Use a value in hex or rgb format, not a color name, if you want to export SVG or an image.
+     */
+    setFill(fill: string): void;
+    /**
+     * Sets the cell's outline color.
+     * @param outline Color to set. Use a value in hex or rgb format, not a color name, if you want to export SVG or an image.
+     */
+    setOutline(outline: string): void;
+    /**
+     * Sets the cell's outline stroke width.
+     * @param outlineWidth
+     */
+    setOutlineWidth(outlineWidth: number): void;
+    /**
+     * Sets the cell's label color
+     * @param color
+     */
+    setColor(color: string): void;
+    /**
+     * Gets the cell's label. May be null
+     */
+    get label(): string;
+    /**
+     * Gets the cell's fill color.
+     */
+    get fill(): string;
+    /**
+     * Gets the cell's outline color.
+     */
+    get outline(): string;
+    /**
+     * Gets the cell's outline width.
+     */
+    get outlineWidth(): number;
+    /**
+     * Gets the cell's text color
+     */
+    get color(): number;
+    /**
+     * Get the size of the cell.
+     */
+    get size(): Size;
+    /**
+     * Get the width of the cell.
+     */
+    get width(): number;
+    /**
+     * Get the height of the cell.
+     */
+    get height(): number;
+    /**
+     * Gets the cell's position relative to the canvas origin.
+     */
+    get position(): PointXY;
+    /**
+     * Removes the cell, and the model object it represents.
+     */
+    remove(): void;
+    /**
+     * @internal
+     */
+    destroy(): void;
+    /**
+     * Bring this cell to the front.
+     */
+    toFront(): void;
+    /**
+     * Send this cell to the back.
+     */
+    toBack(): void;
+}