@teachinglab/omd 0.6.0 → 0.6.2

package/npm-docs/api/omdNode.md

@@ -1,202 +1,202 @@
-# omdNode
-
-The abstract base class for all nodes in the mathematical expression tree. It provides the core functionality for tree structure (parent-child relationships), layout calculations, rendering, and provenance tracking. All specific mathematical elements (constants, variables, operators, functions, equations) extend this class.
-
-## Class Definition
-
-```javascript
-export class omdNode extends omdMetaExpression
-```
-
-This class is not meant to be instantiated directly. Instead, you should use one of its concrete subclasses (e.g., `omdConstantNode`, `omdBinaryExpressionNode`).
-
-### Key Concepts
-
--   **AST (Abstract Syntax Tree):** Each `omdNode` is typically created from a node in the math.js AST, providing a structured representation of the mathematical expression.
--   **Tree Structure:** Nodes are organized in a hierarchical tree with `parent` and `childList` properties, enabling traversal and manipulation of the expression.
--   **Layout:** The `computeDimensions()` and `updateLayout()` methods are fundamental for determining the size and position of a node and its children, ensuring correct visual rendering.
--   **Provenance:** The `provenance` array on each node tracks its history. When a node is cloned (e.g., during a simplification step), the new node's provenance array will contain the ID of the original node, creating a traceable link back to its predecessor. This is crucial for features like step-by-step explanations and highlighting.
-
-## Public Properties
-
--   **`id`** (`number`): A unique identifier for each node instance, automatically assigned upon creation.
--   **`type`** (`string`): A string indicating the specific type of the OMD node (e.g., `"omdConstantNode"`, `"omdBinaryExpressionNode"`).
--   **`parent`** (`omdNode` | `null`): A reference to the parent node in the expression tree. `null` for the root node.
--   **`astNodeData`** (`object`): The original math.js AST node from which this `omdNode` was created. This preserves the raw parsed data.
--   **`provenance`** (`Array<number>`): An array of IDs from which this node was derived. This forms a historical chain, linking a node back through transformations or simplifications.
--   **`argumentNodeList`** (`object`): A map (or object) containing references to the node's structurally significant children (e.g., `left`, `right` for binary expressions, `args` for functions). This is used for recursive operations and provenance tracking.
--   **`isExplainHighlighted`** (`boolean`): A flag indicating if the node is currently highlighted for explanation purposes. This acts as a lock, preventing other highlights from overriding it.
--   **`x`** (`number`): The x-coordinate of the node's top-left corner relative to its parent.
--   **`y`** (`number`): The y-coordinate of the node's top-left corner relative to its parent.
--   **`width`** (`number`): The calculated width of the node's bounding box.
--   **`height`** (`number`): The calculated height of the node's bounding box.
--   **`fontSize`** (`number`): The base font size applied to this node and its children.
--   **`svgElement`** (`SVGElement`): The root SVG element that represents this node visually.
-
-## Public Methods
-
-### `initialize()`
-
-Initializes the node by recursively computing its dimensions and updating its layout. This method should be called after a node and its children have been fully constructed to ensure proper sizing and positioning.
-
-### `clone()`
-
-Creates a deep, structural clone of the node. The new node will have a new `id`, and its `provenance` will link back to the original node's `id`, establishing a historical connection.
-
--   **Returns**: `omdNode` - A new instance of the same type as the original, with all children also cloned.
-
-### `replaceWith(newNode, options)`
-
-Replaces this node with a `newNode` in the expression tree. This updates all parent and child references and triggers a re-layout and re-rendering of the affected parts of the SVG.
-
--   **`newNode`** (`omdNode`): The node to substitute in.
--   **`options`** (`object`, optional): Configuration for the replacement.
-    -   `updateLayout` (`boolean`): If `true` (default), the layout of the entire tree will be recalculated upwards from the point of replacement.
--   **Returns**: `boolean` - `true` if the replacement was successful.
-
-### `simplify()`
-
-Asynchronously attempts to simplify the expression rooted at this node by invoking the central simplification engine (`simplifyStep`).
-
--   **Returns**: `Promise<object>` - A promise that resolves to an object like `{ success, foldedCount, newRoot, message }`. Throws an error if the `simplifyStep` function is not set.
-
-### `toMathJSNode()`
-
-Converts the `omdNode` and its children back into a math.js-compatible AST object. This method must be implemented by all concrete subclasses.
-
--   **Returns**: `object` - The math.js AST node.
--   **Throws**: `Error` if not implemented by the subclass.
-
-### `toString()`
-
-Converts the node into a human-readable string representation. It typically uses the `toMathJSNode()` method internally to leverage math.js's string conversion capabilities.
-
--   **Returns**: `string`.
-
-### `render()`
-
-Generates or retrieves the SVG representation of the node. This method calls `renderSelf()` if the SVG element has not been created yet.
-
--   **Returns**: `SVGElement` - The root SVG element representing this node.
-
-### `renderSelf()`
-
-Abstract method that must be implemented by subclasses. This method is responsible for creating the specific SVG elements and structure for the node's visual representation.
-
--   **Returns**: `SVGElement` - The SVG element created for this node.
--   **Throws**: `Error` if not implemented by the subclass.
-
-### `setFontSize(size)`
-
-Sets the base font size for this node and recursively propagates the new font size to all its children.
-
--   **`size`** (`number`): The font size in pixels.
-
-### `moveTo(x, y)`
-
-Moves the node to a new absolute position (`x`, `y`) relative to its parent. It also recursively moves all children by the same delta.
-
--   **`x`** (`number`): The new x-coordinate.
--   **`y`** (`number`): The new y-coordinate.
-
-### `show()`
-
-Makes the node and its SVG representation visible.
-
-### `hide()`
-
-Hides the node and its SVG representation.
-
-### `getDepth()`
-
-Calculates the depth of the node in the expression tree (0 for the root node).
-
--   **Returns**: `number` - The depth of the node.
-
-### `findParentOfType(type)`
-
-Traverses up the tree to find the nearest parent node of a specific type.
-
--   **`type`** (`string`): The `type` property of the node to search for (e.g., `"omdEquationNode"`).
--   **Returns**: `omdNode` | `null` - The found parent node or `null` if not found.
-
-### `validateProvenance(nodeMap)`
-
-Validates the provenance integrity of this node and all its descendants. It checks for duplicate IDs, invalid references, and self-references in the `provenance` arrays.
-
--   **`nodeMap`** (`Map`, optional): An optional map of all known nodes in the system, used for cross-referencing provenance IDs.
--   **Returns**: `Array<object>` - An array of validation issues found, each describing the type of issue, the node involved, and relevant IDs.
-
-### `setHighlight(highlightOn, color)`
-
-Applies or removes a highlight from the node's background. If `isExplainHighlighted` is `true`, this method will not override the existing explanation highlight.
-
--   **`highlightOn`** (`boolean`): `true` to highlight, `false` to remove.
--   **`color`** (`string`, optional): The color of the highlight. Defaults to `omdColor.highlightColor`.
-
-### `lowlight()`
-
-Reduces the opacity of the node's background. Similar to `setHighlight`, it respects the `isExplainHighlighted` lock.
-
-### `setFillColor(color)`
-
-Sets the fill color of the node's background rectangle. This method also respects the `isExplainHighlighted` lock.
-
-## Abstract Methods (to be implemented by subclasses)
-
--   **`computeDimensions()`**: Calculates the `width` and `height` of the node based on its content and children. Provides a default empty implementation.
--   **`updateLayout()`**: Positions the node's children relative to itself. Provides a default empty implementation.
--   **`getAlignmentBaseline()`**: Returns the vertical y-coordinate within the node's bounding box that should be used for alignment with its siblings. By default, this is the vertical center (`this.height / 2`).
--   **`isConstant()`**: Determines if the node represents a constant numerical value. Returns `false` by default.
--   **`getValue()`**: Retrieves the numerical value of a constant node. Throws an error if the node is not constant.
--   **`getRationalValue()`**: Retrieves the rational value of a constant node as a numerator/denominator pair. Throws an error if the node is not a constant rational expression.
-
-## Internal Methods
-
--   **`_syncProvenanceFrom(originalNode)`**: Recursively walks a cloned node tree and sets the provenance of each node to point back to the corresponding node in the original tree. This is a crucial part of maintaining the provenance chain during cloning operations.
--   **`replaceNodeInParent(newNode)`**: Helper method used by `replaceWith` to update specific references to this node within its parent's `argumentNodeList` and other properties.
--   **`updateSvg(newNode)`**: Helper method used by `replaceWith` to perform the actual DOM manipulation (replacing SVG elements).
--   **`updateLayoutUpwards()`**: Traverses up the tree from this node's parent to re-calculate dimensions and layouts for all ancestors, ensuring the entire affected tree is correctly rendered after a change.
--   **`_validateStepsProvenance(issues)`**: Helper for `validateProvenance` to check provenance within steps.
--   **`_findOrphanedNodes(issues)`**: Helper for `validateProvenance` to find nodes in the `nodeMap` that are no longer part of the active tree.
--   **`_collectAllProvenanceIds(newNodeMap)`**: Collects all provenance IDs from nodes in a given map.
--   **`_collectNodeProvenanceIds(node, referencedIds, processedNodes)`**: Recursively collects provenance IDs for a single node.
--   **`_preserveReferencedNodes(referencedIds, newNodeMap)`**: Ensures that historical nodes referenced in provenance chains are kept in the `nodeMap`.
--   **`_preserveNodeAndContext(id, newNodeMap, processedIds)`**: Preserves a historical node and its relevant parent/sibling context.
--   **`_preserveParentContext(node, newNodeMap)`**: Preserves the parent nodes of a historical node.
--   **`_preserveSiblingContext(node, newNodeMap)`**: Preserves the sibling nodes of a historical node.
-
-## Example
-
-```javascript
-// omdNode is an abstract class - use concrete subclasses
-import { omdConstantNode } from './omdConstantNode.js';
-import { omdBinaryExpressionNode } from './omdBinaryExpressionNode.js';
-import { omdDisplay } from '../display/omdDisplay.js';
-
-// Create a simple expression tree
-const two = new omdConstantNode({ value: 2 });
-const x = new omdVariableNode({ name: 'x' });
-const twoX = new omdBinaryExpressionNode({
-    type: 'OperatorNode', op: '*', fn: 'multiply',
-    args: [two.astNodeData, x.astNodeData],
-    implicit: true
-});
-
-// Initialize the root node (this will recursively initialize children)
-twoX.initialize();
-
-// Render it using omdDisplay
-const container = document.getElementById('math-container');
-const display = new omdDisplay(container);
-display.render(twoX);
-
-console.log(twoX.toString()); // Output: 2x
-```
-
-## See Also
-
--   [`omdLeafNode`](./omdLeafNode.md) - The base class for nodes with no children (constants, variables, operators).
--   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For nodes with two children (e.g., addition, subtraction, multiplication).
--   [`omdFunctionNode`](./omdFunctionNode.md) - For function calls (e.g., `sin(x)`).
+# omdNode
+
+The abstract base class for all nodes in the mathematical expression tree. It provides the core functionality for tree structure (parent-child relationships), layout calculations, rendering, and provenance tracking. All specific mathematical elements (constants, variables, operators, functions, equations) extend this class.
+
+## Class Definition
+
+```javascript
+export class omdNode extends omdMetaExpression
+```
+
+This class is not meant to be instantiated directly. Instead, you should use one of its concrete subclasses (e.g., `omdConstantNode`, `omdBinaryExpressionNode`).
+
+### Key Concepts
+
+-   **AST (Abstract Syntax Tree):** Each `omdNode` is typically created from a node in the math.js AST, providing a structured representation of the mathematical expression.
+-   **Tree Structure:** Nodes are organized in a hierarchical tree with `parent` and `childList` properties, enabling traversal and manipulation of the expression.
+-   **Layout:** The `computeDimensions()` and `updateLayout()` methods are fundamental for determining the size and position of a node and its children, ensuring correct visual rendering.
+-   **Provenance:** The `provenance` array on each node tracks its history. When a node is cloned (e.g., during a simplification step), the new node's provenance array will contain the ID of the original node, creating a traceable link back to its predecessor. This is crucial for features like step-by-step explanations and highlighting.
+
+## Public Properties
+
+-   **`id`** (`number`): A unique identifier for each node instance, automatically assigned upon creation.
+-   **`type`** (`string`): A string indicating the specific type of the OMD node (e.g., `"omdConstantNode"`, `"omdBinaryExpressionNode"`).
+-   **`parent`** (`omdNode` | `null`): A reference to the parent node in the expression tree. `null` for the root node.
+-   **`astNodeData`** (`object`): The original math.js AST node from which this `omdNode` was created. This preserves the raw parsed data.
+-   **`provenance`** (`Array<number>`): An array of IDs from which this node was derived. This forms a historical chain, linking a node back through transformations or simplifications.
+-   **`argumentNodeList`** (`object`): A map (or object) containing references to the node's structurally significant children (e.g., `left`, `right` for binary expressions, `args` for functions). This is used for recursive operations and provenance tracking.
+-   **`isExplainHighlighted`** (`boolean`): A flag indicating if the node is currently highlighted for explanation purposes. This acts as a lock, preventing other highlights from overriding it.
+-   **`x`** (`number`): The x-coordinate of the node's top-left corner relative to its parent.
+-   **`y`** (`number`): The y-coordinate of the node's top-left corner relative to its parent.
+-   **`width`** (`number`): The calculated width of the node's bounding box.
+-   **`height`** (`number`): The calculated height of the node's bounding box.
+-   **`fontSize`** (`number`): The base font size applied to this node and its children.
+-   **`svgElement`** (`SVGElement`): The root SVG element that represents this node visually.
+
+## Public Methods
+
+### `initialize()`
+
+Initializes the node by recursively computing its dimensions and updating its layout. This method should be called after a node and its children have been fully constructed to ensure proper sizing and positioning.
+
+### `clone()`
+
+Creates a deep, structural clone of the node. The new node will have a new `id`, and its `provenance` will link back to the original node's `id`, establishing a historical connection.
+
+-   **Returns**: `omdNode` - A new instance of the same type as the original, with all children also cloned.
+
+### `replaceWith(newNode, options)`
+
+Replaces this node with a `newNode` in the expression tree. This updates all parent and child references and triggers a re-layout and re-rendering of the affected parts of the SVG.
+
+-   **`newNode`** (`omdNode`): The node to substitute in.
+-   **`options`** (`object`, optional): Configuration for the replacement.
+    -   `updateLayout` (`boolean`): If `true` (default), the layout of the entire tree will be recalculated upwards from the point of replacement.
+-   **Returns**: `boolean` - `true` if the replacement was successful.
+
+### `simplify()`
+
+Asynchronously attempts to simplify the expression rooted at this node by invoking the central simplification engine (`simplifyStep`).
+
+-   **Returns**: `Promise<object>` - A promise that resolves to an object like `{ success, foldedCount, newRoot, message }`. Throws an error if the `simplifyStep` function is not set.
+
+### `toMathJSNode()`
+
+Converts the `omdNode` and its children back into a math.js-compatible AST object. This method must be implemented by all concrete subclasses.
+
+-   **Returns**: `object` - The math.js AST node.
+-   **Throws**: `Error` if not implemented by the subclass.
+
+### `toString()`
+
+Converts the node into a human-readable string representation. It typically uses the `toMathJSNode()` method internally to leverage math.js's string conversion capabilities.
+
+-   **Returns**: `string`.
+
+### `render()`
+
+Generates or retrieves the SVG representation of the node. This method calls `renderSelf()` if the SVG element has not been created yet.
+
+-   **Returns**: `SVGElement` - The root SVG element representing this node.
+
+### `renderSelf()`
+
+Abstract method that must be implemented by subclasses. This method is responsible for creating the specific SVG elements and structure for the node's visual representation.
+
+-   **Returns**: `SVGElement` - The SVG element created for this node.
+-   **Throws**: `Error` if not implemented by the subclass.
+
+### `setFontSize(size)`
+
+Sets the base font size for this node and recursively propagates the new font size to all its children.
+
+-   **`size`** (`number`): The font size in pixels.
+
+### `moveTo(x, y)`
+
+Moves the node to a new absolute position (`x`, `y`) relative to its parent. It also recursively moves all children by the same delta.
+
+-   **`x`** (`number`): The new x-coordinate.
+-   **`y`** (`number`): The new y-coordinate.
+
+### `show()`
+
+Makes the node and its SVG representation visible.
+
+### `hide()`
+
+Hides the node and its SVG representation.
+
+### `getDepth()`
+
+Calculates the depth of the node in the expression tree (0 for the root node).
+
+-   **Returns**: `number` - The depth of the node.
+
+### `findParentOfType(type)`
+
+Traverses up the tree to find the nearest parent node of a specific type.
+
+-   **`type`** (`string`): The `type` property of the node to search for (e.g., `"omdEquationNode"`).
+-   **Returns**: `omdNode` | `null` - The found parent node or `null` if not found.
+
+### `validateProvenance(nodeMap)`
+
+Validates the provenance integrity of this node and all its descendants. It checks for duplicate IDs, invalid references, and self-references in the `provenance` arrays.
+
+-   **`nodeMap`** (`Map`, optional): An optional map of all known nodes in the system, used for cross-referencing provenance IDs.
+-   **Returns**: `Array<object>` - An array of validation issues found, each describing the type of issue, the node involved, and relevant IDs.
+
+### `setHighlight(highlightOn, color)`
+
+Applies or removes a highlight from the node's background. If `isExplainHighlighted` is `true`, this method will not override the existing explanation highlight.
+
+-   **`highlightOn`** (`boolean`): `true` to highlight, `false` to remove.
+-   **`color`** (`string`, optional): The color of the highlight. Defaults to `omdColor.highlightColor`.
+
+### `lowlight()`
+
+Reduces the opacity of the node's background. Similar to `setHighlight`, it respects the `isExplainHighlighted` lock.
+
+### `setFillColor(color)`
+
+Sets the fill color of the node's background rectangle. This method also respects the `isExplainHighlighted` lock.
+
+## Abstract Methods (to be implemented by subclasses)
+
+-   **`computeDimensions()`**: Calculates the `width` and `height` of the node based on its content and children. Provides a default empty implementation.
+-   **`updateLayout()`**: Positions the node's children relative to itself. Provides a default empty implementation.
+-   **`getAlignmentBaseline()`**: Returns the vertical y-coordinate within the node's bounding box that should be used for alignment with its siblings. By default, this is the vertical center (`this.height / 2`).
+-   **`isConstant()`**: Determines if the node represents a constant numerical value. Returns `false` by default.
+-   **`getValue()`**: Retrieves the numerical value of a constant node. Throws an error if the node is not constant.
+-   **`getRationalValue()`**: Retrieves the rational value of a constant node as a numerator/denominator pair. Throws an error if the node is not a constant rational expression.
+
+## Internal Methods
+
+-   **`_syncProvenanceFrom(originalNode)`**: Recursively walks a cloned node tree and sets the provenance of each node to point back to the corresponding node in the original tree. This is a crucial part of maintaining the provenance chain during cloning operations.
+-   **`replaceNodeInParent(newNode)`**: Helper method used by `replaceWith` to update specific references to this node within its parent's `argumentNodeList` and other properties.
+-   **`updateSvg(newNode)`**: Helper method used by `replaceWith` to perform the actual DOM manipulation (replacing SVG elements).
+-   **`updateLayoutUpwards()`**: Traverses up the tree from this node's parent to re-calculate dimensions and layouts for all ancestors, ensuring the entire affected tree is correctly rendered after a change.
+-   **`_validateStepsProvenance(issues)`**: Helper for `validateProvenance` to check provenance within steps.
+-   **`_findOrphanedNodes(issues)`**: Helper for `validateProvenance` to find nodes in the `nodeMap` that are no longer part of the active tree.
+-   **`_collectAllProvenanceIds(newNodeMap)`**: Collects all provenance IDs from nodes in a given map.
+-   **`_collectNodeProvenanceIds(node, referencedIds, processedNodes)`**: Recursively collects provenance IDs for a single node.
+-   **`_preserveReferencedNodes(referencedIds, newNodeMap)`**: Ensures that historical nodes referenced in provenance chains are kept in the `nodeMap`.
+-   **`_preserveNodeAndContext(id, newNodeMap, processedIds)`**: Preserves a historical node and its relevant parent/sibling context.
+-   **`_preserveParentContext(node, newNodeMap)`**: Preserves the parent nodes of a historical node.
+-   **`_preserveSiblingContext(node, newNodeMap)`**: Preserves the sibling nodes of a historical node.
+
+## Example
+
+```javascript
+// omdNode is an abstract class - use concrete subclasses
+import { omdConstantNode } from './omdConstantNode.js';
+import { omdBinaryExpressionNode } from './omdBinaryExpressionNode.js';
+import { omdDisplay } from '../display/omdDisplay.js';
+
+// Create a simple expression tree
+const two = new omdConstantNode({ value: 2 });
+const x = new omdVariableNode({ name: 'x' });
+const twoX = new omdBinaryExpressionNode({
+    type: 'OperatorNode', op: '*', fn: 'multiply',
+    args: [two.astNodeData, x.astNodeData],
+    implicit: true
+});
+
+// Initialize the root node (this will recursively initialize children)
+twoX.initialize();
+
+// Render it using omdDisplay
+const container = document.getElementById('math-container');
+const display = new omdDisplay(container);
+display.render(twoX);
+
+console.log(twoX.toString()); // Output: 2x
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - The base class for nodes with no children (constants, variables, operators).
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For nodes with two children (e.g., addition, subtraction, multiplication).
+-   [`omdFunctionNode`](./omdFunctionNode.md) - For function calls (e.g., `sin(x)`).
 -   [`omdEquationNode`](./omdEquationNode.md) - For representing mathematical equations.