@teachinglab/omd 0.1.3 → 0.1.5

package/docs/api/omdEquationStack.md

@@ -1,87 +1,141 @@
-
-# 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:
-
+# 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 Definition
+
+```js
+import { omdEquationStack } from './omd/core/omdEquationStack.js';
+```
+
+## Constructor
+
+### `new omdEquationStack(steps, options)`
+
+Creates a new `omdEquationStack` instance.
+
+-   **`steps`** (`Array<omdNode>`, optional): An initial array of equation steps. Default: empty array.
+-   **`options`** (`object`, optional): Configuration options:
+    -   **`toolbar`** (`boolean` | `object`): If `true`, creates a toolbar for equation operations. Can also be an object for more granular control:
+        -   `enabled` (`boolean`): Whether the toolbar is enabled. Default: `false`.
+        -   `position` (`string`): Where the toolbar should be positioned (`'bottom'`, `'overlay-bottom'`). Default: `'bottom'`.
+        -   `showUndoButton` (`boolean`): Whether to show an undo button. Default: `false`.
+        -   `onUndo` (`function`): Custom undo handler. If not provided, it attempts to call `window.onOMDToolbarUndo`.
+        -   `overlayPadding` (`number`): Padding from the bottom edge when `position` is `'overlay-bottom'`. Default: `34`.
+    -   **`stepVisualizer`** (`boolean`): If `true`, the underlying sequence will be an `omdStepVisualizer` instead of a plain `omdEquationSequenceNode`. Default: `false`.
+    -   **`styling`** (`object`): Styling options for the equation stack:
+        -   `equationBackground` (`object`): Default background style for equation steps (e.g., `{ backgroundColor: '#f0f0f0', cornerRadius: 8, pill: true }`).
+
+## Public Properties
+
+-   **`sequence`** (`omdEquationSequenceNode` | `omdStepVisualizer`): The underlying sequence component that manages the equation steps.
+-   **`toolbar`** (`omdToolbar` | `undefined`): The toolbar component instance, if enabled.
+-   **`layoutGroup`** (`jsvgLayoutGroup`): The internal layout container that arranges the sequence and toolbar vertically.
+-   **`options`** (`object`): The merged configuration options passed to the constructor.
+-   **`overlayPadding`** (`number`): The calculated padding for the toolbar when it's in an overlay position.
+
+## Public Methods
+
+### `updateLayout()`
+
+Updates the layout and positioning of internal components. This method ensures the sequence and toolbar are correctly arranged and that the toolbar is horizontally centered if it's in-flow.
+
+### `getSequence()`
+
+Returns the underlying sequence instance (either `omdEquationSequenceNode` or `omdStepVisualizer`).
+
+-   **Returns**: `omdEquationSequenceNode` | `omdStepVisualizer`.
+
+### `getToolbar()`
+
+Returns the toolbar instance, if one was created during construction.
+
+-   **Returns**: `omdToolbar` | `undefined`.
+
+### `getOverlayPadding()`
+
+Returns the padding value used for positioning the toolbar when it's in an overlay mode.
+
+-   **Returns**: `number`.
+
+### `getToolbarVisualHeight()`
+
+Returns the unscaled visual height of the toolbar's background element, if the toolbar is present.
+
+-   **Returns**: `number`.
+
+### `isToolbarOverlay()`
+
+Checks if the toolbar is configured to be overlaid at the bottom of the container.
+
+-   **Returns**: `boolean`.
+
+### `positionToolbarOverlay(containerWidth, containerHeight, padding)`
+
+Positions the toolbar overlay at the bottom center of the container. This method is typically called by the `omdDisplay` to ensure the toolbar remains visible and correctly placed even when the main content scales.
+
+-   **`containerWidth`** (`number`): The width of the parent container.
+-   **`containerHeight`** (`number`): The height of the parent container.
+-   **`padding`** (`number`, optional): Padding from the bottom edge. Default: `16`.
+
+### `undoLastOperation()`
+
+Removes the last equation step and any preceding operation display node from the sequence. This method also triggers a re-layout and updates any associated step visualizer.
+
+-   **Returns**: `boolean` - `true` if an operation was successfully undone, `false` otherwise.
+
+## 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 and custom toolbar options
+const stackWithVisualizer = new omdEquationStack(steps, {
+    toolbar: {
+        enabled: true,
+        showUndoButton: true,
+        position: 'overlay-bottom'
+    },
+    stepVisualizer: true,
+    styling: {
+        equationBackground: {
+            backgroundColor: '#e0f7fa',
+            cornerRadius: 10,
+            pill: true
+        }
+    }
+});
+
+display.render(stackWithVisualizer);
+```
+
+## Integration
+
+The equation stack integrates seamlessly with the step visualizer:
+
 ```javascript
 import { omdEquationStack } from 'omd';
 import { omdEquationNode } from 'omd';
@@ -108,15 +162,15 @@ 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
-
+```
+
+## 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 });
@@ -127,13 +181,13 @@ 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)
+```
+
+---
+
+### See Also
+
+- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
+- [`omdStepVisualizer`](./omdStepVisualizer.md)
+- [`omdToolbar`](./omdToolbar.md)
+- [`jsvgGroup`](../../jsvg/jsvg.js)

package/docs/api/omdFunctionNode.md

@@ -1,141 +1,83 @@
-
-# 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.
+# omdFunctionNode
+
+Represents a mathematical function call, such as `sin(x)`, `sqrt(9)`, or `log(x, 10)`. This node handles the rendering of the function name, its arguments, and surrounding parentheses. It supports evaluation, simplification, and conversion to/from math.js AST.
+
+## Class Definition
+
+```javascript
+export class omdFunctionNode extends omdNode
+```
+
+## Constructor
+
+### `new omdFunctionNode(astNodeData)`
+
+Creates a new `omdFunctionNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST node for the function. It should contain:
+    -   `fn.name` or `name`: The name of the function (e.g., `"sin"`, `"log"`).
+    -   `args`: An array of AST nodes for the function's arguments.
+
+## Static Methods
+
+### `fromString(functionString)`
+
+Creates an `omdFunctionNode` from a string representation of a function call. This method requires `window.math` (math.js library) to be available globally for parsing.
+
+-   **`functionString`** (`string`): The function call as a string (e.g., `"sqrt(16)"`, `"log(100, 10)"`).
+-   **Returns**: `omdFunctionNode` - A new instance of `omdFunctionNode`.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid function call.
+
+## Public Properties
+
+-   **`functionName`** (`string`): The name of the function (e.g., `"sin"`, `"log"`).
+-   **`args`** (`Array<omdNode>`): An array of `omdNode` instances representing the arguments of the function.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the bounding box of the function node, taking into account the dimensions of the function name, arguments, and parentheses. It also sets the font sizes for the function name and arguments (arguments are typically scaled down slightly).
+
+### `updateLayout()`
+
+Positions the function name, arguments, and parentheses within the node's bounding box. It ensures proper spacing and vertical alignment of all elements.
+
+### `highlightAll()`
+
+Applies a highlight to the function node itself (its background rectangle) and recursively highlights all of its argument nodes.
+
+### `unhighlightAll()`
+
+Removes the highlight from the function node and recursively unhighlights all of its argument nodes.
+
+### `clone()`
+
+Creates a deep, structural clone of the function node, including all its argument nodes and their associated 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 `omdFunctionNode` back into its math.js AST representation. This includes converting its function name and all argument nodes.
+
+-   **Returns**: `object` - A math.js-compatible `FunctionNode` AST object.
+
+### `toString()`
+
+Converts the function node to its string representation (e.g., `"sqrt(x^2)"`, `"log(100, 10)"`).
+
+-   **Returns**: `string` - The function as a string.
+
+### `evaluate(variables)`
+
+Evaluates the function by first evaluating its arguments and then applying the function to the results. It primarily uses `window.math` (math.js) for evaluation. If `math.js` is not available, it falls back to standard JavaScript `Math` functions for common cases (e.g., `sin`, `cos`, `sqrt`).
+
+-   **`variables`** (`object`, optional): 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.
+
+## Internal Methods
+
+-   **`createTextElements()`**: Creates `jsvgTextLine` elements for the function name and parentheses.
+-   **`createArgumentNodes()`**: Iterates through the AST arguments, creates corresponding `omdNode` instances for each, and adds them as children.