@linkurious/ogma-annotations 2.1.0 → 2.1.2

package/dist/types/index.d.ts

@@ -173,6 +173,15 @@ export declare interface BoxStyle extends StrokeOptions {
  */
 export declare const brighten: (color: Color) => RgbaColor;
 
+/**
+ * Move `el` to the end of `root`'s children. SVG paint order is DOM order,
+ * so this is how a shape gets raised to the top of its group. Safe to call
+ * every render even when `el` is already last - `appendChild` on an
+ * existing child just re-positions it, it doesn't clone or re-trigger
+ * insertion.
+ */
+export declare function bringToTop(root: Element, el: Element): void;
+
 /**
  * Calculate optimal zoom threshold for auto-collapse based on comment dimensions
  *
@@ -324,6 +333,14 @@ export declare interface CommentStyle extends TextStyle {
     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";
 }
 
 /**
@@ -556,6 +573,51 @@ export declare class Control extends default_2<FeatureEvents> {
         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.
@@ -603,6 +665,21 @@ export declare class Control extends default_2<FeatureEvents> {
         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.
      *
@@ -1412,6 +1489,42 @@ export { getBoxSize as getTextSize }
 /** @private */
 export declare function getBrowserWindow(): HTMLElement | undefined;
 
+/**
+ * Ids that removing `id` should take with it: `id` itself, plus every arrow
+ * attached to it when it's a comment or text annotation - deleting the
+ * anchor takes its connectors along, since a detached comment-arrow has
+ * nothing to point at.
+ *
+ * @param features - The full feature map (pre-deletion)
+ * @param id - The id being removed
+ * @returns The complete set of ids to delete
+ */
+export declare function getCascadeDeleteIds(features: Record<Id, Annotation>, id: Id): Set<Id>;
+
+/**
+ * Comments must always keep at least one arrow. Returns the comment's id
+ * when deleting `arrowId` would leave it with none, so the caller can block
+ * the deletion instead - or `null` when it's safe to proceed.
+ *
+ * @param features - The full feature map (pre-deletion)
+ * @param arrowId - The arrow being removed
+ */
+export declare function getCommentLeftOrphanedBy(features: Record<Id, Annotation>, arrowId: Id): Id | null;
+
+/**
+ * Get the id of the comment an arrow is connected to, if any.
+ *
+ * A comment is one visual annotation together with the arrow that connects
+ * it - callers that raise a comment's z-order (e.g. bringing a newly
+ * created/selected comment to the front) should raise this arrow along with
+ * it, not just the comment bubble.
+ *
+ * @param arrow - The arrow feature to check
+ * @returns The linked comment's id, or undefined if the arrow isn't attached
+ * to a comment
+ */
+export declare function getCommentLinkId(arrow: Arrow): Id | undefined;
+
 /**
  * Get the position (center) of a comment
  *
@@ -1507,9 +1620,8 @@ export declare const isComment: (a: AnnotationFeature<Geometry, AnnotationProps>
  * These functions provide utilities for:
  * - Checking if an arrow is connected to a comment
  * - Determining if arrow endpoints can be detached from comments
- *
- * Note: The core rule "comments must have at least one arrow" is enforced
- * in store/index.ts removeFeature() method, not here.
+ * - Cascading a comment's delete to its arrows, and blocking deletion of a
+ *   comment's last remaining arrow (store/index.ts:removeFeature uses both)
  */
 /**
  * Check if an arrow is connected to a comment
@@ -1543,6 +1655,16 @@ export declare function isRgbaColor(color: string): color is RgbaColor;
  */
 export declare function isRgbColor(color: string): color is RgbColor;
 
+/**
+ * Whether a comment's connector line should rigidly follow its attachment
+ * point (translate the comment by the same offset) rather than elastically
+ * re-anchoring to the nearest point on the comment box.
+ *
+ * @param comment - Comment annotation
+ * @returns True unless the comment's style explicitly sets `connectorMode: "elastic"`
+ */
+export declare function isRigidConnector(comment: Comment_2): boolean;
+
 export declare const isText: (a: AnnotationFeature<Geometry, AnnotationProps>) => a is Text_2;
 
 /** @private */
@@ -1751,6 +1873,13 @@ export declare interface TextStyle extends BoxStyle {
     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;
 }
 
 /** @private */