@teachinglab/omd 0.1.3 → 0.1.5

package/docs/api/omdStepVisualizer.md

@@ -1,115 +1,147 @@
-
-# omdStepVisualizer
-
-Visualizes a sequence of mathematical steps (typically equations) and provides interactive explanations for how one step transforms into the next. Extends `omdEquationSequenceNode` by adding a visual track of dots and lines to the right of the steps, which can be clicked to reveal details about the simplification or operation applied.
-
-## Import
-
-```js
-import { omdStepVisualizer } from './omd/step-visualizer/omdStepVisualizer.js';
-```
-
-## Class Hierarchy
-
-```
-omdNode
-  └─ omdEquationSequenceNode
-       └─ omdStepVisualizer
-```
-
-See: [`omdEquationSequenceNode`](./omdEquationSequenceNode.md) for base sequence functionality.
-
-## Constructor
-
-```js
-new omdStepVisualizer(steps)
-```
-
-- `steps` (`Array<omdNode>`): An array of nodes (usually `omdEquationNode`) representing the steps in the sequence.
-
-## Key Features
-
-- **Interactive Dots:** Each step is represented by a clickable dot. Clicking a dot reveals a text box explaining the transformation from the previous step.
-- **Highlighting:** When a dot is clicked, the parts of the equations that were changed or involved in the transformation are highlighted.
-- **Automatic Layout:** The visualizer automatically handles the layout of the steps, the visual tracker, and the explanation text boxes.
-- **Simplification Analysis:** Analyzes the sequence to determine the mathematical justification for each step, whether it's a simplification rule (e.g., "Combine like terms") or a direct operation (e.g., "Add 3 to both sides").
-
-## Properties
-
-In addition to properties from `omdEquationSequenceNode`:
-
-- `activeDotIndex` (`number`): The index of the currently active (clicked) dot. `-1` if none.
-- `dotsClickable` (`boolean`): Controls whether the step dots can be clicked to show explanations. Defaults to `true`.
-- `highlighting` ([`omdStepVisualizerHighlighting`](./omdStepVisualizerHighlighting.md)): The manager responsible for all highlighting logic.
-- `textBoxManager` ([`omdStepVisualizerTextBoxes`](./omdStepVisualizerTextBoxes.md)): The manager responsible for creating, positioning, and removing the explanation text boxes.
-- `layoutManager` ([`omdStepVisualizerLayout`](./omdStepVisualizerLayout.md)): The manager responsible for layout and z-ordering of all visual elements.
-- `stepDots`, `stepLines` (`Array`): Internal arrays holding the dot and line objects for the visual tracker. Not part of the public API, but useful for advanced customization.
-- `steps` (`Array<omdNode>`): The sequence of steps (usually `omdEquationNode`). Only `omdEquationNode` steps are visualized with dots/lines; other node types are ignored for the visual tracker.
-
-## Methods
-
-This class inherits all methods from `omdEquationSequenceNode`. Overridden and new methods include:
-
-### `addStep(step, options)`
-Adds a new step to the sequence and creates its corresponding visual dot and connecting line.
-
-```js
-const newStep = omdEquationNode.fromString('x = 5');
-visualizer.addStep(newStep);
-```
-
-### `getNodeStepNumber(nodeId)`
-Gets the step number (index) associated with a given node ID.
-
-```js
-const stepIndex = visualizer.getNodeStepNumber('some-node-id');
-```
-- **Returns:** `number` (the step number, or `undefined` if the node is not found within a step)
-
-### `setDotsClickable(enabled)`
-Enables or disables the ability to click on the step dots.
-
-```js
-visualizer.setDotsClickable(false); // Explanations are now disabled
-```
-
-### `getStepTextBoxes()`
-Retrieves the array of currently visible text box components.
-- **Returns:** `Array` (the active text box instances)
-
-## Internal Helpers
-
-Contains several private methods (`_handleDotClick`, `_getSimplificationDataForDot`, etc.) that manage the internal logic of handling user interaction, analyzing the step sequence, and coordinating the display of highlights and text boxes. These are not intended for external use but are crucial to the component's functionality.
-
-## Supporting Classes
-
-Relies on three main helper classes to organize its complex logic:
-- **`omdStepVisualizerLayout`**: Manages the positioning of all visual elements, including the sequence itself, the dots, the lines, and the text boxes.
-- **`omdStepVisualizerTextBoxes`**: Handles the lifecycle of the explanation text boxes that appear when a dot is clicked.
-- **`omdStepVisualizerHighlighting`**: Manages the logic for highlighting nodes within the equations to show what has changed between steps.
-
-## Example
-
-```js
-import { omdStepVisualizer } from './omd/step-visualizer/omdStepVisualizer.js';
-import { omdEquationNode } from './omd/nodes/omdEquationNode.js';
-import { omdDisplay } from './omd/display/omdDisplay.js';
-
-// 1. Define the steps of a solution (must be omdEquationNode for dots to appear)
-const steps = [
-  omdEquationNode.fromString('2x + 4 = 10'),
-  omdEquationNode.fromString('2x = 6'),
-  omdEquationNode.fromString('x = 3')
-];
-
-// 2. Create the visualizer
-const visualizer = new omdStepVisualizer(steps);
-
-// 3. Add it to a display container
-const display = new omdDisplay(document.getElementById('container'));
-display.render(visualizer);
-
-// Now the steps will be displayed with interactive dots on the right.
-// Only omdEquationNode steps are visualized with dots/lines.
-// Clicking the dot next to "2x = 6" will explain that 4 was subtracted from both sides.
-```
+# omdStepVisualizer
+
+Visualizes a sequence of mathematical steps (typically equations) and provides interactive explanations for how one step transforms into the next. It extends `omdEquationSequenceNode` by adding a visual track of dots and lines to the right of the steps, which can be clicked to reveal details about the simplification or operation applied.
+
+## Class Hierarchy
+
+```
+omdNode
+  └─ omdEquationSequenceNode
+       └─ omdStepVisualizer
+```
+
+See: [`omdEquationSequenceNode`](./omdEquationSequenceNode.md) for base sequence functionality.
+
+## Constructor
+
+### `new omdStepVisualizer(steps)`
+
+Creates a new `omdStepVisualizer` instance.
+
+-   **`steps`** (`Array<omdNode>`): An array of nodes (usually `omdEquationNode`) representing the initial steps in the sequence.
+
+During construction, it initializes internal arrays for `stepDots` and `stepLines`, creates a `visualContainer` for these elements, and sets up managers for `highlighting`, `textBoxes`, and `layout`. It also populates `nodeToStepMap` for efficient lookup.
+
+## Public Properties
+
+-   **`stepDots`** (`Array<jsvgEllipse>`): An array of `jsvgEllipse` objects representing the clickable dots for each equation step.
+-   **`stepLines`** (`Array<jsvgLine>`): An array of `jsvgLine` objects connecting the step dots.
+-   **`visualContainer`** (`jsvgLayoutGroup`): The `jsvgLayoutGroup` that holds the `stepDots` and `stepLines`.
+-   **`dotRadius`** (`number`): The radius of the step dots, determined by `omdConfigManager`.
+-   **`lineWidth`** (`number`): The stroke width of the connecting lines.
+-   **`visualSpacing`** (`number`): The horizontal spacing between the equation sequence and the visual tracker.
+-   **`activeDotIndex`** (`number`): The 0-based index of the currently active (clicked) dot. `-1` if none.
+-   **`dotsClickable`** (`boolean`): Controls whether the step dots can be clicked to show explanations. Default: `true`.
+-   **`nodeToStepMap`** (`Map<string, number>`): A map from `omdNode` IDs to their corresponding step index in the sequence.
+-   **`stepVisualizerHighlights`** (`Set<string>`): A set of node IDs that are currently highlighted by the visualizer.
+-   **`highlighting`** ([`omdStepVisualizerHighlighting`](./omdStepVisualizerHighlighting.md)): The manager responsible for all highlighting logic.
+-   **`textBoxManager`** ([`omdStepVisualizerTextBoxes`](./omdStepVisualizerTextBoxes.md)): The manager responsible for creating, positioning, and removing the explanation text boxes.
+-   **`layoutManager`** ([`omdStepVisualizerLayout`](./omdStepVisualizerLayout.md)): The manager responsible for layout and z-ordering of all visual elements.
+
+## Public Methods
+
+### `rebuildVisualizer()`
+
+Forces a complete rebuild of the visual elements (dots and lines) from scratch. This is useful after significant changes to the underlying `steps` array.
+
+### `addStep(step, options)`
+
+Adds a new step to the sequence. This method overrides the base `omdEquationSequenceNode.addStep` to also create and manage the corresponding visual dot and connecting line for the new step.
+
+-   **`step`** (`omdNode` | `string`): The node object or expression string for the step.
+-   **`options`** (`object`): Options for the step, such as `description` and `stepMark` (importance level).
+
+### `getNodeStepNumber(nodeId)`
+
+Retrieves the step number (index) associated with a given `omdNode` ID within the sequence.
+
+-   **`nodeId`** (`string`): The ID of the node to look up.
+-   **Returns**: `number` | `undefined` - The 0-based step index, or `undefined` if the node is not found within a step.
+
+### `computeDimensions()`
+
+Calculates the overall dimensions of the visualizer, accounting for the width and height of the equation sequence and the additional space required for the visual tracker (dots and lines).
+
+-   **Overrides**: `omdEquationSequenceNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the visualizer, positioning both the equation sequence and the visual tracker elements. It delegates to the `layoutManager` for precise positioning of dots and lines.
+
+-   **Overrides**: `omdEquationSequenceNode.updateLayout()`.
+
+### `undoLastOperation()`
+
+Removes the most recent operation and its resulting equation from the sequence. This method overrides the base `omdEquationSequenceNode.undoLastOperation` to also trigger a `rebuildVisualizer()` to ensure visual elements are synchronized.
+
+-   **Returns**: `boolean` - `true` if an operation was undone, `false` otherwise.
+
+### `setDotColor(dotIndex, color)`
+
+Sets the fill and stroke color of a specific step dot.
+
+-   **`dotIndex`** (`number`): The index of the dot to color.
+-   **`color`** (`string`): The new color.
+
+### `setLineAboveColor(dotIndex, color)`
+
+Sets the stroke color of the line segment directly above a specific step dot.
+
+-   **`dotIndex`** (`number`): The index of the dot whose preceding line should be colored.
+-   **`color`** (`string`): The new color.
+
+### `setDotsClickable(enabled)`
+
+Enables or disables the ability for users to click on the step dots to reveal explanations.
+
+-   **`enabled`** (`boolean`): `true` to enable clicking, `false` to disable.
+
+### `getStepTextBoxes()`
+
+Retrieves the array of currently visible explanation text box components managed by the `textBoxManager`.
+
+-   **Returns**: `Array<omdStepVisualizerTextBox>` - The active text box instances.
+
+## Internal Methods
+
+-   **`_initializeVisualElements()`**: Creates and initializes the visual dots and lines for all existing equation steps, and populates the `nodeToStepMap`.
+-   **`_createStepDot(equation, index)`**: Creates a single `jsvgEllipse` representing a step dot, associates it with an equation, and adds it to the `visualContainer`.
+-   **`_createStepLine(fromIndex, toIndex)`**: Creates a `jsvgLine` connecting two step dots and adds it to the `visualContainer`.
+-   **`_clearVisualElements()`**: Removes all existing dots, lines, and text boxes from the display and resets internal arrays.
+-   **`_handleDotClick(dot, dotIndex)`**: Event handler for when a step dot is clicked. It manages the active dot state, triggers highlighting, and creates/removes explanation text boxes.
+-   **`setActiveDot(dotIndex)`**: Sets a specific dot as the visually active one, changing its color and triggering the display of its explanation text box.
+-   **`_clearActiveDot()`**: Clears the currently active dot, resetting its color, removing its text box, and clearing highlights.
+-   **`_getSimplificationDataForDot(dotIndex)`**: Gathers and formats the simplification and operation data relevant to a specific step dot, used to populate the explanation text box.
+-   **`_createDefaultSimplificationData(message)`**: Helper to create a default data object for step explanations.
+-   **`_findPreviousVisibleEquationIndex(currentIndex)`**: Finds the index of the last visible equation step before the given `currentIndex`.
+-   **`_getRelevantSimplifications(simplificationHistory, startIndex, endIndex)`**: Filters the full simplification history to find entries relevant to a specific range of steps.
+-   **`_createMultipleSimplificationsData(simplifications)`**: Formats data for displaying multiple simplification events in a single text box.
+-   **`_checkForOperationStep(equationIndex)`**: Checks if a step at a given index is an `omdOperationDisplayNode` and extracts its data.
+-   **`_checkForSingleSimplification(simplificationHistory, equationIndex)`**: Checks for a single simplification entry relevant to a specific step.
+-   **`_getFallbackSimplificationData(equationIndex)`**: Provides a default explanation if no specific simplification or operation data is found for a step.
+
+## Example
+
+```javascript
+import { omdStepVisualizer } from '@teachinglab/omd';
+import { omdEquationNode } from '@teachinglab/omd';
+import { omdDisplay } from '@teachinglab/omd';
+
+// 1. Define the steps of a solution (must be omdEquationNode for dots to appear)
+const steps = [
+  omdEquationNode.fromString('2x + 4 = 10'),
+  omdEquationNode.fromString('2x = 6'),
+  omdEquationNode.fromString('x = 3')
+];
+
+// 2. Create the visualizer
+const visualizer = new omdStepVisualizer(steps);
+
+// 3. Add it to a display container
+const display = new omdDisplay(document.getElementById('container'));
+display.render(visualizer);
+
+// Now the steps will be displayed with interactive dots on the right.
+// Only omdEquationNode steps are visualized with dots/lines.
+// Clicking the dot next to "2x = 6" will explain that 4 was subtracted from both sides.
+```

package/docs/api/omdStepVisualizerHighlighting.md

@@ -1,61 +1,66 @@
-
-# omdStepVisualizerHighlighting
-
-Manages the highlighting of nodes within mathematical expressions displayed by the `omdStepVisualizer`. Uses a robust tree differencing algorithm to identify changes between consecutive steps and highlights affected nodes, providing visual feedback on transformations.
-
-## Import
-
-```js
-import { omdStepVisualizerHighlighting } from './omd/step-visualizer/omdStepVisualizerHighlighting.js';
-```
-
-## Constructor
-
-```js
-new omdStepVisualizerHighlighting(stepVisualizer)
-```
-
-- `stepVisualizer` (`omdStepVisualizer`): The step visualizer instance this highlighting manager is associated with.
-
-## Properties
-
-- `stepVisualizer` (`omdStepVisualizer`): The associated step visualizer instance.
-- `highlightedNodes` (`Set<omdNode>`): Set of currently highlighted nodes.
-- `educationalMode` (`boolean`): If `true`, enables highlighting of pedagogical simplifications. Default: `true`.
-
-## Methods
-
-### `highlightAffectedNodes(dotIndex, isOperation = false)`
-Main method to trigger highlighting. Compares the equation at `dotIndex` with the previous visible equation to identify changes and applies highlighting.
-- `dotIndex` (`number`): The index of the dot (step) for which to highlight affected nodes.
-- `isOperation` (`boolean`): If `true`, indicates the step is an operation (e.g., adding to both sides), which affects how provenance is highlighted.
-
-### `clearHighlights()`
-Removes all active highlights from the expression tree.
-
-### Private/Internal Methods
-
-- `_highlightNode(node)`: Applies the standard explanation highlight color to a single node.
-- `_findNearestVisibleEquationAbove(currentIndex)`: Finds the closest visible `omdEquationNode` preceding the given index.
-- `_highlightProvenanceNodes(changedNodes, previousEquation)`: Highlights nodes in the previous equation that are linked by provenance to the `changedNodes` in the current equation.
-- `_belongsToEquation(node, targetEquation)`: Checks if a given node is part of a specific equation's subtree.
-- `_highlightProvenanceNode(node)`: Applies a secondary highlighting style to nodes identified through provenance.
-
-## How it Works
-
-1. **Tree Differencing:** When `highlightAffectedNodes` is called, it uses `omdTreeDiff.findChangedNodes` to compare the current equation and the previous visible equation in the sequence.
-2. **Change Identification:** `omdTreeDiff` identifies nodes that have been added, removed, or modified between the two steps.
-3. **Direct Highlighting:** Nodes identified as directly changed are highlighted with a primary color.
-4. **Provenance Highlighting:** For non-operation steps, the system traces the `provenance` (history) of the changed nodes back to their origins in the previous equation. These originating nodes are then highlighted with a secondary color, visually connecting the transformation.
-
-## Example
-
-This class is typically used internally by `omdStepVisualizer` when a step dot is clicked:
-
-```js
-// Inside omdStepVisualizer's _handleDotClick method:
-this.highlighting.highlightAffectedNodes(dotIndex, isOperation);
-
-// Inside omdStepVisualizer's _clearActiveDot method:
-this.highlighting.clearHighlights();
-```
+# omdStepVisualizerHighlighting
+
+Manages the highlighting of nodes within mathematical expressions displayed by the `omdStepVisualizer`. It uses a robust tree differencing algorithm to identify changes between consecutive steps and highlights affected nodes, providing visual feedback on transformations.
+
+## Class Definition
+
+```javascript
+export class omdStepVisualizerHighlighting
+```
+
+## Constructor
+
+### `new omdStepVisualizerHighlighting(stepVisualizer)`
+
+Creates a new `omdStepVisualizerHighlighting` instance.
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): The step visualizer instance this highlighting manager is associated with.
+
+During construction, it initializes a `Set` to track `highlightedNodes` and sets `educationalMode` to `true` by default.
+
+## Public Properties
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): The associated step visualizer instance.
+-   **`highlightedNodes`** (`Set<omdNode>`): A set of `omdNode` instances that are currently highlighted by this manager.
+-   **`educationalMode`** (`boolean`): If `true`, enables highlighting of pedagogical simplifications (e.g., intermediate steps that might be skipped in a final solution). Default: `true`.
+
+## Public Methods
+
+### `highlightAffectedNodes(dotIndex, isOperation = false)`
+
+This is the main method to trigger highlighting. It compares the equation at `dotIndex` with the previous visible equation in the sequence to identify changes and then applies appropriate highlighting.
+
+-   **`dotIndex`** (`number`): The index of the dot (step) for which to highlight affected nodes.
+-   **`isOperation`** (`boolean`, optional): If `true`, indicates that the step is an operation (e.g., adding to both sides), which affects how provenance is highlighted. Default: `false`.
+
+**How it Works:**
+
+1.  **Clear Existing Highlights**: First, any previously active highlights are cleared.
+2.  **Identify Equations**: It determines the `currentEquation` (associated with `dotIndex`) and finds the `previousEquation` (the nearest visible equation before the current one).
+3.  **Tree Differencing**: It uses `omdTreeDiff.findChangedNodes` to perform a robust comparison between the `previousEquation` and `currentEquation`. This algorithm identifies nodes that have been added, removed, or modified.
+4.  **Direct Highlighting**: Nodes identified as directly changed by the diff algorithm are highlighted with a primary explanation color (`omdColor.explainColor`).
+5.  **Provenance Highlighting**: For non-operation steps, the system traces the `provenance` (history) of the directly changed nodes back to their origins in the `previousEquation`. These originating nodes are then highlighted with a secondary provenance color (`omdColor.provenanceColor`), visually connecting the transformation.
+
+### `clearHighlights()`
+
+Removes all active highlights managed by this class from the expression tree. It iterates through all `highlightedNodes` and calls `setExplainHighlight(false)` on them, then clears its internal `highlightedNodes` set.
+
+## Internal Methods
+
+-   **`_highlightNode(node)`**: Applies the standard explanation highlight color (`omdColor.explainColor`) to a single `omdNode` by calling its `setExplainHighlight(true)` method and adds the node to `highlightedNodes`.
+-   **`_findNearestVisibleEquationAbove(currentIndex)`**: Searches backward from `currentIndex` in the `stepVisualizer.steps` array to find the closest `omdEquationNode` that is currently visible.
+-   **`_highlightProvenanceNodes(changedNodes, previousEquation)`**: Iterates through `changedNodes` and their `provenance` chains to identify and highlight corresponding nodes in the `previousEquation` with `omdColor.provenanceColor`. It uses `rootNode.nodeMap` for efficient node lookup and a `visited` set to prevent redundant processing.
+-   **`_belongsToEquation(node, targetEquation)`**: Checks if a given `omdNode` is part of the subtree of a `targetEquation` by traversing up its parent chain.
+-   **`_highlightProvenanceNode(node)`**: Applies the secondary provenance highlighting style (`omdColor.provenanceColor`) to a single `omdNode` by calling its `setExplainHighlight(true, omdColor.provenanceColor)` method.
+
+## Example
+
+This class is typically used internally by `omdStepVisualizer` when a step dot is clicked:
+
+```javascript
+// Inside omdStepVisualizer's _handleDotClick method:
+this.highlighting.highlightAffectedNodes(dotIndex, isOperation);
+
+// Inside omdStepVisualizer's _clearActiveDot method:
+this.highlighting.clearHighlights();
+```