@teachinglab/omd 0.5.6 → 0.5.8

package/npm-docs/api/expression-nodes.md

@@ -0,0 +1,561 @@
+# Expression Nodes
+
+Expression nodes are the building blocks of mathematical expressions and equations in OMD. They form a tree structure that represents the mathematical content.
+
+## Overview
+
+OMD uses a node-based system where every mathematical element is represented as a node in an expression tree. This allows for powerful manipulation, simplification, and visualization of mathematical expressions.
+
+## Core Node Classes
+
+### omdNode
+
+The abstract base class for all nodes in the expression tree.
+
+**See**: [omdNode API Documentation](./omdNode.md)
+
+### omdEquationNode
+
+Represents a complete mathematical equation with left side, right side, and equals sign.
+
+**Class**: `omdEquationNode extends omdNode`
+
+#### Static Methods
+
+**`fromString(equationString)`**
+
+Creates an equation node from a string representation.
+
+```javascript
+import { omdEquationNode } from '@teachinglab/omd';
+
+const equation = omdEquationNode.fromString('2x + 3 = 11');
+```
+
+- **Parameters**: 
+  - `equationString` (string): The equation string (e.g., `"2x + 4 = 10"`)
+- **Returns**: `omdEquationNode`
+- **Throws**: Error if string is not a valid equation
+
+#### Properties
+
+- **`left`** (omdNode): The left side of the equation
+- **`right`** (omdNode): The right side of the equation
+- **`equalsSign`** (omdOperatorNode): The equals sign operator
+
+#### Manipulation Methods
+
+**`addToBothSides(value)`**
+
+Returns a new equation with a value added to both sides.
+
+```javascript
+const newEq = equation.addToBothSides(5);
+```
+
+- **Parameters**: 
+  - `value` (number | object): Value to add
+- **Returns**: `omdEquationNode`
+
+**`subtractFromBothSides(value)`**
+
+Returns a new equation with a value subtracted from both sides.
+
+```javascript
+const newEq = equation.subtractFromBothSides(3);
+```
+
+- **Parameters**: 
+  - `value` (number | object): Value to subtract
+- **Returns**: `omdEquationNode`
+
+**`multiplyBothSides(value)`**
+
+Returns a new equation with both sides multiplied by a value.
+
+```javascript
+const newEq = equation.multiplyBothSides(2);
+```
+
+- **Parameters**: 
+  - `value` (number | object): Value to multiply by
+- **Returns**: `omdEquationNode`
+
+**`divideBothSides(value)`**
+
+Returns a new equation with both sides divided by a value.
+
+```javascript
+const newEq = equation.divideBothSides(2);
+```
+
+- **Parameters**: 
+  - `value` (number | object): Value to divide by
+- **Returns**: `omdEquationNode`
+
+**`applyFunction(functionName)`**
+
+Applies a function (e.g., sqrt, log) to both sides.
+
+```javascript
+const newEq = equation.applyFunction('sqrt');
+```
+
+- **Parameters**: 
+  - `functionName` (string): Name of function to apply
+- **Returns**: `omdEquationNode`
+
+**`applyOperation(value, operation, side = 'both')`**
+
+Applies an arithmetic operation to one or both sides.
+
+```javascript
+const newEq = equation.applyOperation(5, 'add', 'left');
+```
+
+- **Parameters**: 
+  - `value` (number | omdNode): Value to apply
+  - `operation` (string): Operation type: `'add'`, `'subtract'`, `'multiply'`, or `'divide'`
+  - `side` (string): Side to apply to: `'left'`, `'right'`, or `'both'` (default: `'both'`)
+- **Returns**: `omdEquationNode`
+
+**`swapSides()`**
+
+Swaps the left and right sides of the equation.
+
+```javascript
+const swapped = equation.swapSides();
+```
+
+- **Returns**: `omdEquationNode`
+
+**`simplify()`**
+
+Simplifies both sides using the simplification engine.
+
+```javascript
+const result = equation.simplify();
+// Returns: { success: boolean, newRoot: omdEquationNode, message: string }
+```
+
+- **Returns**: Object with `success`, `newRoot`, and `message` properties
+
+#### Utility Methods
+
+**`clone()`**
+
+Creates a deep clone of the equation node.
+
+```javascript
+const copy = equation.clone();
+```
+
+- **Returns**: `omdEquationNode`
+
+**`toString()`**
+
+Converts the equation to its string representation.
+
+```javascript
+const str = equation.toString();
+// Returns: "2x + 3 = 11"
+```
+
+- **Returns**: `string`
+
+**`evaluate(variables)`**
+
+Evaluates both sides with given variable values.
+
+```javascript
+const result = equation.evaluate({ x: 4 });
+// Returns: { left: 11, right: 11 }
+```
+
+- **Parameters**: 
+  - `variables` (object): Map of variable names to values
+- **Returns**: Object with `left` and `right` evaluated values
+
+**`getLeft()`**
+
+Returns the node representing the left side.
+
+```javascript
+const leftSide = equation.getLeft();
+```
+
+- **Returns**: `omdNode`
+
+**`getRight()`**
+
+Returns the node representing the right side.
+
+```javascript
+const rightSide = equation.getRight();
+```
+
+- **Returns**: `omdNode`
+
+#### Styling Methods
+
+**`setBackgroundStyle(style)`**
+
+Configures background styling for the equation node.
+
+```javascript
+equation.setBackgroundStyle({
+    backgroundColor: '#E3F2FD',
+    cornerRadius: 8,
+    pill: true
+});
+```
+
+- **Parameters**: 
+  - `style` (object): Style properties (`backgroundColor`, `cornerRadius`, `pill`)
+
+**`getEqualsAnchorX()`**
+
+Returns the X-coordinate of the equals sign center (for alignment).
+
+```javascript
+const anchorX = equation.getEqualsAnchorX();
+```
+
+- **Returns**: `number`
+
+**`getBackgroundPaddingX()`**
+
+Returns the horizontal padding applied by background style.
+
+```javascript
+const padding = equation.getBackgroundPaddingX();
+```
+
+- **Returns**: `number`
+
+#### Visualization Methods
+
+**`renderTo(visualizationType, options)`**
+
+Renders the equation to different visualization formats.
+
+```javascript
+// Render to coordinate plane
+const graphJSON = equation.renderTo('graph', {
+    xMin: -10,
+    xMax: 10,
+    yMin: -10,
+    yMax: 10
+});
+
+// Render to table
+const tableJSON = equation.renderTo('table', {
+    xMin: -5,
+    xMax: 5,
+    stepSize: 1
+});
+
+// Render to balance hanger
+const hangerJSON = equation.renderTo('hanger');
+
+// Render to tile equation
+const tileJSON = equation.renderTo('tileequation');
+```
+
+- **Parameters**: 
+  - `visualizationType` (string): Type of visualization: `'graph'`, `'table'`, `'hanger'`, or `'tileequation'`
+  - `options` (object): Configuration options specific to visualization type
+- **Returns**: JSON object for the visualization
+
+**See**: [omdEquationNode Full API Documentation](./omdEquationNode.md)
+
+---
+
+### Expression Component Nodes
+
+#### omdConstantNode
+
+Represents numeric constants.
+
+```javascript
+import { omdConstantNode } from '@teachinglab/omd';
+
+const constant = new omdConstantNode(ast);
+```
+
+**See**: [omdConstantNode API Documentation](./omdConstantNode.md)
+
+---
+
+#### omdVariableNode
+
+Represents algebraic variables.
+
+```javascript
+import { omdVariableNode } from '@teachinglab/omd';
+
+const variable = new omdVariableNode(ast);
+```
+
+**See**: [omdVariableNode API Documentation](./omdVariableNode.md)
+
+---
+
+#### omdOperatorNode
+
+Represents mathematical operators (+, -, ×, ÷, =).
+
+```javascript
+import { omdOperatorNode } from '@teachinglab/omd';
+
+const operator = new omdOperatorNode(ast);
+```
+
+**See**: [omdOperatorNode API Documentation](./omdOperatorNode.md)
+
+---
+
+#### omdBinaryExpressionNode
+
+Represents binary operations (addition, subtraction, multiplication, division).
+
+```javascript
+import { omdBinaryExpressionNode } from '@teachinglab/omd';
+
+const binaryExpr = new omdBinaryExpressionNode(ast);
+```
+
+**See**: [omdBinaryExpressionNode API Documentation](./omdBinaryExpressionNode.md)
+
+---
+
+#### omdUnaryExpressionNode
+
+Represents unary operations (negation).
+
+```javascript
+import { omdUnaryExpressionNode } from '@teachinglab/omd';
+
+const unaryExpr = new omdUnaryExpressionNode(ast);
+```
+
+**See**: [omdUnaryExpressionNode API Documentation](./omdUnaryExpressionNode.md)
+
+---
+
+#### omdPowerNode
+
+Represents exponentiation (x²).
+
+```javascript
+import { omdPowerNode } from '@teachinglab/omd';
+
+const power = new omdPowerNode(ast);
+```
+
+**See**: [omdPowerNode API Documentation](./omdPowerNode.md)
+
+---
+
+#### omdRationalNode
+
+Represents fractions and rational numbers.
+
+```javascript
+import { omdRationalNode } from '@teachinglab/omd';
+
+const rational = new omdRationalNode(ast);
+```
+
+**See**: [omdRationalNode API Documentation](./omdRationalNode.md)
+
+---
+
+#### omdSqrtNode
+
+Represents square root expressions.
+
+```javascript
+import { omdSqrtNode } from '@teachinglab/omd';
+
+const sqrt = new omdSqrtNode(ast);
+```
+
+**See**: [omdSqrtNode API Documentation](./omdSqrtNode.md)
+
+---
+
+#### omdFunctionNode
+
+Represents mathematical functions (sin, cos, log, etc.).
+
+```javascript
+import { omdFunctionNode } from '@teachinglab/omd';
+
+const func = new omdFunctionNode(ast);
+```
+
+**See**: [omdFunctionNode API Documentation](./omdFunctionNode.md)
+
+---
+
+#### omdParenthesisNode
+
+Represents expressions enclosed in parentheses.
+
+```javascript
+import { omdParenthesisNode } from '@teachinglab/omd';
+
+const paren = new omdParenthesisNode(ast);
+```
+
+**See**: [omdParenthesisNode API Documentation](./omdParenthesisNode.md)
+
+---
+
+### Container Nodes
+
+#### omdGroupNode
+
+A container for grouping related nodes.
+
+```javascript
+import { omdGroupNode } from '@teachinglab/omd';
+
+const group = new omdGroupNode(ast);
+```
+
+**See**: [omdGroupNode API Documentation](./omdGroupNode.md)
+
+---
+
+#### omdEquationSequenceNode
+
+A container for displaying step-by-step equation solutions.
+
+```javascript
+import { omdEquationSequenceNode } from '@teachinglab/omd';
+
+const sequence = new omdEquationSequenceNode();
+sequence.addChild(equation1);
+sequence.addChild(equation2);
+```
+
+**See**: [omdEquationSequenceNode API Documentation](./omdEquationSequenceNode.md)
+
+---
+
+## Node Tree Structure
+
+Nodes are organized in a tree structure:
+
+```
+omdEquationNode
+├── left (omdNode)
+│   └── omdBinaryExpressionNode
+│       ├── left (omdConstantNode: 2)
+│       ├── operator (omdOperatorNode: +)
+│       └── right (omdConstantNode: 3)
+├── equalsSign (omdOperatorNode: =)
+└── right (omdNode)
+    └── omdConstantNode: 11
+```
+
+## Working with Expression Trees
+
+### Creating Nodes from Strings
+
+The simplest way to create nodes is from strings:
+
+```javascript
+import { omdEquationNode } from '@teachinglab/omd';
+
+const equation = omdEquationNode.fromString('2x + 3 = 11');
+```
+
+### Manipulating Nodes
+
+Nodes can be manipulated to perform mathematical operations:
+
+```javascript
+// Start with: 2x + 3 = 11
+const step1 = equation.subtractFromBothSides(3);
+// Result: 2x = 8
+
+const step2 = step1.divideBothSides(2);
+// Result: x = 4
+```
+
+### Traversing the Tree
+
+Nodes can be traversed to analyze structure:
+
+```javascript
+const leftSide = equation.getLeft();
+const rightSide = equation.getRight();
+
+console.log(equation.toString()); // "2x + 3 = 11"
+```
+
+### Evaluating Expressions
+
+Nodes can be evaluated with variable values:
+
+```javascript
+const result = equation.evaluate({ x: 4 });
+console.log(result); // { left: 11, right: 11 }
+```
+
+## Common Patterns
+
+### Creating a Step-by-Step Solution
+
+```javascript
+import { omdEquationNode, omdEquationStack } from '@teachinglab/omd';
+
+const original = omdEquationNode.fromString('2x + 3 = 11');
+const step1 = original.subtractFromBothSides(3);
+const step2 = step1.divideBothSides(2);
+
+const steps = [original, step1, step2];
+const stack = new omdEquationStack(steps);
+```
+
+### Simplifying Expressions
+
+```javascript
+const equation = omdEquationNode.fromString('2x + 3x = 10');
+const result = equation.simplify();
+
+if (result.success) {
+    console.log(result.newRoot.toString()); // "5x = 10"
+}
+```
+
+### Rendering to Visualizations
+
+```javascript
+const equation = omdEquationNode.fromString('y = x^2 - 4');
+
+// Render to graph
+const graphData = equation.renderTo('graph', {
+    xMin: -10,
+    xMax: 10,
+    yMin: -10,
+    yMax: 10
+});
+
+// Render to table
+const tableData = equation.renderTo('table', {
+    xMin: -5,
+    xMax: 5,
+    stepSize: 1
+});
+```
+
+## See Also
+
+- [omdNode Base Class](./omdNode.md)
+- [omdEquationNode Full Documentation](./omdEquationNode.md)
+- [Equations Guide](../guides/equations.md)
+- [JSON Schemas](../json-schemas.md)

package/npm-docs/api/focusFrameManager.md

@@ -0,0 +1,145 @@
+# FocusFrameManager
+
+The `FocusFrameManager` is a feature that allows you to define rectangular regions on the canvas called "focus frames." These frames can be used to highlight specific areas of interest, capture their contents as separate SVG or bitmap images, and manage them independently.
+
+This is particularly useful for applications where you need to isolate and process or export specific parts of a larger drawing, such as individual mathematical problems on a worksheet or specific diagrams in a complex scene.
+
+## Class Definition
+
+```javascript
+export class FocusFrameManager {
+    // ...
+}
+```
+
+## Constructor
+
+### `new FocusFrameManager(canvas)`
+
+Creates a new `FocusFrameManager` instance.
+
+-   **`canvas`** (`OMDCanvas`): The main canvas instance.
+
+## Public Methods
+
+### `createFrame([options])`
+
+Creates a new, independent focus frame on the canvas.
+
+-   **`options`** (`object`, optional): Configuration for the new frame.
+    -   `x` (`number`, optional): The x-coordinate of the top-left corner. Default: `0`.
+    -   `y` (`number`, optional): The y-coordinate of the top-left corner. Default: `0`.
+    -   `width` (`number`, optional): The width of the frame. Default: `200`.
+    -   `height` (`number`, optional): The height of the frame. Default: `150`.
+    -   `showOutline` (`boolean`, optional): Whether to display the frame's border. Default: `true`.
+    -   `outlineColor` (`string`, optional): The color of the border. Default: `'#007bff'`.
+    -   `outlineWidth` (`number`, optional): The thickness of the border. Default: `2`.
+    -   `outlineDashed` (`boolean`, optional): Whether the border should be a dashed line. Default: `false`.
+-   **Returns**: `object` - An object containing the `id` of the new frame and a reference to the `frame` instance (`{ id, frame }`).
+-   **Emits**: `focusFrameCreated` with `{ id, frame }`.
+
+### `removeFrame(frameId)`
+
+Removes a specific focus frame from the canvas.
+
+-   **`frameId`** (`string`): The unique ID of the frame to remove.
+-   **Returns**: `boolean` - `true` if the frame was found and removed, `false` otherwise.
+-   **Emits**: `focusFrameRemoved` with `{ frameId }`.
+
+### `getFrame(frameId)`
+
+Retrieves a focus frame instance by its ID.
+
+-   **`frameId`** (`string`): The ID of the frame to retrieve.
+-   **Returns**: `FocusFrame` or `undefined` - The frame instance, or `undefined` if no frame with that ID exists.
+
+### `setActiveFrame(frameId)`
+
+Sets a specific frame as the "active" one, which can be useful for highlighting or targeting operations.
+
+-   **`frameId`** (`string`): The ID of the frame to activate.
+-   **Returns**: `boolean` - `true` if the frame was successfully activated.
+-   **Emits**: `focusFrameActivated` with `{ frameId, frame }`.
+
+### `getActiveFrame()`
+
+Gets the currently active focus frame.
+
+-   **Returns**: `FocusFrame` or `null` - The active frame instance, or `null` if no frame is currently active.
+
+### `captureActiveFrame()`
+
+Captures the SVG content of the currently active focus frame.
+
+-   **Returns**: `string` or `null` - A string of the SVG content within the active frame's bounds, or `null` if there is no active frame.
+
+### `captureAllFrames()`
+
+Captures the content of every focus frame on the canvas.
+
+-   **Returns**: `Map<string, string>` - A Map where keys are frame IDs and values are the SVG content strings for each frame.
+
+### `clearAllFrames()`
+
+Removes all focus frames from the canvas.
+
+-   **Emits**: `focusFramesCleared`.
+
+### `getFrameIds()`
+
+Gets the IDs of all current focus frames.
+
+-   **Returns**: `Array<string>` - An array of all frame IDs.
+
+### `destroy()`
+
+Destroys the manager and removes all associated frames and event listeners.
+
+---
+
+## The `FocusFrame` Class (Internal)
+
+The `FocusFrame` class represents a single rectangular frame. It is not exported directly but is returned by `FocusFrameManager` methods.
+
+### `setActive(active)`
+
+Sets the frame's visual state to active or inactive.
+
+-   **`active`** (`boolean`): `true` to activate, `false` to deactivate.
+
+### `capture()`
+
+Captures the canvas content within the frame's bounds.
+
+-   **Returns**: `string` - The SVG content of the frame as an XML string.
+
+### `async toBitmap([format], [quality])`
+
+Converts the frame's captured content into a bitmap image.
+
+-   **`format`** (`string`, optional): The image format (e.g., `'png'`, `'jpeg'`). Default: `'png'`.
+-   **`quality`** (`number`, optional): The image quality for formats that support it (0 to 1). Default: `1`.
+-   **Returns**: `Promise<Blob>` - A promise that resolves with the image data as a `Blob`.
+
+### `async downloadAsBitmap([filename], [format])`
+
+Triggers a browser download of the frame's content as a bitmap image.
+
+-   **`filename`** (`string`, optional): The desired filename. Default: `focus-frame-{id}.png`.
+-   **`format`** (`string`, optional): The image format. Default: `'png'`.
+
+### `updateBounds(bounds)`
+
+Resizes and/or repositions the frame.
+
+-   **`bounds`** (`object`): An object with the new dimensions and coordinates (`{ x, y, width, height }`).
+
+### `getBounds()`
+
+Gets the current position and size of the frame.
+
+-   **Returns**: `object` - An object containing the frame's bounds (`{ x, y, width, height }`).
+
+### `destroy()`
+
+Removes the frame's visual element from the canvas.