@visuallyjs/browser-ui 1.0.0

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

@@ -0,0 +1,540 @@
+import { Connection } from "./connector/connection-impl";
+import { ViewportElement, ViewportGroupElement } from "./viewport";
+import { Group, Node, Vertex } from "../../core/model/graph";
+import { Extents, PointXY, Size } from "../../core/util";
+import { ExportOptions, VisuallyJsModel } from "../../core/toolkit";
+import { MagnetizeProfile } from "./magnetize-profile";
+import { MagnetizeResult } from "../../core/magnetizer";
+import { ConstrainFunction } from "../util/util";
+import { BOTTOM, CENTER, LEFT, RIGHT, TOP } from "../../core";
+import { UICore } from "./core";
+export type ElementSelectionSpecifier<E> = E | Array<E> | '*';
+export type SelectionList = '*' | Array<string>;
+export interface AbstractSelectOptions<E> {
+    scope?: SelectionList;
+    source?: ElementSelectionSpecifier<E>;
+    target?: ElementSelectionSpecifier<E>;
+}
+export interface SelectOptions<E> extends AbstractSelectOptions<E> {
+    connections?: Array<Connection<E>>;
+}
+export interface SelectEndpointOptions<E> extends AbstractSelectOptions<E> {
+    element?: ElementSelectionSpecifier<E>;
+}
+/**
+ * Optional parameters to the `DeleteConnection` method.
+ * @internal
+ */
+export type DeleteConnectionOptions = {
+    /**
+     * if true, force deletion even if the connection tries to cancel the deletion.
+     */
+    force?: boolean;
+    /**
+     * If false, an event won't be fired. Otherwise a `connection:detach` event will be fired.
+     */
+    fireEvent?: boolean;
+    /**
+     * Optional original event that resulted in the connection being deleted.
+     */
+    originalEvent?: Event;
+};
+export interface GroupResizeResult<E> {
+    element: ViewportGroupElement<E>;
+    newGroupSize: Size;
+    originalGroupSize: Size;
+}
+/**
+ * @internal
+ */
+export type GroupContentAreaInfo<E> = {
+    pageOrigin: PointXY;
+    internalOffset: PointXY;
+    contentArea: E;
+    isGroupElement: boolean;
+};
+/**
+ * @internal
+ */
+export interface GroupLayoutResult<E> {
+    positions: Record<string, PointXY>;
+    sizes: Record<string, Size>;
+    extents: Extents;
+    element: ViewportGroupElement<E>;
+}
+export interface DragHandler2StartParams<E> {
+    /**
+     * The mouse event that instigated the drag
+     */
+    e: MouseEvent;
+    /**
+     * The element being dragged.
+     */
+    el: E;
+    /**
+     * The page position of the initial event. This position is relative to the page origin, and does not take
+     * page scroll into account. It _cannot_ be safely compared to the return value of getBoundingClientRect, because
+     * getBoundingClientRect returns values relative to the viewport origin (ie. the visible part of the page).
+     */
+    pagePosition: PointXY;
+    /**
+     * The page position of the given element translated to the canvas. This value has
+     * taken into account page scroll.
+     */
+    translatedPosition: PointXY;
+    size: Size;
+}
+export interface DragHandler2DragParams<E> extends DragHandler2StartParams<E> {
+    originalPagePosition: PointXY;
+    originalTranslatedPosition: PointXY;
+}
+export interface DragHandler2StopParams<E> extends DragHandler2DragParams<E> {
+}
+export interface DragHandler2<E> {
+    selector: string;
+    target?: string;
+    start: (params: DragHandler2StartParams<E>) => any;
+    drag: (params: DragHandler2DragParams<E>) => any;
+    stop: (params: DragHandler2StopParams<E>) => any;
+    priority?: number;
+    constrainFunction: ConstrainFunction<E, any>;
+    usesPageCoordinates?: boolean;
+}
+/**
+ * Defines a function that will be invoked prior to a vertex being dragged. Returning false from this function will abort the vertex drag.
+ */
+export type VertexDragFilter<E> = (p: {
+    el: E;
+    vertex: Node | Group;
+    e: MouseEvent;
+}) => boolean;
+/**
+ * Defines a function that can constrain drag.
+ */
+export type DragConstrainFunction<E> = (desiredLoc: PointXY, dragEl: E, modelObject: Node | Group, size: Size, currentLoc: PointXY, e: MouseEvent) => PointXY;
+/**
+ * Options for element drag
+ * @group Components
+ * @category Element dragging
+ */
+export interface DragOptions<E> {
+    /**
+     * Optional function to invoke prior to a drag starting.
+     */
+    filter?: VertexDragFilter<E>;
+    /**
+     * Optional CSS3 selector identifying parts of nodes/groups that should not cause a drag to start.
+     */
+    cssFilter?: string;
+    /**
+     * Optional function to use to constrain element dragging.
+     * @param desiredLoc
+     * @param dragEl
+     * @param size
+     * @param currentLoc
+     */
+    constrainFunction?: DragConstrainFunction<E>;
+    /**
+     * Defaults to true, meaning the canvas will pan automatically to track elements that have been dragged out of the visible area.
+     */
+    autoPan?: boolean;
+    /**
+     * When auto-panning, this is the speed (in milliseconds) at which the canvas repositions itself. Defaults to 15ms.
+     */
+    autoPanRepeat?: number;
+    /**
+     * When auto-panning, this is the number of pixels that the canvas repositions itself on each tick. Defaults to 5.
+     */
+    autoPanDelta?: number;
+    /**
+     * 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;
+}
+/**
+ * @internal
+ */
+export interface SupportsElementDragging<E> {
+    dragOptions: DragOptions<E>;
+    addDragHandler(handler: DragHandler2<E>): void;
+    $canStartElementDrag(): boolean;
+    isDraggable: (e: E) => boolean;
+    getZoom: () => number;
+    getEffectiveVisibleZoom: () => number;
+    magnetizerProfile: MagnetizeProfile;
+    $getDragViewportContainer: () => E;
+    getContainer: () => E;
+    model: VisuallyJsModel;
+    autoSizeGroup(group: Group, force: boolean): void;
+    $modelLeftAttribute: string;
+    $modelTopAttribute: string;
+    $startPanRepeat: (dirX: 1 | 0 | -1, dirY: 1 | 0 | -1, dx: number, dy: number, interval: number, cb?: (total: PointXY) => any) => void;
+    $stopPanRepeat: () => void;
+    $provisionallyMagnetize(focus: Vertex, repositionFocus: boolean, knownLocations: Record<string, PointXY>, knownSizes: Record<string, Size>, magnetizerIsAlreadyPrimed: boolean, invertTrackbackPreference: boolean): MagnetizeResult;
+}
+/**
+ * Payload for the node:move:start event that is fired when a node/group has just begun to be moved.
+ * @group Events
+ * @category Element dragging
+ * @eventPayload
+ * @context element-dragging
+ */
+export interface VertexMoveStartParams<E> {
+    dragGroup: Array<{
+        el: E;
+        pos: PointXY;
+        vertex: Node | Group;
+        element: ViewportElement<E>;
+    }>;
+    ui: UICore<E, any>;
+}
+/**
+ * Payload for the node:move event that is fired when a node/group has just begun to be moved.
+ * @group Events
+ * @category Element dragging
+ * @eventPayload
+ * @context element-dragging
+ */
+export interface VertexMoveParams<E> {
+    /**
+     * The list of vertices that were dragged. This array will always contain at the very least information about a vertex that was dragged. If the vertex was in a drag group then all of the members of that drag group will be in this array too.
+     */
+    dragGroup: Array<{
+        pos: PointXY;
+        vertex: Node | Group;
+        originalPos: PointXY;
+        element: ViewportElement<E>;
+    }>;
+    /**
+     * This object contains a record of the final position of every vertex that was moved as a result of this vertex drag - the vertex itself, any members of a drag group for which the vertex was an active member, plus any elements that may have been moved via the magnetizer during or after the drag.
+     */
+    positions: Record<string, PointXY>;
+    ui: UICore<E, any>;
+}
+/**
+ * Payload for the node:move:end event that is fired when a node/group has just been moved.
+ * @group Events
+ * @category Element dragging
+ * @eventPayload
+ * @context element-dragging
+ */
+export interface VertexMoveEndParams<E> {
+    /**
+     * The list of vertices that were dragged. This array will always contain at the very least information about a vertex that was dragged. If the vertex was in a drag group then all of the members of that drag group will be in this array too.
+     */
+    dragGroup: Array<{
+        el: E;
+        pos: PointXY;
+        vertex: Node | Group;
+        originalPos: PointXY;
+        element: ViewportElement<E>;
+    }>;
+    ui: UICore<E, any>;
+}
+/**
+ * Options for the save method.
+ * @group Components
+ * @category Input and Output
+ */
+export interface UIExportOptions extends ExportOptions {
+}
+/**
+ * Return value from UI save; argument to ui load.
+ * @group Components
+ * @category Input and Output
+ */
+export interface UISaveData {
+    zoom: number;
+    data: any;
+}
+/**
+ * Models the current bounds of a viewport, containing its x/y location,
+ * width/height and current zoom.
+ * @group Components
+ */
+export interface ViewportBounds {
+    /**
+     * Width of the content displayed in the viewport
+     */
+    width: number;
+    /**
+     * Height of the content displayed in the viewport
+     */
+    height: number;
+    /**
+     * Minimum value in X of the content displayed in the viewport
+     */
+    x: number;
+    /**
+     * Minimum value in Y of the content displayed in the viewport
+     */
+    y: number;
+    /**
+     * The width of the viewport element.
+     */
+    vw: number;
+    /**
+     * The height of the viewport element.
+     */
+    vh: number;
+    /**
+     * The content in each axis fills the viewport at some ratio to the viewport size in that axis. This field provides the smaller of those two ratios. The axis it pertains to is not specified. The inverse of this value gives you the zoom level that would allow all the content to fit in the viewport.
+     */
+    minimumFill: number;
+    /**
+     * The current zoom level applied in the viewport.
+     */
+    zoom: number;
+}
+/**
+ * A DataHook is a pair of functions that are invoked during a `load` and a `save`. This mechanism is a means you can use for storing/retrieving custom data from the payload the UI exports.
+ */
+export interface DataHook {
+    load: (d: UISaveData) => any;
+    save: (d: UISaveData) => any;
+}
+/**
+ * Base options for a find enclosed/intersecting vertices call.
+ */
+interface EnclosedOrIntersectingVerticesOptions {
+    /**
+     * Origin of the search rectangle, in canvas coordinates
+     */
+    origin: PointXY;
+    /**
+     * Size of the search rectangle, in canvas coordinates
+     */
+    dimensions: Size;
+    /**
+     * If true, ignore groups in the canvas root
+     */
+    dontIncludeGroups?: boolean;
+    /**
+     * If true, ignore nodes in the canvas root
+     */
+    dontIncludeNodes?: boolean;
+    /**
+     * If true, ignore nodes that are children of groups
+     */
+    dontIncludeNodesInsideGroups?: boolean;
+    /**
+     * If true, ignore groups that are children of groups
+     */
+    dontIncludeNestedGroups?: boolean;
+}
+/**
+ * Options for a find intersecting vertices call
+ */
+export interface IntersectingVerticesOptions extends EnclosedOrIntersectingVerticesOptions {
+    /**
+     * If true, only vertices fully enclosed by the search rectangle will be returned
+     */
+    enclosed?: boolean;
+}
+/**
+ * Options for a find enclosed vertices call
+ */
+export interface EnclosedVerticesOptions extends EnclosedOrIntersectingVerticesOptions {
+}
+/**
+ * Possible alignments for the `alignX` argument to `alignContent`
+ */
+export type CanvasAlignmentX = typeof LEFT | typeof CENTER | typeof RIGHT;
+/**
+ * Possible alignments for the `alignY` argument to `alignContent`
+ */
+export type CanvasAlignmentY = typeof TOP | typeof CENTER | typeof BOTTOM;
+/**
+ * Options for a content centering operation.
+ */
+export type CenterContentOptions = {
+    /**
+     * @internal
+     */
+    bounds?: ViewportBounds;
+    /**
+     * True by default. Indicates the content should be centered in the X axis.
+     */
+    horizontal?: boolean;
+    /**
+     * True by default. Indicates the content should be centered in the Y axis.
+     */
+    vertical?: boolean;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * If true, don't animate while centering. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * Zoom level to set, optional
+     */
+    zoom?: number;
+    /**
+     * How long, in milliseconds, the animation should take to run.
+     */
+    animationDuration?: number;
+};
+/**
+ * Options for aligning content in the UI.
+ */
+export interface AlignContentOptions {
+    /**
+     * How to align the content in the Y axis - top, bottom or center
+     */
+    alignY?: CanvasAlignmentY;
+    /**
+     * How to align the content in the X axis - left, right or center
+     */
+    alignX?: CanvasAlignmentX;
+    /**
+     * @internal
+     */
+    bounds?: ViewportBounds;
+    /**
+     * How much padding to leave around the content.
+     */
+    padding?: number;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * If true, don't animate while centering. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * How long, in milliseconds, the animation should take to run.
+     */
+    animationDuration?: number;
+    /**
+     * Zoom to set prior to alignment
+     */
+    zoom?: number;
+}
+/**
+ * Options for aligning content to a specific position in the UI.
+ */
+export interface AlignContentToFaceOptions {
+    /**
+     * Zoom level to set during the alignment
+     */
+    zoom?: number;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * If true, don't animate while centering. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * How long, in milliseconds, the animation should take to run.
+     */
+    animationDuration?: number;
+}
+/**
+ * Options for the zoomToElements method.
+ */
+export interface ZoomToElementsOptions<EL> {
+    /**
+     * Array of elements to zoom to
+     */
+    elements: Array<EL>;
+    /**
+     * If true, don't animate while zooming. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * A decimal between 0 and 1, which indicates how much of the viewport size the content will take up. This value is applied as a ratio of the width or height of the viewport - whichever is smaller. The default is 0.9.
+     */
+    fill?: number;
+    /**
+     * If the content is all already visible, do not make any changes to zoom.
+     */
+    doNotZoomIfVisible?: boolean;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+}
+/**
+ * Base Options for the zoomToFit methods.
+ */
+export interface BaseZoomToFitOptions {
+    /**
+     * If true, don't animate while centering. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * Blank space to leave around the content
+     */
+    padding?: number;
+    /**
+     * A decimal between 0 and 1, which indicates how much of the viewport size the content will take up. This value is applied as a ratio of the width or height of the viewport - whichever is smaller. The default is 0.9.
+     */
+    fill?: number;
+    /**
+     * How to align the content in the Y axis - top, bottom or center
+     */
+    alignY?: CanvasAlignmentY;
+    /**
+     * How to align the content in the X axis - left, right or center
+     */
+    alignX?: CanvasAlignmentX;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+}
+/**
+ * Options for the zoomToFit method.
+ */
+export interface ZoomToFitOptions extends BaseZoomToFitOptions {
+    /**
+     * If the content is all already visible, do not make any changes to zoom.
+     */
+    doNotZoomIfVisible?: boolean;
+}
+/**
+ * Options for the zoomToFitIfNecessary method.
+ */
+export interface ZoomToFitIfNecessaryOptions extends BaseZoomToFitOptions {
+}
+/**
+ * @internal
+ */
+export declare enum ElementTypes {
+    SVG = "SVG",
+    HTML = "HTML"
+}
+/**
+ * @internal
+ */
+export type ElementType = keyof typeof ElementTypes;
+export {};