@teachinglab/omd 0.6.1 → 0.6.3

package/omd/utils/omdNodeOverlay.js

@@ -1,638 +1,638 @@
-/**
- * omdNodeOverlay - A utility class for covering up nodes with overlay elements
- * 
- * This class creates a visual overlay that can be positioned over any node
- * to hide or mask it. Useful for step-by-step reveals, progressive disclosure,
- * or highlighting specific parts of expressions.
- */
-
-import { omdPopup } from './omdPopup.js';
-import { jsvgGroup, jsvgRect } from '@teachinglab/jsvg';
-
-/**
- * A flexible overlay system for covering nodes with customizable elements
- * @extends jsvgGroup
- */
-export class omdNodeOverlay extends jsvgGroup {
-    /**
-     * Creates a new node overlay
-     * @param {Object} options - Configuration options
-     * @param {string} options.fillColor - Fill color for the overlay (default: 'white')
-     * @param {string} options.strokeColor - Stroke color for the overlay (default: 'black')
-     * @param {number} options.strokeWidth - Stroke width (default: 2)
-     * @param {number} options.opacity - Opacity of the overlay (default: 1.0)
-     * @param {number} options.padding - Padding around the target node (default: 0)
-     * @param {number} options.cornerRadius - Corner radius for rounded rectangles (default: 4)
-     * @param {string} options.overlayType - Type of overlay: 'rectangle', 'ellipse', 'text' (default: 'rectangle')
-     * @param {boolean} options.animated - Whether to animate show/hide transitions (default: false)
-     * @param {string} options.text - Initial text for text overlays (default: '')
-     * @param {boolean} options.editable - Whether text overlay should be editable (default: false)
-     */
-    constructor(options = {}) {
-        super();
-        
-        this.options = {
-            fillColor: 'white',
-            strokeColor: 'black',
-            strokeWidth: 2,
-            opacity: 1.0,
-            padding: 0,
-            cornerRadius: 4,
-            overlayType: 'rectangle',
-            animated: false,
-            animationDuration: 300,
-            text: '',
-            editable: false,
-            ...options
-        };
-        
-        this.targetNode = null;
-        this.overlayElement = null;
-        this.textElement = null;
-        this.isVisible = false;
-        this.animationId = null;
-        this.clickLayer = null;
-        this.savedHandlers = [];
-        this.omdPopup = null;
-        
-        this._createOverlayElement();
-    }
-    
-    /**
-     * Creates the actual overlay element based on the overlay type
-     * @private
-     */
-    _createOverlayElement() {
-        switch (this.options.overlayType) {
-            case 'rectangle':
-                this.overlayElement = new jsvgRect();
-                if (this.options.cornerRadius > 0) {
-                    this.overlayElement.setCornerRadius(this.options.cornerRadius);
-                }
-                break;
-            case 'ellipse':
-                this.overlayElement = new jsvgEllipse();
-                break;
-            case 'text':
-                this._createTextOverlay();
-                return;
-            default:
-                this.overlayElement = new jsvgRect();
-        }
-        
-        this.overlayElement.setFillColor(this.options.fillColor);
-        this.overlayElement.setStrokeColor(this.options.strokeColor);
-        this.overlayElement.setStrokeWidth(this.options.strokeWidth);
-        this.overlayElement.setOpacity(this.options.opacity);
-        this.addChild(this.overlayElement);
-        this.setOpacity(0);
-    }
-    
-    /**
-     * Creates a text overlay with background and editable text
-     * @private
-     */
-    _createTextOverlay() {
-        // Create background rectangle
-        this.overlayElement = new jsvgRect();
-        if (this.options.cornerRadius > 0) {
-            this.overlayElement.setCornerRadius(this.options.cornerRadius);
-        }
-        this.overlayElement.setFillColor(this.options.fillColor);
-        this.overlayElement.setStrokeColor(this.options.strokeColor);
-        this.overlayElement.setStrokeWidth(this.options.strokeWidth);
-        this.overlayElement.setOpacity(this.options.opacity);
-        this.addChild(this.overlayElement);
-        
-        // Create a click-only layer for editable overlays
-        if (this.options.editable) {
-            this.clickLayer = new jsvgRect();
-            this.clickLayer.setWidthAndHeight(this.overlayElement.width, this.overlayElement.height);
-            this.clickLayer.setPosition(0, 0);
-            this.clickLayer.setFillColor('transparent');
-            this.clickLayer.setStrokeColor('transparent');
-            this.addChild(this.clickLayer);
-            
-            this.clickLayer.setClickCallback(() => {
-                this.togglePopup();
-            });
-        }
-        
-        // For editable overlays, create a popup instead of inline text
-        if (this.options.editable) {
-            this.textElement = null;
-        } else {
-            // For static text overlays, use jsvgTextLine
-            this.textElement = new jsvgTextLine();
-            this.textElement.setText(this.options.text);
-            this.textElement.setTextAnchor('middle');
-            this.textElement.svgObject.setAttribute('dominant-baseline', 'middle');
-            this.addChild(this.textElement);
-        }
-        
-        this.setOpacity(0);
-    }
-    
-    /**
-     * Targets a specific node to overlay
-     * @param {omdNode} node - The node to cover
-     * @returns {omdNodeOverlay} This overlay for method chaining
-     */
-    coverNode(node) {
-        if (!node) {
-            console.warn('omdNodeOverlay: Cannot cover null or undefined node');
-            return this;
-        }
-        
-        this.targetNode = node;
-        
-        // Save and override parent mouse handlers to prevent highlighting
-        this.savedHandlers = [];
-        let current = this.targetNode;
-        while (current) {
-            if (current.svgObject && typeof current.svgObject.onmouseenter === 'function') {
-                this.savedHandlers.push({
-                    element: current.svgObject,
-                    onmouseenter: current.svgObject.onmouseenter,
-                    onmouseleave: current.svgObject.onmouseleave,
-                });
-                current.svgObject.onmouseenter = null;
-                current.svgObject.onmouseleave = null;
-            }
-            current = current.parent;
-        }
-
-        // Add the overlay as a child of the target node's parent
-        if (this.targetNode.parent) {
-            node.parent.addChild(this);
-        }
-        
-        this._updateOverlayPosition();
-        return this;
-    }
-    
-    /**
-     * Manually sets the overlay position and size
-     * @param {number} x - X position
-     * @param {number} y - Y position
-     * @param {number} width - Width of the overlay
-     * @param {number} height - Height of the overlay
-     * @param {boolean} clearTargetNode - Whether to clear the target node
-     * @returns {omdNodeOverlay} This overlay for method chaining
-     */
-    setCoverArea(x, y, width, height, clearTargetNode = true) {
-        if (clearTargetNode) {
-            this.targetNode = null;
-        }
-        
-        const padding = this.options.padding || 0;
-        const adjustedX = x - padding;
-        const adjustedY = y - padding;
-        const adjustedWidth = width + (padding * 2);
-        const adjustedHeight = height + (padding * 2);
-        
-        this.setPosition(adjustedX, adjustedY);
-        this.overlayElement.setWidthAndHeight(adjustedWidth, adjustedHeight);
-        
-        // Update click layer size to match overlay
-        if (this.clickLayer) {
-            this.clickLayer.setWidthAndHeight(adjustedWidth, adjustedHeight);
-        }
-        
-        // Position text element for text overlays
-        if (this.options.overlayType === 'text' && this.textElement) {
-                this.textElement.setPosition(adjustedWidth / 2, adjustedHeight / 2);
-        }
-        
-        return this;
-    }
-    
-    /**
-     * Updates the overlay position to match the target node
-     * @private
-     */
-    _updateOverlayPosition() {
-        if (!this.targetNode) return;
-        
-        // Get the position relative to the overlay's parent
-        let nodePos;
-        if (this.parent === this.targetNode.parent) {
-            nodePos = {
-                x: this.targetNode.xpos || this.targetNode.x || 0,
-                y: this.targetNode.ypos || this.targetNode.y || 0
-            };
-        } else {
-            nodePos = this._getGlobalPosition(this.targetNode);
-        }
-        
-        let nodeWidth = this.targetNode.width || 0;
-        let nodeHeight = this.targetNode.height || 0;
-        
-        // Prefer backRect dimensions if available
-        if (this.targetNode.backRect) {
-            nodeWidth = this.targetNode.backRect.width || nodeWidth;
-            nodeHeight = this.targetNode.backRect.height || nodeHeight;
-        }
-        
-        this.setCoverArea(nodePos.x, nodePos.y, nodeWidth, nodeHeight, false);
-        
-
-    }
-    
-    /**
-     * Attempts to match visual properties of the target node
-     * @private
-     */
-    _matchNodeProperties() {
-        if (!this.targetNode) return;
-        
-        // Try to match corner radius for rectangles
-        if (this.options.overlayType === 'rectangle' && this.overlayElement.setCornerRadius) {
-            let cornerRadius = 0;
-            
-            // First, check if the node has a backRect (common in OMD nodes)
-            if (this.targetNode.backRect && this.targetNode.backRect.cornerRadius !== undefined) {
-                cornerRadius = this.targetNode.backRect.cornerRadius;
-            }
-            // Fallback: check the main SVG object for rx/ry attributes
-            else if (this.targetNode.svgObject) {
-                const rx = this.targetNode.svgObject.getAttribute('rx');
-                const ry = this.targetNode.svgObject.getAttribute('ry');
-                cornerRadius = parseFloat(rx || ry || 0);
-            }
-            // Another fallback: check if the SVG object is a rect with corner radius
-            else if (this.targetNode.svgObject && this.targetNode.svgObject.tagName === 'rect') {
-                const rx = this.targetNode.svgObject.getAttribute('rx');
-                const ry = this.targetNode.svgObject.getAttribute('ry');
-                cornerRadius = parseFloat(rx || ry || 0);
-            }
-            
-            // Apply the corner radius if found
-            if (cornerRadius > 0) {
-                this.overlayElement.setCornerRadius(cornerRadius);
-                this.options.cornerRadius = cornerRadius;
-            }
-        }
-        
-        // Match font properties for text overlays
-        if (this.options.overlayType === 'text' && this.textElement) {
-            this._matchFontProperties();
-        }
-        
-        // Try to match stroke width if target has stroke
-        if (this.targetNode.svgObject && !this.options.preserveStrokeWidth) {
-            const targetStrokeWidth = this.targetNode.svgObject.getAttribute('stroke-width');
-            if (targetStrokeWidth) {
-                const strokeWidth = parseFloat(targetStrokeWidth);
-                if (strokeWidth > 0) {
-                    this.overlayElement.setStrokeWidth(strokeWidth);
-                }
-            }
-        }
-    }
-    
-    /**
-     * Matches font properties from the target node
-     * @private
-     */
-    _matchFontProperties() {
-        if (!this.targetNode || !this.textElement) return;
-        
-        // Get font size from target node
-        let fontSize = 32; // Default fallback
-        if (this.targetNode.getFontSize && typeof this.targetNode.getFontSize === 'function') {
-            fontSize = this.targetNode.getFontSize();
-        } else if (this.targetNode.fontSize) {
-            fontSize = this.targetNode.fontSize;
-        }
-        this.textElement.setFontSize(fontSize);
-        
-        // Try to match font family and color from target node's text element
-        if (this.targetNode.textElement) {
-            const targetTextSvg = this.targetNode.textElement.svgObject;
-            if (targetTextSvg) {
-                // Match font family
-                const fontFamily = targetTextSvg.style.fontFamily || 'Arial, Helvetica, sans-serif';
-                this.textElement.setFontFamily(fontFamily);
-                
-                // Match font color - handle both jsvgTextLine and jsvgTextInput
-                const fontColor = targetTextSvg.style.fill || targetTextSvg.getAttribute('fill') || 'black';
-                if (this.textElement.setFontColor) {
-                    this.textElement.setFontColor(fontColor);
-                } else if (this.textElement.div) {
-                    // For jsvgTextInput, set color on the div
-                    this.textElement.div.style.color = fontColor;
-                }
-                
-                // Match font weight if available
-                const fontWeight = targetTextSvg.style.fontWeight;
-                if (fontWeight && this.textElement.setFontWeight) {
-                    this.textElement.setFontWeight(fontWeight);
-                } else if (fontWeight && this.textElement.div) {
-                    // For jsvgTextInput, set font weight on the div
-                    this.textElement.div.style.fontWeight = fontWeight;
-                }
-            }
-        }
-    }
-    
-    /**
-     * Calculates the global position of a node
-     * @param {omdNode} node - The node to get position for
-     * @returns {Object} Object with x and y coordinates
-     * @private
-     */
-    _getGlobalPosition(node) {
-        // Try to use SVG bounding box for accurate positioning
-        if (node.svgObject && node.svgObject.getCTM) {
-            try {
-                const ctm = node.svgObject.getCTM();
-                if (ctm) {
-                    return { x: ctm.e, y: ctm.f };
-                }
-            } catch (e) {
-                // Fall back to manual calculation
-            }
-        }
-        
-        let x = node.xpos || node.x || 0;
-        let y = node.ypos || node.y || 0;
-        
-        // Walk up the parent chain
-        let parent = node.parent;
-        while (parent && parent.xpos !== undefined) {
-            x += parent.xpos || parent.x || 0;
-            y += parent.ypos || parent.y || 0;
-            parent = parent.parent;
-        }
-        
-        return { x, y };
-    }
-    
-    /**
-     * Creates the popup instance
-     * @private
-     */
-    _createPopup() {
-        if (!this.options.editable || this.omdPopup) return;
-        
-        // Create the popup instance
-        this.omdPopup = new omdPopup(this.targetNode, this.parent, {
-            animationDuration: this.options.animationDuration
-        });
-        
-        // Set initial text value
-        this.omdPopup.setValue(this.options.text);
-        
-        // Set up validation callback
-        this.omdPopup.setValidationCallback(() => {
-            const currentText = this.omdPopup.getValue();
-            
-            if (this.targetNode) {
-                const nodeText = this.targetNode.text || this.targetNode.toString() || "";
-                
-                if (this.omdPopup.areExpressionsEquivalent(currentText.trim(), nodeText.trim())) {
-                    // Show success and destroy overlay
-                    this.omdPopup.flashValidation(true);
-                    setTimeout(() => {
-                        this.destroy();
-                    }, 500);
-                } else {
-                    // Show error
-                    this.omdPopup.flashValidation(false);
-                }
-            }
-        });
-        
-        // Set up clear callback
-        this.omdPopup.setClearCallback(() => {
-            this.omdPopup.setValue('');
-        });
-    }
-    
-    /**
-     * Toggles the popup visibility
-     * @returns {Promise} Promise that resolves when animation completes
-     */
-    togglePopup() {
-        if (!this.options.editable) return Promise.resolve();
-        
-        if (!this.omdPopup) {
-            this._createPopup();
-        }
-        
-        const overlayX = this.xpos || this.x || 0;
-        const overlayY = this.ypos || this.y || 0;
-        const overlayWidth = this.overlayElement.width || this.targetNode.width || 100;
-        const overlayHeight = this.overlayElement.height || this.targetNode.height || 40;
-        const popupWidth = 400;
-        
-        const popupX = overlayX + (overlayWidth / 2) - (popupWidth / 2);
-        const popupY = overlayY + overlayHeight + 10;
-        
-        return this.omdPopup.toggle(popupX, popupY);
-    }
-    
-
-    
-
-    
-
-
-
-
-    /**
-     * Hides and removes the popup
-     * @private
-     */
-    _hidePopup() {
-        if (this.omdPopup) {
-            this.omdPopup.destroy();
-            this.omdPopup = null;
-        }
-    }
-
-    /**
-     * Shows the overlay
-     * @param {boolean} animated - Whether to animate the show
-     * @returns {Promise} Promise that resolves when animation completes
-     */
-    show(animated = this.options.animated) {
-        return new Promise((resolve) => {
-            if (this.isVisible) {
-                resolve();
-                return;
-            }
-            
-            this.isVisible = true;
-            
-            if (animated) {
-                this._animateOpacity(0, this.options.opacity, this.options.animationDuration)
-                    .then(resolve);
-            } else {
-                this.setOpacity(this.options.opacity);
-                resolve();
-            }
-        });
-    }
-    
-    /**
-     * Animates the opacity from one value to another
-     * @private
-     */
-    _animateOpacity(fromOpacity, toOpacity, duration) {
-        return new Promise((resolve) => {
-            if (this.animationId) {
-                cancelAnimationFrame(this.animationId);
-            }
-            
-            const startTime = performance.now();
-            const deltaOpacity = toOpacity - fromOpacity;
-            
-            const animate = (currentTime) => {
-                const elapsed = currentTime - startTime;
-                const progress = Math.min(elapsed / duration, 1);
-                const easedProgress = 1 - Math.pow(1 - progress, 3);
-                const currentOpacity = fromOpacity + (deltaOpacity * easedProgress);
-                
-                this.setOpacity(currentOpacity);
-                
-                if (progress < 1) {
-                    this.animationId = requestAnimationFrame(animate);
-                } else {
-                    this.animationId = null;
-                    resolve();
-                }
-            };
-            
-            this.animationId = requestAnimationFrame(animate);
-        });
-    }
-    
-        /**
-     * Removes the overlay and cleans up resources
-     * @param {boolean} animated - Whether to animate the destruction
-     * @returns {Promise} Promise that resolves when destruction is complete
-     */
-    destroy(animated = this.options.animated) {
-        return new Promise((resolve) => {
-            if (animated && this.isVisible) {
-                this._animateOpacity(this.options.opacity, 0, this.options.animationDuration)
-                    .then(() => {
-                        this._performDestroy();
-                        resolve();
-                    });
-            } else {
-                this._performDestroy();
-                resolve();
-            }
-        });
-    }
-    
-    /**
-     * Performs the actual destruction without animation
-     * @private
-     */
-    _performDestroy() {
-        if (this.animationId) {
-            cancelAnimationFrame(this.animationId);
-        }
-        
-        // Restore original mouse handlers
-        this.savedHandlers.forEach(({ element, onmouseenter, onmouseleave }) => {
-            if (element) {
-                element.onmouseenter = onmouseenter;
-                element.onmouseleave = onmouseleave;
-            }
-        });
-        
-        this._hidePopup();
-        
-        this.targetNode = null;
-        this.isVisible = false;
-        
-        if (this.parent) {
-            this.parent.removeChild(this);
-        }
-    }
-
-    // === ESSENTIAL GETTERS/SETTERS ===
-    
-    /**
-     * Checks if the overlay is currently visible
-     */
-    getIsVisible() {
-        return this.isVisible;
-    }
-    
-    /**
-     * Gets the currently targeted node
-     */
-    getTargetNode() {
-        return this.targetNode;
-    }
-    
-    /**
-     * Sets the text content for text overlays
-     */
-    setText(text) {
-        if (this.textElement) {
-            this.textElement.setText(text);
-            this.options.text = text;
-        }
-        return this;
-    }
-    
-    /**
-     * Gets the text content from text overlays
-     */
-    getText() {
-        if (this.textElement) {
-            return this.textElement.getText();
-        }
-        return this.options.text;
-    }
-}
-
-/**
- * Factory function for creating common overlay presets
- */
-export class omdNodeOverlayPresets {
-    /**
-     * Creates a simple white overlay for hiding content
-     */
-    static createHidingOverlay(enableTextInput = false, initialText = null) {
-        const config = {
-            fillColor: 'white',
-            strokeColor: 'black',
-            strokeWidth: 2,
-            padding: 1,
-            animated: true
-        };
-        
-        if (enableTextInput) {
-            config.overlayType = 'text';
-            config.text = initialText || '';
-            config.editable = true;
-            config.fillColor = 'white';
-            config.strokeColor = 'black';
-            config.strokeWidth = 2;
-        }
-        
-        return new omdNodeOverlay(config);
-    }
-    
-    /**
-     * Creates a highlighted border overlay for feedback
-     */
-    static createHighlightOverlay(color = '#ffff00') {
-        return new omdNodeOverlay({
-            fillColor: 'none',
-            strokeColor: color,
-            strokeWidth: 3,
-            padding: 2,
-            cornerRadius: 4,
-            animated: true
-        });
-    }
-}
+/**
+ * omdNodeOverlay - A utility class for covering up nodes with overlay elements
+ * 
+ * This class creates a visual overlay that can be positioned over any node
+ * to hide or mask it. Useful for step-by-step reveals, progressive disclosure,
+ * or highlighting specific parts of expressions.
+ */
+
+import { omdPopup } from './omdPopup.js';
+import { jsvgGroup, jsvgRect } from '@teachinglab/jsvg';
+
+/**
+ * A flexible overlay system for covering nodes with customizable elements
+ * @extends jsvgGroup
+ */
+export class omdNodeOverlay extends jsvgGroup {
+    /**
+     * Creates a new node overlay
+     * @param {Object} options - Configuration options
+     * @param {string} options.fillColor - Fill color for the overlay (default: 'white')
+     * @param {string} options.strokeColor - Stroke color for the overlay (default: 'black')
+     * @param {number} options.strokeWidth - Stroke width (default: 2)
+     * @param {number} options.opacity - Opacity of the overlay (default: 1.0)
+     * @param {number} options.padding - Padding around the target node (default: 0)
+     * @param {number} options.cornerRadius - Corner radius for rounded rectangles (default: 4)
+     * @param {string} options.overlayType - Type of overlay: 'rectangle', 'ellipse', 'text' (default: 'rectangle')
+     * @param {boolean} options.animated - Whether to animate show/hide transitions (default: false)
+     * @param {string} options.text - Initial text for text overlays (default: '')
+     * @param {boolean} options.editable - Whether text overlay should be editable (default: false)
+     */
+    constructor(options = {}) {
+        super();
+        
+        this.options = {
+            fillColor: 'white',
+            strokeColor: 'black',
+            strokeWidth: 2,
+            opacity: 1.0,
+            padding: 0,
+            cornerRadius: 4,
+            overlayType: 'rectangle',
+            animated: false,
+            animationDuration: 300,
+            text: '',
+            editable: false,
+            ...options
+        };
+        
+        this.targetNode = null;
+        this.overlayElement = null;
+        this.textElement = null;
+        this.isVisible = false;
+        this.animationId = null;
+        this.clickLayer = null;
+        this.savedHandlers = [];
+        this.omdPopup = null;
+        
+        this._createOverlayElement();
+    }
+    
+    /**
+     * Creates the actual overlay element based on the overlay type
+     * @private
+     */
+    _createOverlayElement() {
+        switch (this.options.overlayType) {
+            case 'rectangle':
+                this.overlayElement = new jsvgRect();
+                if (this.options.cornerRadius > 0) {
+                    this.overlayElement.setCornerRadius(this.options.cornerRadius);
+                }
+                break;
+            case 'ellipse':
+                this.overlayElement = new jsvgEllipse();
+                break;
+            case 'text':
+                this._createTextOverlay();
+                return;
+            default:
+                this.overlayElement = new jsvgRect();
+        }
+        
+        this.overlayElement.setFillColor(this.options.fillColor);
+        this.overlayElement.setStrokeColor(this.options.strokeColor);
+        this.overlayElement.setStrokeWidth(this.options.strokeWidth);
+        this.overlayElement.setOpacity(this.options.opacity);
+        this.addChild(this.overlayElement);
+        this.setOpacity(0);
+    }
+    
+    /**
+     * Creates a text overlay with background and editable text
+     * @private
+     */
+    _createTextOverlay() {
+        // Create background rectangle
+        this.overlayElement = new jsvgRect();
+        if (this.options.cornerRadius > 0) {
+            this.overlayElement.setCornerRadius(this.options.cornerRadius);
+        }
+        this.overlayElement.setFillColor(this.options.fillColor);
+        this.overlayElement.setStrokeColor(this.options.strokeColor);
+        this.overlayElement.setStrokeWidth(this.options.strokeWidth);
+        this.overlayElement.setOpacity(this.options.opacity);
+        this.addChild(this.overlayElement);
+        
+        // Create a click-only layer for editable overlays
+        if (this.options.editable) {
+            this.clickLayer = new jsvgRect();
+            this.clickLayer.setWidthAndHeight(this.overlayElement.width, this.overlayElement.height);
+            this.clickLayer.setPosition(0, 0);
+            this.clickLayer.setFillColor('transparent');
+            this.clickLayer.setStrokeColor('transparent');
+            this.addChild(this.clickLayer);
+            
+            this.clickLayer.setClickCallback(() => {
+                this.togglePopup();
+            });
+        }
+        
+        // For editable overlays, create a popup instead of inline text
+        if (this.options.editable) {
+            this.textElement = null;
+        } else {
+            // For static text overlays, use jsvgTextLine
+            this.textElement = new jsvgTextLine();
+            this.textElement.setText(this.options.text);
+            this.textElement.setTextAnchor('middle');
+            this.textElement.svgObject.setAttribute('dominant-baseline', 'middle');
+            this.addChild(this.textElement);
+        }
+        
+        this.setOpacity(0);
+    }
+    
+    /**
+     * Targets a specific node to overlay
+     * @param {omdNode} node - The node to cover
+     * @returns {omdNodeOverlay} This overlay for method chaining
+     */
+    coverNode(node) {
+        if (!node) {
+            console.warn('omdNodeOverlay: Cannot cover null or undefined node');
+            return this;
+        }
+        
+        this.targetNode = node;
+        
+        // Save and override parent mouse handlers to prevent highlighting
+        this.savedHandlers = [];
+        let current = this.targetNode;
+        while (current) {
+            if (current.svgObject && typeof current.svgObject.onmouseenter === 'function') {
+                this.savedHandlers.push({
+                    element: current.svgObject,
+                    onmouseenter: current.svgObject.onmouseenter,
+                    onmouseleave: current.svgObject.onmouseleave,
+                });
+                current.svgObject.onmouseenter = null;
+                current.svgObject.onmouseleave = null;
+            }
+            current = current.parent;
+        }
+
+        // Add the overlay as a child of the target node's parent
+        if (this.targetNode.parent) {
+            node.parent.addChild(this);
+        }
+        
+        this._updateOverlayPosition();
+        return this;
+    }
+    
+    /**
+     * Manually sets the overlay position and size
+     * @param {number} x - X position
+     * @param {number} y - Y position
+     * @param {number} width - Width of the overlay
+     * @param {number} height - Height of the overlay
+     * @param {boolean} clearTargetNode - Whether to clear the target node
+     * @returns {omdNodeOverlay} This overlay for method chaining
+     */
+    setCoverArea(x, y, width, height, clearTargetNode = true) {
+        if (clearTargetNode) {
+            this.targetNode = null;
+        }
+        
+        const padding = this.options.padding || 0;
+        const adjustedX = x - padding;
+        const adjustedY = y - padding;
+        const adjustedWidth = width + (padding * 2);
+        const adjustedHeight = height + (padding * 2);
+        
+        this.setPosition(adjustedX, adjustedY);
+        this.overlayElement.setWidthAndHeight(adjustedWidth, adjustedHeight);
+        
+        // Update click layer size to match overlay
+        if (this.clickLayer) {
+            this.clickLayer.setWidthAndHeight(adjustedWidth, adjustedHeight);
+        }
+        
+        // Position text element for text overlays
+        if (this.options.overlayType === 'text' && this.textElement) {
+                this.textElement.setPosition(adjustedWidth / 2, adjustedHeight / 2);
+        }
+        
+        return this;
+    }
+    
+    /**
+     * Updates the overlay position to match the target node
+     * @private
+     */
+    _updateOverlayPosition() {
+        if (!this.targetNode) return;
+        
+        // Get the position relative to the overlay's parent
+        let nodePos;
+        if (this.parent === this.targetNode.parent) {
+            nodePos = {
+                x: this.targetNode.xpos || this.targetNode.x || 0,
+                y: this.targetNode.ypos || this.targetNode.y || 0
+            };
+        } else {
+            nodePos = this._getGlobalPosition(this.targetNode);
+        }
+        
+        let nodeWidth = this.targetNode.width || 0;
+        let nodeHeight = this.targetNode.height || 0;
+        
+        // Prefer backRect dimensions if available
+        if (this.targetNode.backRect) {
+            nodeWidth = this.targetNode.backRect.width || nodeWidth;
+            nodeHeight = this.targetNode.backRect.height || nodeHeight;
+        }
+        
+        this.setCoverArea(nodePos.x, nodePos.y, nodeWidth, nodeHeight, false);
+        
+
+    }
+    
+    /**
+     * Attempts to match visual properties of the target node
+     * @private
+     */
+    _matchNodeProperties() {
+        if (!this.targetNode) return;
+        
+        // Try to match corner radius for rectangles
+        if (this.options.overlayType === 'rectangle' && this.overlayElement.setCornerRadius) {
+            let cornerRadius = 0;
+            
+            // First, check if the node has a backRect (common in OMD nodes)
+            if (this.targetNode.backRect && this.targetNode.backRect.cornerRadius !== undefined) {
+                cornerRadius = this.targetNode.backRect.cornerRadius;
+            }
+            // Fallback: check the main SVG object for rx/ry attributes
+            else if (this.targetNode.svgObject) {
+                const rx = this.targetNode.svgObject.getAttribute('rx');
+                const ry = this.targetNode.svgObject.getAttribute('ry');
+                cornerRadius = parseFloat(rx || ry || 0);
+            }
+            // Another fallback: check if the SVG object is a rect with corner radius
+            else if (this.targetNode.svgObject && this.targetNode.svgObject.tagName === 'rect') {
+                const rx = this.targetNode.svgObject.getAttribute('rx');
+                const ry = this.targetNode.svgObject.getAttribute('ry');
+                cornerRadius = parseFloat(rx || ry || 0);
+            }
+            
+            // Apply the corner radius if found
+            if (cornerRadius > 0) {
+                this.overlayElement.setCornerRadius(cornerRadius);
+                this.options.cornerRadius = cornerRadius;
+            }
+        }
+        
+        // Match font properties for text overlays
+        if (this.options.overlayType === 'text' && this.textElement) {
+            this._matchFontProperties();
+        }
+        
+        // Try to match stroke width if target has stroke
+        if (this.targetNode.svgObject && !this.options.preserveStrokeWidth) {
+            const targetStrokeWidth = this.targetNode.svgObject.getAttribute('stroke-width');
+            if (targetStrokeWidth) {
+                const strokeWidth = parseFloat(targetStrokeWidth);
+                if (strokeWidth > 0) {
+                    this.overlayElement.setStrokeWidth(strokeWidth);
+                }
+            }
+        }
+    }
+    
+    /**
+     * Matches font properties from the target node
+     * @private
+     */
+    _matchFontProperties() {
+        if (!this.targetNode || !this.textElement) return;
+        
+        // Get font size from target node
+        let fontSize = 32; // Default fallback
+        if (this.targetNode.getFontSize && typeof this.targetNode.getFontSize === 'function') {
+            fontSize = this.targetNode.getFontSize();
+        } else if (this.targetNode.fontSize) {
+            fontSize = this.targetNode.fontSize;
+        }
+        this.textElement.setFontSize(fontSize);
+        
+        // Try to match font family and color from target node's text element
+        if (this.targetNode.textElement) {
+            const targetTextSvg = this.targetNode.textElement.svgObject;
+            if (targetTextSvg) {
+                // Match font family
+                const fontFamily = targetTextSvg.style.fontFamily || 'Arial, Helvetica, sans-serif';
+                this.textElement.setFontFamily(fontFamily);
+                
+                // Match font color - handle both jsvgTextLine and jsvgTextInput
+                const fontColor = targetTextSvg.style.fill || targetTextSvg.getAttribute('fill') || 'black';
+                if (this.textElement.setFontColor) {
+                    this.textElement.setFontColor(fontColor);
+                } else if (this.textElement.div) {
+                    // For jsvgTextInput, set color on the div
+                    this.textElement.div.style.color = fontColor;
+                }
+                
+                // Match font weight if available
+                const fontWeight = targetTextSvg.style.fontWeight;
+                if (fontWeight && this.textElement.setFontWeight) {
+                    this.textElement.setFontWeight(fontWeight);
+                } else if (fontWeight && this.textElement.div) {
+                    // For jsvgTextInput, set font weight on the div
+                    this.textElement.div.style.fontWeight = fontWeight;
+                }
+            }
+        }
+    }
+    
+    /**
+     * Calculates the global position of a node
+     * @param {omdNode} node - The node to get position for
+     * @returns {Object} Object with x and y coordinates
+     * @private
+     */
+    _getGlobalPosition(node) {
+        // Try to use SVG bounding box for accurate positioning
+        if (node.svgObject && node.svgObject.getCTM) {
+            try {
+                const ctm = node.svgObject.getCTM();
+                if (ctm) {
+                    return { x: ctm.e, y: ctm.f };
+                }
+            } catch (e) {
+                // Fall back to manual calculation
+            }
+        }
+        
+        let x = node.xpos || node.x || 0;
+        let y = node.ypos || node.y || 0;
+        
+        // Walk up the parent chain
+        let parent = node.parent;
+        while (parent && parent.xpos !== undefined) {
+            x += parent.xpos || parent.x || 0;
+            y += parent.ypos || parent.y || 0;
+            parent = parent.parent;
+        }
+        
+        return { x, y };
+    }
+    
+    /**
+     * Creates the popup instance
+     * @private
+     */
+    _createPopup() {
+        if (!this.options.editable || this.omdPopup) return;
+        
+        // Create the popup instance
+        this.omdPopup = new omdPopup(this.targetNode, this.parent, {
+            animationDuration: this.options.animationDuration
+        });
+        
+        // Set initial text value
+        this.omdPopup.setValue(this.options.text);
+        
+        // Set up validation callback
+        this.omdPopup.setValidationCallback(() => {
+            const currentText = this.omdPopup.getValue();
+            
+            if (this.targetNode) {
+                const nodeText = this.targetNode.text || this.targetNode.toString() || "";
+                
+                if (this.omdPopup.areExpressionsEquivalent(currentText.trim(), nodeText.trim())) {
+                    // Show success and destroy overlay
+                    this.omdPopup.flashValidation(true);
+                    setTimeout(() => {
+                        this.destroy();
+                    }, 500);
+                } else {
+                    // Show error
+                    this.omdPopup.flashValidation(false);
+                }
+            }
+        });
+        
+        // Set up clear callback
+        this.omdPopup.setClearCallback(() => {
+            this.omdPopup.setValue('');
+        });
+    }
+    
+    /**
+     * Toggles the popup visibility
+     * @returns {Promise} Promise that resolves when animation completes
+     */
+    togglePopup() {
+        if (!this.options.editable) return Promise.resolve();
+        
+        if (!this.omdPopup) {
+            this._createPopup();
+        }
+        
+        const overlayX = this.xpos || this.x || 0;
+        const overlayY = this.ypos || this.y || 0;
+        const overlayWidth = this.overlayElement.width || this.targetNode.width || 100;
+        const overlayHeight = this.overlayElement.height || this.targetNode.height || 40;
+        const popupWidth = 400;
+        
+        const popupX = overlayX + (overlayWidth / 2) - (popupWidth / 2);
+        const popupY = overlayY + overlayHeight + 10;
+        
+        return this.omdPopup.toggle(popupX, popupY);
+    }
+    
+
+    
+
+    
+
+
+
+
+    /**
+     * Hides and removes the popup
+     * @private
+     */
+    _hidePopup() {
+        if (this.omdPopup) {
+            this.omdPopup.destroy();
+            this.omdPopup = null;
+        }
+    }
+
+    /**
+     * Shows the overlay
+     * @param {boolean} animated - Whether to animate the show
+     * @returns {Promise} Promise that resolves when animation completes
+     */
+    show(animated = this.options.animated) {
+        return new Promise((resolve) => {
+            if (this.isVisible) {
+                resolve();
+                return;
+            }
+            
+            this.isVisible = true;
+            
+            if (animated) {
+                this._animateOpacity(0, this.options.opacity, this.options.animationDuration)
+                    .then(resolve);
+            } else {
+                this.setOpacity(this.options.opacity);
+                resolve();
+            }
+        });
+    }
+    
+    /**
+     * Animates the opacity from one value to another
+     * @private
+     */
+    _animateOpacity(fromOpacity, toOpacity, duration) {
+        return new Promise((resolve) => {
+            if (this.animationId) {
+                cancelAnimationFrame(this.animationId);
+            }
+            
+            const startTime = performance.now();
+            const deltaOpacity = toOpacity - fromOpacity;
+            
+            const animate = (currentTime) => {
+                const elapsed = currentTime - startTime;
+                const progress = Math.min(elapsed / duration, 1);
+                const easedProgress = 1 - Math.pow(1 - progress, 3);
+                const currentOpacity = fromOpacity + (deltaOpacity * easedProgress);
+                
+                this.setOpacity(currentOpacity);
+                
+                if (progress < 1) {
+                    this.animationId = requestAnimationFrame(animate);
+                } else {
+                    this.animationId = null;
+                    resolve();
+                }
+            };
+            
+            this.animationId = requestAnimationFrame(animate);
+        });
+    }
+    
+        /**
+     * Removes the overlay and cleans up resources
+     * @param {boolean} animated - Whether to animate the destruction
+     * @returns {Promise} Promise that resolves when destruction is complete
+     */
+    destroy(animated = this.options.animated) {
+        return new Promise((resolve) => {
+            if (animated && this.isVisible) {
+                this._animateOpacity(this.options.opacity, 0, this.options.animationDuration)
+                    .then(() => {
+                        this._performDestroy();
+                        resolve();
+                    });
+            } else {
+                this._performDestroy();
+                resolve();
+            }
+        });
+    }
+    
+    /**
+     * Performs the actual destruction without animation
+     * @private
+     */
+    _performDestroy() {
+        if (this.animationId) {
+            cancelAnimationFrame(this.animationId);
+        }
+        
+        // Restore original mouse handlers
+        this.savedHandlers.forEach(({ element, onmouseenter, onmouseleave }) => {
+            if (element) {
+                element.onmouseenter = onmouseenter;
+                element.onmouseleave = onmouseleave;
+            }
+        });
+        
+        this._hidePopup();
+        
+        this.targetNode = null;
+        this.isVisible = false;
+        
+        if (this.parent) {
+            this.parent.removeChild(this);
+        }
+    }
+
+    // === ESSENTIAL GETTERS/SETTERS ===
+    
+    /**
+     * Checks if the overlay is currently visible
+     */
+    getIsVisible() {
+        return this.isVisible;
+    }
+    
+    /**
+     * Gets the currently targeted node
+     */
+    getTargetNode() {
+        return this.targetNode;
+    }
+    
+    /**
+     * Sets the text content for text overlays
+     */
+    setText(text) {
+        if (this.textElement) {
+            this.textElement.setText(text);
+            this.options.text = text;
+        }
+        return this;
+    }
+    
+    /**
+     * Gets the text content from text overlays
+     */
+    getText() {
+        if (this.textElement) {
+            return this.textElement.getText();
+        }
+        return this.options.text;
+    }
+}
+
+/**
+ * Factory function for creating common overlay presets
+ */
+export class omdNodeOverlayPresets {
+    /**
+     * Creates a simple white overlay for hiding content
+     */
+    static createHidingOverlay(enableTextInput = false, initialText = null) {
+        const config = {
+            fillColor: 'white',
+            strokeColor: 'black',
+            strokeWidth: 2,
+            padding: 1,
+            animated: true
+        };
+        
+        if (enableTextInput) {
+            config.overlayType = 'text';
+            config.text = initialText || '';
+            config.editable = true;
+            config.fillColor = 'white';
+            config.strokeColor = 'black';
+            config.strokeWidth = 2;
+        }
+        
+        return new omdNodeOverlay(config);
+    }
+    
+    /**
+     * Creates a highlighted border overlay for feedback
+     */
+    static createHighlightOverlay(color = '#ffff00') {
+        return new omdNodeOverlay({
+            fillColor: 'none',
+            strokeColor: color,
+            strokeWidth: 3,
+            padding: 2,
+            cornerRadius: 4,
+            animated: true
+        });
+    }
+}