@visuallyjs/browser-ui 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visuallyjs/browser-ui",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "license": "Commercial",
   "main": "js/visuallyjs.browser-ui.cjs.js",
   "module": "js/visuallyjs.browser-ui.esm.js",

package/types/browser-ui/auto-pan-handler.d.ts

@@ -1,11 +1,12 @@
 import { PointXY } from "../core";
-import { SupportsElementDragging } from "../ui";
+import { AutoPanBoundsStrategy, SupportsElementDragging } from "../ui";
 import { BrowserElement } from "./util";
 export interface AutoPanOptions {
     autoPanDelta?: number;
     autoPanRepeat?: number;
     onPan: (deltas: PointXY) => void;
     shouldHandle: () => boolean;
+    boundsStrategy?: AutoPanBoundsStrategy;
 }
 /**
  * Manages auto pan for a component that supports dragging of elements (not just vertex elements, any elements, such as those used to manage edge dragging or lasso etc).
@@ -19,6 +20,7 @@ export declare class AutoPanHandler {
     private _lastPanDirection;
     private _isPanRepeatActive;
     private _rootBounds;
+    private _boundsStrategy;
     constructor(draggableInstance: SupportsElementDragging<BrowserElement>, options: AutoPanOptions);
     /**
      * Called by ElementDragHandler2 to continuously update the auto-pan logic during a drag.
@@ -27,6 +29,13 @@ export declare class AutoPanHandler {
     updateDragElementPosition(boundingClientRect: DOMRect): void;
     $updateRootBounds(): void;
     private _isElementIntersectingRoot;
+    private _isElementContainedRoot;
+    /**
+     * Determines whether or not the given rect is conside to be inside the root bounds, depending on the current bounds strategy.
+     * @param boundingClientRect
+     * @private
+     */
+    private _isElementInsideRootBounds;
     private _updatePanDirectionAndStartRepeat;
     private _stopPanRepeatInternal;
     reset(): void;

package/types/browser-ui/browser-visuallyjs-instance.d.ts

@@ -40,6 +40,7 @@ export declare abstract class BrowserUI<EVT = any> extends UICore<BrowserElement
     private readonly _managedElementsSelector;
     private readonly _hoverEvents;
     private readonly _eventManager;
+    private _elementEventFilterSelectors;
     private _canDropHandler;
     private _transferrableVertexAttributes;
     /**
@@ -59,6 +60,11 @@ export declare abstract class BrowserUI<EVT = any> extends UICore<BrowserElement
      * @internal
      */
     $canDrop(candidate: Node | Group, target?: Node | Group, onCanvas?: boolean): boolean;
+    /**
+     * Adds a CSS3 selector filter which will exclude the given element (and descendants) from reporting element events. Used internally by popups, but exposed in the API as it may be useful.
+     * @param selector A valid CSS3 selector.
+     */
+    addElementEventFilter(selector: string): void;
     $vertexRendered<N extends Vertex>(v: N, el: BrowserElement, def: VertexMapping<any, BrowserElement>, eventInfo?: {
         position: PointXY;
     }): void;

package/types/browser-ui/components/inspector/definitions.d.ts

@@ -84,6 +84,7 @@ export type FieldInfo = {
     commonValue: any;
     editedValue?: any;
     attribute: string;
+    portId?: string;
 };
 /**
  * Options for the VanillaInspector, an instance of Inspector that uses VisuallyJs's default templating mechanism to render elements.

package/types/browser-ui/components/inspector/inspector.d.ts

@@ -77,7 +77,7 @@ export declare class Inspector extends VjsContext {
     protected $_recomputeCommonData(): void;
     private __filterEmptyStrings;
     /**
-     * Write the changes to the toolkit.
+     * Write the changes to the model.
      * @param updates
      * @internal
      */
@@ -107,7 +107,7 @@ export declare class Inspector extends VjsContext {
      * @param value
      *
      */
-    setValue(key: string, value: any, repaintAfterwards?: boolean): void;
+    setValue(key: string, value: any, portId: string, repaintAfterwards?: boolean): void;
     /**
      * @internal
      * @param b

package/types/browser-ui/dialogs/binder.d.ts

@@ -22,6 +22,7 @@ export declare function attemptCoerce(value: string, datatype: SupportedCoercion
  * @internal
  */
 export declare function extractValueFromElement(el: HTMLElement, unresolvedElementGetter?: (el: Element) => any): any;
+export declare function $makeFieldKey(att: string, portSeparator: string, portId: string | null): string;
 /**
  * Apply the given object to the given DOM element. This method will find all child elements of `el` that have a `vjs-att`
  * attribute set, and then attempt to set the value of any found DOM element with a value extracted from `dataset`.
@@ -30,7 +31,7 @@ export declare function extractValueFromElement(el: HTMLElement, unresolvedEleme
  * @param autoCommitHandler
  * @internal
  */
-export declare function apply(dataset: Record<string, any>, el: any, autoCommitHandler?: (e: Element) => any, unresolvedElementSetter?: (e: Element, value: any) => any): void;
+export declare function apply(dataset: Record<string, any>, el: any, portSeparator: string, autoCommitHandler?: (e: Element) => any): void;
 /**
  * @internal
  */

package/types/browser-ui/dialogs/constants.d.ts

@@ -6,6 +6,7 @@ export declare const DialogConstants: {
         VJS_COMMIT: string;
         MULTIPLE: string;
         VJS: string;
+        VJS_PORT: string;
         DATATYPE: string;
         TITLE: string;
         FOCUS: string;

package/types/browser-ui/pan-zoom.d.ts

@@ -470,7 +470,7 @@ export declare class PanZoom {
      */
     setTransformOrigin(x: number, y: number): void;
     /**
-     * Maps the given page location to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.
+     * Maps the given page location to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner.
      * @param left X location
      * @param top Y location
      * @param roundValues If true, return integers.
@@ -479,13 +479,19 @@ export declare class PanZoom {
     fromPageLocation(left: number, top: number, roundValues?: boolean): PointXY;
     fromWindowLocation(left: number, top: number, roundValues?: boolean): PointXY;
     /**
-     * Maps the given location on the canvas to a point relative to the page origin, allowing for zoom and
-     * pan of the canvas. This takes into account the offset of the viewport in the page so that what
-     * you get back is the mapped position computed relative to the target element's [left,top] corner.
+     * Maps the given location on the canvas to a point relative to the page origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position computed relative to the target element's [left,top] corner.
      * @param left
      * @param top
      */
     toPageLocation(left: number, top: number): PointXY;
+    /**
+     * Maps the given canvas location to a point, in page coordinates, relative to the panzoom container's origin. A return value of [0,0] from this method indicates the top left corner of the surface's container as seen by the user; negative values for x and/or y mean that the point is not in the visible viewport. Similarly, values for x greater the container width, or y greater than the container height, indicate that the point is not in the visible viewport.
+     *
+     * This method is useful when you want to position an element over the canvas at some specific canvas location. For instance, the SurfacePopup components use this to position themselves relative to the vertex they are currently referencing.
+     * @param left
+     * @param top
+     */
+    toViewportLocation(left: number, top: number): PointXY;
     /**
      * Maps the page location of the given event to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.
      * @param event Browser event
@@ -498,10 +504,7 @@ export declare class PanZoom {
      */
     setEnabled(state: boolean): void;
     /**
-     * Returns the apparent origin of the canvas inside the viewport - the coordinates, in real pixel
-     * values, of where the origin of the canvas appears to be. This apparent origin is not necessarily the
-     * same as the origin values of the canvas, because the transform origin and zoom values change
-     * things. This function can be used in conjunction with the content bounds by widgets such as the miniview, to calculate what is actually visible in the viewport at some point in time.
+     * Returns the apparent origin of the canvas inside the viewport - the coordinates, in real pixel values, of where the origin of the canvas appears to be. This apparent origin is not necessarily the same as the origin values of the canvas, because the transform origin and zoom values change things. This function can be used in conjunction with the content bounds by widgets such as the miniview, to calculate what is actually visible in the viewport at some point in time.
      * @returns Position of the canvas, relative to the viewport's 0,0.
      */
     getApparentCanvasLocation(): PointXY;
@@ -517,16 +520,13 @@ export declare class PanZoom {
      */
     getVisibleContentArea(): RectangleXY;
     /**
-     * Appends an element to the viewport so that it floats above the content that is being zoomed and panned.
-     * The element will have `position:absolute` set on it. You can float any element you like, but note that the
-     * responsibility for setting an appropriate z index is yours.
+     * Appends an element to the viewport so that it floats above the content that is being zoomed and panned. The element will have `position:absolute` set on it. You can float any element you like, but note that the responsibility for setting an appropriate z index is yours.
      * @param el - Element to float.
      * @param pos - Position to float the element at.
      */
     floatElement(el: Element, pos: PointXY): void;
     /**
-     * Appends an element to the viewport such that it is zoomed with everything else, but constrains pan
-     * in one or both axes so that the element remains fixed with respect to the viewport origin.
+     * Appends an element to the viewport such that it is zoomed with everything else, but constrains pan in one or both axes so that the element remains fixed with respect to the viewport origin.
      * @param el The DOM element to append.
      * @param pos Location of the element's origin.
      * @param constraints Flags to indicate optional constraint to each axis.
@@ -564,8 +564,7 @@ export declare class PanZoom {
      */
     destroy(): void;
     /**
-     * returns whether or not the given element is owned by the current background, if there is one. with some library
-     * integrations the background can be temporarily null during the processing of an event.
+     * returns whether or not the given element is owned by the current background, if there is one. with some library integrations the background can be temporarily null during the processing of an event.
      * @internal
      * @param el
      */

package/types/browser-ui/paper-renderer/definitions.d.ts

@@ -7,6 +7,14 @@ import { BrowserUIDefaults, BrowserUIOptions } from "../definitions";
  * @category Paper
  */
 export declare const CLASS_PAPER = "vjs-paper";
+/**
+ * Css class added to a Paper component's container element when scaling is switched off.
+ * @cssClass
+ * @context paper
+ * @group Components
+ * @category Paper
+ */
+export declare const CLASS_PAPER_NO_SCALE = "vjs-paper-no-scale";
 /**
  * Css class added to the DOM element used to render a Paper object.
  * @group Components
@@ -75,6 +83,7 @@ export interface PaperOptions extends BrowserUIOptions<PaperDefaults> {
      * Strategy to use to place content within whitespace in the vertical axis.
      */
     verticalAlign?: PaperAlignment;
+    scale?: boolean;
 }
 /**
  * Defaults for a Paper renderer

package/types/browser-ui/paper-renderer/paper.d.ts

@@ -16,6 +16,7 @@ export declare class Paper extends BrowserUI {
     $margin: number;
     $horizontalAlign: PaperAlignment;
     $verticalAlign: PaperAlignment;
+    $scale: boolean;
     /**
      * @internal
      * @param model
@@ -41,6 +42,20 @@ export declare class Paper extends BrowserUI {
     fromWindowLocation(left: number, top: number, roundValues?: boolean): PointXY;
     mapEventLocation(event: MouseEvent): PointXY;
     getViewportBoundsInfo(): ViewportBounds;
+    /**
+     * When not scaling, this method is used by the background to determine what size it should be.
+     * @internal
+     */
+    $getFixedViewportBoundsInfo(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        vw: number;
+        vh: number;
+        zoom: number;
+        minimumFill: number;
+    };
     getApparentCanvasLocation(): PointXY;
     addBackground(background: Background): void;
     removeBackground(background: Background): void;

package/types/browser-ui/plugins/background/generated-grid-background.d.ts

@@ -168,7 +168,7 @@ export declare const CLASS_BACKGROUND_GRID_DOT_MINOR = "vjs-background-grid-dott
  * lines or dots - control this via the `gridType` option.
  *
  * The size of the grid can be mandated in the options for the background, or
- * it can be extracted from the surface.
+ * it can be extracted from the UI.
  *
  * You can hide/show the background grid via the `hide()`, `show()`, `toggle()` or `setVisible(boolean)`
  * methods.

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

@@ -16,6 +16,7 @@ export * from './surface-events';
 export * from './surface-render-options';
 export * from './diagrams';
 export * from './css-classes';
+export * from "./popups";
 /**
  * Register a new decorator for use with the {@link Surface} component.
  * @param name Name to use when registering the decorator.

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

@@ -0,0 +1,14 @@
+/**
+ * The attribute uyed to instruct a PopupHandler where to place a popup with respect to the vertex it is attached to.
+ */
+export declare const ATTRIBUTE_POPUP_POSITION = "data-vjs-popup-position";
+/**
+ * Possible values for the popup position attribute.
+ */
+export type PopupPosition = "top" | "bottom" | "left" | "right" | "center";
+/**
+ * CSS class written on surface popups
+ * @cssClass
+ * @context Popups
+ */
+export declare const CLASS_SURFACE_POPUP = "vjs-surface-popup";

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

@@ -0,0 +1,3 @@
+export * from "./definitions";
+export * from "./popup-handler";
+export * from "./util";

package/types/browser-ui/surface-renderer/popups/popup-handler.d.ts

@@ -0,0 +1,28 @@
+import { PopupPosition } from "./definitions";
+import { Vertex } from "../../../core";
+import { BrowserElement } from "../../util";
+import { ViewportElement } from "../../../ui";
+import { Surface } from "../surface";
+/**
+ * A handler for popups to appear in relation to vertices on the canvas. This class manages positioning of the popup and provision of the current vertex, but not the display of the popup itself, which is delegated to the library integrations
+ */
+export declare class PopupHandler {
+    _current: ViewportElement<any> | null;
+    _anchor: PopupPosition;
+    _defaultAnchor: PopupPosition;
+    setCurrent: (v: Vertex | null) => any;
+    container: BrowserElement;
+    surface: Surface;
+    _cleanup: () => void;
+    private _doSetCurrent;
+    constructor(selector: string, container: BrowserElement, surface: Surface, setCurrent: (v: Vertex | null) => any, anchor?: PopupPosition);
+    $destroy(): void;
+    /**
+     * Sets the current object to null, which hides the popup
+     */
+    $hide(): void;
+    /**
+     * @internal
+     */
+    $positionPopup(): void;
+}

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

@@ -0,0 +1,4 @@
+import { PointXY, Size } from "../../../core";
+import { ViewportElement } from "../../../ui";
+import { Surface } from "../surface";
+export declare function computeOrigin(anchor: string, referenceElement: ViewportElement<any>, popupSize: Size, surface: Surface): PointXY;

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

@@ -412,6 +412,11 @@ export declare class Surface extends BrowserUI<SurfaceEvents> implements Support
      * Gets the current bounds information.
      */
     getViewportBoundsInfo(): ViewportBounds;
+    /**
+     * Surface does not have fixed viewport bounds.
+     * @internal
+     */
+    $getFixedViewportBoundsInfo(): ViewportBounds | null;
     getApparentCanvasLocation(): PointXY;
     /**
      * Adds a background. Theoretically you can add multiple backgrounds but the end result of that is indeterminate.
@@ -508,21 +513,22 @@ export declare class Surface extends BrowserUI<SurfaceEvents> implements Support
      *
      */
     setPanAndZoom(x: number, y: number, zoom: number, animate?: boolean): void;
+    private __findBoundsForElements;
     /**
-     * Center on the current object and zoom in on it.
-     * @param element - The element to center. Can be a DOM element, vertex id, or a Node/Group
+     * Center on the current object/objects and zoom in on it/them.
+     * @param element - The element(s) to center. Can be a DOM element, vertex id, or a Node/Group, or an array of these.
      * @param fillRatio How much of the viewport to fill with the object we zoom in on. This will be limited by the current zoom range. Defaults to 0.6.
      * @param doNotAnimate - by default, this operation will be animated.
      * @canvasPosition
      *
      */
-    centerOnAndZoom(element: string | Vertex | Element, fillRatio?: number, doNotAnimate?: boolean): void;
+    centerOnAndZoom(element: string | Vertex | Element | Array<string | Vertex | Element>, fillRatio?: number, doNotAnimate?: boolean): void;
     /**
-     * Takes a node/group as argument and positions the surface canvas such that the given node is at the center in both axes.
-     * @param element - The element to center. Can be a DOM element, vertex id, or a Node/Group.
+     * Takes a single node/group, or an array of nodes/groups, and positions the surface canvas such that the given vertex/vertices is/are at the center in both axes. It does NOT change the zoom.
+     * @param element - The element(s) to center. Can be a DOM element, vertex id, or a Node/Group, or an array of these.
      * @canvasPosition
      */
-    centerOn(element: string | Vertex | Element): void;
+    centerOn(element: string | Vertex | Element | Array<string | Vertex | Element>, doNotAnimate?: boolean): void;
     /**
      * Takes a node/group as argument and positions the surface canvas such that the given node is at the center in the horizontal axis.
      * @param element - The element to center. Can be a DOM element, vertex id, or a Node/Group
@@ -574,13 +580,20 @@ export declare class Surface extends BrowserUI<SurfaceEvents> implements Support
      */
     fromWindowLocation(left: number, top: number, roundValues?: boolean): PointXY;
     /**
-     * Maps the given location relative to the viewport origin, to a page location, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner.
+     * Maps the given canvas location to a page location, allowing for zoom and pan of the canvas. Note that `page` in this method takes scroll into account. If you wish to map to just the visible section of the browser, use `toWindowLocation`.
      * @param left X location
      * @param top Y location
      * @returns The mapped location, as a PointXY object.
-     *
      */
     toPageLocation(left: number, top: number): PointXY;
+    /**
+     * Maps the given canvas location to a point, in page coordinates, relative to the surface container's origin. A return value of [0,0] from this method indicates the top left corner of the surface's container as seen by the user; negative values for x and/or y mean that the point is not in the visible viewport. Similarly, values for x greater the container width, or y greater than the container height, indicate that the point is not in the visible viewport.
+     *
+     * This method is useful when you want to position an element over the canvas at some specific canvas location. For instance, the SurfacePopup components use this to position themselves relative to the vertex they are currently referencing.
+     * @param left
+     * @param top
+     */
+    toViewportLocation(left: number, top: number): PointXY;
     /**
      * Binds to a mouse event occurring on a given model object. This is a wrapper around the `on` event binding method, which searches for an associated model object for the given event. For instance, you might have a node template that has a button inside of it that you want to respond to. When the button is clicked you want to know the node associated with the button. This method provides that. It is possible to find the associated model object yourself, via the `getObjectInfo` method of the Surface, called with the event's target, but this method does that for you.
      *
@@ -634,7 +647,7 @@ export declare class Surface extends BrowserUI<SurfaceEvents> implements Support
     /**
      * Appends an element to the viewport so that it floats above the content that is being zoomed and panned. The element will have `position:absolute` set on it. You can float any element you like, but note that the responsibility for setting an appropriate z index is yours.
      * @param el Element to float.
-     * @param pos Position to float the element at.
+     * @param pos Position to float the element at. This is in page coordinates, ie. it ignores the pan/zoom of the surface, and defines a position relative to the viewport's top/left corner.
      *
      */
     floatElement(el: BrowserElement, pos: PointXY): void;

package/types/core/geom.d.ts

@@ -209,10 +209,16 @@ export declare function linesOverlap(line1Point1: number, line1Point2: number, l
  */
 export declare function expandRectangle<T extends RectangleXY>(r: RectangleXY, deltaX: number, deltaY: number): T;
 /**
- * Find the intersection point of the two lines, which are treated as being of
- * unlimited length, ie. if both lines are of non-zero length and are not parallel, then
- * an intersection point is always returned even if they do not actually meet: their projections meet
- * at the point this method returns.
+ * Computes the bounding box union of two RectangleXY objects.
+ * This operation returns a new RectangleXY that is large enough to encompass both input rectangles.
+ *
+ * @param rect1 The first RectangleXY object.
+ * @param rect2 The second RectangleXY object.
+ * @returns A new RectangleXY object representing the union of the two input rectangles.
+ */
+export declare function unionOfRectangles(rect1: RectangleXY, rect2: RectangleXY): RectangleXY;
+/**
+ * Find the intersection point of the two lines, which are treated as being of unlimited length, ie. if both lines are of non-zero length and are not parallel, then an intersection point is always returned even if they do not actually meet: their projections meet at the point this method returns.
  * @param l1
  * @param l2
  * @internal

package/types/core/params.d.ts

@@ -144,7 +144,7 @@ export interface GroupAddedParams {
  * @group Events
  * @category Payloads
  */
-export interface GroupRemovedParams {
+export interface GroupRemovedParams extends VertexRemovedParams {
     /**
      * Group that was removed
      */
@@ -157,12 +157,24 @@ export interface GroupRemovedParams {
      * If children were removed, this is the list of them
      */
     children: Array<Node | Group>;
+}
+/**
+ * Base payload for a vertex removed event in the model
+ * @group Events
+ * @category Payloads
+ */
+export interface VertexRemovedParams {
+    vertex: Node | Group;
+    /**
+     * List of edges that are being removed as a result of this vertex's removal.
+     */
+    edges: Array<Edge>;
     /**
-     * If the group was a member of some other group, that group is provided here
+     * If the vertex was a member of some other group, that group is provided here
      */
     parentGroup?: Group;
     /**
-     * Indicates that the group is being removed because some parent group is being removed and is forcing removal of its children.
+     * Indicates that the vertex is being removed because some parent group is being removed and is forcing removal of its children.
      */
     parentGroupIsBeingRemoved: boolean;
 }
@@ -171,23 +183,11 @@ export interface GroupRemovedParams {
  * @group Events
  * @category Payloads
  */
-export interface NodeRemovedParams {
+export interface NodeRemovedParams extends VertexRemovedParams {
     /**
      * Node that was removed
      */
     node: Node;
-    /**
-     * List of edges that are being removed as a result of this node's removal.
-     */
-    edges: Array<Edge>;
-    /**
-     * If the node was a member of some other group, that group is provided here
-     */
-    parentGroup?: Group;
-    /**
-     * Indicates that the node is being removed because some parent group is being removed and is forcing removal of its children.
-     */
-    parentGroupIsBeingRemoved: boolean;
 }
 /**
  * Payload for a vertex updated event.

package/types/core/search/visuallyjs-search.d.ts

@@ -88,11 +88,10 @@ export interface IndexEntry {
     key: string;
 }
 /**
- * Index for a dataset
+ * Reverse text index (think Lucene). This class operates on arbitrary Javascript objects and offers a method to search the fields of all documents. By default every field is searched, but you can control which fields to search via the options you pass to the constructor.
  * @group Search
- * @internal
  */
-declare class DatasetIndex {
+export declare class DatasetIndex {
     fields: Array<string>;
     root: IndexEntry;
     tokenizer: Tokenizer;
@@ -145,10 +144,10 @@ export type SearchResults = {
     ports: Array<Port>;
 };
 /**
- * Search index.
+ * Search index for a Graph. This class wraps 4 indexes - one each for nodes, groups, ports and edges, and exposes a search method that searches across each of the indexes. By default every field in the data objects is searched, but you can control that via the options you pass to the constructor.
  * @group Search
  */
-export declare class Index {
+export declare class GraphSearchIndex {
     instance: VisuallyJsModel;
     nodeIndex: DatasetIndex;
     groupIndex: DatasetIndex;
@@ -164,4 +163,3 @@ export declare class Index {
      */
     search(value: string): SearchResults;
 }
-export {};

package/types/core/toolkit.d.ts

@@ -63,11 +63,11 @@ export type BeforeStartDetachInterceptor = (source: Vertex, edge: Edge) => Recor
  */
 export interface ModelOptions {
     /**
-     * The name of a property that will exist inside the backing data for nodes/group, and which represents a list of ports pertaining to that node/group. When a node/group is rendered, if this property is set, VisuallyJs will consider the value of this property to be a list of port data object. So this property's value should be of type `Array<ObjectData>`
+     * The name of a property that will exist inside the backing data for nodes/group, and which represents a list of ports pertaining to that node/group. When a node/group is rendered, if this property is set, VisuallyJs will consider the value of this property to be a list of port data objects. So this property's value should be of type `Array<ObjectData>`. Note that this mechanism is fine for models where either all vertex types that have ports have them keyed with the same property, or you only have a single vertex type with ports, but for more advanced setups you should look at the `portExtractor` function.
      */
     portDataProperty?: string;
     /**
-     * The name of a property inside of each port's data that can be used to order the ports. For instance, you might have ports that have a `rank` property, which is a number. VisuallyJs will sort the ports according to the natural ordering of this property.
+     * The name of a property inside of each port's data that can be used to order the ports. For instance, you might have ports that have a `rank` property, which is a number. VisuallyJs will sort the ports according to the natural ordering of this property. Note that this mechanism is fine for models where either all vertex types that have ports have them keyed with the same property, or you only have a single vertex type with ports, but for more advanced setups you should look at the `portUpdated` function.
      */
     portOrderProperty?: string;
     model?: DataModelDefinition;
@@ -235,11 +235,13 @@ export interface ModelOptions {
     /**
      * A function to use to extract an array of ports from the data representing some node/group. Whenever a node/group is rendered, VisuallyJs will use this method, if provided, to determine a list of ports for that node/group. If you use this you probably also want to define a `portUpdater`. Note that if you provide the `portDataProperty` then you do not need to set this.
      */
-    portExtractor?: (o: ObjectData) => Array<ObjectData>;
+    portExtractor?: (o: ObjectData, nodeOrGroup: Node | Group) => Array<ObjectData>;
     /**
-     * A function to use to update a given node/group's list of ports. Note that if you provide the `portDataProperty` then you do not need to set this.
+     * A function to use to update a given node/group's list of ports. This function should return a Javascript object which represents the node/group's backing data. This method is invoked whenever changes to some vertex's ports occur.
+     *
+     * Note that if you provide the `portDataProperty` then you do not need to set this.
      */
-    portUpdater?: Function;
+    portUpdater?: (data: ObjectData, nodeOrGroup: Node | Group, ports: Array<Port>) => ObjectData;
     /**
      * Optional model event mappings to bind
      */
@@ -406,8 +408,8 @@ export declare abstract class VisuallyJsModel extends OptimisticEventGenerator i
     edgeTypeFunction: TypeFunction;
     portIdFunction: IdFunction;
     portTypeFunction: TypeFunction;
-    portExtractor: Function;
-    portUpdater: Function;
+    portExtractor: (o: ObjectData, nodeOrGroup: Node | Group) => Array<ObjectData>;
+    portUpdater: (data: ObjectData, nodeOrGroup: Node | Group, ports: Array<Port>) => ObjectData;
     portDataProperty: string;
     portOrderProperty: string;
     modelTopAttribute: string;

package/types/core/util.d.ts

@@ -362,6 +362,11 @@ export declare function isDate(o: any): o is Date;
  * @internal
  */
 export declare function isFunction(o: any): o is Function;
+/**
+ * return whether or not the given value is a Class
+ * @param o
+ */
+export declare function isClass(o: any): boolean;
 /**
  * Returns whether or not the given value is of type `Function` and is a named Function.
  * @param o

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

@@ -23,6 +23,13 @@ export declare const ATTRIBUTE_MANAGED = "data-vjs-managed";
  * @context element-dragging
  */
 export declare const ATTRIBUTE_NOT_DRAGGABLE = "data-vjs-not-draggable";
+/**
+ * This attribute can be written onto DOM elements by node/group renderers to instruct VisuallyJs that the given element should not cause mouse events for the given vertex to be fired.
+ * @group Nodes and Groups
+ * @category DOM Attributes
+ * @domAttribute
+ */
+export declare const ATTRIBUTE_SUPPRESS_VERTEX_EVENTS = "data-vjs-no-events";
 /**
  * Written by the Surface when `elementsDraggable` is provided as a constructor option. The value of this attribute will match what you provide for `elementsDraggable`, but it's really only of any use if you set it to `false`, as `true` is the default.
  * @internal

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

@@ -643,6 +643,10 @@ export declare abstract class UICore<EL, EVT = CoreUIEvent> extends OptimisticEv
      * Gets the current bounds of the UI's viewport.
      */
     abstract getViewportBoundsInfo(): ViewportBounds;
+    /**
+     * If the UI has a fixed viewport (not panning, zooming etc), it can opt to return a value from this method. A background can use this information to place itself.
+     */
+    abstract $getFixedViewportBoundsInfo(): ViewportBounds | null;
     abstract getApparentCanvasLocation(): PointXY;
     abstract toFront(v: string | Vertex | EL, alsoBringAncestorsToFront?: boolean): void;
     abstract toBack(v: string | Vertex | EL, alsoSendAncestorsToBack?: boolean): void;

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

@@ -102,6 +102,10 @@ export type VertexDragFilter<E> = (p: {
  * @category Definitions
  */
 export type DragConstrainFunction<E> = (desiredLoc: PointXY, dragEl: E, modelObject: Node | Group, size: Size, currentLoc: PointXY, e: MouseEvent) => PointXY;
+/**
+ * Strategy for determining whether something that is moving is considered out of bounds. Options are 'contained', ie the element must be fully contained inside the root bounds, or 'intersecting', ie. the element must intersect the root bounds by some amount. Prior to 1.1.4 the behaviour was 'contained', but a change in 1.1.4 switched this to 'intersecting', which does not necessarily provide the best UX when the canvas is hard up against the edge of the screen, because it isnt always possible to move the mouse far enough that the element is not intersecting, and in those situations panning stops. From 1.2.1 onwards the default is once again `contained`, but you can change that via the `autoPanBoundsStrategy` option on the surface's dragOptions.
+ */
+export type AutoPanBoundsStrategy = "contained" | "intersecting";
 /**
  * Options for element drag
  * @group UI
@@ -136,6 +140,10 @@ export interface DragOptions<E> {
      * When auto-panning, this is the number of pixels that the canvas repositions itself on each tick. Defaults to 5.
      */
     autoPanDelta?: number;
+    /**
+     * When auto-panning, this flag instructs the auto pan how to determine if an element is inside the root bounds or not. A value of "contained" (the default), means the whole element has to be inside the root bounds. A value of "intersecting" means that the element needs to just intersect the root bounds by some amount.
+     */
+    autoPanBoundsStrategy?: AutoPanBoundsStrategy;
     /**
      * 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
@@ -164,6 +172,7 @@ export interface SupportsElementDragging<E> {
     $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;
+    addVertexDragFilter(f: VertexDragFilter<E>): void;
 }
 /**
  * Payload for the node:move:start event that is fired when a node/group has just begun to be moved.

package/types/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.2.0";
+export declare const VERSION = "1.2.1";