@teachinglab/omd 0.1.4 → 0.1.6

package/docs/api/omdLeafNode.md

@@ -1,163 +1,86 @@
-
-Represents a leaf in the AST tree, such as an operator, constant, variable, or grouping symbol. This is a base class for other specific leaf node types.
-
-## Class: `omdLeafNode extends omdNode`
-
-```javascript
-import { omdLeafNode } from './omd/nodes/omdLeafNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdLeafNode(nodeData)
-```
-
-**Parameters:**
-
-**Description:**
-Creates a new leaf node. This is an abstract base class - use concrete subclasses instead.
-
-### Methods
-
-Inherits all methods from [omdNode](./omdNode.md), plus:
-
-#### `createTextElement(text)`
-Creates and positions the text element for the node.
-  - Text anchor set to 'middle'
-  - Dominant baseline set to 'middle'
-  - Added as a child of this node
-
-
-#### `clone()`
-Creates a clone of the leaf node.
-  - Same constructor as original
-  - Original node's ID added to provenance array
-
-
-#### `updateTextElement(text)`
-Updates the text content.
-
-
-#### `computeDimensions()`
-Calculates node dimensions based on text content.
-
-
-#### `updateLayout()`
-Updates the position of the node.
-
-
-#### `updateTextPosition()`
-Internal method to center text in node.
-
-### Examples
-
-```javascript
-// This is an abstract class - use concrete subclasses
-const constant = new omdConstantNode(5);
-const variable = new omdVariableNode('x');
-const operator = new omdOperatorNode('+');
-
-// All leaf nodes handle text rendering
-constant.createTextElement('5');
-constant.computeDimensions();
-constant.updateLayout();
-```
-
-### See Also
-
-Concrete implementations:
-
-Base class:
-# omdLeafNode
-
-Represents a leaf in the AST tree, such as an operator, constant, variable, or grouping symbol. This is a base class for other specific leaf node types.
-
-## Class: `omdLeafNode extends omdNode`
-
-```javascript
-import { omdLeafNode } from './omd/nodes/omdLeafNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdLeafNode(nodeData)
-```
-
-**Parameters:**
-- `nodeData` {Object} - The AST node data
-
-**Description:**
-Creates a new leaf node. This is an abstract base class—use concrete subclasses instead.
-
-### Methods
-
-Inherits all methods from [omdNode](./omdNode.md), plus:
-
-#### `createTextElement(text)`
-Creates and positions the text element for the node.
-- `text` {string|number} - The text content to display
-- **Returns:** jsvgTextLine - The created text element with:
-  - Text anchor set to 'middle'
-  - Dominant baseline set to 'middle'
-  - Added as a child of this node
-
----
-
-#### `clone()`
-Creates a clone of the leaf node.
-- **Returns:** omdLeafNode - A new instance with:
-  - Same constructor as original
-  - Original node's ID added to provenance array
-
----
-
-#### `updateTextElement(text)`
-Updates the text content.
-- `text` {string|number} - The new text content
-
----
-
-#### `computeDimensions()`
-Calculates node dimensions based on text content.
-- Gets font size from parent
-- Updates text element font size
-- Sets width and height based on text bounds
-
----
-
-#### `updateLayout()`
-Updates the position of the node.
-- Calls updateTextPosition()
-
----
-
-#### `updateTextPosition()`
-Internal method to center text in node.
-- Sets text position to (width/2, height/2)
-
-### Example
-
-```javascript
-// This is an abstract class—use concrete subclasses
-const constant = new omdConstantNode(5);
-const variable = new omdVariableNode('x');
-const operator = new omdOperatorNode('+');
-
-// All leaf nodes handle text rendering
-constant.createTextElement('5');
-constant.computeDimensions();
-constant.updateLayout();
-```
-
-### See Also
-
-Concrete implementations:
-- [omdConstantNode](./omdConstantNode.md) - For numeric values
-- [omdVariableNode](./omdVariableNode.md) - For variables
-- [omdOperatorNode](./omdOperatorNode.md) - For operators
-- [omdGroupNode](./omdGroupNode.md) - For grouping symbols
-
-Base class:
-- [omdNode](./omdNode.md) - Parent class
+# omdLeafNode
+
+Represents a base class for all leaf nodes in the OMD expression tree, such as constants, variables, operators, and grouping symbols. This class provides fundamental functionalities for handling text content, computing dimensions, and managing layout for single-element nodes.
+
+## Class Definition
+
+```javascript
+export class omdLeafNode extends omdNode
+```
+
+## Constructor
+
+### `new omdLeafNode(astNodeData)`
+
+Creates a new `omdLeafNode` instance. This is an abstract base class; you should use its concrete subclasses (e.g., `omdConstantNode`, `omdVariableNode`) instead.
+
+-   **`astNodeData`** (`object`): The abstract syntax tree (AST) node data from a parser like math.js, containing information relevant to the leaf node.
+
+## Public Properties
+
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that renders the text content of the leaf node.
+
+## Public Methods
+
+### `clone()`
+
+Creates a deep clone of the leaf node. This method uses the original node's constructor to create a new instance, ensuring that the correct subclass is instantiated. The clone's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdLeafNode` - A new instance of the specific leaf node subclass.
+
+### `updateTextElement(text)`
+
+Updates the text content displayed by the node's `textElement`. After updating the text, you typically need to call `computeDimensions()` and `updateLayout()` to reflect the change visually.
+
+-   **`text`** (`string` | `number`): The new text content to display.
+
+### `computeDimensions()`
+
+Calculates the dimensions (width and height) of the node based on its text content and current font size. It uses the `getTextBounds` utility function to accurately measure the text. This method also updates the font size of the internal `textElement`.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the position of the node's internal text element to center it within the node's bounding box. This method primarily calls the internal `updateTextPosition()`.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+## Internal Methods
+
+-   **`createTextElement(text)`**: Creates and initializes a `jsvgTextLine` element with the given text. It sets the text anchor to `'middle'` and dominant baseline to `'middle'` for proper centering, and adds it as a child of this node.
+    -   **Returns**: `jsvgTextLine` - The created text element.
+-   **`updateTextPosition()`**: Positions the `textElement` at the center of the node's calculated width and height.
+
+## Example
+
+```javascript
+// omdLeafNode is an abstract class—use concrete subclasses
+import { omdConstantNode } from './omdConstantNode.js';
+import { omdVariableNode } from './omdVariableNode.js';
+import { omdOperatorNode } from './omdOperatorNode.js';
+
+const constant = new omdConstantNode({ value: 5 });
+const variable = new omdVariableNode({ name: 'x' });
+const operator = new omdOperatorNode({ op: '+' });
+
+// All leaf nodes handle text rendering and layout similarly
+constant.initialize(); // Computes dimensions and layout
+variable.initialize();
+operator.initialize();
+
+// You can then add these to an omdDisplay or other container
+```
+
+## See Also
+
+Concrete implementations:
+
+-   [`omdConstantNode`](./omdConstantNode.md) - For numeric values.
+-   [`omdVariableNode`](./omdVariableNode.md) - For variables.
+-   [`omdOperatorNode`](./omdOperatorNode.md) - For operators.
+-   [`omdGroupNode`](./omdGroupNode.md) - For grouping symbols.
+
+Base class:
+
+-   [`omdNode`](./omdNode.md) - The fundamental base class for all OMD nodes.

package/docs/api/omdNode.md

@@ -1,101 +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.
-
-## 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 created from a node in the math.js AST.
-- **Tree Structure:** Nodes are organized in a tree with `parent` and `childList` properties.
-- **Layout:** The `computeDimensions()` and `updateLayout()` methods are responsible for determining the size and position of a node and its children.
-- **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 link back to its predecessor.
-
-### Properties
-
-#### `id`
-- **Type:** `number`
-- **Description:** A unique identifier for the node instance.
-
-#### `parent`
-- **Type:** `omdNode` | `null`
-- **Description:** A reference to the parent node in the tree.
-
-#### `astNodeData`
-- **Type:** `Object`
-- **Description:** The original math.js AST node from which this `omdNode` was created.
-
-#### `provenance`
-- **Type:** `Array<number>`
-- **Description:** An array of IDs from which this node was derived, forming a historical chain.
-
-#### `argumentNodeList`
-- **Type:** `Object`
-- **Description:** A map of the node's meaningful children (e.g., `{ left: omdNode, right: omdNode }` for a binary expression).
-
-### Core Methods
-
-These methods form the essential public API for interacting with nodes.
-
-#### `initialize()`
-
-Initializes the node by recursively computing its dimensions and updating its layout. This should be called after a node and its children have been constructed.
-
----
-
-#### `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`.
-
-- **Returns:** `omdNode` - A new instance of the same type as the original.
-
----
-
-#### `replaceWith(newNode, options)`
-
-Replaces this node with a new node in the tree, updating all parent and child references and re-rendering the SVG.
-
-- **Parameters:**
-  - `newNode` {omdNode} - The node to substitute in.
-  - `options` {Object} (optional) - e.g., `{ updateLayout: true }`.
-- **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.
-
-- **Returns:** `Promise<Object>` - A promise that resolves to an object like `{ success, foldedCount, newRoot, message }`.
-
----
-
-#### `toMathJSNode()`
-
-Converts the `omdNode` and its children back into a math.js-compatible AST object. This must be implemented by all subclasses.
-
-- **Returns:** `Object` - The math.js AST node.
-
----
-
-#### `toString()`
-
-Converts the node into a human-readable string representation.
-
-- **Returns:** `string`.
-
-### Layout and Rendering Methods
-
-These methods are primarily for internal use and are overridden by subclasses to define specific layout and rendering logic.
-
-- `computeDimensions()`: Calculates the `width` and `height` of the node.
-- `updateLayout()`: Positions the node's children relative to itself.
-- `getAlignmentBaseline()`: Returns the vertical y-coordinate used to align this node with its siblings.
-
-### See Also
-
-- [`omdLeafNode`](./omdLeafNode.md) - The base class for nodes with no children (constants, variables).
-- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For nodes with two children (e.g., addition, subtraction).
-- [`omdFunctionNode`](./omdFunctionNode.md) - For function calls.
+# 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.