@teachinglab/omd 0.6.1 → 0.6.3

package/npm-docs/api/omdStepVisualizerNodeUtils.md

@@ -1,140 +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'
-```
+# 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

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