@visuallyjs/browser-ui 1.0.0

package/types/core/util.d.ts

@@ -0,0 +1,661 @@
+import { RotatedPointXY } from "../ui";
+import { Group, Node } from "./model/graph";
+import { AnchorOrientationHint } from "./model/anchor";
+/**
+ * Determines whether or not logging is currently enabled.
+ * @internal
+ */
+export declare const logEnabled: boolean;
+/**
+ * Logs a console message.
+ * @param args
+ * @internal
+ */
+export declare function log(...args: string[]): void;
+/**
+ * Defines an object that has a constructor. Used internally to create endpoints/connectors/overlays from their names. Exposed as public for people to create their own endpoints/connectors/overlays.
+ * @internal
+ */
+export type Constructable<T> = {
+    new (...args: any[]): T;
+};
+/**
+ * Returns true if the given `object` can be considered to be an instance of the class `cls`.  This is done by
+ * testing the prototype chain of the object and checking at each level to see if the prototype is an instance of the given class.
+ * @param object Object to test
+ * @param cls Class to test for.
+ * @internal
+ */
+export declare function isAssignableFrom(object: any, cls: any): boolean;
+/**
+ * Remove an item from an array
+ * @param l Array to remove the item from
+ * @param v Item to remove.
+ * @returns true if the item was removed, false otherwise.
+ * @internal
+ */
+export declare function remove<T>(l: Array<T>, v: T): boolean;
+/**
+ * Adds an item to a list if the given hash function determines that the item is not already in the list
+ * @param list List to add to
+ * @param item Item to add
+ * @param hashFunction Function to use to check the current items of the list; if this function returns true for any current list item, the insertion does not proceed.
+ * @internal
+ */
+export declare function addWithFunction<T>(list: Array<T>, item: T, hashFunction: (_a: T) => boolean): void;
+/**
+ * Adds an item to a dictionary whose values consists of array of some type. This method is used internally by VisuallyJs and is not intended as part of the public API,
+ * and will likely be removed at some point in the future when the code that depends upon it has been refactored.
+ * @param map
+ * @param key
+ * @param value
+ * @param insertAtStart
+ * @internal
+ */
+export declare function addToDictionary<T>(map: Record<string, Array<T>>, key: string, value: any, insertAtStart?: boolean): Array<any>;
+/**
+ * Add an item to a list that is stored inside some map. This method is used internally.
+ * @param map A map of <K, Array<T>> entries.
+ * @param key The ID of the list to search for in the map
+ * @param value The value to add to the list, if found
+ * @param insertAtStart If true, inserts the new item at the head of the list. Defaults to false.
+ * @internal
+ */
+export declare function addToList<T, K = string>(map: Map<K, Array<T>>, key: K, value: any, insertAtStart?: boolean): Array<any>;
+/**
+ * Add the given item to the given list if it does not exist on the list already.
+ * @param list - List to add to
+ * @param item - Item to add
+ * @param insertAtHead - If true, insert new item at head. Defaults to false.
+ * @internal
+ */
+export declare function suggest(list: Array<any>, item: any, insertAtHead?: boolean): boolean;
+/**
+ * Extract a value from the set where the given predicate returns true for that value.
+ * @param s
+ * @param f
+ * @internal
+ */
+export declare function getFromSetWithFunction<T>(s: Set<T>, f: (_a: T) => boolean): T;
+/**
+ * Remove the entry from the array for which the function `f` returns true.
+ * @param a
+ * @param f
+ * @returns true if an element was removed, false if not.
+ * @internal
+ */
+export declare function removeWithFunction<T>(a: Array<T>, f: (_a: T) => boolean): boolean;
+/**
+ * Rotate the given point around the given center, by the given rotation (in degrees)
+ * @param point
+ * @param center
+ * @param rotation Rotation in degrees
+ * @returns An object consisting of the rotated point, followed by cos theta and sin theta.
+ * @internal
+ */
+export declare function rotatePoint(point: PointXY, center: PointXY, rotation: number): RotatedPointXY;
+/**
+ * Trims whitespace from the given string.
+ * @param s String to trim
+ * @group Utils
+ */
+export declare function fastTrim(s: string): string;
+/**
+ * Inserts the given value into the given array at a sorted location.
+ * @param value Value to insert
+ * @param array Array to insert into
+ * @param comparator Function to use when determining sort order.
+ * @param sortDescending Defaults to false; if true, the insertion is sorted in reverse order.
+ * @internal
+ */
+export declare function insertSorted<T>(value: T, array: Array<T>, comparator: (v1: T, v2: T) => number, sortDescending?: boolean): void;
+/**
+ * Definition of the extends of some set of elements: the min/max values in each axis.
+ * @internal
+ */
+export interface Extents {
+    /** Minimum in x axis */
+    xmin: number;
+    /** Minimum in y axis */
+    ymin: number;
+    /** Maximum in x axis */
+    xmax: number;
+    /** Maximum in y axis */
+    ymax: number;
+}
+/**
+ * Returns an empty bounds object, used in certain initializers internally.
+ * @internal
+ */
+export declare function EMPTY_BOUNDS(): Extents;
+/**
+ * Defines an x/y location.
+ * @group Data Model
+ */
+export interface PointXY {
+    /**
+     * X location
+     */
+    x: number;
+    /**
+     * Y location
+     */
+    y: number;
+}
+/**
+ * Extracts just the x,y properties from the given input value, which may be some other type that just happens to implement PointXY. We use this internally when one of our reference objects contains the values we need, but we want to ensure we have a copy in some local scope, in case we change its values.
+ * @param p
+ * @internal
+ */
+export declare function extractPoint(p: PointXY): PointXY;
+/**
+ * Defines the width and height of some element.
+ * @group Data Model
+ */
+export interface Size {
+    /**
+     * Element width
+     */
+    width: number;
+    /**
+     * element height
+     */
+    height: number;
+}
+/**
+ * Extracts just the width,height properties from the given input value, which may be some other type that just happens to implement Size. We use this internally when one of our reference objects contains the values we need, but we want to ensure we have a copy in some local scope, in case we change its values.
+ * @param p
+ * @internal
+ */
+export declare function extractSize(p: Size): Size;
+/**
+ * Extract a rectangle from the given object. We use this internally to ensure we dont overwrite internal object.
+ * @param p
+ * @internal
+ */
+export declare function extractBounds(p: Size & PointXY): RectangleXY;
+/**
+ * Defines a rectangle in 2d space - its x/y location, width and height, and optionally the computed center, but that can of course be calculated from the other values. Internally there are times when the code has this to hand so we include it here.
+ * @group Data Model
+ */
+export interface RectangleXY extends PointXY, Size {
+    /**
+     * Center of the box. In some cases the code has this information to hand
+     * and populates it, but if it is absent you can figure it out from the
+     * other values.
+     */
+    center?: PointXY;
+}
+/**
+ * This is an alias for RectangleXY.
+ * @group Data Model
+ */
+export type BoundingBox = RectangleXY;
+/**
+ * Details for a vertex that is enclosed by, or intersects, some specified region. The type parameter T will either be a Node or a Group. EL is the type parameter for the element in the UI.
+ * @typeParam T The type of the model object that is intersecting - a Node or a Group.
+ * @typeParam EL The element type for the UI. In the browser-ui package this is {@link BrowserElement} - an HTML or SVG element.
+ * @group Data Model
+ */
+export type IntersectingVertex<EL> = {
+    /**
+     * Intersecting region
+     */
+    r: RectangleXY;
+    /**
+     * The vertex that intersects
+     */
+    v: Node | Group;
+    /**
+     * The element representing the vertex in the UI
+     */
+    el: EL;
+    /**
+     * The ID of the vertex
+     */
+    id: string;
+    /**
+     * True if the vertex is enclosed by the region, false if the vertex only intersects the region.
+     */
+    enclosed: boolean;
+};
+/**
+ * Translates the given rectangle by the given amount in x and y, either in the +ve direction or in the -ve direction,
+ * depending on the value of `dir`.
+ * @param r Rectangle to translate
+ * @param delta How much to translate by in the X and Y axes
+ * @param dir 1 to translate right/down, -1 to translate left/up.
+ * @internal
+ */
+export declare function translateRect(r: RectangleXY, delta: PointXY, dir: 1 | -1): RectangleXY;
+/**
+ * Definition of a grid - the width/height of each cell, and, optionally, a threshold value for each axis to use when
+ * trying to snap some coordinate to the grid.
+ * @group Data Model
+ */
+export interface Grid extends Size {
+    thresholdX?: number;
+    thresholdY?: number;
+}
+/**
+ * Defines a line from some point to another.
+ * @group Data Model
+ */
+export type LineXY = [PointXY, PointXY];
+/**
+ * Generate a v4 UUID.
+ * @returns String representation of a UUID
+ * @group Utils
+ */
+export declare function uuid(): string;
+/**
+ * Generate a shortened UUID.
+ * @param length
+ * @group Utils
+ */
+export declare function shortUuid(length?: number): string;
+/**
+ * gets the midpoints of the four sides of the given rectangle
+ * @param r
+ * @internal
+ */
+export declare function getRectangleMidpoints(r: RectangleXY): Array<PointXY>;
+/**
+ * Gets the closest face midpoint from the given rectangle to the given point.
+ * @internal
+ */
+export declare function getClosestMidpoint(fromPoint: PointXY, r: RectangleXY): PointXY;
+/**
+ * Either write a value to an object or reads a value from the object.
+ * @param inObj Object to operate on
+ * @param path A path in dotted notation to the target in the object
+ * @param value The value to write
+ * @group Utils
+ */
+export declare function data(inObj: Record<string, any>, path: string, value?: any): any;
+/**
+ * Partitions a list into two lists - one for which the supplied partitioner returns true (the `left` list), and the other, the
+ * `right` list, for which the supplied partitioner does not return true.
+ * @param l List to partition
+ * @param partitioner Function to use to partition the list.
+ * @group Utils
+ */
+export declare function partition<T, A extends T, B extends T>(l: ArrayLike<T>, partitioner: (candidate: T) => boolean): {
+    left: Array<A>;
+    right: Array<B>;
+};
+/**
+ * Filters out empty or null values from the given list of strings
+ * @internal
+ */
+export declare function filterEmpty(l: Array<string>): Array<string>;
+/**
+ * Runs the given function for each value in the array that is not null and has a non-zero length.
+ * @internal
+ */
+export declare function eachNotEmpty(strings: Array<string>, fn: (idx: number, s: string) => any): void;
+/**
+ * @internal
+ */
+export type ClosestPointCandidate<T extends PointXY> = {
+    p: T;
+    idx: number;
+    distance: number;
+};
+/**
+ * Find the closest point out of `locations` to the given point on the given constraining rectangle.
+ * @param pos An x,y location in pixel values
+ * @param constrainRect Width/height of the bounding box, in pixels
+ * @param locations A list of x/y logical locations, whose values are proportional lengths (anchor format).
+ * @internal
+ */
+export declare function findClosestPoint<T extends PointXY>(pos: PointXY, constrainRect: RectangleXY, locations: Array<T>): ClosestPointCandidate<T>;
+/**
+ * Get, or insert then get, a value from the map.
+ * @param map Map to get the value from.
+ * @param key Key of the value to retrieve
+ * @param valueGenerator Method used to generate a value for the key if it is not currently in the map.
+ * @internal
+ */
+export declare function getsert<K, V>(map: Map<K, V>, key: K, valueGenerator: () => V): V;
+/**
+ * Get, or insert then get, a value from the map.
+ * @param map Map to get the value from.
+ * @param key Key of the value to retrieve
+ * @param valueGenerator Method used to generate a value for the key if it is not currently in the map.
+ * @internal
+ */
+export declare function recordGetsert<V>(map: Record<string, V>, key: string, valueGenerator: () => V): V;
+/**
+ * Returns whether or not the given value is of `number` type.
+ * @param n
+ * @internal
+ */
+export declare function isNumber(n: any): boolean;
+/**
+ * Returns whether or not the given value is of `string` type.
+ * @param s
+ * @internal
+ */
+export declare function isString(s: any): s is string;
+/**
+ * Returns whether or not the given value is of `boolean` type.
+ * @param s
+ * @internal
+ */
+export declare function isBoolean(s: any): boolean;
+/**
+ * Returns whether or not the given value is of type `object`
+ * @param o
+ * @internal
+ */
+export declare function isObject(o: any): boolean;
+/**
+ * Returns whether or not the given value is of type `Date`
+ * @param o
+ * @internal
+ */
+export declare function isDate(o: any): o is Date;
+/**
+ * Returns whether or not the given value is of type `Function`
+ * @param o
+ * @internal
+ */
+export declare function isFunction(o: any): o is Function;
+/**
+ * Returns whether or not the given value is of type `Function` and is a named Function.
+ * @param o
+ * @internal
+ */
+export declare function isNamedFunction(o: any): boolean;
+/**
+ * Returns whether or not the given object - which may be ArrayLike, or an object - is empty.
+ * @param o
+ * @internal
+ */
+export declare function isEmpty(o: any): boolean;
+/**
+ * Returns whether or not the two objects are identical, ie. there are no keys in o1 that do not exist in o2 and vice versa.
+ * @param a
+ * @param b
+ * @internal
+ */
+export declare function objectsEqual(a: Record<string, any>, b: Record<string, any>): boolean;
+/**
+ * Returns a copy of the given object that has no null values. Note this only operates one level deep.
+ * @param obj
+ * @internal
+ */
+export declare function filterNull(obj: Record<string, any>): Record<string, any>;
+/**
+ * Makes a copy of the given object.
+ * @param a
+ * @internal
+ */
+export declare function clone(a: any): any;
+/**
+ * Merge the values from `b` into the values from `a`, resulting in `c`.  `b` and `a` are unchanged by this method.
+ * Not every datatype can be merged - arrays can, and objects can, but primitives (strings/booleans/numbers/functions)
+ * cannot, and are overwritten in `c` by the value from `b`, if present.
+ *
+ * @remarks
+ *
+ * Collating Values
+ * ----------------
+ *
+ * You can choose to collate strings, booleans or functions if you wish, by providing their key names in the `collations` array. So if
+ * you had, say:
+ *
+ * a:{
+ *     foo:"hello"
+ * }
+ *
+ * b:{
+ *     foo:"world"
+ * }
+ *
+ * and you called  `merge(a, b, ["foo"])`, then the output would be
+ *
+ * {
+ *     foo:["hello", "world"]
+ * }
+ *
+ * if the value in `a` is already an Array then the value from `b` is simply appended:
+ *
+ * a:{
+ *     foo:["hello"]
+ * }
+ *
+ * b:{
+ *     foo:"world"
+ * }
+ *
+ * here the output would be
+ *
+ * {
+ *     foo:["hello", "world"]
+ * }
+ *
+ *
+ * Overwriting values
+ * -----------------
+ *
+ * If you wish to overwrite, rather than merge, specific values, you can provide their keys in the `overwrites` array. Note that it's unnecessary to
+ * specify any primitives in the `overwrites` array, as they will always be overwritten and not merged.
+ *
+ * a:{
+ *     foo:["hello", "world"]
+ * }
+ *
+ * b:{
+ *     foo:"world"
+ * }
+ *
+ * and you called  `merge(a, b, null, ["foo"])`, then the output would be
+ *
+ * {
+ *     foo:"world"
+ * }
+ *
+ * Note that it is irrelevant, in the case of overwriting, what the type of the parent's value is. It will be overwritten regardless.
+ *
+ * @param a Parent object
+ * @param b Child object
+ * @param collations Optional list of parameters to collate, rather than merging or overwriting.
+ * @param overwrites Optional list of parameters to overwrite, rather than merging.
+ * @internal
+ */
+export declare function merge(a: Record<string, any>, b: Record<string, any>, collations?: Array<string>, overwrites?: Array<string>): any;
+/**
+ * Returns whether or not the two arrays are identical, ie. they have the same length and every value is the same
+ * @param a
+ * @param b
+ * @internal
+ */
+export declare function arraysEqual(a: Array<any>, b: Array<any>): boolean;
+export declare function pointsEqual(p1: PointXY, p2: PointXY): boolean;
+/**
+ * Defines the current rotation of some element - its rotation (in degrees) and the center point around which it is rotated.
+ * @internal
+ */
+export interface Rotation {
+    r: number;
+    c: PointXY;
+}
+/**
+ * A set of compound rotations - used when nesting elements/groups inside other groups.
+ * @internal
+ */
+export type Rotations = Array<Rotation>;
+/**
+ * Applies the given set of Rotations to the given point, and returns a new PointXY. For internal use.
+ * @param point - Point to rotate
+ * @param rotations - Rotations to apply.
+ * @internal
+ */
+export declare function applyRotations(point: [number, number, number, number], rotations: Rotations): RotatedPointXY;
+/**
+ * Applies the given set of Rotations to the given point, and returns a new PointXY. For internal use.
+ * @param point - Point to rotate
+ * @param rotations - Rotations to apply.
+ * @internal
+ */
+export declare function applyRotationsXY(point: PointXY, rotations: Rotations): PointXY;
+/**
+ * Replace a value inside some object with another value.
+ * @param inObj Object within which to make the replacement.
+ * @param path Path to the value to replace. Supports dotted and bracket notation. Eg "foo" means a value with key `foo` in the root. "foo.bar" means a value
+ * with key `bar` inside a value with key `foo`. "foo[1]" means the object at index 1 inside a value with key `foo`.
+ * @param value Value to replace the original value with.
+ * @internal
+ */
+export declare function replace(inObj: any, path: string, value: any): any;
+/**
+ *
+ * Take the given model and expand out any parameters. Parameters to expand are marked inside string values with this syntax:
+ *
+ * `
+ * someKey:"this is a value of type {{type}}"
+ * `
+ *
+ * @param model Object to populate with values.
+ * @param values Object containing values to populate
+ * @param functionPrefix This is optional, and if present, helps VisuallyJs figure out what to do if a value is a Function.
+ * if you do not provide it (and `doNotExpandFunctions` is null, or false), VisuallyJs will run the given values through any functions it finds, and use the function's
+ * output as the value in the result. if you do provide the prefix, only functions that are named and have this prefix
+ * will be executed; other functions will be passed as values to the output.
+ * @param doNotExpandFunctions Defaults to false. If true, Functions will be passed directly from `values` to `model` without being executed.
+ * @returns
+ * @internal
+ */
+export declare function populate(model: any, values: any, functionPrefix?: string, doNotExpandFunctions?: boolean): any;
+/**
+ * Implementation of a PriorityQueue.
+ * @group Utils
+ */
+export declare class PriorityQueue<T> {
+    private sorter;
+    stack: Array<T>;
+    get length(): number;
+    constructor(sorter: (a: T, b: T) => number, ...entries: Array<T>);
+    /**
+     * Add an element, sorted.
+     * @param node
+     */
+    add(node: T): void;
+    /**
+     * Update the given element - meaning, remove it and re-insert it.
+     * @param node
+     */
+    update(node: T): void;
+    /**
+     * Remove and return the last entry in the queue (the entry with the highest priority).
+     */
+    pop(): T;
+    /**
+     * Remove the given entry from the queue.
+     * @param node
+     */
+    delete(node: T): void;
+    /**
+     * Get the entry with the lowest priority, or null if the queue is empty.
+     */
+    head(): T;
+    /**
+     * Get the entry with the highest priority, and leave it in the queue.
+     */
+    peek(): T;
+    /**
+     * Returns whether or not the queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Empties out the queue.
+     */
+    clear(): void;
+}
+/**
+ * Models the minimum and maximum values in an allowed zoom range. These value are expressed decimals: 0.5 means 50%, for instance.
+ */
+export type ZoomRange = [number, number];
+/**
+ * Base segment in an edge geometry.
+ * @group Edges
+ * @category Connectors
+ */
+export interface BaseGeometrySegment {
+    /**
+     * X location of first point in segment.
+     */
+    x1: number;
+    /**
+     * X location of second point in segment.
+     */
+    x2: number;
+    /**
+     * Y location of first point in segment.
+     */
+    y1: number;
+    /**
+     * Y location of second point in segment.
+     */
+    y2: number;
+}
+/**
+ * Geometry defines the path along which a connector travels. The internal contents of a Geometry vary between connectors.
+ * @group Edges
+ * @category Connectors
+ */
+export interface Geometry {
+    /**
+     * Definition of where the edge's source is located.
+     */
+    source: AnchorPlacement;
+    /**
+     * Definition of where the edge's target is located.
+     */
+    target: AnchorPlacement;
+    /**
+     * List of segments.
+     */
+    segments: Array<BaseGeometrySegment>;
+}
+/**
+ * Defines the current location that an anchor is placed at, for use in edge geometry objects.
+ */
+export type AnchorPlacement = {
+    /**
+     * Current X in canvas coordinates
+     */
+    curX: number;
+    /**
+     * Current Y in canvas coordinates
+     */
+    curY: number;
+    /**
+     * X location of anchor as a proportion of the width of the element
+     */
+    x: number;
+    /**
+     * Y location of anchor as a proportion of the height of the element
+     */
+    y: number;
+    /**
+     * Orientation of the source anchor
+     */
+    ox: AnchorOrientationHint;
+    /**
+     * Orientation of the target anchor
+     */
+    oy: AnchorOrientationHint;
+    /**
+     * Optional offset to apply in X axis - in canvas coordinates. This is applied after the
+     * anchor's `x` value is used to compute its location on the vertex.
+     */
+    offsetX?: number;
+    /**
+     * Optional offset to apply in Y axis - in canvas coordinates. This is applied after the
+     * anchor's `y` value is used to compute its location on the vertex.
+     */
+    offsetY?: number;
+};

package/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This is the base VisuallyJs package, which uses the internal template engine, and is a dependency for each of the library integrations.
+ * @packageDocumentation
+ * @groupDescription CSS Classes
+ * List of CSS classes assigned to DOM elements by various parts of the VisuallyJs UI
+ * @groupDescription Data Model
+ * Classes/interfaces used to represent the data model of an app written with VisuallyJs.
+ * @groupDescription Utils
+ * Various utility functions for operating on the data model and on the UI.
+ */
+export * from './browser-ui';
+export * from './ui';
+export * from './core';
+export * from './test-support';
+export { HeadlessRecado, Recado, processExpression, evaluateExpression } from './core/templates';
+export * from './charts';

package/types/l.d.ts

@@ -0,0 +1,2 @@
+export declare function watermark(el: Element, h: boolean, orig?: Element): void;
+export declare function chartWatermark(el: SVGElement, h: boolean, orig?: SVGElement): void;

package/types/test-support/index.d.ts

@@ -0,0 +1 @@
+export * from "./test-support";