@visuallyjs/browser-ui 1.0.0

package/types/ui/core/magnetize-profile.d.ts

@@ -0,0 +1,82 @@
+import { GridProfile } from "./grid-profile";
+import { Grid, PointXY } from "../../core/util";
+/**
+ * Options for the magnetize functionality of the UI.
+ * @group Components
+ * @category Magnetizer
+ */
+export interface MagnetizeOptions {
+    /**
+     * If true, magnetizer will be run after the layout is run.
+     */
+    afterLayout?: boolean;
+    /**
+     * If true, magnetizer will be run after a vertex is dragged. Defaults to false.
+     */
+    afterDrag?: boolean;
+    /**
+     * If true, magnetizer will be run constantly as a vertex is being dragged, pushing other vertices out of the way of the vertex that is being dragged. Defaults to false. By default, `constant` magnetize will also set `trackback:true`, but you can disable that behaviour by setting `trackback:false`.
+     */
+    constant?: boolean;
+    /**
+     * Used in conjunction with `constant`: attempts to track any moved elements to their original positions (or as close as possible) once the path is clear, each time the magnetizer runs a sweep. Defaults to true (when `constant` is true).
+     */
+    trackback?: boolean;
+    /**
+     * When in `constant` mode and `trackback` is set, this value specifies a threshold for elements that have been pushed from their original position. Beyond this threshold, the magnetizer will no longer attempt to track an element back. This can be useful in certain situations where the user does want to move an element by pushing it via the magnetizer
+     */
+    trackbackThreshold?: number;
+    /**
+     * If true, vertices moved by the magnetizer will be constrained to move within the visible viewport, which is a function of the current zoom/pan of the UI. Otherwise, vertices will be able to be pushed out of the visible viewport.
+     */
+    constrainToViewport?: boolean;
+    /**
+     * If true, and `afterDrag` is true, when the magnetizer is run after a drag it will be the recently dragged element that moves in precedence to the other elements. By default, the recently dragged element is _not_ moved by the magnetize operation - it stays where you dragged it.
+     */
+    repositionDraggedElement?: boolean;
+    /**
+     * Defaults to false. Indicates the surface should magnetize/gather nodes around a newly resized group, regardless of whether the group size grew or if it shrunk. This flag is the same as setting `afterGroupShrink` and `afterGroupGrow`
+     */
+    afterGroupResize?: boolean;
+    /**
+     * Defaults to false. Indicates the UI should magnetize/gather nodes around a newly resized group if the group size was reduced.
+     */
+    afterGroupShrink?: boolean;
+    /**
+     * Defaults to false. Indicates the UI should magnetize/gather nodes around a newly resized group if the group size was enlarged.
+     */
+    afterGroupGrow?: boolean;
+    /**
+     * Defaults to false. Indicates the UI should gather nodes around a newly collapsed group
+     */
+    afterGroupCollapse?: boolean;
+    /**
+     * Defaults to false. Indicates the UI should magnetize nodes around a newly expanded group
+     */
+    afterGroupExpand?: boolean;
+    /**
+     * How much padding to leave between elements. Defaults to 100 pixels in each axis.
+     */
+    padding?: PointXY;
+}
+/**
+ * Models the behaviour of the magnetizer
+ * @internal
+ */
+export declare class MagnetizeProfile {
+    gridProfile: GridProfile;
+    readonly afterGroupCollapse: boolean;
+    readonly afterGroupExpand: boolean;
+    readonly afterGroupResize: boolean;
+    readonly afterGroupShrink: boolean;
+    readonly afterGroupGrow: boolean;
+    readonly afterLayout: boolean;
+    readonly afterDrag: boolean;
+    readonly constant: boolean;
+    readonly trackback: boolean;
+    readonly trackbackThreshold: number;
+    readonly constrainToViewport: boolean;
+    readonly repositionDraggedElement: boolean;
+    grid: Grid;
+    constructor(opts: MagnetizeOptions, gridProfile: GridProfile);
+}

package/types/ui/core/overlay/arrow-overlay.d.ts

@@ -0,0 +1,34 @@
+import { SimpleShapeOverlay, SimpleShapeOverlayPaintParams } from "./overlay";
+import { UICore } from "../core";
+import { ArrowOverlayOptions, PaintStyle } from "../../common";
+import { ConnectorPath } from "../connector/connectors";
+import { Connection } from "../connector/connection-impl";
+import { PointXY } from "../../../core";
+/**
+ * @internal
+ */
+export interface ArrowOverlayPaintParams extends SimpleShapeOverlayPaintParams {
+    atts: Array<{
+        d: string;
+        fill: string;
+        stroke: string;
+        "stroke-width": number;
+    }>;
+}
+/**
+ * An arrow overlay, with a length, width, direction, location and foldback point.
+ * @group Edges
+ * @category Overlays
+ */
+export declare class ArrowOverlay<EL> extends SimpleShapeOverlay<EL> {
+    component: Connection<any>;
+    width: number;
+    length: number;
+    foldback: number;
+    direction: number;
+    static type: string;
+    type: string;
+    constructor(instance: UICore<EL>, component: Connection<any>, p: ArrowOverlayOptions);
+    contentTags: string[];
+    draw(connector: ConnectorPath, currentConnectionPaintStyle: PaintStyle, absolutePosition?: PointXY): ArrowOverlayPaintParams;
+}

package/types/ui/core/overlay/custom-overlay.d.ts

@@ -0,0 +1,38 @@
+import { Overlay } from "./overlay";
+import { UICore } from "../core";
+import { OverlayOptions } from "../../common";
+import { Connection } from "../connector/connection-impl";
+import { ObjectData } from "../../../core";
+/**
+ * Options for a custom overlay. You need to supply the `create` method, which is passed the current connection as an argument, and return a DOM element.
+ * @group Edges
+ * @category Overlays
+ */
+export interface CustomOverlayOptions<EL> extends OverlayOptions {
+    create: (c: Connection<EL>) => EL;
+}
+/**
+ * A custom overlay allows you to create the element that will be used to represent the overlay.
+ * @group Edges
+ * @category Overlays
+ */
+export declare class CustomOverlay<EL> extends Overlay<EL> {
+    connection: Connection<EL>;
+    create: (c: Connection<EL>) => EL;
+    isSimpleShape: boolean;
+    constructor(instance: UICore<EL>, connection: Connection<EL>, p: CustomOverlayOptions<EL>);
+    /**
+     * Custom overlay type.
+     */
+    static type: string;
+    type: string;
+    updateFrom(d: any, context: ObjectData): void;
+}
+export interface CustomOverlayHolder<EL> extends CustomOverlay<EL> {
+    contentElement: EL;
+}
+/**
+ * @internal
+ * @param o
+ */
+export declare function isCustomOverlay<EL>(o: Overlay<EL>): o is CustomOverlayHolder<EL>;

package/types/ui/core/overlay/diamond-overlay.d.ts

@@ -0,0 +1,14 @@
+import { ArrowOverlay } from "./arrow-overlay";
+import { ArrowOverlayOptions } from "../../common";
+import { Connection } from "../connector/connection-impl";
+import { UICore } from "../core";
+/**
+ * Draws a diamond overlay. Internally this is an arrow overlay with a foldback point set to 2.
+ * @group Edges
+ * @category Overlays
+ */
+export declare class DiamondOverlay<EL> extends ArrowOverlay<EL> {
+    static type: string;
+    type: string;
+    constructor(instance: UICore<EL>, component: Connection<any>, p: ArrowOverlayOptions);
+}

package/types/ui/core/overlay/dot-overlay.d.ts

@@ -0,0 +1,54 @@
+import { SimpleShapeOverlay, SimpleShapeOverlayPaintParams } from "./overlay";
+import { PaintStyle, SimpleShapeOverlayOptions } from "../../common";
+import { UICore } from "../core";
+import { Connection } from "../connector/connection-impl";
+import { PointXY } from "../../../core";
+import { ConnectorPath } from "../connector/connectors";
+/**
+ * Default radius for a DotOverlay
+ * @internal
+ */
+export declare const DEFAULT_DOT_OVERLAY_RADIUS = 5;
+/**
+ * @internal
+ */
+export interface DotOverlayPaintParams extends SimpleShapeOverlayPaintParams {
+    atts: Array<{
+        cx: number;
+        cy: number;
+        r: number;
+        fill: string;
+        stroke: string;
+        "stroke-width": number;
+    }>;
+}
+/**
+ * Options for a Dot overlay
+ * @group Edges
+ * @category Overlays
+ */
+export interface DotOverlayOptions extends SimpleShapeOverlayOptions {
+    /**
+     * Radius of the dot. Defaults to 5.
+     */
+    radius?: number;
+    /**
+     * When the overlay is at position 1 or 0 (or is being used a source/target marker), this determines how the dot intersects the vertex. A value of 'flush', which is the default, means a point on the circumference of the dot touches the vertex boundary. A value of 'center' means the dot's center is on the vertex boundary.
+     */
+    align?: "flush" | "center";
+}
+/**
+ * A dot overlay, with a configurable radius
+ * @group Edges
+ * @category Overlays
+ */
+export declare class DotOverlay<EL> extends SimpleShapeOverlay<EL> {
+    component: Connection<any>;
+    _radius: number;
+    _align: 'flush' | 'center';
+    constructor(instance: UICore<EL>, component: Connection<any>, params?: DotOverlayOptions);
+    static type: string;
+    type: string;
+    contentTags: string[];
+    draw(connector: ConnectorPath, currentConnectionPaintStyle: PaintStyle, absolutePosition?: PointXY): DotOverlayPaintParams;
+}

package/types/ui/core/overlay/ellipse-overlay.d.ts

@@ -0,0 +1,60 @@
+import { OverlayPaintParams, SimpleShapeOverlay } from "./overlay";
+import { UICore } from "../core";
+import { Connection } from "../connector/connection-impl";
+import { PaintStyle, SimpleShapeOverlayOptions } from "../../common";
+import { PointXY } from "../../../core";
+import { ConnectorPath } from "../connector/connectors";
+/**
+ * Default radius in X for a EllipseOverlay
+ * @internal
+ */
+export declare const DEFAULT_ELLIPSE_OVERLAY_RADIUS_X = 8;
+/**
+ * Default radius in Y for a EllipseOverlay
+ * @internal
+ */
+export declare const DEFAULT_ELLIPSE_OVERLAY_RADIUS_Y = 5;
+/**
+ * @internal
+ */
+export interface EllipseOverlayPaintParams extends OverlayPaintParams {
+    atts: Array<{
+        cx: number;
+        cy: number;
+        rx: number;
+        ry: number;
+        fill: string;
+        stroke: string;
+        "stroke-width": number;
+    }>;
+}
+/**
+ * Options for a Ellipse overlay
+ * @group Edges
+ * @category Overlays
+ */
+export interface EllipseOverlayOptions extends SimpleShapeOverlayOptions {
+    /**
+     * Radius in X. Defaults to 8
+     */
+    rx?: number;
+    /**
+     * Radius in Y. Defaults to 5
+     */
+    ry?: number;
+}
+/**
+ * An ellipse overlay, with a configurable radius for x and for y
+ * @group Edges
+ * @category Overlays
+ */
+export declare class EllipseOverlay<EL> extends SimpleShapeOverlay<EL> {
+    component: Connection<any>;
+    rx: number;
+    ry: number;
+    constructor(instance: UICore<EL>, component: Connection<any>, params?: EllipseOverlayOptions);
+    static type: string;
+    type: string;
+    contentTags: string[];
+    draw(connector: ConnectorPath, currentConnectionPaintStyle: PaintStyle, absolutePosition?: PointXY): EllipseOverlayPaintParams;
+}

package/types/ui/core/overlay/label-overlay.d.ts

@@ -0,0 +1,37 @@
+import { Overlay } from "./overlay";
+import { UICore } from "../core";
+import { LabelOverlayOptions } from "../../common";
+import { Connection } from "../connector/connection-impl";
+import { ObjectData } from "../../../core";
+import { FontSpec } from "../../../browser-ui";
+/**
+ * An overlay that draws some text. By default this overlay will use an HTML element, and that element's parent will be the surface canvas, unless the container is an SVG element, in which case the overlay will use an SVG element. You can set `useHTMLElement:false` in the options if you want the overlay to use an SVG element regardless of the container element type.
+ * @group Edges
+ * @category Overlays
+ */
+export declare class LabelOverlay<EL> extends Overlay<EL> {
+    private instance;
+    component: Connection<EL>;
+    label: string | Function;
+    static type: string;
+    type: string;
+    useHTMLElement: boolean;
+    font: FontSpec;
+    constructor(instance: UICore<EL>, component: Connection<EL>, p: LabelOverlayOptions);
+    isSimpleShape: boolean;
+    getLabel(): string;
+    setLabel(l: string | Function): void;
+    updateFrom(d: any, context: ObjectData): void;
+}
+/**
+ * @internal
+ * @param o
+ */
+export declare function isLabelOverlay<EL>(o: Overlay<EL>): o is LabelOverlay<EL>;
+/**
+ * Updates the font for the given label overlay according to the values in data, which may be null
+ * @param lo
+ * @param data
+ * @internal
+ */
+export declare function $updateLabelOverlayFont(lo: LabelOverlay<any>, data: ObjectData): void;

package/types/ui/core/overlay/overlay.d.ts

@@ -0,0 +1,131 @@
+import { UICore } from "../core";
+import { FullOverlaySpec, InternalOverlaySpec, OverlayOptions, OverlaySpec, PaintStyle, SimpleShapeOverlayOptions } from "../../common";
+import { Connection } from "../connector/connection-impl";
+import { EVENT_CLICK } from "../event-constants";
+import { Extents, ObjectData, PointXY } from "../../../core";
+import { ConnectorPath } from "../connector/connectors";
+/**
+ * Returns whether or not the given overlay spec is a 'full' overlay spec, ie. has a `type` and some `options`, or is just an overlay name.
+ * @param o
+ * @internal
+ */
+export declare function isFullOverlaySpec(o: OverlaySpec): o is FullOverlaySpec;
+/**
+ * Convert the given input into an object in the form of a `FullOverlaySpec`
+ * @param spec
+ * @internal
+ */
+export declare function convertToFullOverlaySpec(spec: string | OverlaySpec): InternalOverlaySpec;
+/**
+ * Events that can be bound on an overlay in a view.
+ */
+export type OverlayEvents = typeof EVENT_CLICK;
+/**
+ * Defines the always visible state for an overlay
+ * @group Edges
+ * @category Overlays
+ */
+export declare const OVERLAY_VISIBILITY_ALWAYS = "always";
+/**
+ * Defines the visible only on hover state for an overlay
+ * @group Edges
+ * @category Overlays
+ */
+export declare const OVERLAY_VISIBILITY_HOVER = "hover";
+/**
+ * Defines the available visibility states for an overlay
+ * @group Edges
+ * @category Overlays
+ */
+export type OverlayVisibility = typeof OVERLAY_VISIBILITY_ALWAYS | typeof OVERLAY_VISIBILITY_HOVER;
+/**
+ * @group Edges
+ * @category Overlays
+ * @internal
+ */
+export interface OverlayPaintParams extends Extents {
+    tail: PointXY;
+}
+/**
+ * @group Edges
+ * @category Overlays
+ * @internal
+ * @param o
+ * @param l
+ */
+export declare function setOverlayLocation(o: Overlay<any>, l: number | string): void;
+/**
+ * Base class for overlays.
+ * @group Edges
+ * @category Overlays
+ * @internal
+ */
+export declare abstract class Overlay<EL> {
+    component: Connection<EL>;
+    id: string;
+    abstract type: string;
+    cssClass: string;
+    _visibility: OverlayVisibility;
+    visible: boolean;
+    location: number;
+    events: Record<string, (value: any, event?: any) => any>;
+    attributes: Record<string, string>;
+    /**
+     * Set internally when this overlay came into being via a programmatic addition, and should not be managed by the
+     * types system.
+     * @internal
+     * @param instance
+     * @param component
+     * @param p
+     */
+    ignoreTypes: boolean;
+    constructor(component: Connection<EL>, p: OverlayOptions);
+    abstract updateFrom(opts: any, context: ObjectData): void;
+    abstract isSimpleShape: boolean;
+}
+/**
+ * @group Edges
+ * @category Overlays
+ * @internal
+ */
+export interface SimpleShapeOverlayPaintParams extends OverlayPaintParams {
+    atts: Array<Record<string, any> & {
+        fill: string;
+        stroke: string;
+        "stroke-width": number;
+    }>;
+}
+/**
+ * Base class for an overlay that is a simple geometric shape.
+ * @internal
+ * @group Edges
+ * @category Overlays
+ */
+export declare abstract class SimpleShapeOverlay<EL> extends Overlay<EL> {
+    component: Connection<EL>;
+    paintStyle: PaintStyle;
+    $hollow: boolean;
+    constructor(instance: UICore<EL>, component: Connection<EL>, p: SimpleShapeOverlayOptions);
+    isSimpleShape: boolean;
+    $getStyle(currentConnectionPaintStyle: PaintStyle): {
+        stroke: string;
+        fill: string;
+        lineWidth: number;
+    };
+    updateFrom(d: any, context: ObjectData): void;
+    /**
+     * Return the tag for this overlay's content element. For instance, the ArrowOverlay returns a `path`;
+     * DotOverlay returns `circle`.
+     */
+    abstract contentTags: Array<string>;
+    abstract draw(connector: ConnectorPath, currentConnectionPaintStyle: PaintStyle, absolutePosition?: PointXY): SimpleShapeOverlayPaintParams;
+}
+/**
+ * Parameters passed to a mouse event callback on an overlay event registration.
+ * @group Edges
+ * @category Overlays
+ */
+export interface OverlayMouseEventParams<EL> {
+    e: Event;
+    overlay: Overlay<EL>;
+}

package/types/ui/core/overlay/plain-arrow-overlay.d.ts

@@ -0,0 +1,15 @@
+import { ArrowOverlay } from "./arrow-overlay";
+import { UICore } from "../core";
+import { ArrowOverlayOptions } from "../../common";
+import { Connection } from "../connector/connection-impl";
+/**
+ * A PlainArrow is an arrow with a flat baseline, ie. it does not fold back at all. Internally
+ * this overlay is simply an `Arrow` overlay with `foldback` set to 1.
+ * @group Edges
+ * @category Overlays
+ */
+export declare class PlainArrowOverlay<EL> extends ArrowOverlay<EL> {
+    static type: string;
+    type: string;
+    constructor(instance: UICore<EL>, component: Connection<any>, p: ArrowOverlayOptions);
+}

package/types/ui/core/overlay/rectangle-overlay.d.ts

@@ -0,0 +1,66 @@
+import { OverlayPaintParams, SimpleShapeOverlay } from "./overlay";
+import { UICore } from "../core";
+import { Connection } from "../connector/connection-impl";
+import { PointXY } from "../../../core";
+import { PaintStyle, Connector, SimpleShapeOverlayOptions } from "../../common";
+/**
+ * Default width for a RectangleOverlay
+ * @internal
+ */
+export declare const DEFAULT_RECTANGLE_OVERLAY_WIDTH = 10;
+/**
+ * Default height for a RectangleOverlay
+ * @internal
+ */
+export declare const DEFAULT_RECTANGLE_OVERLAY_HEIGHT = 10;
+/**
+ * Options for a Rectangle overlay
+ * @group Edges
+ * @category Overlays
+ */
+export interface RectangleOverlayOptions extends SimpleShapeOverlayOptions {
+    /**
+     * Width of the rectangle. Defaults to 10.
+     */
+    width?: number;
+    /**
+     * Height of the rectangle. Defaults to 10.
+     */
+    height?: number;
+    /**
+     * Whether or not to rotate the rectangle so that it is always perpendicular to the connector path. Defaults to false.
+     */
+    rotate?: boolean;
+    /**
+     * When the overlay is at position 1 or 0 (or is being used a source/target marker), this determines how the rectangle intersects the vertex. A value of 'flush', which is the default, means a point on the boundary of the rectangle touches the vertex boundary. A value of 'center' means the rectangle's center is on the vertex boundary.
+     */
+    align?: "flush" | "center";
+}
+/**
+ * @internal
+ */
+export interface RectangleOverlayPaintParams extends OverlayPaintParams {
+    atts: Array<{
+        fill: string;
+        stroke: string;
+        "stroke-width": number;
+        d: string;
+    }>;
+}
+/**
+ * A rectangle overlay, with a configurable width/height
+ * @group Edges
+ * @category Overlays
+ */
+export declare class RectangleOverlay<EL> extends SimpleShapeOverlay<EL> {
+    component: Connection<any>;
+    width: number;
+    height: number;
+    _rotate: boolean;
+    _align: 'flush' | 'center';
+    constructor(instance: UICore<EL>, component: Connection<any>, params?: RectangleOverlayOptions);
+    static type: string;
+    type: string;
+    contentTags: string[];
+    draw(connector: Connector, currentConnectionPaintStyle: PaintStyle, absolutePosition?: PointXY): RectangleOverlayPaintParams;
+}