@teachinglab/omd 0.1.3 → 0.1.5

package/docs/api/omdPowerNode.md

@@ -1,127 +1,132 @@
-# omdPowerNode
-
-Represents an exponentiation in a mathematical expression, such as `x^2` or `(a+b)^c`. It handles the specific layout requirements of a base and a superscripted exponent.
-
-## Class: `omdPowerNode extends omdNode`
-
-```javascript
-import { omdPowerNode } from './omd/nodes/omdPowerNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdPowerNode(ast)
-```
-
-
-**Parameters:**
-- `ast` {Object} - The math.js AST for the power operation. It must be an `OperatorNode` with `op: '^'` and an `args` array containing two elements: the base and the exponent.
-
-### Static Methods
-
-
-#### `fromString(expressionString)`
-Creates an `omdPowerNode` from a string.
-
-```javascript
-const powerNode = omdPowerNode.fromString('x^2');
-```
-- **Parameters:**
-  - `expressionString` {string} - The power expression as a string.
-- **Returns:** `omdPowerNode` A new instance.
-- **Throws:** Error if math.js is not available or the string is not a valid power expression.
-
-### Properties
-
-Inherits properties from [`omdNode`](./omdNode.md), plus:
-
-#### `base`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the base of the power operation.
-
-#### `exponent`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the exponent.
-
-### Methods
-
-Inherits methods from [`omdNode`](./omdNode.md). Key methods include:
-
-
-#### `evaluate(variables)`
-Evaluates the expression by raising the evaluated base to the power of the evaluated exponent.
-- **Parameters:**
-  - `variables` {Object} - A map of variable names to their numeric values.
-- **Returns:** `number` - The result of the exponentiation, or `NaN` if base or exponent cannot be evaluated.
-
----
-
-
-#### `simplify()`
-Delegates to the central simplification engine to simplify the base and exponent.
-- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
-- **Note:** This method is not implemented directly on `omdPowerNode`, but is available via the central simplification engine (see [omdSimplification](./omdSimplification.md)).
-
----
-
-
-#### `isSquare()`
-Checks if the exponent is the constant value `2`.
-- **Returns:** `boolean`.
-
----
-
-
-#### `isCube()`
-Checks if the exponent is the constant value `3`.
-- **Returns:** `boolean`.
-
----
-
-
-#### `getAlignmentBaseline()`
-Calculates the vertical alignment point for the node, which is determined by the baseline of its `base` expression.
-- **Returns:** `number` - The y-coordinate for alignment.
-
----
-
-
-#### `toMathJSNode()`
-Converts the node back into its math.js AST representation.
-- **Returns:** `Object` - A math.js `OperatorNode` for the power operation.
-
----
-
-
-#### `toString()`
-Converts the node to its string representation, adding parentheses where necessary to preserve order of operations.
-- **Returns:** `string` - e.g., `"(x+1)^2"`.
-
-### Example
-
-```javascript
-// Create a node representing x^2
-const ast = math.parse('x^2');
-const powerNode = new omdPowerNode(ast);
-
-// Set font size and render
-powerNode.setFontSize(32);
-powerNode.initialize();
-
-// Check properties
-console.log(powerNode.isSquare()); // true
-
-// Evaluate
-console.log(powerNode.evaluate({ x: 5 })); // 25
-
-// Add to an SVG container to display
-const svgContainer = new jsvgContainer();
-svgContainer.addChild(powerNode);
-document.body.appendChild(svgContainer.svgObject);
-```
-
-### See Also
-
-- [`omdNode`](./omdNode.md) - The base class.
-- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Can be used for complex bases or exponents.
+# omdPowerNode
+
+Represents an exponentiation in a mathematical expression, such as `x^2` or `(a+b)^c`. This node handles the specific layout requirements of a base and a superscripted exponent, ensuring correct visual hierarchy and alignment.
+
+## Class Definition
+
+```javascript
+export class omdPowerNode extends omdNode
+```
+
+## Constructor
+
+### `new omdPowerNode(ast)`
+
+Creates a new `omdPowerNode` instance.
+
+-   **`ast`** (`object`): The math.js AST for the power operation. It must be an `OperatorNode` with `op: '^'` and an `args` array containing exactly two elements: the base and the exponent. Throws an error if the AST is invalid.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdPowerNode` from a string representation of a power expression. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The power expression as a string (e.g., `"x^2"`, `"(a+b)^c"`).
+-   **Returns**: `omdPowerNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid power expression.
+
+## Public Properties
+
+-   **`base`** (`omdNode`): The node representing the base of the power operation.
+-   **`exponent`** (`omdNode`): The node representing the exponent.
+-   **`value`** (`string`): The operator symbol for power, which is `"^"`.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the power node. It computes the dimensions of the base and exponent (scaling the exponent's font size down). The total width is the sum of their widths, and the total height accounts for the base's height plus the vertical offset needed for the superscripted exponent.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the power node. It positions the `base` at the bottom of the node's bounding box to ensure space for the exponent above it. The `exponent` is then positioned to the right of the base and shifted upwards by a calculated superscript offset.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `getSuperscriptOffset()`
+
+Calculates the vertical offset (in pixels) by which the exponent should be raised above the base. This offset is a proportion of the current font size to ensure consistent scaling.
+
+-   **Returns**: `number` - The vertical offset.
+
+### `getAlignmentBaseline()`
+
+Calculates the vertical alignment point for the node. For a power node, the baseline is determined by the baseline of its `base` expression, ensuring proper alignment with other mathematical elements.
+
+-   **Overrides**: `omdNode.getAlignmentBaseline()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the power node, including its `base` and `exponent` nodes. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdPowerNode` - A new, identical instance of the power node.
+
+### `toMathJSNode()`
+
+Converts the `omdPowerNode` back into its math.js AST representation. It creates an `OperatorNode` with `op: '^'` and `fn: 'pow'`, containing the converted base and exponent ASTs.
+
+-   **Returns**: `object` - A math.js `OperatorNode` for the power operation. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the node to its string representation, adding parentheses where necessary to preserve the correct order of operations for both the base and the exponent.
+
+-   **Returns**: `string` - e.g., `"(x+1)^2"`.
+
+### `evaluate(variables)`
+
+Evaluates the power expression by raising the evaluated base to the power of the evaluated exponent. It handles cases where base or exponent might not be numerical.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The result of the exponentiation, or `NaN` if base or exponent cannot be evaluated to a number.
+
+### `isSquare()`
+
+Checks if the exponent of the power node is the constant value `2`.
+
+-   **Returns**: `boolean`.
+
+### `isCube()`
+
+Checks if the exponent of the power node is the constant value `3`.
+
+-   **Returns**: `boolean`.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"^"`.
+-   **`createOperand(ast)`**: Creates an `omdNode` instance for the base or exponent from its AST.
+
+## Example
+
+```javascript
+import { omdPowerNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create a node representing x^2
+const ast = math.parse('x^2');
+const powerNode = new omdPowerNode(ast);
+
+// Set font size and render
+powerNode.setFontSize(32);
+powerNode.initialize();
+
+// Check properties
+console.log(powerNode.isSquare()); // true
+
+// Evaluate
+console.log(powerNode.evaluate({ x: 5 })); // 25
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(powerNode);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Can be used for complex bases or exponents.

package/docs/api/omdRationalNode.md

@@ -1,128 +1,145 @@
-# omdRationalNode
-
-Represents a fraction, with a numerator and a denominator, such as `1/2` or `(x+1)/(x-1)`. It handles the distinct visual layout of a fraction, with the numerator positioned above the denominator, separated by a horizontal line.
-
-## Class: `omdRationalNode extends omdNode`
-
-```javascript
-import { omdRationalNode } from './omd/nodes/omdRationalNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdRationalNode(astNodeData)
-```
-
-**Parameters:**
-- `astNodeData` {Object} - The math.js AST for the division operation. It must be an `OperatorNode` with `op: '/'` and an `args` array containing two elements: the numerator and the denominator.
-
-### Static Methods
-
-
-#### `fromString(expressionString)`
-Creates an `omdRationalNode` from a string containing a division.
-
-```javascript
-const rationalNode = omdRationalNode.fromString('x / 2');
-```
-- **Parameters:**
-  - `expressionString` {string} - The fractional expression as a string.
-- **Returns:** `omdRationalNode` A new instance.
-- **Throws:** Error if math.js is not available or the string is not a valid division expression.
-
-### Properties
-
-Inherits properties from [`omdNode`](./omdNode.md), plus:
-
-#### `numerator`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the top part of the fraction.
-
-#### `denominator`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the bottom part of the fraction.
-
-### Methods
-
-Inherits methods from [`omdNode`](./omdNode.md). Key methods include:
-
-
-#### `evaluate(variables)`
-Evaluates the fraction by dividing the evaluated numerator by the evaluated denominator.
-- **Parameters:**
-  - `variables` {Object} - A map of variable names to their numeric values.
-- **Returns:** `number` - The result of the division.
-- **Throws:** Error if the denominator evaluates to zero.
-
----
-
-
-#### `simplify()`
-Delegates to the central simplification engine to simplify the numerator and denominator and to reduce the fraction.
-- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
-- **Note:** This method is not implemented directly on `omdRationalNode`, but is available via the central simplification engine (see [omdSimplification](./omdSimplification.md)).
-
----
-
-
-#### `reduce()`
-If the fraction is constant, reduces it to its lowest terms (e.g., `4/8` becomes `1/2`). If the new denominator is `1`, it returns an `omdConstantNode`.
-- **Returns:** `omdRationalNode | omdConstantNode` The reduced node, or a clone of the original if it's not constant.
-
----
-
-
-#### `isProper()`
-Checks if the fraction is proper (the absolute value of the numerator is less than the absolute value of the denominator). Only applies to constant fractions.
-- **Returns:** `boolean | null` - `true` if proper, `false` if improper, `null` if not constant.
-
----
-
-
-#### `getAlignmentBaseline()`
-Calculates the vertical alignment point for the node, which is the y-position of the fraction bar.
-- **Returns:** `number` - The y-coordinate for alignment.
-
----
-
-
-#### `toMathJSNode()`
-Converts the node back into its math.js AST representation.
-- **Returns:** `Object` - A math.js `OperatorNode` for division.
-
----
-
-
-#### `toString()`
-Converts the node to its string representation, adding parentheses where necessary.
-- **Returns:** `string` - e.g., `"(x + 1) / (x - 1)"`.
-
-fraction.initialize();
-document.body.appendChild(svgContainer.svgObject);
-
-### Example
-
-```javascript
-// Create a fraction from a string
-const fraction = omdRationalNode.fromString('(a+b)/(a-b)');
-
-// Set font size and render
-fraction.setFontSize(28);
-fraction.initialize();
-
-// Evaluate with given variables
-const result = fraction.evaluate({ a: 3, b: 1 });
-console.log(result); // Output: 2 (since (3+1)/(3-1) = 4/2 = 2)
-
-// Add to an SVG container to display
-const svgContainer = new jsvgContainer();
-svgContainer.addChild(fraction);
-document.body.appendChild(svgContainer.svgObject);
-```
-
-### See Also
-
-- [`omdNode`](./omdNode.md) - The base class.
-- [`omdConstantNode`](./omdConstantNode.md) - For constant numerators/denominators.
-- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For complex numerators/denominators.
+# omdRationalNode
+
+Represents a fraction, with a numerator and a denominator, such as `1/2` or `(x+1)/(x-1)`. It handles the distinct visual layout of a fraction, with the numerator positioned above the denominator, separated by a horizontal line.
+
+## Class Definition
+
+```javascript
+export class omdRationalNode extends omdNode
+```
+
+## Constructor
+
+### `new omdRationalNode(astNodeData)`
+
+Creates a new `omdRationalNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST for the division operation. It must be an `OperatorNode` with `op: '/'` and an `args` array containing two elements: the numerator and the denominator. The constructor also creates and initializes the visual `fractionLine`.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdRationalNode` from a string containing a division. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The fractional expression as a string (e.g., `"x / 2"`, `"(a+b)/(a-b)"`).
+-   **Returns**: `omdRationalNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid division expression.
+
+## Public Properties
+
+-   **`numerator`** (`omdNode`): The node representing the top part of the fraction.
+-   **`denominator`** (`omdNode`): The node representing the bottom part of the fraction.
+-   **`fractionLine`** (`jsvgLine`): The visual horizontal line separating the numerator and denominator.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the rational node. It scales down the font size of the numerator and denominator, computes their individual dimensions, and then determines the total width (maximum of numerator/denominator width plus spacing) and total height (sum of numerator, denominator, and padding for the fraction line).
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the rational node. It positions the `numerator` at the top, the `fractionLine` in the middle, and the `denominator` at the bottom, ensuring they are horizontally centered and have appropriate vertical spacing.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `getAlignmentBaseline()`
+
+Calculates the vertical alignment point for the node. For a rational node, this is the y-position of the fraction bar, which serves as the visual baseline.
+
+-   **Overrides**: `omdNode.getAlignmentBaseline()`.
+
+### `isConstant()`
+
+Checks if both the numerator and the denominator are constant numerical values.
+
+-   **Returns**: `boolean`.
+
+### `getRationalValue()`
+
+Retrieves the rational value of the node as a numerator/denominator pair. This method only works if the fraction is constant.
+
+-   **Returns**: `{ num: number, den: number }`.
+-   **Throws**: `Error` if the rational node is not constant.
+
+### `getValue()`
+
+Retrieves the numerical value of the rational node by dividing the numerator's value by the denominator's value. This method only works if the fraction is constant.
+
+-   **Returns**: `number`.
+-   **Throws**: `Error` if the rational node is not constant or if division by zero occurs.
+
+### `clone()`
+
+Creates a deep, structural clone of the rational node, including its `numerator` and `denominator` nodes. The `fractionLine` is also recreated. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdRationalNode` - A new, identical instance of the rational node.
+
+### `toMathJSNode()`
+
+Converts the `omdRationalNode` back into its math.js AST representation. It creates an `OperatorNode` with `op: '/'` and `fn: 'divide'`, containing the converted numerator and denominator ASTs.
+
+-   **Returns**: `object` - A math.js `OperatorNode` for division. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the node to its string representation, adding parentheses around the numerator and/or denominator if they are complex expressions (e.g., binary expressions) to maintain correct order of operations.
+
+-   **Returns**: `string` - e.g., `"(x + 1) / (x - 1)"`.
+
+### `evaluate(variables)`
+
+Evaluates the rational expression by evaluating the numerator and denominator and then performing the division.
+
+-   **`variables`** (`object`): A map of variable names to their values.
+-   **Returns**: `number` - The result of the division.
+-   **Throws**: `Error` if the denominator evaluates to zero.
+
+### `reduce()`
+
+If the fraction is constant, this method reduces it to its lowest terms (e.g., `4/8` becomes `1/2`). If the reduced denominator is `1`, it returns an `omdConstantNode` representing the integer value. It uses a `gcd` (greatest common divisor) helper function internally.
+
+-   **Returns**: `omdRationalNode` | `omdConstantNode` - The reduced fraction node, or an `omdConstantNode` if it simplifies to an integer.
+
+### `isProper()`
+
+Checks if the fraction is proper (the absolute value of the numerator is less than the absolute value of the denominator). This check only applies to constant fractions.
+
+-   **Returns**: `boolean` | `null` - `true` if proper, `false` if improper, `null` if the fraction is not constant.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"/"`.
+-   **`createOperand(ast)`**: Creates an `omdNode` instance for the numerator or denominator from its AST, attempting to preserve provenance.
+
+## Example
+
+```javascript
+import { omdRationalNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create a fraction from a string
+const fraction = omdRationalNode.fromString('(a+b)/(a-b)');
+
+// Set font size and render
+fraction.setFontSize(28);
+fraction.initialize();
+
+// Evaluate with given variables
+const result = fraction.evaluate({ a: 3, b: 1 });
+console.log(result); // Output: 2 (since (3+1)/(3-1) = 4/2 = 2)
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(fraction);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class.
+-   [`omdConstantNode`](./omdConstantNode.md) - For constant numerators/denominators.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For complex numerators/denominators.