@visuallyjs/browser-ui 1.0.0

package/types/core/magnetizer.d.ts

@@ -0,0 +1,232 @@
+import { HasId } from "./model/graph";
+import { PointXY, Size, BoundingBox, Grid } from "./util";
+/**
+ * Result value from a run of a {@link Magnetizer}.
+ * @group Components
+ * @category Magnetizer
+ */
+export type MagnetizeResult = {
+    /**
+     * Original positions of elements
+     */
+    original: Record<string, PointXY>;
+    /**
+     * New positions for elements.
+     */
+    current: Record<string, PointXY>;
+};
+/**
+ * Options for a run of a {@link Magnetizer}
+ * @group Components
+ * @category Magnetizer
+ */
+export interface MagnetizerRunOptions<T> {
+    /**
+     * Element to use as the focus for the magnetize operation. This means its center will be the focus point, and also that it will not be moved
+     */
+    focus?: string;
+    /**
+     * Optional set of known locations for elements that we want to use. We use this when provisionally setting some element's position - we want to use a new value rather than the current position.
+     * @internal
+     */
+    knownLocations?: Record<string, PointXY>;
+    /**
+     * Optional set of known sizes for elements that we want to use.
+     * @internal
+     */
+    knownSizes?: Record<string, Size>;
+    /**
+     * Optional value for the padding to leave between elements. Defaults to 20 pixels in each axis.
+     */
+    padding?: PointXY;
+    /**
+     * Optional origin to use for magnetization process. If not provided, the computed center of the all elements to be magnetized will be used instead.
+     */
+    origin?: PointXY;
+    /**
+     * List of elements to magnetize. If not provided, the magnetizer's current element list is used.
+     */
+    elements?: Record<string, T> | Array<T>;
+    /**
+     * Optional function used to filter elements from being affected by the magnetizer. They are still taken into account when magnetizing the other elements, unless you set `excludeFocus:true`.
+     */
+    filter?: FilterFunction<T>;
+    /**
+     * Number of iterations to run for.  More iterations takes longer but does better magnetizing.
+     */
+    iterations?: number;
+    /**
+     * Optional function used to determine which elements to completely exclude from the magnetizer - they are treated as if they do not exist, and other elements may end up positioned intersecting them.
+     */
+    exclude?: FilterFunction<T>;
+    /**
+     * Defaults to false. If true, the magnetizer works in reverse: elements are gathered together (without overlapping)
+     */
+    gather?: boolean;
+    /**
+     * Optional function used to constrain the movement of elements when the magnetizer is being applied.
+     */
+    constrain?: MagnetizerConstrainFunction;
+    /**
+     * Optional grid to constrain movement to.
+     */
+    grid?: Grid;
+    /**
+     * @internal
+     * @param el
+     */
+    getPosition?: (el: T) => PointXY;
+    /**
+     * @internal
+     * @param el
+     */
+    getSize?: (el: T) => Size;
+    /**
+     * Threshold beyond which the magnetizer will not attempt to track some element back to its original position. In some cases a user might want to push an element using the magnetizer and have the changes stick. Defaults to Infinity.
+     */
+    trackbackThreshold?: number;
+    /**
+     * If this is set, the magnetizer will not run trackbacks this time it is run.
+     */
+    invertTrackbackPreference?: boolean;
+}
+/**
+ * Options for {@link Magnetizer} configuration.
+ * @group Components
+ * @category Magnetizer
+ * @internal
+ */
+export interface MagnetizerOptions<T> {
+    /**
+     * List of elements to magnetize. If not provided, the magnetizer's current element list is used.
+     */
+    elements?: Record<string, T> | Array<T>;
+    container?: any;
+    getSize: (el: T) => Size;
+    getId: (el: T) => string;
+    positionGetter: (el: T) => PointXY;
+    positionSetter: (el: T, p: PointXY) => any;
+    /**
+     * Optional function used to constrain the movement of elements when the magnetizer is being applied.
+     */
+    constrain?: MagnetizerConstrainFunction;
+    /**
+     * Optional function used to filter elements from being affected by the magnetizer. They are still taken into account when magnetizing the other elements, unless you set `excludeFocus:true`.
+     */
+    filter?: FilterFunction<T>;
+    /**
+     * Optional function used to determine which elements to completely exclude from the magnetizer - they are treated as if they do not exist, and other elements may end up positioned intersecting them.
+     */
+    exclude?: FilterFunction<T>;
+}
+export declare function calculateSpacingAdjustment(r1: BoundingBox, r2: BoundingBox): PointXY;
+export type MagnetizerConstrainFunction = (id: string, current: PointXY, delta: PointXY) => PointXY;
+export type FilterFunction<T> = (id: string, v: T) => boolean;
+/**
+ * Offers a means to apply 'magnetization' to some list of elements, pushing them apart so that they do not overlap. For a given run of the magnetizer there is the concept of a "focus" rectangle. The center of this rectangle is the point from which magnetization occurs, with elements being pushed out radially from this point. There are a few different scenarios:
+ *
+ * - execute magnetizer with a given origin, and affect all elements
+ * - execute magnetizer on all elements, having first computed the center of them
+ * - execute magnetizer using a specific element as the focus
+ *
+ * @group Components
+ */
+export declare class Magnetizer<T extends HasId> {
+    private _origin;
+    private _elements;
+    private readonly _constrain;
+    private readonly _filter;
+    private readonly _exclude;
+    private _focusElement;
+    private readonly _defaultGetSize;
+    private readonly _getId;
+    private readonly _defaultGetPosition;
+    private readonly _positionSetter;
+    private _positionArray;
+    private _positions;
+    private _originalPositions;
+    private _trackedPositions;
+    private _trackedMovements;
+    private _tracking;
+    private _trackbackThreshold;
+    private _sizes;
+    constructor(params: MagnetizerOptions<T>);
+    /**
+     * Run the magnetizer using the specified origin.
+     * @param origin
+     * @param options
+     */
+    executeAtPoint(origin: PointXY, options?: MagnetizerRunOptions<T>): MagnetizeResult;
+    /**
+     * Run the magnetizer using an origin computed to be the center of all elements.
+     * @param options
+     */
+    executeAtCenter(options?: MagnetizerRunOptions<T>): MagnetizeResult;
+    /**
+     * Run the magnetizer with the given element as its focus - the focus element will not be shifted.
+     * @param focus
+     * @param options
+     */
+    executeWithFocus(focus: string, options?: MagnetizerRunOptions<T>): MagnetizeResult;
+    /**
+     * Snaps all elements to a grid. Returns a map of element IDs, representing all the elements that were moved.
+     * @param grid
+     */
+    snapToGrid(grid: Grid): MagnetizeResult;
+    setElements(_els: Array<T>): Magnetizer<T>;
+    startTracking(_els: Array<T>, attemptTrackback: boolean, trackbackThreshold: number): Magnetizer<T>;
+    stopTracking(): void;
+    addElement(el: T, doNotTestForDuplicates?: boolean): this;
+    addElements(els: Array<T>, doNotTestForDuplicates?: boolean): this;
+    removeElement(el: T): Magnetizer<T>;
+    reset(): void;
+    private _setOrigin;
+    private _updatePositions;
+    private _computeExtents;
+    /**
+     * Attempt to track the given element back from its current position
+     * to its original position. We draw a line from the current center
+     * to the original center and divide it into a number of steps of roughly
+     * 10 pixels. Then we traverse that center line - from the current position -
+     * and check for overlap at each location. As soon as there is overlap we stop,
+     * and use the furthest point we managed to get to, updating _movedElements
+     * at the same time. If we get all the way to the final position without encountering
+     * any obstructions we remove the id from _trackedPositions, as it is now
+     * back in its original spot.  Note that we do not start testing for
+     * obstructions in the original location - because it would be possible
+     * for an element to appear to pass right through other elements. To make
+     * the effect natural it has to work in the way that elements cannot traverse
+     * back to their original position as long as there is something obstructing the path.
+     * @param id
+     * @private
+     */
+    private _attemptTrackBack;
+    /**
+     * If we're in `trackinq` mode and there are some elements that are not in the position they were
+     * in at the start of tracking, attempt to track elements back to their original positions. The approach is
+     * to cycle through each moved element one at a time and attempt to track it back to its original position.
+     * That operation will either be 1) wholly successful, in which case we remove that element from our
+     * Set of elements that have moved and update the stored position, as well as add that element to
+     * the map of moved elements; 2) partially successful, in which we case we store the new position and add
+     * the element to movedElements, or 3) not successful at all. We run a while loop, inside of which we
+     * repeatedly iterate the trackedElements set and try to reposition the items. If we get a run where
+     * none of the tracked elements were moved then that's the end of this attempt, and we exit. This approach
+     * allows us to not have to worry about the order in which elements were moved from their original
+     * position, as we incrementally push them all back.
+     * @internal
+     * @param _movedElements
+     * @param p
+     * @param e
+     * @param g
+     */
+    private _runTrackbacks;
+    private _run;
+    private _gather;
+    private _magnetize;
+    private _positionElements;
+    /**
+     * Sort the elements by their distance from the origin. note that right now this is the distance from a point, but ideally this distance would be from the element to the focus, which can be an element. keep that in mind when doing the other gather cases. This sort routine tests each corner of each element, and uses the corner that is closest to the origin as that element's distance from the origin.
+     * @private
+     */
+    private _sortPositionsByDistanceFromOrigin;
+}

package/types/core/model/anchor.d.ts

@@ -0,0 +1,38 @@
+/**
+  * Definition of an Anchor. This is the type that VisuallyJs converts all others to internally.
+  * @group Edges
+  */
+export type ObjectAnchorSpec = {
+    /**
+     * Location of the anchor in the X axis as a proportion of the element's width
+     */
+    x: number;
+    /**
+     * Location of the anchor in the Y axis as a proportion of the element's width
+     */
+    y: number;
+    /**
+     * Orientation of the anchor in the X axis.
+     */
+    ox: AnchorOrientationHint;
+    /**
+     * Orientation of the anchor in the Y axis.
+     */
+    oy: AnchorOrientationHint;
+    /**
+     * Optional offset to apply to the anchor position in the X axis after computing it via the `x` property. This value is in canvas coordinates.
+     */
+    offsetX?: number;
+    /**
+     * Optional offset to apply to the anchor position in the Y axis after computing it via the `y` property. This value is in canvas coordinates.
+     */
+    offsetY?: number;
+    /**
+     * Optional port ID to associate with this anchor.
+     */
+    portId?: string;
+};
+/**
+ * Hints for anchor orientation: -1 means "go backwards in this axis", 0 means no preference, and 1 means "go forwards in this axis".
+ */
+export type AnchorOrientationHint = -1 | 0 | 1;

package/types/core/model/cluster.d.ts

@@ -0,0 +1,19 @@
+import { Edge, Vertex } from "./graph";
+/**
+ * Models a group of vertices that, in some context, belong together. The determination of the context is up to the call site.
+ * @group Data Model
+ * @category Graph Objects
+ */
+export declare class Cluster {
+    /**
+     * Vertices in the cluster
+     */
+    vertices: Array<Vertex>;
+    private _edges;
+    constructor(seed: Vertex);
+    addVertex(v: Vertex): void;
+    /**
+     * Edges in the cluster
+     */
+    get edges(): Array<Edge>;
+}

package/types/core/model/defs.d.ts

@@ -0,0 +1,8 @@
+import { Edge, Group, Node, Vertex } from "./graph";
+export interface IGraph {
+    nodes: Array<Node>;
+    id: string;
+    edges: Array<Edge>;
+    groups: Array<Group>;
+    getVertex(id: string): Vertex;
+}

package/types/core/model/djikstra.d.ts

@@ -0,0 +1,26 @@
+import { Vertex, Edge } from "./graph";
+import { IGraph } from "./defs";
+export interface DjikstraOptions {
+    graph: IGraph;
+    source: Vertex;
+    target: Vertex;
+    sourceId?: string;
+    targetId?: string;
+    nodeFilter?: Function;
+    edgeFilter?: Function;
+    processAll?: boolean;
+    strict?: boolean;
+}
+export interface ShortestPathComponent {
+    vertex: Vertex;
+    cost: number;
+    edge: Edge;
+}
+export interface ShortestPathResult {
+    path?: Array<ShortestPathComponent>;
+    pathDistance?: number;
+    dist?: Record<string, number>;
+    edges?: Record<string, Edge>;
+    previous?: Record<string, Vertex>;
+}
+export declare function djikstra(params: DjikstraOptions): ShortestPathResult;

package/types/core/model/floyd-warshall.d.ts

@@ -0,0 +1,15 @@
+import { Graph, Vertex } from "./graph";
+export interface FloydWarshallOptions {
+    graph: Graph;
+    focus?: Vertex;
+}
+export interface FloydWarshallResult {
+    paths: any;
+    parents: any;
+}
+/**
+ * Implementation of the Floyd-Warshall algorithm, which finds the shortest paths between all pairs of vertices in a weighted graph.
+ * @param params
+ * @group Data Model
+ */
+export declare function floydWarshall(params: FloydWarshallOptions): FloydWarshallResult;