@visuallyjs/browser-ui 1.0.0

package/types/browser-ui/definitions.d.ts

@@ -0,0 +1,442 @@
+import { BrowserElement } from "./util";
+import { BoundingBox, Edge, Group, Node, ObjectData, Port, Vertex, VisuallyJsModel, VisuallyJsSelection } from "../core";
+import { PointXY, Size } from "../core";
+import { UICoreDefaults, UICoreOptions, UIEdgeOptions, DragOptions, Overlay, Connection, EdgePropertyMappings, AlignContentOptions } from "../ui";
+import { EdgeInputMethod } from "./edge-input-handler";
+import { ShapeLibrary, ShapeSet } from "./shape-library/shape-library-definitions";
+import { VisuallyJSDOMElement } from "./element-facade";
+import { VertexMapping } from "../ui";
+import { BrowserUI } from "./browser-visuallyjs-instance";
+import { ConnectorEditorActivateParams } from "./connector-editor";
+/**
+ * Defines a function used to filter drop on a canvas
+ * @group Components
+ * @category Palette
+ */
+export type CanvasDropFilter<T> = (data: T) => boolean;
+/**
+ * Defines a function used to filter drop on an edge.
+ * @group Components
+ * @category Palette
+ */
+export type EdgeDropFilter<T> = (data: T, target: Edge) => boolean;
+/**
+ * Defines the callback function invoked when an item is being dragged.
+ * @group Components
+ * @category Palette
+ */
+export type DragFunction<T> = (data: T, el: BrowserElement, e: Event) => any;
+/**
+ * Defines the function invoked when an item is dropped onto an existing vertex.
+ * @group Components
+ * @category Palette
+ */
+export type DropFunction<T> = (data: T, target: Node | Group, draggedElement?: BrowserElement, e?: Event, position?: PointXY, canvasLocation?: PointXY, targetLocation?: PointXY, locationOnTarget?: PointXY) => void;
+/**
+ * Defines the function invoked when an item is dropped on an edge.
+ * @group Components
+ * @category Palette
+ */
+export type EdgeDropFunction<T> = (data: T, target: Edge, draggedElement?: BrowserElement, e?: Event, position?: PointXY, canvasLocation?: PointXY) => void;
+/**
+ * Defines the function invoked when an item is dropped onto whitespace in the canvas.
+ * @group Components
+ * @category Palette
+ */
+export type CanvasDropFunction<T> = (data: T, canvasPosition: PointXY, draggedElement?: BrowserElement, e?: Event, position?: PointXY, elementSize?: Size) => void;
+/**
+ * Defines the function that is invoked to gather a dataset to associate with an item that is being dragged.
+ * @group Components
+ * @category Palette
+ * @typeParam T Defines the type of the object that will be created.
+ */
+export type DataGeneratorFunction<T> = (el: BrowserElement) => T;
+/**
+ * Defines the function invoked to determine the type of some item that is about to be dragged.
+ * @group Components
+ * @category Palette
+ * @typeParam T Defines the kind of the object from which to extract the type id.
+ */
+export type TypeGeneratorFunction<T> = (d: T) => string;
+/**
+ * Defines the function that is invoked to determine whether an item that is about to be dragged represents a group.
+ * @group Components
+ * @category Palette
+ * @typeParam T Defines the kind of the associated data object.
+ */
+export type GroupIdentifierFunction<T> = (d: T, el: BrowserElement) => boolean;
+/**
+ * Defines the method signature for the `onVertexAdded` callback.
+ * @group Components
+ * @category Palette
+ */
+export type OnVertexAddedCallback = (p: {
+    vertex: Node | Group;
+    dropTarget?: DropTargetInfo;
+    doModelUpdate: ModelUpdateFunction;
+}) => any;
+/**
+ * Defines a function you can call from a vertex added callback to run some model updates that will be included in the same transaction as the one that just added the new vertex. You pass a function in to this method, which contains the model updates you wish to make. Your update function will be passed the UI, its model, and any `context` you provided as a second argument when you called doModelUpdate inside the vertex added callback.
+ */
+export type ModelUpdateFunction = (updateFunction: (ui: BrowserUI, model: VisuallyJsModel, context?: any) => any) => void;
+/**
+ * When a new vertex was dropped onto an existing vertex, the onVertexAdded callback is passed an object of this type to describe the vertex onto which the new vertex was dropped.
+ * @group Components
+ * @category Palette
+ */
+export type DropTargetInfo = {
+    /**
+     * The vertex onto which a new vertex was dropped
+     */
+    vertex: Node | Group;
+    /**
+     * Position the existing  vertex is located at
+     */
+    pos: PointXY;
+    /**
+     * Size of the existing vertex
+     */
+    size: Size;
+};
+/**
+ * Definition of a drag group membership - either just the id of a drag group, or the id of a drag group and whether or not
+ * this element plays an `active` role in the drag group.
+ *
+ * @group Components
+ * @category Element dragging
+ */
+export type DragGroupSpec = string | {
+    id: string;
+    active: boolean;
+};
+/**
+ * Models some discrete object whose class, in the UI, can be manipulated. This can be an edge/vertex, an element in the UI, or the ID of some edge/vertex.
+ */
+export type SupportsClassManipulationElement = Edge | Vertex | BrowserElement | string;
+/**
+ * List of object whose css class, in the UI, can be manipulated. This means either some object that itself satisfies {@link SupportsClassManipulationElement}, or an array of these, or a NodeList of DOM elements.
+ */
+export type SupportsClassManipulation = SupportsClassManipulationElement | ArrayLike<SupportsClassManipulationElement> | NodeListOf<any>;
+/**
+ * Common options for edges in the Browser UI package.
+ * @group Edges
+ * @category Options
+ */
+export interface BrowserUIEdgeOptions extends UIEdgeOptions {
+    /**
+     * Optional set of mappings from property values to edge definitions.
+     */
+    propertyMappings?: EdgePropertyMappings;
+    /**
+     * If true, an EdgePathEditor will be registered on the Surface, with which you can interact via the `startEditingPath(..)` and `stopEditingPath()` methods on the Surface.
+     */
+    editable?: boolean;
+    /**
+     * Defaults to true, meaning if edges are editable then any new edge is automatically marked edited and its geometry is stored.
+     */
+    activeEdit?: boolean;
+    /**
+     * Input method for edges. Defaults to drag.
+     */
+    inputMethod?: EdgeInputMethod;
+    /**
+     * Defaults to true, meaning that when a user taps an edge it goes into edit mode.
+     */
+    editOnTap?: boolean;
+    /**
+     * This setting is only relevant when you are using an SVG container. By default, edges are drawn in a layer that appears in the DOM after the vertex layer, meaning edges will show above vertices. If you set this to 0, you can force the edge layer to the back.
+     */
+    layerIndex?: number;
+}
+/**
+ * Base options for a renderer in the Browser UI package.
+ * @group Components
+ * @category Options
+ */
+export interface BrowserUIOptions<O extends BrowserUIDefaults = BrowserUIDefaults> extends UICoreOptions<BrowserElement, O> {
+    /**
+     * Whether or not the elements in the UI should be draggable. Defaults to true.
+     */
+    elementsDraggable?: boolean;
+    /**
+     * Options for edges
+     */
+    edges?: BrowserUIEdgeOptions;
+    /**
+     * Options for dragging vertices.
+     */
+    dragOptions?: DragOptions<BrowserElement>;
+    /**
+     * Optional shape library that can render SVG shapes into node elements. When you provide a shape library to a surface, two things happen: - firstly, the surface registers a `vjs-shape` tag that your templates can use. The `type` of each node is used to extract an appropriate SVG shape definition from the shape library. Secondly, the 'exportToSvg()' method becomes available. Note that SVG export has a few constraints/requirements - see the docs for a discussion.
+     */
+    shapes?: ShapesOptions;
+    /**
+     * Defaults to false. When true, VisuallyJs will use an SVG element as the container for all the other elements. You will need to ensure your templates/components write out SVG elements, and you will have to stick to SVG elements in any Decorators. You may wish to consider looking at the {@link Diagram} class if you want to build an SVG diagram.
+     */
+    useSvgContainer?: boolean;
+    /**
+     * Optional Selection - or generator - to use as the dataset to render. If you supply this the Surface will render the contents of the selection, or the list of vertices that the given function returns. This is useful for such things as inspector windows for parts of your UI.
+     */
+    selection?: VisuallyJsSelection | Function;
+    /**
+     * Whether or not to consume right clicks, which ordinarily will cause a browser to show a context menu with some native browser functions. This defaults to true.
+     */
+    consumeRightClick?: boolean;
+    /**
+     * When using 'vanilla' VisuallyJs, you can provide a map of templates here rather than including them somewhere in the HTML of the page. This is ignored when you are using a library integration.
+     */
+    templates?: Record<string, string>;
+}
+/**
+ * Options for a shape library, for use with a Surface or Paper component.
+ * @group Components
+ * @category Options
+ */
+export interface ShapesOptions {
+    /**
+     * The shape library to use. You must provide either this or `sets`.
+     */
+    library?: ShapeLibrary<ObjectData>;
+    /**
+     * List of shape sets - or a single set - to support. Provide this or `library`. If you provide `library` and this, `library` will take precedence.
+     */
+    sets?: ShapeSet | Array<ShapeSet>;
+    /**
+     * Optional default for fill color. If not provided, fill is set to #FFFFFF.
+     */
+    defaultFillColor?: string;
+    /**
+     * Optional default for outline color. If not provided, outline is set to #000000.
+     */
+    defaultOutlineColor?: string;
+    /**
+     * Optional default for text color. If not provided, text is set to #000000.
+     */
+    defaultColor?: string;
+    /**
+     * The property to use to map an object's type. Defaults to "type".
+     */
+    typeParameter?: string;
+    /**
+     * The property to use to map an object's category (ie which shape set to use). Defaults to "category".
+     */
+    categoryParameter?: string;
+    /**
+     * Defaults to true - labels are split across multiple lines to fit inside their shape. Set this to false if you want labels to always be a single line.
+     */
+    multilineLabels?: boolean;
+    /**
+     * How much of the width of a shape a multiline label will take up before wrapping. Defaults to 0.8. You can set this to a number greater than 1, if you like, but that will allow the label to overflow.
+     */
+    labelFillRatio?: number;
+    /**
+     * The attribute containing each vertex's label. Defaults to 'label'
+     */
+    labelAttribute?: string;
+    /**
+     * Whether or not to show labels. Defaults to true.
+     */
+    showLabels?: boolean;
+    /**
+     * Stroke width to use when drawing svg shapes.
+     */
+    strokeWidth?: number;
+    /**
+     * The name of the tag to make available to node/group renderers. Defaults to `vjs-shape`. Only used with certain advanced usages of Vanilla VisuallyJs. If you're using an integration there's a dedicated shape component you will use instead.
+     * @advanced
+     */
+    tagName?: string;
+    /**
+     * Optional spec for font size/style to apply to all shapes. Shapes that have their own font spec will override this.
+     */
+    font?: FontSpec;
+}
+/**
+ * Defaults for the BrowserUI implementation of VisuallyJs.
+ * @group Components
+ * @category Defaults
+ */
+export interface BrowserUIDefaults extends UICoreDefaults<BrowserElement> {
+    /**
+     * Whether or not elements should be draggable. Default value is `true`.
+     */
+    elementsDraggable?: boolean;
+    /**
+     * Defaults to true, indicating that a ResizeObserver will be used, where available, to allow VisuallyJs to revalidate elements whose size in the DOM have been changed, without the library user having to call `revalidate()`
+     */
+    resizeObserver?: boolean;
+    /**
+     * Defaults to false. When true, VisuallyJs tracks mouseover/mouseout/mouseenter/mouseexit events for overlays, endpoints, elements and connections. Most of the reasoning for having this ability was related to the initial canvas renderer, and with SVG/CSS this functionality is, for the most part, not needed. But you can switch it on if you need to.
+     */
+    hoverEvents?: boolean;
+    useSvgContainer?: boolean;
+}
+/**
+ * @internal
+ */
+export interface UIComponent {
+    canvas: HTMLElement;
+    svg: SVGElement;
+}
+/**
+ * @internal
+ */
+export type ElementModelInfo = {
+    /**
+     * the port/node/group we're referencing
+     */
+    obj: Vertex;
+    /**
+     * if obj is a port, this is its parent. Otherwise this is the same as obj.
+     */
+    vertex: Node | Group;
+    /**
+     * corresponding type def for this vertex definition
+     */
+    typeDef: VertexMapping<any, BrowserElement>;
+    /**
+     * can be used for all vertex types - we get info from the view matching this port type
+     */
+    portType: string;
+    /**
+     * optional ID of the port.
+     */
+    portId: string;
+    /**
+     * DOM element corresponding to `vertex`
+     */
+    vertexEl: VisuallyJSDOMElement;
+    /**
+     * DOM element corresponding to `obj`
+     */
+    objEl: BrowserElement;
+    /**
+     * if true, this port was just created automatically, by a `getPort` call that had `createMissingPorts:true`
+     */
+    missingPortCreated: boolean;
+};
+/**
+ * @internal
+ */
+export interface VisuallyJsDOMInformation {
+    connection?: Connection<any>;
+    overlay?: Overlay<BrowserElement>;
+    node?: Node;
+    group?: Group;
+    port?: Port;
+    vertex?: Vertex;
+}
+/**
+ * @internal
+ */
+export interface InternalBackgroundOptions<T> {
+    type: string;
+    canvas: BrowserElement;
+    viewport: BrowserElement;
+    ui: BrowserUI;
+    options: T;
+    visible: boolean;
+}
+/**
+ * Definition of a Background. This is an internal class that users of the SDK won't need to access unless they are writing their own background type.
+ * @internal
+ */
+export interface Background {
+    setZoom(zoom: number, doNotDebounce?: boolean): void;
+    getWidth(): number;
+    getHeight(): number;
+    owns(el: any): boolean;
+    pan(): void;
+    destroy(): void;
+    _setVisible(v: boolean): void;
+}
+/**
+ * @internal
+ */
+export interface ImageBackground extends Background {
+    setUrl(url: string): void;
+}
+/**
+ * Style for a font - oblique, italic or normal.
+ */
+export type FontStyle = "normal" | "oblique" | "italic";
+/**
+ * Font weight to use (e.g., "normal", "bold", "100", "300").
+ */
+export type FontWeight = string | number;
+/**
+ * Specs for a font. The default values depend on the context.
+ */
+export interface FontSpec {
+    /**
+     * Size of the font. Default value depends on the context this spec occurs in.
+     */
+    size?: number;
+    /**
+     * Font style to use. Default value depends on the context this spec occurs in.
+     */
+    style?: FontStyle;
+    /**
+     * Font weight to use (e.g., "normal", "bold", "100", "300"). Defaults to null, which browsers treat as "normal".
+     */
+    weight?: FontWeight;
+    /**
+     * Font family to use.
+     */
+    family?: string;
+}
+export declare function supportsPathEditing(o: any): o is SupportsPathEditing;
+/**
+ * Definition of a UI that supports path editing
+ */
+export interface SupportsPathEditing {
+    /**
+     * Start editing the given edge or connection.
+     */
+    startEditingPath<T extends ConnectorEditorActivateParams<BrowserElement>>(edgeOrConnection: Edge | Connection<BrowserElement>, params?: T): void;
+    /**
+     * Stop editing any connector paths.
+     */
+    stopEditingPath(): void;
+    /**
+     * Clear the edits for the given connection.
+     */
+    clearPathEdits(edgeOrConnection: string | Edge | Connection<BrowserElement>): boolean;
+}
+/**
+ * Options for the zoomToExtents method
+ */
+export interface ZoomToExtentsOptions {
+    /**
+     * Extents to zoom to. Can be a single box or an array of boxes; in the latter case VisuallyJs will calculate a minimum bounding box for all the boxes provided.
+     */
+    extents: BoundingBox | Array<BoundingBox>;
+    /**
+     * A decimal between 0 and 1, which indicates how much of the viewport size the given extents will take up. This value is applied as a ratio of the width or height of the viewport - whichever is smaller. The default is 0.9.
+     */
+    fill?: number;
+    /**
+     * If the given extents is all already visible, do not make any changes to zoom.
+     */
+    doNotZoomIfVisible?: boolean;
+    /**
+     * If true, don't animate while centering. Defaults to false, ie. the operation will be animated.
+     */
+    doNotAnimate?: boolean;
+    /**
+     * Optional function to call on operation complete.
+     */
+    onComplete?: (p: PointXY) => any;
+    /**
+     * @internal
+     */
+    doNotFirePanEvent?: boolean;
+}
+export interface SupportsViewportManipulation {
+    setPan(x: number, y: number, animate?: boolean): void;
+    setZoom(zoom: number, animate?: boolean): number;
+    centerOn(element: string | Vertex | Element): void;
+    centerOnAndZoom(element: string | Vertex | Element, fillRatio?: number): void;
+    alignContent(options: AlignContentOptions): void;
+    zoomToExtents(zParams: ZoomToExtentsOptions): void;
+}

package/types/browser-ui/dialogs/binder.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Searches children of the given element to find elements that have a `vjs-att` set. For each of those, if the `checkValidity` method is defined,
+ * this method executes it. If it returns false, this method returns false. If no elements have `checkValidity` or no `checkValidity()` call
+ * returns false, this method returns true.
+ *
+ * `checkValidity` is a method defined in input elements and textareas, when a `pattern` is defined on the element (or if it is marked
+ * required and has no valuer set)
+ * @param el
+ * @internal
+ */
+export declare function checkValidity(el: HTMLElement): boolean;
+/**
+ * Extracts a dataset from the given element by finding child elements that have a `vjs-att` attribute set, and extracting from those elements
+ * their value. When the same `vjs-att` value appears more than once as a child of `el`, the values are stored in an array for that field.
+ * @param el - Element to extract values from.
+ * @param unresolvedElementGetter - Optional function to use when an element with an unknown tag has a `vjs-att` declared on it. This function is given the element and whatever it
+ * returns - even null - will be set on the outgoing data.
+ * @internal
+ */
+export declare function extract(el: HTMLElement, unresolvedElementGetter?: (el: Element) => any): Record<string, any>;
+type SupportedCoercion = "integer" | "float";
+/**
+ * @internal
+ * @param value
+ * @param datatype
+ */
+export declare function attemptCoerce(value: string, datatype: SupportedCoercion): any;
+/**
+ * Extract the value represented by the given element.
+ * @param el - Element to extract value from.
+ * @param unresolvedElementGetter- Optional function to use when an element with an unknown tag has a `vjs-att` declared on it. This function is given the element and whatever it
+ * returns - even null - will be the return value.
+ * @internal
+ */
+export declare function extractValueFromElement(el: HTMLElement, unresolvedElementGetter?: (el: Element) => any): any;
+/**
+ * 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`.
+ * @param dataset
+ * @param el
+ * @param autoCommitHandler
+ * @internal
+ */
+export declare function apply(dataset: Record<string, any>, el: any, autoCommitHandler?: (e: Element) => any, unresolvedElementSetter?: (e: Element, value: any) => any): void;
+/**
+ * @internal
+ */
+export declare function clear(els: ArrayLike<any>, source?: any): void;
+export {};

package/types/browser-ui/dialogs/constants.d.ts

@@ -0,0 +1,51 @@
+export declare const DialogConstants: {
+    Attributes: {
+        POSITION: string;
+        AXIS: string;
+        VJS_CANCEL: string;
+        VJS_COMMIT: string;
+        MULTIPLE: string;
+        VJS: string;
+        DATATYPE: string;
+        TITLE: string;
+        FOCUS: string;
+        TYPE: string;
+        CANCEL: string;
+        ID: string;
+    };
+    Values: {
+        BLOCK: string;
+        VISIBLE: string;
+        HIDDEN: string;
+        FIXED: string;
+        ABSOLUTE: string;
+        TOP: string;
+        BOTTOM: string;
+        X: string;
+        Y: string;
+        TRUE: string;
+        FALSE: string;
+        NONE: string;
+        PX: string;
+    };
+    Events: {
+        RESIZE: string;
+        CLICK: string;
+        KEYUP: string;
+        SCROLL: string;
+    };
+    Elements: {
+        BUTTON: string;
+        DIV: string;
+        TEXT: string;
+        RADIO: string;
+        CHECKBOX: string;
+        SELECT: string;
+        TEXTAREA: string;
+        COLOR: string;
+        HIDDEN: string;
+        INPUT: string;
+        NUMBER: string;
+        RANGE: string;
+    };
+};

package/types/browser-ui/dialogs/dialogs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Defines the function called when a user commits a dialog.
+ * @group Components
+ * @category Dialogs
+ */
+export type CommitFunction = (data: Record<string, any>) => any;
+/**
+ * Defines the function called when a user cancels a dialog.
+ * @group Components
+ * @category Dialogs
+ */
+export type CancelFunction = () => any;
+/**
+ * Defines the callback invoked when a dialog has opened
+ * @group Components
+ * @category Dialogs
+ */
+export type OpenFunction = (el: HTMLElement) => any;
+/**
+ * Defines the interceptor invoked prior to a user closing a Dialog, to allow you to allow or reject the operation
+ * @group Components
+ * @category Dialogs
+ */
+export type MaybeCloseFunction = (data: any) => boolean;
+/**
+ * Defines the function invoked after a Dialog has closed.
+ * @group Components
+ * @category Dialogs
+ */
+export type CloseFunction = () => any;

package/types/browser-ui/dialogs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './binder';
+export * from './dialogs';
+export * from './constants';

package/types/browser-ui/drag-manager-2.d.ts

@@ -0,0 +1,54 @@
+/**
+ * This class manages multiple drag handlers on some container element. Each handler is registered with a CSS selector
+ * and optionally a priority. The manager class captures mousedown events on the container and then searches for
+ * an appropriate handler to pass the event to, but matching the selectors each handler declares. When a matching selector
+ * is found, all of the handlers for that selector are iterated by order of their priority, and the first one that does
+ * not return boolean false from the mousedown event (I might call this `start` in fact) becomes the current handler.
+ *
+ * Mousemove and mouseup handlers are then registered on the document, and move events are passed to the current handler.
+ * when the mouseup event occurs it is passed to the handler and the manager stops the drag process.
+ */
+import { BrowserElement } from "./util";
+import { DragHandler2 } from "../ui";
+import { PointXY } from "../core";
+export interface DragManager2Options {
+    translate?: (p: PointXY) => PointXY;
+    init: (e: Event) => void;
+}
+export declare class DragManager2 {
+    private container;
+    private _enabled;
+    private _eventManager;
+    private readonly _mousedownHandler;
+    private readonly _mousemoveHandler;
+    private readonly _mouseupHandler;
+    private _currentHandler;
+    private _currentDragPayload;
+    private _currentDragElement;
+    private _currentDragElementSize;
+    private _handlers;
+    private _selectors;
+    private _downAt;
+    private _currentPagePosition;
+    private _translatedDownAt;
+    private _currentTranslatedPosition;
+    private _translate;
+    private _onInit;
+    constructor(container: BrowserElement, options?: DragManager2Options);
+    $enable(): void;
+    $disable(): void;
+    addHandler(handler: DragHandler2<BrowserElement>): void;
+    removeHandler(handler: DragHandler2<BrowserElement>): void;
+    private _mousedownListener;
+    private _mousemoveListener;
+    private _mouseupListener;
+    /**
+     * Cleanup the manager's internal state.
+     * @private
+     */
+    private _cleanup;
+    /**
+     * Destroy the drag manager - remove its event binding on the container and clean up its internal state.
+     */
+    destroy(): void;
+}