@visuallyjs/browser-ui 1.0.0

package/types/ui/common/abstract-segment.d.ts

@@ -0,0 +1,88 @@
+import { Extents, BoundingBox, PointXY } from "../../core";
+export interface SegmentParams {
+    x1: number;
+    x2: number;
+    y1: number;
+    y2: number;
+}
+/**
+ * @internal
+ */
+export type PointNearPath = {
+    s?: Segment;
+    d: number;
+    x: number;
+    y: number;
+    l: number;
+    x1: number;
+    x2: number;
+    y1: number;
+    y2: number;
+};
+/**
+ * Definition of a segment. This is an internal class that users of the API need not access.
+ * @internal
+ */
+export interface Segment {
+    x1: number;
+    x2: number;
+    y1: number;
+    y2: number;
+    type: string;
+    extents: Extents;
+}
+export interface SegmentHandler<S extends Segment, SP extends SegmentParams> {
+    lineIntersection(segment: S, x1: number, y1: number, x2: number, y2: number): Array<PointXY>;
+    boxIntersection(segment: S, x: number, y: number, w: number, h: number): Array<PointXY>;
+    boundingBoxIntersection(segment: S, box: BoundingBox): Array<PointXY>;
+    getLength(segment: S): number;
+    pointOnPath(segment: S, location: number, absolute?: boolean): PointXY;
+    gradientAtPoint(segment: S, location: number, absolute?: boolean): number;
+    pointAlongPathFrom(segment: S, location: number, distance: number, absolute?: boolean): PointXY;
+    findClosestPointOnPath(segment: S, x: number, y: number): PointNearPath;
+    getPath(segment: S, isFirstSegment: boolean): string;
+    create(params: SP): S;
+}
+/**
+ * Finds the closest point on this segment to the given x/y, returning both the x and y of the point plus its distance from
+ * the supplied point, and its location along the length of the path inscribed by the segment.  This implementation returns
+ * Infinity for distance and null values for everything else subclasses are expected to override.
+ * @param x - X location to find closest point to
+ * @param y - Y location to find closest point to
+ * @returns a `PointNearPath` object, which contains the location of the closest point plus other useful information.
+ * @internal
+ */
+export declare function _defaultSegmentFindClosestPointOnPath(s: Segment, x: number, y: number): PointNearPath;
+/**
+ * Computes the list of points on the segment that intersect the given line.
+ * @param x1 - X location of point 1
+ * @param y1 - Y location of point 1
+ * @param x2 - X location of point 2
+ * @param y2 - Y location of point 2
+ * @returns A list of intersecting points
+ * @internal
+ */
+export declare function _defaultSegmentLineIntersection(s: Segment, x1: number, y1: number, x2: number, y2: number): Array<PointXY>;
+/**
+ * Computes the list of points on the segment that intersect the box with the given origin and size.
+ * @param x - x origin of the box
+ * @param y - y origin of the box
+ * @param w - width of the box
+ * @param h - height of the box
+ * @returns A list of intersecting points
+ * @internal
+ */
+export declare function _defaultSegmentBoxIntersection(s: Segment, x: number, y: number, w: number, h: number): Array<PointXY>;
+/**
+ * Computes the list of points on the segment that intersect the given bounding box.
+ * @param box - Box to test for intersections.
+ * @returns A list of intersecting points
+ * @internal
+ */
+export declare function _defaultSegmentBoundingBoxIntersection(s: Segment, box: BoundingBox): Array<PointXY>;
+/**
+ * @internal
+ * @param sp
+ * @private
+ */
+export declare function _createBaseSegment(sp: SegmentParams): Segment;

package/types/ui/common/anchor.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Common options for anchors.
+ *
+ */
+import { PointXY, Size, Rotations, AnchorOrientationHint, ObjectAnchorSpec } from "../../core";
+import { Connection } from "../core";
+export type Orientation = Record<"y" | "x", AnchorOrientationHint>;
+export declare const OBJECT_TYPE_ANCHOR = "Anchor";
+export declare const FACE_TOP = "top";
+export declare const FACE_LEFT = "left";
+export declare const FACE_RIGHT = "right";
+export declare const FACE_BOTTOM = "bottom";
+export type Face = typeof FACE_TOP | typeof FACE_LEFT | typeof FACE_RIGHT | typeof FACE_BOTTOM;
+export declare const faceOrientations: {
+    top: {
+        x: number;
+        y: number;
+    };
+    bottom: {
+        x: number;
+        y: number;
+    };
+    right: {
+        x: number;
+        y: number;
+    };
+    left: {
+        x: number;
+        y: number;
+    };
+};
+export type Axis = [Face, Face];
+export declare const X_AXIS_FACES: Axis;
+export declare const Y_AXIS_FACES: Axis;
+/**
+ * for each face, what are the two faces that are orthogonal to it?
+ * @internal
+ */
+export declare const ORTHOGONAL_FACES: Record<Face, [Face, Face]>;
+/**
+ * for each face, what is the face opposite?
+ * @internal
+ */
+export declare const OPPOSITE_FACES: Record<Face, Face>;
+/**
+ * @internal
+ */
+export type AnchorComputeParams = {
+    xy?: PointXY;
+    wh?: Size;
+    txy?: PointXY;
+    twh?: Size;
+    timestamp?: string;
+    index?: number;
+    connection?: Connection<any>;
+    elementId: string;
+    otherElementId?: string;
+    rotation?: Rotations;
+    tRotation?: Rotations;
+    otherAnchor?: LightweightAnchor;
+};
+/**
+ * Defines a single location an anchor may be placed at.
+ * @internal
+ */
+export interface AnchorRecord {
+    x: number;
+    y: number;
+    ox: AnchorOrientationHint;
+    oy: AnchorOrientationHint;
+    offsetX?: number;
+    offsetY?: number;
+}
+/**
+ * @internal
+ */
+export interface ComputedPosition {
+    curX: number;
+    curY: number;
+    ox: AnchorOrientationHint;
+    oy: AnchorOrientationHint;
+    x: number;
+    y: number;
+}
+/**
+ * Representation of an anchor.
+ * @internal
+ */
+export interface LightweightAnchor {
+    objectType: typeof OBJECT_TYPE_ANCHOR;
+    locations: Array<AnchorRecord>;
+    currentLocation: number;
+    id: string;
+    cssClass: string;
+    /**
+     * Indicates whether this anchor was constructed as a Continuous anchor. If isFixed is set, this flag will be ignored.
+     */
+    isContinuous: boolean;
+    /**
+     * Indicates whether this anchor was constructed as a Dynamic anchor, ie. it has more than one location it can choose
+     * from. However given the fact that the code treats multiple locations in the same code path as a single location, it
+     * seems likely this flag can be removed.
+     */
+    isDynamic: boolean;
+    /**
+     * Indicates the position of this anchor has been fixed somehow and that all calculations should use `fixedLocation` for
+     * the anchor's location (ignoring the fact that the anchor may be declared as dynamic or continuous). Anchors can
+     * currently be fixed via their edge having anchor information declared, but it seems likely that other parts of the
+     * codebase could make use of this too (such as when an edge is being edited)
+     */
+    isFixed: boolean;
+    /**
+     * When isFixed is set, this is the fixed position.
+     */
+    fixedLocation: AnchorRecord;
+    timestamp: string;
+    type: string;
+    computedPosition?: ComputedPosition;
+}
+export interface LightweightPerimeterAnchor extends LightweightAnchor {
+    shape: PerimeterAnchorShapes;
+}
+/**
+ * A continuous anchor has faces it can choose from, and may be locked to some axis or a face.
+ * @internal
+ */
+export interface LightweightContinuousAnchor extends LightweightAnchor {
+    faces: Array<Face>;
+    lockedFace: Face;
+    isContinuous: true;
+    isDynamic: false;
+    isGeometric: false;
+    currentFace: Face;
+    lockedAxis: Axis;
+    clockwise: boolean;
+}
+export interface AnchorOptions extends Record<string, any> {
+}
+/**
+ * Supported shapes for a Perimeter anchor.
+ * @group Edges
+ */
+export declare enum PerimeterAnchorShapes {
+    Circle = "Circle",
+    Ellipse = "Ellipse",
+    Triangle = "Triangle",
+    Diamond = "Diamond",
+    Rectangle = "Rectangle",
+    Square = "Square"
+}
+/**
+ * Constructor options for a Perimeter Anchor.
+ * @group Edges
+ */
+export interface PerimeterAnchorOptions extends AnchorOptions {
+    /**
+     * The shape to use for the anchor
+     */
+    shape: keyof PerimeterAnchorShapes;
+    /**
+     * Optional rotation
+     */
+    rotation?: number;
+    /**
+     * How many anchors to use to approximate the perimeter.
+     */
+    anchorCount?: number;
+}
+/**
+ * Default anchor locations.
+ * @group Edges
+ * @category Anchors
+ */
+export declare enum AnchorLocations {
+    /**
+     * User must specify an assignment function.
+     */
+    Assign = "Assign",
+    /**
+     * Chooses from Top, Left, Bottom or Right, depending on which is closest to the anchor at the other end of the connection.
+     */
+    AutoDefault = "AutoDefault",
+    /**
+     * Bottom middle of the element.
+     */
+    Bottom = "Bottom",
+    /**
+     * Bottom left corner of the element.
+     */
+    BottomLeft = "BottomLeft",
+    /**
+     * Bottom right corner of the element.
+     */
+    BottomRight = "BottomRight",
+    /**
+     * Center of the element.
+     */
+    Center = "Center",
+    /**
+     * Assigns a separate anchor point for each endpoint, choosing whichever face is closest to the element at the other end of each connection.
+     */
+    Continuous = "Continuous",
+    /**
+     * As with Continuous, but only use the bottom face.
+     */
+    ContinuousBottom = "ContinuousBottom",
+    /**
+     * As with Continuous, but only use the left face.
+     */
+    ContinuousLeft = "ContinuousLeft",
+    /**
+     * As with Continuous, but only use the right face.
+     */
+    ContinuousRight = "ContinuousRight",
+    /**
+     * As with Continuous, but only use the top face.
+     */
+    ContinuousTop = "ContinuousTop",
+    /**
+     * As with Continuous, but only use the left and right faces.
+     */
+    ContinuousLeftRight = "ContinuousLeftRight",
+    /**
+     * As with Continuous, but only use the top and bottom faces.
+     */
+    ContinuousTopBottom = "ContinuousTopBottom",
+    /**
+     * Center of the left edge of the element.
+     */
+    Left = "Left",
+    /**
+     * Center of the right edge of the element.
+     */
+    Right = "Right",
+    /**
+     * Center of the top edge of the element.
+     */
+    Top = "Top",
+    /**
+     * Top left corner of the element.
+     */
+    TopLeft = "TopLeft",
+    /**
+     * Top right corner of the element.
+     */
+    TopRight = "TopRight"
+}
+/**
+ * List of entries in the AnchorLocations enum
+ * @group Edges
+ * @category Anchors
+ */
+export type AnchorId = keyof typeof AnchorLocations;
+/**
+ * An anchor spec in the form `{type:..., options:{ ... }}`
+ * @group Edges
+ * @category Anchors
+ */
+export type FullAnchorSpec = {
+    /**
+     * Anchor type
+     */
+    type: AnchorId;
+    /**
+     * Options for the anchor.
+     */
+    options: AnchorOptions;
+};
+/**
+ * Models the specification of a single anchor.
+ * @group Edges
+ * @category Anchors
+ */
+export type SingleAnchorSpec = AnchorId | FullAnchorSpec | ObjectAnchorSpec;
+/**
+ * Models the specification of an anchor - which may be a SingleAnchorSpec, or an array of SingleAnchorSpec objects.
+ * @group Edges
+ * @category Anchors
+ */
+export type AnchorSpec = SingleAnchorSpec | Array<SingleAnchorSpec>;

package/types/ui/common/connector.d.ts

@@ -0,0 +1,106 @@
+import { Segment } from "./abstract-segment";
+import { PaintGeometry } from "../core/connector/abstract-connector";
+import { Extents, Geometry, PATH_CONSTRAIN_DIAGONAL, PATH_CONSTRAIN_MANHATTAN, PATH_CONSTRAIN_METRO, PATH_CONSTRAIN_NONE, PATH_CONSTRAIN_ORTHOGONAL } from "../../core";
+/**
+ * Common options for connectors.
+ * @group Edges
+ * @category Connectors
+ */
+export interface ConnectorOptions extends Record<string, any> {
+    /**
+     * Stub defines a number of pixels that the connector travels away from its element before the connector's actual path begins.
+     */
+    stub?: number;
+    /**
+     * Defines a number of pixels between the end of the connector and its anchor point. Defaults to zero.
+     */
+    gap?: number;
+    /**
+     * Optional class to set on the element used to render the connector.
+     */
+    cssClass?: string;
+    /**
+     * Optional class to set on the element used to render the connector when the mouse is hovering over the connector.
+     */
+    hoverClass?: string;
+}
+/**
+ * Alias for the use case that a Connector is referenced just by its `type`.
+ * @group Edges
+ * @category Connectors
+ */
+export type ConnectorId = string;
+/**
+ * Connector spec with type and options.
+ * @group Edges
+ * @category Connectors
+ */
+export type ConnectorWithOptions<T extends ConnectorOptions = ConnectorOptions> = {
+    /**
+     * Id of the connector
+     */
+    type: ConnectorId;
+    /**
+     * Options for the connector.
+     */
+    options: T;
+};
+/**
+ * Specification of a connector - either the type id of some Connector, a type+options object.
+ * @group Edges
+ * @category Connectors
+ */
+export type ConnectorSpec<T extends ConnectorOptions = ConnectorOptions> = ConnectorId | ConnectorWithOptions<T>;
+/**
+ * Used internally by connectors.
+ * @internal
+ */
+export type PaintAxis = "y" | "x";
+/**
+ * High level definition of a Connector.
+ * @group Edges
+ * @category Connectors
+ */
+export interface Connector {
+    /**
+     * The connector's type.
+     */
+    type: string;
+    typeDescriptor: string;
+    idPrefix: string;
+    /**
+     * Path for this connector. Written by the router, or a path editor. This is distinct from the edge geometry, in
+     * that this member is used as a BAU field, but edge geometry is only set when the edge path has been edited and
+     * we want to persist the changes.
+     * @internal
+     */
+    geometry: Geometry;
+    edited: boolean;
+    stub: number | number[];
+    sourceStub: number;
+    targetStub: number;
+    typeId: string;
+    gap: number;
+    sourceGap: number;
+    targetGap: number;
+    internalSegments: Array<Segment>;
+    totalLength: number;
+    segmentProportions: Array<[number, number]>;
+    segmentProportionalLengths: Array<number>;
+    paintInfo: PaintGeometry;
+    strokeWidth: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    quadrant: number;
+    bounds: Extents;
+    cssClass: string;
+    hoverClass: string;
+}
+/**
+ * Types of movement constrainment possible for a connector path.
+ * @group Edges
+ * @category Connectors
+ */
+export type ConnectorPathConstrainment = typeof PATH_CONSTRAIN_ORTHOGONAL | typeof PATH_CONSTRAIN_DIAGONAL | typeof PATH_CONSTRAIN_NONE | typeof PATH_CONSTRAIN_MANHATTAN | typeof PATH_CONSTRAIN_METRO;

package/types/ui/common/index.d.ts

@@ -0,0 +1,5 @@
+export * from './anchor';
+export * from './abstract-segment';
+export * from './connector';
+export * from './overlay';
+export * from "./paint-style";

package/types/ui/common/overlay.d.ts

@@ -0,0 +1,117 @@
+import { PaintStyle } from './paint-style';
+import { OverlayEvents, OverlayVisibility } from "../core/overlay/overlay";
+import { FontSpec } from "../../browser-ui";
+/**
+ * Base options for an overlay.
+ * @group Edges
+ * @category Constants
+ */
+export interface OverlayOptions extends Record<string, any> {
+    /**
+     * Optional ID for the overlay. Can be used to retrieve the overlay from a connection.
+     */
+    id?: string;
+    /**
+     * Optional CSS class(es) to add to the overlay's element.
+     */
+    cssClass?: string;
+    /**
+     * Defaults to 0.5. See docs.
+     */
+    location?: number;
+    /**
+     * 1 to point forwards (the default), -1 to point backwards. Only taken into consideration in some overlay types.
+     */
+    direction?: number;
+    /**
+     * Optional event handlers to attach to the overlay.
+     */
+    events?: Record<OverlayEvents, (value: any, event?: any) => any>;
+    /**
+     * Optional custom attributes to write to the overlay's element.
+     */
+    attributes?: Record<string, string>;
+    /**
+     * Whether the overlay is always visible, or only on hover. Defaults to OVERLAY_VISIBILITY_ALWAYS.
+     */
+    visibility?: OverlayVisibility;
+}
+/**
+ * Common options for subclasses of SimpleShapeOverlay
+ */
+export interface SimpleShapeOverlayOptions extends OverlayOptions {
+    /**
+     * Optional paint style to use.
+     */
+    paintStyle?: PaintStyle;
+    /**
+     * Defaults to false. When true, the arrow is stroked but not filled.
+     */
+    hollow?: boolean;
+}
+/**
+ * Options for an Arrow overlay.
+ * @group Edges
+ * @category Overlays
+ */
+export interface ArrowOverlayOptions extends SimpleShapeOverlayOptions {
+    /**
+     * Width of the arrow's baseline. Defaults to 20.
+     */
+    width?: number;
+    /**
+     * Length from the head to the baseline. Defaults to 20.
+     */
+    length?: number;
+    /**
+     * How far, as a decimal, along the line from head to baseline to fold back into. Defaults to 0.623.
+     */
+    foldback?: number;
+}
+/**
+ * @group Edges
+ * @category Overlays
+ */
+export interface LabelOverlayOptions extends OverlayOptions {
+    /**
+     * String, or a function returning a string, for the label.
+     */
+    label: string | Function;
+    /**
+     * Optional name of the attribute that identifies this overlay's location on the path. Defaults to `location`.
+     */
+    labelLocationAttribute?: string;
+    /**
+     * Whether or not to use an HTML element. Defaults to false (uses an SVG element)
+     */
+    useHTMLElement?: boolean;
+    /**
+     * Optional spec for the font to use on this label.
+     */
+    font?: FontSpec;
+}
+/**
+ * An overlay specified by name and options.
+ * @group Edges
+ * @category Overlays
+ */
+export type FullOverlaySpec = {
+    /**
+     * Overlay type
+     */
+    type: string;
+    /**
+     * Options for the overlay
+     */
+    options: OverlayOptions;
+};
+export type InternalOverlaySpec = FullOverlaySpec & {
+    sourceMarker?: boolean;
+    targetMarker?: boolean;
+};
+/**
+ * A specifier for an overlay.
+ * @group Edges
+ * @category Overlays
+ */
+export type OverlaySpec = string | FullOverlaySpec;

package/types/ui/common/paint-style.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Basic style definition for an edge
+ */
+export interface PaintStyle {
+    /**
+     * Stroke color for the edge
+     */
+    stroke?: string;
+    /**
+     * Fill color for the edge.
+     */
+    fill?: string;
+    /**
+     * Width of the stroke
+     */
+    strokeWidth?: number;
+    /**
+     * Color for the outline path
+     */
+    outlineStroke?: string;
+    /**
+     * Width of the outline path
+     */
+    outlineWidth?: number;
+    /**
+     * Definition for stroke pattern
+     */
+    dashArray?: string;
+    /**
+     * Definition of a linear gradient to apply. Each entry is [offset, color].
+     */
+    gradient?: Array<[number, string]>;
+}

package/types/ui/connector-bezier/abstract-bezier-connector.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The bezier connector's internal representation of a path.
+ */
+import { Connector, ConnectorOptions, ConnectorPathConstrainment } from "../common";
+import { Connection } from "../core/connector/connection-impl";
+import { PointXY, BaseGeometrySegment, Geometry } from "../../core";
+export interface BezierGeometrySegment extends BaseGeometrySegment {
+    cp1: PointXY;
+    cp2: PointXY;
+}
+/**
+ * Defines the geometry used by a cubic bezier connector.
+ * @group Edges
+ * @category Connectors
+ */
+export interface BezierConnectorGeometry extends Geometry {
+    segments: Array<BezierGeometrySegment>;
+}
+/**
+ * This is the default location of a Cubic Bezier connector's control point, relative to the distance between the two anchors. It is used as the default value for the Bezier connector's "scale". A larger value will make the
+ * connector "curvier".
+ * @group Connectors
+ * @category Bezier
+ * @internal
+ */
+export declare const DEFAULT_BEZIER_CONTROL_POINT_SCALE = 0.45;
+/**
+ * The default distance the control point will be placed at for a bezier curve when the source and target are the same
+ * element.
+ * @group Connectors
+ * @category Bezier
+ * @internal
+ */
+export declare const DEFAULT_BEZIER_LOOPBACK_DISTANCE = 62;
+/**
+ * Base options interface for Quadratic and Cubic Bezier connectors.
+ * @group Edges
+ * @category Connectors
+ */
+export interface AbstractBezierOptions extends ConnectorOptions {
+    proximityLimit?: number;
+    orientation?: string;
+    /**
+     * When the connector's source and target is the same vertex, this is a measure of how far the control point will
+     * be placed from the element. Defaults to 62 pixels
+     */
+    loopbackDistance?: number;
+}
+/**
+ * @internal
+ */
+export interface BezierConnectorBase extends Connector {
+    curviness: number;
+    proximityLimit: number;
+    orientation: string;
+    loopbackDistance: number;
+    clockwise: boolean;
+    isLoopbackCurrently: boolean;
+    geometry: BezierConnectorGeometry;
+    constrain: ConnectorPathConstrainment;
+    smooth: boolean;
+}
+/**
+ * @param connection
+ * @param params
+ * @internal
+ */
+export declare function createAbstractBezierConnector(type: string, connection: Connection<any>, params: AbstractBezierOptions): BezierConnectorBase;