@teachinglab/omd 0.5.7 → 0.5.8

package/npm-docs/api/omdStepVisualizerHighlighting.md

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

package/npm-docs/api/omdStepVisualizerInteractiveSteps.md

@@ -0,0 +1,109 @@
+# 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, allowing users to explore the mathematical transformations.
+
+## Class Definition
+
+```javascript
+export class omdStepVisualizerInteractiveSteps
+```
+
+## Constructor
+
+### `new omdStepVisualizerInteractiveSteps(stepVisualizer, simplificationData)`
+
+Creates a new `omdStepVisualizerInteractiveSteps` instance.
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): A reference to the `omdStepVisualizer` instance this component is associated with.
+-   **`simplificationData`** (`object`): An object containing the simplification details for the step, typically including `message`, `rawMessages`, `ruleNames`, and potentially `operationValueNode`.
+
+During construction, it extracts and cleans messages and rule names from the `simplificationData`, initializes layout properties (like `stepWidth`, `fontSize`), sets up the main `layoutGroup`, and creates the individual step elements.
+
+## Public Properties
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): A reference to the associated `omdStepVisualizer` instance.
+-   **`simplificationData`** (`object`): The raw data describing the simplification step.
+-   **`messages`** (`Array<string>`): Cleaned and extracted messages for each sub-step.
+-   **`ruleNames`** (`Array<string>`): Extracted names of the simplification rules applied.
+-   **`stepElements`** (`Array<jsvgTextBox>`): An array of `jsvgTextBox` instances, each representing a line of explanation.
+-   **`layoutGroup`** (`jsvgLayoutGroup`): The main `jsvgLayoutGroup` that contains all the visual elements of the interactive steps, including the background and individual step messages.
+-   **`stepWidth`** (`number`): The fixed width for each step explanation box.
+-   **`baseStepHeight`** (`number`): The minimum height for a single step explanation box.
+-   **`headerHeight`** (`number`): The height reserved for the header text box.
+-   **`fontSize`** (`number`): The base font size for the explanation text.
+-   **`smallFontSize`** (`number`): A smaller font size used for secondary text (e.g., step numbers).
+-   **`backgroundRect`** (`jsvgRect`): The background rectangle for the entire group of interactive steps.
+-   **`contentGroup`** (`jsvgLayoutGroup`): An internal layout group that holds the header and individual step messages.
+-   **`onStepHover`** (`Function`): Callback function for hover events on step explanations.
+-   **`onStepClick`** (`Function`): Callback function for click events on step explanations.
+
+## Public Methods
+
+### `setOnStepHover(callback)`
+
+Sets a callback function to be executed when the user hovers over a step explanation.
+
+-   **`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.
+
+-   **`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 within its parent container.
+
+-   **`x`** (`number`): The X-coordinate.
+-   **`y`** (`number`): The Y-coordinate.
+
+### `getDimensions()`
+
+Returns the calculated width and height of the interactive step group, including its background.
+
+-   **Returns**: `object` - An object with `width` and `height` properties.
+
+### `destroy()`
+
+Cleans up the component by removing all its children, clearing references, and unsetting callbacks.
+
+## Internal Methods
+
+-   **`_extractMessages(data)`**: Extracts and cleans messages from the `simplificationData`, removing HTML tags and bullet points.
+-   **`_extractRuleNames(data)`**: Extracts rule names from the `simplificationData`, providing default values if not present.
+-   **`setupLayoutGroup()`**: Initializes the main `layoutGroup` and creates its `backgroundRect`, setting initial styling.
+-   **`createStepElements()`**: Orchestrates the creation of individual step explanation elements. It decides whether to create a single step element or multiple, based on the number of messages.
+-   **`createSingleStepElement(message, index)`**: Creates a header and a single `jsvgTextBox` for a step explanation when there's only one message.
+-   **`createMultipleStepElements()`**: Creates a header and multiple `jsvgTextBox` elements for step explanations when there are multiple messages, optionally including step numbers.
+-   **`createHeaderBox(headerText)`**: Creates a styled `jsvgTextBox` to serve as a header for the explanation group.
+-   **`createStepTextBox(message, index, isMultiple)`**: Creates an individual styled `jsvgTextBox` for a step message, calculates its height, and stores relevant step data.
+-   **`formatStepContent(message, index, isMultiple)`**: Formats the raw message content into HTML, adding styling for step numbers, bullets, and highlighting operation details (action, value).
+-   **`applyStepStyling(stepBox, content, isMultiple)`**: Applies CSS styling to the `jsvgTextBox`'s underlying DOM element and sets its `innerHTML` with the formatted content.
+-   **`setupStepInteractions(stepBox)`**: Sets up `mouseenter`, `mouseleave`, and `click` event listeners for a step box, triggering hover and click callbacks.
+-   **`calculateStepHeight(message)`**: Dynamically calculates the required height for a step box based on its content, using a temporary DOM element for accurate measurement.
+-   **`updateBackgroundSize()`**: Adjusts the size of the `backgroundRect` to fit the dynamically calculated content height and width.
+-   **`isOperationMessage(message)`**: Checks if a message string indicates an operation (e.g., "Added X to both sides").
+-   **`extractOperationAction(message)`**: Extracts the action verb (e.g., "Added", "Subtracted") from an operation message.
+-   **`extractOperationValue(message)`**: Extracts the value (e.g., "3", "x") from an operation message.
+-   **`extractOperationValueNode(message)`**: Attempts to extract the `omdNode` representing the value from an operation message, if available in the `simplificationData`.
+
+## 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/npm-docs/api/omdStepVisualizerLayout.md

@@ -0,0 +1,71 @@
+# omdStepVisualizerLayout
+
+Manages the visual layout, positioning, and visibility of elements within the `omdStepVisualizer`. It ensures that step dots, connecting lines, and associated text boxes are correctly positioned relative to the mathematical equations, maintaining a clean and interactive display.
+
+## Class Definition
+
+```javascript
+export class omdStepVisualizerLayout
+```
+
+## Constructor
+
+### `new omdStepVisualizerLayout(stepVisualizer)`
+
+Creates a new `omdStepVisualizerLayout` instance.
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): A reference to the `omdStepVisualizer` instance this layout manager will control.
+
+## Public Properties
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): The associated `omdStepVisualizer` instance.
+
+## Public Methods
+
+### `updateVisualLayout()`
+
+Calculates and applies the positions of all visual elements (dots, lines, text boxes) relative to the mathematical equations in the sequence. It ensures proper alignment and spacing, accounting for factors like equation background padding and the dynamic size of text boxes.
+
+### `findDotIndexForEquation(equation)`
+
+Finds the index of the step dot associated with a given `omdEquationNode` within the `stepVisualizer.stepDots` array.
+
+-   **`equation`** (`omdEquationNode`): The equation node to find the corresponding dot for.
+-   **Returns**: `number` - The 0-based 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. Lines are placed behind dots, and text boxes are placed on top of everything else.
+
+### `updateAllLinePositions()`
+
+Recalculates and updates the start and end points of all connecting lines between the step dots. This ensures lines accurately connect the centers of the dots, even after layout changes.
+
+### `updateVisualVisibility()`
+
+Adjusts the visibility of the step dots and lines based on the visibility of their corresponding equations. It also dynamically re-creates line segments only between currently visible dots, ensuring no lines are drawn to hidden steps.
+
+### `updateDotClickability(dot)`
+
+Enables or disables the click functionality for a specific step dot. It sets the cursor style to `"pointer"` when clickable and `"default"` otherwise, and attaches/detaches the `onclick` event handler.
+
+-   **`dot`** (`jsvgEllipse`): The `jsvgEllipse` element representing the dot.
+
+## Internal Methods
+
+-   **`_getMaxEquationEffectivePaddingX()`**: Computes the maximum effective horizontal padding (x) among all visible `omdEquationNode` steps. This value is used to offset the visual tracker, preventing overlap with equation backgrounds.
+
+## 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`:
+
+```javascript
+// Inside omdStepVisualizer's updateLayout method:
+this.layoutManager.updateVisualLayout();
+this.layoutManager.updateVisualVisibility();
+this.layoutManager.updateAllLinePositions();
+```

package/npm-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/npm-docs/api/omdStepVisualizerTextBoxes.md

@@ -0,0 +1,77 @@
+# omdStepVisualizerTextBoxes
+
+Manages the interactive text boxes that appear when a step dot is clicked in the `omdStepVisualizer`. This class handles the creation, positioning, and removal of these explanation popups, and integrates with highlighting and layout managers for a cohesive user experience.
+
+## Class Definition
+
+```javascript
+export class omdStepVisualizerTextBoxes
+```
+
+## Constructor
+
+### `new omdStepVisualizerTextBoxes(stepVisualizer, highlighting)`
+
+Creates a new `omdStepVisualizerTextBoxes` instance.
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): A reference to the `omdStepVisualizer` instance.
+-   **`highlighting`** (`omdStepVisualizerHighlighting`): A reference to the highlighting manager.
+
+During construction, it initializes the `stepTextBoxes` array, which will store references to active text boxes.
+
+## Public Properties
+
+-   **`stepVisualizer`** (`omdStepVisualizer`): The associated step visualizer instance.
+-   **`highlighting`** (`omdStepVisualizerHighlighting`): The associated highlighting instance.
+-   **`stepTextBoxes`** (`Array<object>`): An array of objects, each representing an active text box. Each object contains `dotIndex`, `interactiveSteps` (the `omdStepVisualizerInteractiveSteps` instance), and `layoutGroup` (its `jsvgLayoutGroup`).
+
+## Public Methods
+
+### `createTextBoxForDot(dotIndex)`
+
+Creates and displays an interactive text box for the specified step dot. This involves retrieving simplification data, finding the appropriate positioning reference, and then creating and adding the `omdStepVisualizerInteractiveSteps` component to the visualizer's container.
+
+-   **`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. It destroys the `omdStepVisualizerInteractiveSteps` instance and removes its `layoutGroup` from the visual container, then triggers a layout update.
+
+-   **`dotIndex`** (`number`): The index of the dot whose text box should be removed.
+
+### `clearAllTextBoxes()`
+
+Removes all active text boxes from the visualizer. It iterates through all tracked text boxes, destroys their `interactiveSteps` instances, removes their `layoutGroup`s from the visual container, and then clears the `stepTextBoxes` array. A layout update is triggered afterwards.
+
+### `getStepTextBoxes()`
+
+Returns an array of all currently active text box objects managed by this class.
+
+-   **Returns**: `Array<object>`.
+
+## Internal Methods
+
+-   **`_createInteractiveStepsForDot(dotIndex, targetDot, simplificationData)`**: Creates and configures an `omdStepVisualizerInteractiveSteps` instance. It positions the text box relative to the `targetDot`, sets up hover and click interactions, and adds the text box's `layoutGroup` to the `stepVisualizer.visualContainer`.
+-   **`_findDotAboveForPositioning(dotIndex)`**: Determines the appropriate `omdEquationNode` (and its corresponding dot) to position the text box relative to. It searches for the nearest visible equation above the clicked dot, falling back to the clicked dot itself if no such equation is found.
+-   **`_getSimplificationDataForDot(dotIndex)`**: Retrieves the simplification data for a given dot by delegating the call to the `stepVisualizer`'s internal method (`stepVisualizer._getSimplificationDataForDot`).
+
+## 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`:
+
+```javascript
+// Inside omdStepVisualizer's _handleDotClick method:
+this.textBoxManager.createTextBoxForDot(dotIndex);
+
+// Inside omdStepVisualizer's _clearActiveDot method:
+this.textBoxManager.removeTextBoxForDot(this.activeDotIndex);
+```

package/npm-docs/api/omdToolbar.md

@@ -0,0 +1,131 @@
+# 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.). It features dynamic popups for selecting operations and inputting values.
+
+## Class Definition
+
+```javascript
+export class omdToolbar
+```
+
+## Constructor
+
+### `new omdToolbar(parentContainer, sequence, [options])`
+
+Creates an instance of the `omdToolbar`.
+
+-   **`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`.
+        -   `undo` (`string`): Undo button background. Default: `#87D143`.
+    -   `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`.
+    -   `popupDirection` (`string`): Direction for popups (`'below'` or `'above'`). Default: `'below'`.
+    -   `showUndoButton` (`boolean`): Whether to display an undo button. Default: `false`.
+    -   `undoIconUrl` (`string`): Data URL for the undo button icon. Default: a base64 encoded SVG.
+    -   `onUndo` (`function`): Custom callback function for the undo action. If not provided, it attempts to call `window.onOMDToolbarUndo`.
+    -   `x`, `y` (`number`): Optional position of the toolbar in the parent container.
+    -   `styles` (`object`): An object to provide structured styling options (e.g., `backgroundColor`, `buttonColor`, `popupBackgroundColor`, `borderRadius`, `buttonSize`, `mainFontSize`, `inputFontSize`, `menuFontSize`, `inputWidth`, `padding`, `spacing`). These override individual options.
+
+## Public Properties
+
+-   **`parentContainer`** (`jsvgGroup`): The SVG group where the toolbar is rendered.
+-   **`sequence`** (`omdEquationSequenceNode`): The sequence node the toolbar interacts with.
+-   **`config`** (`object`): The merged configuration options for the toolbar, including defaults and overrides.
+-   **`state`** (`object`): Internal state of the toolbar, including:
+    -   `activePopup` (`object` | `null`): Tracks the currently active popup (`type`, `group`).
+    -   `selectedOperation` (`string`): The currently selected operation (e.g., `'+'`, `'f'`).
+    -   `inputValue` (`string`): The current value in the input field.
+-   **`elements`** (`object`): An object containing references to the various `jsvg` elements that make up the toolbar UI:
+    -   `toolbarGroup` (`jsvgGroup`): The main SVG group for the entire toolbar.
+    -   `background` (`jsvgRect`): The background rectangle of the toolbar.
+    -   `leftButton` (`jsvgButton`): The button for selecting operations.
+    -   `middleInputButton` (`jsvgButton`): The button for displaying and inputting values.
+    -   `rightButton` (`jsvgButton`): The button for applying the operation.
+    -   `undoButton` (`jsvgButton`): The optional undo button.
+
+## Public Methods
+
+### `setInputText(text)`
+
+Sets the text displayed in the middle input button and updates the internal `inputValue` state. It also adjusts the font size of the button's text element for better centering.
+
+-   **`text`** (`string`): The text to display.
+
+### `destroy()`
+
+Cleans up the toolbar component by removing its SVG elements from the DOM and clearing internal references.
+
+## Internal Methods
+
+-   **`_render()`**: Renders the initial toolbar UI components, including the background, operation button, input button, apply button, and optional undo button. It also sets up their initial positions and styling.
+-   **`_bringToFront(node)`**: Moves a `jsvgObject` to the top of its parent's stacking order to ensure it's visible.
+-   **`_togglePopup(popupType)`**: Toggles the visibility of a popup menu (either `'operations'` or `'input'`). It ensures only one popup is visible at a time and handles attaching/detaching the popup's SVG group to the toolbar's group.
+-   **`_renderPopup(contentFactory, anchorButton)`**: A generic method to create and position a popup group. It takes a `contentFactory` function (which generates the popup's content) and an `anchorButton` to position the popup relative to.
+-   **`_renderOperationsMenu()`**: Renders the operations menu popup, containing buttons for `'f'` (function), `'÷'`, `'×'`, `'–'`, and `'+'`.
+-   **`_renderFunctionMenu()`**: Renders the function selection menu popup, containing buttons for common functions like `'sqrt'`, `'cos'`, `'sin'`, `'tan'`, and `'ln'`.
+-   **`_renderDigitGrid()`**: Renders the digit grid (number pad) popup, including digits `0-9`, a backspace (`'←'`), and a variable (`'x'`).
+-   **`_handleFunctionClick(func)`**: Handles clicks on the function menu buttons, setting the input text to the selected function name.
+-   **`_handleDigitClick(digit)`**: Handles clicks on the digit grid buttons, updating the input value (appending digits or performing backspace).
+-   **`_selectOperation(operation)`**: Handles the selection of a new operation from the menu, updating the left button's text and potentially clearing the input text if switching to/from function mode.
+-   **`_applyOperation()`**: Applies the selected operation and value to the `sequence`. It parses the input value (as a number or math.js expression) and calls the appropriate method on the `sequence` (e.g., `applyEquationFunction`, `applyEquationOperation`). It also clears the input and notifies the host application to refresh the display.
+-   **`_createButton(config)`**: A factory method for creating `jsvgButton` instances with common styling and behavior. It supports text labels, SVG icons, and custom sizes.
+-   **`_updateApplyButtonState()`**: Updates the enabled/disabled state of the apply button based on whether there is an `inputValue`.
+-   **`_updateToolbarLayout()`**: Updates the positions of all toolbar elements (buttons, background) to ensure correct spacing and alignment.
+-   **`_handleUndo()`**: Handles the undo action, either by calling a custom `onUndo` callback or a global `window.onOMDToolbarUndo` hook.
+
+## Example
+
+```javascript
+import { omdToolbar } from '@teachinglab/omd';
+import { omdEquationSequenceNode } from '@teachinglab/omd';
+import { omdEquationNode } from '@teachinglab/omd';
+
+// 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,
+  showUndoButton: true, // Enable the undo button
+  styles: { // Example of structured styling
+    backgroundColor: '#34495e',
+    buttonColor: '#ecf0f1',
+    popupBackgroundColor: '#bdc3c7',
+    borderRadius: 10
+  }
+});
+
+// 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) - The sequence node the toolbar operates on.
+-   [`omdEquationNode`](./omdEquationNode.md) - The type of nodes typically found in the sequence.