# OMD Documentation

# 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` 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`): The manager responsible for all highlighting logic.
- `textBoxManager` (`omdStepVisualizerTextBoxes`): The manager responsible for creating, positioning, and removing the explanation text boxes.
- `layoutManager` (`omdStepVisualizerLayout`): 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

    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.

↑ Top