@teachinglab/omd 0.1.0

package/omd/step-visualizer/omdStepVisualizerHighlighting.js

@@ -0,0 +1,206 @@
+import { omdColor } from '../../src/omdColor.js';
+import { omdEquationNode } from '../nodes/omdEquationNode.js';
+import { omdStepVisualizerNodeUtils } from '../utils/omdStepVisualizerNodeUtils.js';
+import { omdTreeDiff } from '../utils/omdTreeDiff.js';
+
+/**
+ * Step visualizer highlighting functionality using robust tree diff algorithm.
+ * This class implements optimal substructure matching to identify truly changed nodes
+ * between mathematical equation steps, eliminating the need for special cases.
+ */
+export class omdStepVisualizerHighlighting {
+    constructor(stepVisualizer) {
+        this.stepVisualizer = stepVisualizer;
+        this.highlightedNodes = new Set();
+        this.educationalMode = true; // Enable highlighting of pedagogical simplifications
+    }
+
+    /**
+     * Main entry point for highlighting nodes based on robust tree diff.
+     * @param {number} dotIndex - Index of the dot/step.
+     */
+    highlightAffectedNodes(dotIndex, isOperation = false) {
+        
+        this.clearHighlights();
+
+        const dot = this.stepVisualizer.stepDots[dotIndex];
+        if (!dot || !dot.equationRef) {
+            console.error("Highlighting failed: No equation reference for dot", dotIndex);
+            return;
+        }
+
+        const currentEquation = dot.equationRef;
+        const equationIndex = this.stepVisualizer.steps.indexOf(currentEquation);
+        
+
+        const previousEquation = this._findNearestVisibleEquationAbove(equationIndex);
+        
+        if (!previousEquation) {
+            const leafNodes = omdStepVisualizerNodeUtils.findLeafNodes(currentEquation);
+            leafNodes.forEach(node => this._highlightNode(node));
+            return;
+        }
+        
+        const previousIndex = this.stepVisualizer.steps.indexOf(previousEquation);
+
+        // Use robust tree diff algorithm to find changed nodes
+        const changedNodes = omdTreeDiff.findChangedNodes(previousEquation, currentEquation, {
+            educationalMode: this.educationalMode
+        });
+        
+
+        // Apply highlighting to changed nodes
+        changedNodes.forEach(node => this._highlightNode(node));
+
+        // Use provenance to highlight related nodes in the previous equation
+        if (!isOperation) {
+            this._highlightProvenanceNodes(changedNodes, previousEquation);
+        }
+
+    }
+
+    /**
+     * Highlights a single node with the standard explanation color.
+     * @param {omdNode} node - The node to highlight.
+     * @private
+     */
+    _highlightNode(node) {
+        if (node && typeof node.setExplainHighlight === 'function') {
+            node.setExplainHighlight(true);
+            this.highlightedNodes.add(node);
+        }
+    }
+
+    /**
+     * Finds the nearest visible equation above the given index.
+     * @param {number} currentIndex - Index of current equation.
+     * @returns {omdEquationNode|null} The nearest visible equation above, or null.
+     * @private
+     */
+    _findNearestVisibleEquationAbove(currentIndex) {
+        for (let i = currentIndex - 1; i >= 0; i--) {
+            const step = this.stepVisualizer.steps[i];
+            if (step instanceof omdEquationNode && step.visible !== false) {
+                return step;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Clears all highlights managed by this class.
+     */
+    clearHighlights() {
+        this.highlightedNodes.forEach(node => {
+            if (node && typeof node.setExplainHighlight === 'function') {
+                node.setExplainHighlight(false);
+            }
+        });
+        
+        this.highlightedNodes.clear();
+        this.stepVisualizer.stepVisualizerHighlights.clear();
+    }
+
+    /**
+     * Highlights nodes in the previous equation based on provenance from changed nodes.
+     * This creates a visual connection between the current changes and their origins.
+     * @param {Array} changedNodes - Array of changed nodes in the current equation
+     * @param {omdEquationNode} previousEquation - The previous equation to highlight nodes in
+     * @private
+     */
+    _highlightProvenanceNodes(changedNodes, previousEquation) {
+        
+        const rootNode = previousEquation.getRootNode();
+        if (!rootNode || !rootNode.nodeMap) {
+            return;
+        }
+        
+        const currentIndex = this.stepVisualizer.steps.indexOf(previousEquation) + 1;
+        let targetEquation = null;
+        
+        // Search backwards for the first visible equation
+        for (let i = currentIndex - 1; i >= 0; i--) {
+            const step = this.stepVisualizer.steps[i];
+            if (step instanceof omdEquationNode && step.visible !== false) {
+                targetEquation = step;
+                break;
+            }
+        }
+        
+        if (!targetEquation) {
+            return;
+        }
+        
+        const visited = new Set();
+        const nodesToProcess = [];
+        
+        // Start with the changed nodes' provenance
+        changedNodes.forEach(node => {
+            if (node.provenance && Array.isArray(node.provenance)) {
+                node.provenance.forEach(id => {
+                    if (!visited.has(id)) {
+                        visited.add(id);
+                        nodesToProcess.push(id);
+                    }
+                });
+            }
+        });
+        
+        // Process provenance IDs
+        while (nodesToProcess.length > 0) {
+            const id = nodesToProcess.shift();
+            const provenanceNode = rootNode.nodeMap.get(id);
+            
+            if (provenanceNode) {
+                if (this._belongsToEquation(provenanceNode, targetEquation)) {
+                    this._highlightProvenanceNode(provenanceNode);
+                }
+                // Add this node's provenance to the processing queue
+                if (provenanceNode.provenance && Array.isArray(provenanceNode.provenance)) {
+                    provenanceNode.provenance.forEach(subId => {
+                        if (!visited.has(subId)) {
+                            visited.add(subId);
+                            nodesToProcess.push(subId);
+                            
+                        }
+                    });
+                }
+            } else {
+                
+            }
+        }
+        
+        
+    }
+
+    /**
+     * Checks if a node belongs to a specific equation by traversing up the tree
+     * @param {omdNode} node - The node to check
+     * @param {omdEquationNode} targetEquation - The equation to check against
+     * @returns {boolean} True if the node belongs to the equation
+     * @private
+     */
+    _belongsToEquation(node, targetEquation) {
+        let current = node;
+        while (current) {
+            if (current === targetEquation) {
+                return true;
+            }
+            current = current.parent;
+        }
+        return false;
+    }
+
+    /**
+     * Highlights a provenance node with secondary highlighting style
+     * @param {omdNode} node - The node to highlight with provenance style
+     * @private
+     */
+    _highlightProvenanceNode(node) {
+        if (node && typeof node.setExplainHighlight === 'function') {
+            // Use a slightly different color or style for provenance if desired
+            node.setExplainHighlight(true, omdColor.provenanceColor); 
+            this.highlightedNodes.add(node);
+        }
+    }
+}

package/omd/step-visualizer/omdStepVisualizerLayout.js

@@ -0,0 +1,245 @@
+import { omdEquationNode } from '../nodes/omdEquationNode.js';
+import { omdColor } from '../../src/omdColor.js';
+import { jsvgLine } from '@teachinglab/jsvg';
+
+/**
+ * Handles visual layout, positioning, and visibility management for step visualizations
+ */
+export class omdStepVisualizerLayout {
+    constructor(stepVisualizer) {
+        this.stepVisualizer = stepVisualizer;
+    }
+
+    /**
+     * Updates the layout of visual elements relative to the sequence
+     */
+    updateVisualLayout() {
+        if (this.stepVisualizer.stepDots.length === 0) return;
+        
+        // Position visual container to the right of the sequence
+        // Add extra offset based on equation background padding (if any)
+        const baseRight = (this.stepVisualizer.sequenceWidth || this.stepVisualizer.width);
+        // Use EFFECTIVE padding (after pill clamping) to avoid overlap when pills are wider
+        const extraPaddingX = this._getMaxEquationEffectivePaddingX();
+        const visualX = baseRight + this.stepVisualizer.visualSpacing + extraPaddingX;
+        this.stepVisualizer.visualContainer.setPosition(visualX, 0);
+        
+        // Position dots based on visible equations
+        const visibleSteps = this.stepVisualizer.steps.filter(s => s.visible !== false);
+        let currentY = 0;
+        const verticalPadding = 15 * this.stepVisualizer.getFontSize() / this.stepVisualizer.getRootFontSize();
+        
+        visibleSteps.forEach((step, visIndex) => {
+            if (step instanceof omdEquationNode) {
+                const dotIndex = this.findDotIndexForEquation(step);
+                if (dotIndex >= 0 && dotIndex < this.stepVisualizer.stepDots.length) {
+                    const dot = this.stepVisualizer.stepDots[dotIndex];
+                    
+                    // Center dot vertically with the equation
+                    let equationCenter;
+                    if (step.equalsSign && step.equalsSign.ypos !== undefined) {
+                        equationCenter = step.equalsSign.ypos + (step.equalsSign.height / 2);
+                    } else {
+                        equationCenter = step.getAlignmentBaseline ? step.getAlignmentBaseline() : step.height / 2;
+                    }
+                    const dotY = currentY + equationCenter;
+                    const dotX = (this.stepVisualizer.dotRadius * 3) / 2;
+                    
+                    dot.setPosition(dotX, dotY);
+                }
+            }
+            
+            currentY += step.height;
+            if (visIndex < visibleSteps.length - 1) {
+                currentY += verticalPadding;
+            }
+        });
+        
+        this.updateAllLinePositions();
+        
+        // Update container dimensions
+        let containerWidth = this.stepVisualizer.dotRadius * 3;
+        let containerHeight = this.stepVisualizer.height;
+        
+        const textBoxes = this.stepVisualizer.textBoxManager.getStepTextBoxes();
+        if (textBoxes.length > 0) {
+            const textBoxWidth = 280;
+            containerWidth = Math.max(containerWidth, textBoxWidth + this.stepVisualizer.dotRadius * 2 + 10 + 20);
+            
+            // Calculate the maximum extent of any text box to prevent clipping
+            textBoxes.forEach(textBox => {
+                if (textBox.interactiveSteps) {
+                    const dimensions = textBox.interactiveSteps.getDimensions();
+                    const layoutGroup = textBox.interactiveSteps.getLayoutGroup();
+                    
+                    // Calculate the bottom of this text box
+                    const textBoxBottom = layoutGroup.ypos + dimensions.height;
+                    containerHeight = Math.max(containerHeight, textBoxBottom + 20); // Add some buffer
+                }
+            });
+        }
+        
+        if (this.stepVisualizer.stepDots.length > 0) {
+            const maxRadius = Math.max(...this.stepVisualizer.stepDots.map(d=>d.radius||this.stepVisualizer.dotRadius));
+            const containerWidth = maxRadius * 3;
+            const maxDotY = Math.max(...this.stepVisualizer.stepDots.map(dot => dot.ypos + this.stepVisualizer.dotRadius));
+            containerHeight = Math.max(containerHeight, maxDotY);
+        }
+        
+        this.stepVisualizer.visualContainer.setWidthAndHeight(containerWidth, containerHeight);
+        this.updateVisualZOrder();
+    }
+
+    /**
+     * Computes the maximum horizontal padding (x) among visible equations, if configured.
+     * This allows dots to shift further right when pill background padding is added.
+     * @returns {number}
+     * @private
+     */
+    _getMaxEquationEffectivePaddingX() {
+        try {
+            const steps = this.stepVisualizer.steps || [];
+            let maxPadX = 0;
+            steps.forEach(step => {
+                if (step instanceof omdEquationNode && step.visible !== false) {
+                    if (typeof step.getEffectiveBackgroundPaddingX === 'function') {
+                        const px = Number(step.getEffectiveBackgroundPaddingX());
+                        maxPadX = Math.max(maxPadX, isNaN(px) ? 0 : px);
+                    }
+                }
+            });
+            return maxPadX;
+        } catch (_) {
+            return 0;
+        }
+    }
+
+    /**
+     * Finds the dot index for a given equation
+     */
+    findDotIndexForEquation(equation) {
+        return this.stepVisualizer.stepDots.findIndex(dot => dot.equationRef === equation);
+    }
+
+    /**
+     * Updates the z-order of visual elements
+     */
+    updateVisualZOrder() {
+        if (!this.stepVisualizer.visualContainer) return;
+
+        // Lines behind (z-index 1)
+        this.stepVisualizer.stepLines.forEach(line => {
+            if (line && line.svgObject) {
+                line.svgObject.style.zIndex = '1';
+                if (line.parentNode !== this.stepVisualizer.visualContainer) {
+                    this.stepVisualizer.visualContainer.addChild(line);
+                }
+            }
+        });
+
+        // Dots in front (z-index 2)
+        this.stepVisualizer.stepDots.forEach(dot => {
+            if (dot && dot.svgObject) {
+                dot.svgObject.style.zIndex = '2';
+                if (dot.parentNode !== this.stepVisualizer.visualContainer) {
+                    this.stepVisualizer.visualContainer.addChild(dot);
+                }
+            }
+        });
+
+        // Text boxes on top (z-index 3)
+        const textBoxes = this.stepVisualizer.textBoxManager.getStepTextBoxes();
+        textBoxes.forEach(textBox => {
+            if (textBox && textBox.svgObject) {
+                textBox.svgObject.style.zIndex = '3';
+                if (textBox.parentNode !== this.stepVisualizer.visualContainer) {
+                    this.stepVisualizer.visualContainer.addChild(textBox);
+                }
+            }
+        });
+    }
+
+    /**
+     * Updates all line positions to connect dot centers
+     */
+    updateAllLinePositions() {
+        this.stepVisualizer.stepLines.forEach(line => {
+            const fromDot = this.stepVisualizer.stepDots[line.fromDotIndex];
+            const toDot = this.stepVisualizer.stepDots[line.toDotIndex];
+            
+            if (fromDot && toDot) {
+                line.setEndpoints(fromDot.xpos, fromDot.ypos, toDot.xpos, toDot.ypos);
+            }
+        });
+    }
+
+    /**
+     * Updates visibility of visual elements based on equation visibility
+     */
+    updateVisualVisibility() {
+        const sv = this.stepVisualizer;
+
+        // Update dot visibility first, which is the source of truth
+        sv.stepDots.forEach(dot => {
+            if (dot.equationRef && dot.equationRef.visible !== false) {
+                dot.show();
+                dot.visible = true; // Use the dot's own visibility property
+            } else {
+                dot.hide();
+                dot.visible = false;
+            }
+        });
+
+        // Remove all old lines from the container and the array
+        sv.stepLines.forEach(line => {
+            // Remove the line if it is currently a child of the visualContainer
+            if (line.parent === sv.visualContainer) {
+                sv.visualContainer.removeChild(line);
+            }
+        });
+        sv.stepLines = [];
+
+        // Get the dots that are currently visible
+        const visibleDots = sv.stepDots.filter(dot => dot.visible);
+
+        // Re-create connecting lines only between the visible dots
+        for (let i = 0; i < visibleDots.length - 1; i++) {
+            const fromDot = visibleDots[i];
+            const toDot = visibleDots[i + 1];
+
+            const line = new jsvgLine();
+            line.setStrokeColor(omdColor.stepColor);
+            line.setStrokeWidth(sv.lineWidth);
+            line.fromDotIndex = sv.stepDots.indexOf(fromDot);
+            line.toDotIndex = sv.stepDots.indexOf(toDot);
+
+            sv.visualContainer.addChild(line);
+            sv.stepLines.push(line);
+        }
+
+        // After creating the lines, update their positions
+        this.updateAllLinePositions();
+    }
+
+    /**
+     * Updates the clickability of a dot
+     */
+    updateDotClickability(dot) {
+        if (this.stepVisualizer.dotsClickable) {
+            dot.svgObject.style.cursor = "pointer";
+            dot.svgObject.onclick = (event) => {
+                try {
+                    const idx = this.stepVisualizer.stepDots.indexOf(dot);
+                    if (idx < 0) return; // orphan dot, ignore
+                    this.stepVisualizer._handleDotClick(dot, idx);
+                    event.stopPropagation();
+                } catch (error) {
+                    console.error('Error in dot click handler:', error);
+                }
+            };
+        } else {
+            dot.svgObject.style.cursor = "default";
+            dot.svgObject.onclick = null;
+        }
+    }
+} 

package/omd/step-visualizer/omdStepVisualizerTextBoxes.js

@@ -0,0 +1,163 @@
+import { omdEquationNode } from '../nodes/omdEquationNode.js';
+import { omdStepVisualizerInteractiveSteps } from '../utils/omdStepVisualizerInteractiveSteps.js';
+
+/**
+ * Manages interactive step text boxes that appear when dots are clicked
+ * Handles creation, positioning, and cleanup of explanation popups
+ */
+export class omdStepVisualizerTextBoxes {
+    constructor(stepVisualizer, highlighting) {
+        this.stepVisualizer = stepVisualizer;
+        this.highlighting = highlighting;
+        this.stepTextBoxes = [];
+    }
+
+    /**
+     * Creates an interactive steps popup for a clicked dot
+     * @param {number} dotIndex - Index of the dot to create text box for
+     */
+    createTextBoxForDot(dotIndex) {
+        try {
+            this.removeTextBoxForDot(dotIndex);
+            
+            const targetDot = this._findDotAboveForPositioning(dotIndex);
+            if (!targetDot) {
+                console.error('Target dot not found for positioning text box for dot index:', dotIndex);
+                return;
+            }
+            
+            const simplificationData = this._getSimplificationDataForDot(dotIndex);
+            this._createInteractiveStepsForDot(dotIndex, targetDot, simplificationData);
+            
+        } catch (error) {
+            console.error('Error creating text box for dot', dotIndex, ':', error);
+        }
+    }
+
+    /**
+     * Creates interactive steps for a dot with simplification data
+     * @param {number} dotIndex - Index of the dot
+     * @param {Object} targetDot - The dot to position relative to
+     * @param {Object} simplificationData - Full simplification data including rule names
+     * @private
+     */
+    _createInteractiveStepsForDot(dotIndex, targetDot, simplificationData) {
+        const interactiveSteps = new omdStepVisualizerInteractiveSteps(this.stepVisualizer, simplificationData);
+        
+        // Position relative to the target dot
+        const x = targetDot.xpos + this.stepVisualizer.dotRadius * 2 + 10;
+        const y = targetDot.ypos - this.stepVisualizer.dotRadius;
+        interactiveSteps.setPosition(x, y);
+        
+        // Set up hover interactions
+        interactiveSteps.setOnStepHover((stepIndex, message, isEntering) => {
+        });
+        
+        // Set up click interactions
+        interactiveSteps.setOnStepClick((stepIndex, message) => {
+        });
+        
+        // Add to visual container and track
+        const layoutGroup = interactiveSteps.getLayoutGroup();
+        layoutGroup.dotIndex = dotIndex;
+        this.stepVisualizer.visualContainer.addChild(layoutGroup);
+        
+        this.stepTextBoxes.push({
+            dotIndex: dotIndex,
+            interactiveSteps: interactiveSteps,
+            layoutGroup: layoutGroup
+        });
+        
+        // Update layout to prevent clipping after adding text box
+        this.stepVisualizer.layoutManager.updateVisualLayout();
+    }
+
+
+
+
+
+    /**
+     * Removes the text box for a specific dot
+     * @param {number} dotIndex - Index of the dot to remove text box for
+     */
+    removeTextBoxForDot(dotIndex) {
+        const textBoxIndex = this.stepTextBoxes.findIndex(tb => tb.dotIndex === dotIndex);
+        if (textBoxIndex >= 0) {
+            const item = this.stepTextBoxes[textBoxIndex];
+            this.stepVisualizer.visualContainer.removeChild(item.layoutGroup);
+            item.interactiveSteps.destroy();
+            this.stepTextBoxes.splice(textBoxIndex, 1);
+            
+            // Update layout after removing text box to adjust container size
+            this.stepVisualizer.layoutManager.updateVisualLayout();
+        }
+    }
+
+    /**
+     * Removes all text boxes
+     */
+    clearAllTextBoxes() {
+        this.stepTextBoxes.forEach(item => {
+            this.stepVisualizer.visualContainer.removeChild(item.layoutGroup);
+            item.interactiveSteps.destroy();
+        });
+        this.stepTextBoxes = [];
+        
+        // Update layout after clearing all text boxes
+        this.stepVisualizer.layoutManager.updateVisualLayout();
+    }
+
+    /**
+     * Finds the appropriate dot above the clicked one for text box positioning
+     * @param {number} dotIndex - Index of the clicked dot
+     * @returns {Object|null} The dot to align with, or null if none found
+     * @private
+     */
+    _findDotAboveForPositioning(dotIndex) {
+        const currentDot = this.stepVisualizer.stepDots[dotIndex];
+        if (!currentDot || !currentDot.equationRef) {
+            return null;
+        }
+        
+        const currentEquation = currentDot.equationRef;
+        const currentEquationIndex = this.stepVisualizer.steps.indexOf(currentEquation);
+        
+        // Find the nearest visible equation above
+        for (let i = currentEquationIndex - 1; i >= 0; i--) {
+            const step = this.stepVisualizer.steps[i];
+            if (step instanceof omdEquationNode && step.visible !== false) {
+                // Find the corresponding dot
+                for (let dotIdx = dotIndex - 1; dotIdx >= 0; dotIdx--) {
+                    const dot = this.stepVisualizer.stepDots[dotIdx];
+                    if (dot && dot.equationRef === step) {
+                        return dot;
+                    }
+                }
+                break;
+            }
+        }
+        
+        // If no visible equation above, use the clicked dot itself
+        return currentDot;
+    }
+
+    /**
+     * Gets the simplification data for a specific dot
+     * @param {number} dotIndex - Index of the dot
+     * @returns {Object} The simplification data for this step
+     * @private
+     */
+    _getSimplificationDataForDot(dotIndex) {
+        return this.stepVisualizer._getSimplificationDataForDot(dotIndex);
+    }
+
+
+
+    /**
+     * Gets all text boxes
+     * @returns {Array} Array of text box objects
+     */
+    getStepTextBoxes() {
+        return this.stepTextBoxes;
+    }
+}