@linkurious/ogma-annotations 1.0.5

package/dist/types/Control.d.ts

@@ -0,0 +1,104 @@
+import Ogma from '@linkurious/ogma';
+import EventEmitter from 'eventemitter3';
+import { Annotation, AnnotationCollection, Arrow, ControllerOptions, FeatureEvents, Id, Text } from './types';
+export declare class Control extends EventEmitter<FeatureEvents> {
+    private arrows;
+    private texts;
+    private links;
+    private layer;
+    private annotations;
+    private ogma;
+    private options;
+    private selected;
+    private updateTimeout;
+    private hoveredNode;
+    private dragged;
+    private textToMagnet;
+    private activeLinks;
+    constructor(ogma: Ogma, options?: Partial<ControllerOptions>);
+    private _render;
+    private _onFeatureDrag;
+    private _onFeatureDragEnd;
+    private _onFeatureDragStart;
+    private _onNodesDragStart;
+    private _onNodesDrag;
+    private _moveNodes;
+    private _snapToText;
+    private _findAndSnapToNode;
+    private _snapToNode;
+    private _onAdded;
+    private _onRemoved;
+    private _onUnselect;
+    private _onSelect;
+    /**
+     * @returns the currently selected annotation
+     */
+    getSelected(): Annotation | null;
+    private findMagnetPoint;
+    /**
+     * Set the options for the controller
+     * @param options new Options
+     * @returns the updated options
+     */
+    setOptions(options?: Partial<ControllerOptions>): ControllerOptions;
+    /**
+     * Selects the annotation with the given id
+     * @param id the id of the annotation to select
+     */
+    select(id: Id): this;
+    /**
+     * Unselects the currently selected annotation
+     */
+    unselect(): this;
+    /**
+     * Add an annotation to the controller
+     * @param annotation The annotation to add
+     */
+    add(annotation: Arrow | Text | AnnotationCollection): this;
+    private loadLink;
+    /**
+     * Start adding an arrow (add it, and give control to the user)
+     * @param x coord of the first point
+     * @param y coord of the first point
+     * @param arrow The arrow to add
+     */
+    startArrow(x: number, y: number, arrow?: Arrow): void;
+    /**
+     * Start adding a text (add it, and give control to the user)
+     * @param x coord of the top left point
+     * @param y coord of the top left point
+     * @param text The text to add
+     */
+    startText(x: number, y: number, text?: Text): void;
+    /**
+     * Cancel drawing on the current frame
+     */
+    cancelDrawing(): void;
+    /**
+     * Triggers the update event on the annotation
+     * @param annotation The annotation updated
+     */
+    onUpdate: (annotation: Annotation) => void;
+    private _onUpdate;
+    /**
+     * Update the style of the annotation with the given id
+     * @param id The id of the annotation to update
+     * @param style The new style
+     */
+    updateStyle<A extends Annotation>(id: Id, style: A['properties']['style']): this;
+    /**
+     *
+     * @returns the annotations in the controller
+     */
+    getAnnotations(): AnnotationCollection;
+    /**
+     * Retrieve the annotation with the given id
+     * @param id the id of the annotation to get
+     * @returns The annotation with the given id
+     */
+    getAnnotation(id: Id): Arrow | Text | undefined;
+    /**
+     * Destroy the controller and its elements
+     */
+    destroy(): void;
+}

package/dist/types/Editor/Arrows/defaults.d.ts

@@ -0,0 +1,10 @@
+import { Arrow, ArrowStyles } from '../../types';
+export declare const defaultStyle: ArrowStyles;
+export declare const defaultOptions: Arrow;
+export declare const createArrow: (x0?: number, y0?: number, x1?: number, y1?: number, styles?: {
+    tail?: import("../../types").Extremity | undefined;
+    head?: import("../../types").Extremity | undefined;
+    strokeType?: "none" | "plain" | "dashed" | undefined;
+    strokeColor?: string | undefined;
+    strokeWidth?: number | undefined;
+}) => Arrow;

package/dist/types/Editor/Arrows/index.d.ts

@@ -0,0 +1,38 @@
+import Ogma, { Point } from '@linkurious/ogma';
+import { createArrow, defaultOptions, defaultStyle } from './defaults';
+import { Arrow, ControllerOptions } from '../../types';
+import Editor from '../base';
+/**
+ * @class Arrows
+ * Draw and edit arrows
+ */
+export declare class Arrows extends Editor<Arrow> {
+    private draggedHandle;
+    private start;
+    private end;
+    private arrow;
+    private startX;
+    private startY;
+    private minArrowHeight;
+    private maxArrowHeight;
+    private handles;
+    constructor(ogma: Ogma, options?: Pick<Partial<ControllerOptions>, 'arrowHandleSize' | 'maxArrowHeight' | 'minArrowHeight'>);
+    private onHandleMouseDown;
+    /**
+     * Start drawing a new arrow, it will also be added as a new annotation
+     * @param x
+     * @param y
+     * @param arrow
+     */
+    startDrawing(x: number, y: number, arrow?: Arrow): void;
+    cancelDrawing(): void;
+    private startDragging;
+    private onMouseUp;
+    private onMouseMove;
+    detect(point: Point, margin?: number): Arrow | undefined;
+    refreshEditor(): void;
+    getDefaultOptions(): Arrow;
+    draw(svg: SVGSVGElement): void;
+    destroy(): void;
+}
+export { defaultOptions as defaultArrowOptions, defaultStyle as defaultArrowStyle, createArrow };

package/dist/types/Editor/Arrows/render.d.ts

@@ -0,0 +1,13 @@
+import { Arrow, ArrowStyles } from '../../types';
+/**
+ * @function getArrowHeight
+ * @param arrow The arrow to measure
+ * @returns The height of the bounding box of the arrow
+ */
+export declare function getArrowHeight(arrow: Arrow, min?: number, max?: number): number;
+/**
+ * @function draw
+ * @param arrow The arrow to draw
+ * @param g the group in which to draw
+ */
+export default function draw(arrow: Arrow, g: SVGGElement, defaultStyle: ArrowStyles, minArrowHeight: number, maxArrowHeight: number): void;

package/dist/types/Editor/Texts/defaults.d.ts

@@ -0,0 +1,5 @@
+import { AnnotationOptions, Text, TextStyle } from '../../types';
+export declare const defaultStyle: TextStyle;
+export declare const defaultOptions: Text;
+export declare const defaultControllerOptions: AnnotationOptions;
+export declare const createText: (x?: number, y?: number, width?: number, height?: number, content?: string, styles?: Partial<TextStyle>) => Text;

package/dist/types/Editor/Texts/index.d.ts

@@ -0,0 +1,40 @@
+import Ogma, { Point } from '@linkurious/ogma';
+import { createText, defaultControllerOptions, defaultOptions, defaultStyle } from './defaults';
+import { ControllerOptions, Id, Text } from '../../types';
+import Editor from '../base';
+/**
+ * @class Texts
+ * Draw, update, edit texts
+ */
+export declare class Texts extends Editor<Text> {
+    private textArea;
+    private handleSize;
+    private rect;
+    private annotation;
+    private startX;
+    private startY;
+    private handles;
+    private draggedHandle;
+    private isFocused;
+    private placeholder;
+    constructor(ogma: Ogma, options?: Pick<Partial<ControllerOptions>, 'textHandleSize' | 'textPlaceholder'>);
+    private _onFocus;
+    private _onBlur;
+    protected _canRemove(): boolean;
+    startDrawing: (x: number, y: number, text?: Text) => void;
+    cancelDrawing: () => void;
+    private startDragging;
+    private onHandleMouseDown;
+    private onMouseMove;
+    private _onMouseMove;
+    private onMouseUp;
+    private onViewChanged;
+    private _onInput;
+    detect({ x, y }: Point, margin?: number): Text | undefined;
+    draw(svg: SVGSVGElement): void;
+    getDefaultOptions(): Text;
+    refreshEditor(): void;
+    select(id: Id): void;
+    destroy(): void;
+}
+export { defaultOptions as defaultTextOptions, defaultStyle as defaultTextStyle, defaultControllerOptions, createText };

package/dist/types/Editor/Texts/render.d.ts

@@ -0,0 +1,7 @@
+import { Text } from '../../types';
+/**
+ * @function draw
+ * @param annotation the annotation to draw
+ * @param g the group in which the text should be drawn
+ */
+export default function draw(annotation: Text, g: SVGGElement): void;

package/dist/types/Editor/base.d.ts

@@ -0,0 +1,81 @@
+import Ogma, { Options, Overlay, Point, SVGLayer } from '@linkurious/ogma';
+import eventEmmitter from 'eventemitter3';
+import { Annotation, Events, Id } from '../types';
+/**
+ * @class Annotations
+ * Abstract class to display Texts and Arrows, provide add/remove/update and mouse events
+ * Modifying annotation is handled by the child classes, it is too specific
+ */
+export default abstract class Editor<T extends Annotation> extends eventEmmitter<Events<T>> {
+    protected ogma: Ogma;
+    protected elements: T[];
+    protected layer: SVGLayer;
+    protected editor: Overlay;
+    protected selectedId: Id;
+    protected hoveredId: Id;
+    protected ogmaOptions: Options;
+    protected shouldDetect: boolean;
+    protected isDragging: boolean;
+    constructor(ogma: Ogma, editorHtml: string);
+    private _onKeyUp;
+    protected _canRemove(): boolean;
+    private _onClickMouseMove;
+    /**
+     * @method add
+     * @param options Params for the annotation (merged with default)
+     * @returns the added annotation
+     */
+    add(options: T): T;
+    updateStyle(annotation: T, style: Partial<T['properties']['style']>): void;
+    updateGeometry(annotation: T, geometry: Partial<T['geometry']>): void;
+    /**
+     * @method update
+     * Updates an annotation (position, color etc)
+     * @param id Id of the annotation to update
+     * @param new params of the annotation
+     */
+    update(id: Id, element: Partial<T>): void;
+    updateAnnotation(target: T, element: Partial<T>): void;
+    getById(id: Id): T;
+    /**
+     * @method select
+     * @param id id of the element to select
+     * Select element, show editor, disable Ogma dragging and fire event
+     */
+    select(id: Id): void;
+    hover(id: Id): void;
+    getSelectedFeature(): T | null;
+    unselect(): this;
+    unhover(): this;
+    /**
+     * @method remove
+     * @param id Id of the annotation to remove
+     * Removes annotation with the given id
+     */
+    remove(id: Id): void;
+    /**
+     * @method disableDragging
+     * Prevents Ogma from dragging elements or moving the view while dragging an annotation
+     */
+    disableDragging(): void;
+    /**
+     * @method restoreDragging
+     * restore ogma options as they were before we start dragging an annotation
+     */
+    restoreDragging(): void;
+    enableDetection(): void;
+    /**
+     * @method disableDetection
+     * Disables the hover behaviour, used by controller to avoid hovering
+     * arrows while dragging texts and vice versa
+     */
+    disableDetection(): void;
+    refreshLayer(): void;
+    getElements(): T[];
+    abstract refreshEditor(): void;
+    abstract draw(svg: SVGSVGElement): void;
+    abstract cancelDrawing(): void;
+    abstract getDefaultOptions(): T;
+    abstract detect(point: Point, margin: number): T | undefined;
+    destroy(): void;
+}

package/dist/types/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const NONE = -1;
+export declare const EVT_DRAG = "dragging";
+export declare const EVT_DRAG_START = "dragstart";
+export declare const EVT_DRAG_END = "dragend";
+export declare const EVT_SELECT = "select";
+export declare const EVT_UNSELECT = "unselect";
+export declare const EVT_HOVER = "hover";
+export declare const EVT_UNHOVER = "unhover";
+export declare const EVT_REMOVE = "remove";
+export declare const EVT_ADD = "add";
+export declare const EVT_CANCEL_DRAWING = "cancelDrawing";
+export declare const EVT_UPDATE = "update";
+export declare const EVT_LINK = "link";

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+import './style.css';
+export * from './Editor/Arrows';
+export * from './Editor/Texts';
+export * from './Control';
+export * from './utils';
+export * from './types';

package/dist/types/links.d.ts

@@ -0,0 +1,20 @@
+import { Point } from '@linkurious/ogma';
+import { Arrow, Id, TargetType, Link, Side } from './types';
+/**
+ * Class that implements linking between annotation arrows and different items.
+ * An arrow can be connected to a text or to a node. It supports double indexing
+ * so that you could get the arrow by the id of the text or the id of the node
+ * or by the id of the arrow id itself.
+ * A node or text can be connected to multiple arrows.
+ * An arrow can be connected to only one node or text, but on both ends.
+ */
+export declare class Links {
+    private links;
+    private linksByTargetId;
+    private linksByArrowId;
+    add(arrow: Arrow, side: Side, targetId: Id, targetType: TargetType, connectionPoint: Point): this;
+    arrowIsLinked(arrowId: Id, side: Side): boolean;
+    remove(arrow: Arrow, side: Side): this;
+    getArrowLink(arrowId: Id, side: Side): Link | null;
+    getTargetLinks(targetId: Id): Link[];
+}

package/dist/types/types.d.ts

@@ -0,0 +1,172 @@
+import { Point } from '@linkurious/ogma';
+import type { Feature, FeatureCollection, Geometry, GeometryObject, LineString, Polygon } from 'geojson';
+import { EVT_ADD, EVT_CANCEL_DRAWING, EVT_DRAG, EVT_DRAG_END, EVT_DRAG_START, EVT_HOVER, EVT_REMOVE, EVT_SELECT, EVT_UNHOVER, EVT_UNSELECT, EVT_UPDATE, EVT_LINK } from './constants';
+export declare const isArrow: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Arrow;
+export declare const isText: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Text;
+export declare const isAnnotationCollection: (a: AnnotationFeature<Geometry, AnnotationProps> | FeatureCollection) => a is AnnotationCollection;
+type AnnotationType = 'arrow' | 'text';
+export interface AnnotationProps {
+    type: AnnotationType;
+    style?: unknown;
+}
+export type Id = string | number;
+export interface AnnotationFeature<G extends GeometryObject = GeometryObject, P = AnnotationProps> extends Feature<G, P> {
+    id: string | number;
+}
+export interface ArrowStyles extends StrokeOptions {
+    tail?: Extremity;
+    head?: Extremity;
+}
+type ExportedLink = {
+    id: Id;
+    side: 'start' | 'end';
+    type: 'node' | 'text';
+    magnet?: Point;
+};
+export interface ArrowProperties extends AnnotationProps {
+    type: 'arrow';
+    style?: ArrowStyles;
+    link?: Partial<Record<Side, ExportedLink>>;
+}
+export type Arrow = AnnotationFeature<LineString, ArrowProperties>;
+export interface AnnotationCollection extends FeatureCollection {
+    features: (Arrow | Text)[];
+}
+export type StrokeOptions = {
+    strokeType?: 'plain' | 'dashed' | 'none';
+    strokeColor?: string;
+    strokeWidth?: number;
+};
+export interface TextStyle extends StrokeOptions {
+    /** Helvetica, sans-serif...  */
+    font?: string;
+    /** 12px, 1em... */
+    fontSize?: string;
+    /** text color: #f00, yellow...*/
+    color?: string;
+    /** background color: empty for transparent #f00, yellow...*/
+    background?: string;
+    /** padding around the text */
+    padding?: number;
+}
+export interface TextProperties extends AnnotationProps {
+    type: 'text';
+    /**text to display*/
+    content: string;
+    style?: TextStyle;
+}
+export type Text = AnnotationFeature<Polygon, TextProperties>;
+export type Stroke = {
+    type: 'plain' | 'dashed' | 'none';
+    color: string;
+    width: number;
+};
+export type StrokeStyle = Stroke;
+export type Extremity = 'none' | 'arrow' | 'arrow-plain';
+export type AnnotationOptions = {
+    handleSize: number;
+    placeholder: string;
+};
+export type Events<T> = {
+    [EVT_HOVER]: (evt: T) => void;
+    [EVT_UNHOVER]: (evt: T) => void;
+    [EVT_SELECT]: (evt: T) => void;
+    [EVT_UNSELECT]: (evt: T) => void;
+    [EVT_DRAG_START]: (evt: T) => void;
+    [EVT_DRAG]: (evt: T, key: 'line' | 'start' | 'end' | 'text') => void;
+    [EVT_DRAG_END]: (evt: T) => void;
+    [EVT_REMOVE]: (evt: T) => void;
+    [EVT_ADD]: (evt: T) => void;
+    [EVT_UPDATE]: (evt: T) => void;
+};
+export type FeatureEvents = {
+    /**
+     * Event trigerred when selecting an annotation
+     * @param evt The annotation selected
+     */
+    [EVT_SELECT]: (evt: Annotation) => void;
+    /**
+     * Event trigerred when unselecting an annotation
+     * @param evt The annotation unselected
+     */
+    [EVT_UNSELECT]: (evt: Annotation) => void;
+    /**
+     * Event trigerred when removing an annotation
+     * @param evt The annotation removed
+     */
+    [EVT_REMOVE]: (evt: Annotation) => void;
+    /**
+     * Event trigerred when adding an annotation
+     * @param evt The annotation added
+     */
+    [EVT_ADD]: (evt: Annotation) => void;
+    [EVT_CANCEL_DRAWING]: () => void;
+    /**
+     * Event trigerred when updating an annotation
+     * @returns The annotation updated
+     */
+    [EVT_UPDATE]: (evt: Annotation) => void;
+    /**
+     * Event trigerred when linking an arrow to a text or node
+     */
+    [EVT_LINK]: (evt: {
+        arrow: Arrow;
+        link: Link;
+    }) => void;
+};
+export type TargetType = 'text' | 'node';
+export type Side = 'start' | 'end';
+export type Link = {
+    /** arrow atteched to the text or node */
+    arrow: Id;
+    /** id of the text the arrow is attached to */
+    id: Id;
+    /**  On which end the arrow is tighten to the text */
+    side: Side;
+    /** id of the text or node  the arrow is attached to */
+    target: Id;
+    /** Text or node */
+    targetType: TargetType;
+    /**
+     * On which point relative to topleft corner the arrow is tighten, in case of
+     * node, it can be deduced from the arrow itself
+     */
+    connectionPoint: Point;
+};
+export type ControllerOptions = {
+    magnetColor: string;
+    /**
+     * The radius in which arrows are attracted
+     */
+    magnetRadius: number;
+    /**
+     * The margin in which the Texts are detected when looking for magnet points
+     */
+    detectMargin: number;
+    /**
+     * Display size of the magnet point
+     */
+    magnetHandleRadius: number;
+    /**
+     * Placeholder for the text input
+     */
+    textPlaceholder: string;
+    /**
+     * Size of the text handle
+     */
+    textHandleSize: number;
+    /**
+     * Size of the arrow handle
+     */
+    arrowHandleSize: number;
+    /**
+     * Minimum height of the arrow in units
+     */
+    minArrowHeight: number;
+    /**
+     * Maximum height of the arrow in units
+     */
+    maxArrowHeight: number;
+};
+export type Annotation = Arrow | Text;
+export {};

package/dist/types/utils.d.ts

@@ -0,0 +1,48 @@
+import { Point } from '@linkurious/ogma';
+import type { BBox } from 'geojson';
+import { AnnotationCollection, Arrow, Text } from './types';
+export declare function createSVGElement<T extends SVGElement>(tag: string): T;
+export declare function getTextBbox(t: Text): BBox;
+export declare function getTextSize(t: Text): {
+    width: number;
+    height: number;
+};
+export declare function getTextPosition(t: Text): {
+    x: number;
+    y: number;
+};
+export declare function updateTextBbox(t: Text): void;
+export declare function setTextBbox(t: Text, x: number, y: number, width: number, height: number): void;
+export declare function getArrowStart(a: Arrow): {
+    x: number;
+    y: number;
+};
+export declare function getArrowSide(a: Arrow, side: 'start' | 'end'): {
+    x: number;
+    y: number;
+};
+export declare function getArrowEnd(a: Arrow): {
+    x: number;
+    y: number;
+};
+export declare function setArrowStart(a: Arrow, x: number, y: number): void;
+export declare function setArrowEnd(a: Arrow, x: number, y: number): void;
+export declare function getArrowEndPoints(a: Arrow): {
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+};
+export declare function setArrowEndPoint(a: Arrow, side: 'start' | 'end', x: number, y: number): void;
+export declare const getHandleId: (handle: HTMLDivElement) => number;
+type Bounds = [number, number, number, number];
+export declare function getAnnotationsBounds(annotations: AnnotationCollection): Bounds;
+export declare function getAttachmentPointOnNode(start: Point, nodeCenter: Point, nodeRadius: number): {
+    x: number;
+    y: number;
+};
+export {};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@linkurious/ogma-annotations",
+  "version": "1.0.5",
+  "description": "Headless annotation plugin for Ogma",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.umd.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.umd.js",
+      "default": "./dist/index.mjs",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./style.css": {
+      "import": "./dist/style.css",
+      "require": "./dist/style.css"
+    },
+    "./umd": "./dist/index.umd.js",
+    "./esm": "./dist/index.mjs"
+  },
+  "scripts": {
+    "start": "npm run dev",
+    "dev": "vite -c web/vite.config.ts",
+    "build:ui": "vite build -c vite.config-ui.ts",
+    "prebuild": "rm -rf dist",
+    "build": "tsc && vite build && npm run types",
+    "lint:ci": "eslint --ext .ts,.tsx src",
+    "lint": "eslint --ext .ts,.tsx --fix src",
+    "types": "tsc --d -emitDeclarationOnly --outDir dist/types",
+    "preview": "vite preview",
+    "docs:build": "typedoc --plugin typedoc-plugin-markdown --out ../../docs/annotations src/index.ts",
+    "test:unit": "vitest run -c test/unit/vitest.config.mts",
+    "test:watch": "vitest watch -c test/unit/vitest.config.mts",
+    "test:e2e": "vitest run -c test/e2e/vitest.config.mts",
+    "test:e2e:watch": "vitest watch -c test/e2e/vitest.config.mts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linkurious/ogma-prototype.git"
+  },
+  "keywords": [
+    "annotations",
+    "headless",
+    "arrow",
+    "ogma",
+    "text"
+  ],
+  "author": "Linkurious SAS",
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@linkurious/ogma": ">=4.5.6"
+  },
+  "devDependencies": {
+    "canvas": "^2.11.2",
+    "get-port": "^7.0.0",
+    "jsdom": "^22.1.0",
+    "playwright": "1.40.0",
+    "typescript": "5.3.2",
+    "vite": "^5.0.2",
+    "vitest": "^0.34.6"
+  },
+  "dependencies": {
+    "@borgar/textbox": "^1.6.0",
+    "@types/geojson": "^7946.0.13",
+    "@types/vector2js": "^2.0.2",
+    "eventemitter3": "^5.0.1",
+    "vector2js": "^2.0.1"
+  }
+}