@teachinglab/omd 0.1.0

package/docs/api/omdEquationStack.md

@@ -0,0 +1,139 @@
+
+# omdEquationStack
+
+A renderable component that bundles a sequence of mathematical equations with optional UI controls (toolbar). It extends `jsvgGroup` and acts as a node that can be rendered by an `omdDisplay`.
+
+## Class: `omdEquationStack extends jsvgGroup`
+
+```js
+import { omdEquationStack } from './omd/core/omdEquationStack.js';
+```
+
+## Constructor
+
+```js
+new omdEquationStack(steps = [], options = {})
+```
+- `steps` (`Array<omdNode>`): Initial array of equation steps (default: empty array)
+- `options` (`Object`): Configuration options:
+  - `toolbar` (`boolean`): If `true`, creates a toolbar for equation operations (default: `false`)
+  - `stepVisualizer` (`boolean`): If `true`, creates a sequence with step visualization (default: `false`)
+
+
+## Properties
+
+- `sequence` (`omdEquationSequenceNode` | `omdStepVisualizer`): The underlying sequence component
+- `toolbar` (`omdToolbar` | `undefined`): The toolbar component (if enabled)
+- `layoutGroup` (`jsvgLayoutGroup`): Layout container for sequence and toolbar
+- `options` (`Object`): Configuration options passed to constructor
+
+## Methods
+
+### `updateLayout()`
+Updates the layout and positioning of internal components. Centers the toolbar under the equation stack if their widths differ.
+
+### `getSequence()`
+Returns the underlying sequence instance.
+- **Returns:** `omdEquationSequenceNode` | `omdStepVisualizer`
+
+### `getToolbar()`
+Returns the toolbar instance, if one was created.
+- **Returns:** `omdToolbar` | `undefined`
+
+
+## Usage
+
+The `omdEquationStack` component is a complete equation solving interface that combines an equation sequence with an optional toolbar. It automatically handles layout and positioning.
+
+```javascript
+import { omdDisplay } from 'omd';
+import { omdEquationStack } from 'omd';
+import { omdEquationNode } from 'omd';
+
+// Create display
+const container = document.getElementById('math-display');
+const display = new omdDisplay(container);
+
+// Create equation steps
+const steps = [
+    omdEquationNode.fromString('2x + 3 = 11'),
+    omdEquationNode.fromString('2x = 8'),
+    omdEquationNode.fromString('x = 4')
+];
+
+// Basic equation stack with toolbar
+const stack = new omdEquationStack(steps, {
+    toolbar: true
+});
+
+// Render the stack
+display.render(stack);
+
+// Alternative: Create with step visualizer
+const stackWithVisualizer = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+display.render(stackWithVisualizer);
+```
+
+## Integration
+
+The equation stack integrates seamlessly with the step visualizer:
+
+```javascript
+import { omdEquationStack } from 'omd';
+import { omdEquationNode } from 'omd';
+import { omdDisplay } from 'omd';
+
+// Create steps for a more complex equation
+const steps = [
+    omdEquationNode.fromString('x/2 + 3 = 7'),
+    omdEquationNode.fromString('x/2 = 4'),
+    omdEquationNode.fromString('x = 8')
+];
+
+// Enable step visualizer with highlighting
+const stack = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+// Render in display
+const container = document.getElementById('equation-display');
+const display = new omdDisplay(container);
+display.render(stack);
+
+// Access the visualizer for programmatic control
+const visualizer = stack.getSequence();
+// visualizer.nextStep(); // Progress through solution steps if interactive
+```
+
+## Layout Behavior
+
+The equation stack automatically manages its internal layout:
+- The sequence is positioned at the top
+- The toolbar (if present) is centered below the sequence
+- Layout updates automatically when content changes
+
+```javascript
+// Create a stack and let it handle layout automatically
+const stack = new omdEquationStack(steps, { toolbar: true });
+
+// Manual layout update (rarely needed)
+stack.updateLayout();
+
+// Access components
+const sequence = stack.getSequence();
+const toolbar = stack.getToolbar();
+```
+
+---
+
+### See Also
+
+- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
+- [`omdStepVisualizer`](./omdStepVisualizer.md)
+- [`omdToolbar`](./omdToolbar.md)
+- [`jsvgGroup`](../../jsvg/jsvg.js)

package/docs/api/omdFunctionNode.md

@@ -0,0 +1,141 @@
+
+# omdFunctionNode
+
+Represents a mathematical function call, such as `sin(x)`, `sqrt(9)`, or `log(x, 10)`. Handles rendering of the function name, its arguments, and parentheses, and supports evaluation and conversion to math.js AST.
+
+## Class: `omdFunctionNode extends omdNode`
+
+```javascript
+import { omdFunctionNode } from './omd/nodes/omdFunctionNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdFunctionNode(astNodeData)
+```
+
+**Parameters:**
+- `astNodeData` {Object} - The math.js AST node for the function, which should contain:
+  - `fn.name` or `name`: The name of the function (e.g., "sin").
+  - `args`: An array of AST nodes for the function's arguments.
+
+
+### Static Methods
+
+#### `fromString(functionString)`
+
+Creates an `omdFunctionNode` from a string representation. Requires `window.math` (math.js) to be available.
+
+```javascript
+const sqrtNode = omdFunctionNode.fromString('sqrt(16)');
+```
+
+- **Parameters:**
+  - `functionString` {string} - The function call as a string.
+- **Returns:** {omdFunctionNode} A new instance of `omdFunctionNode`.
+- **Throws:** `Error` if `math.js` is not available or the string is not a valid function.
+
+
+### Example
+
+```javascript
+// Create a function node from a string
+const funcNode = omdFunctionNode.fromString('log(100, 10)');
+
+// Set its font size and render it
+funcNode.setFontSize(32);
+funcNode.initialize(); // Computes dimensions and layout
+
+// Evaluate the function
+const result = funcNode.evaluate();
+console.log(result); // Output: 2
+
+// Add it to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(funcNode);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class for all nodes.
+- [`omdConstantNode`](./omdConstantNode.md) - For numeric arguments.
+- [`omdVariableNode`](./omdVariableNode.md) - For variable arguments.
+- [`jsvgTextLine`](../../jsvg/jsvgComponents.js) - For SVG text rendering.
+Evaluates the function by first evaluating its arguments and then applying the function to the results. Uses `math.js` if available, otherwise falls back to standard JavaScript `Math` functions for common cases.
+
+- **Parameters:**
+  - `variables` {Object} - A map of variable names to their numeric values (e.g., `{ x: 2 }`).
+- **Returns:** `number` - The result of the function evaluation.
+- **Throws:** `Error` if the function is unknown or cannot be evaluated.
+
+---
+
+#### `simplify()`
+
+Delegates to the central simplification engine to simplify the function and its arguments.
+
+- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
+
+---
+
+#### `clone()`
+
+Creates a deep, structural clone of the function node, including all its argument nodes and SVG elements. The clone's provenance array is updated to include the original node's ID.
+
+- **Returns:** {omdFunctionNode} A new, identical instance of the function node.
+
+---
+
+#### `toMathJSNode()`
+
+Converts the node back into its math.js AST representation, including a `clone` method for compatibility.
+
+- **Returns:** `Object` - A math.js-compatible AST node.
+
+---
+
+#### `toString()`
+
+Converts the function node to its string representation.
+
+- **Returns:** `string` - The function as a string, e.g., `"sqrt(x^2)"`.
+
+---
+
+#### `highlightAll()` / `unhighlightAll()`
+
+Highlights or unhighlights the function node and all its arguments.
+
+---
+
+#### `computeDimensions()` / `updateLayout()`
+
+Calculates and updates the layout and dimensions of the function node and its children.
+
+### Example
+
+```javascript
+// Create a function node from a string
+const funcNode = omdFunctionNode.fromString('log(100, 10)');
+
+// Set its font size and render it
+funcNode.setFontSize(32);
+funcNode.initialize(); // Computes dimensions and layout
+
+// Evaluate the function
+const result = funcNode.evaluate();
+console.log(result); // Output: 2
+
+// Add it to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(funcNode);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class for all nodes.
+- [`omdConstantNode`](./omdConstantNode.md) - For numeric arguments.
+- [`omdVariableNode`](./omdVariableNode.md) - For variable arguments.

package/docs/api/omdGroupNode.md

@@ -0,0 +1,182 @@
+
+Represents a single grouping symbol, such as `(` or `)`, as a leaf node in the expression tree. This node is typically used for visual representation.
+
+## Class: `omdGroupNode extends omdLeafNode`
+
+```javascript
+import { omdGroupNode } from './omd/nodes/omdGroupNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdGroupNode(nodeData)
+```
+
+**Parameters:**
+
+**Description:**
+Creates a leaf node that visually represents a grouping symbol.
+
+### Properties
+
+Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
+
+#### `symbol`
+
+#### `type`
+
+#### `textElement`
+
+### Methods
+
+Inherits all methods from [`omdLeafNode`](./omdLeafNode.md), plus:
+
+#### `parseSymbol(nodeData)`
+Internal method to extract symbol from input.
+
+
+#### `parseType()`
+Internal method to set node type.
+
+
+#### `clone()`
+Creates a clone of the group node.
+  - Same text content
+  - Original node's ID added to provenance array
+
+
+#### `computeDimensions()`
+Calculates node dimensions based on text content.
+Does NOT add padding, unlike other leaf nodes.
+Overrides base class method.
+
+
+#### `updateLayout()`
+Updates the position of the node.
+Overrides base class method.
+
+
+#### `toMathJSNode()`
+Converts to math.js AST format.
+  - `type`: "SymbolNode"
+  - `name`: The grouping symbol
+
+### Examples
+
+```javascript
+// Create grouping symbols
+const leftParen = new omdGroupNode('(');
+const rightParen = new omdGroupNode(')');
+const leftBracket = new omdGroupNode('[');
+
+// Render a symbol
+const node = new omdGroupNode('(');
+node.setFontSize(24);
+node.computeDimensions(); // Calculate size (no padding)
+node.updateLayout(); // Position the text element
+```
+
+### See Also
+
+# omdGroupNode
+
+Represents a single grouping symbol, such as `(` or `)`, as a leaf node in the expression tree. This node is typically used for visual representation.
+
+## Class: `omdGroupNode extends omdLeafNode`
+
+```javascript
+import { omdGroupNode } from './omd/nodes/omdGroupNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdGroupNode(nodeData)
+```
+
+**Parameters:**
+- `nodeData` {string} - The grouping symbol character to display
+
+**Description:**
+Creates a leaf node that visually represents a grouping symbol.
+
+### Properties
+
+Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
+
+#### `symbol`
+- **Type:** string
+- **Description:** The grouping symbol character (e.g., '(' or ')')
+
+#### `type`
+- **Type:** string
+- **Description:** Always "parenthesis"
+
+#### `textElement`
+- **Type:** jsvgTextLine
+- **Description:** The SVG text element displaying the symbol
+
+### Methods
+
+Inherits all methods from [`omdLeafNode`](./omdLeafNode.md), plus:
+
+#### `parseSymbol(nodeData)`
+Internal method to extract symbol from input.
+- **Returns:** string - The input symbol unchanged
+
+---
+
+#### `parseType()`
+Internal method to set node type.
+- **Returns:** "parenthesis"
+
+---
+
+#### `clone()`
+Creates a clone of the group node.
+- **Returns:** omdGroupNode - A new instance with:
+  - Same text content
+  - Original node's ID added to provenance array
+
+---
+
+#### `computeDimensions()`
+Calculates node dimensions based on text content.
+Does NOT add padding, unlike other leaf nodes.
+Overrides base class method.
+
+---
+
+#### `updateLayout()`
+Updates the position of the node.
+Overrides base class method.
+
+---
+
+#### `toMathJSNode()`
+Converts to math.js AST format.
+- **Returns:** Object - A math.js-compatible AST node with:
+  - `type`: "SymbolNode"
+  - `name`: The grouping symbol
+
+### Example
+
+```javascript
+// Create grouping symbols
+const leftParen = new omdGroupNode('(');
+const rightParen = new omdGroupNode(')');
+const leftBracket = new omdGroupNode('[');
+
+// Render a symbol
+const node = new omdGroupNode('(');
+node.setFontSize(24);
+node.computeDimensions(); // Calculate size (no padding)
+node.updateLayout(); // Position the text element
+```
+
+### See Also
+
+- [omdLeafNode](./omdLeafNode.md) - Parent class
+- [omdNode](./omdNode.md) - Base class
+- [omdParenthesisNode](./omdParenthesisNode.md) - For complete parenthetical expressions

package/docs/api/omdHelpers.md

@@ -0,0 +1,96 @@
+
+# omdHelpers
+
+`omdHelpers` is a collection of convenience functions designed to simplify common tasks when working with the OMD library. These helpers abstract away underlying complexities, making it easier to create and manipulate mathematical expressions and visualizations.
+
+## Overview
+
+The `omdHelpers` object is exported from the main `omd/index.js` entry point, making its functions readily available for use in your project.
+
+## Functions
+
+### `createNodeFromExpression(expression, mathjs)`
+
+Creates an `omdNode` instance from a string representation of a mathematical expression. This function parses the expression using math.js and instantiates the appropriate `omdNode` subclass.
+
+- **Parameters:**
+    - `expression` {string} - The mathematical expression as a string (e.g., `"x^2 + 2x + 1"`).
+    - `mathjs` {object} - The math.js instance to use for parsing the expression.
+- **Returns:** {omdNode} The root `omdNode` of the created expression tree.
+
+```javascript
+import { omdHelpers } from 'omd-library';
+import * as math from 'mathjs';
+
+const expressionNode = omdHelpers.createNodeFromExpression('2x + 5', math);
+// expressionNode will be an instance of omdBinaryExpressionNode or another omdNode subclass
+```
+
+---
+
+### `createEquation(equationString)`
+
+Creates an `omdEquationNode` instance from a string representation of an equation. This is a specialized helper for equations, ensuring proper parsing and node creation.
+
+- **Parameters:**
+    - `equationString` {string} - The equation as a string (e.g., `"x + 2 = 5"`).
+- **Returns:** {omdEquationNode} The created `omdEquationNode`.
+
+```javascript
+import { omdHelpers } from 'omd-library';
+
+const equation = omdHelpers.createEquation('3y - 7 = 14');
+// equation will be an instance of omdEquationNode
+```
+
+---
+
+### `createStepVisualizer(equationStrings)`
+
+Creates an `omdStepVisualizer` instance from an array of equation strings. This is useful for quickly setting up a step-by-step solution display.
+
+- **Parameters:**
+    - `equationStrings` {Array<string>} - An array of strings, where each string represents an equation step (e.g., `["2x = 10", "x = 5"]`).
+- **Returns:** {omdStepVisualizer} The created `omdStepVisualizer` instance.
+
+```javascript
+import { omdHelpers } from 'omd-library';
+
+const steps = [
+    '4x + 8 = 20',
+    '4x = 12',
+    'x = 3'
+];
+const visualizer = omdHelpers.createStepVisualizer(steps);
+// visualizer will be an instance of omdStepVisualizer
+```
+
+## Example Usage
+
+```javascript
+import { omdDisplay, omdHelpers } from 'omd-library';
+import * as math from 'mathjs';
+
+// Get a container element (assuming it exists in your HTML)
+const container = document.getElementById('math-display-area');
+
+// Create an expression node using a helper
+const expression = omdHelpers.createNodeFromExpression('a^2 + b^2', math);
+
+// Create an equation using a helper
+const equation = omdHelpers.createEquation('E = mc^2');
+
+// Create a step visualizer using a helper
+const solutionSteps = [
+    'x + 5 = 10',
+    'x = 5'
+];
+const stepVisualizer = omdHelpers.createStepVisualizer(solutionSteps);
+
+// You can then render these nodes using omdDisplay or omdCanvas
+const display = new omdDisplay(container);
+display.render(expression);
+
+// Or for the step visualizer
+// display.render(stepVisualizer);
+```