@teachinglab/omd 0.6.1 → 0.6.3

package/npm-docs/api/omdEquationStack.md

@@ -1,193 +1,193 @@
-# 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';
-import { omdDisplay } from 'omd';
-
-// Create steps for a more complex equation
-const steps = [
-    omdEquationNode.fromString('x/2 + 3 = 7'),
-    omdEquationNode.fromString('x/2 = 4'),
-    omdEquationNode.fromString('x = 8')
-];
-
-// Enable step visualizer with highlighting
-const stack = new omdEquationStack(steps, {
-    toolbar: true,
-    stepVisualizer: true
-});
-
-// Render in display
-const container = document.getElementById('equation-display');
-const display = new omdDisplay(container);
-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
-
-```javascript
-// Create a stack and let it handle layout automatically
-const stack = new omdEquationStack(steps, { toolbar: true });
-
-// Manual layout update (rarely needed)
-stack.updateLayout();
-
-// Access components
-const sequence = stack.getSequence();
-const toolbar = stack.getToolbar();
-```
-
----
-
-### See Also
-
-- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
-- [`omdStepVisualizer`](./omdStepVisualizer.md)
-- [`omdToolbar`](./omdToolbar.md)
+# 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';
+import { omdDisplay } from 'omd';
+
+// Create steps for a more complex equation
+const steps = [
+    omdEquationNode.fromString('x/2 + 3 = 7'),
+    omdEquationNode.fromString('x/2 = 4'),
+    omdEquationNode.fromString('x = 8')
+];
+
+// Enable step visualizer with highlighting
+const stack = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+// Render in display
+const container = document.getElementById('equation-display');
+const display = new omdDisplay(container);
+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
+
+```javascript
+// Create a stack and let it handle layout automatically
+const stack = new omdEquationStack(steps, { toolbar: true });
+
+// Manual layout update (rarely needed)
+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)

package/npm-docs/api/omdFunctionNode.md

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