@teachinglab/omd 0.1.4 → 0.1.5

package/docs/api/omdSimplification.md

@@ -1,110 +1,79 @@
-# omdSimplification
-
-Core module that provides the main entry points for expression simplification.
-
-## Functions
-
-
-### `simplifyExpression(rootNode)`
-
-Simplifies an entire mathematical expression tree by repeatedly applying simplification rules.
-
-**Parameters:**
-- `rootNode` (`omdNode`): The root node of the expression to simplify.
-
-**Returns:** `{ foldedCount: number, newRoot: omdNode }`
-  - `foldedCount`: Number of simplifications applied.
-  - `newRoot`: The simplified expression tree (fresh clone if any simplifications occurred).
-
-**Notes:**
-- Limited to 50 iterations to prevent infinite loops.
-- Preserves font size from the original node.
-- Handles errors gracefully by returning the original node if an error occurs.
-
-**Example:**
-```javascript
-import { simplifyExpression } from './omd/simplification/omdSimplification.js';
-
-const result = simplifyExpression(node);
-console.log(result.newRoot.toString());
-console.log(`Applied ${result.foldedCount} simplifications`);
-```
-
-
-### `simplifyStep(rootNode)`
-
-Applies a single simplification step to the expression tree.
-
-**Parameters:**
-- `rootNode` (`omdNode`): The root node of the expression.
-
-**Returns:** `{ foldedCount: number, newRoot: omdNode, historyEntry: object|null }`
-  - `foldedCount`: 1 if a simplification was applied, 0 otherwise.
-  - `newRoot`: The expression tree after applying the step.
-  - `historyEntry`: Object describing the applied simplification, or `null` if none.
-
-**Notes:**
-- Only applies the first matching rule found.
-- Preserves font size from the original node.
-- Handles errors gracefully by returning the original node if an error occurs.
-
-**Example:**
-```javascript
-import { simplifyStep } from './omd/simplification/omdSimplification.js';
-
-const stepResult = simplifyStep(node);
-if (stepResult.historyEntry) {
-  console.log('Applied:', stepResult.historyEntry);
-}
-```
-
-
-### `findSimplificationOpportunities(rootNode)`
-
-Finds all possible simplification opportunities in an expression tree.
-
-**Parameters:**
-- `rootNode` (`omdNode`): The root node to search.
-
-**Returns:** `Array<{ node: omdNode, rule: object, ruleData: object }>`
-  - `node`: The node where a rule can be applied.
-  - `rule`: The applicable rule.
-  - `ruleData`: Data needed to apply the rule.
-
-**Notes:**
-- Uses depth-first traversal.
-- Skips already visited nodes.
-- Only checks rules relevant to each node type.
-- Stops after finding the first applicable rule for each node.
-
-
-### Debug Functions
-
-> **Note:** The following functions are intended for development and debugging, not for production use.
-
-#### `getAvailableRulesForNode(node)`
-
-Lists all rules that could potentially apply to a node.
-
-**Parameters:**
-- `node` (`omdNode`): The node to check.
-
-**Returns:** `Array<string>` - Array of rule names.
-
-#### `getApplicableRulesForNode(node)`
-
-Lists rules that can actually be applied to a node.
-
-**Parameters:**
-- `node` (`omdNode`): The node to check.
-
-**Returns:** `Array<string>` - Array of applicable rule names.
-
-**Notes:**
-- Handles errors gracefully by skipping failed rule checks.
-
-## See Also
-
-- [Simplification Rules](./simplificationRules.md)
-- [Simplification Engine](./simplificationEngine.md)
-- [Configuration Options](./configuration-options.md) 
+# omdSimplification
+
+This module provides the core logic for simplifying mathematical expression trees within the OMD library. It defines functions for applying simplification rules, finding opportunities for simplification, and managing the simplification process.
+
+## Functions
+
+### `simplifyExpression(rootNode)`
+
+Simplifies an entire mathematical expression tree by repeatedly applying simplification rules until no further simplifications are possible or a maximum iteration limit is reached. This function ensures that the resulting expression is in its most simplified form.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression tree to simplify.
+-   **Returns**: `{ foldedCount: number, newRoot: omdNode }`
+    -   `foldedCount`: The total number of individual simplifications applied across all iterations.
+    -   `newRoot`: The simplified expression tree. This is a fresh clone of the final simplified state, with its font size preserved from the original `rootNode`.
+
+**Notes:**
+
+-   A maximum of `50` iterations is performed to prevent potential infinite loops.
+-   Handles errors gracefully; if an error occurs during simplification, the original node is returned.
+
+### `simplifyStep(rootNode)`
+
+Applies a single simplification step to the expression tree. This function finds the first applicable simplification rule and applies it, returning the result.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression to simplify.
+-   **Returns**: `{ foldedCount: number, newRoot: omdNode, historyEntry: object | null }`
+    -   `foldedCount`: `1` if a simplification was applied, `0` otherwise.
+    -   `newRoot`: The expression tree after applying the single step. This will be a new `omdNode` instance if a simplification occurred.
+    -   `historyEntry`: An object describing the applied simplification (e.g., rule name, affected nodes, message), or `null` if no simplification was applied.
+
+**Notes:**
+
+-   Only the first matching rule found is applied in a single step.
+-   Preserves the font size from the original node.
+-   Handles errors gracefully; if an error occurs during rule application, the original node is returned.
+
+### `findSimplificationOpportunities(rootNode)`
+
+Traverses the expression tree (depth-first) to find all possible simplification opportunities. It identifies nodes where a simplification rule can be applied.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression tree to search.
+-   **Returns**: `Array<{ node: omdNode, rule: object, ruleData: object }>` - An array of objects, where each object represents a simplification opportunity:
+    -   `node`: The `omdNode` instance where a rule can be applied.
+    -   `rule`: The simplification rule object that can be applied.
+    -   `ruleData`: Data needed by the rule's `apply` method.
+
+**Notes:**
+
+-   Uses a `visitedNodes` set to prevent infinite loops in cyclic graphs (though expression trees are typically acyclic).
+-   Only checks rules relevant to each node type, optimizing performance.
+-   For each node, it stops after finding the first applicable rule.
+
+### `getAvailableRulesForNode(node)`
+
+**Debug Function:** Lists all simplification rules that are potentially relevant to a given `omdNode`'s type, regardless of whether they can currently be applied.
+
+-   **`node`** (`omdNode`): The node to check.
+-   **Returns**: `Array<string>` - An array of rule names.
+
+### `getApplicableRulesForNode(node)`
+
+**Debug Function:** Lists simplification rules that can actually be applied to a given `omdNode` based on its current structure and values.
+
+-   **`node`** (`omdNode`): The node to check.
+-   **Returns**: `Array<string>` - An array of applicable rule names.
+
+**Notes:**
+
+-   Handles errors gracefully by skipping rule checks that might fail.
+
+## Integration with `omdNode`
+
+This module also sets the `simplifyStep` function as the global simplification handler for `omdNode` instances. This allows any `omdNode` to call its `simplify()` method, which will internally use the `simplifyStep` function defined here.
+
+## See Also
+
+-   [`Simplification Rules`](./simplificationRules.md) - Details the individual simplification rules.
+-   [`Simplification Engine`](./simplificationEngine.md) - (If applicable, for higher-level orchestration).
+-   [`Configuration Options`](./configuration-options.md) - For configuring simplification behavior.

package/docs/api/omdSqrtNode.md

@@ -1,79 +1,144 @@
-# omdSqrtNode
-
-Represents a square root node in the mathematical expression tree. Handles rendering of the radical symbol and the expression under the root.
-
-## Class: `omdSqrtNode extends omdNode`
-
-```js
-import { omdSqrtNode } from './omd/nodes/omdSqrtNode.js';
-```
-
-### Constructor
-
-```js
-new omdSqrtNode(astNodeData)
-```
-- `astNodeData` {Object}: Math.js AST node with a single argument (the radicand)
-
-### Properties
-
-Inherits all properties from [omdNode](./omdNode.md), plus:
-
-- `argument` (`omdNode`): The radicand node (expression under the root)
-- `value` (`string`): Always "sqrt"
-- `radicalPath` (`jsvgPath`): The radical symbol (√)
-- `radicalLine` (`jsvgLine`): The horizontal line above the radicand
-
-### Methods
-
-Inherits all methods from [omdNode](./omdNode.md), plus:
-
-- `toString()`: Returns string representation, e.g. `sqrt(x+1)`
-- `toMathJSNode()`: Converts to a math.js-compatible AST node
-- `evaluate(variables)`: Evaluates the square root numerically
-  - `variables` {Object}: Variable name to value mapping
-  - **Returns:** `number` (or `NaN` if radicand can't be evaluated)
-- `simplify()`: Attempts to simplify the expression (delegates to central simplification engine)
-  - **Returns:** `{ success, newRoot, message }`
-- `clone()`: Deep clone of the node
-- `highlightAll()`, `unhighlightAll()`: Recursively highlight/unhighlight this node and its argument
-- `toPowerForm()`: Returns an equivalent `omdPowerNode` (x^(1/2)), or `null` if no argument
-
-#### Static Methods
-
-- `fromString(expressionString)`: Create a sqrt node from a string (must be a sqrt function)
-  - `expressionString` {string}
-  - **Returns:** `omdSqrtNode`
-  - **Throws:** Error if not a sqrt function or if math.js is not available
-
-### Example
-
-```js
-import { omdSqrtNode } from './omd/nodes/omdSqrtNode.js';
-
-// Create from AST
-const node = new omdSqrtNode({
-  type: 'FunctionNode',
-  fn: { name: 'sqrt' },
-  args: [ { type: 'SymbolNode', name: 'x' } ]
-});
-
-// Or from string (if static method is available)
-const node2 = omdSqrtNode.fromString('sqrt(x+1)');
-
-// Render and layout
-node.setFontSize(24);
-node.computeDimensions();
-node.updateLayout();
-
-// Evaluate
-const val = node.evaluate({ x: 9 }); // 3
-
-// Convert to power form
-const powerNode = node.toPowerForm(); // x^(1/2)
-```
-
-### See Also
-- [omdNode](./omdNode.md) — Parent class
-- [omdPowerNode](./omdPowerNode.md) — For power form (x^(1/2))
-- [omdFunctionNode](./omdFunctionNode.md) — For other functions
+# omdSqrtNode
+
+Represents a square root node in the mathematical expression tree. It handles the rendering of the radical symbol (√) and the expression under the root (radicand), ensuring correct visual layout and mathematical behavior.
+
+## Class Definition
+
+```javascript
+export class omdSqrtNode extends omdNode
+```
+
+## Constructor
+
+### `new omdSqrtNode(astNodeData)`
+
+Creates a new `omdSqrtNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST node containing square root function information. It should have an `args` property, which is an array containing a single AST node for the radicand. The constructor also initializes the visual `radicalPath` and `radicalLine` elements.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdSqrtNode` from a string representation of a square root function. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The square root expression as a string (e.g., `"sqrt(x+1)"`).
+-   **Returns**: `omdSqrtNode` - 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 `sqrt` function.
+
+## Public Properties
+
+-   **`argument`** (`omdNode`): The node representing the radicand (the expression under the root).
+-   **`value`** (`string`): Always `"sqrt"` for this node type.
+-   **`radicalPath`** (`jsvgPath`): The SVG path element that draws the radical symbol (√).
+-   **`radicalLine`** (`jsvgLine`): The SVG line element that draws the horizontal line above the radicand.
+-   **`args`** (`Array<object>`): The raw AST arguments passed to the constructor.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the square root node. It scales down the font size of the `argument`, computes its dimensions, and then determines the overall width (radical width + spacing + argument width) and height (argument height + extra height for the radical top).
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the square root node. It positions the `argument` node, then draws and positions the `radicalPath` and `radicalLine` elements relative to the argument, ensuring the radical symbol correctly encloses the radicand.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the square root node, including its `argument` node and visual elements. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdSqrtNode` - A new, identical instance of the square root node.
+
+### `highlightAll()`
+
+Applies a highlight to the square root node itself and recursively highlights its `argument` node.
+
+### `unhighlightAll()`
+
+Removes the highlight from the square root node and recursively unhighlights its `argument` node.
+
+### `toMathJSNode()`
+
+Converts the `omdSqrtNode` back into its math.js AST representation. It creates a `FunctionNode` with `fn: 'sqrt'` and the converted `argument` AST.
+
+-   **Returns**: `object` - A math.js `FunctionNode` for the square root operation. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the square root node to its string representation (e.g., `"sqrt(x+1)"`).
+
+-   **Returns**: `string`.
+
+### `evaluate(variables)`
+
+Evaluates the square root expression. It evaluates the `argument` and then calculates its square root.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The evaluated square root, or `NaN` if the radicand cannot be evaluated or is negative.
+
+### `isSquareRoot()`
+
+Checks if the node represents a square root. Always returns `true` for `omdSqrtNode`.
+
+-   **Returns**: `boolean`.
+
+### `isCubeRoot()`
+
+Checks if the node represents a cube root. Always returns `false` for `omdSqrtNode`.
+
+-   **Returns**: `boolean`.
+
+### `toPowerForm()`
+
+Converts the square root node into an equivalent `omdPowerNode` representation (e.g., `sqrt(x)` becomes `x^(0.5)`).
+
+-   **Returns**: `omdPowerNode` - The equivalent power expression, or `null` if the `argument` is missing.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"sqrt"`.
+-   **`createArgumentNode()`**: Creates an `omdNode` instance for the radicand from its AST, and adds it as a child.
+-   **`createRadicalElements()`**: Creates and initializes the `jsvgPath` for the radical symbol and the `jsvgLine` for the horizontal bar, adding them as children.
+
+## Example
+
+```javascript
+import { omdSqrtNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create from AST
+const node = new omdSqrtNode({
+  type: 'FunctionNode',
+  fn: { name: 'sqrt' },
+  args: [ { type: 'SymbolNode', name: 'x' } ]
+});
+
+// Or from string
+const node2 = omdSqrtNode.fromString('sqrt(x+1)');
+
+// Render and layout
+node.setFontSize(24);
+node.initialize();
+
+// Evaluate
+const val = node.evaluate({ x: 9 }); // 3
+
+// Convert to power form
+const powerNode = node.toPowerForm(); // x^(1/2)
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class.
+-   [`omdPowerNode`](./omdPowerNode.md) - For power form (e.g., `x^(1/2)`).
+-   [`omdFunctionNode`](./omdFunctionNode.md) - For other mathematical functions.