@linkurious/ogma-annotations
Version:
Headless annotation plugin for Ogma
1,466 lines (1,351 loc) • 58.3 kB
TypeScript
import { BBox } from 'geojson';
import { default as default_2 } from 'eventemitter3';
import { Feature } from 'geojson';
import { FeatureCollection } from 'geojson';
import { Geometry } from 'geojson';
import { GeometryObject } from 'geojson';
import { LineString } from 'geojson';
import { Node as Node_2 } from '@linkurious/ogma';
import { Ogma } from '@linkurious/ogma';
import { Point as Point_2 } from 'geojson';
import { Point as Point_3 } from '@linkurious/ogma';
import { Polygon as Polygon_2 } from 'geojson';
import { Position } from 'geojson';
import { Size } from '@linkurious/ogma';
/**
* Adjusts the brightness of a color (hex or rgba) based on its perceived luminance.
* For bright colors, the adjustment is applied as darkening; for dark colors, as lightening.
*
* @param color - Color string in hex (#RRGGBB or #RGB) or rgba format
* @param amount - Adjustment factor between -1 and 1:
* - Positive values (0 to 1): lighten dark colors, darken bright colors
* - Negative values (-1 to 0): darken dark colors, lighten bright colors
* - 0: no change
* - Example: 0.2 applies a 20% adjustment, -0.1 applies a -10% adjustment
* @returns Adjusted color in rgba format
*/
export declare function adjustColorBrightness(color: Color, amount: number): RgbaColor;
/** Union type of all Annotation features */
export declare type Annotation = Arrow | Box | Text_2 | Comment_2 | Polygon;
/** Collection of Annotations, GeoJSON FeatureCollection */
export declare interface AnnotationCollection extends FeatureCollection {
features: Annotation[];
}
/**
* Base interface for all annotation features.
* @template G - Geometry type
* @template P - Properties type
*/
export declare interface AnnotationFeature<G extends GeometryObject = GeometryObject, P = AnnotationProps> extends Feature<G, P> {
/** Unique identifier for the annotation */
id: Id;
}
/** Function type to get an Annotation by its id */
export declare type AnnotationGetter = (id: Id) => Annotation | undefined;
export declare type AnnotationOptions = {
handleSize: number;
placeholder?: string;
};
/**
* Base properties for all annotations.
*/
export declare interface AnnotationProps {
/** Type of annotation */
type: AnnotationType;
/** Optional style configuration */
style?: unknown;
}
/** Types of annotations supported */
export declare type AnnotationType = "arrow" | "text" | "box" | "comment" | "polygon";
/**
* Arrow annotation feature. Represents a directed line between two points,
* can connect a textbox to a shape.
*/
export declare interface Arrow extends AnnotationFeature<LineString, ArrowProperties> {
}
export declare interface ArrowProperties extends AnnotationProps {
type: "arrow";
style?: ArrowStyles;
link?: Partial<Record<Side, ExportedLink>>;
}
/**
* Styles specific to arrow annotations.
*/
export declare interface ArrowStyles extends StrokeOptions {
/** Tail extremity style */
tail?: Extremity;
/** Head extremity style */
head?: Extremity;
}
/**
* Safely cast a string to a Color type with runtime validation
* @throws {Error} if the color format is invalid
*/
export declare function asColor(color: string): Color;
/**
* Safely cast a string to a HexColor type with runtime validation
* @throws {Error} if the color format is invalid
*/
export declare function asHexColor(color: string): HexColor;
/**
* Safely cast a string to an RgbaColor type with runtime validation
* @throws {Error} if the color format is invalid
*/
export declare function asRgbaColor(color: string): RgbaColor;
/**
* Safely cast a string to an RgbColor type with runtime validation
* @throws {Error} if the color format is invalid
*/
export declare function asRgbColor(color: string): RgbColor;
/**
* Bounding box object, with the following properties:
* - [0]: min x
* - [1]: min y
* - [2]: max x
* - [3]: max y
*/
export declare type Bounds = [number, number, number, number];
/**
* Box annotation feature
*/
export declare interface Box extends AnnotationFeature<Point_2, BoxProperties> {
}
/** Properties specific to box annotations. */
export declare interface BoxProperties extends AnnotationProps {
type: "box";
/** Width of the box */
width: number;
/** Height of the box */
height: number;
/** Style options for the box */
style?: BoxStyle;
}
/** Styles specific to box annotations. */
export declare interface BoxStyle extends StrokeOptions {
/** background color: empty for transparent #f00, yellow...*/
background?: Color;
/** padding around the box */
padding?: number;
/** border radius */
borderRadius?: number;
/** if true, the box scales with zoom. Default is true */
scaled?: boolean;
/** box shadow in CSS format, e.g. "0px 4px 6px rgba(0, 0, 0, 0.1)" */
boxShadow?: string;
}
/**
* Brighten a color for highlight purposes.
* @param color - Color string in hex (#RRGGBB or #RGB) or rgba format
* @returns
*/
export declare const brighten: (color: Color) => RgbaColor;
/**
* Calculate optimal zoom threshold for auto-collapse based on comment dimensions
*
* The threshold is computed so that the comment collapses when its screen-space
* size would be smaller than a minimum readable size.
*
* @param comment - Comment annotation
* @param minReadableWidth - Minimum readable width in pixels (default: 80)
* @returns Zoom threshold below which comment should collapse
*
* @example
* // A 200px wide comment with minReadable=80 will collapse at zoom < 0.4
* // because 200 * 0.4 = 80
*/
export declare function calculateCommentZoomThreshold(comment: Comment_2, minReadableWidth?: number): number;
/**
* Check if arrow endpoint can be detached from its target
*
* Always returns true since arrow endpoints can be freely retargeted,
* even for comment arrows. The comment is typically on the start side.
*
* @param _arrow - The arrow feature (unused, kept for API consistency)
* @returns Always true - arrow ends can be detached
*
* @example
* ```typescript
* if (canDetachArrowEnd(arrow)) {
* // Allow user to drag arrow end point
* }
* ```
*/
export declare function canDetachArrowEnd(_arrow: Arrow): boolean;
/**
* Check if arrow start point can be detached from its source
*
* Returns false for arrows originating FROM comments, since comment arrows
* must always remain attached to the comment on their start side.
*
* @param arrow - The arrow feature
* @returns True if arrow start can be detached
*
* @example
* ```typescript
* if (canDetachArrowStart(arrow)) {
* // Allow user to drag arrow start point
* } else {
* // Keep arrow start locked to comment
* }
* ```
*/
export declare function canDetachArrowStart(arrow: Arrow): boolean;
/** Event related to a single annotation feature */
export declare interface ClickEvent {
/** Annotation ID involved in the event */
id?: Id;
/** Mouse position in pixel coordinates */
position: {
x: number;
y: number;
};
}
export declare type ClientMouseEvent = {
clientX: number;
clientY: number;
};
export declare function clientToContainerPosition(evt: ClientMouseEvent, container?: HTMLElement | null): {
x: number;
y: number;
};
/**
* Any valid color format
*/
export declare type Color = HexColor | RgbColor | RgbaColor | "transparent" | "none" | string;
export declare function colorToRgba(color: Color, alpha: number): RgbaColor;
/**
* Comment annotation type
* Geometry: Point (center position of comment box/icon)
*
* Note: Arrows are stored separately in Arrow features.
* Arrows reference comments via their link.start or link.end properties.
*/
declare interface Comment_2 extends AnnotationFeature<Point_2, CommentProps> {
}
export { Comment_2 as Comment }
export declare const COMMENT_MODE_COLLAPSED = "collapsed";
export declare const COMMENT_MODE_EXPANDED = "expanded";
/**
* Properties for Comment annotations
*
* Comments are specialized annotations that:
* - Always maintain fixed screen-space size
* - Always have at least one arrow pointing TO them
* - Can be collapsed (icon) or expanded (text box)
* - Support multiple arrows pointing to them
*/
export declare interface CommentProps extends AnnotationProps {
type: "comment";
/** Text content (similar to text annotation) */
content: string;
/** Display mode: collapsed (icon) or expanded (text box) */
mode: typeof COMMENT_MODE_COLLAPSED | typeof COMMENT_MODE_EXPANDED;
/** Width in expanded mode (pixels) */
width: number;
/** Height (auto-grows with content, pixels) */
height: number;
/** Optional metadata */
author?: string;
timestamp?: Date;
/** Styling */
style?: CommentStyle;
}
/**
* Style configuration for Comment annotations
*/
export declare interface CommentStyle extends TextStyle {
/** Background color for collapsed icon (default: "#FFD700") */
iconColor?: Color;
/** Icon to display when collapsed (default: "💬") */
iconSymbol?: string;
/** Border color for collapsed icon */
iconBorderColor?: Color;
/** Border width for collapsed icon */
iconBorderWidth?: number;
/** Minimum height (default: 60px) */
minHeight?: number;
/** Maximum height before scrolling (default: 480px, undefined = no limit) */
maxHeight?: number;
/** Size when collapsed (default: 32px) */
iconSize?: number;
/** Zoom threshold below which comment auto-collapses (default: 0.5) */
collapseZoomThreshold?: number;
/** Show "send" button in edit mode (default: true) */
showSendButton?: boolean;
/** Auto-grow height with content (default: true) */
autoGrow?: boolean;
/** Show drop shadow on comment box (default: true) */
shadow?: boolean;
/** Expand to full width when selected (default: false) */
expandOnSelect?: boolean;
}
/**
* Main controller class for managing annotations.
* It manages rendering and editing of annotations.
*/
export declare class Control extends default_2<FeatureEvents> {
private ogma;
private store;
private renderers;
private interactions;
private editor;
private links;
private index;
private drawing;
private snapping;
private selectionManager;
private historyManager;
private updateManager;
private commentManager;
constructor(ogma: Ogma, options?: Partial<ControllerOptions>);
private initializeRenderers;
private setupEvents;
private onRotate;
private onZoom;
private onLayout;
/**
* Set the options for the controller
* @param options new Options
* @returns the updated options
*/
setOptions(options?: Partial<ControllerOptions>): {
showSendButton: boolean;
showEditButton: boolean;
sendButtonIcon: string;
editButtonIcon: string;
minArrowHeight: number;
maxArrowHeight: number;
detectMargin: number;
magnetRadius: number;
magnetHandleRadius: number;
textPlaceholder: string;
};
/**
* Add an annotation to the controller
* @param annotation The annotation to add
*/
add(annotation: Annotation | AnnotationCollection): this;
/**
* Remove an annotation or an array of annotations from the controller
* @param annotation The annotation(s) to remove
*/
remove(annotation: Annotation | AnnotationCollection): this;
/**
* Undo the last change
* @returns true if undo was successful, false if no changes to undo
*/
undo(): boolean;
/**
* Redo the last undone change
* @returns true if redo was successful, false if no changes to redo
*/
redo(): boolean;
/**
* Check if there are changes to undo
* @returns true if undo is possible
*/
canUndo(): boolean;
/**
* Check if there are changes to redo
* @returns true if redo is possible
*/
canRedo(): boolean;
/**
* Clear the undo/redo history
*/
clearHistory(): void;
/**
* Get all annotations in the controller
* @returns A FeatureCollection containing all annotations
*/
getAnnotations(): AnnotationCollection;
/**
* Select one or more annotations by id
* @param annotations The id(s) of the annotation(s) to select
* @returns this for chaining
*/
select(annotations: Id | Id[]): this;
/**
* Unselect one or more annotations, or all if no ids provided
* @param annotations The id(s) of the annotation(s) to unselect, or undefined to unselect all
* @returns this for chaining
*/
unselect(annotations?: Id | Id[]): this;
/**
* Cancel the current drawing operation
* @returns this for chaining
*/
cancelDrawing(): this;
/**
* Enable arrow drawing mode - the recommended way to add arrows.
*
* Call this method when the user clicks an "Add Arrow" button. The control will:
* 1. Wait for the next mousedown event
* 2. Create an arrow at that position with the specified style
* 3. Start the interactive drawing process
* 4. Clean up automatically when done
*
* **This is the recommended API for 99% of use cases.** Only use `startArrow()`
* if you need to implement custom mouse handling or positioning logic.
*
* @example
* ```ts
* addArrowButton.addEventListener('click', () => {
* control.enableArrowDrawing({ strokeColor: '#3A03CF', strokeWidth: 2 });
* });
* ```
*
* @param style Arrow style options
* @returns this for chaining
* @see startArrow for low-level programmatic control
*/
enableArrowDrawing(style?: Partial<Arrow["properties"]["style"]>): this;
/**
* Enable text drawing mode - the recommended way to add text annotations.
*
* Call this method when the user clicks an "Add Text" button. The control will:
* 1. Wait for the next mousedown event
* 2. Create a text box at that position with the specified style
* 3. Start the interactive drawing/editing process
* 4. Clean up automatically when done
*
* **This is the recommended API for 99% of use cases.** Only use `startText()`
* if you need to implement custom mouse handling or positioning logic.
*
* @example
* ```ts
* addTextButton.addEventListener('click', () => {
* control.enableTextDrawing({ color: '#3A03CF', fontSize: 24 });
* });
* ```
*
* @param style Text style options
* @returns this for chaining
* @see startText for low-level programmatic control
*/
enableTextDrawing(style?: Partial<Text_2["properties"]["style"]>): this;
/**
* Enable box drawing mode - the recommended way to add boxes.
*
* Call this method when the user clicks an "Add Box" button. The control will:
* 1. Wait for the next mousedown event
* 2. Create a box at that position with the specified style
* 3. Start the interactive drawing process (drag to size)
* 4. Clean up automatically when done
*
* **This is the recommended API for 99% of use cases.** Only use `startBox()`
* if you need to implement custom mouse handling or positioning logic.
*
* @example
* ```ts
* addBoxButton.addEventListener('click', () => {
* control.enableBoxDrawing({ background: '#EDE6FF', borderRadius: 8 });
* });
* ```
*
* @param style Box style options
* @returns this for chaining
* @see startBox for low-level programmatic control
*/
enableBoxDrawing(style?: Partial<Box["properties"]["style"]>): this;
/**
* Enable polygon drawing mode - the recommended way to add polygons.
*
* Call this method when the user clicks an "Add Polygon" button. The control will:
* 1. Wait for the next mousedown event
* 2. Create a polygon starting at that position with the specified style
* 3. Start the interactive drawing process (click points to draw shape)
* 4. Clean up automatically when done
*
* **This is the recommended API for 99% of use cases.** Only use `startPolygon()`
* if you need to implement custom mouse handling or positioning logic.
*
* @example
* ```ts
* addPolygonButton.addEventListener('click', () => {
* control.enablePolygonDrawing({ strokeColor: '#3A03CF', background: 'rgba(58, 3, 207, 0.15)' });
* });
* ```
*
* @param style Polygon style options
* @returns this for chaining
* @see startPolygon for low-level programmatic control
*/
enablePolygonDrawing(style?: Partial<Polygon["properties"]["style"]>): this;
/**
* Enable comment drawing mode - the recommended way to add comments.
*
* Call this method when the user clicks an "Add Comment" button. The control will:
* 1. Wait for the next mousedown event
* 2. Create a comment with an arrow pointing to that position
* 3. Smart positioning: automatically finds the best placement for the comment box
* 4. Start the interactive editing process
* 5. Clean up automatically when done
*
* **This is the recommended API for 99% of use cases.** Only use `startComment()`
* if you need to implement custom mouse handling or positioning logic.
*
* @example
* ```ts
* addCommentButton.addEventListener('click', () => {
* control.enableCommentDrawing({
* commentStyle: { color: '#3A03CF', background: '#EDE6FF' },
* arrowStyle: { strokeColor: '#3A03CF', head: 'halo-dot' }
* });
* });
* ```
*
* @param options Drawing options including offsets and styles
* @param options.offsetX Manual X offset for comment placement (overrides smart positioning)
* @param options.offsetY Manual Y offset for comment placement (overrides smart positioning)
* @param options.commentStyle Style options for the comment box
* @param options.arrowStyle Style options for the arrow
* @returns this for chaining
* @see startComment for low-level programmatic control
*/
enableCommentDrawing(options?: {
offsetX?: number;
offsetY?: number;
commentStyle?: Partial<CommentProps>;
arrowStyle?: Partial<ArrowProperties>;
}): this;
/**
* Place a pre-created annotation by moving it with the cursor.
* The annotation follows the mouse until the user clicks to place it.
* Press Escape to cancel.
*
* @param annotation The text or box annotation to place
* @returns this for chaining
*/
enablePlacement(annotation: Text_2 | Box): this;
/**
* **Advanced API:** Programmatically start drawing a comment at specific coordinates.
*
* This is a low-level method that gives you full control over the drawing process.
* You must handle mouse events and create the comment object yourself.
*
* **For most use cases, use `enableCommentDrawing()` instead** - it handles all
* mouse events and annotation creation automatically.
*
* Use this method only when you need:
* - Custom mouse event handling (e.g., custom cursors, right-click menus)
* - Programmatic placement without user interaction
* - Integration with custom UI frameworks
*
* @example
* ```ts
* // Custom cursor example
* ogma.setOptions({ cursor: { default: 'crosshair' } });
* ogma.events.once('mousedown', (evt) => {
* const { x, y } = ogma.view.screenToGraphCoordinates(evt);
* const comment = createComment(x, y, 'My comment', { color: '#3A03CF' });
* control.startComment(x, y, comment);
* });
* ```
*
* @param x X coordinate to start drawing
* @param y Y coordinate to start drawing
* @param comment The comment annotation to add
* @param options Drawing options including offsets and styles
* @returns this for chaining
* @see enableCommentDrawing for the recommended high-level API
*/
startComment(x: number, y: number, comment: Comment_2, options?: {
offsetX?: number;
offsetY?: number;
commentStyle?: Partial<CommentProps>;
arrowStyle?: Partial<ArrowProperties>;
}): this;
/**
* **Advanced API:** Programmatically start drawing a box at specific coordinates.
*
* This is a low-level method that gives you full control over the drawing process.
* You must handle mouse events and optionally create the box object yourself.
*
* **For most use cases, use `enableBoxDrawing()` instead** - it handles all
* mouse events and annotation creation automatically.
*
* Use this method only when you need:
* - Custom mouse event handling (e.g., custom cursors, right-click menus)
* - Programmatic placement without user interaction
* - Integration with custom UI frameworks
*
* @example
* ```ts
* // Custom cursor example
* ogma.setOptions({ cursor: { default: 'crosshair' } });
* ogma.events.once('mousedown', (evt) => {
* const { x, y } = ogma.view.screenToGraphCoordinates(evt);
* const box = createBox(x, y, 100, 50, { background: '#EDE6FF' });
* control.startBox(x, y, box);
* });
* ```
*
* @param x X coordinate for the box origin
* @param y Y coordinate for the box origin
* @param box The box annotation to add (optional, will be created if not provided)
* @returns this for chaining
* @see enableBoxDrawing for the recommended high-level API
*/
startBox(x: number, y: number, box?: Box): this;
/**
* **Advanced API:** Programmatically start drawing an arrow at specific coordinates.
*
* This is a low-level method that gives you full control over the drawing process.
* You must handle mouse events and optionally create the arrow object yourself.
*
* **For most use cases, use `enableArrowDrawing()` instead** - it handles all
* mouse events and annotation creation automatically.
*
* Use this method only when you need:
* - Custom mouse event handling (e.g., custom cursors, right-click menus)
* - Programmatic placement without user interaction
* - Integration with custom UI frameworks
*
* @example
* ```ts
* // Custom cursor example
* ogma.setOptions({ cursor: { default: 'crosshair' } });
* ogma.events.once('mousedown', (evt) => {
* const { x, y } = ogma.view.screenToGraphCoordinates(evt);
* const arrow = createArrow(x, y, x, y, { strokeColor: '#3A03CF' });
* control.startArrow(x, y, arrow);
* });
* ```
*
* @param x X coordinate for the arrow start
* @param y Y coordinate for the arrow start
* @param arrow The arrow annotation to add (optional, will be created if not provided)
* @returns this for chaining
* @see enableArrowDrawing for the recommended high-level API
*/
startArrow(x: number, y: number, arrow?: Arrow): this;
/**
* **Advanced API:** Programmatically start drawing a text annotation at specific coordinates.
*
* This is a low-level method that gives you full control over the drawing process.
* You must handle mouse events and optionally create the text object yourself.
*
* **For most use cases, use `enableTextDrawing()` instead** - it handles all
* mouse events and annotation creation automatically.
*
* Use this method only when you need:
* - Custom mouse event handling (e.g., custom cursors, right-click menus)
* - Programmatic placement without user interaction
* - Integration with custom UI frameworks
*
* @example
* ```ts
* // Custom cursor example
* ogma.setOptions({ cursor: { default: 'crosshair' } });
* ogma.events.once('mousedown', (evt) => {
* const { x, y } = ogma.view.screenToGraphCoordinates(evt);
* const text = createText(x, y, 0, 0, 'Hello', { color: '#3A03CF' });
* control.startText(x, y, text);
* });
* ```
*
* @param x X coordinate for the text
* @param y Y coordinate for the text
* @param text The text annotation to add (optional, will be created if not provided)
* @returns this for chaining
* @see enableTextDrawing for the recommended high-level API
*/
startText(x: number, y: number, text?: Text_2): this;
/**
* **Advanced API:** Programmatically start drawing a polygon at specific coordinates.
*
* This is a low-level method that gives you full control over the drawing process.
* You must handle mouse events and create the polygon object yourself.
*
* **For most use cases, use `enablePolygonDrawing()` instead** - it handles all
* mouse events and annotation creation automatically.
*
* Use this method only when you need:
* - Custom mouse event handling (e.g., custom cursors, right-click menus)
* - Programmatic placement without user interaction
* - Integration with custom UI frameworks
*
* @example
* ```ts
* // Custom cursor example
* ogma.setOptions({ cursor: { default: 'crosshair' } });
* ogma.events.once('mousedown', (evt) => {
* const { x, y } = ogma.view.screenToGraphCoordinates(evt);
* const polygon = createPolygon([[[x, y]]], { strokeColor: '#3A03CF' });
* control.startPolygon(x, y, polygon);
* });
* ```
*
* @param x X coordinate to start drawing
* @param y Y coordinate to start drawing
* @param polygon The polygon annotation to add
* @returns this for chaining
* @see enablePolygonDrawing for the recommended high-level API
*/
startPolygon(x: number, y: number, polygon: Polygon): this;
/**
* Get the currently selected annotations as a collection
* @returns A FeatureCollection of selected annotations
*/
getSelectedAnnotations(): AnnotationCollection;
/**
* Get the first selected annotation (for backwards compatibility)
* @returns The currently selected annotation, or null if none selected
*/
getSelected(): Annotation | null;
/**
* Get a specific annotation by id
* @param id The id of the annotation to retrieve
* @returns The annotation with the given id, or undefined if not found
*/
getAnnotation<T = Annotation>(id: Id): T | undefined;
/**
* Scale an annotation by a given factor around an origin point
* @param id The id of the annotation to scale
* @param scale The scale factor
* @param ox Origin x coordinate
* @param oy Origin y coordinate
* @returns this for chaining
*/
setScale(id: Id, scale: number, ox: number, oy: number): this;
/**
* Toggle a comment between collapsed and expanded mode
* @param id The id of the comment to toggle
* @returns this for chaining
*/
toggleComment(id: Id): this;
/**
* Destroy the controller and its elements
*/
destroy(): void;
/**
* 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;
/**
* Update an annotation with partial updates
*
* This method allows you to update any properties of an annotation, including
* geometry, properties, and style. Updates are merged with existing data.
*
* @param annotation Partial annotation object with id and properties to update
* @returns this for chaining
*
* @example
* ```ts
* // Update arrow geometry
* controller.update({
* id: arrowId,
* geometry: {
* type: 'LineString',
* coordinates: [[0, 0], [200, 200]]
* }
* });
*
* // Update text content and position
* controller.update({
* id: textId,
* geometry: {
* type: 'Point',
* coordinates: [100, 100]
* },
* properties: {
* content: 'Updated text'
* }
* });
*
* // Update style only (prefer updateStyle for style-only updates)
* controller.update({
* id: boxId,
* properties: {
* style: {
* background: '#ff0000'
* }
* }
* });
* ```
*/
update<A extends Annotation>(annotation: DeepPartial<A> & {
id: Id;
}): this;
/**
* Attach an arrow to a node at the specified side
* @param arrowId
* @param targetNode
* @param side
*/
link(arrowId: Id, targetNode: Node_2, side: Side): this;
/**
* Attach an arrow to an annotation at the specified side
* @param arrowId
* @param target
* @param side
*/
link(arrowId: Id, target: Id, side: Side): this;
isDrawing(): boolean;
}
/**
* Options for the annotations control
*/
export declare type ControllerOptions = {
/**
* 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;
/**
* Show send button in text editor
*/
showSendButton: boolean;
/**
* Show edit button in text editor
*/
showEditButton: boolean;
/**
* SVG icon for the send button in text editor
* Should be a complete SVG string (e.g., '<svg>...</svg>')
*/
sendButtonIcon: string;
/**
* SVG icon for the edit button in text editor
* Should be a complete SVG string (e.g., '<svg>...</svg>')
*/
editButtonIcon: string;
/**
* Minimum height of the arrow in units
*/
minArrowHeight: number;
/**
* Maximum height of the arrow in units
*/
maxArrowHeight: number;
};
export declare const createArrow: (x0?: number, y0?: number, x1?: number, y1?: number, styles?: {
/** Tail extremity style */
tail?: Extremity | undefined;
/** Head extremity style */
head?: Extremity | undefined;
strokeType?: StrokeType | undefined;
strokeColor?: string | undefined;
strokeWidth?: number | undefined;
}) => Arrow;
export declare const createBox: (x?: number, y?: number, width?: number, height?: number, styles?: Partial<BoxStyle>) => Box;
/**
* Create a new Comment annotation
*
* @param x - X coordinate of the comment box/icon center
* @param y - Y coordinate of the comment box/icon center
* @param content - Text content
* @param options - Optional configuration
* @returns New Comment feature
*
* @important This creates ONLY the comment box without an arrow. Since comments
* require at least one arrow, you should use {@link createCommentWithArrow}
* instead for programmatic creation. This function is primarily used internally
* by the interactive drawing handlers.
*
* @see createCommentWithArrow for creating comments programmatically
*/
export declare function createComment(x: number, y: number, content: string, options?: Partial<CommentProps>): Comment_2;
/**
* Create a comment with an arrow pointing to a target location
*
* This is the recommended way to create comments programmatically, as it ensures
* that the comment always has at least one arrow (which is required).
*
* @param targetX - X coordinate where the arrow points to
* @param targetY - Y coordinate where the arrow points to
* @param commentX - X coordinate of the comment box center
* @param commentY - Y coordinate of the comment box center
* @param content - Text content of the comment
* @param options - Optional configuration
* @param options.commentStyle - Style options for the comment
* @param options.arrowStyle - Style options for the arrow
* @returns Object containing the comment and arrow features
*
* @example
* ```typescript
* import { createCommentWithArrow } from '@linkurious/ogma-annotations';
*
* // Create a comment pointing to a node at (100, 100)
* const { comment, arrow } = createCommentWithArrow(
* 100, 100, // Target position (where arrow points)
* 300, 50, // Comment position
* "Important node!", // Comment text
* {
* commentStyle: {
* style: {
* background: "#FFFACD",
* color: "#333"
* }
* },
* arrowStyle: {
* strokeColor: "#3498db",
* strokeWidth: 2,
* head: "arrow"
* }
* }
* );
*
* // Add both to the controller
* controller.add(comment);
* controller.add(arrow);
*
* // The arrow is automatically linked to the comment
* ```
*/
export declare function createCommentWithArrow(targetX: number, targetY: number, commentX: number, commentY: number, content?: string, options?: {
commentStyle?: Partial<CommentProps>;
arrowStyle?: Partial<ArrowStyles>;
}): {
comment: Comment_2;
arrow: Arrow;
};
/**
* Create a polygon annotation
*/
export declare function createPolygon(coordinates: [number, number][][], properties?: Partial<Omit<PolygonProperties, "type">> & {
id?: Id;
}): Polygon;
/** @private */
export declare function createSVGElement<T extends SVGElement>(tag: string): T;
export declare const createText: (x?: number, y?: number, width?: number, height?: number, content?: string, styles?: Partial<TextStyle>) => Text_2;
/** @private */
export declare type Cursor = "default" | "pointer" | "move" | "grab" | "grabbing" | "auto" | "resize" | "col-resize" | "row-resize" | "all-scroll" | "n-resize" | "e-resize" | "s-resize" | "w-resize" | "ne-resize" | "nw-resize" | "se-resize" | "sw-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | "alias" | "crosshair";
/** @private */
export declare const cursors: Record<string, Cursor>;
/**
* Darken a color for highlight purposes.
* @param color - Color string in hex (#RRGGBB or #RGB) or rgba format
* @returns
*/
export declare const darken: (color: Color) => RgbaColor;
export declare const DATA_ATTR = "data-annotation";
/** @private */
export declare const debounce: <F extends (...args: Parameters<F>) => ReturnType<F>>(func: F, waitFor: number) => (...args: Parameters<F>) => void;
/** @private */
export declare function debounceTail<T, A extends unknown[]>(fn: (this: T, ...args: A) => void, delay: number): (this: T, ...args: A) => void;
export declare type DeepPartial<T> = {
[K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};
export declare const DEFAULT_EDIT_ICON = "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12 6.00015H7.33333C6.97971 6.00015 6.64057 6.14063 6.39052 6.39068C6.14048 6.64072 6 6.97986 6 7.33348V16.6668C6 17.0204 6.14048 17.3596 6.39052 17.6096C6.64057 17.8597 6.97971 18.0002 7.33333 18.0002H16.6667C17.0203 18.0002 17.3594 17.8597 17.6095 17.6096C17.8595 17.3596 18 17.0204 18 16.6668V12.0002M16.25 5.75015C16.5152 5.48493 16.8749 5.33594 17.25 5.33594C17.6251 5.33594 17.9848 5.48493 18.25 5.75015C18.5152 6.01537 18.6642 6.37508 18.6642 6.75015C18.6642 7.12522 18.5152 7.48493 18.25 7.75015L12.2413 13.7595C12.083 13.9176 11.8875 14.0334 11.6727 14.0962L9.75733 14.6562C9.69997 14.6729 9.63916 14.6739 9.58127 14.6591C9.52339 14.6442 9.47055 14.6141 9.4283 14.5719C9.38604 14.5296 9.35593 14.4768 9.3411 14.4189C9.32627 14.361 9.32727 14.3002 9.344 14.2428L9.904 12.3275C9.96702 12.1129 10.083 11.9175 10.2413 11.7595L16.25 5.75015Z\" stroke=\"#1A70E5\" stroke-width=\"1.33333\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n";
/** Default send button icon (paper plane) */
export declare const DEFAULT_SEND_ICON = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n <path d=\"M22 2L11 13M22 2L15 22L11 13M22 2L2 9L11 13\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>";
/**
* Default options for creating new Arrow annotations.
* Contains the default arrow structure with {@link defaultArrowStyle}.
*/
export declare const defaultArrowOptions: Arrow;
/**
* Default style configuration for arrow annotations.
*
* @example
* ```typescript
* {
* strokeType: "plain",
* strokeColor: "#202020",
* strokeWidth: 1,
* head: "none",
* tail: "none"
* }
* ```
*/
export declare const defaultArrowStyle: ArrowStyles;
/**
* Default options for creating new Box annotations.
* Contains the default box structure with {@link defaultBoxStyle}.
*/
export declare const defaultBoxOptions: Box;
/**
* Default style configuration for box annotations.
*
* @example
* ```typescript
* {
* background: "#f5f5f5",
* strokeWidth: 0,
* borderRadius: 8,
* padding: 16,
* strokeType: "plain"
* }
* ```
*/
export declare const defaultBoxStyle: BoxStyle;
/**
* Default options for creating new Comments.
* Contains the default comment configuration with {@link defaultCommentStyle}.
*
* @example
* ```typescript
* {
* mode: "expanded",
* width: 200,
* height: 120,
* content: "",
* style: defaultCommentStyle
* }
* ```
*/
export declare const defaultCommentOptions: Partial<CommentProps>;
/**
* Default style for Comment annotations
*
* @example
* ```typescript
* {
* // Box styling
* background: "#FFFACD", // Light yellow (sticky note color)
* padding: 8,
* borderRadius: 4,
* strokeColor: "#DDD",
* strokeWidth: 1,
* strokeType: "plain",
*
* // Icon styling (collapsed mode)
* iconColor: "#FFCB2F", // Gold
* iconSymbol: "💬",
* iconBorderColor: "#aaa",
* iconBorderWidth: 2,
*
* // Size properties
* minHeight: 60,
* iconSize: 32,
*
* // Text styling
* color: "#333",
* font: "Arial, sans-serif",
* fontSize: 12,
*
* // Editing UI
* showSendButton: true,
* autoGrow: true,
*
* // Visual effects
* shadow: true,
* expandOnSelect: false,
*
* // Fixed size (always screen-aligned)
* fixedSize: true
* }
* ```
*/
export declare const defaultCommentStyle: CommentStyle;
/**
* Default polygon properties for creating new Polygon annotations.
* Contains the default polygon configuration with {@link defaultPolygonStyle}.
*/
export declare const defaultPolygonProperties: PolygonProperties;
/**
* Default style configuration for polygon annotations.
*
* @example
* ```typescript
* {
* background: "transparent",
* strokeWidth: 2,
* borderRadius: 8,
* padding: 16,
* strokeType: "plain",
* strokeColor: "#000000"
* }
* ```
*/
export declare const defaultPolygonStyle: PolygonStyle;
/**
* Default options for creating new Text annotations.
* Contains the default text structure with {@link defaultTextStyle}.
*/
export declare const defaultTextOptions: Text_2;
/**
* Default style configuration for text annotations.
*
* @example
* ```typescript
* {
* font: "sans-serif",
* fontSize: 18,
* color: "#505050",
* background: "#f5f5f5",
* strokeWidth: 0,
* borderRadius: 8,
* padding: 16,
* strokeType: "plain",
* fixedSize: false
* }
* ```
*/
export declare const defaultTextStyle: TextStyle;
/**
* @private
* @param a Arrow annotation
* @param point Point to test
* @param threshold Detection threshold
* @returns True if the point is on the arrow line within the given threshold
*/
export declare function detectArrow(a: Arrow, point: Point_3, threshold: number): boolean;
/** @private */
export declare function detectBox(a: Box, p: Point, sin?: number, cos?: number, threshold?: number): boolean;
/**
* Detect if a point is within a comment's bounds
* @private
* @param comment - Comment to test
* @param point - Point to test
* @param threshold - Detection threshold in pixels
* @param zoom - Current zoom level
* @returns True if point is within comment bounds
*/
export declare function detectComment(comment: Comment_2, point: Point, threshold: number | undefined, sin: number, cos: number, zoom?: number): boolean;
/**
* Point-in-polygon detection using ray casting algorithm
* @private
* @param polygon The polygon annotation
* @param point The point to test
* @param threshold Detection threshold in pixels
* @return True if the point is inside the polygon or within the threshold distance from its edges
*/
export declare function detectPolygon(polygon: Polygon, point: Point, threshold?: number): boolean;
/**
* Detects whether a point is within a text annotation's bounds.
* @private
* @param a Text annotation
* @param p Point to test
* @param threshold Detection threshold
* @param sin Rotation sine
* @param cos Rotation cosine
* @param zoom Current zoom level
* @returns True if the point is within the text bounds, false otherwise
*/
export declare function detectText(a: Text_2, p: Point, threshold?: number, sin?: number, cos?: number, zoom?: number): boolean;
/** Event related to a single annotation feature */
declare interface DragEvent_2 {
/** Annotation ID involved in the event */
id: Id;
/** Current mouse position in pixel coordinates during the drag */
position: {
x: number;
y: number;
};
}
export { DragEvent_2 as DragEvent }
export declare const EVT_ADD = "add";
export declare const EVT_CANCEL_DRAWING = "cancelDrawing";
export declare const EVT_CLICK = "click";
export declare const EVT_COMPLETE_DRAWING = "completeDrawing";
export declare const EVT_DRAG = "dragging";
export declare const EVT_DRAG_END = "dragend";
export declare const EVT_DRAG_START = "dragstart";
export declare const EVT_HISTORY = "history";
export declare const EVT_HOVER = "hover";
export declare const EVT_LINK = "link";
export declare const EVT_REMOVE = "remove";
export declare const EVT_SELECT = "select";
export declare const EVT_UNHOVER = "unhover";
export declare const EVT_UNSELECT = "unselect";
export declare const EVT_UPDATE = "update";
export declare type ExportedLink = {
id: Id;
side: Side;
type: TargetType;
magnet?: Point;
};
/** Extremity types for arrow annotations. */
export declare type Extremity = "none" | "arrow" | "arrow-plain" | "dot" | "halo-dot";
/** Event related to a single annotation feature */
export declare interface FeatureEvent {
/** Annotation ID involved in the event */
id: Id;
}
export declare type FeatureEvents = {
/**
* Event trigerred when selecting an annotation
* @param evt The annotation selected
*/
[EVT_SELECT]: (evt: FeaturesEvent) => void;
/**
* Event trigerred when unselecting an annotation
* @param evt The annotation unselected
*/
[EVT_UNSELECT]: (evt: FeaturesEvent) => void;
/**
* Event trigerred when removing an annotation
* @param evt The annotation removed
*/
[EVT_REMOVE]: (evt: FeatureEvent) => void;
/**
* Event trigerred when adding an annotation
* @param evt The annotation added
*/
[EVT_ADD]: (evt: FeatureEvent) => void;
/**
* Event trigerred when canceling drawing mode
*/
[EVT_CANCEL_DRAWING]: () => void;
/**
* Event trigerred when completing a drawing operation
* @param evt Contains the ID of the completed annotation
*/
[EVT_COMPLETE_DRAWING]: (evt: FeatureEvent) => void;
/**
* Event trigerred when updating an annotation.
* This fires after any modification including drag operations, style changes, scaling, etc.
* @param evt The updated annotation with all changes applied
*/
[EVT_UPDATE]: (evt: Annotation) => void;
/**
* Event trigerred when linking an arrow to a node or annotation
* @param evt Contains the arrow and link details
*/
[EVT_LINK]: (evt: {
arrow: Arrow;
link: Link;
}) => void;
/**
* Event trigerred when history state changes (after undo/redo operations)
* @param evt Contains boolean flags for undo/redo availability
*/
[EVT_HISTORY]: (evt: HistoryEvent) => void;
/**
* Event triggered when a drag operation starts on an annotation
*/
[EVT_DRAG_START]: (evt: DragEvent_2) => void;
/**
* Event triggered when a drag operation ends on an annotation
*/
[EVT_DRAG_END]: (evt: DragEvent_2) => void;
/**
* Event triggered when a click completes on an annotation (mouseup without drag)
*/
[EVT_CLICK]: (evt: ClickEvent) => void;
};
/** Event related to multiple annotation features */
export declare interface FeaturesEvent {
/** Annotation IDs involved in the event */
ids: Id[];
}
/**
* Calculate the bounds of a collection of annotations
* @param annotations
* @returns Bounds [minX, minY, maxX, maxY]
*/
export declare function getAnnotationsBounds(annotations: AnnotationCollection): Bounds;
export declare function getArrowEnd(a: Arrow): {
x: number;
y: number;
};
export declare function getArrowEndPoints(a: Arrow): {
start: {
x: number;
y: number;
};
end: {
x: number;
y: number;
};
};
export declare function getArrowSide(a: Arrow, side: Side): {
x: number;
y: number;
};
export declare function getArrowStart(a: Arrow): {
x: number;
y: number;
};
export declare function getAttachmentPointOnNode(start: Point_3, nodeCenter: Point_3, nodeRadius: number): {
x: number;
y: number;
};
declare function getBbox<T extends Annotation>(b: T): BBox;
export { getBbox }
export { getBbox as getTextBbox }
export declare function getBoxCenter<T extends Annotation>(t: T): {
x: number;
y: number;
};
declare function getBoxPosition<T extends Annotation>(t: T, fixedSize?: boolean, zoom?: number): {
x: number;
y: number;
};
export { getBoxPosition }
export { getBoxPosition as getTextPosition }
declare function getBoxSize<T extends Annotation>(t: T): {
width: number;
height: number;
};
export { getBoxSize }
export { getBoxSize as getTextSize }
/** @private */
export declare function getBrowserWindow(): HTMLElement | undefined;
/**
* Get the position (center) of a comment
*
* @param comment - Comment annotation
* @returns Center position
*/
export declare function getCommentPosition(comment: Comment_2): Point;
/**
* Get the dimensions of a comment based on its mode
*
* @param comment - Comment annotation
* @returns Width and height
*/
export declare function getCommentSize(comment: Comment_2): Size;
/**
* Get the effective zoom threshold for a comment
* Uses explicit threshold if set, otherwise calculates from dimensions
*
* @param comment - Comment annotation
* @returns Effective zoom threshold
*/
export declare function getCommentZoomThreshold(comment: Comment_2): number;
export declare function getCoordinates(geojson: Feature | FeatureCollection | Geometry): Position[];
export declare const getHandleId: (handle: HTMLDivElement) => number;
/**
* Get bounding box of a polygon
*/
export declare function getPolygonBounds(polygon: Polygon): Bounds;
/**
* Get centroid (geometric center) of a polygon
*/
export declare function getPolygonCenter(polygon: Polygon): Point;
export declare const handleDetectionThreshold = 5;
export declare const handleRadius = 3;
/**
* Hex color string in format #RGB or #RRGGBB
* @example "#fff" | "#ffffff" | "#F0A" | "#FF00AA"
*/
export declare type HexColor = `#${string}`;
export declare function hexShortToLong(color: HexColor): HexColor;
/**
* Adds alpha channel to a hex color
* @param color
* @param alpha
* @returns rgba color string
*/
export declare function hexToRgba(color: HexColor, alpha: number): RgbaColor;
/** History stack change event */
export declare interface HistoryEvent {
/** Indicates if undo operation is available */
canUndo: boolean;
/** Indicates if redo operation is available */
canRedo: boolean;
}
export declare const HL_BRIGHTEN = 0.2;
/** Unique identifier type for annotations */
export declare type Id = string | number;
/** Helper to check if a feature collection is an annotation collection */
export declare const isAnnotationCollection: (a: AnnotationFeature<Geometry, AnnotationProps> | FeatureCollection) => a is AnnotationCollection;
export declare const isArrow: (a: AnnotationFeatur