@teachinglab/omd 0.1.0

package/docs/api/omdLeafNode.md

@@ -0,0 +1,163 @@
+
+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

package/docs/api/omdNode.md

@@ -0,0 +1,101 @@
+# 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.

package/docs/api/omdOperationDisplayNode.md

@@ -0,0 +1,139 @@
+# 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 

package/docs/api/omdOperatorNode.md

@@ -0,0 +1,127 @@
+# 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
+
+``` 

package/docs/api/omdParenthesisNode.md

@@ -0,0 +1,122 @@
+# omdParenthesisNode
+
+Represents a parenthetical grouping in a mathematical expression, such as `(x + 2)`. This node is crucial for enforcing the correct order of operations.
+
+## Class: `omdParenthesisNode extends omdNode`
+
+```javascript
+import { omdParenthesisNode } from './omd/nodes/omdParenthesisNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdParenthesisNode(astNodeData)
+```
+
+**Parameters:**
+- `astNodeData` {Object} - The math.js AST node, which must have a `content` property containing the AST for the inner expression.
+
+### Static Methods
+
+#### `fromString(expressionString)`
+
+Creates an `omdParenthesisNode` from a string.
+
+```javascript
+const parenNode = omdParenthesisNode.fromString('(2 * x)');
+```
+
+- **Parameters:**
+  - `expressionString` {string} - The expression, which must be enclosed in parentheses.
+- **Returns:** {omdParenthesisNode} A new instance.
+- **Throws:** `Error` if `math.js` is not available or the string is not a valid parenthesized expression.
+
+### Properties
+
+Inherits properties from [`omdNode`](./omdNode.md), plus:
+
+#### `expression`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the expression inside the parentheses.
+
+### Methods
+
+Inherits methods from [`omdNode`](./omdNode.md). Key methods include:
+
+#### `evaluate(variables)`
+
+Evaluates the inner expression.
+- **Parameters:**
+  - `variables` {Object} - A map of variable names to their numeric values.
+- **Returns:** `number` - The result of the inner expression's evaluation.
+
+---
+
+#### `simplify()`
+
+Delegates to the central simplification engine to simplify the inner expression. The engine may also remove unnecessary parentheses.
+
+- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
+
+---
+
+#### `isNecessary()`
+
+Checks if the parentheses are mathematically necessary to maintain the order of operations, based on the parent node's context.
+
+- **Returns:** `boolean` - `true` if the parentheses are required, `false` otherwise.
+
+---
+
+#### `isConstant()`
+
+Checks if the inner expression is a constant.
+- **Returns:** `boolean`.
+
+---
+
+#### `getValue()`
+
+Returns the numeric value of the inner expression, if it is constant.
+- **Returns:** `number`.
+
+---
+
+#### `toMathJSNode()`
+
+Converts the node back into its math.js AST representation.
+- **Returns:** `Object` - A math.js `ParenthesisNode`.
+
+---
+
+#### `toString()`
+
+Converts the node to its string representation, including the parentheses.
+- **Returns:** `string` - e.g., `"(x + 2)"`.
+
+### Example
+
+```javascript
+// Create a node representing (x + 2)
+const innerExpressionAst = math.parse('x + 2');
+const parenNode = new omdParenthesisNode({ content: innerExpressionAst });
+
+// Set font size and render
+parenNode.setFontSize(28);
+parenNode.initialize();
+
+// The simplification engine might remove these parentheses if the context allows.
+const simplified = parenNode.simplify();
+
+// Add to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(parenNode);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class.
+- [`omdGroupNode`](./omdGroupNode.md) - The class used to render the individual `(` and `)` symbols.
+- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - A common type for the inner expression.