@linkurious/ogma-annotations 2.0.3 → 2.1.1

package/dist/ogma-annotations.css

@@ -1 +1 @@
-:root{--handle-width: 2px;--point-handle-width: calc(3 * var(--handle-width));--point-handle-border: 2px;--point-handle-total: calc(var(--point-handle-width) + var(--point-handle-border));--handle-color: #38e;--handle-background: #fff;--active-color: #1a70e5;--disabled-color: #999;--hover-color: rgba(56, 136, 238, .2)}svg text{-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.handle{position:absolute;background-color:var(--handle-color)}.handle.line{cursor:move}.ogma-annotation-text-editor{display:flex;flex-direction:column;align-items:flex-end;position:relative;width:100%;height:100%}.ogma-annotation-text-editor.animate-width{transition:width .2s ease-out,left .2s ease-out}.ogma-annotation-text-editor textarea{outline:none;padding:0;margin:0;border:0;width:100%;height:100%;cursor:text;z-index:1000;resize:none;white-space:break-spaces;background-color:transparent;overflow:hidden}.ogma-annotation-text-editor textarea::-webkit-scrollbar{width:6px}.ogma-annotation-text-editor textarea::-webkit-scrollbar-track{background:transparent}.ogma-annotation-text-editor textarea::-webkit-scrollbar-thumb{background:#0003;border-radius:3px}.ogma-annotation-text-editor textarea::-webkit-scrollbar-thumb:hover{background:#0000004d}.ogma-send-button{width:24px;height:24px;margin-left:auto;border:none;background:transparent;cursor:pointer;display:flex;align-items:center;justify-content:center;border-radius:4px;transition:background-color .2s ease;z-index:1001}.ogma-send-button-icon{width:16px;height:16px;display:flex;align-items:center;justify-content:center;color:var(--handle-color, #38e)}.ogma-send-button-icon svg{width:100%;height:100%}.ogma-send-button:not(:disabled):hover{background-color:var(--hover-color);transform:scale(1.05)}.ogma-send-button:not(:disabled):hover .ogma-send-button-icon{color:var(--active-color)}.ogma-send-button:not(:disabled):active{background-color:var(--hover-color);transform:scale(.95)}.ogma-send-button:not(:disabled):active .ogma-send-button-icon{color:var(--active-color)}.ogma-send-button:disabled{cursor:not-allowed;opacity:.3}.ogma-send-button:disabled .ogma-send-button-icon{color:var(--disabled-color)}.annotation-text-handle .noevents{pointer-events:none;z-index:20}.line-handle,.point-handle{z-index:30}.line-handle.top{cursor:ns-resize;height:var(--handle-width);left:0;width:100%;top:calc(var(--handle-width) * -1)}.line-handle.bottom{cursor:ns-resize;height:var(--handle-width);width:100%;left:0;bottom:calc(var(--handle-width) * -1)}.line-handle.left{cursor:ew-resize;height:100%;top:0;left:calc(var(--handle-width) * -1);width:var(--handle-width)}.line-handle.right{cursor:ew-resize;height:100%;right:calc(var(--handle-width) * -1);top:0;width:var(--handle-width)}.line-handle.top,.line-handle.bottom,.line-handle.left,.line-handle.right{cursor:move}.point-handle{border-radius:50%;background-color:#fff;transform-origin:center;transform:translate(-50%,-50%);border:var(--point-handle-border) solid var(--handle-color);width:var(--point-handle-width);height:var(--point-handle-width)}.point-handle.top-left{transform:translate(-55%,-55%)}.point-handle.top-right{transform:translate(-45%,-55%)}.point-handle.bottom-left{transform:translate(-55%,-45%)}.point-handle.bottom-right{transform:translate(-45%,-45%)}.rotated .point-handle.bottom-left,.rotated .point-handle.top-right{display:none}.point-handle.top-left,.point-handle.bottom-right{cursor:nwse-resize}.point-handle.top-right,.point-handle.bottom-left{cursor:nesw-resize}.point-handle.bottom-left,.point-handle.bottom-right{top:100%}.point-handle.top-left,.point-handle.top-right{top:0}.point-handle.bottom-left,.point-handle.top-left{left:0}.point-handle.bottom-right,.point-handle.top-right{left:100%}.arrow-handle>.handle{height:var(--point-handle-width);width:var(--point-handle-width);border-radius:50%;cursor:move;transform:translate(-50%,-50%)}.arrow-handle>.line{height:var(--handle-width);border-radius:0;cursor:move}.arrow-handle>.point{background-color:var(--handle-background);border:2px solid var(--handle-color)}.annotations-hidden-input{position:absolute;bottom:0;left:0;visibility:hidden;display:block}.active{background-color:#38e}.annotation-text{cursor:pointer}.annotation-text:hover>rect{stroke:var(--handle-color)}.annotation-text a{fill:var(--handle-color)}.annotation-text a:hover{text-decoration:underline}.annotation-hovered,.annotation-selected{background:#f5f5f5;background-color:#f5f5f5}
+:root{--handle-width: 2px;--point-handle-width: calc(3 * var(--handle-width));--point-handle-border: 2px;--point-handle-total: calc(var(--point-handle-width) + var(--point-handle-border));--handle-color: #38e;--annotation-link-color: var(--handle-color);--handle-background: #fff;--active-color: #1a70e5;--disabled-color: #999;--hover-color: rgba(56, 136, 238, .2)}svg text{-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.ogma-annotation-link{fill:var(--annotation-link-color, #38e);color:var(--annotation-link-color, #38e);text-decoration:none;pointer-events:auto;cursor:pointer}.handle{position:absolute;background-color:var(--handle-color)}.handle.line{cursor:move}.ogma-annotation-text-editor{display:flex;flex-direction:column;align-items:flex-end;position:relative;width:100%;height:100%}.ogma-annotation-text-editor.animate-width{transition:width .2s ease-out,left .2s ease-out}.ogma-annotation-text-editor textarea{outline:none;padding:0;margin:0;border:0;width:100%;height:100%;cursor:text;z-index:1000;resize:none;white-space:break-spaces;background-color:transparent;overflow:hidden}.ogma-annotation-text-editor textarea::-webkit-scrollbar{width:6px}.ogma-annotation-text-editor textarea::-webkit-scrollbar-track{background:transparent}.ogma-annotation-text-editor textarea::-webkit-scrollbar-thumb{background:#0003;border-radius:3px}.ogma-annotation-text-editor textarea::-webkit-scrollbar-thumb:hover{background:#0000004d}.ogma-send-button{width:24px;height:24px;margin-left:auto;border:none;background:transparent;cursor:pointer;display:flex;align-items:center;justify-content:center;border-radius:4px;transition:background-color .2s ease;z-index:1001}.ogma-send-button-icon{width:16px;height:16px;display:flex;align-items:center;justify-content:center;color:var(--handle-color, #38e)}.ogma-send-button-icon svg{width:100%;height:100%}.ogma-send-button:not(:disabled):hover{background-color:var(--hover-color);transform:scale(1.05)}.ogma-send-button:not(:disabled):hover .ogma-send-button-icon{color:var(--active-color)}.ogma-send-button:not(:disabled):active{background-color:var(--hover-color);transform:scale(.95)}.ogma-send-button:not(:disabled):active .ogma-send-button-icon{color:var(--active-color)}.ogma-send-button:disabled{cursor:not-allowed;opacity:.3}.ogma-send-button:disabled .ogma-send-button-icon{color:var(--disabled-color)}.annotation-text-handle .noevents{pointer-events:none;z-index:20}.line-handle,.point-handle{z-index:30}.line-handle.top{cursor:ns-resize;height:var(--handle-width);left:0;width:100%;top:calc(var(--handle-width) * -1)}.line-handle.bottom{cursor:ns-resize;height:var(--handle-width);width:100%;left:0;bottom:calc(var(--handle-width) * -1)}.line-handle.left{cursor:ew-resize;height:100%;top:0;left:calc(var(--handle-width) * -1);width:var(--handle-width)}.line-handle.right{cursor:ew-resize;height:100%;right:calc(var(--handle-width) * -1);top:0;width:var(--handle-width)}.line-handle.top,.line-handle.bottom,.line-handle.left,.line-handle.right{cursor:move}.point-handle{border-radius:50%;background-color:#fff;transform-origin:center;transform:translate(-50%,-50%);border:var(--point-handle-border) solid var(--handle-color);width:var(--point-handle-width);height:var(--point-handle-width)}.point-handle.top-left{transform:translate(-55%,-55%)}.point-handle.top-right{transform:translate(-45%,-55%)}.point-handle.bottom-left{transform:translate(-55%,-45%)}.point-handle.bottom-right{transform:translate(-45%,-45%)}.rotated .point-handle.bottom-left,.rotated .point-handle.top-right{display:none}.point-handle.top-left,.point-handle.bottom-right{cursor:nwse-resize}.point-handle.top-right,.point-handle.bottom-left{cursor:nesw-resize}.point-handle.bottom-left,.point-handle.bottom-right{top:100%}.point-handle.top-left,.point-handle.top-right{top:0}.point-handle.bottom-left,.point-handle.top-left{left:0}.point-handle.bottom-right,.point-handle.top-right{left:100%}.arrow-handle>.handle{height:var(--point-handle-width);width:var(--point-handle-width);border-radius:50%;cursor:move;transform:translate(-50%,-50%)}.arrow-handle>.line{height:var(--handle-width);border-radius:0;cursor:move}.arrow-handle>.point{background-color:var(--handle-background);border:2px solid var(--handle-color)}.annotations-hidden-input{position:absolute;bottom:0;left:0;visibility:hidden;display:block}.active{background-color:#38e}.annotation-text{cursor:pointer}.annotation-text:hover>rect{stroke:var(--handle-color)}.annotation-text a{fill:var(--handle-color)}.annotation-text a:hover{text-decoration:underline}.annotation-hovered,.annotation-selected{background:#f5f5f5;background-color:#f5f5f5}

package/dist/types/index.d.ts

@@ -128,6 +128,19 @@ export declare type Bounds = [number, number, number, number];
 export 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 }
+ */
+export declare type BoxMagnet = {
+    type: "box";
+    nx: number;
+    ny: number;
+};
+
 /** Properties specific to box annotations. */
 export declare interface BoxProperties extends AnnotationProps {
     type: "box";
@@ -543,6 +556,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.
@@ -590,6 +648,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.
      *
@@ -1209,6 +1282,12 @@ declare interface DragEvent_2 {
 }
 export { DragEvent_2 as DragEvent }
 
+/** Arrow snapped at parametric position t (0–1) along an edge path. */
+export declare type EdgeMagnet = {
+    type: "edge";
+    t: number;
+};
+
 export declare const EVT_ADD = "add";
 
 export declare const EVT_CANCEL_DRAWING = "cancelDrawing";
@@ -1239,6 +1318,11 @@ export declare const EVT_UNSELECT = "unselect";
 
 export 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().
+ */
 export declare type ExportedLink = {
     id: Id;
     side: Side;
@@ -1540,13 +1624,12 @@ export declare interface Link {
     target: Id;
     /** Text or node */
     targetType: TargetType;
-    /**
-     * On which point relative to topleft corner the arrow is tighten, in case of
-     * node, a 0 vector represents the center, otherwise it can be deduced from the arrow itself
-     */
-    magnet: Point;
+    /** Typed snap point — semantics depend on targetType, see Magnet union. */
+    magnet: Magnet;
 }
 
+export declare type Magnet = NodeMagnet | EdgeMagnet | BoxMagnet | PolygonMagnet;
+
 /**
  * Migrates old Polygon-based Box/Text to new Point-based format
  * Called only when annotations are added/loaded
@@ -1554,6 +1637,12 @@ export declare interface Link {
  */
 export declare function migrateBoxOrTextIfNeeded<T extends Annotation>(annotation: T): T;
 
+/** Arrow snapped to the center or perimeter of a node. */
+export declare type NodeMagnet = {
+    type: "node";
+    center: boolean;
+};
+
 export declare const NONE = -1;
 
 export declare function parseColor(color: Color): {
@@ -1575,6 +1664,16 @@ export declare type Point = {
 export 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.
+ */
+export declare type PolygonMagnet = {
+    type: "polygon";
+    rx: number;
+    ry: number;
+};
+
 export declare interface PolygonProperties extends AnnotationProps {
     type: "polygon";
     style?: PolygonStyle;
@@ -1712,6 +1811,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 */