@teachinglab/omd 0.1.4 → 0.1.5

package/docs/api/omdDisplay.md

@@ -1,121 +1,87 @@
-# omdDisplay
-
-A high-level component for displaying a single mathematical expression or a series of equation steps with automatic centering and layout management.
-
-## Class: `omdDisplay`
-
-```javascript
-import { omdDisplay } from 'omd-library';
-```
-
-### Constructor
-
-```javascript
-new omdDisplay(container, options)
-```
-
-**Parameters:**
-- `container` {HTMLElement} - The DOM element where the expression will be rendered.
-- `options` {Object} (optional) - Configuration options:
-  - `fontSize` {number} - The base font size in pixels for the expression. Defaults to `32`.
-  - `centerContent` {boolean} - If `true`, the content is automatically centered within the container. Defaults to `true`.
-  - `topMargin` {number} - The top margin in pixels, used when centering content. Defaults to `40`.
-
-**Example:**
-```javascript
-const displayContainer = document.getElementById('math-display');
-const display = new omdDisplay(displayContainer, {
-    fontSize: 36,
-    topMargin: 50
-});
-```
-
-### Methods
-
-
-#### `render(expression)`
-Renders a mathematical expression or equation. If a string is provided:
-- If the string contains semicolons (`;`), it is treated as a sequence of equations and rendered as steps.
-- If the string contains an equals sign (`=`), it is treated as a single equation and wrapped in an `omdStepVisualizer`.
-- Otherwise, it is parsed as a single expression.
-
-```javascript
-display.render('x^2 + 2x + 1 = 0');
-
-// Renders a sequence of steps
-display.render('2x + 4 = 10; 2x = 6; x = 3');
-```
-- **Parameters:**
-  - `expression` {string | omdNode} - The mathematical expression string or a pre-existing `omdNode` instance.
-- **Returns:** `omdNode` The root node of the rendered content (often an `omdStepVisualizer`).
-
----
-
-#### `update(newNode)`
-
-Replaces the currently displayed node with a new one, applying the current font size and centering if enabled.
-
-```javascript
-const newNode = omdEquationNode.fromString('y = mx + b');
-display.update(newNode);
-```
-- **Parameters:**
-  - `newNode` {omdNode} - The new node to display.
-
----
-
-#### `getCurrentNode()`
-
-Returns the node currently being displayed.
-
-```javascript
-const currentNode = display.getCurrentNode();
-```
-- **Returns:** {omdNode | null} The current root node, or `null` if nothing is displayed.
-
----
-
-#### `centerNode()`
-
-Manually triggers the centering logic for the current node. This is especially useful for `omdEquationSequenceNode` instances to align them by their equals signs.
-
-```javascript
-display.centerNode();
-```
-
----
-
-#### `setFontSize(size)`
-
-Updates the font size for the currently displayed node and for any future content rendered.
-
-```javascript
-display.setFontSize(48);
-```
-- **Parameters:**
-  - `size` {number} - The new font size in pixels.
-
----
-
-#### `clear()`
-
-Removes the current expression from the display.
-
-```javascript
-display.clear();
-```
-
----
-
-#### `destroy()`
-
-Cleans up the component, removing all DOM elements and detaching the resize observer.
-
-```javascript
-display.destroy();
-```
-
-
-### See Also
-- [`omdStepVisualizer`](./omdStepVisualizer.md) - The component used to display steps.
-- [`omdEquationNode`](./omdEquationNode.md) - The node for representing equations.
+# omdDisplay
+
+A high-level component for displaying mathematical expressions or a series of equation steps. It handles rendering, automatic centering, scaling, and layout management within a given HTML container.
+
+## Class Definition
+
+```javascript
+export class omdDisplay
+```
+
+## Constructor
+
+### `new omdDisplay(container, [options])`
+
+Creates a new `omdDisplay` instance.
+
+-   **`container`** (`HTMLElement`): The DOM element where the expression will be rendered.
+-   **`options`** (`object`, optional): Configuration options:
+    -   `fontSize` (`number`): The base font size in pixels for the expression. Default: `32`.
+    -   `centerContent` (`boolean`): If `true`, the content is automatically centered within the container. Default: `true`.
+    -   `topMargin` (`number`): The top margin in pixels, used when centering content. Default: `40`.
+    -   `bottomMargin` (`number`): The bottom margin in pixels. Default: `16`.
+    -   `fitToContent` (`boolean`): If `true`, the SVG container will resize to tightly fit the content. Default: `false`.
+    -   `autoScale` (`boolean`): If `true`, content will automatically scale down to fit the container. Default: `true`.
+    -   `maxScale` (`number`): Maximum scale factor for `autoScale`. Default: `1` (no upscaling).
+    -   `edgePadding` (`number`): Horizontal padding from edges when `autoScale` is enabled. Default: `16`.
+
+## Public Methods
+
+### `render(expression)`
+
+Renders a mathematical expression or equation within the display. It intelligently handles different input types:
+
+-   If `expression` is a string containing semicolons (`;`), it's treated as a sequence of equations and rendered as an `omdStepVisualizer`.
+-   If `expression` is a string containing an equals sign (`=`), it's treated as a single equation and wrapped in an `omdStepVisualizer`.
+-   Otherwise, if `expression` is a string, it's parsed as a single mathematical expression.
+-   If `expression` is already an `omdNode` instance, it's rendered directly.
+
+-   **`expression`** (`string` | `omdNode`): The mathematical expression string or a pre-existing `omdNode` instance.
+-   **Returns**: `omdNode` - The root node of the rendered content (often an `omdStepVisualizer`).
+
+### `update(newNode)`
+
+Replaces the currently displayed node with a new one, applying the current font size and centering if enabled. The new node is initialized before being added to the display.
+
+-   **`newNode`** (`omdNode`): The new node to display.
+
+### `getCurrentNode()`
+
+Returns the node currently being displayed.
+
+-   **Returns**: `omdNode` | `null` - The current root node, or `null` if nothing is displayed.
+
+### `centerNode()`
+
+Manually triggers the centering and scaling logic for the current node. This is particularly useful for `omdEquationSequenceNode` instances to align them by their equals signs, and for ensuring content fits within the container based on `autoScale` and `maxScale` options.
+
+### `fitToContent()`
+
+Adjusts the SVG container's dimensions to tightly fit the rendered content, adding a small padding. This is useful for generating images or when the display needs to precisely match the content size.
+
+### `setFontSize(size)`
+
+Updates the base font size for the currently displayed node and for any future content rendered. This will trigger a re-layout and re-centering.
+
+-   **`size`** (`number`): The new font size in pixels.
+
+### `setFont(fontFamily, fontWeight)`
+
+Applies a specific font family and weight to all text elements within the rendered SVG. This setting is also stored for future content.
+
+-   **`fontFamily`** (`string`): CSS `font-family` string (e.g., `'"Shantell Sans", cursive'`).
+-   **`fontWeight`** (`string`, optional): CSS `font-weight` (e.g., `'400'`, `'bold'`). Default: `'400'`.
+
+### `clear()`
+
+Removes the current expression from the display.
+
+### `destroy()`
+
+Cleans up the component, removing all DOM elements and detaching the resize observer.
+
+## Internal Methods
+
+-   **`_setupSVG()`**: Initializes the main SVG element, sets its viewBox, and attaches a `ResizeObserver` to the container.
+-   **`_handleResize()`**: Callback for the `ResizeObserver` that updates the SVG viewBox and re-centers the content on container resize.
+-   **`_repositionOverlayToolbar()`**: Positions any overlay toolbars associated with the current node (e.g., for interactive step visualizers).

package/docs/api/omdEquationNode.md

@@ -1,161 +1,174 @@
-# omdEquationNode
-
-Represents a mathematical equation, which consists of a left side, a right side, and an equals sign. This class provides extensive functionality for manipulating the equation, such as applying operations to both sides, swapping sides, and simplification.
-
-## Class: `omdEquationNode extends omdNode`
-
-```javascript
-import { omdEquationNode } from './omd/nodes/omdEquationNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdEquationNode(ast)
-```
-
-
-**Parameters:**
-- `ast` {Object} - The math.js Abstract Syntax Tree (AST) for the equation. Typically an `AssignmentNode` with `object` (left side) and `value` (right side) properties, but can also be an `OperatorNode` with two arguments.
-
-### Static Methods
-
-
-#### `fromString(equationString)`
-Creates an `omdEquationNode` instance from a string representation of an equation.
-
-```javascript
-const equation = omdEquationNode.fromString('2x + 4 = 10');
-```
-- **Parameters:**
-  - `equationString` {string} - The string to parse (e.g., "2x+4=10").
-- **Returns:** `omdEquationNode` A new instance of `omdEquationNode`.
-- **Throws:** Error if the string is not a valid equation (must contain exactly one '=' and both sides must be non-empty).
-
-### Properties
-
-Inherits all properties from [`omdNode`](./omdNode.md), plus:
-
-#### `left`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the left side of the equation.
-
-#### `right`
-- **Type:** [`omdNode`](./omdNode.md)
-- **Description:** The node representing the right side of the equation.
-
-#### `equalsSign`
-- **Type:** [`omdOperatorNode`](./omdOperatorNode.md)
-- **Description:** The node for the equals sign.
-
-### Methods
-
-Inherits all methods from [`omdNode`](./omdNode.md), plus:
-
-
-#### `addToBothSides(value)`
-Returns a new equation with a value added to both sides.
-- `value` {number|Object} - The value or math.js AST to add.
-- **Returns:** `omdEquationNode` A new equation node with the operation applied.
-
----
-
-
-#### `subtractFromBothSides(value)`
-Returns a new equation with a value subtracted from both sides.
-- `value` {number|Object} - The value or math.js AST to subtract.
-- **Returns:** `omdEquationNode` A new equation node.
-
----
-
-
-#### `multiplyBothSides(value)`
-Returns a new equation with both sides multiplied by a value.
-- `value` {number|Object} - The value or math.js AST to multiply by.
-- **Returns:** `omdEquationNode` A new equation node.
-
----
-
-
-#### `divideBothSides(value)`
-Returns a new equation with both sides divided by a value.
-- `value` {number|Object} - The value or math.js AST to divide by.
-- **Returns:** `omdEquationNode` A new equation node.
-
----
-
-
-#### `applyFunction(functionName)`
-Applies a function (e.g., `sqrt`, `log`) to both sides of the equation.
-- `functionName` {string} - The name of the function to apply.
-- **Returns:** `omdEquationNode` A new equation with the function applied to both sides.
-
----
-
-
-#### `applyOperation(value, operation, side = 'both')`
-Applies an arithmetic operation to one or both sides of the equation.
-- `value` {number|omdNode} - The value to apply.
-- `operation` {string} - The operation to perform: 'add', 'subtract', 'multiply', or 'divide'.
-- `side` {string} - The side to apply the operation to: 'left', 'right', or 'both'. Defaults to 'both'.
-- **Returns:** `omdEquationNode` A new equation node with the operation applied.
-
----
-
-
-#### `swapSides()`
-Swaps the left and right sides of the equation.
-- **Returns:** `omdEquationNode` A new equation node with the sides swapped.
-
----
-
-
-#### `simplify()`
-Simplifies both sides of the equation using the simplification engine.
-- **Returns:** `Object` An object containing `{ success, newRoot, message }`.
-
----
-
-
-#### `clone()`
-Creates a deep clone of the equation node, preserving its structure and provenance.
-- **Returns:** `omdEquationNode` A new, identical instance of the equation node.
-
----
-
-
-#### `toString()`
-Converts the equation to its string representation.
-- **Returns:** `string` The equation as a string (e.g., "x + 1 = 5").
-
----
-
-
-#### `evaluate(variables)`
-Evaluates both sides of the equation with a given set of variables.
-- `variables` {Object} - A map of variable names to their numeric values (e.g., `{ x: 2 }`).
-- **Returns:** `Object` An object with the evaluated `left` and `right` side values.
-
-### Example
-
-```javascript
-// Create an equation from a string
-const equation = omdEquationNode.fromString('2 * (x + 1) = 10');
-
-// Perform a series of operations
-const step1 = equation.divideBothSides(2);      // Result: x + 1 = 5
-const step2 = step1.subtractFromBothSides(1); // Result: x = 4
-
-// You can chain these operations
-const finalResult = omdEquationNode.fromString('2 * (x + 1) = 10')
-    .divideBothSides(2)
-    .subtractFromBothSides(1);
-
-console.log(finalResult.toString()); // Output: x = 4
-```
-
-### See Also
-
-- [`omdNode`](./omdNode.md) - The base class for all nodes.
-- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Often used for the sides of the equation.
-- [`omdStepVisualizer`](./omdStepVisualizer.md) - For displaying a sequence of equation transformations.
+# omdEquationNode
+
+Represents a mathematical equation, consisting of a left side, a right side, and an equals sign. This class provides extensive functionality for manipulating the equation, such as applying operations to both sides, swapping sides, simplification, and rendering to various visualization formats.
+
+## Class Definition
+
+```javascript
+export class omdEquationNode extends omdNode
+```
+
+## Constructor
+
+### `new omdEquationNode(ast)`
+
+Creates a new `omdEquationNode` instance.
+
+-   **`ast`** (`object`): The math.js Abstract Syntax Tree (AST) for the equation. It typically expects an `AssignmentNode` (with `object` for the left side and `value` for the right side) or an `OperatorNode` (with `op: '='` and two arguments).
+
+## Static Methods
+
+### `fromString(equationString)`
+
+Creates an `omdEquationNode` instance from a string representation of an equation.
+
+-   **`equationString`** (`string`): The string to parse (e.g., `"2x + 4 = 10"`).
+-   **Returns**: `omdEquationNode` - A new instance of `omdEquationNode`.
+-   **Throws**: `Error` if the string is not a valid equation (must contain exactly one `'='` and both sides must be non-empty).
+
+## Public Properties
+
+-   **`left`** ([`omdNode`](./omdNode.md)): The node representing the left side of the equation.
+-   **`right`** ([`omdNode`](./omdNode.md)): The node representing the right side of the equation.
+-   **`equalsSign`** ([`omdOperatorNode`](./omdOperatorNode.md)): The node for the equals sign.
+
+## Public Methods
+
+### `addToBothSides(value)`
+
+Returns a new equation with a value added to both sides.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to add.
+-   **Returns**: `omdEquationNode` - A new equation node with the operation applied.
+
+### `subtractFromBothSides(value)`
+
+Returns a new equation with a value subtracted from both sides.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to subtract.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `multiplyBothSides(value)`
+
+Returns a new equation with both sides multiplied by a value.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to multiply by.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `divideBothSides(value)`
+
+Returns a new equation with both sides divided by a value.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to divide by.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `applyFunction(functionName)`
+
+Applies a function (e.g., `sqrt`, `log`) to both sides of the equation.
+
+-   **`functionName`** (`string`): The name of the function to apply.
+-   **Returns**: `omdEquationNode` - A new equation with the function applied to both sides.
+
+### `applyOperation(value, operation, side = 'both')`
+
+Applies an arithmetic operation to one or both sides of the equation.
+
+-   **`value`** (`number` | `omdNode`): The value to apply.
+-   **`operation`** (`string`): The operation to perform: `'add'`, `'subtract'`, `'multiply'`, or `'divide'`.
+-   **`side`** (`string`): The side to apply the operation to: `'left'`, `'right'`, or `'both'`. Defaults to `'both'`.
+-   **Returns**: `omdEquationNode` - A new equation node with the operation applied.
+
+### `swapSides()`
+
+Swaps the left and right sides of the equation.
+
+-   **Returns**: `omdEquationNode` - A new equation node with the sides swapped.
+
+### `simplify()`
+
+Simplifies both sides of the equation using the simplification engine.
+
+-   **Returns**: `object` - An object containing `{ success, newRoot, message }`.
+
+### `clone()`
+
+Creates a deep clone of the equation node, preserving its structure and provenance.
+
+-   **Returns**: `omdEquationNode` - A new, identical instance of the equation node.
+
+### `toString()`
+
+Converts the equation to its string representation.
+
+-   **Returns**: `string` - The equation as a string (e.g., `"x + 1 = 5"`).
+
+### `evaluate(variables)`
+
+Evaluates both sides of the equation with a given set of variables.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values (e.g., `{ x: 2 }`).
+-   **Returns**: `object` - An object with the evaluated `left` and `right` side values.
+
+### `setBackgroundStyle(style)`
+
+Configures the background styling for the equation node. This can include `backgroundColor`, `cornerRadius`, and `pill` (for a pill-shaped background).
+
+-   **`style`** (`object`): An object containing style properties.
+
+### `getEqualsAnchorX()`
+
+Returns the horizontal X-coordinate of the center of the equals sign relative to this node's origin. Useful for aligning equations in a sequence.
+
+-   **Returns**: `number`.
+
+### `getBackgroundPaddingX()`
+
+Returns the horizontal padding applied by the background style.
+
+-   **Returns**: `number`.
+
+### `getEffectiveBackgroundPaddingX()`
+
+Returns the effective horizontal padding used in layout, accounting for factors like pill clamping.
+
+-   **Returns**: `number`.
+
+### `renderTo(visualizationType, options)`
+
+Renders the equation to different visualization formats (e.g., graph, table, balance hanger, tile equation).
+
+-   **`visualizationType`** (`string`): The type of visualization (`"graph"`, `"table"`, `"hanger"`, `"tileequation"`).
+-   **`options`** (`object`, optional): Configuration options specific to the visualization type.
+-   **Returns**: `object` - A JSON object conforming to the schemas defined in `src/json-schemas.md`.
+
+### `getLeft()`
+
+Returns the `omdNode` representing the left side of the equation.
+
+-   **Returns**: `omdNode`.
+
+### `getRight()`
+
+Returns the `omdNode` representing the right side of the equation.
+
+-   **Returns**: `omdNode`.
+
+## Internal Methods
+
+-   **`_applyOperation(value, op, fn)`**: Internal helper for applying arithmetic operations to both sides.
+-   **`_needsParenthesesForOperation(node, operation)`**: Determines if a child node needs parentheses when an operation is applied, based on operator precedence.
+-   **`_createNodeFromValue(value)`**: Converts a number or math.js AST into an appropriate `omdNode`.
+-   **`_establishGranularProvenance(newNode, originalNode, operationValue, operation)`**: Manages provenance tracking for equation operations, linking new nodes to their origins.
+-   **`_isMultiplicationOperation(node)`**: Checks if a given node represents a multiplication operation.
+-   **`_copyProvenanceStructure(target, source)`**: Recursively copies provenance information from a source node to a target node.
+-   **`_createFunctionNode(functionName, argument)`**: Creates an `omdFunctionNode` wrapping a given argument.
+-   **`_createNewEquation(left, right)`**: Creates a new `omdEquationNode` from two `omdNode` instances.
+-   **`_getEffectivePadding(contentHeight)`**: Computes effective padding for background styling, considering pill radius clamping.
+-   **`_applyPillToDescendants()`**: Applies pill-shaped corner radius to all descendant nodes' backgrounds when the parent equation uses a pill style.
+-   **`_matchChildBackgrounds(color)`**: Hides child node backgrounds by setting their color to match the parent equation's background.
+-   **`_renderToGraph(options)`**: Generates JSON for a coordinate plane graph visualization.
+-   **`_renderToTable(options)`**: Generates JSON for a table visualization.
+-   **`_renderSingleSideTable(side, title, options)`**: Helper for generating tables for a single side of the equation.
+-   **`_renderToHanger()`**: Generates JSON for a balance hanger visualization.
+-   **`_normalizeExpressionString(expr)`**: Normalizes expression strings for evaluation/graphing (e.g., inserts `*` for implicit multiplication).
+-   **`_convertToHangerValues(node)`**: Converts an equation side into values suitable for a balance hanger visualization.