@teachinglab/omd 0.1.0

package/docs/api/omdStepVisualizer.md

@@ -0,0 +1,115 @@
+
+# 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.
+```

package/docs/api/omdStepVisualizerHighlighting.md

@@ -0,0 +1,61 @@
+
+# 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();
+```

package/docs/api/omdStepVisualizerInteractiveSteps.md

@@ -0,0 +1,129 @@
+# omdStepVisualizerInteractiveSteps
+
+This class creates and manages the interactive text boxes that display detailed explanations for simplification steps within the `omdStepVisualizer`. It formats the messages, handles styling, and sets up hover and click interactions.
+
+## Class: `omdStepVisualizerInteractiveSteps`
+
+```javascript
+import { omdStepVisualizerInteractiveSteps } from './omd/utils/omdStepVisualizerInteractiveSteps.js';
+```
+
+### Constructor
+
+```javascript
+new omdStepVisualizerInteractiveSteps(stepVisualizer, simplificationData)
+```
+
+**Parameters:**
+- `stepVisualizer` {omdStepVisualizer} - A reference to the `omdStepVisualizer` instance.
+- `simplificationData` {Object} - An object containing the simplification details for the step, typically including `message`, `rawMessages`, and `ruleNames`.
+
+### Properties
+
+#### `stepVisualizer`
+- **Type:** `omdStepVisualizer`
+- **Description:** A reference to the associated `omdStepVisualizer` instance.
+
+#### `simplificationData`
+- **Type:** `Object`
+- **Description:** The raw data describing the simplification step.
+
+#### `messages`
+- **Type:** `Array<string>`
+- **Description:** Cleaned and extracted messages for each sub-step.
+
+#### `ruleNames`
+- **Type:** `Array<string>`
+- **Description:** Extracted names of the simplification rules applied.
+
+#### `stepElements`
+- **Type:** `Array<jsvgTextBox>`
+- **Description:** An array of `jsvgTextBox` instances, each representing a line of explanation.
+
+#### `layoutGroup`
+- **Type:** `jsvgLayoutGroup`
+- **Description:** The main `jsvgLayoutGroup` that contains all the visual elements of the interactive steps, including the background and individual step messages.
+
+### Methods
+
+#### `setOnStepHover(callback)`
+
+Sets a callback function to be executed when the user hovers over a step explanation.
+
+- **Parameters:**
+  - `callback` {Function} - A function that receives `(stepIndex, message, isEntering)` as arguments.
+
+---
+
+#### `setOnStepClick(callback)`
+
+Sets a callback function to be executed when the user clicks on a step explanation.
+
+- **Parameters:**
+  - `callback` {Function} - A function that receives `(stepIndex, message)` as arguments.
+
+---
+
+#### `getLayoutGroup()`
+
+Returns the main `jsvgLayoutGroup` containing all the interactive step elements. This group should be added to the parent container (e.g., `omdStepVisualizer`'s `visualContainer`).
+
+- **Returns:** `jsvgLayoutGroup`
+
+---
+
+#### `setPosition(x, y)`
+
+Sets the position of the entire interactive step group.
+
+- **Parameters:**
+  - `x` {number} - The X-coordinate.
+  - `y` {number} - The Y-coordinate.
+
+---
+
+#### `getDimensions()`
+
+Returns the calculated width and height of the interactive step group.
+
+- **Returns:** {Object} An object with `width` and `height` properties.
+
+---
+
+#### `destroy()`
+
+Cleans up the component by removing all its children and clearing references.
+
+### Private Methods
+
+- `_extractMessages(data)`: Extracts and cleans messages from the `simplificationData`.
+- `_extractRuleNames(data)`: Extracts rule names from the `simplificationData`.
+- `setupLayoutGroup()`: Initializes the main `layoutGroup` and its background rectangle.
+- `createStepElements()`: Creates individual `jsvgTextBox` elements for each message.
+- `createSingleStepElement(message, index)`: Creates elements for a single step explanation.
+- `createMultipleStepElements()`: Creates elements for multiple step explanations, including a header.
+- `createHeaderBox(headerText)`: Creates a styled header `jsvgTextBox`.
+- `createStepTextBox(message, index, isMultiple)`: Creates an individual styled `jsvgTextBox` for a step message.
+- `formatStepContent(message, index, isMultiple)`: Formats the message content with styling and optional step numbers.
+- `applyStepStyling(stepBox, content, isMultiple)`: Applies CSS styling to the `jsvgTextBox`'s underlying DOM element.
+- `setupStepInteractions(stepBox)`: Sets up `mouseenter`, `mouseleave`, and `click` event listeners for a step box.
+- `calculateStepHeight(message)`: Dynamically calculates the required height for a step box based on its content.
+- `updateBackgroundSize()`: Adjusts the size of the background rectangle to fit the content.
+- `isOperationMessage(message)`: Checks if a message describes an operation (e.g., "Added X to both sides").
+- `extractOperationAction(message)`: Extracts the action (e.g., "Added") from an operation message.
+- `extractOperationValue(message)`: Extracts the value (e.g., "3") from an operation message.
+- `extractOperationValueNode(message)`: Attempts to extract the `omdNode` representing the value from an operation message.
+
+### How it Works
+
+This class takes simplification data and renders it as a series of interactive text boxes. Each box represents a sub-step or a part of the explanation. It dynamically calculates sizes and positions to ensure the text boxes are readable and visually appealing. Hover and click events on these boxes can be used to trigger further actions, such as highlighting specific nodes in the main equation display.
+
+### Example
+
+This class is typically used internally by `omdStepVisualizerTextBoxes`.
+
+```javascript
+// Example of internal usage within omdStepVisualizerTextBoxes:
+// const interactiveSteps = new omdStepVisualizerInteractiveSteps(this.stepVisualizer, simplificationData);
+// this.stepVisualizer.visualContainer.addChild(interactiveSteps.getLayoutGroup());
+```

package/docs/api/omdStepVisualizerLayout.md

@@ -0,0 +1,60 @@
+
+# omdStepVisualizerLayout
+
+Manages the visual layout, positioning, and visibility of elements within the `omdStepVisualizer`. Ensures that step dots, connecting lines, and associated text boxes are correctly positioned relative to the mathematical equations.
+
+## Import
+
+```js
+import { omdStepVisualizerLayout } from './omd/step-visualizer/omdStepVisualizerLayout.js';
+```
+
+## Constructor
+
+```js
+new omdStepVisualizerLayout(stepVisualizer)
+```
+
+- `stepVisualizer` (`omdStepVisualizer`): Reference to the step visualizer instance this layout manager will control.
+
+## Properties
+
+- `stepVisualizer` (`omdStepVisualizer`): The associated step visualizer instance.
+
+## Methods
+
+### `updateVisualLayout()`
+Calculates and applies the positions of all visual elements (dots, lines, text boxes) relative to the mathematical equations in the sequence. Ensures proper alignment and spacing.
+
+### `findDotIndexForEquation(equation)`
+Finds the index of the step dot associated with a given `omdEquationNode`.
+- `equation` (`omdEquationNode`): The equation node to find the corresponding dot for.
+- **Returns:** `number` (index of the dot, or `-1` if not found)
+
+### `updateVisualZOrder()`
+Manages the z-order (stacking order) of the visual elements to ensure they are rendered correctly (e.g., lines behind dots, text boxes on top).
+
+### `updateAllLinePositions()`
+Recalculates and updates the start and end points of all connecting lines between the step dots.
+
+### `updateVisualVisibility()`
+Adjusts the visibility of the step dots and lines based on the visibility of their corresponding equations. Re-creates lines only between currently visible dots.
+
+### `updateDotClickability(dot)`
+Enables or disables the click functionality for a specific step dot, changing its cursor style accordingly.
+- `dot` (`jsvgEllipse`): The `jsvgEllipse` element representing the dot.
+
+## How it Works
+
+This class works in conjunction with `omdStepVisualizer` to dynamically arrange the visual components. When the sequence of equations changes (e.g., steps are added or hidden), `omdStepVisualizer` calls methods on this layout manager to re-calculate and apply the new visual arrangement.
+
+## Example
+
+This class is primarily used internally by `omdStepVisualizer`:
+
+```js
+// Inside omdStepVisualizer's updateLayout method:
+this.layoutManager.updateVisualLayout();
+this.layoutManager.updateVisualVisibility();
+this.layoutManager.updateAllLinePositions();
+```

package/docs/api/omdStepVisualizerNodeUtils.md

@@ -0,0 +1,140 @@
+# omdStepVisualizerNodeUtils
+
+This module provides a collection of utility functions specifically designed to assist with node operations and analysis within the context of step visualizations, particularly for identifying and extracting information from `omdNode` instances.
+
+## Class: `omdStepVisualizerNodeUtils`
+
+This class is not meant to be instantiated. All its methods are static.
+
+### Static Methods
+
+#### `isLeafNode(node)`
+
+Checks if a given `omdNode` is a leaf node (e.g., `omdConstantNode`, `omdVariableNode`, `omdOperatorNode`).
+
+- **Parameters:**
+  - `node` {omdNode} - The node to check.
+- **Returns:** {boolean} `true` if the node is a leaf node, `false` otherwise.
+
+---
+
+#### `isBinaryNode(node)`
+
+Checks if a given `omdNode` is an `omdBinaryExpressionNode` and has both `left` and `right` children.
+
+- **Parameters:**
+  - `node` {omdNode} - The node to check.
+- **Returns:** {boolean} `true` if it's a binary node, `false` otherwise.
+
+---
+
+#### `isUnaryNode(node)`
+
+Checks if a given `omdNode` is an `omdUnaryExpressionNode` and has an `argument` child.
+
+- **Parameters:**
+  - `node` {omdNode} - The node to check.
+- **Returns:** {boolean} `true` if it's a unary node, `false` otherwise.
+
+---
+
+#### `hasExpression(node)`
+
+Checks if a given `omdNode` has an `expression` property (common in nodes like `omdParenthesisNode`).
+
+- **Parameters:**
+  - `node` {omdNode} - The node to check.
+- **Returns:** {boolean} `true` if it has an expression property, `false` otherwise.
+
+---
+
+#### `getNodeValue(node)`
+
+Attempts to retrieve a string representation of the node's value. This is particularly useful for leaf nodes (constants, variables) but can also provide a string for more complex nodes.
+
+- **Parameters:**
+  - `node` {omdNode} - The node to get the value from.
+- **Returns:** {string} The string representation of the node's value.
+
+---
+
+#### `findLeafNodes(node)`
+
+Recursively finds all leaf nodes within the subtree rooted at the given node.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+- **Returns:** {Array<omdNode>} An array of `omdNode` instances that are leaf nodes.
+
+---
+
+#### `findVariableNodes(node)`
+
+Finds all `omdVariableNode` instances within the subtree rooted at the given node.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+- **Returns:** {Array<omdVariableNode>} An array of `omdVariableNode` instances.
+
+---
+
+#### `findConstantNodes(node)`
+
+Finds all `omdConstantNode` instances within the subtree rooted at the given node.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+- **Returns:** {Array<omdConstantNode>} An array of `omdConstantNode` instances.
+
+---
+
+#### `findLeafNodesWithValue(node, value)`
+
+Finds leaf nodes within a subtree that match a specific string `value`. It performs exact matches first, then numeric matches for constants, and finally partial string matches.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+  - `value` {string} - The value to search for.
+- **Returns:** {Array<omdNode>} An array of matching leaf nodes.
+
+---
+
+#### `findAllNodes(node)`
+
+Recursively finds all `omdNode` instances (including non-leaf nodes) within the subtree rooted at the given node.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+- **Returns:** {Array<omdNode>} An array of all `omdNode` instances in the tree.
+
+---
+
+#### `findRightmostNodeWithValue(node, value)`
+
+Finds the rightmost leaf node within a subtree that matches a specific `value`. It has special handling for nodes that are the right operand of a subtraction.
+
+- **Parameters:**
+  - `node` {omdNode} - The root node to start the search from.
+  - `value` {string} - The value to search for.
+- **Returns:** {omdNode | null} The rightmost matching leaf node, or `null` if not found.
+
+### Example
+
+```javascript
+import { omdStepVisualizerNodeUtils } from './omd/utils/omdStepVisualizerNodeUtils.js';
+import { omdEquationNode } from './omd/nodes/omdEquationNode.js';
+
+const equation = omdEquationNode.fromString('2x + 3 = 7');
+
+// Find all leaf nodes
+const leafNodes = omdStepVisualizerNodeUtils.findLeafNodes(equation);
+console.log(leafNodes.map(node => node.toString())); // Output: ['2', 'x', '3', '7']
+
+// Find all constant nodes
+const constantNodes = omdStepVisualizerNodeUtils.findConstantNodes(equation);
+console.log(constantNodes.map(node => node.getValue())); // Output: [2, 3, 7]
+
+// Get the value of a specific node
+const firstLeaf = leafNodes[0];
+console.log(omdStepVisualizerNodeUtils.getNodeValue(firstLeaf)); // Output: '2'
+```

package/docs/api/omdStepVisualizerTextBoxes.md

@@ -0,0 +1,68 @@
+
+# omdStepVisualizerTextBoxes
+
+Manages the interactive text boxes that appear when a step dot is clicked in the `omdStepVisualizer`. Handles creation, positioning, and removal of these popups, and integrates with highlighting and layout managers for a cohesive user experience.
+
+## Import
+
+```js
+import { omdStepVisualizerTextBoxes } from './omd/step-visualizer/omdStepVisualizerTextBoxes.js';
+```
+
+## Constructor
+
+```js
+new omdStepVisualizerTextBoxes(stepVisualizer, highlighting)
+```
+
+- `stepVisualizer` (`omdStepVisualizer`): Reference to the step visualizer instance.
+- `highlighting` (`omdStepVisualizerHighlighting`): Reference to the highlighting manager.
+
+## Properties
+
+- `stepVisualizer` (`omdStepVisualizer`): The associated step visualizer instance.
+- `highlighting` (`omdStepVisualizerHighlighting`): The associated highlighting instance.
+- `stepTextBoxes` (`Array<Object>`): Array of active text box objects, each with `dotIndex`, `interactiveSteps`, and `layoutGroup`.
+
+## Methods
+
+### `createTextBoxForDot(dotIndex)`
+Creates and displays an interactive text box for the specified step dot. Retrieves simplification data and positions the text box appropriately.
+- `dotIndex` (`number`): The index of the dot for which to create the text box.
+
+### `removeTextBoxForDot(dotIndex)`
+Removes the text box associated with the specified step dot.
+- `dotIndex` (`number`): The index of the dot whose text box should be removed.
+
+### `clearAllTextBoxes()`
+Removes all active text boxes from the visualizer.
+
+### `getStepTextBoxes()`
+Returns an array of all currently active text box objects.
+- **Returns:** `Array<Object>`
+
+### Private/Internal Methods
+
+- `_createInteractiveStepsForDot(dotIndex, targetDot, simplificationData)`: Creates and configures the `omdStepVisualizerInteractiveSteps` instance for a dot.
+- `_findDotAboveForPositioning(dotIndex)`: Determines the appropriate dot to position the text box relative to, ensuring correct placement even if some steps are hidden.
+- `_getSimplificationDataForDot(dotIndex)`: Retrieves simplification data for a given dot from the step visualizer.
+
+## How it Works
+
+When a user clicks a step dot in the `omdStepVisualizer`, this class:
+1. **Fetches Data:** Requests simplification data from the step visualizer for the clicked step.
+2. **Creates UI:** Instantiates an `omdStepVisualizerInteractiveSteps` component, which renders the explanation text and interactive elements.
+3. **Positions:** Calculates the optimal position for the text box, usually to the right of the step dot, and ensures it doesn't overlap with other elements.
+4. **Highlighting Integration:** Works with `omdStepVisualizerHighlighting` to trigger visual feedback when the text box is displayed or interacted with.
+
+## Example
+
+This class is primarily used internally by `omdStepVisualizer`:
+
+```js
+// Inside omdStepVisualizer's _handleDotClick method:
+this.textBoxManager.createTextBoxForDot(dotIndex);
+
+// Inside omdStepVisualizer's _clearActiveDot method:
+this.textBoxManager.removeTextBoxForDot(this.activeDotIndex);
+```

package/docs/api/omdToolbar.md

@@ -0,0 +1,102 @@
+
+# omdToolbar
+
+Provides a visual toolbar UI for applying mathematical operations and functions to an `omdEquationSequenceNode` in the OMD system. The toolbar is rendered as an SVG group and supports operations like add, subtract, multiply, divide, and function application (e.g., sqrt, cos, etc.).
+
+## Import
+
+```js
+import { omdToolbar } from './omd/omdToolbar.js';
+```
+
+## Constructor
+
+```js
+new omdToolbar(parentContainer, sequence, options)
+```
+
+- `parentContainer` (`jsvgGroup`): The parent SVG group where the toolbar will be rendered.
+- `sequence` (`omdEquationSequenceNode`): The sequence node to which operations will be applied.
+- `options` (`object`, optional): Toolbar configuration options:
+  - `height` (`number`): Toolbar height. Default: `60`.
+  - `padding` (`number`): Padding around elements. Default: `6`.
+  - `spacing` (`number`): Spacing between elements. Default: `8`.
+  - `borderRadius` (`number`): Corner radius for background. Default: `30`.
+  - `fontFamily` (`string`): Font family. Default: `'Albert Sans', sans-serif`.
+  - `fontWeight` (`string`): Font weight. Default: `'500'`.
+  - `colors` (`object`): Color scheme:
+    - `background` (`string`): Toolbar background. Default: `omdColor.mediumGray`.
+    - `button` (`string`): Button background. Default: `'white'`.
+    - `popup` (`string`): Popup menu background. Default: `omdColor.lightGray`.
+  - `buttonSize` (`number`): Button size. Default: `48`.
+  - `checkMarkSize` (`number`): Checkmark SVG size. Default: `24`.
+  - `mainFontSize` (`number`): Main button font size. Default: `32`.
+  - `inputFontSize` (`number`): Input text font size. Default: `28`.
+  - `menuFontSize` (`number`): Menu item font size. Default: `24`.
+  - `inputWidth` (`number`): Input button width. Default: `120`.
+  - `x`, `y` (`number`): Optional position of the toolbar in the parent container.
+
+## Properties
+
+- `parentContainer` (`jsvgGroup`): The SVG group where the toolbar is rendered.
+- `sequence` (`omdEquationSequenceNode`): The sequence node the toolbar interacts with.
+- `config` (`object`): Merged configuration options.
+- `state` (`object`): Internal state, including `activePopup`, `selectedOperation`, and `inputValue`.
+- `elements` (`object`): References to the various `jsvg` elements in the toolbar UI.
+
+## Methods
+
+### `setInputText(text)`
+Sets the text displayed in the middle input button.
+- `text` (`string`): The text to display.
+
+### Private/Internal Methods
+
+- `_render()`: Renders the toolbar UI components.
+- `_togglePopup(popupType)`: Toggles a popup menu (operations or input).
+- `_renderPopup(contentFactory, anchorButton)`: Creates and positions a popup group.
+- `_renderOperationsMenu()`: Renders the operations menu popup (`f`, `÷`, `×`, `–`, `+`).
+- `_renderFunctionMenu()`: Renders the function selection menu popup (`sqrt`, `cos`, etc.).
+- `_renderDigitGrid()`: Renders the digit grid (number pad) popup.
+- `_handleFunctionClick(func)`: Handles function menu button clicks.
+- `_handleDigitClick(digit)`: Handles digit grid button clicks.
+- `_selectOperation(operation)`: Handles operation selection from the menu.
+- `_applyOperation()`: Applies the selected operation and value to the sequence.
+- `_createButton(config)`: Creates a button component.
+- `_updateApplyButtonState()`: Updates the enabled/disabled state of the apply button.
+- `_updateToolbarLayout()`: Updates the positions of toolbar elements.
+
+## Example
+
+```js
+import { omdToolbar } from './omd/omdToolbar.js';
+import { omdEquationSequenceNode } from './omd/nodes/omdEquationSequenceNode.js';
+import { omdEquationNode } from './omd/nodes/omdEquationNode.js';
+
+// Create an SVG container (e.g., from jsvgContainer)
+const svgContainer = new jsvgContainer();
+document.body.appendChild(svgContainer.svgObject);
+
+// Create an initial sequence
+const initialEquation = omdEquationNode.fromString('2x + 5 = 15');
+const sequence = new omdEquationSequenceNode([initialEquation]);
+
+// Create the toolbar and add it to the SVG container
+const toolbar = new omdToolbar(svgContainer, sequence, {
+  x: 50, // Position the toolbar
+  y: 50
+});
+
+// Interact with the toolbar to apply operations to the sequence.
+// For example, click the '-' button and enter '5' to subtract 5 from both sides.
+```
+
+## Notes
+
+- The toolbar can be styled via CSS for custom appearance.
+- Supports dynamic updates (e.g., adding/removing tools or buttons at runtime).
+
+## See Also
+
+- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
+- [`omdEquationNode`](./omdEquationNode.md)