@teachinglab/omd 0.1.0

package/docs/api/omdConstantNode.md

@@ -0,0 +1,117 @@
+# omdConstantNode
+
+Represents a numeric constant in a mathematical expression. This is a leaf node, meaning it has no children.
+
+## Class: `omdConstantNode extends omdLeafNode`
+
+```javascript
+import { omdConstantNode } from './omd/nodes/omdConstantNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdConstantNode(nodeData)
+```
+
+
+**Parameters:**
+- `nodeData` {Object|number} - The math.js AST node data (should have a `value` property) or a raw numeric value.
+
+**Description:**
+Creates a node representing a numeric constant. This is typically done automatically by the parser when an expression is processed.
+
+### Static Methods
+
+
+#### `fromValue(value)`
+Creates an `omdConstantNode` from a simple numeric value.
+
+```javascript
+const constantNode = omdConstantNode.fromValue(42);
+```
+- **Parameters:**
+  - `value` {number} - The numeric value for the constant.
+- **Returns:** `omdConstantNode` A new instance of `omdConstantNode`.
+
+### Properties
+
+Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
+
+
+#### `number`
+- **Type:** `number`
+- **Description:** The numeric value of the constant.
+
+### Methods
+
+Inherits all methods from [`omdLeafNode`](./omdLeafNode.md). Key methods include:
+
+
+#### `getValue()`
+Gets the numeric value of the constant.
+- **Returns:** `number` - The constant's value.
+
+---
+
+
+#### `evaluate()`
+Evaluates the node, which for a constant simply returns its value.
+- **Returns:** `number` - The numeric value.
+
+---
+
+
+#### `getRationalValue()`
+Gets the value as a rational number (a fraction with a denominator of 1).
+- **Returns:** `Object` - An object `{ num: number, den: 1 }`.
+
+---
+
+
+#### `toMathJSNode()`
+Converts the node to its math.js AST representation.
+- **Returns:** `Object` - A math.js-compatible AST node for a constant, with a `clone()` method for compatibility.
+
+---
+
+
+#### `simplify()`
+A constant cannot be simplified further.
+- **Returns:** `Object` - An object indicating failure: `{ success: false, ... }`.
+
+---
+
+
+#### `toString()`
+Converts the node to its string representation.
+- **Returns:** `string` - The numeric value as a string.
+
+
+#### `isConstant()`
+Checks if the node is a constant (always true for omdConstantNode).
+- **Returns:** `boolean`
+
+### Example
+
+```javascript
+// Create a constant node from a number
+const pi = omdConstantNode.fromValue(3.14159);
+
+// Set its font size and render it
+pi.setFontSize(24);
+pi.initialize(); // Computes dimensions and layout
+
+// Get its value
+console.log(pi.getValue()); // 3.14159
+
+// Add it to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(pi);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdLeafNode`](./omdLeafNode.md) - The parent class.
+- [`omdVariableNode`](./omdVariableNode.md) - For symbolic variables like 'x'.

package/docs/api/omdDisplay.md

@@ -0,0 +1,121 @@
+# omdDisplay
+
+A high-level component for displaying a single mathematical expression or a series of equation steps with automatic centering and layout management.
+
+## Class: `omdDisplay`
+
+```javascript
+import { omdDisplay } from 'omd-library';
+```
+
+### Constructor
+
+```javascript
+new omdDisplay(container, options)
+```
+
+**Parameters:**
+- `container` {HTMLElement} - The DOM element where the expression will be rendered.
+- `options` {Object} (optional) - Configuration options:
+  - `fontSize` {number} - The base font size in pixels for the expression. Defaults to `32`.
+  - `centerContent` {boolean} - If `true`, the content is automatically centered within the container. Defaults to `true`.
+  - `topMargin` {number} - The top margin in pixels, used when centering content. Defaults to `40`.
+
+**Example:**
+```javascript
+const displayContainer = document.getElementById('math-display');
+const display = new omdDisplay(displayContainer, {
+    fontSize: 36,
+    topMargin: 50
+});
+```
+
+### Methods
+
+
+#### `render(expression)`
+Renders a mathematical expression or equation. If a string is provided:
+- If the string contains semicolons (`;`), it is treated as a sequence of equations and rendered as steps.
+- If the string contains an equals sign (`=`), it is treated as a single equation and wrapped in an `omdStepVisualizer`.
+- Otherwise, it is parsed as a single expression.
+
+```javascript
+display.render('x^2 + 2x + 1 = 0');
+
+// Renders a sequence of steps
+display.render('2x + 4 = 10; 2x = 6; x = 3');
+```
+- **Parameters:**
+  - `expression` {string | omdNode} - The mathematical expression string or a pre-existing `omdNode` instance.
+- **Returns:** `omdNode` The root node of the rendered content (often an `omdStepVisualizer`).
+
+---
+
+#### `update(newNode)`
+
+Replaces the currently displayed node with a new one, applying the current font size and centering if enabled.
+
+```javascript
+const newNode = omdEquationNode.fromString('y = mx + b');
+display.update(newNode);
+```
+- **Parameters:**
+  - `newNode` {omdNode} - The new node to display.
+
+---
+
+#### `getCurrentNode()`
+
+Returns the node currently being displayed.
+
+```javascript
+const currentNode = display.getCurrentNode();
+```
+- **Returns:** {omdNode | null} The current root node, or `null` if nothing is displayed.
+
+---
+
+#### `centerNode()`
+
+Manually triggers the centering logic for the current node. This is especially useful for `omdEquationSequenceNode` instances to align them by their equals signs.
+
+```javascript
+display.centerNode();
+```
+
+---
+
+#### `setFontSize(size)`
+
+Updates the font size for the currently displayed node and for any future content rendered.
+
+```javascript
+display.setFontSize(48);
+```
+- **Parameters:**
+  - `size` {number} - The new font size in pixels.
+
+---
+
+#### `clear()`
+
+Removes the current expression from the display.
+
+```javascript
+display.clear();
+```
+
+---
+
+#### `destroy()`
+
+Cleans up the component, removing all DOM elements and detaching the resize observer.
+
+```javascript
+display.destroy();
+```
+
+
+### See Also
+- [`omdStepVisualizer`](./omdStepVisualizer.md) - The component used to display steps.
+- [`omdEquationNode`](./omdEquationNode.md) - The node for representing equations.

package/docs/api/omdEquationNode.md

@@ -0,0 +1,161 @@
+# omdEquationNode
+
+Represents a mathematical equation, which consists of a left side, a right side, and an equals sign. This class provides extensive functionality for manipulating the equation, such as applying operations to both sides, swapping sides, and simplification.
+
+## Class: `omdEquationNode extends omdNode`
+
+```javascript
+import { omdEquationNode } from './omd/nodes/omdEquationNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdEquationNode(ast)
+```
+
+
+**Parameters:**
+- `ast` {Object} - The math.js Abstract Syntax Tree (AST) for the equation. Typically an `AssignmentNode` with `object` (left side) and `value` (right side) properties, but can also be an `OperatorNode` with two arguments.
+
+### Static Methods
+
+
+#### `fromString(equationString)`
+Creates an `omdEquationNode` instance from a string representation of an equation.
+
+```javascript
+const equation = omdEquationNode.fromString('2x + 4 = 10');
+```
+- **Parameters:**
+  - `equationString` {string} - The string to parse (e.g., "2x+4=10").
+- **Returns:** `omdEquationNode` A new instance of `omdEquationNode`.
+- **Throws:** Error if the string is not a valid equation (must contain exactly one '=' and both sides must be non-empty).
+
+### Properties
+
+Inherits all properties from [`omdNode`](./omdNode.md), plus:
+
+#### `left`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the left side of the equation.
+
+#### `right`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the right side of the equation.
+
+#### `equalsSign`
+- **Type:** [`omdOperatorNode`](./omdOperatorNode.md)
+- **Description:** The node for the equals sign.
+
+### Methods
+
+Inherits all methods from [`omdNode`](./omdNode.md), plus:
+
+
+#### `addToBothSides(value)`
+Returns a new equation with a value added to both sides.
+- `value` {number|Object} - The value or math.js AST to add.
+- **Returns:** `omdEquationNode` A new equation node with the operation applied.
+
+---
+
+
+#### `subtractFromBothSides(value)`
+Returns a new equation with a value subtracted from both sides.
+- `value` {number|Object} - The value or math.js AST to subtract.
+- **Returns:** `omdEquationNode` A new equation node.
+
+---
+
+
+#### `multiplyBothSides(value)`
+Returns a new equation with both sides multiplied by a value.
+- `value` {number|Object} - The value or math.js AST to multiply by.
+- **Returns:** `omdEquationNode` A new equation node.
+
+---
+
+
+#### `divideBothSides(value)`
+Returns a new equation with both sides divided by a value.
+- `value` {number|Object} - The value or math.js AST to divide by.
+- **Returns:** `omdEquationNode` A new equation node.
+
+---
+
+
+#### `applyFunction(functionName)`
+Applies a function (e.g., `sqrt`, `log`) to both sides of the equation.
+- `functionName` {string} - The name of the function to apply.
+- **Returns:** `omdEquationNode` A new equation with the function applied to both sides.
+
+---
+
+
+#### `applyOperation(value, operation, side = 'both')`
+Applies an arithmetic operation to one or both sides of the equation.
+- `value` {number|omdNode} - The value to apply.
+- `operation` {string} - The operation to perform: 'add', 'subtract', 'multiply', or 'divide'.
+- `side` {string} - The side to apply the operation to: 'left', 'right', or 'both'. Defaults to 'both'.
+- **Returns:** `omdEquationNode` A new equation node with the operation applied.
+
+---
+
+
+#### `swapSides()`
+Swaps the left and right sides of the equation.
+- **Returns:** `omdEquationNode` A new equation node with the sides swapped.
+
+---
+
+
+#### `simplify()`
+Simplifies both sides of the equation using the simplification engine.
+- **Returns:** `Object` An object containing `{ success, newRoot, message }`.
+
+---
+
+
+#### `clone()`
+Creates a deep clone of the equation node, preserving its structure and provenance.
+- **Returns:** `omdEquationNode` A new, identical instance of the equation node.
+
+---
+
+
+#### `toString()`
+Converts the equation to its string representation.
+- **Returns:** `string` The equation as a string (e.g., "x + 1 = 5").
+
+---
+
+
+#### `evaluate(variables)`
+Evaluates both sides of the equation with a given set of variables.
+- `variables` {Object} - A map of variable names to their numeric values (e.g., `{ x: 2 }`).
+- **Returns:** `Object` An object with the evaluated `left` and `right` side values.
+
+### Example
+
+```javascript
+// Create an equation from a string
+const equation = omdEquationNode.fromString('2 * (x + 1) = 10');
+
+// Perform a series of operations
+const step1 = equation.divideBothSides(2);      // Result: x + 1 = 5
+const step2 = step1.subtractFromBothSides(1); // Result: x = 4
+
+// You can chain these operations
+const finalResult = omdEquationNode.fromString('2 * (x + 1) = 10')
+    .divideBothSides(2)
+    .subtractFromBothSides(1);
+
+console.log(finalResult.toString()); // Output: x = 4
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class for all nodes.
+- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Often used for the sides of the equation.
+- [`omdStepVisualizer`](./omdStepVisualizer.md) - For displaying a sequence of equation transformations.

package/docs/api/omdEquationSequenceNode.md

@@ -0,0 +1,301 @@
+# omdEquationSequenceNode
+
+Represents a sequence of equations for step-by-step calculations. This node manages the layout of multiple equations, ensuring their equals signs are vertically aligned for readability. It's particularly useful for displaying mathematical problem-solving sequences where each step builds on the previous one.
+
+## Class: `omdEquationSequenceNode extends omdNode`
+
+```javascript
+import { omdEquationSequenceNode } from './omd/nodes/omdEquationSequenceNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdEquationSequenceNode(steps)
+```
+
+**Parameters:**
+- `steps` {Array<omdEquationNode>} - An array of `omdEquationNode` objects representing the sequence of equations.
+
+### Static Methods
+
+#### `fromStringArray(stepStrings)`
+Creates an `omdEquationSequenceNode` instance from an array of equation strings.
+
+```javascript
+const sequence = omdEquationSequenceNode.fromStringArray([
+    '2x + 4 = 10',
+    '2x = 6',
+    'x = 3'
+]);
+```
+- **Parameters:**
+  - `stepStrings` {Array<string>} - Array of strings, each representing an equation step.
+- **Returns:** `omdEquationSequenceNode` A new instance.
+- **Throws:** Error if any string is not a valid equation (must contain '=').
+
+---
+
+#### `fromSteps(stepsArray)`
+Creates a sequence from an array of expression strings (can be equations or expressions).
+
+```javascript
+const sequence = omdEquationSequenceNode.fromSteps([
+    '2x + 4 = 10',
+    'x = 3'
+]);
+```
+- **Parameters:**
+  - `stepsArray` {Array<string>} - Array of expression strings.
+- **Returns:** `omdEquationSequenceNode` A new sequence node.
+
+### Properties
+
+Inherits all properties from [`omdNode`](./omdNode.md), plus:
+
+#### `steps`
+- **Type:** `Array<omdNode>`
+- **Description:** Array of nodes representing each step in the sequence.
+
+#### `currentStepIndex`
+- **Type:** `number`
+- **Description:** Index of the currently active step (0-based).
+
+#### `stepDescriptions`
+- **Type:** `Array<string>`
+- **Description:** Optional descriptions for each step.
+
+#### `importanceLevels`
+- **Type:** `Array<number>`
+- **Description:** Importance levels for filtering steps (0 = major, 1 = intermediate, 2 = minor).
+
+#### `currentFilterLevels`
+- **Type:** `Array<number>`
+- **Description:** Currently active filter levels for step visibility.
+
+### Methods
+
+Inherits all methods from [`omdNode`](./omdNode.md), plus:
+
+#### `addStep(step, descriptionOrOptions, importance)`
+Adds a new step to the sequence.
+
+```javascript
+// Using options object
+sequence.addStep(equationNode, { 
+    description: 'Subtract 4 from both sides', 
+    stepMark: 0 
+});
+
+// Using separate parameters
+sequence.addStep(equationNode, 'Subtract 4 from both sides', 0);
+
+// Using string (will be parsed)
+sequence.addStep('x = 3', 'Final result', 0);
+```
+- **Parameters:**
+  - `step` {omdNode|string} - The node object or expression string for the step.
+  - `descriptionOrOptions` {Object|string} - Options object or description string.
+  - `importance` {number} - Importance level (0-2) if using string description.
+- **Returns:** `number` The index of the added step.
+
+---
+
+#### `getCurrentEquation()`
+Gets the last equation in the sequence (the current working equation).
+- **Returns:** `omdEquationNode|null` The last equation, or null if no equations exist.
+
+---
+
+#### `getCurrentStep()`
+Gets the current step node based on `currentStepIndex`.
+- **Returns:** `omdNode|null` The current step node.
+
+---
+
+#### `applyEquationOperation(value, operation)`
+Applies a specified operation to the current equation and adds the result as a new step.
+
+```javascript
+sequence.applyEquationOperation(4, 'subtract'); // Subtract 4 from both sides
+sequence.applyEquationOperation(2, 'divide');   // Divide both sides by 2
+```
+- **Parameters:**
+  - `value` {number|string} - The constant value or expression string to apply.
+  - `operation` {string} - The operation: 'add', 'subtract', 'multiply', or 'divide'.
+- **Returns:** `omdEquationSequenceNode` Returns this sequence for chaining.
+
+---
+
+#### `setFilterLevel(level)`
+Sets the filter level for visible steps in the sequence.
+
+```javascript
+sequence.setFilterLevel(0); // Show only major steps
+sequence.setFilterLevel(1); // Show only intermediate steps
+```
+- **Parameters:**
+  - `level` {number} - The stepMark level to show (default: 0 for major steps).
+
+---
+
+#### `setFilterLevels(levels)`
+Sets multiple filter levels for visible steps.
+
+```javascript
+sequence.setFilterLevels([0, 1]); // Show major and intermediate steps
+```
+- **Parameters:**
+  - `levels` {Array<number>} - Array of stepMark levels to show.
+
+---
+
+#### `updateStepsVisibility(filterFunction)`
+Updates the visibility of steps based on a filter function.
+
+```javascript
+sequence.updateStepsVisibility(step => step.stepMark <= 1); // Show steps with importance 0 or 1
+```
+- **Parameters:**
+  - `filterFunction` {Function} - Function that returns true for visible steps.
+
+---
+
+#### `recordSimplificationHistory(name, affectedNodes, message, metadata)`
+Records a simplification step in the history.
+
+```javascript
+sequence.recordSimplificationHistory(
+    'Combine Like Terms',
+    ['node1', 'node2'],
+    'Combined 2x and 3x to get 5x',
+    { ruleType: 'arithmetic' }
+);
+```
+- **Parameters:**
+  - `name` {string} - Name of the simplification rule.
+  - `affectedNodes` {Array<string>} - Array of node IDs affected.
+  - `message` {string} - Human-readable description.
+  - `metadata` {Object} - Additional metadata (optional).
+
+---
+
+#### `getSimplificationHistory()`
+Gets the complete simplification history for this sequence.
+- **Returns:** `Array<Object>` Array of simplification history entries.
+
+---
+
+#### `clearSimplificationHistory()`
+Clears the simplification history.
+
+---
+
+#### `rebuildNodeMap()`
+Rebuilds the internal node map used for tracking all nodes in the sequence.
+
+---
+
+#### `findAllNodes()`
+Finds all nodes contained within this sequence.
+- **Returns:** `Array<omdNode>` Array of all contained nodes.
+
+---
+
+#### `clear()`
+Clears all steps from the sequence.
+
+```javascript
+sequence.clear(); // Removes all steps and resets the sequence
+```
+
+---
+
+#### `clone()`
+Creates a deep clone of the sequence node.
+- **Returns:** `omdEquationSequenceNode` A new, identical instance.
+
+---
+
+#### `toString()`
+Converts the entire sequence to a multi-line string.
+- **Returns:** `string` Multi-line string representation of all steps.
+
+---
+
+#### `setFontSize(fontSize)`
+Sets the font size for the sequence and propagates to all steps.
+- **Parameters:**
+  - `fontSize` {number} - The new font size.
+
+### Static Properties
+
+#### `OPERATION_MAP`
+Maps operation names to equation methods.
+
+```javascript
+{
+    'add': 'addToBothSides',
+    'subtract': 'subtractFromBothSides',
+    'multiply': 'multiplyBothSides',
+    'divide': 'divideBothSides'
+}
+```
+
+### Example Usage
+
+```javascript
+// Create a sequence from equation strings
+const sequence = omdEquationSequenceNode.fromStringArray([
+    '2x + 4 = 10'
+]);
+
+// Add steps using operations
+sequence.applyEquationOperation(4, 'subtract')  // 2x + 4 - 4 = 10 - 4 → 2x = 6
+        .applyEquationOperation(2, 'divide');   // 2x ÷ 2 = 6 ÷ 2 → x = 3
+
+// Filter to show only major steps
+sequence.setFilterLevel(0);
+
+// Add a custom step with description
+const finalStep = omdEquationNode.fromString('x = 3');
+sequence.addStep(finalStep, {
+    description: 'Solution found',
+    stepMark: 0
+});
+
+// Get the solution
+console.log(sequence.getCurrentEquation().toString()); // "x = 3"
+
+// View the complete sequence
+console.log(sequence.toString());
+```
+
+### Advanced Example: Step Filtering
+
+```javascript
+const sequence = new omdEquationSequenceNode([]);
+
+// Add steps with different importance levels
+sequence.addStep('2x + 4 = 10', 'Original equation', 0);        // Major step
+sequence.addStep('2x + 4 - 4 = 10 - 4', 'Subtract 4', 1);     // Intermediate step  
+sequence.addStep('2x = 6', 'Simplified', 0);                    // Major step
+sequence.addStep('2x ÷ 2 = 6 ÷ 2', 'Divide by 2', 1);        // Intermediate step
+sequence.addStep('x = 3', 'Final answer', 0);                   // Major step
+
+// Show only major steps (0)
+sequence.setFilterLevel(0); // Shows: 2x + 4 = 10, 2x = 6, x = 3
+
+// Show major and intermediate steps
+sequence.setFilterLevels([0, 1]); // Shows all steps
+
+// Custom filtering
+sequence.updateStepsVisibility(step => step.stepMark === 0); // Only major steps
+```
+
+### See Also
+
+- [`omdEquationNode`](./omdEquationNode.md) - Individual equation representation.
+- [`omdStepVisualizer`](./omdStepVisualizer.md) - Visual step tracker extending this class.
+- [`omdOperationDisplayNode`](./omdOperationDisplayNode.md) - For displaying operation steps.
+- [`omdNode`](./omdNode.md) - The base class for all nodes.