@visuallyjs/browser-ui 1.1.4 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visuallyjs/browser-ui",
-  "version": "1.1.4",
+  "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/charts/sankey/sankey.d.ts

@@ -175,7 +175,7 @@ export declare class SankeyChart extends BaseChart {
         csvData?: string;
         dataType?: string;
         jsonData?: VisuallyJsDefaultJSON;
-    }): void;
+    }, onload?: () => any): void;
     hasData(): boolean;
     destroy(): void;
     private _clearVertex;

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/layout/circular/circular-layout.d.ts

@@ -11,14 +11,19 @@ export interface CircularLayoutParameters extends LayoutParameters {
      * If true, the first node in the data set will be placed in the center of the circle. Defaults to false.
      */
     centerRoot?: boolean;
+    /**
+     * Whether or not to shift the layout so that the origin is [width/2, height/2] and not [0,0]. This is useful in situations such as groups, where elements cannot be placed in a negative position in either axis (due to there being no facility to pan the group canvas)
+     */
+    centerContent?: boolean;
 }
 /**
- * A layout that places vertices in a circle, optionally with one at the center.
+ * A layout that places vertices in a circle, optionally with one at the center, and optionally centered around [width/2, height/2] (the default origin is 0,0).
  * @group Layouts
  * @category Circular
  */
 export declare class CircularLayout extends AbstractLayout<CircularLayoutParameters> {
     private readonly _centerRoot;
+    private readonly _centerContent;
     static type: string;
     readonly type: string;
     padding: PointXY;

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/selection.d.ts

@@ -66,7 +66,7 @@ export interface SelectionOptions {
     /**
      * Optional function that can be called to fill the selection. You'd use this when you are rendering individual selections and you need to be able to refresh the whole view based on some change in the data model.
      */
-    generator?: Function;
+    generator?: SelectionGenerator;
     /**
      * If true, the selection will not populate itself as soon as it is constructed. Otherwise, and this is the default behaviour, it will.
      */
@@ -82,6 +82,10 @@ export interface SelectionOptions {
  * @category Selection
  */
 export type SELECTION_EVENTS = typeof EVENT_EDGE_UPDATED | typeof EVENT_DATA_LOAD_END | typeof EVENT_DATA_LOAD_START | typeof EVENT_NODE_UPDATED | typeof EVENT_GRAPH_CLEAR_START | typeof EVENT_GROUP_UPDATED | typeof EVENT_PORT_UPDATED | typeof EVENT_EDGE_TARGET_CHANGED | typeof EVENT_EDGE_SOURCE_CHANGED | typeof EVENT_EDGE_REMOVED | typeof EVENT_EDGE_ADDED | typeof EVENT_GROUP_REMOVED | typeof EVENT_NODE_REMOVED | typeof EVENT_GROUP_ADDED | typeof EVENT_NODE_ADDED;
+/**
+ * Defines a function that can be used as the generator for a selection.
+ */
+export type SelectionGenerator = (s: VisuallyJsSelection, m: VisuallyJsModel) => any;
 /**
  * A selection is a group of vertices and edges, upon which you can perform bulk operations.
  * @group Model
@@ -97,7 +101,7 @@ export declare class VisuallyJsSelection extends OptimisticEventGenerator implem
     _groups: Array<Group>;
     _edges: Array<Edge>;
     capacityPolicy: string;
-    generator: Function;
+    generator: SelectionGenerator;
     onReload: Function;
     onBeforeReload: Function;
     onClear: Function;

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
      */
@@ -248,6 +250,11 @@ export interface ModelOptions {
      * Optional map of group templates to register on the model.
      */
     groupTemplates?: Record<string, GroupTemplate>;
+    /**
+     * The name of the property inside nodes/groups that identifies their parent group. This defaults to "group" but
+     * can be changed if it clashes with your data model.
+     */
+    groupProperty?: string;
 }
 /**
  * Definition of a model event callback.
@@ -395,13 +402,14 @@ export declare abstract class VisuallyJsModel extends OptimisticEventGenerator i
     typeProperty: string;
     edgeTypeProperty: string;
     portTypeProperty: string;
+    groupProperty: string;
     typeFunction: TypeFunction;
     edgeIdFunction: IdFunction;
     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;