@teachinglab/omd 0.1.4 → 0.1.6

package/docs/api/omdOperationDisplayNode.md

@@ -1,139 +1,118 @@
-# omdOperationDisplayNode
-
-Represents a visual node for displaying an operation applied to both sides of an equation. Example: -3   -3
-
-## Class: `omdOperationDisplayNode extends omdNode`
-
-```javascript
-import { omdOperationDisplayNode } from './omd/nodes/omdOperationDisplayNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdOperationDisplayNode(operation, value)
-```
-
-**Parameters:**
-- `operation` {string} - The type of operation (e.g., 'add', 'subtract', 'multiply', 'divide')
-- `value` {number|string|omdNode} - The value being applied. Can be a number, variable name, or an omdNode
-
-**Description:**
-Creates a node that visually represents an operation on both sides of an equation. The node has no visible background and disables mouse interactions.
-
-### Properties
-
-Inherits all properties from [omdNode](./omdNode.md), plus:
-
-#### `operation`
-- **Type:** string
-- **Description:** The operation type (e.g., 'add', 'subtract')
-
-#### `value`
-- **Type:** number|string|omdNode
-- **Description:** The value used in the operation
-
-#### `type`
-- **Type:** string
-- **Description:** Always "omdOperationDisplayNode"
-
-#### `operatorLeft`, `operatorRight`
-- **Type:** omdOperator
-- **Description:** The operator symbols for each side
-
-#### `valueLeft`, `valueRight`
-- **Type:** omdNode
-- **Description:** The value nodes for each side
-
-### Methods
-
-Inherits all methods from [omdNode](./omdNode.md), plus:
-
-#### `_getOperatorSymbol(operation)`
-Internal method to get display symbol.
-- `operation` {string} - Operation type
-- **Returns:** string - Symbol for operation:
-  - 'add' → '+'
-  - 'subtract' → '-'
-  - 'multiply' → '×'
-  - 'divide' → '÷'
-
----
-
-#### `_createValueElement(value)`
-Internal method to create value node.
-- `value` {number|string|omdNode} - Value to convert
-- **Returns:** omdNode - Appropriate node type:
-  - omdNode → cloned
-  - AST → parsed
-  - number → omdNumber
-  - single letter → omdVariable
-  - string → omdTerm
-  - other → omdExpression
-
----
-
-#### `_disableElement(element)`
-Internal method to disable interactions.
-- `element` {omdNode} - Element to disable
-- Hides background
-- Removes mouse events
-- Disables recursively
-
----
-
-#### `computeDimensions()`
-Calculates node dimensions.
-- Adds padding between operator and value
-- Adds gap between sides
-- Sets width and height based on children
-
----
-
-#### `updateLayout()`
-Updates positions of all elements.
-- Updates child layouts
-- Positions left side elements
-- Adds gap
-- Positions right side elements
-- Centers vertically
-
----
-
-#### `clone()`
-Creates deep clone of node.
-- **Returns:** omdOperationDisplayNode - New instance with:
-  - Same operation and value
-  - Original node's ID in provenance
-
-### Examples
-
-```javascript
-// Create operation display
-const node = new omdOperationDisplayNode('subtract', 3);
-
-// With variable
-const varNode = new omdOperationDisplayNode('multiply', 'x');
-
-// With complex value
-const complexNode = new omdOperationDisplayNode('divide', {
-  type: 'OperatorNode',
-  op: '+',
-  args: [
-    { type: 'ConstantNode', value: 1 },
-    { type: 'SymbolNode', name: 'x' }
-  ]
-});
-
-// Render with proper spacing
-node.setFontSize(24);
-node.computeDimensions();
-node.updateLayout();
-```
-
-### See Also
-
-- [omdNode](./omdNode.md) - Parent class
-- [omdOperator](./omdOperator.md) - For operator symbols
-- [omdEquationNode](./omdEquationNode.md) - For equations
-- [omdEquationSequenceNode](./omdEquationSequenceNode.md) - For step sequences 
+# omdOperationDisplayNode
+
+Represents a visual node for displaying an operation applied to both sides of an equation. This node is designed to show the operation (e.g., `+5` or `×2`) on both the left and right sides of an equation, typically used in step-by-step solution visualizers. It is non-interactive and non-highlightable by design.
+
+## Class Definition
+
+```javascript
+export class omdOperationDisplayNode extends omdNode
+```
+
+## Static Properties
+
+### `OPERATOR_SYMBOLS`
+
+A static map that defines the display symbols for various operations.
+
+```javascript
+static OPERATOR_SYMBOLS = {
+    'add': '+',
+    'subtract': '-',
+    'multiply': '×',
+    'divide': '÷'
+};
+```
+
+## Constructor
+
+### `new omdOperationDisplayNode(operation, value)`
+
+Creates a new `omdOperationDisplayNode` instance.
+
+-   **`operation`** (`string`): The type of operation (e.g., `'add'`, `'subtract'`, `'multiply'`, `'divide'`).
+-   **`value`** (`number` | `string` | `omdNode`): The value being applied in the operation. Can be a number, a variable name string, or an `omdNode` instance.
+
+During construction, the node initializes its display, creates the visual elements for the operation, disables all user interactions and highlighting, and adds the elements as children.
+
+## Public Properties
+
+-   **`operation`** (`string`): The type of operation (e.g., `'add'`, `'subtract'`).
+-   **`value`** (`number` | `string` | `omdNode`): The value used in the operation.
+-   **`type`** (`string`): Always `"omdOperationDisplayNode"`.
+-   **`leftToken`** (`omdVariableNode`): The `omdVariableNode` representing the operation and value on the left side.
+-   **`rightToken`** (`omdVariableNode`): The `omdVariableNode` representing the operation and value on the right side.
+-   **`gap`** (`number`): The horizontal spacing between the left and right operation tokens.
+-   **`leftClusterWidth`** (`number`): The calculated width of the left operation token, used for alignment in equation sequences.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions (width and height) of the operation display node. It determines the total width by summing the widths of the left and right tokens and the `gap` between them. The height is based on the tallest token with some vertical padding.
+
+### `updateLayout()`
+
+Updates the layout of the operation display node. It positions the `leftToken` at the beginning and the `rightToken` after the calculated `gap`, ensuring they are vertically centered within the node's height.
+
+### `getLeftWidthForAlignment()`
+
+Returns the effective width of the left operation cluster. This is used by `omdEquationSequenceNode` to align the equals signs of equations with the center of the gap in the operation display.
+
+-   **Returns**: `number`.
+
+### `showLeftOnly()`
+
+Hides the right operation token and recalculates the dimensions and layout to display only the left operation. This is useful for scenarios where only one side of the operation needs to be shown.
+
+### `clone()`
+
+Creates a deep clone of the `omdOperationDisplayNode`. The cloned node will have the same operation and value, and its provenance will link back to the original node. The cloned node is also made non-highlightable.
+
+-   **Returns**: `omdOperationDisplayNode` - A new, identical instance.
+
+## Internal Methods
+
+-   **`_initializeDisplay()`**: Sets up the initial display properties, making the background transparent and ensuring the node is non-highlightable.
+-   **`_createOperationElements()`**: Creates the `leftToken` and `rightToken` `omdVariableNode` instances based on the operation and value, and immediately disables their highlighting.
+-   **`_disableAllInteractions()`**: Calls helper methods to disable mouse interactions and highlighting for both operation tokens.
+-   **`_addChildElements()`**: Adds the `leftToken` and `rightToken` as children of this node.
+-   **`_getOperatorSymbol(operation)`**: Converts the operation name (e.g., `'add'`) to its corresponding display symbol (e.g., `'+'`).
+-   **`_valueToString(value)`**: Converts the input `value` (number, string, or `omdNode`) into a string representation for display.
+-   **`_disableElement(element)`**: Recursively disables background, mouse interactions, and highlighting for a given `omdNode` and its children.
+-   **`_hideElementBackground(element)`**: Sets the background of an element to transparent.
+-   **`_disableMouseInteractions(element)`**: Removes mouse event listeners and sets the cursor to `'default'`.
+-   **`_disableHighlighting(element)`**: Overrides highlighting methods (`setHighlight`, `lowlight`, `setFillColor`) on an element to prevent it from being highlighted.
+-   **`_makeNodeNonHighlightable()`**: Applies the `_disableHighlighting` logic to the `omdOperationDisplayNode` itself.
+-   **`_disableChildElements(element)`**: Recursively calls `_disableElement` on all children of a given element.
+
+## Example
+
+```javascript
+// Create operation display for subtracting 3
+const subtractNode = new omdOperationDisplayNode('subtract', 3);
+
+// Create operation display for multiplying by 'x'
+const multiplyNode = new omdOperationDisplayNode('multiply', 'x');
+
+// Create operation display for dividing by a complex expression
+const complexDivideNode = new omdOperationDisplayNode('divide', {
+  type: 'OperatorNode',
+  op: '+',
+  args: [
+    { type: 'ConstantNode', value: 1 },
+    { type: 'SymbolNode', name: 'x' }
+  ]
+});
+
+// To render these, you would typically add them to an omdEquationSequenceNode
+// or an omdDisplay.
+// For example:
+// const display = new omdDisplay(document.getElementById('container'));
+// display.render(subtractNode);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdEquationNode`](./omdEquationNode.md) - For representing mathematical equations.
+-   [`omdEquationSequenceNode`](./omdEquationSequenceNode.md) - For managing sequences of equation steps.

package/docs/api/omdOperatorNode.md

@@ -1,127 +1,92 @@
-# omdOperatorNode
-
-Represents an operator symbol (e.g., `+`, `-`, `*`, `÷`) as a leaf node in the expression tree.
-
-## Class: `omdOperatorNode extends omdLeafNode`
-
-```javascript
-import { omdOperatorNode } from './omd/nodes/omdOperatorNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdOperatorNode(nodeData)
-```
-
-**Parameters:**
-- `nodeData` {Object|string} - The AST node data or the operator symbol as a string.
-
-**Description:**
-Creates a leaf node that represents an operator. It handles mapping from operation names (e.g., 'multiply') to symbols (e.g., `×`).
-
-### Properties
-
-Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `opName`
-- **Type:** string
-- **Description:** The name of the operator (e.g., `*`, `+`)
-
-#### `type`
-- **Type:** string
-- **Description:** Always "operator"
-
-#### `textElement`
-- **Type:** SVGElement
-- **Description:** The SVG text element displaying the operator symbol
-
-### Methods
-
-Inherits all methods from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `parseOpName(nodeData)`
-Internal method to extract operator name from AST data.
-- **Returns:** string
-- **Supported Operators:**
-  - multiply: `×` (configurable)
-  - divide: `÷`
-  - add: `+`
-  - subtract: `−`
-  - pow: `^`
-  - unaryMinus: `-`
-  - unaryPlus: `+`
-
----
-
-#### `parseType()`
-Internal method to set node type.
-- **Returns:** "operator"
-
----
-
-#### `computeDimensions()`
-Calculates dimensions with padding around the operator.
-Overrides base class method.
-
----
-
-#### `updateLayout()`
-Updates the layout of the node.
-Overrides base class method.
-
----
-
-#### `toMathJSNode()`
-Converts to math.js AST format.
-- **Returns:** Object - A math.js-compatible AST node with:
-  - `type`: "OperatorNode"
-  - `op`: Operator name
-  - `fn`: Function name (same as op)
-  - `args`: Empty array
-
----
-
-#### `toString()`
-Convert to string representation.
-- **Returns:** string - The operator symbol
-
----
-
-#### `highlight(color)`
-Highlights the node and sets operator label color to white.
-- `color` {omdColor} - The highlight color
-
----
-
-#### `clearProvenanceHighlights()`
-Clears highlights and resets operator label color.
-
-### Examples
-
-```javascript
-// From string
-const plus = new omdOperatorNode('+');
-const times = new omdOperatorNode('*'); // Displays as × (configurable)
-
-// From AST data
-const minus = new omdOperatorNode({
-  type: 'OperatorNode',
-  op: 'subtract'
-}); // Displays as −
-
-// Rendering
-const node = new omdOperatorNode('+');
-node.setFontSize(24);
-node.computeDimensions(); // Calculate size with padding
-node.updateLayout(); // Position the text element
-```
-
-### See Also
-
-- [omdLeafNode](./omdLeafNode.md) - Parent class
-- [omdNode](./omdNode.md) - Base class
-- [omdBinaryExpressionNode](./omdBinaryExpressionNode.md) - Uses operator nodes
-- [omdUnaryExpressionNode](./omdUnaryExpressionNode.md) - Uses operator nodes
-
-``` 
+# omdOperatorNode
+
+Represents an operator symbol (e.g., `+`, `-`, `*`, `÷`) as a leaf node in the expression tree. This node handles the visual representation of operators, including mapping common operation names to their appropriate symbols and applying styling.
+
+## Class Definition
+
+```javascript
+export class omdOperatorNode extends omdLeafNode
+```
+
+## Constructor
+
+### `new omdOperatorNode(nodeData)`
+
+Creates a new `omdOperatorNode` instance.
+
+-   **`nodeData`** (`object` | `string`): The AST node data (from math.js) or the operator symbol as a string (e.g., `"+"`, `"*"`). The constructor maps common operation names (like `"multiply"`) to their display symbols (like `"×"`), respecting the configured multiplication symbol.
+
+## Public Properties
+
+-   **`opName`** (`string`): The internal name of the operator (e.g., `"*"`, `"+"`). This might differ from the displayed symbol for multiplication.
+-   **`type`** (`string`): Always `"omdOperatorNode"`.
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that displays the operator symbol.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the node based on its text content, adding a small amount of padding around the operator symbol to improve visual spacing.
+
+-   **Overrides**: `omdLeafNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the node. This method primarily calls the superclass's `updateLayout`.
+
+-   **Overrides**: `omdLeafNode.updateLayout()`.
+
+### `toMathJSNode()`
+
+Converts the `omdOperatorNode` to a math.js-compatible AST format. It creates a minimal `OperatorNode` AST object.
+
+-   **Returns**: `object` - A math.js-compatible AST node with `type: "OperatorNode"`, `op` (operator symbol), `fn` (function name, typically same as `op`), and an empty `args` array. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the operator node to its string representation, which is simply its `opName`.
+
+-   **Returns**: `string` - The operator symbol (e.g., `"+"`, `"*"`).
+
+### `highlight(color)`
+
+Applies a highlight to the node's background and sets the operator's text color to white for better contrast. This method respects the `isExplainHighlighted` lock.
+
+-   **`color`** (`string`): The color of the highlight.
+
+### `clearProvenanceHighlights()`
+
+Clears any provenance-related highlights from the node and resets the operator's text color to its default (black).
+
+## Internal Methods
+
+-   **`parseOpName(nodeData)`**: Extracts the operator's internal name from the constructor's `nodeData`. It handles mapping from math.js function names (e.g., `"multiply"`) to display symbols (e.g., `"×"`), using the configured multiplication symbol.
+-   **`parseType()`**: Sets the node's type. Always returns `"operator"`.
+
+## Example
+
+```javascript
+import { omdOperatorNode } from '@teachinglab/omd';
+
+// Create operator nodes from strings
+const plus = new omdOperatorNode('+');
+const times = new omdOperatorNode('*'); // Displays as × (configurable via omdConfigManager)
+
+// Create operator node from AST data (e.g., from math.js parse result)
+const minus = new omdOperatorNode({
+  type: 'OperatorNode',
+  op: '-',
+  fn: 'subtract'
+}); // Displays as −
+
+// To render, typically add to a parent node or an omdDisplay
+// node.setFontSize(24);
+// node.initialize(); // Computes dimensions and layout
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - The parent class for all leaf nodes.
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - A common consumer of operator nodes.
+-   [`omdUnaryExpressionNode`](./omdUnaryExpressionNode.md) - Another consumer of operator nodes (e.g., for unary minus).