@visuallyjs/browser-ui 1.0.0

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

@@ -0,0 +1,185 @@
+import { DiagonalAxis, OrthogonalAxis, PATH_CONSTRAIN_DIAGONAL, PATH_CONSTRAIN_MANHATTAN, PATH_CONSTRAIN_METRO, PATH_CONSTRAIN_NONE, PATH_CONSTRAIN_ORTHOGONAL } from "../constants";
+export type DistanceHeuristic = (x1: number, y1: number, x2: number, y2: number) => number;
+/**
+ * A segment in an a* path
+ * @internal
+ */
+export interface AStarPathSegment {
+    ax1: number;
+    ay1: number;
+    ax2: number;
+    ay2: number;
+    axis: ParentAxis;
+    pathId: string;
+}
+/**
+ * An A* path.
+ * @internal
+ */
+export interface AStarPath {
+    id: string;
+    segments: Array<AStarPathSegment>;
+    targetCell: PathFinderGridCell;
+    sourceCell: PathFinderGridCell;
+    isEmpty: boolean;
+}
+/**
+ * A cell in an A* grid.
+ * @internal
+ */
+export interface PathFinderGridCell {
+    key: string;
+    f: number;
+    g: number;
+    h: number;
+    opened: boolean;
+    closed: boolean;
+    hasSourceObstacles: boolean;
+    hasTargetObstacles: boolean;
+    /**
+     * list of obstacles that intersect this cell. The elements in this array are the
+     * core obstacles, without buffer.
+     */
+    obstacles: Array<string>;
+    /**
+     * list of buffer zones that intersect this cell. for a given vertex at [50,50] with size [50,50],
+     * for example, if we say our obstacle padding is 20 pixels, then there would be a corresponding
+     * buffer in this array at [30,30] with size [90,90]. it is helpful to distinguish between the core
+     * size of obstacles and that of their buffers, because in some cases we want to treat buffers
+     * differently. For instance, when approaching the source/target of some path, we may want to travel
+     * through its buffer zone. It wouldnt be our preference, but we could sort buffer zone candidates
+     * below non buffer zone candidates, while still rejecting candidates that are in the core of
+     * the obstacle.  Also, when smoothing a path that is not constrained orthogonal, if we use the
+     * theta* approach of following line of sight, we may want to allow line of sight to travel through
+     * buffer zones, as this can reduce the number of turns - but we dont want line of sight to travel
+     * through obstacles themselves of course.
+     *
+     * For obstacles that lie in the middle of our path we want to avoid the obstacles _and_ its buffer
+     * zone completely, and I'm hoping that the candidate sorting approach will do that. I won't know
+     * until I've done the code though.
+     */
+    buffers: Array<string>;
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+    parent: PathFinderGridCell;
+    directionFromParent: DirectionFromParent;
+    /**
+     * For start and end nodes, which may have a null parent. This axis determines the direction the path should take
+     * when entering/leaving, and is derived from the associated anchor's orientation.
+     */
+    fixedAxis: ParentAxis;
+    ax: number;
+    ay: number;
+}
+/**
+ * Constant defining an empty path
+ * @internal
+ */
+export declare const EMPTY_ASTAR_PATH = "empty";
+/**
+ * The axis of travel from some parent cell to a child.
+ * @internal
+ */
+export type ParentAxis = DiagonalAxis | OrthogonalAxis | undefined;
+/**
+ * Direction of travel from some parent cell to a child. 1 means travelling in the positive direction for the axis of
+ * travel, and that of course depends on the axis.  -1 means travelling in the negative direction for the axis. 0 means the
+ * child has the same value as the parent.
+ * @internal
+ */
+export type DirectionFromParent = -1 | 1 | 0;
+/**
+ * Models an adjacent cell during the path finding phase
+ * @internal
+ */
+export type AdjacentCell = {
+    dx: number;
+    dy: number;
+    axis: ParentAxis;
+    directionFromParent: DirectionFromParent;
+};
+/**
+ * Models a list of adjacent cells during the path finding phase.
+ * @internal
+ */
+export type AdjacentCells = Array<AdjacentCell>;
+/**
+ * Models a function that can find adjacent cells given a cell x/y, an axis of travel, and a direction of travel.
+ * @internal
+ */
+export type AdjacentCellsFinder = (x: number, y: number, pa: ParentAxis, pd: DirectionFromParent) => AdjacentCells;
+/**
+ * List of adjacent cells in horizontal, vertical and diagonal directions.
+ * @internal
+ */
+export declare const freeMovementAdjacencies: Array<AdjacentCell>;
+/**
+ * List of adjacent cells in horizontal and vertical directions only
+ * @internal
+ */
+export declare const orthogonalAdjacencies: Array<AdjacentCell>;
+/**
+ * Finder for adjacent orthogonal cells. Finds all cells from orthogonalAdjacencies except the cell that is the previous
+ * cell on the current path.
+ * @param x
+ * @param y
+ * @param pa
+ * @param pd
+ * @internal
+ */
+export declare const orthogonalAdjacentCellsFinder: AdjacentCellsFinder;
+/**
+ * Finder for adjacent cells in any direction. Finds all cells from freeMovementAdjacencies except the cell that is the previous
+ * cell on the current path.
+ * @param x
+ * @param y
+ * @param axis
+ * @param direction
+ * @internal
+ * commenting this out prior to 6.90.0, it doesnt seem necessary.
+ */
+/**
+ * Finder for adjacent cells when constrain is diagonal. Finds all cells from freeMovementAdjacencies that are either
+ * in a straight line with the current path, or at a 45 degree turn (and omits the cell that is the previous
+ * cell on the current path)
+ * @param x
+ * @param y
+ * @param axis
+ * @param direction
+ * @internal
+ */
+export declare const diagonalAdjacentCellsFinder: (x: number, y: number, axis: ParentAxis, direction: DirectionFromParent) => AdjacentCell[];
+/**
+ * A candidate for the next cell to travel to.
+ * @internal
+ */
+export interface PathCandidateCell {
+    cx: number;
+    cy: number;
+    obstacles: Array<string>;
+    buffers: Array<string>;
+    obj: PathFinderGridCell;
+    /**
+     * This is the axis the path travels on to get from its parent to this candidate.
+     */
+    axis: ParentAxis;
+    /**
+     * The is the direction the path is travelling on.
+     * Positive horizontal means left to right
+     * Negative horizontal means right to left
+     * Positive vertical means top to bottom
+     * Negative vertical means bottom to top,
+     * Positive diagonal LR means left to right and top to bottom
+     * Negative diagonal LR means right to left and bottom to top
+     * Positive diagonal RL means left to right and bottom to top
+     * Negative diagonal RL means right to left and top to bottom
+     */
+    directionFromParent: DirectionFromParent;
+    ax: number;
+    ay: number;
+    g: number;
+    isTarget?: boolean;
+}
+export type AStarPathConstrainment = typeof PATH_CONSTRAIN_ORTHOGONAL | typeof PATH_CONSTRAIN_DIAGONAL | typeof PATH_CONSTRAIN_NONE | typeof PATH_CONSTRAIN_MANHATTAN | typeof PATH_CONSTRAIN_METRO;

package/types/core/astar/index.d.ts

@@ -0,0 +1,3 @@
+export * from './definitions';
+export * from './astar-util';
+export * from './candidate-sorter';

package/types/core/astar/path-to-segments.d.ts

@@ -0,0 +1,45 @@
+import { AStarGrid } from "./astar-util";
+import { AStarPath, AStarPathConstrainment, ParentAxis, PathFinderGridCell } from "./definitions";
+import { LineXY } from "../util";
+/**
+ * A segment we've chomped out of the chain of parents from some cell.
+ * @internal
+ */
+type ChompedSegment = {
+    axis: ParentAxis;
+    source: PathFinderGridCell;
+    target: PathFinderGridCell;
+    isFirstSegment: boolean;
+    length: number;
+};
+/**
+ * find the next segment from the given `fromCell`. Potentially returns null.
+ * @internal
+ */
+export declare function chompSegment(fromCell: PathFinderGridCell): ChompedSegment | null;
+/**
+ * Constructs a list of segments that represent the path found between sourceCell and targetCell. This method starts on
+ * targetCell and works backwards towards sourceCell, constructing a list of segments by traversing through each cell's
+ * parent.
+ * @param targetCell
+ * @param sourceCell
+ * @param grid
+ * @param constrain
+ * @param pathId
+ * @internal
+ */
+export declare function defaultPathToSegments(targetCell: PathFinderGridCell, sourceCell: PathFinderGridCell, grid: AStarGrid, constrain: AStarPathConstrainment, pathId: string, optimise: boolean): AStarPath;
+/**
+ * Constructs a line of sight optimised path between sourceCell and targetCell, This method first calls the default path to segment
+ * routine and then optimises to remove any segments that are unnecessary. The result is that the path does not necessarily
+ * follow 90 degree or 45 degree turns - it is free to make turns of any angle.
+ * @param targetCell
+ * @param sourceCell
+ * @param grid
+ * @param constrain
+ * @param hasLineOfSight Helper function that can say whether or not some line has line of sight.
+ * @param pathId
+ * @internal
+ */
+export declare function lineOfSightPathToSegments(targetCell: PathFinderGridCell, sourceCell: PathFinderGridCell, grid: AStarGrid, constrain: AStarPathConstrainment, hasLineOfSight: (grid: AStarGrid, l: LineXY) => boolean, pathId: string): AStarPath;
+export {};

package/types/core/autosaver.d.ts

@@ -0,0 +1,67 @@
+import { ModelEvent, VisuallyJsModel } from "./toolkit";
+type ABinding = [ModelEvent, Function];
+/**
+ * Options for the auto save module.
+ * @group Model
+ */
+export interface AutoSaveOptions {
+    /**
+     * Whether or not to automatically save the data when an update to a model object occurs. If you set this then you need to provide `saveUrl` or `autoSaveHandler`.
+     */
+    enabled?: boolean;
+    /**
+     * Optional type to use for auto save. Defaults to "json", the default input/output format VisuallyJs uses. If you have registered your own exporter you can use this parameter to instruct VisuallyJs to auto save via that exporter.
+     */
+    type?: string;
+    /**
+     * URL for auto save endpoint.
+     */
+    saveUrl?: string;
+    /**
+     * A debounce timeout to use when the `autoSave` functionality is turned on. You can use this to reduce the number of calls to your auto save endpoint.
+     */
+    debounceTimeout?: number;
+    /**
+     * A map of HTTP headers to send along with an auto save request.
+     */
+    saveHeaders?: any;
+    /**
+     * A function to call when an auto save operation was successful.
+     */
+    onAutoSaveSuccess?: () => any;
+    /**
+     * A function to call when an auto save operation experienced an error.
+     */
+    onAutoSaveError?: () => any;
+    /**
+     * A handler for the auto save operation. You need to provide this or `saveUrl` if you set `autoSave:true`.
+     * @param instance
+     */
+    autoSaveHandler?: (instance: VisuallyJsModel) => any;
+    /**
+     * A function to run before auto save runs.
+     */
+    onBeforeAutoSave?: () => any;
+    /**
+     * A function to run after the auto save has run.
+     */
+    onAfterAutoSave?: () => any;
+}
+/**
+ * Saves the model automatically. An instance of this class is created by the UI; it does not need to be
+ * created manually.
+ * @internal
+ */
+export declare class AutoSaver {
+    instance: VisuallyJsModel;
+    bindings: Array<ABinding>;
+    private _timer;
+    constructor(instance: VisuallyJsModel, options: AutoSaveOptions);
+    discard(): void;
+}
+export declare class CatchAllEventHandler {
+    instance: VisuallyJsModel;
+    bindings: Array<any>;
+    constructor(instance: VisuallyJsModel);
+}
+export {};

package/types/core/color-generator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Defines an object that can generate colors for a specific context. The strategy employed to generate colors is implementation specific.
+ * @group Utils
+ */
+export interface ColorGenerator<CTX = any> {
+    /**
+     * Generate a color.
+     * @param context Current context.
+     */
+    generate(context?: CTX): string;
+}
+/**
+ * A color generator that returns the same color every time it is called.
+ * @group Utils
+ */
+export declare class SingleColorGenerator<CTX> implements ColorGenerator<CTX> {
+    private color;
+    constructor(color: string);
+    /**
+     * Returns the color this class was constructed with.
+     */
+    generate(ctx?: CTX): string;
+}
+declare class RgbColor {
+    r: number;
+    g: number;
+    b: number;
+    constructor(r: number, g: number, b: number);
+    toString(): string;
+    static fromString(color: string): RgbColor;
+}
+/**
+ * A random color generator, random within bounds, it won't return a color with any component outside the range (20, 245). It also attempts to ensure that it doesnt give out two colors that are too similar. You can call `reset` on the color generator if you want to clear its history.
+ * @group Utils
+ */
+export declare class RandomColorGenerator<CTX> implements ColorGenerator<CTX> {
+    assignedColors: Array<RgbColor>;
+    /**
+     * Generate a random color. Within certain bounds.
+     */
+    generate(ctx?: CTX): string;
+    reset(): void;
+}
+/**
+ * A color generator that perpetually cycles through a given list of colors.
+ * @group Utils
+ */
+export declare class StaticColorGenerator<CTX> implements ColorGenerator<CTX> {
+    colors: string[];
+    counter: number;
+    constructor(...colors: Array<string>);
+    /**
+     * Returns the next color in the series this class was constructed with.
+     */
+    generate(ctx?: CTX): string;
+}
+/**
+ * Computes the "distance" between two colors, ie. how different a human perceives them to be.
+ * @param r1
+ * @param r2
+ * @internal
+ */
+export declare function colourDistance(r1: RgbColor, r2: RgbColor): number;
+export declare function getContrastColor(c: string | RgbColor): RgbColor;
+export declare function getOutlineColor(c: string | RgbColor): RgbColor;
+export {};

package/types/core/constants.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Constant representing the word "width". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const WIDTH = "width";
+/**
+ * Constant representing the word "height". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const HEIGHT = "height";
+/**
+ * Constant representing the word "rotation". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const ROTATION = "rotation";
+/**
+ * Constant representing the letter "v". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const V = "v";
+/**
+ * Constant representing the letter "h". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const H = "h";
+/**
+ * Constant representing the word "top". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const TOP = "top";
+/**
+ * Constant representing the word "left". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const LEFT = "left";
+/**
+ * Constant representing the word "right". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const RIGHT = "right";
+/**
+ * Constant representing the word "bottom". Various parts of the UI use this.
+ * @group Constants
+ */
+export declare const BOTTOM = "bottom";
+/**
+ * Constant representing the word "center"
+ * @group Constants
+ */
+export declare const CENTER = "center";
+/**
+ * Constant representing the letter "x"
+ * @group Constants
+ */
+export declare const X = "x";
+/**
+ * Constant representing the letter "y"
+ * @group Constants
+ */
+export declare const Y = "y";
+/**
+ * Models a path segment travelling diagonally, ie with a delta in both X and Y, from top left toward bottom right when moving in the "positive" direction
+ * @internal
+ */
+export declare const DIAGONAL_AXIS_LR = "dlr";
+/**
+ * Models a path segment travelling diagonally, ie with a delta in both X and Y, from top right toward bottom left when moving in the "positive" direction.
+ * @internal
+ */
+export declare const DIAGONAL_AXIS_RL = "drl";
+/**
+ * Models no direction constraint for a path segment. Paths can travel at any angle.
+ * @group Edges
+ * @category Connectors
+ */
+export declare const PATH_CONSTRAIN_NONE = "none";
+/**
+ * Models Orthogonal direction constrain for a path - meaning segments can travel vertically or horizontally only.
+ * @group Edges
+ * @category Connectors
+ */
+export declare const PATH_CONSTRAIN_ORTHOGONAL = "orthogonal";
+/**
+ * MANHATTAN is an alias for Orthogonal
+ * @group Edges
+ * @category Connectors
+ */
+export declare const PATH_CONSTRAIN_MANHATTAN = "manhattan";
+/**
+ * Models Diagonal constrain for a path - meaning segments can travel vertically,
+ * horizontally, or lines with a 45 degree angle.
+ * @group Edges
+ * @category Connectors
+ */
+export declare const PATH_CONSTRAIN_DIAGONAL = "diagonal";
+/**
+ * METRO is an alias for DIAGONAL
+ * @group Edges
+ * @category Connectors
+ */
+export declare const PATH_CONSTRAIN_METRO = "metro";
+/**
+ * @internal
+ */
+export declare const NEGATIVE = -1;
+/**
+ * The vertical orthogonal axis.
+ * @internal
+ */
+export declare const ORTHOGONAL_AXIS_VERTICAL = "v";
+/**
+ * The horizontal orthogonal axis.
+ * @internal
+ */
+export declare const ORTHOGONAL_AXIS_HORIZONTAL = "h";
+/**
+ * @internal
+ */
+export type OrthogonalAxis = typeof ORTHOGONAL_AXIS_HORIZONTAL | typeof ORTHOGONAL_AXIS_VERTICAL;
+/**
+ * Models a path segment travelling diagonally, ie with a delta in both X and Y
+ * @internal
+ */
+export type DiagonalAxis = typeof DIAGONAL_AXIS_LR | typeof DIAGONAL_AXIS_RL;
+/**
+ * Constant for matching JS 'undefined'.
+ * @internal
+ */
+export declare const UNDEFINED = "undefined";
+/**
+ * Constant used in various places internally, and as the key for default node, edge, port and group definitions.
+ * @group Constants
+ */
+export declare const DEFAULT = "default";
+/**
+ * Constant for the term "true", as a string.
+ * @group Constants
+ */
+export declare const TRUE = "true";
+/**
+ * Constant for the term "false", as a string.
+ * @group Constants
+ */
+export declare const FALSE = "false";
+/**
+ * The default attribute used to model a vertex's position in the X axis in its backing data
+ * @internal
+ */
+export declare const DEFAULT_LEFT_ATTRIBUTE = "left";
+/**
+ * The default attribute used to model a vertex's position in the X axis in its backing data
+ * @internal
+ */
+export declare const DEFAULT_TOP_ATTRIBUTE = "top";
+/**
+ * The default attribute used to model a vertex's rotation in its backing data
+ * @internal
+ */
+export declare const DEFAULT_ROTATION_ATTRIBUTE = "rotation";
+/**
+ * The default attribute used to model a vertex's width in its backing data
+ * @internal
+ */
+export declare const DEFAULT_WIDTH_ATTRIBUTE = "width";
+/**
+ * The default attribute used to model a vertex's height in its backing data
+ * @internal
+ */
+export declare const DEFAULT_HEIGHT_ATTRIBUTE = "height";
+/**
+ * @internal
+ */
+export declare const SOURCE = "source";
+/**
+ * @internal
+ */
+export declare const TARGET = "target";
+/**
+ * @internal
+ */
+export type ProxyLocation = typeof SOURCE | typeof TARGET;

package/types/core/csv-loader.d.ts

@@ -0,0 +1,84 @@
+import { VisuallyJsModel } from "./toolkit";
+import { ObjectData } from "./model/graph";
+export declare const CSV = "csv";
+/**
+ * Options for the CsvReader.
+ */
+export interface CsvReaderOptions {
+    /**
+     * Whether to treat the first line of the CSV as headers.
+     */
+    readHeaders?: boolean;
+    /**
+     * Number of lines to skip at the beginning of the CSV.
+     */
+    skipLines?: number;
+    /**
+     * Optional explicit headers to use if readHeaders is false.
+     */
+    headers?: string[];
+}
+/**
+ * A class to read and process CSV data.
+ * @group IO
+ */
+export declare class CsvReader {
+    csv: string;
+    lines: string[];
+    startLine: number;
+    headers: string[] | undefined;
+    /**
+     * Creates an instance of CsvReader.
+     * @param csv The CSV string to read.
+     * @param options Configuration options for reading the CSV.
+     */
+    constructor(csv: string, options?: CsvReaderOptions);
+    /**
+     * Internal method to iterate over CSV lines and call a processor function.
+     * @param lineProcessor Function to call for each line, receives an array of field values.
+     * @private
+     */
+    _read(lineProcessor: (entries: string[]) => void): void;
+    /**
+     * Read each line consecutively and call a function with an array representing each line.
+     * @param onLineRead Function to call with an array of strings for each line.
+     */
+    readLines(onLineRead: (entries: string[]) => void): void;
+    /**
+     * Read each line consecutively and call a function with a record (object) representing each line.
+     * If headers are available, they are used as keys; otherwise, "Field 1", "Field 2", etc. are used.
+     * @param onRecordRead Function to call with a record object for each line.
+     */
+    readRecords(onRecordRead: (record: Record<string, string>) => void): void;
+}
+/**
+ * Options for a source,target,value CSV parser.
+ * @group IO
+ */
+export interface SourceValueTargetCsvParserOptions {
+    /**
+     * Optional function that you can use to decorate loaded nodes prior to their addition to the model
+     * @param o Basic data object containing the node's ID.
+     * @param isSource Whether or not the given node is an edge source.
+     */
+    nodeDecorator?: (o: ObjectData, isSource: boolean) => ObjectData;
+    /**
+     * Defaults to true - whether or not the file is expected to have headers
+     */
+    readHeaders?: boolean;
+    /**
+     * Optional function that you can use to decorate loaded edges prior to their addition to the model
+     * @param e Basic data object containing the edge's value.
+     * @param source Data for the edge's source
+     * @param target Data for the edge's target
+     */
+    edgeDecorator?: (e: ObjectData, source: ObjectData, target: ObjectData) => ObjectData;
+}
+/**
+ * Loads CSV data from a file whose lines are in the format `source,target,value`
+ * @param csv The CSV string to load.
+ * @param model
+ * @param parameters Optional parameters (currently unused in this implementation).
+ * @returns An object containing nodes and edges.
+ */
+export declare const SourceValueTargetCsvParser: (csv: string, model: VisuallyJsModel, parameters?: SourceValueTargetCsvParserOptions) => void;

package/types/core/datamodel/data-model.d.ts

@@ -0,0 +1,23 @@
+import { GroupDefinition, NodeDefinition, PortDefinition } from "./vertex-definition";
+import { VisuallyJsModel } from "../toolkit";
+/**
+ * Base interface a for data model.
+ * @internal
+ */
+export interface DataModelDefinition {
+    nodes?: Record<string, NodeDefinition>;
+    groups?: Record<string, GroupDefinition>;
+    ports?: Record<string, PortDefinition>;
+}
+/**
+ * @internal
+ */
+export declare class DataModel {
+    private _nodeDefinitions;
+    private _groupDefinitions;
+    private _portDefinitions;
+    constructor(instance: VisuallyJsModel, def?: DataModelDefinition);
+    getNodeDefinition(type: string): NodeDefinition;
+    getGroupDefinition(type: string): GroupDefinition;
+    getPortDefinition(type: string): PortDefinition;
+}

package/types/core/datamodel/vertex-definition.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Base class for node, group and port definitions. This interface is shared by the model and the view.
+ * @group Nodes and Groups
+ * @category View
+ */
+export interface VertexDefinition {
+    /**
+     * Optional connection limit. Defaults to 1. A value of -1 means there is no limit.
+     */
+    maxConnections?: number;
+    /**
+     * Whether or not to allow edges from this vertex back to itself. Defaults to false.
+     */
+    allowLoopback?: boolean;
+    /**
+     * Whether or not to allow edges from a port back to the vertex it belongs to. Defaults to true.
+     */
+    allowVertexLoopback?: boolean;
+}
+/**
+ * A node definition in a view.
+ * @group Nodes and Groups
+ * @category View
+ */
+export interface NodeDefinition extends VertexDefinition {
+}
+/**
+ * A group definition in a view.
+ * @group Nodes and Groups
+ * @category View
+ */
+export interface GroupDefinition extends NodeDefinition {
+}
+/**
+ * A port definition in a view.
+ * @group Nodes and Groups
+ * @category View
+ */
+export interface PortDefinition extends VertexDefinition {
+}