@linkurious/ogma-annotations 2.1.0 → 2.1.2

package/dist/types/ui.d.ts

@@ -0,0 +1,1423 @@
+import { default as default_2 } from 'eventemitter3';
+import { Feature } from 'geojson';
+import { FeatureCollection } 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 { Polygon as Polygon_2 } from 'geojson';
+
+/** Union type of all Annotation features */
+declare type Annotation = Arrow | Box | Text_2 | Comment_2 | Polygon;
+
+/** Collection of Annotations, GeoJSON FeatureCollection */
+declare interface AnnotationCollection extends FeatureCollection {
+    features: Annotation[];
+}
+
+/**
+ * Base interface for all annotation features.
+ * @template G - Geometry type
+ * @template P - Properties type
+ */
+declare interface AnnotationFeature<G extends GeometryObject = GeometryObject, P = AnnotationProps> extends Feature<G, P> {
+    /** Unique identifier for the annotation */
+    id: Id;
+}
+
+export declare class AnnotationPanel {
+    private control;
+    private panel;
+    private panelBody;
+    private mode;
+    private currentAnnotation;
+    private currentColor;
+    private recent;
+    private colorCircles;
+    private colorPickerOverlay;
+    private colorPicker;
+    private detachVisibility;
+    private documentClickHandler;
+    constructor(options: AnnotationPanelOptions);
+    private setAnnotation;
+    private renderArrow;
+    private renderText;
+    private renderPolygon;
+    private section;
+    private icon;
+    private colorSelector;
+    private backgroundSelector;
+    private fontSelector;
+    private extremitySelector;
+    private dropdown;
+    private slider;
+    private lineTypeButtons;
+    private bind;
+    private updateColorFromAnnotation;
+    private updateColorCircles;
+    private toggleColorPicker;
+    private closeColorPicker;
+    private updateStyle;
+    setPlacement(placement: PanelPlacement): void;
+    setOrientation(orientation: PanelOrientation): void;
+    show(): void;
+    hide: () => void;
+    destroy(): void;
+}
+
+export declare interface AnnotationPanelOptions {
+    control: Control;
+    /**
+     * Element the panel mounts into. The panel creates and manages its own root
+     * `<div class="annotation-panel">` inside it. Defaults to `document.body`.
+     */
+    container?: HTMLElement;
+    /**
+     * Which screen edge/corner the panel docks to. Defaults to `"right"`
+     * (vertically centered on the right edge — the original look). Change at
+     * runtime with {@link AnnotationPanel.setPlacement}.
+     */
+    placement?: PanelPlacement;
+    /**
+     * Whether panel sections stack vertically or run horizontally as a
+     * toolbar. Defaults to `"vertical"`. Change at runtime with
+     * {@link AnnotationPanel.setOrientation}.
+     */
+    orientation?: PanelOrientation;
+}
+
+/**
+ * Base properties for all annotations.
+ */
+declare interface AnnotationProps {
+    /** Type of annotation */
+    type: AnnotationType;
+    /** Optional style configuration */
+    style?: unknown;
+}
+
+/**
+ * Styled drawing/undo-redo toolbar: add arrow, comment, box, text and
+ * polygon annotations, undo/redo, and delete the current selection. The
+ * React equivalent is `AddMenu` (`@linkurious/ogma-annotations-react/ui`) -
+ * this class mirrors its buttons and defaults for a vanilla consumer.
+ */
+export declare class AnnotationToolbar {
+    private control;
+    private root;
+    private activeButton;
+    private undoButton;
+    private redoButton;
+    private handleDrawingEnd;
+    private handleHistory;
+    constructor(options: AnnotationToolbarOptions);
+    private drawingButton;
+    private button;
+    private separator;
+    private setActiveMode;
+    private updateUndoRedo;
+    setPlacement(placement: PanelPlacement): void;
+    setOrientation(orientation: PanelOrientation): void;
+    destroy(): void;
+}
+
+export declare interface AnnotationToolbarOptions {
+    control: Control;
+    /**
+     * Element the toolbar mounts into. The toolbar creates and manages its
+     * own root `<div class="annotation-toolbar">` inside it. Defaults to
+     * `document.body`.
+     */
+    container?: HTMLElement;
+    /**
+     * Which screen edge/corner the toolbar docks to. Defaults to `"bottom"`.
+     * Change at runtime with {@link AnnotationToolbar.setPlacement}.
+     */
+    placement?: PanelPlacement;
+    /**
+     * Whether buttons run left-to-right or stack top-to-bottom. Defaults to
+     * `"horizontal"`. Change at runtime with
+     * {@link AnnotationToolbar.setOrientation}.
+     */
+    orientation?: PanelOrientation;
+    /**
+     * Which drawing tools to show, and in what order. Defaults to all six:
+     * `["arrow", "comment", "sticky-note", "box", "text", "polygon"]`.
+     */
+    enabledTypes?: ToolbarDrawingType[];
+    /** Per-type default style overrides for the drawing tool buttons. */
+    styles?: AnnotationToolbarStyles;
+    /**
+     * Which deletion control(s) to show - the erase tool, the
+     * select-then-trash button, or both. Defaults to `"erase"`.
+     */
+    deleteMode?: DeleteMode;
+    /** Called when the SVG export button is clicked. Omit to hide the button. */
+    onSvgExport?: () => void;
+    /** Called when the JSON export button is clicked. Omit to hide the button. */
+    onJsonExport?: () => void;
+}
+
+/**
+ * Per-type default style overrides, merged over the toolbar's own built-in
+ * defaults (which stay in effect for anything you don't override). See
+ * `Control.enableArrowDrawing` etc. for what each shape configures.
+ */
+export declare interface AnnotationToolbarStyles {
+    arrow?: Partial<Arrow["properties"]["style"]>;
+    box?: Partial<Box["properties"]["style"]>;
+    text?: Partial<Text_2["properties"]["style"]>;
+    polygon?: Partial<Polygon["properties"]["style"]>;
+    comment?: {
+        offsetX?: number;
+        offsetY?: number;
+        commentStyle?: Partial<CommentProps>;
+        arrowStyle?: Partial<ArrowProperties>;
+    };
+    stickyNote?: Partial<Text_2["properties"]["style"]>;
+}
+
+/** Types of annotations supported */
+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.
+ */
+declare interface Arrow extends AnnotationFeature<LineString, ArrowProperties> {
+}
+
+declare interface ArrowProperties extends AnnotationProps {
+    type: "arrow";
+    style?: ArrowStyles;
+    link?: Partial<Record<Side, ExportedLink>>;
+}
+
+/**
+ * Styles specific to arrow annotations.
+ */
+declare interface ArrowStyles extends StrokeOptions {
+    /** Tail extremity style */
+    tail?: Extremity;
+    /** Head extremity style */
+    head?: Extremity;
+}
+
+/**
+ * Wires `control` events to show/hide callbacks. Returns a `detach` function
+ * that removes every listener it registered.
+ */
+export declare function attachPanelVisibility(control: PanelVisibilityControl, { onShow, onHide }: PanelVisibilityHandlers): () => void;
+
+export declare interface BackgroundOption {
+    value: string;
+    /** Inline style for the swatch's color circle. */
+    style: string;
+}
+
+export declare const BACKGROUNDS: BackgroundOption[];
+
+/**
+ * Box annotation feature
+ */
+declare interface Box extends AnnotationFeature<Point_2, BoxProperties> {
+}
+
+/**
+ * Arrow snapped to a rectangular annotation (text, box, comment).
+ * nx/ny are center-relative fractions multiplied by width/height:
+ *   left-center  = { nx: -0.5, ny: 0 }
+ *   right-center = { nx:  0.5, ny: 0 }
+ *   center       = { nx:  0,   ny: 0 }
+ */
+declare type BoxMagnet = {
+    type: "box";
+    nx: number;
+    ny: number;
+};
+
+/** Properties specific to box annotations. */
+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. */
+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;
+}
+
+/** Event related to a single annotation feature */
+declare interface ClickEvent {
+    /** Annotation ID involved in the event */
+    id?: Id;
+    /** Mouse position in pixel coordinates */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Any valid color format
+ */
+declare type Color = HexColor | RgbColor | RgbaColor_2 | "transparent" | "none" | string;
+
+/**
+ * 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> {
+}
+
+declare const COMMENT_MODE_COLLAPSED = "collapsed";
+
+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
+ */
+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
+ */
+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;
+    /**
+     * Connector-line behavior when the attachment point moves (default: "rigid").
+     * - "rigid": the comment translates by the same offset as the moved
+     *   attachment point — the arrow keeps its length/angle, whole callout moves.
+     * - "elastic": the comment stays put; the arrow re-anchors to the nearest
+     *   point on the comment box, so the line can stretch/rotate.
+     */
+    connectorMode?: "rigid" | "elastic";
+}
+
+/**
+ * Main controller class for managing annotations.
+ * It manages rendering and editing of annotations.
+ */
+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;
+    /**
+     * Enable sticky note drawing mode - drops a plain, resizable text box
+     * (empty content, "Quick note…" ghost placeholder, no connector arrow)
+     * like a Miro sticky note, unlike `enableCommentDrawing`. It's a regular
+     * `text` annotation, so it's placed the same interactive way as
+     * `enableBoxDrawing`/`enableTextDrawing`: click for a default-size square,
+     * or drag to size it - either way it keeps the usual corner/edge drag
+     * handles to resize it afterward.
+     *
+     * Call this method when the user clicks an "Add sticky note" button. The
+     * control will:
+     * 1. Wait for the next mousedown event
+     * 2. Create the note at that position and start the interactive
+     *    corner-drag, already selected
+     * 3. On release: a plain click (no drag) gets a default square size, a
+     *    drag gets sized to match instead - either way it drops straight
+     *    into editing (the placeholder is just ghost text, so typing
+     *    immediately replaces it)
+     * 4. Clean up automatically when done
+     *
+     * @example
+     * ```ts
+     * addStickyNoteButton.addEventListener('click', () => {
+     *   control.enableStickyNoteDrawing({ background: '#FFEB99' });
+     * });
+     * ```
+     *
+     * @param style Sticky note style options (merged over the sticky note defaults)
+     * @returns this for chaining
+     * @see startStickyNote for low-level programmatic control
+     */
+    enableStickyNoteDrawing(style?: Partial<Text_2["properties"]["style"]>): this;
+    /**
+     * Enable erase mode: every click on an annotation deletes it immediately.
+     * Stays armed across multiple clicks until `disableEraseMode()` is called,
+     * or another drawing tool is enabled / `cancelDrawing()` is called.
+     *
+     * @returns this for chaining
+     * @see disableEraseMode to turn erase mode off
+     */
+    enableEraseMode(): this;
+    /** Turn erase mode off. No-op if it isn't active. */
+    disableEraseMode(): this;
+    /** Whether erase mode is currently active. */
+    isEraseModeActive(): boolean;
+    /**
+     * 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 sticky note at
+     * specific coordinates - same interactive corner-drag as `startBox`.
+     * You must handle mouse events yourself (or immediately release/complete
+     * it via the same events `enableStickyNoteDrawing` would).
+     *
+     * **For most use cases, use `enableStickyNoteDrawing()` instead.**
+     *
+     * @param x X coordinate for the note's top-left corner
+     * @param y Y coordinate for the note's top-left corner
+     * @param style Sticky note style options
+     * @returns this for chaining
+     * @see enableStickyNoteDrawing for the recommended high-level API
+     */
+    startStickyNote(x: number, y: number, style?: Partial<Text_2["properties"]["style"]>): 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
+ */
+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;
+};
+
+/**
+ * Registers `<rgba-color-picker>` if it isn't already, then returns a fresh
+ * instance. Safe to call repeatedly and from multiple module copies.
+ */
+export declare function createRgbaColorPicker(): RgbaColorPicker;
+
+declare type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export declare const DEFAULT_PANEL_ORIENTATION: PanelOrientation;
+
+/** Preserves the panel's original vertically-centered, right-docked look. */
+export declare const DEFAULT_PANEL_PLACEMENT: PanelPlacement;
+
+/** Default palette used to seed the recent-colors strip. */
+export declare const DEFAULT_RECENT_COLORS: string[];
+
+/**
+ * Which deletion control(s) the toolbar shows - `"erase"` (default) deletes
+ * on click via the erase tool; `"select"` selects an annotation then deletes
+ * it with the trash button; `"both"` shows both, since they serve slightly
+ * different workflows.
+ */
+export declare type DeleteMode = "select" | "erase" | "both";
+
+/** 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;
+    };
+}
+
+/** Arrow snapped at parametric position t (0–1) along an edge path. */
+declare type EdgeMagnet = {
+    type: "edge";
+    t: number;
+};
+
+declare const EVT_ADD = "add";
+
+declare const EVT_CANCEL_DRAWING = "cancelDrawing";
+
+declare const EVT_CLICK = "click";
+
+declare const EVT_COMPLETE_DRAWING = "completeDrawing";
+
+declare const EVT_DRAG_END = "dragend";
+
+declare const EVT_DRAG_START = "dragstart";
+
+declare const EVT_HISTORY = "history";
+
+declare const EVT_LINK = "link";
+
+declare const EVT_REMOVE = "remove";
+
+declare const EVT_SELECT = "select";
+
+declare const EVT_UNSELECT = "unselect";
+
+declare const EVT_UPDATE = "update";
+
+/**
+ * Serialized link stored inside arrow.properties.link.
+ * Uses plain { x, y } for backward compatibility with saved annotations.
+ * Converted to the internal Magnet type by Links.add().
+ */
+declare type ExportedLink = {
+    id: Id;
+    side: Side;
+    type: TargetType;
+    magnet?: Point;
+};
+
+/** Extremity types for arrow annotations. */
+declare type Extremity = "none" | "arrow" | "arrow-plain" | "dot" | "halo-dot";
+
+export declare const EXTREMITY_OPTIONS: ExtremityOption[];
+
+export declare interface ExtremityOption {
+    value: string;
+    label: string;
+    icon: IconName;
+}
+
+/** Event related to a single annotation feature */
+declare interface FeatureEvent {
+    /** Annotation ID involved in the event */
+    id: Id;
+}
+
+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 */
+declare interface FeaturesEvent {
+    /** Annotation IDs involved in the event */
+    ids: Id[];
+}
+
+export declare interface FontOption {
+    value: string;
+    label: string;
+    /** Icon name from the shared icon set (see `ui/icons`). */
+    icon: IconName;
+}
+
+export declare const FONTS: FontOption[];
+
+/**
+ * Hex color string in format #RGB or #RRGGBB
+ * @example "#fff" | "#ffffff" | "#F0A" | "#FF00AA"
+ */
+declare type HexColor = `#${string}`;
+
+/** History stack change event */
+declare interface HistoryEvent {
+    /** Indicates if undo operation is available */
+    canUndo: boolean;
+    /** Indicates if redo operation is available */
+    canRedo: boolean;
+}
+
+/** Inner SVG markup for each icon (paths only; no <svg> wrapper). */
+export declare const ICON_PATHS: Record<IconName, string>;
+
+/**
+ * Inline SVG icon set shared by the vanilla and React UI.
+ *
+ * Each entry is the *inner* markup of a 24x24 lucide icon (stroke-based,
+ * `currentColor`). The vanilla panel wraps these with `svgIcon()`; the React
+ * package wraps the same paths in a small `<Icon>` component. Keeping the path
+ * data here means consumers need no icon font and no `lucide-react` runtime
+ * dependency.
+ *
+ * Source: lucide.dev (ISC license).
+ */
+export declare type IconName = "chevron-down" | "x" | "arrow-left" | "arrow-right" | "play" | "circle-dot" | "dot" | "circle" | "circle-dashed" | "type" | "italic" | "code" | "trash" | "undo" | "redo" | "pentagon" | "rectangle-horizontal" | "message-square" | "sticky-note" | "eraser" | "download" | "camera" | "rotate-cw" | "rotate-ccw" | "minimize";
+
+/** Unique identifier type for annotations */
+declare type Id = string | number;
+
+export declare function initialRecentColors(): RecentColorsState;
+
+export declare const LINE_TYPES: LineTypeOption[];
+
+export declare interface LineTypeOption {
+    value: string;
+    icon: IconName;
+}
+
+/** Link between an arrow and a text or node */
+declare interface Link {
+    /** arrow attached 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;
+    /** Typed snap point — semantics depend on targetType, see Magnet union. */
+    magnet: Magnet;
+}
+
+declare type Magnet = NodeMagnet | EdgeMagnet | BoxMagnet | PolygonMagnet;
+
+export declare const MAX_RECENT_COLORS = 3;
+
+/** Arrow snapped to the center or perimeter of a node. */
+declare type NodeMagnet = {
+    type: "node";
+    center: boolean;
+};
+
+/** Whether panel sections stack top-to-bottom or run left-to-right. */
+export declare type PanelOrientation = "vertical" | "horizontal";
+
+/**
+ * Placement and orientation options shared by the vanilla `AnnotationPanel`
+ * and the React panel/controller. Both are applied as `data-placement` /
+ * `data-orientation` attributes on the panel root, consumed by the rules in
+ * `ui/styles.css` — no inline layout styles are set from JS.
+ */
+/** Which screen edge/corner the panel docks to. */
+export declare type PanelPlacement = "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
+/**
+ * The slice of `Control` this state machine relies on. Declared structurally so
+ * the function does not pull the full `Control` type into the `/ui` entry's
+ * rolled declarations (which would otherwise create a duplicate, incompatible
+ * `Control` identity for consumers).
+ */
+export declare interface PanelVisibilityControl {
+    on(event: string, handler: (...args: any[]) => void): unknown;
+    off(event: string, handler: (...args: any[]) => void): unknown;
+    once(event: string, handler: (...args: any[]) => void): unknown;
+    getAnnotation(id: string | number): Annotation | undefined;
+    isDrawing(): boolean;
+}
+
+export declare interface PanelVisibilityHandlers {
+    /** Called when the panel should be shown for `annotation`. */
+    onShow: (annotation: Annotation) => void;
+    /** Called when the panel should be hidden. */
+    onHide: () => void;
+}
+
+/** 2D coordinate */
+declare type Point = {
+    x: number;
+    y: number;
+};
+
+/**
+ * Polygon placed on the graph, use it to highlight areas
+ */
+declare interface Polygon extends AnnotationFeature<Polygon_2, PolygonProperties> {
+}
+
+/**
+ * Arrow snapped to a polygon annotation.
+ * rx/ry are 0–1 fractions of the polygon's bounding box from its top-left corner.
+ */
+declare type PolygonMagnet = {
+    type: "polygon";
+    rx: number;
+    ry: number;
+};
+
+declare interface PolygonProperties extends AnnotationProps {
+    type: "polygon";
+    style?: PolygonStyle;
+}
+
+declare interface PolygonStyle extends BoxStyle {
+}
+
+export declare interface RecentColorsState {
+    colors: string[];
+    /** Index of the currently active swatch. */
+    activeIndex: number;
+}
+
+/** Channel-wise rgba, matching the shape emitted by `vanilla-colorful`. */
+export declare interface RgbaChannels {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+/** Channel-wise rgba color, as read/written by the picker's `color` property. */
+export declare interface RgbaColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+/**
+ * RGBA color string in format rgba(r, g, b, a)
+ * @example "rgba(255, 0, 0, 1)" | "rgba(128, 128, 128, 0.5)"
+ */
+declare type RgbaColor_2 = `rgba(${number}, ${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})`;
+
+/**
+ * The public surface of the `<rgba-color-picker>` element we rely on. Declared
+ * locally (rather than re-exporting `vanilla-colorful`'s class type) so that
+ * consumers don't have to resolve the package's deep `lib/entrypoints` types,
+ * which it does not expose via its `exports` map.
+ */
+export declare interface RgbaColorPicker extends HTMLElement {
+    color: RgbaColor;
+    addEventListener(type: "color-changed", listener: (event: CustomEvent<{
+        value: RgbaColor;
+    }>) => void): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+
+/** Serializes an rgba object (as emitted by the color picker) to a CSS string. */
+export declare function rgbaToString(color: RgbaChannels): string;
+
+/**
+ * RGB color string in format rgb(r, g, b)
+ * @example "rgb(255, 0, 0)" | "rgb(128, 128, 128)"
+ */
+declare type RgbColor = `rgb(${number}, ${number}, ${number})` | `rgb(${number},${number},${number})`;
+
+declare type Side = typeof SIDE_START | typeof SIDE_END;
+
+declare const SIDE_END: "end";
+
+declare const SIDE_START: "start";
+
+/** Stroke style options for annotations */
+declare type StrokeOptions = {
+    /** Type of stroke: plain, dashed, or none */
+    strokeType?: StrokeType;
+    /** Stroke color: #f00, yellow... */
+    strokeColor?: Color;
+    /** Stroke width */
+    strokeWidth?: number;
+};
+
+/** Stroke types available for annotations */
+declare type StrokeType = "plain" | "dashed" | "none";
+
+/**
+ * Returns a complete `<svg>` string for the named icon, ready to drop into
+ * `innerHTML`. Used by the vanilla panel.
+ */
+export declare function svgIcon(name: IconName, size?: number): string;
+
+/** @private */
+declare const TARGET_TYPES: {
+    TEXT: "text";
+    NODE: "node";
+    BOX: "box";
+    COMMENT: "comment";
+    POLYGON: "polygon";
+    ANNOTATION: "annotation";
+    EDGE: "edge";
+};
+
+declare type TargetType = (typeof TARGET_TYPES)[keyof typeof TARGET_TYPES];
+
+/**
+ * Text annotation feature, represents a text box at a specific position
+ */
+declare interface Text_2 extends AnnotationFeature<Point_2, TextProperties> {
+}
+
+declare interface TextProperties extends Omit<BoxProperties, "type"> {
+    type: "text";
+    /**text to display*/
+    content: string;
+    /** Width of the text box */
+    width: number;
+    /** Height of the text box */
+    height: number;
+    style?: TextStyle;
+}
+
+declare interface TextStyle extends BoxStyle {
+    /** Helvetica, sans-serif...  */
+    font?: string;
+    /** Font size, in pixels */
+    fontSize?: number | string;
+    /** text color: #f00, yellow...*/
+    color?: Color;
+    /** background color: empty for transparent #f00, yellow...*/
+    background?: Color;
+    /** padding around the text */
+    padding?: number;
+    /** Text box border radius */
+    borderRadius?: number;
+    /** When true, text maintains constant size regardless of zoom level */
+    fixedSize?: boolean;
+    /**
+     * Ghost text shown (via the textarea's native `placeholder` attribute)
+     * while `content` is empty - disappears the instant the user types, no
+     * selection/focus tricks needed. Overrides the global
+     * `ControllerOptions.textPlaceholder` for this annotation.
+     */
+    placeholder?: string;
+}
+
+/** One of the toolbar's drawing tools - see `enabledTypes`. */
+export declare type ToolbarDrawingType = "arrow" | "comment" | "sticky-note" | "box" | "text" | "polygon";
+
+/**
+ * Given the current recent-colors state and a color coming from the selected
+ * annotation, returns the next state: if the color is already known it becomes
+ * active, otherwise it is unshifted to the front (capped at MAX_RECENT_COLORS).
+ *
+ * Pure — callers (React/vanilla) hold the state and apply the result.
+ */
+export declare function withColorFromAnnotation(state: RecentColorsState, color: string): RecentColorsState;
+
+export { }