@teachinglab/omd 0.3.0 → 0.3.2

package/docs/api/omdSimplification.md

@@ -1,79 +1,79 @@
-# 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).
+# 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,144 +1,144 @@
-# 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.
+# 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.